> ## 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.

# O que é o Tracer?

> Valide transações em tempo real com o Tracer: aplique limites de gastos, detecte atividade não autorizada e decida allow/deny em menos de 100ms.

O **Tracer** é a plataforma da Lerian para validação de transações em tempo real e controles de gastos. Ele ajuda instituições financeiras a aplicar políticas de gastos, detectar transações não autorizadas e manter registros de compliance prontos para auditoria. O Tracer faz isso em tempo real, antes de a transação ser executada.

No Midaz v4, o Tracer é distribuído no release do Midaz. Ele continua sendo um runtime e um deploy separados do serviço de Ledger. O chart do Midaz o instala como um componente opcional: consulte o [README do chart do Midaz](https://github.com/LerianStudio/helm/tree/main/charts/midaz).

## O Tracer em um core banking completo

***

O Tracer é uma das peças de um core banking Lerian, sua camada de controle em tempo real. Um ledger registra o que aconteceu. O Tracer decide o que pode acontecer primeiro. Nesse fluxo, antes de sua aplicação registrar uma transação no Midaz, ela chama o Tracer para conferir o movimento contra suas regras e limites de gastos. Sua aplicação envia ao ledger apenas se a decisão for `ALLOW`, então movimentos não autorizados ou acima do limite nunca chegam ao ledger.

O Tracer permanece separado do ledger. Ele nunca inicia uma chamada ao Midaz e nunca lê saldos. Ele avalia o contexto que recebe, registra o histórico de validações e gerencia o estado da reserva. Por padrão, sua aplicação orquestra os dois, enviando ao ledger apenas em caso de `ALLOW`.

O Midaz também pode chamar o Tracer diretamente por meio de um elo de reserva opcional por ledger ([reservation seam](https://docs.lerian.studio/pt/products/tracer/integration-guide.md#midaz-ledger-reservation-seam)), que vem desligado por padrão. Nesse elo, o caminho de transação do Ledger HTTP v2 pede ao Tracer que avalie suas regras e retenha capacidade do limite antes de confirmar uma transação. Depois, ele confirma ou libera a retenção. A API HTTP pública do Tracer permanece `/v1`. O elo não é uma API pública Tracer v2.

Apenas o caminho de transação do Ledger HTTP v2 aciona o elo. O Ledger HTTP v1 nunca o faz. Nos dois fluxos, as chamadas seguem em direção ao Tracer. O Tracer não chama de volta o Midaz.

Para onde isso se encaixa no quadro geral, veja [Construindo um core banking completo](https://docs.lerian.studio/pt/products/building-a-complete-core-banking.md).

## Por que usar o Tracer?

***

Instituições financeiras precisam controlar como o dinheiro se move: aplicar tetos de gastos, bloquear transações não autorizadas e produzir trilhas de auditoria para reguladores. Fazer isso manualmente ou por processos em lote gera atrasos, erros e lacunas de compliance.

O Tracer resolve isso avaliando cada transação em tempo real contra suas políticas. Ele oferece duas capacidades:

* **Regras de validação**: regras de negócio que avaliam o contexto da transação e retornam decisões instantâneas, sem exigir deploys de código. Você define regras como expressões, então analistas e times de compliance podem usá-las sem escrever código.
* **Limites de gastos dinâmicos**: limites configuráveis por transação, por conta, por portfólio, por segmento ou por comerciante, com rastreamento de uso em tempo real e reinício automático de período.

### Resolvendo desafios de controle e compliance

O Tracer ajuda instituições a avaliar políticas de gastos, identificar transações não autorizadas e atender exigências de auditoria.

## Principais capacidades

***

* Validação em tempo real com tempos de resposta abaixo de 80ms (p99)
* Motor de regras baseado em expressões usando CEL (Common Expression Language) (Uma linguagem de expressão leve para escrever regras de negócio, por exemplo, 'if transaction amount > 10000 then REVIEW'. O Tracer usa CEL para regras de validação.) para regras type-safe e acessíveis a analistas
* Design agnóstico de produto, que aceita qualquer esquema de pagamento, por exemplo:
  * Transações de cartão (débito, crédito, pré-pago)
  * Transferências (domésticas, internacionais, ACH)
  * Pix (instantâneo, agendado)
  * Criptomoeda (bitcoin, ethereum, stablecoin)
* Limites de gastos dinâmicos:
  * Por transação, conta, portfólio, segmento ou comerciante
  * Períodos diário, semanal, mensal, personalizado ou por transação
* Rastreamento de uso do limite em tempo real, com reinício automático de período
* Trilha de auditoria encadeada por hash
* Padrão configurável para ausência de correspondência (`DEFAULT_DECISION_WHEN_NO_MATCH`): quando nenhuma regra corresponde a uma requisição de validação, o Tracer retorna o padrão configurado (ALLOW para fail-open, DENY para fail-closed). Falhas de infraestrutura aparecem como erros HTTP. O sistema que chama decide o comportamento de fallback.

## Como funciona

***

O Tracer tem quatro contextos principais:

1. **Validation Context** - orquestra requisições de validação, coordena a avaliação de regras e limites, e registra a trilha de auditoria.
2. **Rules Context** - gerencia definições de regra, compila expressões e avalia regras contra o contexto da transação.
3. **Limits Context** - gerencia configurações de limite de gastos, rastreia contadores de uso e aplica os tetos.
4. **Audit Context** - mantém o log de eventos imutável e verifica sua cadeia de hash.

**Seu sistema deve agir sobre a decisão de validação** (por exemplo, bloqueando a transação, mostrando um erro ao usuário, ou colocando-a em fila para revisão).

### Quem faz o quê

O Tracer se posiciona entre vários times. Cada time é dono de uma parte diferente do ciclo:

| Ator | O que faz | Toca em |
| - | - | - |
| **Analista de risco/fraude** | Escreve e ajusta regras ("negar Pix acima de R\$ 50 mil de contas novas") | `POST /v1/rules`, `/v1/rules/{id}/activate`, revisão da trilha de auditoria |
| **Gerente de produto/risco** | Configura limites de gastos por segmento, portfólio, conta | `POST /v1/limits`, endpoints de ciclo de vida, monitoramento de uso |
| **Engenheiro de integração** | Constrói a chamada do sistema de autorização para o Tracer | `POST /v1/validations`, tratamento de retry/timeout/fallback |
| **Sistema de autorização** | Envia toda transação para validação, age sobre ALLOW/DENY/REVIEW | Chama `POST /v1/validations` no caminho crítico |
| **Ledger do Midaz** (elo opcional) | Quando o elo de reserva por ledger está habilitado, pede ao Tracer que avalie regras e retenha capacidade do limite antes de confirmar, depois liquida a retenção | A chamada gRPC `Reserve`, depois as transições de confirmação/liberação |
| **Tracer** | Avalia regras e limites, registra o resultado, retorna a decisão | Executa internamente e nunca chama de volta |
| **Compliance/auditoria** | Consulta a trilha, verifica a integridade da cadeia de hash | `GET /v1/validations`, `/v1/audit-events`, `/v1/audit-events/{id}/verify` |
| **SRE/plataforma** | Monitora latência, capacidade, prontidão | Observa `/readyz`, métricas OTel, taxas de erro |

Uma requisição típica flui assim: **sistema de autorização → Tracer (avalia regras + confere limites → decisão) → log de auditoria → resposta de volta ao sistema de autorização**. Os times de risco e produto configuram as definições de regra e limite com antecedência. O compliance lê o log de auditoria depois. O Tracer nunca volta a acessar sua stack. Não há webhooks nem callbacks.

> [!NOTE]
>
> Valores monetários (o `amount` da transação, o `maxAmount` do limite de gastos e os contadores de uso) usam strings decimais, por exemplo `"1500.00"` ou `"50000.00"`.

## Quando usar o Tracer

***

O Tracer se encaixa em qualquer fluxo em que você precise controlar como o dinheiro se move pela sua instituição.

* **Governança de gastos**: avalia transações contra políticas de gastos internas ou de nível de cliente
* **Validação de transação**: avalia regras de negócio personalizadas e retorna decisões antes da execução da transação
* **Compliance regulatório**: produz logs prontos para auditoria e garante rastreabilidade
* **Proteção ao cliente**: detecta gastos excessivos e retorna decisões sobre as quais seu sistema pode agir

## Escopo e princípios de design

***

O Tracer é um motor de validação de transações, e a gestão completa de fraude fica fora do seu escopo. É um componente especializado, otimizado para decisões de baixa latência (\< 100ms), que valida payloads pré-enriquecidos contra regras e limites configuráveis.

### No que o Tracer foca

* **Validação baseada em regras**: lógica determinística, baseada em expressões, usando CEL
* **Limites de gastos**: aplicação em tempo real com reinício automático de período
* **Trilha de auditoria**: registros imutáveis
* **Decisões de baixa latência**: respostas de API síncronas abaixo de 80ms (p99)

### O que o Tracer não inclui

| Capacidade | Motivo | Alternativa |
| - | - | - |
| **Pontuação por machine learning** | A inferência de ML adiciona latência incompatível com a meta de sub-100ms | Integre serviços externos de ML a montante e passe as pontuações via metadados |
| **Enriquecimento de dados** | Chamadas externas durante a validação quebram as garantias de latência | Enriqueça os payloads na sua integração antes de chamar o Tracer |
| **Fluxos de revisão manual** | A gestão de casos está fora do escopo central de validação | Construa filas de revisão no seu sistema e use a decisão `REVIEW` como gatilho |
| **Interface de usuário** | O design API-first permite integração flexível | Construa interfaces personalizadas ou use ferramentas de terceiros |
| **Execução de pagamento** | O Tracer retorna decisões de validação; ele não movimenta fundos | Execute ou bloqueie pagamentos no sistema a montante com base na decisão |

> [!TIP]
>
> Essas fronteiras mantêm o Tracer rápido e previsível: ele retorna decisões de transação instantâneas com trilhas de auditoria.

## Integração

***

Seu sistema de autorização envia requisições de validação com o contexto completo da transação, e o Tracer responde com uma decisão, tipicamente em menos de 35ms.

Com este **Payload-Complete Pattern**, todo o contexto que o Tracer precisa chega em uma única requisição. Não há chamadas externas durante a validação, e a latência permanece previsível.

> [!NOTE]
>
> Na Lerian Cloud, o Tracer limita cada requisição ao seu tenant a partir do seu token. Veja [Access Manager](https://docs.lerian.studio/pt/platform/access-manager.md) para o fluxo de autenticação.

Como todos os produtos Lerian, o Tracer vem com integração nativa ao [Access Manager](https://docs.lerian.studio/pt/platform/access-manager.md). Quando habilitado, o Access Manager cuida da autenticação e autorização das APIs do Tracer.

O Tracer declara cinco grupos de acesso no Access Manager:

* `tracer-viewer-group`: leitura de regras, limites, validações, da trilha de auditoria, do dashboard e do catálogo de eventos.
* `tracer-contributor-group`: leitura, criação e alteração de regras e limites.
* `tracer-validator-group`: validação de transações e leitura de validações e do dashboard.
* `tracer-audit-viewer-group`: leitura da trilha de auditoria e do dashboard.
* `tracer-editor-group`: todas as ações dos outros grupos, e exclusão de regras e limites.

O grupo de administradores do Access Manager (`admin-group`) tem o mesmo acesso que o `tracer-editor-group`.

## Próximos passos

***

> [card] [Explore a API do Tracer](https://docs.lerian.studio/pt/reference/products/tracer/tracer-api-quick-start.md)
>
> Navegue pelos endpoints de regras de validação, limites de gastos e trilhas de auditoria.

> [card] [Primeiros passos](https://docs.lerian.studio/pt/products/tracer/getting-started.md)
>
> Configure o Tracer e defina sua primeira regra de autorização.


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