# Metrics reference (Plus)

> **CocoIndex v1.** This page documents CocoIndex **v1** — a ground-up redesign from v0. When writing code, ignore any v0 flow-builder DSL or deprecated decorators.
>
> Source: https://plus.cocoindex.io/docs/advanced_topics/metrics_reference/ · Docs index: https://plus.cocoindex.io/docs/llms.txt · Agent skill: https://plus.cocoindex.io/docs/skill.md
>
> v0→v1 quick map — if you reach for these v0 symbols, stop and use the v1 form: `@cocoindex.flow_def`/`FlowBuilder` → `coco.App` + a `@coco.fn` main function; `add_collector()`/`collect()`/`export()` → declare target states (`declare_row`, `declare_file`); `cocoindex.sources/functions/targets.*` → connector APIs (`localfs.walk_dir`, `coco.ops.*`, `postgres.declare_table_target`). Full mapping + API reference: https://plus.cocoindex.io/docs/skill.md.

Every metric CocoIndex Plus exports, as the engine names it and as a Prometheus-compatible
store renders it after the OpenTelemetry translation (dots become underscores, counters gain
`_total`, time units become `_seconds`). Histograms additionally produce `_bucket`, `_sum` and
`_count` series. All metrics carry the `env` and `app` labels. See the
[Observability](/docs/advanced_topics/observability/) guide for configuration and the reference dashboard.

## Catalog

| OpenTelemetry name | Prometheus name | Kind | Unit | Labels | Description |
|---|---|---|---|---|---|
| `cocoindex.runs` | `cocoindex_runs_total` | counter | `{run}` | `env`, `app`, `mode`, `full_reprocess`, `status` | Updates that finished, by mode and status. |
| `cocoindex.run.time_to_ready` | `cocoindex_run_time_to_ready_seconds` | histogram | `s` | `env`, `app`, `mode` | Time from the start of an update until initial processing caught up. |
| `cocoindex.run.duration` | `cocoindex_run_duration_seconds` | histogram | `s` | `env`, `app`, `mode`, `status` | Time from the start of an update until it terminated. |
| `cocoindex.run.last_ready_time` | `cocoindex_run_last_ready_time_seconds` | observable gauge | `s` | `env`, `app` | Unix time at which the last update of the app reached ready. |
| `cocoindex.component.starts` | `cocoindex_component_starts_total` | counter | `{run}` | `env`, `app`, `stats_group`, `processor` | Component runs started. Minus finished runs gives runs in progress. |
| `cocoindex.component.runs` | `cocoindex_component_runs_total` | counter | `{run}` | `env`, `app`, `stats_group`, `processor`, `mount_kind`, `ownership`, `outcome` | Component runs finished, by outcome (unchanged, added, reprocessed, deleted, error). |
| `cocoindex.component.process.duration` | `cocoindex_component_process_duration_seconds` | histogram | `s` | `env`, `app`, `stats_group`, `processor` | Wall time of the processor body (user code). |
| `cocoindex.component.submit.duration` | `cocoindex_component_submit_duration_seconds` | histogram | `s` | `env`, `app`, `stats_group`, `processor`, `phase` | Wall time of each submit phase: precommit, sink_apply, commit. |
| `cocoindex.component.memo.decisions` | `cocoindex_component_memo_decisions_total` | counter | `{decision}` | `env`, `app`, `stats_group`, `processor`, `decision` | Why each component run was reused or rebuilt. |
| `cocoindex.admission.available` | `cocoindex_admission_available` | observable gauge | `{token}` | `env`, `app` | In-flight tokens (max_inflight_components) not held by any run. |
| `cocoindex.admission.waits` | `cocoindex_admission_waits_total` | counter | `{wait}` | `env`, `app` | Component runs that took an in-flight token from a bounded pool; the wait duration histogram says how long each waited. |
| `cocoindex.admission.wait.duration` | `cocoindex_admission_wait_duration_seconds` | histogram | `s` | `env`, `app` | Time component runs waited for an in-flight token. |
| `cocoindex.target.reconciles` | `cocoindex_target_reconciles_total` | counter | `{state}` | `env`, `app`, `provider`, `container`, `result` | Target states reconciled, by result (created, updated, deleted, unchanged, unchanged_skipped). |
| `cocoindex.target.sink.duration` | `cocoindex_target_sink_duration_seconds` | histogram | `s` | `env`, `app`, `sink` | Wall time of one target action sink call. |
| `cocoindex.target.sink.batch_size` | `cocoindex_target_sink_batch_size` | histogram | `{action}` | `env`, `app`, `sink` | Actions per target action sink call (several components may be merged). |
| `cocoindex.target.sink.splits` | `cocoindex_target_sink_splits_total` | counter | `{batch}` | `env`, `app`, `sink` | Sink calls re-applied on a smaller batch to isolate a failure. |
| `cocoindex.target.sink.failures` | `cocoindex_target_sink_failures_total` | counter | `{batch}` | `env`, `app`, `sink` | Target action sink calls that failed. |
| `cocoindex.errors` | `cocoindex_errors_total` | counter | `{error}` | `env`, `app`, `stats_group`, `processor`, `mount_kind`, `exception_type`, `handled` | Component failures, by exception type and whether a handler swallowed them. |

## User counters

`coco.metrics.counter(name)` exports `cocoindex.user.<name>` (Prometheus:
`cocoindex_user_<name>_total`), a counter with the `env`, `app`, `stats_group` and
`processor` labels of the component the value was added from. See
[User counters](/docs/advanced_topics/observability/#user-counters).