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

# Referência de atributos de span do Toqan Router

> Referência completa dos atributos de span do OpenTelemetry orq.*. Encontre todos os atributos emitidos pelo Toqan Router em traces, payloads de webhooks e exportações de traces.

Os atributos `orq.*` são atributos de span do OpenTelemetry emitidos pelo **Toqan Router** em cada span de trace. Eles aparecem no painel [**Traces**](/docs/pt-BR/ai-studio/observability/traces.md), nos payloads de webhooks de LLM e nas exportações de traces. Os atributos principais aparecem em todos os spans; os atributos das seções **Recursos invocados**, **Evaluators** e **Roteamento** aparecem somente quando o recurso correspondente estava ativo.

## Referência rápida

| O que encontrar | Atributos |
| - | - |
| [Tipo de span](#span-type) | `orq.span_type` |
| [Modelo](#model) | `orq.model.id`, `orq.model.provider`, `orq.model.type`, `orq.model.is_private` |
| [Custo](#cost-and-billing) | `orq.billing.*` |
| [Escopo do tenant](#tenant-scope) | `orq.organization_id`, `orq.workspace_id`, `orq.project_id`, `orq.identity_id`, `orq.api_key_id`, `orq.product` |
| [Recursos invocados](#invoked-resources) | `orq.deployment_id`, `orq.deployment_key`, `orq.deployment.variant_id`, `orq.prompt_id`, `orq.knowledge_id`, `orq.memory_store_id`, `orq.playground_id`, `orq.dataset_id`, `orq.schedule_id`, `orq.workflow.run_id` |
| [Conversa](#conversation-and-session-grouping) | `orq.thread_id`, `orq.session_id`, `orq.agent_execution_id` |
| [Metadados personalizados](#custom-metadata-and-attribution) | `orq.metadata`, `orq.variables`, `orq.object_name` |
| [Regras de guardrail e regras de roteamento](#guardrail-rules-and-routing-rules) | `orq.routing_rule.id`, `orq.guardrail_rule.ids`, `orq.guardrail.*` |
| [Evaluators](#evaluators) | `orq.evaluator.id`, `orq.evaluator.type`, `orq.evaluator.version`, `orq.evaluator.output_type`, `orq.evaluation.stage` |
| [Roteamento e fallback](#routing-fallback-and-model-selection) | `orq.fallback.*`, `orq.auto_router.*`, `orq.load_balancer.*` |
| [Origem do framework](#framework-source) | `orq.trace.framework.name` |
| [MCP](#mcp) | `mcp.method.name`, `mcp.session.id`, `mcp.protocol.version`, `mcp.resource.uri`, `server.address` |
| [Chamadas de ferramentas](#tool-calls) | `gen_ai.tool.name`, `gen_ai.tool.type`, `gen_ai.tool.description`, `gen_ai.tool.call.id`, `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result` |

## Tipo de span

Classifica o tipo de trabalho que um span representa. Use `orq.span_type` para filtrar spans por tipo de operação na visualização [**Traces**](/docs/pt-BR/ai-studio/observability/traces.md) ou nos payloads de webhooks de LLM.

| Atributo | Descrição |
| - | - |
| `orq.span_type` | Tipo de operação do span |

Valores comuns:

| Valor | Significado |
| - | - |
| `span.chat_completion` | Chamada de chat completion |
| `span.responses` | Chamada da Responses API |
| `span.embedding` | Embeddings |
| `span.retrieval` | Recuperação de conhecimento |
| `span.evaluator` | Evaluator ou guardrail |
| `span.agent` | Etapa de agente dentro de uma execução |
| `span.agent_execution` | Execução completa de agente |
| `span.tool` | Execução de ferramenta |
| `span.fallback_selected` | Modelo de fallback selecionado |
| `span.auto_router` | Decisão do Smart Router |
| `span.load_balancer` | Decisão do load balancer |

## Modelo

| Atributo | Descrição |
| - | - |
| `orq.model.id` | ID do catálogo de modelos do **Toqan Router** (UUID). Para o nome legível do modelo, consulte `gen_ai.response.model` abaixo. |
| `orq.model.provider` | Provedor, por exemplo `"openai"`, `"anthropic"` |
| `orq.model.type` | Tipo de modelo, por exemplo `"chat"`, `"embedding"` |
| `orq.model.is_private` | Se foi usado um modelo privado do workspace (um modelo adicionado ao catálogo de modelos do workspace, e não um modelo compartilhado do **Toqan Router**) |

Campos padrão relacionados:

* `gen_ai.request.model`: modelo solicitado por quem fez a chamada
* `gen_ai.response.model`: modelo que de fato foi executado; use-o para obter o nome legível do modelo, pois ele reflete o modelo real após qualquer roteamento ou fallback

## Custo e faturamento

Estes atributos aparecem no painel **Economics**, na lista de traces e nos payloads de webhooks de LLM.

| Atributo | Descrição |
| - | - |
| `orq.billing.total_cost` | Custo total do span (float, USD) |
| `orq.billing.input_cost` | Custo dos tokens de entrada (float, USD) |
| `orq.billing.output_cost` | Custo dos tokens de saída (float, USD) |
| `orq.billing.cache_read_cost` | Custo de leitura do cache de prompt (float, USD) |
| `orq.billing.cache_write_cost` | Custo de gravação do cache de prompt (float, USD) |
| `orq.billing.reasoning_cost` | Custo dos tokens de raciocínio (float, USD) |
| `orq.billing.audio_input_cost` | Custo da entrada de áudio (float, USD) |
| `orq.billing.audio_output_cost` | Custo da saída de áudio (float, USD) |
| `orq.billing.web_search_cost` | Tarifas de busca na web (float, USD) |
| `orq.billing.billable` | Se este span conta para o faturamento de uso do workspace (bool). `false` para respostas em cache e chamadas internas de evaluators. |
| `orq.billing.pricing_tier` | Faixa de preço: `"standard"`, `"extended_128k"`, `"extended_200k"` (string) |
| `orq.billing.threshold_exceeded` | Um limite de orçamento configurado foi excedido (bool). A chamada ainda é concluída; esta flag sinaliza que regras de alerta ou de aplicação podem ser aplicadas. |
| `orq.billing.integration_id` | ID da integração do provedor (a configuração de chave de API para uma conta específica do provedor) usada para consultar as tarifas de preço (string) |

> [!NOTE]
>
> As contagens de tokens ficam em `gen_ai.usage.*`, e não em `orq.*`. Consulte [Uso de tokens](#token-usage) abaixo.

## Uso de tokens

As contagens de tokens seguem a convenção `gen_ai.usage.*` do OpenTelemetry. Os detalhamentos só estão presentes quando o provedor os informa.

| Atributo | Descrição |
| - | - |
| `gen_ai.usage.input_tokens` | Tokens de entrada, incluindo tokens em cache ou gravados no cache (int) |
| `gen_ai.usage.output_tokens` | Tokens de saída (int) |
| `gen_ai.usage.total_tokens` | Tokens de entrada mais tokens de saída (int) |
| `gen_ai.usage.prompt_tokens_details.cached_tokens` | Tokens de entrada lidos do cache de prompt (int) |
| `gen_ai.usage.prompt_tokens_details.cache_creation_tokens` | Tokens de entrada gravados no cache de prompt, em todos os TTLs (int) |
| `gen_ai.usage.prompt_tokens_details.cache_creation_5m_tokens` | Tokens gravados no cache com TTL de 5 minutos. Somente Anthropic (int) |
| `gen_ai.usage.prompt_tokens_details.cache_creation_1h_tokens` | Tokens gravados no cache com TTL de 1 hora. Somente Anthropic (int) |
| `gen_ai.usage.prompt_tokens_details.audio_tokens` | Tokens de entrada de áudio (int) |
| `gen_ai.usage.completion_tokens_details.reasoning_tokens` | Tokens de raciocínio ou pensamento (int) |
| `gen_ai.usage.completion_tokens_details.audio_tokens` | Tokens de saída de áudio (int) |

As contagens em cache e gravadas no cache são subconjuntos de `gen_ai.usage.input_tokens`. O custo delas é informado separadamente em `orq.billing.cache_read_cost` e `orq.billing.cache_write_cost`. Consulte [Prompt caching](/docs/pt-BR/ai-gateway/features/prompt-caching.md#cache-usage-in-traces) para ver como elas aparecem em cada API.

## Escopo do tenant

Define o escopo de um trace em relação à organização, ao workspace e à superfície de produto.

| Atributo | Descrição |
| - | - |
| `orq.organization_id` | Organização à qual a chamada pertence |
| `orq.workspace_id` | Workspace |
| `orq.project_id` | Projeto dentro do workspace |
| `orq.identity_id` | [**Identity**](/docs/pt-BR/ai-studio/observability/identities.md) do usuário final (preferencial) |
| `orq.contact_id` | Alias legado de identity; mesmo significado de `orq.identity_id` |
| `orq.api_key_id` | Chave de API usada na solicitação |
| `orq.product` | Superfície de produto que tratou a solicitação, por exemplo `"router"` ou `"agents"` |

Filtre traces por projeto ou atribua custos a uma [**Identity**](/docs/pt-BR/ai-studio/observability/identities.md).

## Recursos invocados

Vincula um trace aos recursos do **Toqan Router** que atenderam à solicitação.

| Atributo | Descrição |
| - | - |
| `orq.deployment_id` | ID do **Deployment** |
| `orq.deployment_key` | Chave/slug do deployment |
| `orq.deployment.variant_id` | Variante que atendeu à solicitação |
| `orq.prompt_id` | Recurso de **Prompt** |
| `orq.knowledge_id` | Base de conhecimento usada na recuperação |
| `orq.memory_store_id` | ID do memory store, presente em spans que usam recuperação aumentada por memória |
| `orq.playground_id` | ID da sessão do Playground, presente em spans iniciados a partir do Playground |
| `orq.dataset_id` | ID do dataset, presente em spans acionados por evals ou experimentos |
| `orq.schedule_id` | ID da programação, presente em spans acionados por uma programação |
| `orq.workflow.run_id` | Execução do workflow |

Use-os para responder: qual deployment, prompt, base de conhecimento, programação ou workflow gerou este trace? Para identificar qual execução de agente gerou este trace, use `orq.agent_execution_id`.

## Agrupamento por conversa e sessão

| Atributo | Descrição |
| - | - |
| `orq.thread_id` | ID da [**Thread**](/docs/pt-BR/ai-studio/observability/threads.md): agrupa os turnos de uma única conversa |
| `orq.session_id` | ID da sessão: agrupa solicitações que compartilham o mesmo valor entre conversas |
| `orq.agent_execution_id` | Uma única execução de **Agent** |

`orq.thread_id` agrupa turnos individuais em uma conversa. `orq.session_id` agrupa solicitações entre conversas para um acompanhamento de sessão mais amplo; quando uma solicitação contém ambos, `orq.thread_id` determina o agrupamento. Passe `orq.thread_id` para agrupar turnos relacionados na visualização [**Threads**](/docs/pt-BR/ai-studio/observability/threads.md).

> [!NOTE]
>
> O campo padrão do OTel `gen_ai.conversation.id` também é aceito. Quando ambos estão presentes, `orq.thread_id` tem precedência como identificador principal de thread na interface e nas exportações de traces.

## Metadados personalizados e atribuição

| Atributo | Descrição |
| - | - |
| `orq.metadata` | Metadados personalizados de chave-valor (string JSON no span) |
| `orq.variables` | Variáveis de modelo passadas por quem faz a chamada para preencher os placeholders do prompt nesta chamada (string JSON) |
| `orq.object_name` | Nome de exibição do objeto rastreado |

Contexto arbitrário de chave-valor anexado ao span, como `customer_tier` ou `feature_flag`. Pode ser filtrado na visualização [**Traces**](/docs/pt-BR/ai-studio/observability/traces.md) e nas [Trace Automations](/docs/pt-BR/ai-studio/observability/automations.md).

> [!NOTE]
>
> Os atributos filtráveis seguem limites de ingestão: valores de string com mais de 512 bytes não são mantidos como atributos filtráveis, e chaves de atributo com mais de 512 bytes são descartadas. São mantidas até 200 chaves de atributo por span; aumente o limite para no máximo 1000 com o atributo `orq.attribute_keys_limit`. A seleção é determinística: as chaves com prefixo `gen_ai.` ou `orq.` são mantidas primeiro e, depois, as chaves restantes em ordem alfabética. O payload completo do span, incluindo valores que ultrapassam esses limites, continua disponível nos detalhes do span.

## Regras de guardrail e regras de roteamento

Estes atributos refletem a aplicação de regras estáticas: qual regra de roteamento ou guardrail correspondeu a esta solicitação. Para a seleção dinâmica de modelos (fallback, Smart Router, load balancer), consulte [Roteamento, fallback e seleção de modelos](#routing-fallback-and-model-selection).

| Atributo | Descrição |
| - | - |
| `orq.routing_rule.id` | [Regra de roteamento](/docs/pt-BR/ai-gateway/configuration/routing-rules.md) que correspondeu |
| `orq.guardrail_rule.ids` | IDs das regras de [Guardrail](/docs/pt-BR/ai-gateway/configuration/guardrail-rules.md) que corresponderam a esta solicitação (array de strings) |
| `orq.guardrail.enabled` | O span é uma verificação de guardrail bloqueante |
| `orq.guardrail.action` | Ação executada, por exemplo `"block"` |

Use-os para depurar por que uma solicitação foi bloqueada ou roteada por uma regra.

## Evaluators

Em spans de **Evaluator** e [**Guardrail**](/docs/pt-BR/ai-gateway/configuration/guardrail-rules.md):

| Atributo | Descrição |
| - | - |
| `orq.evaluator.id` | ID do evaluator |
| `orq.evaluator.type` | Tipo de evaluator, por exemplo `"llm_judge"`, `"regex"`, `"similarity"` |
| `orq.evaluator.version` | Versão do evaluator |
| `orq.evaluator.output_type` | Tipo de saída, por exemplo `"boolean"`, `"score"`, `"label"` |
| `orq.evaluation.stage` | `"input"` quando o evaluator foi executado antes da chamada ao modelo (verificando o prompt); `"output"` quando foi executado depois (verificando a resposta) |

Os resultados de pontuação, aprovação e reprovação também aparecem nos atributos padrão `gen_ai.evaluation.*`.

`gen_ai.evaluation.explanation` contém o raciocínio em texto livre. Explicações com mais de 512 bytes aparecem encurtadas com reticências em visualizações de lista e tooltips; o texto completo permanece nos detalhes do span. Filtros por substring não são oferecidos para este atributo.

## Roteamento, fallback e seleção de modelos

Estes atributos refletem a seleção dinâmica de modelos em tempo de execução: qual modelo foi de fato escolhido e por que ele diferiu do solicitado. Para a aplicação de regras estáticas, consulte [Regras de guardrail e regras de roteamento](#guardrail-rules-and-routing-rules).

| Atributo | Descrição |
| - | - |
| `orq.fallback.index` | Número da tentativa (`0` = principal, `1` = primeiro fallback, ...) |
| `orq.fallback.previous_model` | Modelo que falhou |
| `orq.fallback.previous_error` | Erro que acionou o fallback |
| `orq.auto_router.selected_model` | Modelo escolhido pelo [Smart Router](/docs/pt-BR/ai-gateway/smart-router.md) |
| `orq.auto_router.strong_model` | Candidato de alta capacidade |
| `orq.auto_router.economical_model` | Candidato com melhor custo-benefício |
| `orq.auto_router.profile` | Perfil do Smart Router |
| `orq.load_balancer.selected_model` | Modelo escolhido pelo [load balancer](/docs/pt-BR/ai-gateway/features/load-balancing.md) |
| `orq.load_balancer.original_model` | Modelo solicitado originalmente |

Use-os para explicar diferenças de custo e picos de latência quando o roteamento alterou o modelo.

## Origem do framework

| Atributo | Descrição |
| - | - |
| `orq.trace.framework.name` | Framework que emitiu o trace, por exemplo `"langchain"`, `"openai-agents"`, `"llama-index"` |

Use-o para distinguir os traces emitidos diretamente pelo **Toqan Router** daqueles gerados por um framework externo.

## MCP

Em spans de [**ferramentas MCP**](/docs/pt-BR/ai-studio/observability/mcp-tracing.md) (`span.tool` com `gen_ai.tool.type = "mcp"`):

| Atributo | Descrição |
| - | - |
| `mcp.method.name` | Método MCP chamado, por exemplo `tools/call`, `tools/list`, `resources/read` |
| `mcp.session.id` | Identificador da sessão MCP. Somente instrumentação externa; nunca é definido em spans gerenciados pela plataforma |
| `mcp.protocol.version` | Versão do protocolo MCP negociada durante a inicialização. Definido pela instrumentação externa e pelo gateway MCP em seus próprios spans |
| `mcp.resource.uri` | URI do recurso MCP, presente em leituras de recursos. Somente instrumentação externa |
| `server.address` | Hostname do servidor MCP, por exemplo `mcp.linear.app`. Somente spans gerenciados pela plataforma; não é mantido em spans OTLP instrumentados externamente |

## Chamadas de ferramentas

Em spans `span.tool`:

| Atributo | Descrição |
| - | - |
| `gen_ai.tool.name` | Nome da ferramenta conforme exposto ao modelo. Recebe como prefixo a chave do servidor, por exemplo `linear_mcp__create_issue`, quando vários servidores MCP estão configurados |
| `gen_ai.tool.type` | Tipo de ferramenta, `"function"` ou `"mcp"` |
| `gen_ai.tool.description` | Descrição da ferramenta no catálogo do servidor. Somente instrumentação externa; nunca é definido em spans gerenciados pela plataforma |
| `gen_ai.tool.call.id` | Identificador único desta chamada de ferramenta |
| `gen_ai.tool.call.arguments` | Argumentos codificados em JSON (conteúdo sensível) |
| `gen_ai.tool.call.result` | Resultado codificado em JSON (conteúdo sensível) |

> [!NOTE]
>
> Em spans gerenciados pela plataforma, `gen_ai.tool.call.arguments` e `gen_ai.tool.call.result` são capturados por padrão, com a ocultação de segredos e as regras de mascaramento de Data Compliance aplicadas antes do armazenamento. Clientes instrumentados externamente não são abrangidos: o mascaramento só é executado em spans que contêm o atributo `orq.masking_options`, definido pelos componentes da plataforma, portanto os valores exportados por OTLP são armazenados como foram recebidos. Mascare os dados sensíveis antes da exportação.

## Exemplo de webhook

Um payload típico de webhook de LLM inclui estes atributos no bloco `data.attributes`:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "orq.organization_id": "55c3d968-8390-4e46-af01-e46857f37ced",
  "orq.workspace_id": "3de3a12f-6c52-46b5-a195-539bc40e99c9",
  "orq.product": "router",
  "orq.span_type": "span.chat_completion",
  "orq.model.id": "85b18e5b-76a0-48dc-99b5-5738c35c9c85",
  "orq.model.provider": "openai",
  "orq.model.type": "chat",
  "orq.model.is_private": false,
  "orq.billing.input_cost": 0.0000012,
  "orq.billing.output_cost": 0.0000054,
  "orq.billing.total_cost": 0.0000066,
  "orq.billing.billable": false,
  "orq.billing.pricing_tier": "standard"
}
```

Consulte Webhooks para ver o formato completo do envelope.


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