Concepts Alerts

Alerts

An Alert is the runtime record of a threshold rule (Alert Config) firing on a specific Check. It is a distinct entity from an Incident — an Alert tracks "this check has been unhealthy since X"; an Incident is a manually declared, user-facing disruption. Alerts never create or attach to Incidents automatically — that link is always a deliberate action taken from the Alerts panel.

Key properties

Field	Type	Description
AlertConfigId	int	The threshold rule that fired
CheckId	int	The check whose result triggered this alert
ServiceId	int	The service the check belongs to
IncidentId	int?	Set once this alert is linked to an incident (null until that manual step happens)
ImpactAtFireTime	ServiceStatus	The service status snapshot at the moment the alert fired
Message	string?	Optional detail captured at fire time
MessageFingerprint	string	Used to detect duplicate/repeat firings for dedup purposes
FiredAt	datetime	When the alert first fired
ResolvedAt	datetime?	When the alert auto-resolved (recovery threshold met). Null while still active
OccurrenceCount	int	How many times this same alert condition has re-fired without resolving — see below
EscalationCurrentStep / EscalationStepStartedAt	int?, datetime?	Tracks progress through the service's Escalation Policy, if one is assigned
AcknowledgedAt / AcknowledgedBy	long?, string?	Set when a team member acknowledges the alert
LastUserActivityAt	datetime?	Last time a human interacted with this alert — feeds escalation re-triggers

Source: Alert.cs

Severity and metric

Every Alert Config — and by extension every Alert it produces — has:

• Severity: Warning or Critical
• AlertFor (the metric watched): Status, Latency, or Uptime

Source: AlertSeverity.cs, AlertFor.cs

Occurrence tracking

Rather than creating a brand-new Alert record every time the same failing condition is re-observed, Piro increments OccurrenceCount on the existing open Alert. This keeps a single alert as the source of truth for "how many times has this been observed" instead of flooding the Alerts panel with duplicates for a condition that never actually resolved. MessageFingerprint is what identifies "the same alert" across occurrences.

Lifecycle

Fired → (re-fires increment OccurrenceCount) → Acknowledged (optional) → Resolved

1. Fired — the alert config's failure threshold is met; an Alert record is created (or an existing unresolved one has its occurrence count bumped).
2. Escalation (optional) — if the service has an Escalation Policy assigned, the alert begins progressing through its steps, paging on-call users until acknowledged.
3. Acknowledged (optional) — a team member acknowledges the alert, which pauses escalation progression (subject to re-escalation thresholds).
4. Resolved — the alert config's recovery threshold is met; ResolvedAt is set and escalation stops.

Manual linking to an Incident

Alerts are never auto-attached to an Incident. From the Alerts panel, a user can:

• Create a new incident from an alert — omit incidentId in the request and Piro creates one, pre-populated with the affected service.
• Link to an existing incident — pass an incidentId to attach the alert to an incident already in progress (useful when multiple alerts represent the same outage).

Both paths go through the same endpoint:

POST /api/v1/alerts/{id}/incident

Source: AlertsOverviewController.cs

⚠️ No auto-creation. Earlier design notes/roadmaps for Piro mentioned automatically creating incidents from alerts — this was deliberately dropped. An alert firing does not by itself create or update any incident; someone must act on it from the Alerts panel.

Dashboard metrics

Alerts feed MTTA (mean time to acknowledge) and MTTR (mean time to resolve) metrics shown on the dashboard, computed from FiredAt, AcknowledgedAt, and ResolvedAt.

Related

• Incidents — the user-facing disruption an alert can be manually linked to
• Escalation Policies — how an unacknowledged alert escalates to on-call
• Triggers — notification channels an alert dispatches to when it fires
• Checks — the underlying probe whose result produces alerts