Variables de entorno

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 y streaming de eventos— consulta la referencia de configuración BYOC. Esta página se centra en lo que es distintivo de Tracer.

Tracer se ejecuta como un servicio independiente y también se incluye en el monorepo de Midaz (components/tracer) como parte del despliegue gradual de la consolidación. Las variables siguientes reflejan la forma actual más completa, incluida la costura gRPC de reserva que el ledger invoca.

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 es obligatorio para cada conexión a una dependencia y el servidor se niega a arrancar sin él. En `byoc`, el TLS se recomienda y se advierte en lugar de imponerse. 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

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, o `*`). Restringe a orígenes explícitos en producción.	— (restrictivo)	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.

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	`tracer`	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
`MIGRATIONS_PATH`	Ruta a los archivos de migración de la base de datos	`./migrations`	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_WORKER_INTERVAL_HOURS`	Intervalo de limpieza (horas)	`24`	No
`CLEANUP_WORKER_RETENTION_DAYS`	Ventana de retención de contadores de uso (días)	`90`	No
`RESERVATION_REAPER_ENABLED`	Ejecuta el reaper de reservas expiradas	`false`	No
`RESERVATION_REAPER_INTERVAL_SECONDS`	Intervalo del reaper (segundos)	`30`	No
`RESERVATION_LONG_LIVED_TTL_HOURS`	TTL tras el cual se recolecta una reserva de larga duración (horas)	`720`	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

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.
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, MULTI_TENANT_TENANT_CAP_RETRY_AFTER_SECONDS). Desactivado por defecto. APPLICATION_NAME identifica el módulo ante Tenant Manager.
Streaming de eventos — STREAMING_* (productor de lib-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

Autenticación y manejo de peticiones

Base de datos (PostgreSQL)

Workers en segundo plano

Readiness y drenaje

Costura gRPC de reserva

Base de configuración compartida

​Puertos y endpoints de salud

​Despliegue y TLS

​Aplicación

​Autenticación y manejo de peticiones

​Base de datos (PostgreSQL)

​Workers en segundo plano

​Readiness y drenaje

​Costura gRPC de reserva

​Base de configuración compartida

Puertos y endpoints de salud

Despliegue y TLS

Aplicación

Autenticación y manejo de peticiones

Base de datos (PostgreSQL)

Workers en segundo plano

Readiness y drenaje

Costura gRPC de reserva

Base de configuración compartida