Pingtower
Docs
Configure
One YAML file. The agent refuses to start on anything it does not understand, which is the point.
# /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 |
|---|---|---|
idREQUIRED | 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.
| Field | Default | Meaning |
|---|---|---|
interval | 60s | How often to run. |
timeout | 10s | Per run. A timeout is a down verdict with the reason. |
report | on_change | on_change sends on a status transition plus one sample per sample_interval. on_breach also keeps sending every run while the check is not up. always sends every run. |
sample_interval | 60s | Under on_change and on_breach, the cadence of the “still here” sample. |
down_level | 400 | Level of the event when the check is down. Set 500 for a check that should page. |
Per check only:
| Field | Meaning |
|---|---|
idREQUIRED | Stable name. Becomes the check:<id> tag. |
addonREQUIRED | One from the catalogue. |
with | The addon’s own parameters. An unknown key is a startup error. |
Validate and try
addons agent --config /etc/addons/agent.yaml --check # parse and validate, then exit
addons list # every addon, parameter and default
addons check tlscert --param address=example.com:443 # run one check once, print the event
addons check tlscert --param address=example.com:443 --report # and send it
addons check reads the token from the environment, never a flag.
Sensors
Sensors have their own list and their own gate. See Sensors.
agent:
enable_sensors: [nftwatch, network]
sensors:
- id: host-firewall
sensor: nftwatch
with: { netns: host, settle: 250ms, reconcile: 5m }