Variables de entorno

Referencia de las variables de entorno de Tracer: licencia, puertos, TLS, PostgreSQL, autenticación, declaración de permisos RI, workers en segundo plano, límites de costo de CEL, gRPC de reservas y multi-tenancy.

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 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_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.

Licencia

Tracer necesita una licencia al iniciar. Inicia con LICENSE_KEY o con LICENSE_FILE_PATH. Sin ninguna de las dos, se niega a iniciar. Tracer no lee ninguna otra variable de licencia.

Variable	Descripción	Predeterminado	Requerida
LICENSE_KEY	Clave de licencia de tu despliegue. Sensible.	—	Sí (a menos que LICENSE_FILE_PATH esté definida)
LICENSE_FILE_PATH	Ruta de un archivo de licencia firmado montado. Tracer lo usa en lugar de la clave. Una ruta que no contiene un archivo aceptado detiene Tracer.	—	No

Con LICENSE_KEY, Tracer obtiene la licencia firmada del servidor de licencias y la mantiene solo en memoria. Tracer no guarda ninguna licencia en PostgreSQL, así que cada inicio la obtiene de nuevo. Mientras el servidor de licencias no responde, Tracer sigue en ejecución pero no listo, y lo intenta de nuevo. Mientras espera, el puerto principal rechaza conexiones y solo responde el listener de HEALTH_PORT. Un rechazo del servidor de licencias detiene 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	SERVER_ADDRESS, como :4020	ninguno	/health, /version y la API /v1
Salud y métricas	HEALTH_PORT	sin definir (sin listener)	/health, /readyz, /metrics
Seam gRPC de reservas	TRACER_GRPC_PORT	:4021	gRPC reserve / confirm / release

Sondea /readyz en HEALTH_PORT. El puerto principal no sirve /readyz ni /metrics. Sin HEALTH_PORT, ningún listener los responde.

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, Tracer evalúa solo esa cantidad de reglas y registra una advertencia. Si ninguna de las reglas evaluadas es una coincidencia DENY, la decisión es REVIEW con el motivo rule_evaluation_error, también cuando DEFAULT_DECISION_WHEN_NO_MATCH=DENY. 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_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, Tracer permite todos los orígenes, sin credenciales; 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 (todos los orígenes permitidos)	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

Tracer ya no lee API_KEY_ENABLED_ONLY_VALIDATION. Cuando la variable sigue definida, Tracer registra una advertencia en el log al iniciar y la ignora. POST /v1/validations/rules-only se autentica como cualquier otra ruta.

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.

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, drenado y timeouts

Variable	Descripción	Predeterminado	Obligatorio
HEALTH_PORT	Puerto del listener que sirve /health, /readyz y /metrics. Sin él, nada sirve /readyz ni /metrics.	sin definir	No
SHUTDOWN_DRAIN_DELAY	Tiempo que cada listener sigue sirviendo después de SIGTERM, para que el balanceador de carga retire el pod antes de que empiece el apagado. Una duración Go, como 15s. Un valor inválido detiene Tracer.	0, o 15s cuando Tracer corre en un pod de Kubernetes	No
SHUTDOWN_TIMEOUT	Un presupuesto total de tiempo, después del retraso de drenado, para el drenado de todos los listeners y los hooks de apagado. Una duración Go. Un valor inválido detiene Tracer. Si el presupuesto termina primero, Tracer sigue en ejecución hasta cerrar sus conexiones a la base de datos y su productor de eventos, por eso define el período de gracia de terminación del pod por encima de SHUTDOWN_DRAIN_DELAY más SHUTDOWN_TIMEOUT.	30s	No
REQUEST_TIMEOUT_SEC	Presupuesto de tiempo de cada solicitud HTTP, en segundos enteros. Una solicitud que sigue en ejecución al final responde 504 con el código 0564. Una base de datos que rechaza la conexión responde 503 con el código 0567.	30	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	Seguridad de transporte de los puertos de Tracer. mtls: el puerto de reservas y el puerto de la API REST exigen un certificado de cliente firmado por TRACER_TLS_CLIENT_CA_FILE. server: TLS solo en el puerto de reservas, sin certificado de cliente. mesh o vacío: Tracer escucha en texto plano.	vacío	Sí (si DEPLOYMENT_MODE=saas)
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 que el puerto de reservas acepta en 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, a menos que DEPLOYMENT_MODE=local esté definido explícitamente)
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
STREAMING_TENANT_KAFKA	Solo tiene efecto con MULTI_TENANT_ENABLED=true y STREAMING_ENABLED=true. Tracer entonces publica los eventos de cada tenant en el tópico de ese tenant, con los brokers y las credenciales que el Tenant Manager tiene para el tenant, así que STREAMING_BROKERS y STREAMING_SASL_* no son obligatorios.	false	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) 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.