Monitoring PrintStash with Prometheus and Grafana

PrintStash exposes Prometheus metrics at /metrics on the API service. Add it to an existing monitoring stack when you want trends and alerts outside the application.

What /metrics gives you

The endpoint exports four useful metric families:

• printstash_http_request_duration_seconds records latency by method, route template, and status. Route templates keep model IDs from creating unbounded labels.
• printstash_ingestion_jobs_total counts completed and failed ingestion jobs.
• printstash_printer_status counts configured printers by provider and coarse state at scrape time.
• printstash_app_info reports build information.

The metrics are process-local and match the normal single-process deployment. Do not add multiple Uvicorn workers and expect the counters to aggregate automatically.

Add the scrape job

For an API reachable as printstash-api:8000:

scrape_configs:
  - job_name: printstash
    static_configs:
      - targets: ["printstash-api:8000"]

The endpoint is open by default. Set VAULT_METRICS_TOKEN if the monitoring network is not fully trusted, restart the API, and add the same token to Prometheus:

scrape_configs:
  - job_name: printstash
    authorization:
      type: Bearer
      credentials: "<metrics-token>"
    static_configs:
      - targets: ["printstash-api:8000"]

Use a Docker service name when Prometheus shares the network. Use a LAN address only if the API port is intentionally reachable from the Prometheus host.

Alerts worth starting with

• No successful scrape for five minutes.
• A sustained increase in failed ingestion jobs.
• A printer that remains offline outside a maintenance window.
• A high percentile of API latency over a useful period, not one slow request.

Printer alerts from Prometheus are independent of PrintStash notification channels. Use whichever system already handles routing, silences, and on-call noise in your homelab.

The health endpoint is the other half

/api/v1/health is a minimal liveness probe (name, version, status). Use /api/v1/health/details for the operational probe: database, storage, backup, printer-provider, ingestion, and shared-library health.

Optional integrations degrade gracefully. For example, an unavailable Spoolman connection is visible but does not make the whole service unhealthy.

Point Uptime Kuma or a load balancer at health. Point Prometheus at metrics. Use the application audit log when you need to know who changed state rather than how the service behaved over time.

Application-level print alerts are configured separately in the notification guide. If Prometheus reaches PrintStash across network boundaries, review the trusted-network model before exposing the API port.