Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Monitoring

birdd run serves a read-only operational API on 127.0.0.1:8786 by default. It has no HTTP authentication and must remain on loopback or behind a trusted local operator portal.

Health

curl http://127.0.0.1:8786/health

A healthy response is HTTP 200 and confirms that the process can query SQLite. Database failure returns HTTP 503. Health does not prove that relays are reachable or federation is current.

The adapter processes have separate health endpoints:

  • birdd serve: http://127.0.0.1:8787/health
  • birdd-signal: http://127.0.0.1:8789/health

The Signal endpoint returns HTTP 503 while its signal-cli event stream is disconnected. The generic adapter endpoint only confirms that its HTTP server is running.

Metrics

Prometheus metrics are available from:

curl http://127.0.0.1:8786/metrics
curl http://127.0.0.1:8789/metrics

Useful signals include:

  • Process and database availability
  • Local and remote observation totals
  • Synchronization successes, failures, and last-success time
  • Per-relay connect, fetch, and publish state
  • Federation gaps and conflicts
  • Delayed, due, wrapped, published, and suppressed restricted deliveries
  • Signal stream, command, response, and attachment failures

Runtime counters reset when a process restarts. Database-backed observation and federation gauges persist.

Federation status

Use the CLI when you need the complete stream and recipient view:

birdd --config birdd.toml federation-status
birdd --config birdd.toml federation-status --json

Pay attention to increasing gaps or conflicts, stale sync-success timestamps, all relays becoming unreachable, and growing due or wrapped delivery queues.

Admin API

The loopback API also exposes:

/admin/v1/overview
/admin/v1/federation
/admin/v1/trust
/admin/v1/extensions
/admin/v1/config

The configuration response is redacted, but the API should still be treated as operator-only. birdd-admin-web provides a UI for these endpoints when deployed behind an authenticated reverse proxy.

Logs and telemetry

Logs are structured JSON. Set RUST_LOG to adjust filtering:

RUST_LOG=birdd=debug birdd --config birdd.toml run

OpenTelemetry export is enabled when an OTEL_EXPORTER_OTLP_*_ENDPOINT environment variable is present. NixOS operators can inspect services with systemctl status and journalctl.