Alert (alert)

Category: modifiers | Form: | Symbol: Al

Trigger notifications when conditions are met

Triggers notifications when metric conditions are met on attached elements. Cascade strategy: pervasive — alert configs cannot be removed by child elements once inherited. Phase: response (evaluates after execution completes). Evaluation order 400 (runs last). Applies to all element types. Fail action: log (alert failures are logged, not rejected). Alert instances persist in DB with states: firing, acknowledged, silenced, resolved. Five operations: firing (list active alerts), history (past alerts, limit max 200), acknowledge (requires alert_id UUID, emits alert.acknowledged event), resolve (requires alert_id, optional resolution text, emits alert.resolved event), silence (requires alert_id and duration like “1h”/“24h”/“7d”, emits alert.silenced event). Severity levels: info, warning, error, critical, yellow, orange. Use yellow for near-threshold pacing alerts (e.g. 105%), orange for breach alerts (e.g. 115%), critical for immediate escalation. Use alert for operational monitoring; use audit for compliance logging.

Guide

Overview

An Alert resource defines monitoring rules for Actions, Flows, or system metrics. When a condition (like high error rate) is met, it notifies theconfigured channels.

Why Alerts Exist

• Proactive Monitoring: Detect issues before customers complain.
• SLA Enforcement: Ensure services meet performance targets.
• Ops Integration: Send notifications to Slack, PagerDuty, or Email.

Directory Structure

high-error-rate/
├── README.md              # Documentation
├── .triform/              # Metadata
│   ├── triform.yaml       # kind: observers/alert
│   ├── contract.yaml      # Capabilities
│   ├── spec.yaml          # Condition config
│   └── schema.json        # Validation
└── examples/              # Usage examples

Creating an Alert

$ triform create observers/alert high-error-rate

Configuration

Target

What to monitor.

target:
  kind: function
  ref: "@project/payment-process"

Condition

When to trigger.

condition:
  metric: error_rate
  operator: ">"
  threshold: 0.05  # 5%
  window_minutes: 5

Notifications

Who to tell.

notifications:
  - channel: slack
    config: { channel: "#ops-alerts" }
  - channel: pagerduty
    config: { severity: critical }

Schedule

Deduplication and quiet hours.

schedule:
  repeat_interval_minutes: 60
  quiet_hours:
    start: "22:00"
    end: "08:00"

Runtime Behavior

Property	Value
Cascade	pervasive — alert rules from all scopes apply; cannot be removed by child elements
Eval Order	400
Phase	response
Fail Action	log and notify (no HTTP error — responses pass through; alerts fire asynchronously)
Applies To	all (actors, frontend, data, external)

Alert runs last in the response phase (order 400), after the response is fully formed. It never blocks or modifies the response — it observes execution outcomes and fires notifications asynchronously via the configured channels (Slack, PagerDuty, email).

Files in This Resource

• README.md - Documentation
• .triform/triform.yaml - Metadata
• .triform/contract.yaml - Capabilities
• .triform/spec.yaml - Configuration

Relationships

• Attaches to: circle

Capabilities

• conditions: Threshold conditions
• channels: Multi-channel notifications
• cooldown: Alert cooldown
• escalation: Severity escalation

Properties

Property	Type	Default	Description
severity	string	"warning"	Alert severity level
message	string	—	Human-readable alert message displayed when the alert fires
condition	string	—	Alert trigger condition — use either metric-based (operator+threshold) or CEL expression
notifications	array	[]	Notification channels
silencing	object	—	Alert silencing
runbook_url	string	—	Link to runbook for this alert
auto_resolve	boolean	true	Automatically resolve when condition clears

Operations

acknowledge

Post /ops/acknowledge/{alert_id} | Auth: Write

Acknowledge a firing alert

Marks a firing alert as acknowledged. Requires alert_id (UUID) in input. Optional note field for context. Emits alert.acknowledged event via EventBus. Returns 404 if alert instance not found or already resolved. The acknowledging actor is recorded from the auth context.

attach

Post /ops/attach | Auth: Read

Attach this modifier to a target element

Attaches this modifier to a target element. The target_id must be a UUID of an existing element that supports this modifier type (check applies_to in definition.yaml). Priority controls evaluation order when multiple modifiers of the same type are attached — lower priority runs first. The attachment is stored in element_modifiers table. Cascade resolution runs at bond-time to merge this modifier into the target’s resolved config. Common mistake: attaching to an incompatible element type — check topology rules first.

delete

Delete /ops/delete | Auth: Admin

Delete element (soft delete)

Soft delete — sets state to ‘deleted’ but retains the record. Cannot delete elements that have children (has_no_bond precondition) or active runs. Requires admin auth and confirmation.

detach

Post /ops/detach | Auth: Read

Detach this modifier from a target element

Removes this modifier from a target element. Requires the target_id. Pervasive modifiers (audit, policy) can only be detached at the level they were originally attached — inherited pervasive modifiers cannot be detached by child elements. After detach, cascade resolution re-runs to remove this modifier’s effect from the resolved config.

disable

Post /ops/disable | Auth: Admin

Disable element (hides and prevents use)

Idempotent — safe to call on already-disabled elements. Optionally pass a reason string. Disabled elements cannot be invoked or executed. Inverse of enable.

enable

Post /ops/enable | Auth: Admin

Enable element (makes usable and visible)

Idempotent — safe to call on already-enabled elements. Transitions element to ready/enabled state. Cannot enable deleted elements. Inverse of disable.

evaluate

Post /ops/evaluate | Auth: Read

Evaluate modifier against current context

Evaluates this modifier against a context and optional target_id. Returns applies (bool), result (modifier-specific), and message. For modifiers without custom evaluation logic, returns a default pass result. Auth-policy returns allowed/denied. This is the explicit evaluation endpoint — during normal request flow, modifiers are evaluated automatically by the cascade resolver as middleware.

firing

Get /ops/firing | Auth: Read

List currently firing alerts

Returns active alert instances for this alert element, filtered from the circle’s alert instances table. Each entry has id, state, severity, current/threshold values, message, fired_at, and notification_count. Returns status “ok” when no alerts are firing.

get

Get /ops/get | Auth: Read

Get element details

Element is already resolved by the routing layer — this returns the cached element, not a fresh DB query. Use the path /api/{circle}/{slug} to address elements.

get_attached_modifiers

Get /ops/attached/{target_id} | Auth: Read

Get all modifiers attached to a target element

Lists all modifiers attached to a specific target element, including modifier_id, type, subcategory, and priority. Useful for debugging cascade resolution or understanding which policies apply to an element before invoking it.

history

Get /ops/history | Auth: Read

Get alert firing history

Returns past alert instances with full lifecycle data: fired_at, resolved_at, duration_seconds, severity, resolution, acknowledgment info. Default limit 50, max 200. Use ?limit=N and ?since=X for filtering. Use to analyze alert frequency and resolution times.

intention

Get /ops/intention | Auth: Read

Get element intention with full inheritance chain

Returns three levels: direct (this element’s intention), inherited (from category and root), and resolved (final merged intention). Useful for understanding an element’s purpose in context of its hierarchy.

list_attachments

Get /ops/targets | Auth: Read

List all elements this modifier is attached to

Returns all target elements where this modifier is currently applied. Shows target_id, target_type, priority, and cascade_policy.

readme_update

Post /ops/readme_update | Auth: Write

Update element README.md content

Creates or overwrites README.md in the element’s git repo. Commits to the draft branch. Content must be provided as a markdown string.

resolve

Post /ops/resolve/{alert_id} | Auth: Write

Resolve a firing alert

Manually resolves a firing alert. Requires alert_id (UUID). Optional resolution text (defaults to “manually resolved”). Calculates duration_seconds from fired_at to now. Emits alert.resolved event. Returns 404 if not found or already resolved. Use when the underlying issue has been fixed.

schema

Get /ops/schema | Auth: Read

Get element input/output schema (MCP tools/list compatible)

Returns type-level port schemas from the TypeRegistry — not instance-specific overrides. Includes direction (input/output), required flag, and JSON schema per port. Useful for understanding what data an element accepts and produces.

silence

Post /ops/silence | Auth: Admin

Silence this alert config for a duration

Silences an alert instance for a duration. Requires alert_id and duration (format: “30m”, “1h”, “24h”, “7d” — number + m/h/d unit). Optional reason. Emits alert.silenced event. Returns 404 if alert not found. Requires admin auth. Invalid duration format returns InvalidInput error. Use during maintenance windows to suppress expected alerts.

trigger

Post /ops/trigger | Auth: Execute

Manually trigger this alert

Forces this alert to fire immediately, bypassing the normal condition evaluation. Useful for testing notification channels, runbook links, and escalation paths. Creates an alert instance with the configured severity and message. Optional override fields: severity, message, labels. Emits alert.fired event via EventBus.

update

Patch /ops/update | Auth: Write

Update element

Partial update — send only the fields you want to change. spec, name, and intention are all independently optional. spec MUST be a JSON object when present; deep-merged into the existing spec by default. Empty {"spec":{}} preserves existing spec content but still records a new version (no-op for content, not for version state). To clear/replace the entire spec wholesale send {"spec":{...},"deep":false}. List-typed spec fields use replace semantics (the patch list replaces the existing list, no array merging). Coordinates Git + DB writes. Slug cannot be changed after creation.

Error Codes

Code	Class	Retryable	Description
ALERT_CHANNEL_FAILED	internal	yes	Failed to send to channel
ALERT_CONDITION_INVALID	validation	no	Invalid alert condition