Environment variables

This reference lists the environment variables used to configure Tracer, the real-time spending-control and transaction-risk service. You set these at deploy time, through Helm values, Docker Compose, or your orchestrator’s environment. Variables marked as required cause the server to fail on startup if not set. For the configuration blocks that every Lerian product shares — TLS posture, OpenTelemetry, Access Manager authentication, multi-tenancy, and event streaming — see the BYOC configuration reference. This page focuses on what is distinctive to Tracer.

Tracer runs as a standalone service and is also bundled into the Midaz monorepo (components/tracer) as part of the consolidation rollout. The variables below reflect the current, most complete shape, including the reservation gRPC seam the ledger calls into.

Ports and health endpoints

See the health and readiness reference for the probe contract.

Surface	Port variable	Default	Endpoints
REST + health	`SERVER_PORT` / `SERVER_ADDRESS`	`4020`	`/health`, `/readyz`, `/version`, `/metrics`
Reservation gRPC seam (opt-in)	`TRACER_GRPC_PORT`	unset (off)	gRPC reserve / confirm / release

Deployment and TLS

Variable	Description	Default	Required
`DEPLOYMENT_MODE`	Deployment flavor: `local`, `byoc`, or `saas`. In `saas`, TLS is mandatory for every dependency connection and the server refuses to start without it. In `byoc`, TLS is recommended and warned-on rather than enforced. Also tags the `/readyz` response.	`local`	No
`ALLOW_INSECURE_TLS`	Bypass per-connection TLS enforcement on infrastructure DSNs. Leave unset or `false` in production.	`false`	No

Application

Variable	Description	Default	Required
`VERSION`	Service version tag	varies	No
`LOG_LEVEL`	Log verbosity: `debug`, `info`, `warn`, or `error`	`debug`	No
`CEL_COST_LIMIT`	Maximum evaluation cost for a single CEL rule expression	`10000`	No

Authentication and request handling

Variable	Description	Default	Required
`API_KEY_ENABLED`	Enforce API-key authentication	`false`	No
`API_KEY`	API key for request authentication. Sensitive — use at least 32 characters in production.	—	Yes (if `API_KEY_ENABLED=true`)
`API_KEY_ENABLED_ONLY_VALIDATION`	Validate-only mode: check keys without hard-enforcing them	`false`	No
`API_KEY_LABEL`	Audit actor identifier recorded for the API-key principal	`tracer-default`	No
`CORS_ALLOWED_ORIGINS`	Allowed CORS origins (CSV, or `*`). Lock to explicit origins in production.	— (restrictive)	No
`TRUSTED_PROXY_CIDRS`	Trusted proxy CIDRs for `X-Forwarded-For` parsing. Set when running behind a load balancer.	— (uses peer IP)	No

Database (PostgreSQL)

Tracer stores rules and usage counters in its own tracer database on the shared Midaz PostgreSQL primary.

Variable	Description	Default	Required
`DB_HOST`	PostgreSQL host	—	Yes
`DB_PORT`	PostgreSQL port	—	Yes
`DB_USER`	Database user	—	Yes
`DB_PASSWORD`	Database password. Sensitive.	—	Yes
`DB_NAME`	Database name	`tracer`	Yes
`DB_SSL_MODE`	libpq SSL mode: `disable`, `require`, `verify-ca`, or `verify-full`. Use `require` or stronger in production.	`disable`	No
`MIGRATIONS_PATH`	Path to database migration files	`./migrations`	No

Background workers

Variable	Description	Default	Required
`CLEANUP_WORKER_ENABLED`	Run the expired usage-counter cleanup worker	`false`	No
`CLEANUP_WORKER_INTERVAL_HOURS`	Cleanup interval (hours)	`24`	No
`CLEANUP_WORKER_RETENTION_DAYS`	Usage-counter retention window (days)	`90`	No
`RESERVATION_REAPER_ENABLED`	Run the expired-reservation reaper	`false`	No
`RESERVATION_REAPER_INTERVAL_SECONDS`	Reaper interval (seconds)	`30`	No
`RESERVATION_LONG_LIVED_TTL_HOURS`	TTL after which a long-lived reservation is reaped (hours)	`720`	No
`RULE_SYNC_POLL_INTERVAL_SECONDS`	Rule-cache sync poll interval (seconds)	`10`	No
`RULE_SYNC_STALENESS_THRESHOLD_SECONDS`	Rule-cache staleness threshold (seconds)	`50`	No
`RULE_SYNC_OVERLAP_BUFFER_SECONDS`	Rule-cache sync overlap buffer (seconds)	`2`	No

Readiness and draining

Variable	Description	Default	Required
`READYZ_DRAIN_GRACE_SECONDS`	Window during which `/readyz` returns 503 after SIGTERM, so Kubernetes de-registers the pod before shutdown	`12`	No
`READYZ_CACHE_STALENESS_THRESHOLD_SECONDS`	Rule-cache age at which `/readyz` reports `degraded`	`300`	No

Reservation gRPC seam

Server side of the seam the Midaz ledger calls to reserve spending limits. Off unless TRACER_GRPC_PORT is set.

Variable	Description	Default	Required
`TRACER_GRPC_PORT`	gRPC listen port for the reservation server	unset (off)	No
`TRACER_TLS_MODE`	Seam security: `mesh` (TLS terminated by the service mesh) or `mtls`	`mesh`	No
`TRACER_TLS_CERT_FILE`	Server certificate PEM path (when `mtls`)	—	No
`TRACER_TLS_KEY_FILE`	Server private-key PEM path (when `mtls`). Sensitive.	—	No
`TRACER_TLS_CLIENT_CA_FILE`	Client CA certificate PEM path for mutual verification (when `mtls`)	—	No

Shared configuration backbone

The following blocks are identical across Lerian products and are documented in full in the BYOC configuration reference. They default off.

Access Manager authentication — PLUGIN_AUTH_ENABLED, PLUGIN_AUTH_ADDRESS. Enable in production.
Multi-tenancy — MULTI_TENANT_*, plus Tracer’s per-tenant pool knobs (MULTI_TENANT_MAX_TENANT_POOLS, MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT, MULTI_TENANT_TENANT_CAP_RETRY_AFTER_SECONDS). Off by default. APPLICATION_NAME identifies the module to Tenant Manager.
Event streaming — STREAMING_* (lib-streaming producer). Off by default.
OpenTelemetry — ENABLE_TELEMETRY, OTEL_*. Tracer also exposes a Prometheus /metrics endpoint.

Overview

Guides

Console

Operations

Environment variables

Ports and health endpoints

Deployment and TLS

Application

Authentication and request handling

Database (PostgreSQL)

Background workers

Readiness and draining

Reservation gRPC seam

Shared configuration backbone

​Ports and health endpoints

​Deployment and TLS

​Application

​Authentication and request handling

​Database (PostgreSQL)

​Background workers

​Readiness and draining

​Reservation gRPC seam

​Shared configuration backbone

Ports and health endpoints

Deployment and TLS

Application

Authentication and request handling

Database (PostgreSQL)

Background workers

Readiness and draining

Reservation gRPC seam

Shared configuration backbone