Pingtower
Docs
Alerts & escalation
An alert has three states and two verbs. Everything about paging follows from that.
- Firing means nobody has claimed it. It re-pages on its rule’s cadence and climbs its escalation ladder. In the app this is the Open filter.
- Acked means someone is on it. Paging stops. The count keeps climbing if lines keep matching, so you can watch whether your fix worked.
- Resolved means done. The alert leaves the open feed, stops counting toward the project’s
open_alerts, and stays in history for thirty days by default.
What an alert carries
| Field | Meaning |
|---|---|
id | Stable id, used by ack and resolve. |
project, rule | Which rule opened it. |
state | firing, acked or resolved. |
level | The highest level seen among its lines. |
count | Matching lines since it opened. |
escalation_level | Which rung of the ladder it has reached. 0 is the rule’s own recipients. |
template | The recovered shape that matched. |
last_message | The most recent raw line, so the notification says something useful. |
first_seen, last_seen | When it opened and when the last line matched. |
identifiers | The key values that split this alert from its siblings, when the rule uses identifier_keys. |
page_accounts | Who the current escalation rung is paging, when it narrows the audience. |
investigate | The rule asked the app to lead with the log tail. |
Reading the feed
GET /v1/pull?cursor=N&wait=S returns every alert changed since cursor N and the next cursor. wait parks the request for up to that many seconds if nothing has changed, which is how the app keeps a live feed without polling in a loop. wait=0 returns immediately.
curl -s "$PT/v1/pull?cursor=0" -H "Authorization: Bearer ptk_…"
Ack and resolve
POST /v1/alerts/{id}/ack and POST /v1/alerts/{id}/resolve. Both return the alert as it now stands. Acking an alert that is already acked, or resolving one already resolved, returns 200 with the unchanged alert; only an unknown id is a 404. The app uses exactly these routes, so anything it can do a script can do.
Both are written to the audit log with who did it.
Who gets paged
Every device of every member of the tenant gets a push for every alert event. An escalation rung that names schedules or accounts narrows that event’s audience to those people, and that is also the only event delivered as a critical alert. Webhook, Slack and Telegram integrations receive the same events, filtered however each integration was configured.
| Event | When |
|---|---|
alert.opened | The rule fired and no matching alert was firing. |
alert.bumped | Another line folded into a firing alert. |
alert.escalated | A ladder rung’s after_minutes passed without an ack, or a renotify fired. |
alert.acked | Someone acked. |
alert.resolved | Someone resolved, or quiet time ran out. |