Variables de entorno

Referencia de variables de entorno de Tracer: puertos, TLS, PostgreSQL, autenticación, workers, límites de coste CEL y gRPC de reserva.

Esta referencia enumera las variables de entorno usadas para configurar Tracer, el servicio de control de gasto en tiempo real y análisis de riesgo de transacciones. Las defines en el momento del despliegue, mediante valores de Helm, Docker Compose o el entorno de tu orquestador. Las variables marcadas como requeridas hacen que el servidor falle al arrancar si no se definen.

Para los bloques de configuración que comparte cada producto de Lerian —postura de TLS, OpenTelemetry, autenticación de Access Manager, multi-tenancy, descubrimiento de servicios y streaming de eventos— consulta la referencia de configuración BYOC. Esta página se centra en lo que es distintivo de Tracer.

​

Puertos y endpoints de salud

Consulta la referencia de salud y readiness para el contrato de las sondas.

Superficie	Variable de puerto	Valor por defecto	Endpoints
REST + salud	SERVER_PORT / SERVER_ADDRESS	4020	/health, /readyz, /version, /metrics
Costura gRPC de reserva (opcional)	TRACER_GRPC_PORT	sin definir (desactivada)	gRPC reserve / confirm / release

​

Despliegue y TLS

Variable	Descripción	Valor por defecto	Requerida
DEPLOYMENT_MODE	Sabor de despliegue: local, byoc o saas. En saas, el TLS de la conexión a PostgreSQL se valida al arrancar y el servidor se niega a iniciar sin él. En byoc y local, esa verificación de arranque se omite, pero la imposición de TLS por conexión sigue aplicándose salvo que ALLOW_INSECURE_TLS=true. También etiqueta la respuesta de /readyz.	local	No
ALLOW_INSECURE_TLS	Omite la imposició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	Valor por defecto	Requerida
VERSION	Etiqueta de versión del servicio	varía	No
LOG_LEVEL	Verbosidad de los logs: debug, info, warn o error	debug	No
CEL_COST_LIMIT	Coste máximo de evaluación para una única 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	Valor por defecto	Requerida
DEFAULT_DECISION_WHEN_NO_MATCH	Decisión devuelta cuando ninguna regla coincide con una transacción. Solo se aceptan ALLOW (fail-open) y DENY (fail-closed) — REVIEW se rechaza a propósito, y cualquier otro valor hace fallar el servicio al arrancar. Dejarla sin definir mantiene ALLOW y registra una advertencia al inicio.	ALLOW	No
MAX_RULES_PER_REQUEST	Techo 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 informa totalRulesLoaded con truncated: true. Debe ser positiva y como máximo 100000; un valor inválido hace fallar el servicio al arrancar.	1000	No

​

Autenticación y manejo de peticiones

Variable	Descripción	Valor por defecto	Requerida
API_KEY_ENABLED	Impone la autenticación por clave de API	false	No
API_KEY	Clave de API para la autenticación de peticiones. Sensible: usa al menos 32 caracteres en producción.	—	Sí (si API_KEY_ENABLED=true)
API_KEY_ENABLED_ONLY_VALIDATION	Modo solo validación: comprueba las claves sin imponerlas de forma estricta	false	No
API_KEY_LABEL	Identificador de actor de auditoría registrado para el principal de la clave de API	tracer-default	No
CORS_ALLOWED_ORIGINS	Orígenes CORS permitidos (CSV). Sin definir, se permiten todos los orígenes: restringe a orígenes explícitos en producción. El valor explícito * se rechaza al arrancar cuando API_KEY_ENABLED=true.	— (permite todos)	No
TRUSTED_PROXY_CIDRS	CIDR de proxy de confianza para el análisis de X-Forwarded-For. Defínela al ejecutar detrás de un balanceador de carga.	— (usa la IP del par)	No

​

Base de datos (PostgreSQL)

Tracer almacena reglas y contadores de uso en su propia base de datos tracer en la primaria de PostgreSQL compartida de Midaz. La migración de esquema la aplica una imagen dedicada de migration-runner antes de que arranque la aplicación; el servicio inicia contra un esquema ya migrado y no ejecuta migraciones en el proceso.

Variable	Descripción	Valor por defecto	Requerida
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 más estricto en producción.	disable	No

​

Workers en segundo plano

Variable	Descripción	Valor por defecto	Requerida
CLEANUP_WORKER_ENABLED	Ejecuta el worker de limpieza de contadores de uso expirados	false	No
CLEANUP_INTERVAL_HOURS	Intervalo de limpieza (horas). La ventana de retención en sí es fija de 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 obsolescencia de la caché de reglas (segundos)	50	No
RULE_SYNC_OVERLAP_BUFFER_SECONDS	Búfer de solapamiento de sincronización de la caché de reglas (segundos)	2	No

​

Reservas

Variable	Descripción	Valor por defecto	Requerida
RESERVATION_LONG_LIVED_TTL_HOURS	Duración 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 llevan una duración fija que esta variable no cambia.	720	No

​

Readiness y drenaje

Variable	Descripción	Valor por defecto	Requerida
READYZ_DRAIN_GRACE_SECONDS	Ventana durante la cual /readyz devuelve 503 tras un SIGTERM, para que Kubernetes dé de baja el pod antes del apagado	12	No
READYZ_CACHE_STALENESS_THRESHOLD_SECONDS	Antigüedad de la caché de reglas a la que /readyz reporta degraded	300	No

​

Costura gRPC de reserva

Lado servidor de la costura que el ledger de Midaz invoca para reservar límites de gasto. Desactivada salvo que se defina TRACER_GRPC_PORT.

Variable	Descripción	Valor por defecto	Requerida
TRACER_GRPC_PORT	Puerto de escucha gRPC del servidor de reservas	sin definir (desactivado)	No
TRACER_TLS_MODE	Seguridad de la costura: mesh (TLS terminado por el service mesh) o mtls	mesh	No
TRACER_TLS_CERT_FILE	Ruta del certificado PEM del servidor (cuando mtls)	—	No
TRACER_TLS_KEY_FILE	Ruta de la clave privada PEM del servidor (cuando mtls). Sensible.	—	No
TRACER_TLS_CLIENT_CA_FILE	Ruta del certificado CA PEM del cliente para verificación mutua (cuando mtls)	—	No

​

Base de configuración compartida

Los siguientes bloques son idénticos en todos los productos de Lerian y están documentados por completo en la referencia de configuración BYOC. Están desactivados por defecto.

• Autenticación de Access Manager — PLUGIN_AUTH_ENABLED, PLUGIN_AUTH_ADDRESS. Habilítala en producción. En compilaciones con descubrimiento habilitado (ver Descubrimiento de servicios más abajo), Tracer resuelve el host de Access Manager a través de Consul y recurre a PLUGIN_AUTH_ADDRESS si la resolución falla; las compilaciones actuales siempre usan PLUGIN_AUTH_ADDRESS.
• Multi-tenancy — MULTI_TENANT_*, más los ajustes de pool por tenant de Tracer (MULTI_TENANT_MAX_TENANT_POOLS, MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT, TENANT_CAP_RETRY_AFTER_SECONDS). Desactivado por defecto. APPLICATION_NAME identifica el módulo ante Tenant Manager.
• Descubrimiento de servicios — SD_* (Consul). Desactivado por defecto y temporalmente inerte: las compilaciones actuales excluyen la integración con Consul, así que SD_ENABLED=true no tiene efecto y Tracer siempre resuelve Access Manager desde la dirección estática PLUGIN_AUTH_ADDRESS. En compilaciones con descubrimiento habilitado, Tracer se registra como midaz-tracer (anunciando el puerto HTTP de SERVER_ADDRESS, por defecto 4020) y resuelve Access Manager mediante Consul. La costura gRPC de reserva no se anuncia: Tracer es el servidor en esa costura.
• Streaming de eventos — STREAMING_* (productor de lib-streaming). Desactivado por defecto.
• OpenTelemetry — ENABLE_TELEMETRY, OTEL_*. Tracer también expone un endpoint /metrics de Prometheus.