# Metrics (https://www.librechat.ai/docs/configuration/metrics)

## General

![Active users in LibreChat](/images/metrics/librechat-metrics-active-users.png)

LibreChat provides two Prometheus-compatible metrics surfaces. The API's built-in `/metrics` endpoint reports operational behavior such as Redis activity and browser telemetry proxy outcomes. The optional database exporter reports usage data stored in MongoDB, including token totals and active-user counts.

## Built-in API Metrics

LibreChat exposes Prometheus metrics from the API server at `/metrics`. Set `METRICS_SECRET` and scrape the endpoint with `Authorization: Bearer <METRICS_SECRET>`. The endpoint returns `401` when the secret is unset, the header is missing, or the token does not match.

```yaml filename="prometheus.yml"
scrape_configs:
  - job_name: librechat-api
    scheme: https
    metrics_path: /metrics
    authorization:
      type: Bearer
      credentials: your-metrics-secret
    static_configs:
      - targets: ['librechat.example.com']
```

### Agent Startup Metrics

Initial Agent chat requests emit two startup metrics:

- `agent_startup_milestone_duration_seconds{milestone}` measures cumulative latency from request ingress to each startup milestone.
- `agent_startups_total{result}` counts startup attempts by terminal result.

Milestones cover request admission, job creation and acknowledgement, conversation and history loading, client and run initialization, stream startup, and the first queued response or content event. Results distinguish content queued, completion without a content delta, deduplication, rejection, pause, replacement, abort, and error.

When [backend OpenTelemetry tracing](/docs/configuration/dotenv#opentelemetry-tracing) is enabled, the `librechat.agent.startup` span reports the same milestones as events. It includes total startup duration, milestone count, terminal result, and the generation stream ID when one is assigned.

### Redis Metrics

Redis-backed caches and services emit two logical-operation metrics:

- `redis_operations_total{client,use_case,operation,status}` counts operations.
- `redis_operation_duration_seconds{client,use_case,operation,status}` measures latency.

`client` is `keyv` or `ioredis`, and `status` is `success` or `error`. Bounded `use_case` labels identify work such as caches, sessions, rate limits, concurrency, ACL principals, resumable stream jobs and pub/sub, MCP registry scans, and leader election. These metrics count LibreChat's logical operations rather than every internal Redis round trip. Connection lifecycle pings and global maintenance are excluded, and clearing a namespace is counted as one logical operation.

When [backend OpenTelemetry tracing](/docs/configuration/dotenv#opentelemetry-tracing) is enabled, each HTTP span also summarizes its Redis work with:

- `librechat.redis.calls`
- `librechat.redis.duration_ms`
- `librechat.redis.errors`
- `librechat.redis.max_call_ms`
- `librechat.redis.operations`
- `librechat.redis.use_cases`

The ten use cases with the highest total duration also receive `calls`, `duration_ms`, `errors`, and `max_call_ms` attributes under `librechat.redis.<use_case>.*`. This request-level summary does not require command-level Redis spans; enable `OTEL_IOREDIS_TRACING_ENABLED` only when individual command spans are needed.

### Browser RUM Proxy Metrics

Browser RUM proxy outcomes are reported as `rum_proxy_requests_total{endpoint,result}`. `endpoint` is `traces`, `logs`, or `unknown`; `result` can be `success`, `auth_drop`, `auth_error`, `bad_request`, `not_configured`, `collector_4xx`, `collector_5xx`, `collector_error`, or `collector_timeout`.

### Agent Event Actor Metrics

Durable bound Agent Events expose low-cardinality receipt and recovery metrics:

- `agent_event_actor_receipt_operations_total{operation,outcome,resolution}` counts receipt reads, settlement, and legacy backfill. `operation` is `read`, `settle`, or `backfill`; `outcome` is `hit`, `miss`, `success`, `replay`, or `conflict`.
- `agent_event_actor_receipts_retained{resolution}` reports replay receipts retained by `checkpoint_verified`, `action_compensated`, or `history_repaired` resolution.
- `agent_event_actor_receipts_expiry_eligible` reports retained receipts whose 90-day MongoDB TTL has elapsed but which have not yet been removed.
- `agent_event_actor_reconciliations_pending` reports active reconciliation markers waiting for a terminal receipt.
- `agent_event_actor_oldest_reconciliation_age_seconds` reports the age of the oldest active reconciliation.
- `agent_event_actor_deliveries{state}` reports delivery rows currently in `retry` or `dead` state.

Storage gauges are collected on authenticated scrapes and cached for up to 60 seconds. Alert on sustained reconciliation age, dead deliveries, or expiry-eligible receipts rather than a single scrape.

### Shared-Link Metrics

`share_link_rejections_total{operation,code}` counts bounded create or update failures. `operation` is `create` or `update`; `code` is `TARGET_MESSAGE_NOT_FOUND` when the selected branch tail is not persisted, or `NO_MESSAGES` when the conversation has no persisted messages. The metric contains no conversation text or user identity.

## Database Metrics Exporter

The metrics exporter is available at [virtUOS/librechat_exporter](https://github.com/virtUOS/librechat_exporter).
It is a separate tool you deploy alongside LibreChat.

### Setup

To deploy the exporter, just add the necessary container to your compose configuration like this:

```yaml
services:
  metrics:
    image: ghcr.io/virtuos/librechat_exporter:main
    depends_on:
      - mongodb
    ports:
      - '8000:8000'
    restart: unless-stopped
```

You can optionally also configure the exporter.
But usually, the defaults should be just fine.

```yaml
services:
  metrics:
    environment:
      - MONGODB_URI=mongodb://mongodb:27017/
      - LOGGING_LEVEL=info
```

### Usage

You can now add the exporter to your Prometheus scrape configuration:

```yaml
- job_name: librechat
  static_configs:
    - targets:
        - 'librechat.example.com:8000'
```

Once scraping the metrics has started, look for `librechat_*` metrics (e.g., `librechat_registered_users`).
The exporter provides several metrics.

Have fun building your Grafana dashboard!