Reference for Tracer environment variables covering ports, TLS, PostgreSQL, authentication, RI permission declaration, background workers, CEL cost limits, and reservation gRPC.
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, see the BYOC configuration reference. Those blocks cover TLS posture, OpenTelemetry, Access Manager authentication, service discovery, and event streaming. This page focuses on what is distinctive to Tracer.
Deployment flavor: local, byoc, or saas. In saas, TLS on the PostgreSQL connection is validated at boot and the server refuses to start without it. In byoc and local, that boot-time check is skipped, but per-connection TLS enforcement still applies unless ALLOW_INSECURE_TLS=true. Also tags the /readyz response.
local
No
ALLOW_INSECURE_TLS
Bypass per-connection TLS enforcement on infrastructure DSNs. Leave unset or false in production.
Decision a validation returns when no rule matches. Only ALLOW (fail-open) and DENY are accepted. Tracer deliberately rejects REVIEW, and any other value fails the service at boot. Leaving it unset keeps ALLOW and logs a startup warning.
ALLOW
No
MAX_RULES_PER_REQUEST
Ceiling on how many active rules are evaluated in a single validation. When more rules apply, the excess is truncated (a warning is logged) and the response reports totalRulesLoaded with truncated: true. Must be positive and at most 100000; an invalid value fails the service at boot.
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). When unset or empty, cross-origin requests are not allowed; set an explicit allow-list in production. The explicit value * is rejected at boot when API_KEY_ENABLED=true.
unset (no cross-origin requests allowed)
No
TRUSTED_PROXY_CIDRS
Trusted proxy CIDRs for X-Forwarded-For parsing. Set when running behind a load balancer.
Publish Tracer’s permission declaration to the identity service at boot. This integration is optional and fail-open: a publish or configuration failure logs a warning and Tracer continues serving.
false
No
IDP_HOST
Absolute URL of the identity service (distinct from the Access Manager address in PLUGIN_AUTH_ADDRESS). When declaration is enabled in saas, an explicit http:// URL makes boot fail; use https://.
—
No (needed to publish)
IDP_M2M_CLIENT_ID
Client ID used for the declaration’s machine-to-machine token.
—
No (needed to publish)
IDP_M2M_CLIENT_SECRET
Secret used for the declaration’s machine-to-machine token. Sensitive.
Tracer stores rules and usage counters in its own tracer database on the shared Midaz PostgreSQL primary. A dedicated migration-runner image applies the schema migration before the application starts. The service boots against an already-migrated schema and does not run migrations in-process.
Plan a maintenance window for the upgrade to Midaz v4.2.0. Its migration 000025 widens the asset column of the validation history table. PostgreSQL rewrites that table and rebuilds its indexes under an exclusive lock, so validation reads and writes wait until it ends. The duration grows with the number of stored validations.Each migration waits at most 5 seconds for the lock and fails with SQLSTATE 55P03 when traffic holds it. Run it again in a quieter window. A second run is safe.
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
—
Yes
DB_SSL_MODE
libpq SSL mode: disable, require, verify-ca, or verify-full. Use require or stronger in production.
Run the worker that expires reservations past their lifetime and returns their held capacity
true
No
RESERVATION_REAPER_INTERVAL_SECONDS
Reservation reaper sweep interval (seconds). Must be from 1 to 3600; an invalid value fails the service at boot.
30
No
RESERVATION_LONG_LIVED_TTL_HOURS
Lifetime recorded on a reservation that the ledger holds for a pending transaction (hours). Must be positive and at most 8760; an invalid value fails the service at boot. Reservations for direct transactions carry a fixed lifetime this variable does not change.
Server side of the seam the Midaz ledger calls to reserve spending limits.Tracer always opens the reservation port, :4021 by default. Protect it with Access Manager authentication (PLUGIN_AUTH_ENABLED), an API key (API_KEY_ENABLED), mutual TLS (TRACER_TLS_MODE=mtls) or your service mesh. Tracer starts without any of these, and any workload that reaches the port can reserve and release limit capacity.
Variable
Description
Default
Required
TRACER_GRPC_PORT
gRPC listen address for the reservation seam
:4021
No
TRACER_TLS_MODE
Seam transport mode: mtls, server, mesh, or empty
empty
No
TRACER_TLS_CERT_FILE
Server certificate PEM path
—
Yes (if TRACER_TLS_MODE is mtls or server)
TRACER_TLS_KEY_FILE
Server private-key PEM path. Sensitive.
—
Yes (if TRACER_TLS_MODE is mtls or server)
TRACER_TLS_CLIENT_CA_FILE
Client CA certificate PEM path
—
Yes (if TRACER_TLS_MODE=mtls)
TRACER_TLS_CLIENT_ALLOWED_NAMES
Comma-separated client certificate names for mtls mode
—
No
TRACER_SEAM_ALLOWED_CLIENTS
Comma-separated Access Manager application client IDs for the seam, read when PLUGIN_AUTH_ENABLED=true
Set it to true when PLUGIN_AUTH_ENABLED=true. Otherwise Access Manager authorizes application tokens under one shared role, and only TRACER_SEAM_ALLOWED_CLIENTS limits which applications can reserve.
false
No
AUTH_CACHE_TTL
Cache lifetime for Access Manager decisions, as a Go duration such as 60s
unset (no cache)
Yes (if PLUGIN_AUTH_ENABLED=true with DEPLOYMENT_MODE=saas)
AUTH_BREAKER_ENABLED
Circuit breaker on Access Manager calls
unset (off)
No
AUTH_JWT_VERIFY_CERT
PEM public keys or certificates for token signatures
The following blocks are identical across Lerian products. The BYOC configuration reference documents them in full. They default off.
Access Manager authentication: PLUGIN_AUTH_ENABLED, PLUGIN_AUTH_ADDRESS. Enable in production. With service discovery on (see Service discovery below), Tracer resolves the Access Manager host through Consul. It falls back to PLUGIN_AUTH_ADDRESS if resolution fails.
Service discovery: SD_* (Consul). Off by default. When SD_ENABLED=true, Tracer registers itself as midaz-tracer (advertising the HTTP port from SERVER_ADDRESS, default 4020) and resolves Access Manager through Consul. If that resolution fails, it falls back to the static PLUGIN_AUTH_ADDRESS. Discovery requires SD_EXTERNAL_ADDRESS or SD_INTERNAL_ADDRESS. Tracer is the server on the reservation gRPC seam and does not advertise it.
Event streaming: STREAMING_*. Off by default.
OpenTelemetry: ENABLE_TELEMETRY, OTEL_*. Tracer also exposes a Prometheus /metrics endpoint.
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.
