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. 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, multi-tenancy, 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 (opt-in)	`TRACER_GRPC_PORT`	sin definir (desactivado)	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
`VERSION`	Etiqueta de versión del servicio	varía	No
`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 devuelta cuando ninguna regla coincide con una transacción. Solo se aceptan `ALLOW` (fail-open) y `DENY` (fail-closed): `REVIEW` se rechaza 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`	Modo de solo validación: verifica las claves sin aplicarlas de forma estricta	`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`.	— (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.	— (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. Esta integración es opcional y fail-open: una falla de publicación o configuración registra una advertencia y Tracer sigue funcionando.	`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://`.	—	No (necesaria para publicar)
`IDP_M2M_CLIENT_ID`	ID de cliente usado para el token machine-to-machine de la declaración.	—	No (necesaria para publicar)
`IDP_M2M_CLIENT_SECRET`	Secreto usado para el token machine-to-machine de la declaración. Sensible.	—	No (necesaria para publicar)

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_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. Desactivado a menos que definas TRACER_GRPC_PORT.

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

Base de configuración compartida

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. En los builds con descubrimiento habilitado (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. Los builds actuales siempre usan PLUGIN_AUTH_ADDRESS.
Multi-tenancy: MULTI_TENANT_*, además de 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. 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_* (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

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

Base de configuración compartida

​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

​Base de configuración compartida

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

Base de configuración compartida