API Metrics

			 |# API Metrics
			 |
			 |**API Metrics** are OBP-API's record of the calls made to it: one record for every API call, saying who made the call, which endpoint it reached, when, how long it took and what status it returned. They are used to see how the API is being used (which endpoints, which Consumers, which Users), to follow up a particular call, and to review the calls made by a Consumer or by an agent acting under a Consent.
			 |
			 |On this instance, API Metrics are being recorded.
			 |
			 |## What each record contains
			 |
			 |- the date and time of the call, and its duration in milliseconds
			 |- the URL, the HTTP verb and the HTTP status code returned
			 |- the endpoint that handled the call and the API version it is implemented in
			 |- the User (user id and username) and the Consumer (consumer id, application name and developer email)
			 |- how the caller authenticated (for example DirectLogin, OAuth2, Consent or Anonymous) and, for a call made under a Consent, the Consent reference id
			 |- the correlation id, which is also returned to the caller in the `Correlation-Id` response header and is shared by every Connector call made while serving the call (see [Connector Metrics](http://localhost:5174/glossary#Connector-Metrics))
			 |- `source_ip`: the address of the client, as OBP-API decided it (see [Client IP Address](http://localhost:5174/glossary#Client-IP-Address)). Records written before this was introduced hold the raw `X-Forwarded-For` header instead
			 |- `forwarded_for`: the hops the call passed through: the `X-Forwarded-For` list it arrived with, followed by the address of the machine that connected to OBP-API. Entries to the left of the first address OBP-API does not trust may have been written by the caller, so read them as a claim, not a fact
			 |- `target_ip`: the `X-Forwarded-Host` request header, as sent
			 |- `domain_api_url`: for a call made under a [Domain API](http://localhost:5174/glossary#Domain-APIs), the path and query string the caller used, such as `/carbon-registry/v1/activity?limit=10`; the URL above is then the OBP URL the call was served at. Absent for every other call. A Domain API's base paths never overlap, so the calls through one Domain API are those whose `domain_api_url` starts with its base path.
			 |- the `api_instance_id` of the OBP-API instance that served the call
			 |- the response body, for selected endpoints only
			 |
			 |## How long records are kept
			 |
			 |Records are written to the database in batches. On this instance, records stay in the live metrics table for 90 days, are then moved to the metrics archive, and are deleted from the archive after 1095 days.
			 |
			 |## Reading API Metrics
			 |
			 |- `GET /management/metrics`: search the records, filtered by date, User, Consumer, endpoint, verb, status and more. Requires the Role CanReadMetrics.
			 |- `GET /management/aggregate-metrics`: counts and durations over a filtered set of records. Requires the Role CanReadAggregateMetrics.
			 |- `GET /management/metrics/top-apis`, `/top-consumers` and `/top-users`: the most used endpoints, the most active Consumers and the most active Users. Require the Role CanReadMetrics.
			 |- `GET /management/metrics/banks/BANK_ID`: the records for calls about one bank. Requires the Role CanGetMetricsAtOneBank at that bank.
			 |- `GET /my/metrics`: the calling User's own calls, together with the calls made by agents under Consents that User granted. No Role is required.
			 |- `GET /management/system/diagnostics/metrics`: the state of the metrics table and its archive. Requires the Role CanGetMetricsDiagnostics.
			 |
			 |## API Metrics are not Telemetry
			 |
			 |API Metrics record individual calls and who made them. [Telemetry](http://localhost:5174/glossary#Telemetry) is aggregated numbers about how an instance is behaving (request rates, durations, cache hit ratios, memory, threads) and never records who made a call. Use API Metrics to answer "who called what"; use Telemetry to answer "is this instance healthy".
			 |
			 |See also: [Connector Metrics](http://localhost:5174/glossary#Connector-Metrics), [Telemetry](http://localhost:5174/glossary#Telemetry), [Rate Limiting](http://localhost:5174/glossary#Rate-Limiting), [Consent](http://localhost:5174/glossary#Consent).
			 |