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 e risco de transação em tempo real. Você as define no momento do deploy, por meio de valores do Helm, do Docker Compose ou 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.

Visão geral

Guias

Console

Operações

Variáveis de ambiente

Portas e endpoints de saúde

Deploy e TLS

Aplicação

Avaliação de regras

Autenticação e tratamento de requisições

Declaração de permissões da RI

Banco de dados (PostgreSQL)

Workers em segundo plano

Reservas

Prontidão e drenagem

Elo gRPC de reserva

Multi-tenancy

Configuração compartilhada entre produtos

​Portas e endpoints de saúde

​Deploy e TLS

​Aplicação

​Avaliação de regras

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

​Declaração de permissões da RI

​Banco de dados (PostgreSQL)

​Workers em segundo plano

​Reservas

​Prontidão e drenagem

​Elo gRPC de reserva

​Multi-tenancy

​Configuração compartilhada entre produtos

Portas e endpoints de saúde

Deploy e TLS

Aplicação

Avaliação de regras

Autenticação e tratamento de requisições

Declaração de permissões da RI

Banco de dados (PostgreSQL)

Workers em segundo plano

Reservas

Prontidão e drenagem

Elo gRPC de reserva

Multi-tenancy

Configuração compartilhada entre produtos