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

# Trace Scrubbing

> Mascare campos selecionados nos traces armazenados usando o plugin trace_scrubbing no AI Gateway.

O **plugin** `trace_scrubbing` define o que o **AI Gateway** grava nos traces armazenados. Ele altera apenas a cópia armazenada, nunca a solicitação em tempo real, a resposta ou o payload que o provedor recebe. Consulte [Trace Data Masking](/docs/pt-BR/ai-gateway/features/security.md) para o campo `security` por solicitação, que alimenta o mesmo mascaramento.

## Casos de uso

* Manter o conteúdo dos prompts, a saída do modelo ou as variáveis de template fora do armazenamento de traces, sem alterar o que o modelo recebe.
* Preservar os dados de latência, tokens e custo em um trace, removendo o texto que os gerou.
* Aplicar uma única política de mascaramento em todo o workspace, em vez de adicionar `security.mask` a cada chamada, nas rotas listadas em [Endpoints compatíveis](#supported-endpoints).

## Comparação com o Trace Data Masking

O **Trace Scrubbing** (esta página) e o [Trace Data Masking](/docs/pt-BR/ai-gateway/features/security.md) decidem o que o **AI Gateway** grava em um trace armazenado. Eles mascaram os mesmos campos com o mesmo código; portanto, a diferença não está no que é mascarado, mas em onde a máscara é definida e em quem pode alterá-la.

**O que é igual**

* Ambos aceitam `input`, `output`, `system`, `metadata`, `variables` ou `all`.
* Ambos apagam ou removem esses campos apenas do trace armazenado. A solicitação em tempo real, a resposta, o payload que o provedor recebe e os dados verificados por [**Guardrails**](/docs/pt-BR/ai-gateway/configuration/guardrail-rules.md) e **Evaluators** permanecem intactos.
* Uma solicitação que envia os dois é mesclada: as máscaras se somam, e nenhum dos lados remove uma máscara definida pelo outro.

**O que difere**

| | `security.mask` em uma solicitação | Plugin `trace_scrubbing` |
| - | - | - |
| Onde é definido | No bloco `security` da solicitação | No array `plugins` da solicitação, em uma [regra de roteamento](/docs/pt-BR/ai-gateway/configuration/routing-rules.md#plugins), em um MCP gateway ou para todo o workspace em [**Settings** > **Plugins**](#enable-for-a-workspace) |
| Aplica-se sem que o chamador o envie | Não. Uma solicitação que omite o campo é registrada por completo, a menos que o workspace, uma regra ou um gateway adicione máscaras | Sim, nas configurações de workspace, de regra de roteamento e de MCP gateway; uma entrada `plugins` no escopo da solicitação ainda depende do chamador |
| Uma solicitação pode afrouxá-lo | Não se aplica: o chamador o define e, portanto, pode alterá-lo ou removê-lo a cada solicitação | Não. Uma solicitação pode adicionar máscaras, mas não pode remover uma definida pelo workspace, por uma regra ou por um gateway |
| Endpoints alcançados | Todos os endpoints em que é aplicado, incluindo `deployments/invoke`. [/classify](/docs/pt-BR/ai-gateway/features/decisions.md) o ignora, e `images/edits` e `moderations` o aceitam sem aplicá-lo | Os mesmos endpoints, além de `/classify` e invocações de deployments quando definido no workspace ou em uma regra de roteamento, e os traces de chamadas de ferramentas que um MCP gateway armazena; os traces de `images/edits`, `moderations` e das rotas WebSocket de `/responses` e `/responses/compact` permanecem sem máscara; consulte [Cobertura](/docs/pt-BR/ai-gateway/features/security.md#coverage) |
| Seleção vazia | Permitida, e não mascara nada | Uma entrada de solicitação sem valores em `mask` é aceita e não mascara nada; uma configuração de regra de roteamento ou de MCP gateway a rejeita. Um toggle de workspace sem valores selecionados mascara tudo |

**Qual usar**: `security.mask` é adequado para um chamador que protege o próprio tráfego, com o custo de enviar o campo em cada solicitação. `trace_scrubbing` é adequado para uma política que deve valer para todos, pois um administrador a define uma única vez para o workspace, uma regra ou um gateway, e nenhum chamador pode desativá-la.

## Início rápido

Adicione uma entrada `trace_scrubbing` ao array `plugins` com pelo menos um valor em `mask`.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "messages": [{ "role": "user", "content": "Summarize the open ticket." }],
    "plugins": [{ "id": "trace_scrubbing", "mask": ["input", "output"] }]
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: 'https://router.toqan.ai/eu/v3/router',
});

const response = await client.chat.completions.create({
  model: 'openai/gpt-5.4-mini',
  messages: [{ role: 'user', content: 'Summarize the open ticket.' }],
  // @ts-ignore - Toqan Router extension
  plugins: [{ id: 'trace_scrubbing', mask: ['input', 'output'] }],
});
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.chat.completions.create(
    model="openai/gpt-5.4-mini",
    messages=[{"role": "user", "content": "Summarize the open ticket."}],
    extra_body={"plugins": [{"id": "trace_scrubbing", "mask": ["input", "output"]}]},
)
```

Informe pelo menos um valor em `mask` na entrada: uma configuração de regra de roteamento ou de MCP gateway rejeita uma entrada sem valores. Uma entrada no escopo da solicitação sem valores é aceita pelo runtime e não mascara nada. A tabela [O que cada valor mascara](/docs/pt-BR/ai-gateway/features/security.md#what-each-value-masks) lista os valores aceitos e o que cada um remove de um trace armazenado.

## Ativar para um workspace

Ative o **Trace Scrubbing** em **Settings** > **Plugins** para aplicar uma máscara a todas as solicitações, sem passar um array `plugins` em cada chamada. Depois que o toggle estiver ativado, um ícone  aparece ao lado dele; clique nele para escolher as superfícies a mascarar. Ativar o plugin sem escolher nenhuma opção mascara tudo.

A configuração do workspace é um piso, não um padrão. As máscaras enviadas por uma solicitação são adicionadas às máscaras do workspace, e `all` prevalece sobre qualquer seleção mais restrita; assim, uma solicitação pode mascarar mais, mas nunca menos. Esse comportamento é igual ao da [redação de PII](/docs/pt-BR/ai-gateway/features/plugins/pii-redaction.md#workspace-level-redaction) no nível do workspace.

## Aplicar por regra de roteamento

Associe o **Trace Scrubbing** a uma [regra de roteamento](/docs/pt-BR/ai-gateway/configuration/routing-rules.md#plugins) para mascarar o tráfego que corresponde à regra, com os campos escolhidos na própria regra. Um MCP gateway aceita o mesmo plugin para os traces de chamadas de ferramentas que armazena.

## O que ele não faz

* Não remove nada da solicitação ou da resposta em tempo real, nem do payload que o provedor recebe.
* Não altera os dados que um Evaluator ou um Guardrail processa: a verificação continua recebendo a entrada, a saída, as instruções e as variáveis originais do runtime, e apenas o span persistido é limpo. Consulte [Trace scrubbing e dados de evaluators](/docs/pt-BR/ai-studio/observability/trace-evaluations.md#trace-scrubbing-and-evaluator-data).
* Não remove PII antes que o provedor a veja. Para isso, use [PII Redaction](/docs/pt-BR/ai-gateway/features/plugins/pii-redaction.md).

> [!NOTE]
>
> O scrubbing remove os valores mascarados do trace armazenado, em vez de apenas ocultá-los na visualização; por isso, não é possível depurar a solicitação a partir desses campos posteriormente. Quando o diagnóstico for importante, mantenha uma cópia não sanitizada em outro lugar ou restrinja a máscara aos campos que não podem ser armazenados.

## Endpoints compatíveis

A entrada `plugins` é aceita nos mesmos endpoints que os demais plugins; consulte Endpoints compatíveis. A configuração do workspace e a associação a uma regra de roteamento têm alcance maior: a máscara é gravada no trace armazenado de qualquer solicitação cujo handler registre opções de mascaramento, incluindo invocações de deployments e [/classify](/docs/pt-BR/ai-gateway/features/decisions.md), além dos traces de chamadas de ferramentas que um MCP gateway armazena. Uma rota que não registra nenhuma opção nunca passa por scrubbing, qualquer que seja a configuração: `images/edits`, `moderations` e as rotas WebSocket de `/responses` e `/responses/compact`.


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