Skip to content
NOEMATA

Alerts & workflows

A workflow is a named configuration of executable work over your data. It declares a schedule and either inline execute logic or a use reference to a parameterized workflow template. Each workflow has its own enabled configuration, execution history, and carried state. A run is one execution. A template has no schedule or enabled state and never runs by itself.

A workflow executes a checkpointed step pipeline or a declarative detection. Detections evaluate thresholds, appearances, disappearances, series changes, error-budget burn rates, or extraction queries; see Detections. A detection is defined, scheduled, and run as a workflow.

Workflows live in the file store beside your frames, as named entries in a *.workflows.json file (or under a frame’s workflows key):

{
  "workflows": {
    "service_error_rate": {
      "title": "Service error rate over 5%",
      "schedule": { "every": "1m", "delay": "30s" },
      "execute": {
        "steps": [
          {
            "@expr/query": {
              "from": "services",
              "select": { "as": { "ServiceName": "ServiceName", "value": "ErrorRate" } }
            }
          },
          { "@expr/filter": { "where": "value > 0.05" } },
          { "@expr/emit": { "log": { "event_name": "acme.error_rate.breach" } } }
        ]
      }
    }
  }
}

Three facts hold throughout this section:

  • The execution’s source file selects its frame view. Inline execution uses the workflow file; workflow-level use uses the template file. A matching filename takes precedence (foo.workflows.json or foo.templates.json uses foo.frame.json; index.workflows.json uses index.frame.json). Without a match, lookup follows the containing folder’s route to its nearest frame. The pipeline above evaluates services from the co-located frame’s view, with ErrorRate as the view defines it; the view’s timestamp scopes the query to each run’s evaluation window. Workflows use the same vocabulary as dashboards.
  • The runtime carries state between runs. @expr/workflow_state reads values published by the previous occurrence and stages values for the next one. The runtime records state in run checkpoints.
  • Workflows produce telemetry. @expr/emit creates custom OpenTelemetry log records and metric points. Detections emit records for findings such as alerts, changes, recommendations, and extractions. Runtime telemetry describes workflow runs and scheduler activity. See record conventions for field details.

Reuse a workflow template

Declare reusable logic under templates.workflows in a *.templates.json file. A partial declares its parameter schema and an execution body; a reference contains a fixed execution body. This example uses an existing view’s traces table and EntryErrorRate scalar:

{
  "templates": {
    "workflows": {
      "service_errors": {
        "partial": {
          "parameters": {
            "type": "object",
            "properties": {
              "service_name": {
                "type": "string"
              },
              "threshold": {
                "type": "number",
                "minimum": 0,
                "maximum": 1,
                "default": 0.05
              }
            },
            "required": ["service_name"],
            "additionalProperties": false
          },
          "template": {
            "execute": {
              "threshold": {
                "from": "traces",
                "where": "ServiceName = {service_name:String}",
                "group_by": "ServiceName",
                "value": "EntryErrorRate",
                "alert": {
                  "levels": {
                    "warning": {
                      "above": {
                        "@expr/get_context": "threshold"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

Save this as workflows.templates.json and create independent workflows with different arguments and schedules:

{
  "workflows": {
    "checkout_errors": {
      "title": "Checkout errors",
      "enabled": true,
      "schedule": { "every": "1m", "window": "5m", "delay": "30s" },
      "use": {
        "ref": "./workflows.templates.json#/workflow/service_errors",
        "params": { "service_name": "checkout", "threshold": 0.05 }
      }
    },
    "staging_errors": {
      "title": "Staging errors",
      "enabled": true,
      "schedule": { "every": "15m" },
      "use": {
        "ref": "./workflows.templates.json#/workflow/service_errors",
        "params": { "service_name": "staging", "threshold": 0.2 }
      }
    }
  }
}
  • Set exactly one of execute and use. Templates cannot own schedules, enablement, or run history.
  • Parameter defaults come from direct parameters.properties entries. Supplied values override defaults; the resulting object must satisfy the parameter schema before scheduling.
  • Detector runtime settings read parameters with @expr/get_context. Supported settings are evaluation and alert limits; threshold comparator operands; change interval, window, fill, kinds, magnitude, segment size, and seasonality; appearance and disappearance horizons; burn-rate objective and window; and alert persistence, no-data behavior, and ordering. For example, a burn-rate template can declare "objective": { "@expr/get_context": "objective" } and "window": { "@expr/get_context": "slo_window" }.
  • SQL placeholders bind values inside query fragments without text interpolation. Query expressions and per-row emit values keep their existing evaluation stages; template parameters do not replace arbitrary authored syntax.
  • The template’s location supplies the borrowed frame view. The configured workflow’s location and name supply its execution identity. Calling the same template twice creates independent state and scheduling cursors.
  • Inline execution and workflow-level use load referenced block/expression templates transitively before execution. Definitions and borrowed views are resolved for each new occurrence; failed or crashed occurrences are not resumed.
  • A monitored-subject or grouping change requires a new workflow state version; threshold adjustments can preserve state.

What runs by default

Deployment scheduling requires workflows.enabled: true in noemata.json (default false). Setup offers to enable scheduling, and noemata up --edit turns scheduling off for that run. Enabling the deployment switch runs the installed packs’ enabled rules. workflows.selection decides whether the published workflows, your local ones, or both run; see What the scheduler reads.

Integration packs configure 250 enabled workflows and 17 disabled opt-ins, including faults, changes, recommendations, reports, and on-demand rules. These per-rule defaults apply only when deployment scheduling is enabled. Existing explicit user overrides are preserved. The pack README lists each rule’s default, record kind, and source requirements.

Customize individual rules in detectors.workflows.local.json. Rules marked off · site also require a deployment-specific SLO, budget, or latency target:

{
  "workflows": {
    "entry_latency": { "enabled": true },
    "client_ip_concentration": { "enabled": false }
  }
}

Keep user-owned configuration in .local.json or .overrides.json files; reconcile updates managed pack files and preserves these overlays.

Briefs and reports

Pack reports.workflows.json files configure alert briefs, daily change and open-alert digests, weekly recommendation, rightsizing, storage, and coding-agent usage reports. Reports run when deployment scheduling is enabled, except the explicitly disabled escalation reminder. Customize them through reports.workflows.local.json. Enabling an on-demand workflow does not add a schedule; configure a schedule separately to run it periodically.

Reports emit noemata.report and briefs emit noemata.brief, both available in @opentelemetry/views/extractions. ReportKind identifies the report; BriefFor links a brief to its alert event ID. These workflows record message bodies but do not deliver notifications. Open-state reports use the latest transitions retained within 30 days; they cannot reconstruct instances with no retained transition. Each pack README documents source and coverage limits.

In this section

  • Schedules & windows — cadences, evaluation windows, delay, the per-workflow phase, time zones, and what happens after downtime.
  • Operating workflows — what the scheduler reads, run history, versioning state, failure semantics, and schema upgrades.

For the field-by-field shape — the step pipeline, workflow state, and emitting events — see the frame schema reference.