Version: Next 🚧

Environment variables

All settings are read from environment variables at boot. The exporter uses zod to validate them and fails fast with a clear error if anything is invalid. Provide them via a .env file (loaded by dotenv) or your container runtime.

Core

Variable	Default	Description
`MONGO_URI`	`mongodb://host.docker.internal:27017/librechat`	Connection string for your LibreChat MongoDB database.
`PORT`	`9087`	The port on which the exporter runs and exposes `/metrics`.
`MONGO_POOL_SIZE`	`50`	`maxPoolSize` passed to `mongoose.connect`.
`REFRESH_INTERVAL`	`30000`	Interval in ms for the basic metrics scrape (cheap, runs often).
`ADVANCED_REFRESH_INTERVAL`	`REFRESH_INTERVAL × 10`	Interval in ms for the advanced metrics scrape (heavy `$facet` aggregations, runs on a separate timer so a slow advanced cycle never blocks basic).
`CARDINALITY_REFRESH_INTERVAL`	`ADVANCED_REFRESH_INTERVAL`	Interval in ms for the cardinality scrape (per-user `id`-labeled metrics). A no-op (no Mongo queries) when `EMIT_PER_USER_METRICS=false`.
`LOG_TIMINGS`	`false`	When `true`, prints per-scrape and per-section timing logs. Per-section durations are always exposed as the `librechat_exporter_section_duration_seconds` histogram regardless. Accepts `true` or `false` (case-insensitive).

Cardinality and tenancy

Variable	Default	Description
`EMIT_PER_USER_METRICS`	`false`	When `true`, emits three high-cardinality `id`-labeled metrics — one Prometheus series per user. Off by default to protect large deployments. See Cardinality below.
`ANONYMIZE_EMAIL_LABEL`	`true`	Controls the value of the `id` label on the three cardinality metrics. When `true` (default), the value is the user's Mongo `_id` (24-char ObjectId). When `false`, it's the real email address. The label name stays `id` either way so dashboards don't need to change.
`TENANT_ID`	(unset)	When set, installs mongoose schema hooks that scope every aggregate / find / count query to the named tenant. Leave unset on single-tenant LibreChat installs (the default).

HTTP server hardening

Variable	Default	Description
`METRICS_PORT`	(unset)	Optional second port for `/metrics` only. If set and different from `PORT`, `/metrics` binds there and `/health` stays on `PORT`. Useful for k8s sidecar / internal-only metrics scraping.
`TRUST_PROXY`	`loopback`	Value passed to `app.set('trust proxy', ...)`. Set when running behind a reverse proxy so `req.ip` (and the IP allowlist) see real clients. Accepts `true`, `false`, a CIDR list, or `loopback` / `linklocal` / `uniquelocal`.
`RATE_LIMIT_WINDOW_MS`	`60000`	Per-IP rate-limit window in ms.
`RATE_LIMIT_MAX`	`120`	Max requests per IP to `/metrics` per window.
`HEALTH_RATE_LIMIT_MAX`	`600`	Max requests per IP to `/health` per window.

Auth (all optional)

See the Auth reference for the full guide. Summary:

Variable	Default	Description
`METRICS_BEARER_TOKEN`	(unset)	Static bearer token. If set, `/metrics` requires `Authorization: Bearer <token>`.
`METRICS_BASIC_AUTH_USER`	(unset)	HTTP Basic username. Must be set together with `METRICS_BASIC_AUTH_PASSWORD`.
`METRICS_BASIC_AUTH_PASSWORD`	(unset)	HTTP Basic password.
`METRICS_OAUTH2_ISSUER`	(unset)	OIDC issuer URL. Exporter discovers JWKS from `${issuer}/.well-known/openid-configuration` at boot. Mutually exclusive with `METRICS_OAUTH2_JWKS_URI`.
`METRICS_OAUTH2_JWKS_URI`	(unset)	Direct JWKS endpoint URL. Use when the IdP does not expose OIDC discovery.
`METRICS_OAUTH2_AUDIENCE`	(unset)	Required if any `METRICS_OAUTH2_*` is set. The `aud` claim the exporter accepts.
`METRICS_OAUTH2_REQUIRED_SCOPES`	(unset)	Space-separated scopes. Token must carry every listed scope in `scope` or `scp`.
`METRICS_OAUTH2_ALGORITHMS`	`RS256,ES256`	Comma-separated allowed JWT signing algorithms.
`METRICS_ALLOWED_IPS`	(unset)	Comma-separated CIDRs (IPv4 / IPv6). Requests outside the list are rejected with 403. Combine with a token method (both must pass) or use standalone.
`METRICS_AUTH_LOG_REJECTS`	`true`	Log auth rejections (rate-limited to ~1/sec). Set to `false` to silence.

Example `.env`

MONGO_URI=mongodb://my-mongo-host:27017/librechat
PORT=9087
ADVANCED_REFRESH_INTERVAL=300000
EMIT_PER_USER_METRICS=false

Cardinality

Why this matters

Prometheus charges (and slows down) per unique label combination, not per metric. Adding a per-user label creates one time series per value — easily tens of thousands on a busy LibreChat install.

Three metrics carry an id label and emit one Prometheus series per user. On large deployments this grows unbounded, so they are gated behind EMIT_PER_USER_METRICS=true:

librechat_transaction_cost_by_user{id}
librechat_transaction_token_sum_by_model_user{model,tokenType,id}
librechat_agent_usage_by_user_count{agent,id}

By default (ANONYMIZE_EMAIL_LABEL=true) the id label carries the user's Mongo _id. Set ANONYMIZE_EMAIL_LABEL=false if you want the real email address as the label value instead. These metrics live on their own scrape loop (CARDINALITY_REFRESH_INTERVAL) so you can refresh them less often than the rest of the advanced tier — for example only twice a day.

The corresponding *_by_email_domain variants are bounded by company-domain count and remain enabled by default.

See the Adding a metric playbook for the cardinality budget rules new metrics should follow.

Core​

Cardinality and tenancy​

HTTP server hardening​

Auth (all optional)​

Example .env​

Cardinality​