Variables de entorno

Esta referencia enumera las variables de entorno que se usan para configurar Tracer, el servicio de control de gasto y riesgo de transacciones en tiempo real. Estas variables se configuran en el momento del despliegue, mediante los valores de Helm, Docker Compose o el entorno de tu orquestador. Las variables marcadas como obligatorias hacen que el servidor falle al iniciar si no están definidas. Al iniciar, Tracer también verifica los valores de abajo. Cuando una verificación falla, Tracer no inicia, y el error indica el nombre de la variable.

Una variable booleana de las tablas de esta página acepta solo true o false. Tracer no verifica ALLOW_INSECURE_TLS de esta forma.
AUTH_TIMEOUT y AUTH_CACHE_TTL necesitan una duración con unidad, como 60s.
READYZ_DRAIN_GRACE_SECONDS, READYZ_CACHE_STALENESS_THRESHOLD_SECONDS, TENANT_CAP_RETRY_AFTER_SECONDS y las variables MULTI_TENANT_* que contienen un conteo o un número de segundos aceptan solo un número entero, sin unidad.
Cuando AUTH_JWT_VERIFY_CERT está definida, debe contener claves públicas RSA o certificados en PEM. Cuando está vacía y AUTH_JWT_VERIFY_CERT_PATH está definida, ese archivo debe ser legible y contener esas claves o certificados.
Cada entrada de TRUSTED_PROXIES debe ser una dirección IP o un CIDR.
Cada booleano o número de STREAMING_* debe ser válido, y STREAMING_EVENT_POLICIES debe estar bien formada, también cuando STREAMING_ENABLED=false.

Para los bloques de configuración que comparten todos los productos de Lerian, consulta la referencia de configuración de BYOC. Esos bloques cubren la postura de TLS, OpenTelemetry, la autenticación de Access Manager, el descubrimiento de servicios y el streaming de eventos. Esta página se enfoca en lo que es propio de Tracer.

Puertos y endpoints de salud

Consulta la referencia de salud y readiness para el contrato de los probes.

Superficie	Variable de puerto	Predeterminado	Endpoints
REST + salud	`SERVER_PORT` / `SERVER_ADDRESS`	`4020`	`/health`, `/readyz`, `/version`, `/metrics`
Seam gRPC de reservas	`TRACER_GRPC_PORT`	`:4021`	gRPC reserve / confirm / release

Despliegue y TLS

Variable	Descripción	Predeterminado	Obligatorio
`DEPLOYMENT_MODE`	Modalidad de despliegue: `local`, `byoc` o `saas`. En `saas`, el TLS de la conexión de PostgreSQL se valida al iniciar y el servidor se niega a arrancar sin él. En `byoc` y `local`, esa verificación al arrancar se omite, pero la aplicación de TLS por conexión sigue vigente a menos que `ALLOW_INSECURE_TLS=true`. También etiqueta la respuesta de `/readyz`.	`local`	No
`ALLOW_INSECURE_TLS`	Omite la aplicación de TLS por conexión en los DSN de infraestructura. Déjala sin definir o en `false` en producción.	`false`	No

Aplicación

Variable	Descripción	Predeterminado	Obligatorio
`LOG_LEVEL`	Nivel de detalle del log: `debug`, `info`, `warn` o `error`	`debug`	No
`CEL_COST_LIMIT`	Costo máximo de evaluación para una sola expresión de regla CEL	`10000`	No
`OPENAPI_DOCS_ENABLED`	Sirve la especificación OpenAPI 3.1 y la documentación interactiva de Scalar en `/v1/openapi.{json,yaml}` y `/v1/docs`	`false`	No

Evaluación de reglas

Variable	Descripción	Predeterminado	Obligatorio
`DEFAULT_DECISION_WHEN_NO_MATCH`	Decisión que una validación devuelve cuando ninguna regla coincide. Solo se aceptan `ALLOW` (fail-open) y `DENY`. Tracer rechaza `REVIEW` deliberadamente, y cualquier otro valor hace fallar el servicio al arrancar. Si se deja sin definir, se mantiene `ALLOW` y se registra una advertencia al iniciar.	`ALLOW`	No
`MAX_RULES_PER_REQUEST`	Límite de cuántas reglas activas se evalúan en una sola validación. Cuando aplican más reglas, el exceso se trunca (se registra una advertencia) y la respuesta reporta `totalRulesLoaded` con `truncated: true`. Debe ser positivo y como máximo `100000`; un valor inválido hace fallar el servicio al arrancar.	`1000`	No

Autenticación y manejo de solicitudes

Variable	Descripción	Predeterminado	Obligatorio
`API_KEY_ENABLED`	Aplica la autenticación por API key	`false`	No
`API_KEY`	Clave de API para la autenticación de solicitudes. Sensible. Usa al menos 32 caracteres en producción.	—	Sí (si `API_KEY_ENABLED=true`)
`API_KEY_ENABLED_ONLY_VALIDATION`	Autentica `POST /v1/validations` y `POST /v1/validations/rules-only` con la API key en lugar de Access Manager. Esas rutas verifican la clave solo cuando `API_KEY_ENABLED=true`. Tracer no inicia con esta variable cuando `MULTI_TENANT_ENABLED=true`.	`false`	No
`API_KEY_LABEL`	Identificador del actor de auditoría registrado para el principal de la API key	`tracer-default`	No
`CORS_ALLOWED_ORIGINS`	Orígenes CORS permitidos (CSV). Si se deja sin definir o vacío, no se permiten solicitudes entre orígenes; define una lista explícita de permitidos en producción. El valor explícito `*` se rechaza al arrancar cuando `API_KEY_ENABLED=true`.	sin definir (no se permiten solicitudes entre orígenes)	No
`TRUSTED_PROXY_CIDRS`	CIDR de proxies confiables para el análisis de `X-Forwarded-For`. Defínela cuando el servicio se ejecuta detrás de un balanceador de carga.	sin definir (usa la IP del peer)	No

Declaración de permisos RI

Variable	Descripción	Predeterminado	Obligatorio
`IDP_DECLARATION_ENABLED`	Publica la declaración de permisos de Tracer en el servicio de identidad al arrancar. Con `true`, Tracer no inicia cuando `IDP_HOST`, `IDP_M2M_CLIENT_ID` o `IDP_M2M_CLIENT_SECRET` está vacía. Una falla de publicación no detiene Tracer.	`false`	No
`IDP_HOST`	URL absoluta del servicio de identidad (distinta de la dirección de Access Manager en `PLUGIN_AUTH_ADDRESS`). Cuando la declaración está habilitada en `saas`, una URL explícita `http://` hace fallar el arranque; usa `https://`.	—	Sí (si `IDP_DECLARATION_ENABLED=true`)
`IDP_M2M_CLIENT_ID`	ID de cliente usado para el token machine-to-machine de la declaración.	—	Sí (si `IDP_DECLARATION_ENABLED=true`)
`IDP_M2M_CLIENT_SECRET`	Secreto usado para el token machine-to-machine de la declaración. Sensible.	—	Sí (si `IDP_DECLARATION_ENABLED=true`)

Base de datos (PostgreSQL)

Tracer almacena las reglas y los contadores de uso en su propia base de datos tracer, dentro del primario de PostgreSQL compartido con Midaz. Una imagen dedicada de migration-runner aplica la migración del esquema antes de que la aplicación arranque. El servicio arranca contra un esquema ya migrado y no ejecuta migraciones en el proceso.

Planifica una ventana de mantenimiento para la actualización a Midaz v4.2.0. Su migración 000025 amplía la columna de activo de la tabla del historial de validaciones. PostgreSQL reescribe esa tabla y reconstruye sus índices bajo un lock exclusivo, así que las lecturas y escrituras de validaciones esperan hasta que termina. La duración crece con el número de validaciones almacenadas.Cada migración espera como máximo 5 segundos por el lock y falla con SQLSTATE 55P03 cuando el tráfico lo mantiene. Ejecútala de nuevo en una ventana más tranquila. Una segunda ejecución es segura.

Variable	Descripción	Predeterminado	Obligatorio
`DB_HOST`	Host de PostgreSQL	—	Sí
`DB_PORT`	Puerto de PostgreSQL	—	Sí
`DB_USER`	Usuario de la base de datos	—	Sí
`DB_PASSWORD`	Contraseña de la base de datos. Sensible.	—	Sí
`DB_NAME`	Nombre de la base de datos	—	Sí
`DB_SSL_MODE`	Modo SSL de libpq: `disable`, `require`, `verify-ca` o `verify-full`. Usa `require` o uno más estricto en producción.	`disable`	No

Workers en segundo plano

Variable	Descripción	Predeterminado	Obligatorio
`CLEANUP_WORKER_ENABLED`	Ejecuta el worker de limpieza de contadores de uso vencidos	`false`	No
`CLEANUP_INTERVAL_HOURS`	Intervalo de limpieza (horas). La ventana de retención en sí está fija en 90 días y no es configurable.	`24`	No
`RULE_SYNC_POLL_INTERVAL_SECONDS`	Intervalo de sondeo de sincronización de la caché de reglas (segundos)	`10`	No
`RULE_SYNC_STALENESS_THRESHOLD_SECONDS`	Umbral de antigüedad de la caché de reglas (segundos)	`50`	No
`RULE_SYNC_OVERLAP_BUFFER_SECONDS`	Margen de superposición de la sincronización de la caché de reglas (segundos)	`2`	No

Reservas

Variable	Descripción	Predeterminado	Obligatorio
`RESERVATION_REAPER_ENABLED`	Ejecuta el worker que expira las reservas que superan su vigencia y devuelve su capacidad retenida	`true`	No
`RESERVATION_REAPER_INTERVAL_SECONDS`	Intervalo de barrido del reaper de reservas (segundos). Debe ir de `1` a `3600`; un valor inválido hace fallar el servicio al arrancar.	`30`	No
`RESERVATION_LONG_LIVED_TTL_HOURS`	Vigencia registrada en una reserva que el ledger retiene para una transacción pendiente (horas). Debe ser positiva y como máximo `8760`; un valor inválido hace fallar el servicio al arrancar. Las reservas de transacciones directas tienen una vigencia fija que esta variable no modifica.	`720`	No

Readiness y drenado

Variable	Descripción	Predeterminado	Obligatorio
`READYZ_DRAIN_GRACE_SECONDS`	Ventana durante la cual `/readyz` devuelve 503 después de SIGTERM, para que Kubernetes elimine el registro del pod antes del apagado	`12`	No
`READYZ_CACHE_STALENESS_THRESHOLD_SECONDS`	Antigüedad de la caché de reglas a partir de la cual `/readyz` reporta `degraded`	`300`	No

Seam gRPC de reservas

Lado servidor del seam que el ledger de Midaz llama para reservar límites de gasto. Tracer siempre abre el puerto de reservas, :4021 de forma predeterminada. Protégelo con la autenticación de Access Manager (PLUGIN_AUTH_ENABLED), una clave de API (API_KEY_ENABLED), TLS mutuo (TRACER_TLS_MODE=mtls) o tu service mesh. Fuera de DEPLOYMENT_MODE=saas y del modo multi-tenant, Tracer inicia sin ninguna de estas protecciones, y cualquier workload que alcance el puerto puede reservar y liberar capacidad de límite.

Variable	Descripción	Predeterminado	Obligatorio
`TRACER_GRPC_PORT`	Dirección de escucha gRPC del seam de reservas	`:4021`	No
`TRACER_TLS_MODE`	Modo de transporte del seam: `mtls`, `server`, `mesh` o vacío	vacío	No
`TRACER_TLS_CERT_FILE`	Ruta del PEM del certificado del servidor	—	Sí (si `TRACER_TLS_MODE` es `mtls` o `server`)
`TRACER_TLS_KEY_FILE`	Ruta del PEM de la clave privada del servidor. Sensible.	—	Sí (si `TRACER_TLS_MODE` es `mtls` o `server`)
`TRACER_TLS_CLIENT_CA_FILE`	Ruta del PEM del certificado CA del cliente	—	Sí (si `TRACER_TLS_MODE=mtls`)
`TRACER_TLS_CLIENT_ALLOWED_NAMES`	Nombres de certificado de cliente separados por comas para el modo `mtls`	—	No
`TRACER_SEAM_ALLOWED_CLIENTS`	IDs de cliente de aplicación de Access Manager separados por comas para el seam, leídos cuando `PLUGIN_AUTH_ENABLED=true`. Tracer ignora esta variable en el modo multi-tenant.	—	Sí (si `PLUGIN_AUTH_ENABLED=true` en el modo single-tenant, fuera de `DEPLOYMENT_MODE=local`)
`AUTH_M2M_INVERSION_ENABLED`	Configúrala en `true` cuando `PLUGIN_AUTH_ENABLED=true`. De lo contrario, Access Manager autoriza los tokens de aplicación bajo un único rol compartido y solo `TRACER_SEAM_ALLOWED_CLIENTS` limita qué aplicaciones pueden reservar.	`false`	No
`AUTH_CACHE_TTL`	Vigencia de la caché de decisiones de Access Manager, como duración con unidad, por ejemplo `60s`	sin definir (sin caché)	Sí (si `PLUGIN_AUTH_ENABLED=true` con `DEPLOYMENT_MODE=saas`)
`AUTH_BREAKER_ENABLED`	Circuit breaker en las llamadas a Access Manager	sin definir (desactivado)	No
`AUTH_JWT_VERIFY_CERT`	Claves públicas o certificados PEM para las firmas de token	—	No

Multi-tenancy

Variable	Descripción	Predeterminado	Obligatorio
`MULTI_TENANT_ENABLED`	Activa el modo multi-tenant. En este modo, Tracer no inicia sin `PLUGIN_AUTH_ENABLED=true`.	`false`	No
`MULTI_TENANT_URL`	URL del Tenant Manager, con esquema y host. Tracer no inicia con una URL `http://` a menos que `MULTI_TENANT_ALLOW_INSECURE_HTTP=true`.	—	Sí (si `MULTI_TENANT_ENABLED=true`)
`MULTI_TENANT_SERVICE_API_KEY`	Clave de API para el Tenant Manager. Sensible.	—	Sí (si `MULTI_TENANT_ENABLED=true`)
`MULTI_TENANT_REDIS_HOST`	Host del Redis que lleva los eventos de tenant.	—	Sí (si `MULTI_TENANT_ENABLED=true`)
`MULTI_TENANT_REDIS_PORT`	Puerto del Redis de eventos de tenant.	`6379`	No
`MULTI_TENANT_REDIS_PASSWORD`	Contraseña del Redis de eventos de tenant. Sensible.	—	No
`MULTI_TENANT_REDIS_TLS`	Usa TLS para el Redis de eventos de tenant.	`true`	No
`MULTI_TENANT_MAX_TENANT_POOLS`	Número máximo de tenants con workers en ejecución en una instancia de Tracer.	`100`	No
`MULTI_TENANT_IDLE_TIMEOUT_SEC`	Tiempo de inactividad después del cual Tracer puede cerrar un pool de base de datos de tenant (segundos).	`300`	No
`MULTI_TENANT_TIMEOUT`	Tiempo límite de una llamada al Tenant Manager (segundos).	`30`	No
`MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD`	Fallas antes de que se abra el circuit breaker del Tenant Manager.	`5`	No
`MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC`	Tiempo antes de que el circuit breaker del Tenant Manager vuelva a intentarlo (segundos).	`30`	No
`MULTI_TENANT_CACHE_TTL_SEC`	Cuánto tiempo Tracer guarda una configuración de tenant (segundos).	`120`	No
`MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC`	Intervalo entre las verificaciones de la configuración de los pools de tenant (segundos).	`30`	No
`MULTI_TENANT_ALLOW_INSECURE_HTTP`	Acepta una `MULTI_TENANT_URL` `http://`. Déjala sin definir o en `false` en producción.	`false`	No
`TENANT_CAP_RETRY_AFTER_SECONDS`	Valor de `Retry-After`, en segundos, del HTTP 503 con código `0466` que Tracer devuelve cuando alcanza `MULTI_TENANT_MAX_TENANT_POOLS`.	`5`	No

Configuración compartida entre productos

Los siguientes bloques son idénticos en todos los productos de Lerian. La referencia de configuración de BYOC los documenta en su totalidad. Están desactivados por defecto.

Autenticación de Access Manager: PLUGIN_AUTH_ENABLED, PLUGIN_AUTH_ADDRESS. Habilítala en producción. Con el descubrimiento de servicios activado (consulta Descubrimiento de servicios más abajo), Tracer resuelve el host de Access Manager mediante Consul. Recurre a PLUGIN_AUTH_ADDRESS si la resolución falla.
Descubrimiento de servicios: SD_* (Consul). Desactivado por defecto. Cuando SD_ENABLED=true, Tracer se registra a sí mismo como midaz-tracer (anunciando el puerto HTTP de SERVER_ADDRESS, 4020 por defecto) y resuelve Access Manager mediante Consul. Si esa resolución falla, recurre a la dirección estática PLUGIN_AUTH_ADDRESS. El descubrimiento requiere SD_EXTERNAL_ADDRESS o SD_INTERNAL_ADDRESS. Tracer es el servidor en el seam gRPC de reservas y no lo anuncia.
Streaming de eventos: STREAMING_*. Desactivado por defecto.
OpenTelemetry: ENABLE_TELEMETRY, OTEL_*. Tracer también expone un endpoint /metrics de Prometheus.

Resumen

Guías

Console

Operaciones

Variables de entorno

Puertos y endpoints de salud

Despliegue y TLS

Aplicación

Evaluación de reglas

Autenticación y manejo de solicitudes

Declaración de permisos RI

Base de datos (PostgreSQL)

Workers en segundo plano

Reservas

Readiness y drenado

Seam gRPC de reservas

Multi-tenancy

Configuración compartida entre productos

​Puertos y endpoints de salud

​Despliegue y TLS

​Aplicación

​Evaluación de reglas

​Autenticación y manejo de solicitudes

​Declaración de permisos RI

​Base de datos (PostgreSQL)

​Workers en segundo plano

​Reservas

​Readiness y drenado

​Seam gRPC de reservas

​Multi-tenancy

​Configuración compartida entre productos

Puertos y endpoints de salud

Despliegue y TLS

Aplicación

Evaluación de reglas

Autenticación y manejo de solicitudes

Declaración de permisos RI

Base de datos (PostgreSQL)

Workers en segundo plano

Reservas

Readiness y drenado

Seam gRPC de reservas

Multi-tenancy

Configuración compartida entre productos