Observability
Signals & Alerts
Signals are structured events emitted by the Niitaka policy engine whenever something noteworthy happens during an agent run — a guardrail tripped, a retry fired, a cost spike detected. They are your real-time audit trail of every intervention the platform makes on behalf of your agent.
Alerts are the notification layer on top of signals. Configure a webhook, email, or Slack destination and Niitaka will push a notification each time a matching signal arrives.
Signal taxonomy
Every signal has a type (the broad category) and a subtype (the specific event). The colour coding follows severity.
Hard execution stop — a cost or step threshold was reached and the run was aborted.
Operational control action taken — a retry or model fallback was triggered by the engine.
Soft warning — an anomaly detector noticed unusual cost or error rates across sessions.
A policy rule matched and its configured action was applied. Expected enforcement.
Reading the signals feed
The Signals page groups signals by day with sticky date headers. Each row shows:
Click any signal row to navigate directly to the session it belongs to. The session drawer opens at the exact event that triggered the signal.
Filtering
- Type filter — show only control, policy, guardrail, or alert signals.
- Agent filter — scope to signals from a single agent ID.
- Date range — presets for last 24 h, 7 d, 30 d, or a custom range.
Real-time stream
Signals appear in the feed in real time via Server-Sent Events (SSE). You do not need to refresh — new signals push to the top of the current day group as they arrive.
Alert configurations
Alerts let you forward specific signals to an external destination. Configure them under Settings → Alerts.
Sends a plain-text email with signal type, subtype, agent, and message.
# Slack
Posts a formatted message to the configured Slack Incoming Webhook URL.
⚡ Webhook
HTTP POST to any HTTPS endpoint with a JSON payload matching the Signal schema.
Configuration fields
When signals fire
The policy engine evaluates every incoming event. A signal is emitted whenever:
- A
cost_limitorstep_limitwarn or abort threshold is crossed. - A
retrypolicy fires (subtype:retry) or is exhausted (subtype:retry_exhausted). - A
fallbackpolicy switches the model (subtype:fallback). - A
policy_triggeredevent is logged by the engine for any other policy match. - A cost spike or error spike is detected by the background anomaly detector (subtype:
cost_spike/error_spike).
See Policy Evaluation for a detailed walkthrough of how the engine decides which signal to emit.
Next steps
- Policies — configure the rules that drive signal emission.
- Policy Evaluation — understand how the engine evaluates each event.