Variáveis de ambiente

Esta referência lista as variáveis de ambiente usadas para configurar o Tracer, o serviço de controle de gastos em tempo real e de análise de risco de transações. Você as define no momento da implantação, por valores Helm, Docker Compose ou pelo ambiente do seu orquestrador. Variáveis marcadas como obrigatórias fazem o servidor falhar na inicialização se não forem definidas. Para os blocos de configuração que todo produto Lerian compartilha — postura de TLS, OpenTelemetry, autenticação do Access Manager, multi-tenancy, descoberta de serviços e streaming de eventos — veja a referência de configuração BYOC. Esta página foca no que é distintivo do Tracer.

Portas e endpoints de saúde

Veja a referência de saúde e prontidão para o contrato de sondas.

Superfície	Variável de porta	Padrão	Endpoints
REST + saúde	`SERVER_PORT` / `SERVER_ADDRESS`	`4020`	`/health`, `/readyz`, `/version`, `/metrics`
Seam gRPC de reserva (opt-in)	`TRACER_GRPC_PORT`	sem definir (desligado)	gRPC reserve / confirm / release

Implantação e TLS

Variável	Descrição	Padrão	Obrigatória
`DEPLOYMENT_MODE`	Sabor de implantação: `local`, `byoc` ou `saas`. Em `saas`, o TLS da 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 de inicialização é pulada, mas a imposição de TLS por conexão continua valendo, a menos que `ALLOW_INSECURE_TLS=true`. Também marca a resposta de `/readyz`.	`local`	Não
`ALLOW_INSECURE_TLS`	Ignora a imposição de TLS por conexão nas DSNs de infraestrutura. Deixe sem definir ou `false` em produção.	`false`	Não

Aplicação

Variável	Descrição	Padrão	Obrigatória
`VERSION`	Tag de versão do serviço	varia	Não
`LOG_LEVEL`	Verbosidade dos logs: `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`	Serve 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 retornada quando nenhuma regra corresponde a uma transação. Apenas `ALLOW` (fail-open) e `DENY` (fail-closed) são aceitos — `REVIEW` é rejeitado de propósito, 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 excedente é truncado (um aviso é registrado) e a resposta informa `totalRulesLoaded` com `truncated: true`. Deve ser positiva 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`	Impõe a 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`	Modo somente validação: verifica as chaves sem impô-las rigidamente	`false`	Não
`API_KEY_LABEL`	Identificador de ator de auditoria registrado para o principal da chave de API	`tracer-default`	Não
`CORS_ALLOWED_ORIGINS`	Origens CORS permitidas (CSV). Sem definir ou vazia, requisições cross-origin não são permitidas; defina uma lista explícita de origens permitidas em produção. O valor explícito `*` é rejeitado no boot quando `API_KEY_ENABLED=true`.	— (requisições cross-origin não são permitidas)	Não
`TRUSTED_PROXY_CIDRS`	CIDRs de proxy confiáveis para a análise de `X-Forwarded-For`. Defina ao rodar atrás de um load balancer.	— (usa o IP do peer)	Não

Declaração de permissões 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 no boot. Essa integração é opcional e fail-open: uma falha de publicação ou configuração registra um aviso e o Tracer continua atendendo.	`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 explícita `http://` faz o boot falhar; use `https://`.	—	Não (necessária para publicar)
`IDP_M2M_CLIENT_ID`	ID de cliente usado para o token máquina a máquina da declaração.	—	Não (necessário para publicar)
`IDP_M2M_CLIENT_SECRET`	Segredo usado para o token máquina a máquina da declaração. Sensível.	—	Não (necessário para publicar)

Banco de dados (PostgreSQL)

O Tracer armazena regras e contadores de uso em seu próprio banco de dados tracer no primário PostgreSQL compartilhado do Midaz. A migração de esquema é aplicada por uma imagem dedicada de migration-runner antes de a aplicação iniciar; o serviço sobe contra um esquema já migrado e não executa migrações no processo.

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 background

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 janela de retenção em si é fixa em 90 dias e não é configurável.	`24`	Não
`RULE_SYNC_POLL_INTERVAL_SECONDS`	Intervalo de poll de sincronização do cache de regras (segundos)	`10`	Não
`RULE_SYNC_STALENESS_THRESHOLD_SECONDS`	Limiar de obsolescência do cache de regras (segundos)	`50`	Não
`RULE_SYNC_OVERLAP_BUFFER_SECONDS`	Buffer de sobreposição da sincronização do cache de regras (segundos)	`2`	Não

Reservas

Variável	Descrição	Padrão	Obrigatória
`RESERVATION_LONG_LIVED_TTL_HOURS`	Duração registrada em uma reserva que o ledger mantém para uma transação pendente (horas). Deve ser positiva e no máximo `8760`; um valor inválido faz o serviço falhar na inicialização. As reservas de transações diretas têm uma duração fixa que esta 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 o SIGTERM, para que o Kubernetes desregistre o pod antes do desligamento	`12`	Não
`READYZ_CACHE_STALENESS_THRESHOLD_SECONDS`	Idade do cache de regras na qual `/readyz` reporta `degraded`	`300`	Não

Seam gRPC de reserva

Lado servidor do seam que o ledger do Midaz chama para reservar limites de gasto. Desligado a menos que TRACER_GRPC_PORT esteja definido.

Variável	Descrição	Padrão	Obrigatória
`TRACER_GRPC_PORT`	Porta de escuta gRPC do servidor de reserva	sem definir (desligado)	Não
`TRACER_TLS_MODE`	Segurança do seam: `mesh` (TLS terminado pelo service mesh) ou `mtls`	`mesh`	Não
`TRACER_TLS_CERT_FILE`	Caminho do PEM do certificado de servidor (quando `mtls`)	—	Não
`TRACER_TLS_KEY_FILE`	Caminho do PEM da chave privada de servidor (quando `mtls`). Sensível.	—	Não
`TRACER_TLS_CLIENT_CA_FILE`	Caminho do PEM do certificado CA de cliente para verificação mútua (quando `mtls`)	—	Não

Base de configuração compartilhada

Os blocos a seguir são idênticos entre os produtos Lerian e estão documentados por completo na referência de configuração BYOC. Eles vêm desativados.

Autenticação do Access Manager — PLUGIN_AUTH_ENABLED, PLUGIN_AUTH_ADDRESS. Ative em produção. Em builds com descoberta habilitada (veja Descoberta de serviços abaixo), o Tracer resolve o host do Access Manager via Consul e recorre a PLUGIN_AUTH_ADDRESS se a resolução falhar; os builds atuais sempre usam PLUGIN_AUTH_ADDRESS.
Multi-tenancy — MULTI_TENANT_*, mais os botões de pool por tenant do Tracer (MULTI_TENANT_MAX_TENANT_POOLS, MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT, TENANT_CAP_RETRY_AFTER_SECONDS). Desativado por padrão. APPLICATION_NAME identifica o módulo para o Tenant Manager.
Descoberta de serviços — SD_* (Consul). Desativada por padrão. Quando SD_ENABLED=true, o Tracer se registra como midaz-tracer (anunciando a porta HTTP de SERVER_ADDRESS, padrão 4020) e resolve o Access Manager via Consul; se essa resolução falhar, recorre ao PLUGIN_AUTH_ADDRESS estático. SD_EXTERNAL_ADDRESS ou SD_INTERNAL_ADDRESS é obrigatório quando a descoberta está habilitada. A costura gRPC de reserva não é anunciada: o Tracer é o servidor nessa costura.
Streaming de eventos — STREAMING_* (produtor lib-streaming). Desativado por padrão.
OpenTelemetry — ENABLE_TELEMETRY, OTEL_*. O Tracer também expõe um endpoint /metrics do Prometheus.

Visão geral

Guias

Console

Operações

Variáveis de ambiente

Portas e endpoints de saúde

Implantação e TLS

Aplicação

Avaliação de regras

Autenticação e tratamento de requisições

Declaração de permissões RI

Banco de dados (PostgreSQL)

Workers em background

Reservas

Prontidão e drenagem

Seam gRPC de reserva

Base de configuração compartilhada

​Portas e endpoints de saúde

​Implantação e TLS

​Aplicação

​Avaliação de regras

​Autenticação e tratamento de requisições

​Declaração de permissões RI

​Banco de dados (PostgreSQL)

​Workers em background

​Reservas

​Prontidão e drenagem

​Seam gRPC de reserva

​Base de configuração compartilhada

Portas e endpoints de saúde

Implantação e TLS

Aplicação

Avaliação de regras

Autenticação e tratamento de requisições

Declaração de permissões RI

Banco de dados (PostgreSQL)

Workers em background

Reservas

Prontidão e drenagem

Seam gRPC de reserva

Base de configuração compartilhada