Operating the verifier

For platform and ops engineers. At the end of this page, Prometheus scrapes your verifier, alerts fire on the conditions that need you, and you know what each readiness state means and how to fix it.

Before you start

• A running verifier. See Deploying the verifier.
• A network path from your probes and Prometheus to the verifier’s port 9090 that stays inside your private network.

The monitor port

Port 9090 is the monitor port. It is read-only: every endpoint is GET, nothing on it changes the verifier, and any other path answers 404.

The monitor port listens on 127.0.0.1:9090 by default, so only the verifier’s own host reaches it. When probes or Prometheus connect from another host, pod or container, set TRUSTPIN_MONITOR_LISTEN_ADDR=:9090 together with TRUSTPIN_MONITOR_API_KEY. The console’s deployment bundle already does this for Docker Compose and Kubernetes. Never route the monitor port through your public gateway or an Ingress.

Calling it with the key

TRUSTPIN_MONITOR_API_KEY (at least 16 characters, from attest-verifier keygen --secret) is accepted in two forms:

# HTTP Basic: any user name, the key as the password
curl -s -u monitor:"$TRUSTPIN_MONITOR_API_KEY" http://localhost:9090/readyz
 
# Bearer token
curl -s -H "Authorization: Bearer $TRUSTPIN_MONITOR_API_KEY" http://localhost:9090/metrics

With the key set, a request without it gets:

Without TRUSTPIN_MONITOR_API_KEY, every endpoint answers anyone who can reach the port.

Readiness

GET /readyz answers 200 for ok and degraded, and 503 for unavailable. Point your orchestrator’s readiness probe at it, and its liveness probe at /healthz.

{
  "status": "ok",
  "checks": {
    "policy": { "status": "ok", "version": 5, "source": "cdn", "lastRefreshAt": "2026-10-21T08:00:00Z", "lastRefreshResult": "unchanged" },
    "signingKeys": { "status": "ok", "ephemeral": false, "count": 1 },
    "revocationList": { "status": "ok", "source": "download", "ageHours": 3 },
    "store": { "status": "ok" },
    "playIntegrity": { "status": "ok" },
    "debugTokens": { "status": "disabled" }
  }
}

A check’s reason is a fixed text. The details, which can name hosts or users, are only in the verifier’s log.

unavailable (503): the instance must not receive traffic.

degraded (200): the instance serves traffic but needs attention. Alert on it.

Metrics

GET /metrics serves the Prometheus text format. Every series is prefixed trustpin_attest_, and labels carry no device or key ids. endpoint is always the route, such as /v1/attest.

The Go runtime and process metrics are served too.

Scraping

Download prometheus.yml. It has two jobs:

• A fixed address, such as a Docker Compose service:

  scrape_configs:
    - job_name: attest-verifier
      static_configs:
        - targets: ["verifier:9090"]
      basic_auth:
        username: prometheus
        password_file: /etc/prometheus/monitor-api-key   # holds TRUSTPIN_MONITOR_API_KEY

• Kubernetes pods, found through the prometheus.io/scrape, prometheus.io/port and prometheus.io/path annotations that the console’s deployment bundle puts on the verifier pods. Mount the key from the verifier’s Secret into Prometheus.

Prometheus sends the key as its basic-auth password; the user name is ignored.

Alerts and dashboard

alerts.yml holds Prometheus alerting rules. Add it to rule_files:

dashboard.json is a Grafana dashboard that charts every metric: the policy version and age, attestations and tokens by platform, result and reason, challenges, HTTP traffic and latency, the store, and upstreams. In Grafana, open Dashboards, choose New, then Import, upload the file, and pick your Prometheus data source. The instance variable selects one verifier or all of them.

These files may be copied and modified freely, under the verifier licence’s Code Samples clause.

Logs

The verifier writes one JSON line per request (TRUSTPIN_LOG_FORMAT=json, the default) with event, platform, app, result, reasons, pv, upstream, latency_ms, request_id and sub_prefix. Tokens, key certificates, client data, evidence, challenges and secrets are never logged at any level.

Every response echoes X-Request-ID: your gateway’s value when it is at most 128 printable characters, a generated one otherwise. Use it to match the gateway’s log lines with the verifier’s.

Troubleshooting

Next steps

• Verifier API reference
• Rolling out: monitor to enforce
• Deploying the verifier