Variáveis de ambiente

Referência das variáveis de ambiente do Tracer, cobrindo portas, TLS, PostgreSQL, autenticação, declaração de permissões da RI, workers em segundo plano, limites de custo CEL, o gRPC de reserva e multi-tenancy.

Esta referência lista as variáveis de ambiente usadas para configurar o Tracer, o serviço de controle de gastos e risco de transação em tempo real. Você as define no momento do deploy, por meio do ambiente do seu orquestrador. Variáveis marcadas como obrigatórias fazem o servidor falhar na inicialização se não forem definidas.

Na inicialização, o Tracer também verifica os valores abaixo. Quando uma verificação falha, o Tracer não inicia, e o erro informa o nome da variável.

• Uma variável booleana nas tabelas desta página aceita apenas true ou false. O Tracer não verifica ALLOW_INSECURE_TLS dessa forma.
• AUTH_TIMEOUT e AUTH_CACHE_TTL precisam de uma duração com unidade, como 60s.
• READYZ_DRAIN_GRACE_SECONDS, READYZ_CACHE_STALENESS_THRESHOLD_SECONDS, TENANT_CAP_RETRY_AFTER_SECONDS e as variáveis MULTI_TENANT_* que contêm uma contagem ou um número de segundos aceitam apenas um número inteiro, sem unidade.
• Quando AUTH_JWT_VERIFY_CERT está definida, ela deve conter chaves públicas RSA ou certificados em PEM. Quando ela está vazia e AUTH_JWT_VERIFY_CERT_PATH está definida, esse arquivo deve ser legível e conter essas chaves ou certificados.
• Cada entrada de TRUSTED_PROXIES deve ser um endereço IP ou um CIDR.
• Cada booleano ou número de STREAMING_* deve ser válido, e STREAMING_EVENT_POLICIES deve estar bem formada, também quando STREAMING_ENABLED=false.

Para os blocos de configuração compartilhados por todos os produtos Lerian, veja a referência de configuração BYOC. Esses blocos cobrem postura de TLS, OpenTelemetry, autenticação do Access Manager, descoberta de serviços e streaming de eventos. Esta página foca no que é específico do Tracer.

​

Portas e endpoints de saúde

Veja a referência de prontidão e disponibilidade para o contrato das sondas.

Superfície	Variável de porta	Padrão	Endpoints
REST + saúde	SERVER_PORT / SERVER_ADDRESS	4020	/health, /readyz, /version, /metrics
Elo gRPC de reserva	TRACER_GRPC_PORT	:4021	gRPC reserve / confirm / release

​

Deploy e TLS

Variável	Descrição	Padrão	Obrigatória
DEPLOYMENT_MODE	Variante de deploy: local, byoc ou saas. Em saas, o TLS na conexão com o PostgreSQL é validado na inicialização e o servidor se recusa a iniciar sem ele. Em byoc e local, essa verificação na inicialização é ignorada, mas a aplicação de TLS por conexão continua valendo, a menos que ALLOW_INSECURE_TLS=true. Também marca a resposta do /readyz.	local	Não
ALLOW_INSECURE_TLS	Ignora a aplicação de TLS por conexão em DSNs de infraestrutura. Deixe sem definir ou como false em produção.	false	Não

​

Aplicação

Variável	Descrição	Padrão	Obrigatória
LOG_LEVEL	Verbosidade do log: debug, info, warn ou error	debug	Não
CEL_COST_LIMIT	Custo máximo de avaliação para uma única expressão de regra CEL	10000	Não
OPENAPI_DOCS_ENABLED	Publica a especificação OpenAPI 3.1 e a documentação interativa do Scalar em /v1/openapi.{json,yaml} e /v1/docs	false	Não

​

Avaliação de regras

Variável	Descrição	Padrão	Obrigatória
DEFAULT_DECISION_WHEN_NO_MATCH	Decisão que uma validação retorna quando nenhuma regra corresponde. Apenas ALLOW (fail-open) e DENY são aceitos. O Tracer rejeita REVIEW propositalmente, e qualquer outro valor faz o serviço falhar na inicialização. Deixar sem definir mantém ALLOW e registra um aviso na inicialização.	ALLOW	Não
MAX_RULES_PER_REQUEST	Teto de quantas regras ativas são avaliadas em uma única validação. Quando mais regras se aplicam, o excesso é truncado (um aviso é registrado) e a resposta reporta totalRulesLoaded com truncated: true. Deve ser positivo e no máximo 100000; um valor inválido faz o serviço falhar na inicialização.	1000	Não

​

Autenticação e tratamento de requisições

Variável	Descrição	Padrão	Obrigatória
API_KEY_ENABLED	Exige autenticação por chave de API	false	Não
API_KEY	Chave de API para autenticação de requisições. Sensível. Use pelo menos 32 caracteres em produção.	—	Sim (se API_KEY_ENABLED=true)
API_KEY_ENABLED_ONLY_VALIDATION	Autentica POST /v1/validations e POST /v1/validations/rules-only com a API key em vez do Access Manager. Essas rotas conferem a chave apenas quando API_KEY_ENABLED=true. O Tracer não inicia com esta variável quando MULTI_TENANT_ENABLED=true.	false	Não
API_KEY_LABEL	Identificador de ator registrado na auditoria para o principal da chave de API	tracer-default	Não
CORS_ALLOWED_ORIGINS	Origens de CORS permitidas (CSV). Quando não definida ou vazia, requisições entre origens não são permitidas; defina uma allow-list explícita em produção. O valor explícito * é rejeitado na inicialização quando API_KEY_ENABLED=true.	não definida (nenhuma requisição entre origens é permitida)	Não
TRUSTED_PROXY_CIDRS	CIDRs de proxies confiáveis para a leitura do X-Forwarded-For. Defina quando estiver atrás de um balanceador de carga.	não definida (usa o IP do peer)	Não

​

Declaração de permissões da RI

Variável	Descrição	Padrão	Obrigatória
IDP_DECLARATION_ENABLED	Publica a declaração de permissões do Tracer no serviço de identidade na inicialização. Com true, o Tracer não inicia quando IDP_HOST, IDP_M2M_CLIENT_ID ou IDP_M2M_CLIENT_SECRET está vazia. Uma falha de publicação não para o Tracer.	false	Não
IDP_HOST	URL absoluta do serviço de identidade (diferente do endereço do Access Manager em PLUGIN_AUTH_ADDRESS). Quando a declaração está habilitada em saas, uma URL http:// explícita faz a inicialização falhar; use https://.	—	Sim (se IDP_DECLARATION_ENABLED=true)
IDP_M2M_CLIENT_ID	Client ID usado para o token machine-to-machine da declaração.	—	Sim (se IDP_DECLARATION_ENABLED=true)
IDP_M2M_CLIENT_SECRET	Secret usado para o token machine-to-machine da declaração. Sensível.	—	Sim (se IDP_DECLARATION_ENABLED=true)

​

Banco de dados (PostgreSQL)

O Tracer armazena regras e contadores de uso em seu próprio banco de dados tracer no primário do PostgreSQL compartilhado do Midaz. Uma imagem dedicada de execução de migrações aplica a migração de esquema antes de a aplicação iniciar. O serviço inicia sobre um esquema já migrado e não executa migrações em processo.

Planeje uma janela de manutenção para o upgrade para o Midaz v4.2.0. A migração 000025 dessa versão amplia a coluna de ativo da tabela de histórico de validações. O PostgreSQL reescreve essa tabela e recria os índices dela sob um lock exclusivo, então leituras e escritas de validações esperam até o fim. A duração cresce com o número de validações armazenadas.

Cada migração espera no máximo 5 segundos pelo lock e falha com SQLSTATE 55P03 quando o tráfego o mantém. Rode-a de novo em uma janela mais tranquila. Uma segunda execução é segura.

Variável	Descrição	Padrão	Obrigatória
DB_HOST	Host do PostgreSQL	—	Sim
DB_PORT	Porta do PostgreSQL	—	Sim
DB_USER	Usuário do banco de dados	—	Sim
DB_PASSWORD	Senha do banco de dados. Sensível.	—	Sim
DB_NAME	Nome do banco de dados	—	Sim
DB_SSL_MODE	Modo SSL do libpq: disable, require, verify-ca ou verify-full. Use require ou mais forte em produção.	disable	Não

​

Workers em segundo plano

Variável	Descrição	Padrão	Obrigatória
CLEANUP_WORKER_ENABLED	Executa o worker de limpeza de contadores de uso expirados	false	Não
CLEANUP_INTERVAL_HOURS	Intervalo de limpeza (horas). A própria janela de retenção é fixa em 90 dias e não é configurável.	24	Não
RULE_SYNC_POLL_INTERVAL_SECONDS	Intervalo de verificação da sincronização do cache de regras (segundos)	10	Não
RULE_SYNC_STALENESS_THRESHOLD_SECONDS	Limiar de desatualização do cache de regras (segundos)	50	Não
RULE_SYNC_OVERLAP_BUFFER_SECONDS	Margem de sobreposição da sincronização do cache de regras (segundos)	2	Não

​

Reservas

Variável	Descrição	Padrão	Obrigatória
RESERVATION_REAPER_ENABLED	Executa o worker que expira reservas após o tempo de vida delas e devolve a capacidade retida	true	Não
RESERVATION_REAPER_INTERVAL_SECONDS	Intervalo de varredura do reaper de reservas (segundos). Deve ser de 1 a 3600; um valor inválido faz o serviço falhar na inicialização.	30	Não
RESERVATION_LONG_LIVED_TTL_HOURS	Tempo de vida registrado em uma reserva que o ledger mantém para uma transação pendente (horas). Deve ser positivo e no máximo 8760; um valor inválido faz o serviço falhar na inicialização. Reservas de transações diretas têm um tempo de vida fixo que essa variável não altera.	720	Não

​

Prontidão e drenagem

Variável	Descrição	Padrão	Obrigatória
READYZ_DRAIN_GRACE_SECONDS	Janela durante a qual /readyz retorna 503 após SIGTERM, para que o Kubernetes remova o pod do registro antes do desligamento	12	Não
READYZ_CACHE_STALENESS_THRESHOLD_SECONDS	Idade do cache de regras a partir da qual /readyz reporta degraded	300	Não

​

Elo gRPC de reserva

Lado servidor do elo que o ledger do Midaz chama para reservar limites de gastos.

O Tracer sempre abre a porta de reserva, :4021 por padrão. Proteja-a com autenticação do Access Manager (PLUGIN_AUTH_ENABLED), uma chave de API (API_KEY_ENABLED), TLS mútuo (TRACER_TLS_MODE=mtls) ou sua service mesh. Fora de DEPLOYMENT_MODE=saas e do modo multi-tenant, o Tracer inicia sem nenhuma dessas proteções, e qualquer workload que alcance a porta pode reservar e liberar capacidade de limite.

Variável	Descrição	Padrão	Obrigatória
TRACER_GRPC_PORT	Endereço de escuta gRPC do elo de reserva	:4021	Não
TRACER_TLS_MODE	Modo de transporte do elo: mtls, server, mesh ou vazio	vazio	Não
TRACER_TLS_CERT_FILE	Caminho do PEM do certificado do servidor	—	Sim (se TRACER_TLS_MODE for mtls ou server)
TRACER_TLS_KEY_FILE	Caminho do PEM da chave privada do servidor. Sensível.	—	Sim (se TRACER_TLS_MODE for mtls ou server)
TRACER_TLS_CLIENT_CA_FILE	Caminho do PEM do certificado CA de cliente	—	Sim (se TRACER_TLS_MODE=mtls)
TRACER_TLS_CLIENT_ALLOWED_NAMES	Nomes de certificado de cliente separados por vírgula para o modo mtls	—	Não
TRACER_SEAM_ALLOWED_CLIENTS	IDs de cliente de aplicação do Access Manager separados por vírgula para o elo, lidos quando PLUGIN_AUTH_ENABLED=true. O Tracer ignora essa variável no modo multi-tenant.	—	Sim (se PLUGIN_AUTH_ENABLED=true no modo single-tenant, fora de DEPLOYMENT_MODE=local)
AUTH_M2M_INVERSION_ENABLED	Defina como true quando PLUGIN_AUTH_ENABLED=true. Caso contrário, o Access Manager autoriza tokens de aplicação sob um único papel compartilhado, e apenas TRACER_SEAM_ALLOWED_CLIENTS limita quais aplicações podem reservar.	false	Não
AUTH_CACHE_TTL	Tempo de vida do cache de decisões do Access Manager, como duração com unidade, por exemplo 60s	não definida (sem cache)	Sim (se PLUGIN_AUTH_ENABLED=true com DEPLOYMENT_MODE=saas)
AUTH_BREAKER_ENABLED	Circuit breaker nas chamadas ao Access Manager	não definida (desligado)	Não
AUTH_JWT_VERIFY_CERT	Chaves públicas ou certificados PEM para assinaturas de token	—	Não

​

Multi-tenancy

Variável	Descrição	Padrão	Obrigatória
MULTI_TENANT_ENABLED	Ativa o modo multi-tenant. Nesse modo, o Tracer não inicia sem PLUGIN_AUTH_ENABLED=true.	false	Não
MULTI_TENANT_URL	URL do Tenant Manager, com esquema e host. O Tracer não inicia com uma URL http://, a menos que MULTI_TENANT_ALLOW_INSECURE_HTTP=true.	—	Sim (se MULTI_TENANT_ENABLED=true)
MULTI_TENANT_SERVICE_API_KEY	Chave de API do Tenant Manager. Sensível.	—	Sim (se MULTI_TENANT_ENABLED=true)
MULTI_TENANT_REDIS_HOST	Host do Redis que transporta os eventos de tenant.	—	Sim (se MULTI_TENANT_ENABLED=true)
MULTI_TENANT_REDIS_PORT	Porta do Redis de eventos de tenant.	6379	Não
MULTI_TENANT_REDIS_PASSWORD	Senha do Redis de eventos de tenant. Sensível.	—	Não
MULTI_TENANT_REDIS_TLS	Usa TLS no Redis de eventos de tenant.	true	Não
MULTI_TENANT_MAX_TENANT_POOLS	Número máximo de tenants com workers em execução em uma instância do Tracer.	100	Não
MULTI_TENANT_IDLE_TIMEOUT_SEC	Tempo ocioso depois do qual o Tracer pode fechar um pool de banco de dados de tenant (segundos).	300	Não
MULTI_TENANT_TIMEOUT	Tempo limite de uma chamada ao Tenant Manager (segundos).	30	Não
MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD	Falhas antes que o circuit breaker do Tenant Manager abra.	5	Não
MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC	Tempo até o circuit breaker do Tenant Manager tentar de novo (segundos).	30	Não
MULTI_TENANT_CACHE_TTL_SEC	Por quanto tempo o Tracer guarda uma configuração de tenant (segundos).	120	Não
MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC	Intervalo entre as verificações das configurações dos pools de tenant (segundos).	30	Não
MULTI_TENANT_ALLOW_INSECURE_HTTP	Aceita uma MULTI_TENANT_URL http://. Deixe sem definir ou como false em produção.	false	Não
TENANT_CAP_RETRY_AFTER_SECONDS	Valor de Retry-After, em segundos, do HTTP 503 com código 0466 que o Tracer retorna quando atinge MULTI_TENANT_MAX_TENANT_POOLS.	5	Não

​

Configuração compartilhada entre produtos

Os blocos a seguir são idênticos entre os produtos Lerian. A referência de configuração BYOC os documenta por completo. Eles vêm desligados por padrão.

• Autenticação do Access Manager: PLUGIN_AUTH_ENABLED, PLUGIN_AUTH_ADDRESS. Habilite em produção. Com a descoberta de serviços ligada (veja Descoberta de serviços abaixo), o Tracer resolve o host do Access Manager por meio do Consul. Ele recorre a PLUGIN_AUTH_ADDRESS se a resolução falhar.
• Descoberta de serviços: SD_* (Consul). Desligado por padrão. Quando SD_ENABLED=true, o Tracer se registra como midaz-tracer (anunciando a porta HTTP a partir de SERVER_ADDRESS, padrão 4020) e resolve o Access Manager por meio do Consul. Se essa resolução falhar, ele recorre ao PLUGIN_AUTH_ADDRESS estático. A descoberta exige SD_EXTERNAL_ADDRESS ou SD_INTERNAL_ADDRESS. O Tracer é o servidor no elo gRPC de reserva e não o anuncia.
• Streaming de eventos: STREAMING_*. Desligado por padrão.
• OpenTelemetry: ENABLE_TELEMETRY, OTEL_*. O Tracer também expõe um endpoint Prometheus /metrics.