Observability

Impri exposes three observability surfaces for self-hosters and operators:

• /metrics — Prometheus text-format endpoint (opt-in)
• /readyz — readiness probe (always available, no auth)
• /healthz — liveness probe (existing, always available)
• GET /v1/usage — per-project usage snapshot (admin scope)
• Structured logging — JSON via pino with request-ID correlation

Prometheus metrics (/metrics)

Enabling

The /metrics endpoint does not exist by default. It is registered only when METRICS_ENABLED=1. Without this env var, any request to /metrics returns 404.

METRICS_ENABLED=1

Protecting access

Option A — bearer token (recommended when /metrics is on the public port):

METRICS_ENABLED=1
METRICS_TOKEN=<random-string>

When METRICS_TOKEN is set, the endpoint requires:

Authorization: Bearer <METRICS_TOKEN>

Requests with a missing or mismatched token receive 401 Unauthorized. The comparison uses constant-time (timingSafeEqual) to prevent timing attacks.

Option B — private port (recommended for bare-metal / VM self-hosters):

Bind a second listener on a non-public interface so the metrics endpoint is never reachable over the internet at all.

METRICS_ENABLED=1
METRICS_HOST=127.0.0.1
METRICS_PORT=9090

With METRICS_PORT set to a different value than PORT, the server starts a separate Fastify instance (metrics-only, no auth preHandler, no CORS) on METRICS_HOST:METRICS_PORT. The main listener on PORT receives no /metrics traffic.

Option C — no token, public port (development only):

METRICS_ENABLED=1 without METRICS_TOKEN is valid but you must restrict access at the network layer: firewall rule, reverse proxy IP allowlist, or METRICS_HOST=127.0.0.1. Never expose an unprotected /metrics to the internet — it leaks operational statistics.

Content type

Content-Type: text/plain; version=0.0.4

Standard Prometheus text exposition format. Prometheus, Grafana Agent, VictoriaMetrics, and any compatible scraper will ingest it without configuration.

Prometheus scrape_config examples

With bearer token:

scrape_configs:
  - job_name: impri
    static_configs:
      - targets: ['your-impri-host:8484']
    authorization:
      type: Bearer
      credentials: <METRICS_TOKEN>

Private port, no token:

scrape_configs:
  - job_name: impri
    static_configs:
      - targets: ['127.0.0.1:9090']

Metric reference

All metrics are prefixed with impri_. Labels never contain raw API keys, webhook secrets, bot tokens, action content, email addresses, callback URLs, or any other user-supplied data — only enum values and route patterns.

Build and runtime

HTTP traffic

The /metrics route itself is excluded from HTTP counters to avoid noise.

Rate limiting

Actions

Watchers

Webhooks

Notification channels

Health and readiness probes

GET /healthz — liveness

Always available. No auth. Never blocks.

Returns 200 OK immediately with {"status":"ok","ts":<unix>}. Use this as your container liveness probe or uptime-check endpoint. Its only question is: "is the process alive?" — it performs no DB check.

curl http://localhost:8484/healthz
# {"status":"ok","ts":1720000000}

GET /readyz — readiness

Always available. No auth. Returns sensitive-free pass/fail only.

Use this as your Kubernetes readiness probe or load-balancer health check. It answers: "is the server ready to serve traffic?" Kubernetes probes cannot carry tokens; the endpoint deliberately returns no sensitive data — only pass/fail per named check.

Checks (in order):

1. db_reachable — SELECT 1 confirms the SQLite file is open and WAL is accessible.
2. schema_applied — verifies the api_keys table exists (confirms migrations ran).
3. db_writable — inserts and immediately deletes a sentinel row in rate_limits within a single transaction (confirms writes are not blocked by disk-full or a read-only mount).
4. redis (advisory, only when REDIS_URL is set) — PING with a 1 s timeout. Failure sets status: 'degraded' in the response but does not cause a 503 — Redis is a non-fatal fallback path.

Success response (HTTP 200):

{
  "status": "ok",
  "checks": {
    "db_reachable": "ok",
    "schema_applied": "ok",
    "db_writable": "ok",
    "redis": "ok"
  },
  "ts": 1720000000
}

Failure response (HTTP 503):

{
  "status": "error",
  "checks": {
    "db_reachable": "ok",
    "schema_applied": "error",
    "db_writable": "skipped"
  },
  "error": "schema_applied: expected table api_keys not found",
  "ts": 1720000000
}

Error messages contain only the check name and a fixed-string reason — never raw SQL, row data, or secrets.

Kubernetes example:

livenessProbe:
  httpGet:
    path: /healthz
    port: 8484
  initialDelaySeconds: 5
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /readyz
    port: 8484
  initialDelaySeconds: 5
  periodSeconds: 10
  failureThreshold: 3

Structured logging

Impri uses pino with JSON output. All logs include level, time, msg, and Fastify's request fields. The logger redacts Authorization and cookie headers in HTTP logs.

Request-ID correlation

Every response includes an X-Request-Id header matching the reqId field in the server log. This lets you correlate a 429 or 403 in an agent's log with the exact server log line:

curl -sI https://api.impri.dev/v1/actions | grep x-request-id
# x-request-id: req-abc123

Search for that ID in your log aggregator to find the full structured log entry.

Background tick logging

All background tick functions (runExpiryTick, runWebhookTick, runWatcherTick, runChannelDigestTick) receive a pino logger instance so their output flows through pino's redaction pipeline. No background output is written to raw stderr.

Structured lifecycle events

Key lifecycle events are logged as structured JSON with the fields listed below. None of these fields ever contain raw API keys, tokens, passwords, callback URLs (which may carry auth in query params), watcher config (which may contain embedded credentials), action content, or email addresses.

Action lifecycle

{ "event": "action.created", "action_id": "act_...", "kind": "email.send",
  "project_id": "proj_...", "key_id": 42, "rule_applied": null, "initial_status": "pending" }

{ "event": "action.decided", "action_id": "act_...", "verdict": "approve",
  "channel": "telegram", "key_id": 42, "latency_ms": 47213 }

{ "event": "action.expired", "action_id": "act_...", "project_id": "proj_..." }

{ "event": "action.result", "action_id": "act_...", "status": "executed" }

Webhook delivery

{ "event": "webhook.delivery", "delivery_id": "wdl_...", "action_id": "act_...",
  "attempt": 2, "result": "retry", "status_code": 503, "duration_ms": 1240 }

{ "event": "webhook.dlq", "delivery_id": "wdl_...", "action_id": "act_...", "attempt": 7 }

callback_url is never logged (may contain tokens in query params).

Watcher runs

{ "event": "watcher.run", "watcher_id": "wat_...", "kind": "rss",
  "result": "ok", "items_fetched": 12, "items_new": 3, "items_published": 3, "duration_ms": 890 }

{ "event": "watcher.degraded", "watcher_id": "wat_...", "kind": "rss", "fail_count": 3 }

{ "event": "watcher.paused", "watcher_id": "wat_...", "kind": "rss" }

Watcher config (which may contain RSS URLs with embedded auth or API keys) is never logged.

Rate limiting

{ "event": "rate_limit_hit", "key_id": 42, "route": "actions:create" }

key_id is the database row ID — not the raw im_... token value.

Notification channels

{ "event": "channel.notification", "channel_id": "ch_...",
  "channel_type": "slack", "result": "ok", "action_id": "act_..." }

{ "event": "channel.auto_disabled", "channel_id": "ch_...",
  "channel_type": "slack", "project_id": "proj_...", "fail_count": 5 }

Channel config (containing bot tokens and webhook URLs) is never logged.

Log levels

Usage endpoint (GET /v1/usage)

Returns a per-project usage snapshot. Useful for building dashboards, quota warnings, or self-service billing pages in your own tooling.

Auth: requires admin scope. Project is derived exclusively from the verified API key — never from a client-supplied parameter.

Rate limit: 60 requests per minute per key.

curl -H "Authorization: Bearer im_..." https://api.impri.dev/v1/usage

Response (HTTP 200):

{
  "project_id": "proj_...",
  "billing_active": false,
  "tier": "free",
  "subscription_status": null,
  "current_period_end": null,

  "period": {
    "start": 1719792000,
    "end":   1722470400
  },

  "actions": {
    "created_this_period": 42,
    "pending":  5,
    "approved": 30,
    "rejected":  4,
    "expired":   3
  },

  "approvals": {
    "used":      34,
    "limit":    100,
    "remaining": 66
  },

  "watchers": {
    "active":    2,
    "degraded":  1,
    "paused":    0,
    "total":     3,
    "limit":     3,
    "remaining": 0
  },

  "limits": {
    "approvals_per_month":      100,
    "watchers":                   3,
    "min_watcher_interval_sec": 900
  },

  "webhook_delivery": {
    "dlq_size":  0,
    "pending":   1,
    "in_retry":  0
  },

  "ts": 1720000000
}

Field notes:

• approvals.limit and watchers.limit are null on unlimited tiers (indie annual, team).
• approvals.remaining and watchers.remaining are null when the limit is null.
• period.start / period.end are Unix seconds for the first second of the current and next UTC calendar months.
• billing_active: false on self-hosted instances without STRIPE_SECRET_KEY — no usage limits are enforced in that case.
• All counts are scoped to the project that owns the API key; no cross-project data is accessible.

Error responses:

Security notes

• /metrics is absent unless METRICS_ENABLED=1. When the token option is not used, restrict at the network layer.
• /readyz is intentionally public. It returns only pass/fail per named check and fixed-string error reasons — never query content, row data, DB paths, or secrets. The write canary uses a sentinel value and is deleted within the same transaction.
• GET /v1/usage enforces admin scope and derives project_id from the verified key only. Returns 403 (not 404) on missing scope.
• All metric labels are enum values or Fastify route patterns — never user-supplied data, URLs, tokens, or action content.
• Pino's redaction pipeline covers all HTTP logs (Authorization, cookie). Background ticks use the same logger instance, so nothing flows to raw stderr unredacted.