> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://docs.lerian.studio/pt/reference/byoc-configuration.md). 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](https://docs.lerian.studio/pt/reference/health-and-readiness.md) 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.

> [!WARNING]
>
> 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](https://docs.lerian.studio/pt/reference/byoc-configuration.md) 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`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.