Scanner performance API

GET /api/v1/scanner/performance provides a tenant-scoped, UI-consumable read model over durable Scanner records. It does not expose Prometheus samples to the browser and does not synthesize values for metrics Scanner cannot derive.

Authorization and tenancy

• Required policy: scanner.operations.read, satisfied by canonical scanner:read or the legacy escape-hatch scanner.admin.
• A validated tenant context is required. There is no default-tenant fallback.
• Supported window values are 1h, 6h, 24h, 7d, and 30d; the default is 24h.

Response

{
  "tenantId": "62ebf136-e558-4772-b397-785a0e735dcb",
  "window": "6h",
  "from": "2026-07-16T13:00:00Z",
  "until": "2026-07-16T19:00:00Z",
  "observedAt": "2026-07-16T19:00:00Z",
  "metrics": {
    "queueDepth": {
      "value": 4,
      "source": "scanner.scan_runtime_state:Pending"
    },
    "scanDurationMs": {
      "sampleCount": 20,
      "p50": 1250,
      "p95": 4900,
      "source": "scanner.scan_metrics:non-replay"
    }
  },
  "omittedMetrics": [
    {
      "metric": "failureRate",
      "reason": "no immutable terminal outcome timestamp is recorded"
    }
  ]
}

The fields have deliberately narrow meanings:

• queueDepth is the current count of tenant rows whose durable runtime status is exactly Pending. It is not Redis stream length and is not windowed. A zero is a real count, not a missing-value fallback.
• scanDurationMs is calculated from scanner.scan_metrics.total_duration_ms for non-replay scans whose started_at falls in [from, until). sampleCount records the percentile population.
• scanDurationMs is absent when the selected window has no recorded samples. It is also absent for compatibility tenants whose identifier cannot address the UUID-keyed metrics store. omittedMetrics states the reason.
• failureRate is absent. scanner.scan_runtime_state.updated_at can change when replay, entropy, or digest data is attached after terminal execution, so it is not an immutable completion timestamp and cannot support an honest windowed failure rate.

An unsupported window returns 400. Authentication or scanner:read/legacy scanner.admin authorization failures return 401 or 403.

Future extension rule

Add a metric only after Scanner durably records the required source fields and a derivation test proves the window, tenant, replay, and missing-data behavior. Do not zero-fill an unavailable metric.