> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-pt-br/sdks/backend-sdk/backend1n/technical_documentation/api_reference/management/metrics.md).

# /metrics

Returns a JSON snapshot with the traffic, latency, saturation, cached SDK health and aggregated quality signals of the service. It is intended for a Prometheus or an operator to query every few seconds: it is built only from state that is already in memory and performs no active check against the SDK or the database. The endpoint also returns `200` when the service could not initialize the SDK. In that case it does not fail, but reports it in the snapshot itself with `state.initialized` set to false, `state.classification` equal to `unhealthy` and an `SDK_UNAVAILABLE` alert in `alerts` - which is precisely the diagnosis the endpoint is for.

```json
{"openapi":"3.0.1","info":{"title":"Backend1n-Service REST API","version":"5.0.0"},"servers":[{"url":"http://127.0.0.1:6982/"}],"security":[],"paths":{"/metrics":{"get":{"description":"Returns a JSON snapshot with the traffic, latency, saturation, cached SDK health and aggregated quality signals of the service. It is intended for a Prometheus or an operator to query every few seconds: it is built only from state that is already in memory and performs no active check against the SDK or the database. The endpoint also returns `200` when the service could not initialize the SDK. In that case it does not fail, but reports it in the snapshot itself with `state.initialized` set to false, `state.classification` equal to `unhealthy` and an `SDK_UNAVAILABLE` alert in `alerts` - which is precisely the diagnosis the endpoint is for.\n","tags":["Management"],"responses":{"200":{"description":"Current snapshot of operational metrics.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OperationalMetricsResponse"}}}},"500":{"description":"An error occurred while building the snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExceptionResult"}}}}}}}},"components":{"schemas":{"OperationalMetricsResponse":{"type":"object","description":"Operational snapshot of the service. It is built solely from state that is already in memory - it does not query the SDK or the database -, so it can be queried every few seconds without penalizing the service. The `traffic`, `saturation` and `latency` blocks are collected by the REST manager; `service`, `state`, `usage`, `quality` and `alerts` are added by Backend1N Service.\n","properties":{"schemaVersion":{"type":"string","description":"Version of this snapshot's contract."},"timestamp":{"$ref":"#/components/schemas/TimeStamp"},"service":{"type":"object","additionalProperties":true,"description":"Identity of the service - `name`, `version`, `pathBase`, `uptimeSeconds` and `configuredThreads`."},"state":{"$ref":"#/components/schemas/MetricsState"},"traffic":{"type":"object","additionalProperties":true,"description":"Cumulative totals (`requests`, `success`, `clientErrors`, `serverErrors`, `unauthorized`; disjoint categories that add up to `requests`), windows of `1m`, `5m` and `15m` with `requests`, `rps`, `successRate` and `errorRate`, and the `byEndpoint` breakdown with the same counters per registered route. Routes are published as a template with the parameters named `{uuid}` (`/faces/{uuid}`, `/assets/media/{uuid}`) and `{collectionId}`.\n"},"saturation":{"type":"object","additionalProperties":true,"description":"`inflight`, `maxInflight1m`, `configuredThreads`, `queueP95Ms1m` and `backlogSuspected`."},"latency":{"type":"object","additionalProperties":true,"description":"Latency in milliseconds per window (`1m`, `5m`, `15m`), split into `totalMs`, `queueMs` (time in queue) and `sdkMs` (time inside the SDK). Each one publishes `avg`, `p50`, `p95`, `p99` and `max`. The percentiles are approximate (computed by intervals), so they may coincide with the interval edge and end up above the observed maximum when there are few samples.\n"},"usage":{"type":"object","additionalProperties":true,"description":"Request counters per business operation in `operations`, keyed as `METHOD /path`. The management routes (`/health`, `/version`, `/config`, `/metrics` and `/metrics/prometheus`) are excluded.\n"},"quality":{"type":"object","additionalProperties":true,"description":"Aggregated signals for `extraction`, `search` and `database`, plus `lastFailure` with the code and the time of the last failed operation (empty object while none has failed). It only contains aggregates: no biometric template, image, identifier or personal data is stored. The score summaries (`faceConfidence`, `imageQuality`, `bestSimilarity`) publish `count`, `min`, `max`, `avg`, `p50` and `p95`.\n"},"alerts":{"type":"array","description":"Actionable alerts. Empty list when there is nothing to report.","items":{"$ref":"#/components/schemas/MetricsAlert"}}}},"TimeStamp":{"type":"string","description":"A date/time value (UTC) in \"%Y-%m-%dT%H:%M:%SZ\" format."},"MetricsState":{"type":"object","description":"Service state summarized from the snapshot.","properties":{"initialized":{"type":"boolean","description":"Whether the SDK started correctly when the service started."},"classification":{"$ref":"#/components/schemas/MetricsClassification"},"sdk":{"$ref":"#/components/schemas/MetricsSdkState"}}},"MetricsClassification":{"type":"string","description":"Summary of the operational state of the service, derived solely from the published snapshot. The rules are evaluated in this order and the first one that is met wins: `unhealthy` (the SDK did not start or the last known health check is negative), `saturated`, `degraded`, `unknown` (no request has been served yet and health has not been checked), `idle` and `ok`. The numeric thresholds are the `metrics_*` parameters described in the installation manual.\n","enum":["ok","degraded","saturated","idle","unhealthy","unknown"]},"MetricsSdkState":{"type":"object","description":"Last known health snapshot of the SDK. The values are published from that cached snapshot and never from an active check, so that the endpoint remains cheap to query on every scrape.\n","properties":{"initialized":{"type":"boolean"},"alive":{"type":"boolean"},"healthy":{"type":"boolean"},"lastInitStatus":{"type":"string","description":"Status returned by the SDK when the service started."},"lastHealthKnown":{"type":"boolean","description":"If false, no health check has been recorded yet."},"lastHealthCheckAt":{"$ref":"#/components/schemas/TimeStamp"},"lastError":{"type":"string","description":"Reason for the last unhealthy state. Empty string when there is none."}}},"MetricsAlert":{"type":"object","description":"Actionable alert derived from the snapshot.","properties":{"code":{"type":"string","description":"Alert identifier.","enum":["SDK_UNAVAILABLE","HIGH_ERROR_RATE","SATURATED","BACKEND1N_OPERATION_FAILED","IDLE"]},"severity":{"type":"string","description":"Severity of the alert.","enum":["critical","warning","info"]},"message":{"type":"string","description":"Human-readable description of the reason for the alert."},"since":{"$ref":"#/components/schemas/TimeStamp"}}},"ExceptionResult":{"type":"object","description":"An error occurred while calling the backend services.","properties":{"status":{"type":"number"},"error":{"type":"string"},"exception":{"type":"string","description":"Specific description of the reason for the exception (internal service text; it is not part of the contract)."},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}}}}}}
```
