Skip to main content

MONITOR SERVER HEALTH

This guide shows you how to monitor a running swamp serve instance using its health endpoints.

Prerequisites

  • A running swamp serve instance with authentication enabled
  • Admin access — either via --admins (OAuth mode) or a token with an admin grant (token mode)

Mint a monitoring token (token mode)

If your server uses --auth-mode token, mint a dedicated token for monitoring and grant it admin access:

swamp access token mint health-monitor --principal user:monitoring
swamp access grant create --subject user:monitoring --allow admin --on "access:*"

Retrieve the token plaintext with the swamp vault get command shown in the mint output.

If your server uses --auth-mode oauth and the monitoring principal is listed in --admins, skip this step — that principal already has admin access.

Query the health snapshot

curl https://swamp.example.com/api/v1/health \
  -H "Authorization: Bearer health-monitor.secret"

The response is a JSON object with instance identity, active runs, throughput metrics, worker status, scheduling, webhooks, and component health.

See REST API — GET /api/v1/health for the full response schema.

Stream health updates

To receive health snapshots as a continuous Server-Sent Events stream:

curl -N https://swamp.example.com/api/v1/health/stream \
  -H "Authorization: Bearer health-monitor.secret"

The stream sends an initial snapshot immediately, then pushes updates every 5 seconds by default.

To change the push interval (in milliseconds, between 1000 and 60000):

curl -N https://swamp.example.com/api/v1/health/stream?interval=10000 \
  -H "Authorization: Bearer health-monitor.secret"

To resume after a disconnect, pass the last received event ID:

curl -N https://swamp.example.com/api/v1/health/stream \
  -H "Authorization: Bearer health-monitor.secret" \
  -H "Last-Event-ID: 42"

Query full run history

The /internal/runs endpoint returns all run records, including completed and failed runs. It is disabled by default.

To enable it, start the server with any of:

swamp serve --enable-internal-api
# swamp-serve.yaml
enable-internal-api: true
export SWAMP_ENABLE_INTERNAL_API=true

Then query it:

curl https://swamp.example.com/internal/runs \
  -H "Authorization: Bearer health-monitor.secret"
← PreviousLoad External Grants at StartupNext →Set Up Extension Trust