Pingtower

API reference

Mon, 01 Jan 0001 00:00:00 +0000

Every endpoint below answers at https://api.pingtower.com, over TLS — almost all of them with a bearer token. Which token you send decides which plane you are on — the prefixes are mutually exclusive, so one kind can never be mistaken for another.

This page is generated from the daemon’s route table rather than written by hand, and a build gate fails when the two disagree. Nothing here can outlive the code it describes. The same document is served machine-readable at /api/openapi.json, and this page as Markdown at index.md.

FAQ

Mon, 01 Jan 0001 00:00:00 +0000

General

Is Pingtower free?

Yes, during preview, with no credit card. The Free tier holds 5 projects, 1,000 alerts and 50,000 log rows per tenant. Paid plans will come later, announced well ahead, and early users get founder pricing. See Plans & quotas and pricing.

Do I need to install anything?

The iOS app, if you want a phone to ring. The service is hosted. The daemon and the addons agent are optional, for keeping data on your own hardware and for probing things from outside.

Ingest

Mon, 01 Jan 0001 00:00:00 +0000

POST /v1/ingest, authenticated with a pti_ source token. Nothing in the body names a project or a source; the token decides.

Payload

Field	Type	Meaning
`message`REQUIRED	string	The line. Template extraction runs on this. Up to 64 KiB.
`level`	integer	Severity. 100 debug, 200 info, 300 warn, 400 error, 500 critical.
`keys`	object	Up to 128 named values, names up to 128 bytes, values up to 4096 bytes. Each value is substituted out of the message to form the template, is available to rule conditions, and can group alerts through `identifier_keys`. Scalars only; they are stored as strings.
`tags`	string[]	Up to 64 free-form labels a rule can match on, each up to 256 characters.

{
 "message": "payment gateway timeout after 30012ms for order o_48113",
 "level": 400,
 "keys": { "order": "o_48113", "gateway": "stripe", "latency_ms": 30012 },
 "tags": ["billing", "prod"]
}

The server timestamps the line on arrival. There is no client timestamp field.

Install

Mon, 01 Jan 0001 00:00:00 +0000

Get a release and verify it

Download the tarball and the SHA256SUMS and SHA256SUMS.sig beside it from the addons download table. Get the release public key, addons-release.pub, and check the sums file was signed by this project, then that your tarball matches it. Skipping either lets a tampered tarball and a tampered checksum file agree with each other.
```
printf 'release@pingtower.com namespaces="pingtower-addons-release" %s\n' \
 "$(cut -d' ' -f1,2 addons-release.pub)" > allowed_signers
ssh-keygen -Y verify -f allowed_signers -I release@pingtower.com \
 -n pingtower-addons-release -s SHA256SUMS.sig < SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
```
Addons signatures live in their own pingtower-addons-release namespace, so an addons signature can never pass as a daemon release or vice versa. Needs stock OpenSSH 8.2 or later.

Install & sign in

Mon, 01 Jan 0001 00:00:00 +0000

Install the app

Join the TestFlight beta.The beta is open to everyone, with no invite needed; when the app ships on the App Store the link changes and your account carries over.
Sign up or sign in

Email and password. Signing up creates an account and nothing else. Passwords are at least eight characters. The sign-in limiter allows a handful of attempts and then refills over about five minutes, so a mistyped password is not a lockout.

Install the daemon

Mon, 01 Jan 0001 00:00:00 +0000

Download and verify

Get the binary for your architecture from the download table. Every release carries an SSH signature over a signed provenance file that names exactly what was built. Check the SHA-256 against the table, then verify the signature against the release public key, pingtower-release.pub.

sha256sum pingtower-linux-amd64 # compare with the table
printf 'release@pingtower.com namespaces="pingtower-release" %s\n' \
 "$(cut -d' ' -f1,2 pingtower-release.pub)" > allowed_signers
ssh-keygen -Y verify -f allowed_signers -I release@pingtower.com \
 -n pingtower-release -s pingtower-linux-amd64.release.sig \
 < pingtower-linux-amd64.release
cat pingtower-linux-amd64.release # sha256= must match the sum above

Needs stock OpenSSH 8.2 or later. If any check fails, do not run the binary.

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

Create an account and a tenant

Sign up in the iOS app, or from the API. Signing up gives you a login; it does not create a tenant, so create one next. A tenant is a company or a team, and everything below lives inside it.

PT=https://api.pingtower.com

curl -s "$PT/v1/signup" -H 'Content-Type: application/json' \
 -d '{"email":"you@example.com","password":"…"}'
# → {"account":{…},"token":"pts_…"}

curl -s "$PT/v1/tenants" -H "Authorization: Bearer pts_…" \
 -H 'Content-Type: application/json' -d '{"name":"Acme"}'
# → {"id":"<tid>","name":"Acme","role":"owner"}

Mint a tenant API key

Concepts

Mon, 01 Jan 0001 00:00:00 +0000

Term	What it is	Lives in
Account	You. An email and a password. One account can belong to many tenants.	pingtower.com
Tenant	A company or a team. Owns its own data, members and API keys. Every tenant you join gives you a separate credential scoped to just that tenant’s data.	pingtower.com, or your own box
Project	A namespace inside a tenant: a service, an environment, a product. Holds sources, rules, integrations, actions and reports. Open-alert counts roll up per project. Addressed by name.	tenant
Source	One thing that sends lines. Each source has its own ingest token, which you can rotate without touching the others, and its own `retain_logs` switch.	project
Template	A message’s shape: the line with the values you passed as `keys` substituted out. `payment failed for o_48113` with `keys.order = o_48113` becomes `payment failed for {{ .order }}`, so every order’s failure counts as the same thing.	project
Rule	A declarative match plus timing: what to look for, how many in what window, how often to re-page, who to escalate to.	project
Alert	A rule that fired. Carries a count, an escalation level, first and last seen, and the last message. Firing until acked, resolved when done.	project

How isolation works

Each tenant is one SQLite file. The credential you present decides which file is opened. Nothing in a URL or a request body can reach another tenant’s data, because there is no code path that opens a file the token did not name.

Configure

Mon, 01 Jan 0001 00:00:00 +0000

# /etc/addons/agent.yaml
agent:
 id: probe-fra-01
 region: eu-fra
 tower:
 url: https://api.pingtower.com # or your own box
 token_env: PINGTOWER_INGEST_TOKEN # read from /etc/addons/agent.env
 heartbeat: 5m
 max_concurrent: 8
 enable_addons: [sshcheck] # privileged addons must be listed
 enable_sensors: []

defaults:
 interval: 60s
 sample_interval: 60s
 timeout: 10s
 report: on_change

checks:
 - id: api-health
 addon: httpcheck
 interval: 30s
 down_level: 500 # 500 pages; 400 is the default
 with:
 url: https://api.acme.example/healthz
 expect_status: 200
 max_ttfb: 800ms

 - id: api-cert
 addon: tlscert
 interval: 6h
 with:
 address: api.acme.example:443
 warn_before: 336h # 14 days; default is 21

 - id: box-login
 addon: sshcheck
 interval: 5m
 with:
 address: 10.0.0.12:22
 user: probe
 key_file: /etc/addons/probe_ed25519
 command: systemctl is-active postgresql
 expect_output: active

`agent`

Field	Default	Meaning
`id`REQUIRED		Stable name. Carried on every event and the heartbeat’s identity.
`region`		Free-form label carried on every event.
`tower.url`		Where to POST. `https://api.pingtower.com`, or your box.
`tower.token_env`	`PINGTOWER_INGEST_TOKEN`	Environment variable holding the `pti_` token. Never a config value, so it stays out of the file.
`tower.max_rps`		Cap on the agent’s own send rate.
`tower.spool_dir`	`/var/lib/addons/spool`	Where events wait out an outage.
`tower.spool_max_bytes`	64 MiB	Oldest events are dropped past this.
`heartbeat`	`5m`	How often the agent reports on itself.
`max_concurrent`	8	Checks running at once.
`enable_addons`	`[]`	Privileged addons this agent may run. An unknown or non-privileged name is a startup error.
`enable_sensors`	`[]`	Sensors this agent may run. Same rule.
`state_dir`	beside the spool	Where addons that need a baseline, like `hostmetrics`, keep it.

`defaults` and per-check fields

Every field here can be set once under defaults and overridden per check.

Errors

Mon, 01 Jan 0001 00:00:00 +0000

{ "error": "validation failed",
 "fields": [ { "field": "name", "message": "must not be empty", "rule": "required" } ] }

Status	When	Extra fields
`400`	The body or a parameter failed validation.	`fields[]` with `field`, `message`, `rule`.
`401`	Bearer missing, malformed, or not the kind this route takes; or a wrong `current_password` on a route that re-checks it.
`403`	Your role cannot do this: a member renaming a project or deleting a source, an admin inviting an owner.
`404`	Unknown project, source, rule, alert, or a tenant you are not a member of.
`409`	Conflict. Deleting something a rule still names; removing the last owner; an email already taken; a disabled integration asked to test; editing a self-hosted box’s relay integration through anything but `PUT /v1/relay`.	`rules[]` for a referenced source, action or schedule.
`422`	The request was well-formed but points at something that does not exist: a rule naming an unknown action, a schedule naming a non-member. Also an integration named `pingtower.com relay`, which is reserved.	`errors[]` when more than one.
`429`	Over a rate limit, a storage quota, or a count cap.	`Retry-After` header, whole seconds, on a rate limit only.
`500`	The daemon could not store or read.
`503`	A test route was called on a daemon with no sender or executor configured.

The referenced-error shape

{ "error": "store: source is referenced by rules: gateway-timeouts, errors",
 "rules": ["gateway-timeouts", "errors"] }

Returned on DELETE of a source, action or on-call schedule, and on renaming an action, while a rule still references it. Edit or delete those rules first.

Reverse proxy & TLS

Mon, 01 Jan 0001 00:00:00 +0000

Caddy

/etc/caddy/Caddyfile:

alerts.example.com {
 reverse_proxy 127.0.0.1:8391 {
 header_up X-Real-IP {remote_host}
 }
}

Caddy issues and renews the certificate itself. The header_up line is for client addresses.

nginx

server {
 listen 443 ssl http2;
 server_name alerts.example.com;
 ssl_certificate /etc/letsencrypt/live/alerts.example.com/fullchain.pem;
 ssl_certificate_key /etc/letsencrypt/live/alerts.example.com/privkey.pem;

 location / {
 proxy_pass http://127.0.0.1:8391;
 proxy_http_version 1.1;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto https;
 proxy_read_timeout 60s;
 }
}

Long-poll needs a patient proxyGET /v1/pull?wait=25 holds the connection open for up to 25 seconds. A proxy read timeout under 30 seconds turns every quiet poll into a 504. Caddy’s default is fine; nginx’s default of 60 seconds is fine; a stricter default in front of either is not.

Client addresses

Sign-up, sign-in, account deletion, password-reset requests and seat redemption are rate-limited per client address. Behind a proxy on the same host, every request reaches the daemon from 127.0.0.1, so the daemon cannot tell callers apart: it skips the per-client limit altogether, keeps the per-email limits, and counts everyone’s failed sign-ins as one caller’s. Set -client-ip-header X-Real-IP (or PINGTOWER_CLIENT_IP_HEADER=X-Real-IP) to the header the proxy sets, as both examples above do.

Rules

Mon, 01 Jan 0001 00:00:00 +0000

{
 "name": "gateway-timeouts",
 "match": {
 "min_level": 400,
 "sources": ["api", "worker"],
 "tags": ["billing"],
 "template_contains": "gateway timeout"
 },
 "conditions": [
 { "key": "latency_ms", "op": "gte", "value": 10000 }
 ],
 "fire_after": { "count": 5, "window_minutes": 10, "distinct_sources": true },
 "identifier_keys": ["gateway"],
 "dedup_window_minutes": 30,
 "renotify_minutes": 10,
 "max_renotify": 6,
 "escalations": [
 { "after_minutes": 15, "schedules": ["backend-secondary"], "repeat_minutes": 10 },
 { "after_minutes": 45, "accounts": ["cto@acme.example"] }
 ],
 "actions": ["restart-gateway-worker"],
 "auto_resolve_quiet_minutes": 60,
 "investigate": true
}

POST /v1/projects/{id}/rules creates one. GET PUT DELETE /v1/projects/{id}/rules/{name} read, replace and remove it. A rule’s name is its identity. A project holds at most 500 rules, and every …_minutes field is capped at 525,600, a year; the rest are in Limits.

The alert feed

Mon, 01 Jan 0001 00:00:00 +0000

The list

The feed is a single live pull over the tenant’s alert cursor, so it updates in place without a refresh. Unresolved alerts sort before resolved ones, and within that the most recently seen first.

Filter by state with the segmented control: Open is everything not resolved, then Firing, Acked, Resolved. Filter by project from the projects already in the list. Pull down to restart the poll if the connection dropped.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Lines arrive but no alert opens

Check the ingest response: "alerted": false means no rule matched. The usual causes, in order:

The rule’s min_level is above the line’s level. min_level: 400 ignores a 300.
match.sources names a source and the line came from another.
template_contains is matched against the template, not the message. If the substring you wrote contains a value that is in keys, it has been replaced with {{ .name }} in the template.
fire_after is waiting for more lines.

GET /v1/projects/{id}/rules/{name} shows the rule as stored.

Alerts & escalation

Mon, 01 Jan 0001 00:00:00 +0000

firing→acked→resolved

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.

Credentials

Mon, 01 Jan 0001 00:00:00 +0000

Token	Prefix	Grants	Get one from
Session	`pts_`	The account plane: list and create tenants, manage members and keys.	`POST /v1/login`, or signing in from the app
Tenant API key	`ptk_<tenant>_`	One tenant’s data plane: pull, ack, resolve, projects, sources, rules, integrations, actions, log tail.	`POST /v1/tenants/{tid}/keys`, or Account → API keys in the app
Ingest source token	`pti_<tenant>_`	`POST /v1/ingest` only. Cannot read anything back.	Creating a source

The <tenant> segment is a routing hint that picks which database to open. The secret is still verified by a constant-time compare inside that database, so a forged tenant segment opens the wrong file and fails.

Critical alerts

Mon, 01 Jan 0001 00:00:00 +0000

Which pushes are critical

The event decides, not the level. Two events are delivered as critical alerts: alert.opened, the first page of something nobody has seen yet, and alert.escalated, meaning a rule’s renotify fired or a ladder rung was reached without an ack. A repeat of an open alert (alert.bumped), an ack and a resolve are ordinary notifications, so the interruption is spent once per new alert rather than once per matching line.

Rate limits

Mon, 01 Jan 0001 00:00:00 +0000

Plane	Free	Pro
Ingest, per tenant	20 req/s, burst 40	200 req/s, burst 400
Data and account, per tenant	10 req/s, burst 20	100 req/s, burst 200

Enterprise limits are set per tenant. Over a limit the response is 429 with Retry-After in whole seconds.

Routes that take a password

Sign-up, login, account deletion and password-reset requests are limited in layers, so that one caller who knows your email cannot lock you out:

Relay & pairing

Mon, 01 Jan 0001 00:00:00 +0000

The shape of it

The box mints a join code: pingtower pair --email you@example.com.
The app redeems the code against the box and gets a box-minted ptk_ key, plus a receipt.
pingtower.com confirms the receipt with the box, once, at GET /v1/pair/verify.
The app writes the relay credential to the box with PUT /v1/relay.
From then on, every project on the box has a webhook integration named “pingtower.com relay”. Every alert event goes out through it like any other webhook, and pingtower.com turns it into a push to the devices paired with that tenant, critical or ordinary by the same rule as a hosted page.

The box never accepts a connection from pingtower.com beyond the one-time verify. Everything is outbound from the box, so it works from behind NAT as long as the app can reach the box’s URL when it pairs.

Log tail & templates

Mon, 01 Jan 0001 00:00:00 +0000

Templates

A template is a message with the values you passed as keys substituted out. The substitution is literal: each key’s value is searched for in the message and replaced with {{ .name }}, longest value first, every occurrence.

Message	Keys	Template
`user bob logged in`	`{"name":"bob"}`	`user {{ .name }} logged in`
`timeout after 30012ms for o_48113`	`{"order":"o_48113","latency_ms":30012}`	`timeout after {{ .latency_ms }}ms for {{ .order }}`
`disk full`	none	`disk full`

The template’s SHA-256 is its id, returned on every ingest response as template_id and carried by every alert as template. Two lines with the same template are the same thing to a rule and fold into the same alert.

Pairing your own box

Mon, 01 Jan 0001 00:00:00 +0000

Pairing joins two things: an account on pingtower.com, which is what the app signs in with, and a tenant on a box you run, which is where the data lives. Once paired, the app talks to the box for everything and to pingtower.com only for the account and for push.

On the box, mint a join code
```
pingtower pair --email you@example.com
```
It prints one code starting with ptj_. The code bundles the box’s URL, the tenant, and a one-shot pairing secret. It is valid for one hour and can be redeemed once. Owners and admins can also mint codes from the API with POST /v1/pair/codes, with ttl_seconds up to seven days, to seat teammates without a shell. Seats exist only on a box: pingtower.com refuses to mint or redeem one with a 409, and a hosted tenant adds people by invite.

Projects & sources

Mon, 01 Jan 0001 00:00:00 +0000

Projects

GET /v1/projects lists every project the tenant owns, name-ordered, each with name, config_version, sources, rules, open_alerts and created_at. Paginate with limit and after, passing the last name on the previous page.

POST /v1/projects with {"name": "…"} creates one. Projects are explicit rows: a typo in a path is a 404, never a project created by accident.

POST /v1/projects/{id}/rename and DELETE /v1/projects/{id} are owner or admin only. Renaming does not break ingest tokens, which resolve through the source row. Deleting removes the project’s sources, rules, alerts and reports; a report’s public page stops resolving.

Integrations

Mon, 01 Jan 0001 00:00:00 +0000

Kind	Needs	Notes
webhook	`url`. Optional `secret`; one is minted and shown once if you leave it out.	Signed. Payload below.
slack	`webhook_url` from an incoming-webhook app.
telegram	`token` for a bot and a `chat_id`.
apns	Nothing. Rejected if you send credentials.	Push to the iOS app. Recipients are the tenant’s members; the row exists so you can filter its events and read its delivery log.

Credentials, and a webhook’s signing secret, are sealed at rest and never returned by a read. Set -secret-key on a self-hosted daemon before creating any.

Actions

Mon, 01 Jan 0001 00:00:00 +0000

{
 "name": "restart-gateway-worker",
 "method": "POST",
 "url": "https://deploy.acme.example/api/services/gateway-worker/restart",
 "headers": { "Authorization": "Bearer …" },
 "body": "{\"reason\":\"pingtower\"}",
 "timeout_seconds": 10,
 "events": ["alert.opened"],
 "enabled": true
}

Field	Meaning
`name`	Identity. Rules reference it by name or id.
`method`	`GET`, `POST`, `PUT`, `PATCH` or `DELETE`.
`url`	http or https, up to 2048 characters. Private and loopback ranges are refused.
`headers`	Up to 32. Sealed at rest; reads return only `header_keys`.
`body`	Up to 8 KiB. Sealed at rest; reads return `has_body`. Send `""` to clear it, omit it to keep it.
`timeout_seconds`	0 to 60, default 10.
`events`	`alert.opened`, `alert.escalated`, or both. Default `alert.opened`.
`enabled`	A disabled action is skipped silently.

POST GET /v1/projects/{id}/actions, then GET PUT DELETE /v1/projects/{id}/actions/{aid}.

On-call schedules

Mon, 01 Jan 0001 00:00:00 +0000

API only for nowSchedules, overrides and the who-is-on-call-now answer are served by the hosted service and by self-hosted boxes alike. The iOS app does not yet have screens for them; manage them from the API until it does.

Layers and rotations

A schedule is per project. It has a timezone and one or more layers. Each layer rotates through its participants every shift_minutes, starting at rotation_start. A layer with a restriction is active only inside that window, and a later layer wins over an earlier one while both are active. That is how “weekday office hours go to the ops account, everything else to the weekly rota” is written.

Reports

Mon, 01 Jan 0001 00:00:00 +0000

A report belongs to a project and optionally labels one alert. It gets an unguessable public URL at /public/reports/{uuid} on the service’s host, and can be put behind a password.

POST /v1/projects/{id}/reports

{
 "title": "Checkout degraded, 2026-09-01",
 "description": "Gateway timeouts from 03:12 UTC. Payments retried; no orders lost.",
 "alert_id": "…",
 "view_password": "correct-horse"
}

Field	Meaning
`title`	Up to 256 characters.
`description`	Up to 4096.
`alert_id`	Optional. Must name a live alert when the report is created.
`view_password`	Optional, 8 to 72 bytes. Readers of the public page must enter it. On update: omitted keeps it, `""` clears it, a value replaces it.

The response carries public_uuid and password_protected. POST /v1/projects/{id}/reports/{rid}/rotate-uuid invalidates every link handed out so far and mints a new one.

httpcheck

Mon, 01 Jan 0001 00:00:00 +0000

Parameters

Parameter	Default	Meaning
`url`REQUIRED		http or https.
`method`	`GET`
`headers`		Map of request headers.
`body`		Request body, sent as-is.
`expect_status`	`200`	Any other status is down.
`body_matches`		RE2 pattern the body must match, else down.
`max_ttfb`		Time to first byte above this is degraded.
`follow_redirects`	`true`

Measurements

Key	Unit
`dns_ms`, `connect_ms`, `tls_ms`, `ttfb_ms`, `total_ms`	milliseconds, each stage on its own
`body_bytes`	bytes

Rules for it

{"name":"slow-ttfb","match":{"tags":["addon:httpcheck"]},
 "conditions":[{"key":"ttfb_ms","op":"gte","value":500}]}

{"name":"probe-down","match":{"tags":["addon:httpcheck"],"min_level":400},
 "fire_after":{"count":2,"window_minutes":5,"distinct_sources":true}}

Team & account

Mon, 01 Jan 0001 00:00:00 +0000

Everything on this page is on the account plane and takes a pts_ session token. In the app it lives under Account.

Members and roles

GET /v1/tenants/{tid}/members lists members with their role. Roles are owner, admin and member; see Concepts for what each can do.

DELETE /v1/tenants/{tid}/members/{aid} removes one and revokes their API keys, the invites they created and their box pairings. Removing the last owner is refused. Removing any owner, yourself included, needs {"current_password": "…"} in the body.

Plans & quotas

Mon, 01 Jan 0001 00:00:00 +0000

Pingtower is free during preview, with no credit card. Every new account starts on the Free tier, and its limits are the numbers the server enforces.

Limit	Free	Pro
Projects per tenant	5	100
Alerts retained	1,000	50,000
Log rows retained	50,000	2,000,000
Ingest rate	20 events/s, burst 40	200 events/s, burst 400
API rate	10 req/s, burst 20	100 req/s, burst 200

Pro and Enterprise exist today and are granted by email; there is no checkout. Enterprise is custom limits set to fit your stream. The pricing page says how paid plans will arrive when they do.

tcpcheck

Mon, 01 Jan 0001 00:00:00 +0000

Parameters

Parameter	Default	Meaning
`address`REQUIRED		`host:port`.
`max_connect`		Connect time above this is degraded.

A refused or timed-out connect is down.

Measurements

dns_ms, connect_ms, total_ms.

dnscheck

Mon, 01 Jan 0001 00:00:00 +0000

Parameters

Parameter	Default	Meaning
`name`REQUIRED		The name to resolve.
`type`	`A`	Record type.
`resolver`	system	`host:port` of the resolver to ask.
`expect`		A value that must appear among the answers, else down.
`max_resolve`		Resolve time above this is degraded.

Measurements

resolve_ms, answers (count). The answers themselves are in the event message.

tlscert

Mon, 01 Jan 0001 00:00:00 +0000

Parameters

Parameter	Default	Meaning
`address`REQUIRED		`host` or `host:port`; port defaults to 443.
`server_name`	host from `address`	SNI to present when it differs.
`warn_before`	`504h` (21 days)	Expiry closer than this is down.

An untrusted or already expired certificate is down, with issuer, subject and expiry still filled in, because “which certificate, expiring when, rejected why” is the whole diagnosis. There is deliberately no parameter to skip verification.

Measurements

days_until_expiry (negative once expired), handshake_ms, chain_length.

icmpping

Mon, 01 Jan 0001 00:00:00 +0000

Parameters

Parameter	Default	Meaning
`host`REQUIRED
`count`	`3`	Packets per run.
`spacing`	`200ms`	Between packets.
`max_rtt`		Average above this is degraded.
`max_loss_pct`		Loss above this is down. Total loss is always down.

The addon prefers an unprivileged datagram socket, which macOS allows by default and Linux allows for group ids inside net.ipv4.ping_group_range. If neither that nor a raw socket can be opened the check fails with an error rather than reporting the target down: “we lack permission” and “the host is unreachable” are opposite conclusions.

hostmetrics

Mon, 01 Jan 0001 00:00:00 +0000

Parameters

Parameter	Default	Meaning
`max_sample_interval`	`15m`	Longest gap between two samples that still yields rates. 1s to 24h.

There is no universal up or down threshold. The gauges are for rules that reflect your workload, for example {"key":"load_1m_per_effective_cpu","op":"gte","value":2}.

Measurements

CPU as percentages of time: cpu_utilization_pct (excludes idle and iowait), cpu_user_pct (includes nice), cpu_system_pct (includes IRQ), with steal and iowait separate.
Load: raw 1, 5 and 15 minute averages, and each divided by the CPUs the agent process can actually run on, labelled cpu_scope=process-affinity.
Memory and swap: totals, used, percentages. memory_used_bytes is MemTotal - MemAvailable, so reclaimable cache is not called unavailable. A zero-sized swap omits swap_used_pct.
Paging rates in the kernel’s units: _kib_per_s for page in and out, pages per second for swap.

Rates need two valid samples. The first run reports measurement_health=warming-up and omits them, as does any run after a corrupt state file, a counter rollback, an interval outside the allowed range, or a CPU-count change. A normal restart resumes from the saved baseline in agent.state_dir.

sshcheck

Mon, 01 Jan 0001 00:00:00 +0000

privileged Add sshcheck to agent.enable_addons.

Parameters

Parameter	Default	Meaning
`address`	port 22	`host:port`.
`user`REQUIRED
`key_file`REQUIRED		Private key readable by the `addons` user.
`known_hosts`	`~/.ssh/known_hosts`	Expanded against the agent’s home.
`command`		Run after auth.
`expect_exit_code`	`0`	Only with `command`.
`expect_output`		Substring the output must contain. Only with `command`.
`max_command`		Command time above this is degraded. Only with `command`.

No password, passphrase or host-key-bypass parameter exists. A host key that does not match known_hosts is down, because that is a real finding about the target. An unreadable key or a missing known_hosts file is a config error, not a verdict. Setting any expect_* without a command is refused at startup. Output past 4 KiB is dropped.

portscan

Mon, 01 Jan 0001 00:00:00 +0000

privileged Add portscan to agent.enable_addons. Needs the nmap binary on the box.

Parameters

Parameter	Default	Meaning
`host`REQUIRED		Exactly one host.
`ports`REQUIRED		Ports or ranges to scan, up to 1024.
`baseline`REQUIRED		Ports expected open.
`max_rate`	`100`/s	Capped at 1000.
`host_timeout`	`60s`

An open port not in the baseline is down. A baseline port proved closed is degraded. A port the scan could not determine is degraded.

traceroute

Mon, 01 Jan 0001 00:00:00 +0000

privileged Add traceroute to agent.enable_addons. Needs the traceroute binary.

Parameters

Parameter	Default	Meaning
`host`REQUIRED
`max_hops`	`30`
`probes`	`3`	Per hop.
`wait`	`1s`	Per probe, whole seconds, at most 30.

A path where some hops do not answer is degraded. No hop answering at all is down.

Measurements

hops, path_change (1 when the path differs from the last run), rtt_ms, and hop_<n>_rtt_ms per hop.

logwatch

Mon, 01 Jan 0001 00:00:00 +0000

privileged Add logwatch to agent.enable_addons, and give the addons user read access to the file.

Parameters

Parameter	Default	Meaning
`path`REQUIRED
`pattern`REQUIRED		RE2.
`warn_at`	`1`	Matches per run at or above this are degraded.
`down_at`	`0`	Matches at or above this are down. 0 means never. Wins over `warn_at`.
`max_bytes`	4 MiB	Most read per run; the rest is reported as `skipped_bytes`.
`initial_tail`	256 KiB	How far back to read on first run.

A missing file is down. An unreadable one is a config error.

securityupdates

Mon, 01 Jan 0001 00:00:00 +0000

privileged Add securityupdates to agent.enable_addons. Debian and apt only.

Parameters

Parameter	Default	Meaning
`metadata_max_age`	`48h`	Package lists older than this report `measurement_health=stale`.

The addon never runs apt update or installs anything. If package metadata is missing or unreadable it reports measurement_health=unavailable with the counts omitted rather than a zero that looks like good news.

Measurements

updates_available, security_updates_available, metadata_age_s, reboot_required, held_packages, phased_updates, deferred_updates.

A rule for it

{"name":"security-updates-pending","match":{"tags":["addon:securityupdates"]},
 "conditions":[{"key":"security_updates_available","op":"gte","value":1}],
 "identifier_keys":["agent"],"renotify_minutes":1440}

Sensors

Mon, 01 Jan 0001 00:00:00 +0000

New in addons 0.2.0. Linux only. Gated behind agent.enable_sensors, so a config naming a sensor without that fails at startup, like the privileged addons.

Sensor	Watches	Needs
`nftwatch`	The host’s nftables ruleset. Reports the moment it changes. Sends only ruleset hashes and object counts, never the rules.	`CAP_NET_ADMIN`
`network`	Every inbound TCP connection attempt, through a pass-only eBPF program that can observe and never drop, redirect or rewrite. Aggregated by port and redacted remote prefix.	`CAP_BPF`, `CAP_NET_ADMIN`
`authwatch`	SSH and sudo authentication events from the system journal, matched strictly against the distribution’s exact message forms. Usernames and raw messages are never sent; remote addresses are reduced to a /24 or /64.	journal read access
`filewatch`	An explicit set of files and shallow directory roots. inotify is only a wake-up; every event settles into a stat reconciliation, so an atomic editor replace is a confirmed change. Events carry path, type, owner, mode and SHA-256, never contents.	read access
`listeningports`	The kernel’s TCP and UDP listener inventory against an explicit baseline. Undeclared and vanished listeners become events. Exact addresses and PIDs never enter events.	none
`servicewatch`	An explicit list of systemd units: failures, recoveries, restart-loop crossings, unit-file hash changes, and a service whose command became a different binary.	none
`pressure`	Kernel PSI stall triggers for CPU, memory and I/O. One event per crossing, one per recovery.	none

Several run under the stock unit with an empty capability set. The kernel-attached ones take one narrow capability through a local systemd drop-in; the tarball’s README has the exact drop-in for each.

A live Logs tab, cleaner team changes, and fairer delivery.

Thu, 24 Sep 2026 00:00:00 +0000

TestFlight build 38 is out, and pingtower.com is running the server it pairs with. Most of what changed is things you’ll notice; a fair share of it is things you shouldn’t have to.

Get the beta on TestFlight →

Logs, first

The app now opens on a Logs tab: every project’s live tail side by side, merged newest first. Filter by project, minimum level, or — with one project in scope — a single source, and the header tells you when you’re looking at “3 of 5 projects”. A tail that loses the network says “Reconnecting…” and backs off instead of giving up, and when you come back to it, it resumes from where it was rather than dropping the lines in between. Alerts are one tab over, and a notification still opens straight into the alert.

The probe agent learns to watch from inside.

Tue, 01 Sep 2026 00:00:00 +0000

The addons agent has one job: watch your infrastructure from a box that isn’t part of it, so an outage your app can’t log still becomes an alert. That job hasn’t changed. But as of 0.2.0, the same binary has a second one — installed on the box you care about, it watches from inside, continuously, at the kernel.

Sensors, not checks

A check runs on a schedule: every sixty seconds, ask the question, report the answer. That’s the right shape for “is the site up” and the wrong shape for “did someone just change my firewall” — a rule added and removed between two runs never existed as far as a poll is concerned.

The iOS beta is open to everyone.

Sun, 30 Aug 2026 00:00:00 +0000

Two days ago the app was sitting in Apple’s review queue. Today it’s in your hands: the public TestFlight beta is open to everyone, no invite needed.

Join the beta on TestFlight →

Install Apple’s TestFlight app, tap the link, and you have the pager: a live alert feed, one swipe to ack — which stops the escalation ladder for everyone — and critical alerts that sound through Silent mode and Focus, a permission you grant once. Sign up right in the app, or log in with the account you already created; self-hosting your tower? Pair your box with pingtower pair and its alerts ring the same phone.

Pingtower is live. The app is in review.

Fri, 28 Aug 2026 00:00:00 +0000

Update, August 30: the app cleared review — the public TestFlight beta is open to everyone. Details in the follow-up post.

As of today, Pingtower is a real service you can sign up for. The hosted tower runs at api.pingtower.com, signups are open, and the whole thing is free while we’re in pre-release. One curl creates your account; a second one creates your team.

Here’s exactly what’s live, what’s signed, and what’s still sitting in a review queue at Apple.

Privacy Policy

Fri, 28 Aug 2026 00:00:00 +0000

Pingtower is an alerting service: your applications send structured logs to a Pingtower server, and Pingtower turns them into alerts that reach a person — usually through the Pingtower iOS app. This policy explains what data we handle across the three places Pingtower runs: the hosted service at pingtower.com, the self-hosted server, and the iOS app.

Who this covers

The hosted service — Pingtower operated by us, where your account, tenants, and (if you use hosted tenants) your log and alert data live on our infrastructure.
The self-hosted server — the same software running on your own machine. Its data stays with you, with the specific exceptions described below.
The iOS app — the client that receives alerts on your phone.
This website — a static site with no analytics, advertising, or tracking cookies.

Your Pingtower account

Everyone who uses the iOS app has an account on the hosted service — including self-hosters. That is a deliberate part of how Pingtower works: Apple push notifications for the Pingtower app can only be sent by us, so the registry of which phone belongs to which person has to live on our service.

Terms of Service

Fri, 28 Aug 2026 00:00:00 +0000

These terms govern your use of Pingtower: the hosted service at pingtower.com, the Pingtower server software when you run it yourself, and the Pingtower iOS app. By creating an account or using any of them, you agree to these terms.

What Pingtower is

Pingtower is log-driven alerting. Your applications POST structured log lines to a Pingtower server; the server deduplicates repeats, evaluates your rules, and maintains alert state with escalation until a person acknowledges. Alerts reach people through the iOS app — including critical alerts that sound through Silent mode — and through integrations you configure, such as webhooks, Slack, and Telegram.

Sign in like a normal app. Run every team from your phone.

Mon, 13 Jul 2026 00:00:00 +0000

Getting a new phone onto Pingtower used to mean finding an API key, copying it off a laptop, and pasting it into a text field before you could see a single alert. That’s a fine way to hand a script a credential. It’s a bad way to onboard a person.

This week we rebuilt how Pingtower handles accounts and teams from the ground up. Here’s what’s different.

Onboarding is now email and password — sign up or log in, and you’re in. No server address to track down, no key to paste, no laptop required. Whether you’re setting up Pingtower for the first time or handing your phone to a new hire, the whole flow is: type your email, pick a password, done.

Addons

Mon, 01 Jan 0001 00:00:00 +0000

Features

Mon, 01 Jan 0001 00:00:00 +0000

Get started

Mon, 01 Jan 0001 00:00:00 +0000

How it works

Mon, 01 Jan 0001 00:00:00 +0000

Pingtower as an Opsgenie alternative

Mon, 01 Jan 0001 00:00:00 +0000

The deadline

Atlassian stopped selling Opsgenie on 4 June 2025 and ends support on 5 April 2027. Atlassian’s own path is Jira Service Management for incident management or Compass for alerting and on-call, with a migration tool that turns Opsgenie off 120 days after you run it. If you have not decided yet, the date that matters is not April 2027; it is whenever your renewal conversation happens.

Who this page is for

A team of two to twenty that used Opsgenie for three things: a rota, an escalation policy, and a phone that rings at 3 a.m. That team is paying for, and migrating, a great deal of product it never opened. Pingtower is those three things, built for people who carry their own pager, plus the part Opsgenie never did: taking your application’s own errors directly, deduplicating them by shape, and turning them into the alert.

Pingtower vs Uptime Kuma

Mon, 01 Jan 0001 00:00:00 +0000

What Uptime Kuma is for

Uptime Kuma asks “is it up” on a schedule and shows you the answer, to you on a dashboard and to your customers on a status page. It does that well, it is MIT-licensed, and it runs on a Raspberry Pi. If a service going unreachable is the only failure you need to know about, and a message in a channel is how you want to know, it is the right tool and this page should not talk you out of it.

Pricing

Mon, 01 Jan 0001 00:00:00 +0000

Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

Set up Pingtower for your user

Mon, 01 Jan 0001 00:00:00 +0000

The iOS app

Mon, 01 Jan 0001 00:00:00 +0000

Transparency

Mon, 01 Jan 0001 00:00:00 +0000

Pingtower

API reference

FAQ

General

Ingest

Payload

Install

Install & sign in

Install the daemon

Quickstart

Concepts

How isolation works

Configure

agent

defaults and per-check fields

Errors

The referenced-error shape

Reverse proxy & TLS

Caddy

nginx

Client addresses

Rules

The alert feed

The list

Troubleshooting

Lines arrive but no alert opens

Alerts & escalation

What an alert carries

Reading the feed

Credentials

Critical alerts

Which pushes are critical

Rate limits

Routes that take a password

Relay & pairing

The shape of it

Log tail & templates

Templates

Pairing your own box

Projects & sources

Projects

Integrations

Actions

On-call schedules

Layers and rotations

Reports

httpcheck

Parameters

Measurements

Rules for it

Team & account

Members and roles

Plans & quotas

tcpcheck

Parameters

Measurements

dnscheck

Parameters

Measurements

tlscert

Parameters

Measurements

icmpping

Parameters

hostmetrics

Parameters

Measurements

sshcheck

Parameters

portscan

Parameters

traceroute

Parameters

Measurements

logwatch

Parameters

securityupdates

Parameters

Measurements

A rule for it

`agent`

`defaults` and per-check fields