|# Telemetry
|
|**Telemetry** is the set of aggregated numbers that describe how a running OBP-API instance is behaving: how many requests it serves and how long they take, how often its caches answer without recomputing, how full its queues and connection pools are, how much memory it uses and how many threads it runs. Operators use it to see trouble building up (a heap filling, a queue backing up, a cache that has stopped hitting) and to find its cause once something has gone wrong.
|
|## Telemetry is not API Metrics
|
|OBP already uses the word "metrics" for two kinds of per-call record. Telemetry is a different thing and deliberately has a different name:
|
|| | What it is | Where it lives | Carries identities? |
||---|---|---|---|
|| **API Metrics** | one record per API call: who called what, when, and how long it took | the OBP database, read through the metrics endpoints | yes: consumer and user |
|| **Connector Metrics** | one record per call from OBP-API to the Connector | the OBP database, read through the connector metrics endpoint | per call |
|| **Telemetry** | aggregated numbers about the running instance: counts, rates, durations, sizes, current levels | collected from each instance by a monitoring system such as Prometheus and viewed in a tool such as Grafana; never stored in the OBP database | never |
|
|API Metrics answer "who used the API, and how". Telemetry answers "is this instance healthy, and if not, why not". Because Telemetry never records who made a call, it can be collected on every request without writing to the database.
|
|## What Telemetry measures
|
|Telemetry uses four types of measurement:
|
|- **Counters** count how often something happened, for example cache hits and cache misses.
|- **Gauges** report a current level, for example the depth of a queue or the number of live threads.
|- **Distribution summaries** describe how large something is and how widely that varies, for example the size of response bodies or the number of items in a returned list.
|- **Timers** describe how long something takes, for example the duration of an endpoint or a Connector call.
|
|It covers each endpoint (request rate, errors and duration), each Connector method, the caches, Redis, the database connection pool, the log dispatch queue, and the Java virtual machine itself (memory, garbage collection, threads).
|
|## Naming
|
|OBP-API's own Telemetry series start with `obp_api_`, for example `obp_api_cache_gets_total` with a `cache` label naming the cache and a `result` label of `hit` or `miss`. Other Open Bank Project products use their own prefixes. Standard series from the Java virtual machine and the database connection pool keep their usual names (`jvm_*`, `hikaricp_*`), so that standard dashboards work with them.
|
|Telemetry labels only ever take values from small, fixed sets (an operation id, an API version, a status class, a cache name). They never contain a user id, consumer id, consent id, account id or any other identifier of a person or a record.
|
|## Which instance is reporting
|
|Each running OBP-API process has its own `api_instance_id`, the same id that appears on every API Metrics record it writes. Telemetry reports it alongside the build commit, so figures from one instance can be matched with that instance's API Metrics.
|
|## Reading Telemetry
|
|- **Prometheus** collects Telemetry from a separate port of each OBP-API instance, at the path `/telemetry`, in the Prometheus text format. Reading each instance directly keeps figures from different instances apart, and the port keeps answering when the API itself is overloaded. On this instance the port is not open.
|- **People** can read the same figures with `GET /obp/v7.0.0/management/telemetry`, which requires the Role CanGetTelemetry. Its response names the instance that answered.
|
|See also: [API Metrics](http://localhost:5174/glossary#API-Metrics), [Connector Metrics](http://localhost:5174/glossary#Connector-Metrics), [Rate Limiting](http://localhost:5174/glossary#Rate-Limiting), [Connector](http://localhost:5174/glossary#Connector), [Resource Doc](http://localhost:5174/glossary#Resource-Doc).
|