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. 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, multi-tenancy, 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 (opcional)	`TRACER_GRPC_PORT`	não definida (desligado)	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
`VERSION`	Tag de versão do serviço	varia	Não
`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 retornada quando nenhuma regra corresponde a uma transação. Apenas `ALLOW` (fail-open) e `DENY` (fail-closed) são aceitos: `REVIEW` é rejeitado 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`	Modo apenas validação: verifica as chaves sem aplicá-las de forma rígida	`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`.	— (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.	— (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. Essa integração é opcional e fail-open: uma falha de publicação ou de 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 `http://` explícita faz a inicialização falhar; use `https://`.	—	Não (necessária para publicar)
`IDP_M2M_CLIENT_ID`	Client ID usado para o token machine-to-machine da declaração.	—	Não (necessária para publicar)
`IDP_M2M_CLIENT_SECRET`	Secret usado para o token machine-to-machine da declaração. Sensível.	—	Não (necessária 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 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.

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_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. Desligado a menos que você defina TRACER_GRPC_PORT.

Variável	Descrição	Padrão	Obrigatória
`TRACER_GRPC_PORT`	Porta de escuta gRPC do servidor de reserva	não definida (desligado)	Não
`TRACER_TLS_MODE`	Segurança do elo: `mesh` (TLS terminado pelo service mesh) ou `mtls`	`mesh`	Não
`TRACER_TLS_CERT_FILE`	Caminho do PEM do certificado do servidor (quando `mtls`)	—	Não
`TRACER_TLS_KEY_FILE`	Caminho do PEM da chave privada do 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. 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. Em builds com descoberta habilitada (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. As builds atuais sempre usam PLUGIN_AUTH_ADDRESS.
Multi-tenancy: MULTI_TENANT_*, além dos parâmetros de pool por tenant do Tracer (MULTI_TENANT_MAX_TENANT_POOLS, MULTI_TENANT_MAX_OPEN_CONNS_PER_TENANT, TENANT_CAP_RETRY_AFTER_SECONDS). Desligado por padrão. APPLICATION_NAME identifica o módulo para o Tenant Manager.
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_* (produtor lib-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

Base de configuração compartilhada

​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

​Base de configuração compartilhada

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

Base de configuração compartilhada