Alarms

The Alarms system in Cruncher provides automatic notifications and status tracking for running Studies and Schedules. When enabled, Cruncher writes JSON alarm files to a designated folder, allowing other applications or monitoring systems to detect study progress, warnings, or errors in near real time.

Purpose

Alarms provide a lightweight way to monitor Cruncher activity without using the user interface. Each alarm file records the current state of a Study or Schedule and is updated as processing progresses. They can be consumed by external systems for status dashboards, workflow triggers, or automated reporting.

Configuration

• Enable Alarms — Global toggle that activates or deactivates the alarm system.
• Alarms Folder — Directory where JSON alarm files are written. Each active Study or Schedule writes a separate file.
• Heartbeat Interval — Defines how often Cruncher updates a small “heartbeat” file in the alarms folder. This allows external programs to detect if Cruncher has stopped or crashed unexpectedly.

Alarm Files

Each alarm file is a JSON document describing the current execution state. The file name is derived from a hash of its contents ensuring uniqueness. The contents are a dictionary structure with the following values.

• TIMESTAMP — Records when the Alarming event was triggered
• ALARM_TYPE — Denotes the specific type of Alarm
• MACHINE — Gives the machine name the Alarming event occurred on
• SOURCE — Gives the Study or Schedule name related to the Alarming event
• MESSAGE — Contains any associated log message (if applicable)

Example Alarm File Structure

			{
			"TIMESTAMP": 1725898168.2709,
			"ALARM_TYPE": "STUDY_WARNING",
			"MACHINE": "my_workstation",
			"SOURCE": "Future Hour Ahead 0043",
			"MESSAGE": "load_forecast may contain stale data",
			}
		

Alarm Types

Alarm Types can be enabled/disabled for individual Schedules/Studies based on a few general categories.

• Start
  • SCHEDULE_STARTED — Notification sent on a successful kick-off of a Scheduled run.
  • SCHEDULE_FAILED_TO_START — An error occurred preventing a Scheduled run from starting.
• Warning
  • VALIDATION_WARNING — Validation Warning from automatic quick validation of a Schedule in advance of a run.
  • STUDY_WARNING — Warning thrown during the execution of a Study.
• Error
  • VALIDATION_ERROR — Validation Error from automatic quick validation of a Schedule in advance of a run.
  • STUDY_CRUNCHER_ERROR/STUDY_SIMULATOR_ERROR — Error thrown during the execution of a Study; different types indicate if the error originated from a Cruncher process, or was passed back from Simulator during its processing.
• Completion
  • STUDY_SNAPSHOTS_COMPLETE — Indication that Snapshot processing has completed.
  • STUDY_COMPLETE — Indication that all processing has completed for a Study run (which may or may not have included Analysis).
• SIMAUTO_ERROR — SimAuto is critical to all of the processing Cruncher performs; errors related to SimAuto connections are critical to deal with quickly. If Alarms are enabled for a Schedule/Study, SimAuto errors are automatically reported.

Heartbeat File

In addition to the individual alarm files, Cruncher can maintain a small “heartbeat” file named .heartbeat in the same directory. This file has not contents, but its Modification timestamp is updated at the interval specified by the Heartbeat setting confirming that Cruncher is still active. External monitors can use this file to detect unexpected shutdowns or stalled processes.

Integration

Alarm and heartbeat files are designed to be easily parsed by other systems. They can be used to trigger automation scripts, send email alerts, update dashboards, or integrate with enterprise scheduling systems. Because they use standard JSON, they can be read by Python, PowerShell, or any language with a JSON parser.