> 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-en/sdks/backend-sdk/finger/technical_documentation/api_reference/management/get-the-operational-metrics-snapshot.md). # Get the operational metrics snapshot Returns a cheap JSON snapshot of the service, suitable for frequent scraping: it never processes fingerprints nor runs a health check. The `traffic`, `saturation`, `latency` and `quality` figures are accumulated in memory since the service started; the `usage` counters are the values of the license. | Block | Content | | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `schemaVersion`, `timestamp` | Payload version (`1.0`) and UTC instant of the snapshot | | `service` | `name` (`facephi-finger-service`), `version`, `role`, `pathBase` (`/api/v1/finger`) and `configuredThreads` | | `state` | `initialized`, `license` (`valid`, `statusCode`, `statusMessage`), `engine` (result of the last call to `/health`) and `classification` | | `traffic` | Every request served, management endpoints included: `totals`, `1m`/`5m`/`15m` windows and `byEndpoint` | | `saturation` | `inflight`, `maxInflight1m`, `configuredThreads`, `queueP95Ms1m` and `backlogSuspected` | | `latency` | Total, queue (`queueMs`) and processing (`sdkMs`) latency in milliseconds (`avg`, `p50`, `p95`, `p99`, `max`) per window | | `usage` | License usage counters of the successful fingerprint operations: `enabled`, `operations.extract`, `operations.authenticate` and `total` | | `usageCountersEnabled`, `extractCount`, `authenticateCount`, `totalCount` | The `usage` figures under the 2.1.0 field names | | `quality` | Aggregated quality of the successful fingerprint operations | | `alerts` | Active alerts | `errorRate` counts every `4xx` and `5xx` response, so validation rejections (HTTP `400`) also increase it. A `Negative` authentication is returned with HTTP `200` and never counts as an error nor as a low-quality sample. Alerts: | `code` | `severity` | `message` | Active when | | -------------------- | ---------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LICENSE_EXPIRED` | `critical` | `License is invalid or expired` | The license is not valid | | `ENGINE_UNAVAILABLE` | `critical` | `Fingerprint engine health check failed` | The last call to `/health` failed to check the processing components | | `HIGH_ERROR_RATE` | `warning` | `5m error rate is above the warning threshold` | The 5-minute error rate reaches `metrics_error_rate_warning` | | `SATURATED` | `warning` | `Queue latency and inflight indicate saturation` | `state.classification` is `saturated` | | `LOW_QUALITY` | `warning` | `Recent fingerprint results show degraded quality` | At least 20 extractions carry a quality figure, at least 20% of them had `quality` or `nfiq2` below 50, and the last one of those happened within `metrics_quality_alert_window_seconds` | | `IDLE` | `info` | `Traffic is below the idle threshold` | `state.classification` is `idle` | The classification thresholds (`metrics_*`) are configured in `config.json`, with the `FACEPHI_FINGER_REST_METRICS_*` environment variables or at runtime with `POST /api/v1/finger/config`. It never requires a JWT. ```json {"openapi":"3.0.1","info":{"title":"Facephi Finger Service REST API","version":"2.2.1"},"tags":[{"name":"Management","description":"Version, health, operational metrics and runtime configuration of the service."}],"servers":[{"url":"http://127.0.0.1:6982/"}],"security":[],"paths":{"/api/v1/finger/metrics":{"get":{"summary":"Get the operational metrics snapshot","description":"Returns a cheap JSON snapshot of the service, suitable for frequent scraping: it never processes\nfingerprints nor runs a health check. The `traffic`, `saturation`, `latency` and `quality` figures are\naccumulated in memory since the service started; the `usage` counters are the values of the license.\n\n| Block | Content |\n|---|---|\n| `schemaVersion`, `timestamp` | Payload version (`1.0`) and UTC instant of the snapshot |\n| `service` | `name` (`facephi-finger-service`), `version`, `role`, `pathBase` (`/api/v1/finger`) and `configuredThreads` |\n| `state` | `initialized`, `license` (`valid`, `statusCode`, `statusMessage`), `engine` (result of the last call to `/health`) and `classification` |\n| `traffic` | Every request served, management endpoints included: `totals`, `1m`/`5m`/`15m` windows and `byEndpoint` |\n| `saturation` | `inflight`, `maxInflight1m`, `configuredThreads`, `queueP95Ms1m` and `backlogSuspected` |\n| `latency` | Total, queue (`queueMs`) and processing (`sdkMs`) latency in milliseconds (`avg`, `p50`, `p95`, `p99`, `max`) per window |\n| `usage` | License usage counters of the successful fingerprint operations: `enabled`, `operations.extract`, `operations.authenticate` and `total` |\n| `usageCountersEnabled`, `extractCount`, `authenticateCount`, `totalCount` | The `usage` figures under the 2.1.0 field names |\n| `quality` | Aggregated quality of the successful fingerprint operations |\n| `alerts` | Active alerts |\n\n`errorRate` counts every `4xx` and `5xx` response, so validation rejections (HTTP `400`) also increase it. A\n`Negative` authentication is returned with HTTP `200` and never counts as an error nor as a low-quality sample.\n\nAlerts:\n\n| `code` | `severity` | `message` | Active when |\n|---|---|---|---|\n| `LICENSE_EXPIRED` | `critical` | `License is invalid or expired` | The license is not valid |\n| `ENGINE_UNAVAILABLE` | `critical` | `Fingerprint engine health check failed` | The last call to `/health` failed to check the processing components |\n| `HIGH_ERROR_RATE` | `warning` | `5m error rate is above the warning threshold` | The 5-minute error rate reaches `metrics_error_rate_warning` |\n| `SATURATED` | `warning` | `Queue latency and inflight indicate saturation` | `state.classification` is `saturated` |\n| `LOW_QUALITY` | `warning` | `Recent fingerprint results show degraded quality` | At least 20 extractions carry a quality figure, at least 20% of them had `quality` or `nfiq2` below 50, and the last one of those happened within `metrics_quality_alert_window_seconds` |\n| `IDLE` | `info` | `Traffic is below the idle threshold` | `state.classification` is `idle` |\n\nThe classification thresholds (`metrics_*`) are configured in `config.json`, with the\n`FACEPHI_FINGER_REST_METRICS_*` environment variables or at runtime with `POST /api/v1/finger/config`. It\nnever requires a JWT.\n","operationId":"getMetrics","tags":["Management"],"responses":{"200":{"description":"Operational metrics snapshot.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsResponse"}}}},"400":{"description":"The service is not initialized (`Service not initialized`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestResult"}}}}}}}},"components":{"schemas":{"MetricsResponse":{"type":"object","description":"Operational metrics snapshot. See the operation description for the meaning of each block.","properties":{"schemaVersion":{"type":"string"},"timestamp":{"type":"string","description":"UTC instant of the snapshot (`YYYY-MM-DDTHH:MM:SSZ`)."},"service":{"$ref":"#/components/schemas/MetricsService"},"state":{"$ref":"#/components/schemas/MetricsState"},"traffic":{"$ref":"#/components/schemas/MetricsTraffic"},"saturation":{"$ref":"#/components/schemas/MetricsSaturation"},"latency":{"$ref":"#/components/schemas/MetricsLatency"},"usage":{"$ref":"#/components/schemas/MetricsUsage"},"usageCountersEnabled":{"type":"boolean","description":"Same value as `usage.enabled`, kept for compatibility with 2.1.0."},"extractCount":{"type":"integer","format":"int64","description":"Same value as `usage.operations.extract`, kept for compatibility with 2.1.0."},"authenticateCount":{"type":"integer","format":"int64","description":"Same value as `usage.operations.authenticate`, kept for compatibility with 2.1.0."},"totalCount":{"type":"integer","format":"int64","description":"Same value as `usage.total`, kept for compatibility with 2.1.0."},"quality":{"$ref":"#/components/schemas/MetricsQuality"},"alerts":{"type":"array","description":"Active alerts; empty when there are none.","items":{"$ref":"#/components/schemas/MetricsAlert"}}}},"MetricsService":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"role":{"type":"string","enum":["master","worker"]},"pathBase":{"type":"string"},"configuredThreads":{"type":"integer","description":"Configured worker threads (`number_of_threads`)."}}},"MetricsState":{"type":"object","properties":{"initialized":{"type":"boolean"},"license":{"$ref":"#/components/schemas/LicenseStatus"},"engine":{"$ref":"#/components/schemas/MetricsEngineState"},"classification":{"type":"string","description":"Single-value summary of the snapshot. The cases are evaluated in this order and the first one that\nmatches applies:\n\n| Value | When |\n|---|---|\n| `unhealthy` | The service is not initialized, the license is not valid, or the last health check failed |\n| `unknown` | There is no traffic yet, no health check has run and there is no quality alert |\n| `saturated` | There is traffic and either `saturation.backlogSuspected` is `true`, or in-flight requests exceed `metrics_saturation_min_inflight_ratio` times the configured threads while the 1-minute queue p95 reaches `metrics_saturation_queue_p95_ms` |\n| `degraded` | The 5-minute error rate (`4xx` and `5xx`) reaches `metrics_error_rate_warning`, there has been at least one server error (`5xx`) since startup, or the `LOW_QUALITY` alert is active |\n| `idle` | There is traffic, the 15-minute request rate is below `metrics_idle_rps_threshold` and no backlog is suspected |\n| `ok` | None of the above |\n","enum":["ok","idle","degraded","saturated","unhealthy","unknown"]}}},"LicenseStatus":{"type":"object","description":"Status of the service license.","properties":{"valid":{"type":"boolean","description":"Whether the service currently holds a valid license. This is the field to check."},"statusCode":{"type":"string","description":"Status code reported by the licensing layer, for example `LA_OK`, `LF_OK`, `OK` or an error code."},"statusMessage":{"type":"string","description":"Human-readable description of `statusCode`. `The license is valid.` when the license is valid."}},"required":["valid","statusCode","statusMessage"]},"MetricsEngineState":{"type":"object","description":"Result of the last call to `GET /api/v1/finger/health`. `/metrics` never runs a health check itself.","properties":{"role":{"type":"string"},"servicesConfigured":{"type":"array","items":{"type":"string"}},"healthy":{"type":"boolean"},"lastHealthKnown":{"type":"boolean"},"lastHealthCheckAt":{"type":"string"},"lastError":{"type":"string"}}},"MetricsTraffic":{"type":"object","description":"Every request served since startup, management endpoints included.","properties":{"totals":{"$ref":"#/components/schemas/TrafficCounters"},"windows":{"type":"object","properties":{"1m":{"$ref":"#/components/schemas/TrafficWindow"},"5m":{"$ref":"#/components/schemas/TrafficWindow"},"15m":{"$ref":"#/components/schemas/TrafficWindow"}}},"byEndpoint":{"type":"array","description":"One entry per endpoint that has already received requests.","items":{"$ref":"#/components/schemas/TrafficEndpoint"}}}},"TrafficCounters":{"type":"object","properties":{"requests":{"type":"integer","format":"int64"},"success":{"type":"integer","format":"int64"},"clientErrors":{"type":"integer","format":"int64"},"serverErrors":{"type":"integer","format":"int64"},"unauthorized":{"type":"integer","format":"int64"}}},"TrafficWindow":{"type":"object","properties":{"requests":{"type":"integer","format":"int64"},"rps":{"type":"number","format":"double"},"successRate":{"type":"number","format":"double"},"errorRate":{"type":"number","format":"double","description":"Ratio of `4xx` and `5xx` responses in the window."}}},"TrafficEndpoint":{"allOf":[{"type":"object","properties":{"method":{"type":"string"},"path":{"type":"string"}}},{"$ref":"#/components/schemas/TrafficCounters"}]},"MetricsSaturation":{"type":"object","properties":{"inflight":{"type":"integer","format":"int64"},"maxInflight1m":{"type":"integer","format":"int64"},"configuredThreads":{"type":"integer","format":"int64"},"queueP95Ms1m":{"type":"integer","format":"int64"},"backlogSuspected":{"type":"boolean"}}},"MetricsLatency":{"type":"object","properties":{"scope":{"type":"string"},"windows":{"type":"object","properties":{"1m":{"$ref":"#/components/schemas/LatencyWindow"},"5m":{"$ref":"#/components/schemas/LatencyWindow"},"15m":{"$ref":"#/components/schemas/LatencyWindow"}}}}},"LatencyWindow":{"type":"object","properties":{"totalMs":{"$ref":"#/components/schemas/LatencyStats"},"queueMs":{"$ref":"#/components/schemas/LatencyStats"},"sdkMs":{"$ref":"#/components/schemas/LatencyStats"}}},"LatencyStats":{"type":"object","properties":{"avg":{"type":"integer","format":"int64"},"p50":{"type":"integer","format":"int64"},"p95":{"type":"integer","format":"int64"},"p99":{"type":"integer","format":"int64"},"max":{"type":"integer","format":"int64"}}},"MetricsUsage":{"type":"object","description":"Usage counters of the license for the fingerprint operations completed successfully. They are the values\naccumulated by the license, including the increments of this instance that are still pending\nsynchronization, so they are not reset when the service restarts.\n","properties":{"enabled":{"type":"boolean","description":"Whether the license enables usage counters. When `false`, the counters stay at `0`."},"operations":{"type":"object","properties":{"extract":{"type":"integer","format":"int64"},"authenticate":{"type":"integer","format":"int64"}}},"total":{"type":"integer","format":"int64","description":"`operations.extract` + `operations.authenticate`."}}},"MetricsQuality":{"type":"object","description":"Quality figures aggregated since startup from the successful fingerprint operations. It is an empty object\nuntil the first successful operation. `extract` appears with the first successful extraction, `authenticate`\nwith the first successful authentication, and `summary` as soon as the block is not empty.\n","properties":{"extract":{"type":"object","properties":{"samples":{"type":"integer","format":"int64","description":"Successful extractions."},"measuredSamples":{"type":"integer","format":"int64","description":"Extractions that returned `quality` or `qualityDetails.nfiq2`."},"overallQuality":{"$ref":"#/components/schemas/NumericSummary"},"nfiq2":{"$ref":"#/components/schemas/NumericSummary"}}},"authenticate":{"type":"object","properties":{"samples":{"type":"integer","format":"int64","description":"Successful authentications."},"positive":{"type":"integer","format":"int64"},"negative":{"type":"integer","format":"int64"},"similarity":{"$ref":"#/components/schemas/NumericSummary"}}},"summary":{"type":"object","properties":{"lowQualitySamples":{"type":"integer","format":"int64","description":"Extractions whose `quality` or `qualityDetails.nfiq2` was below 50."},"lowQualitySince":{"type":"string","description":"UTC instant of the first low-quality extraction since startup; only present once there is one."}}}}},"NumericSummary":{"type":"object","properties":{"samples":{"type":"integer","format":"int64"},"avg":{"type":"number","format":"double"},"min":{"type":"number","format":"double"},"max":{"type":"number","format":"double"}}},"MetricsAlert":{"type":"object","properties":{"code":{"type":"string","enum":["LICENSE_EXPIRED","ENGINE_UNAVAILABLE","HIGH_ERROR_RATE","SATURATED","LOW_QUALITY","IDLE"]},"severity":{"type":"string","enum":["critical","warning","info"]},"message":{"type":"string"},"since":{"type":"string","description":"UTC instant (`YYYY-MM-DDTHH:MM:SSZ`). For `ENGINE_UNAVAILABLE` it is the instant of the failed health\ncheck, for `LOW_QUALITY` the start of the current low-quality episode, and for the other alerts the instant\nof the snapshot.\n"}}},"BadRequestResult":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"},"timeStamp":{"$ref":"#/components/schemas/TimeStamp"}},"required":["status","error","message","timeStamp"]},"TimeStamp":{"type":"string","description":"UTC date and time in ISO-8601 format with second precision (`YYYY-MM-DDTHH:MM:SSZ`)."}}}} ```