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

# Início rápido

> Instrumente uma aplicação com OpenTelemetry para ter visibilidade completa dos traces e acompanhamento de custos no Toqan Router. Os guias específicos de cada framework estão na seção Integrations.

A observabilidade do **Toqan Router** captura cada chamada de LLM, etapa de agente e uso de ferramenta como traces pesquisáveis, com latência, contagem de tokens e custo. O **OpenTelemetry** é a forma padrão e independente de framework de instrumentá-la.

> [!NOTE]
>
> * Defina o endpoint OTLP do **Toqan Router** e autentique-se com uma chave de API
> * Configure o SDK do OpenTelemetry em uma aplicação existente
> * Veja cada chamada de LLM, etapa de agente e uso de ferramenta em **Traces**
> * Para a configuração específica de cada framework, consulte [Frameworks em Integrations](/docs/pt-BR/ai-studio/integrations/frameworks/overview.md)

### 1. Crie uma conta no Toqan Router

[Cadastre-se](https://router.toqan.ai/eu/auth/signup) para obter uma conta gratuita do **Toqan Router** e configure um workspace.

### 2. Configure o Toqan Router

Abra **Settings > API Keys** no [AI Studio](https://router.toqan.ai/eu). Clique em <kbd>Create API Key</kbd>, dê um nome a ela e copie-a.

Em seguida, abra um terminal e execute o comando abaixo, substituindo `your-api-key-here` pela chave copiada. Os exemplos de código das próximas etapas a leem dessa variável de ambiente.

```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"github-dark"}}
export TOQAN_API_KEY="your-api-key-here"
```

```powershell Windows theme={"theme":{"light":"github-light","dark":"github-dark"}}
$env:TOQAN_API_KEY = "your-api-key-here"
```

### 3. Instrumente com OpenTelemetry

Instale o SDK do OpenTelemetry e o exportador OTLP HTTP:

```bash Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
```

```bash Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http
```

Defina as variáveis de ambiente que apontam o SDK do OpenTelemetry para o coletor do **Toqan Router**:

```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OTEL_EXPORTER_OTLP_ENDPOINT="https://router.toqan.ai/eu/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $TOQAN_API_KEY"
export OTEL_RESOURCE_ATTRIBUTES="service.name=my-agent,service.version=1.0.0"
```

```powershell Windows theme={"theme":{"light":"github-light","dark":"github-dark"}}
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "https://router.toqan.ai/eu/v2/otel"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer $env:TOQAN_API_KEY"
$env:OTEL_RESOURCE_ATTRIBUTES = "service.name=my-agent,service.version=1.0.0"
```

Inicialize o tracer provider uma única vez na inicialização da aplicação. O exportador lê o endpoint, os cabeçalhos e o recurso das variáveis de ambiente acima:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
trace.set_tracer_provider(provider)
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter(),
});
sdk.start();
```

> [!NOTE]
>
> O exportador aceita tanto `https://router.toqan.ai/eu/v2/otel` quanto o caminho completo `https://router.toqan.ai/eu/v2/otel/v1/traces`. Os spans de qualquer código instrumentado com OpenTelemetry são exportados automaticamente.
>
> O OTLP é servido por HTTP, com `http/protobuf` ou `http/json`. Os traces são recebidos em `/v2/otel/v1/traces`, os logs em `/v2/otel/v1/logs` e as métricas em `/v2/otel/v1/metrics`.
>
> Implantações auto-hospedadas e on-premise servem `/v2/otel` no próprio hostname. Consulte [Base URLs](/docs/pt-BR/reference/base-urls.md).

### 4. Conecte um framework

Usa um framework? Instrumente o framework com a configuração própria dele em vez de criar spans manualmente. Cada página em **Integrations** mostra a instalação exata, as variáveis de ambiente e a chamada de instrumentação:

> [card] [LangGraph](/docs/pt-BR/ai-studio/integrations/frameworks/langgraph.md#observability)
>
> Uma única chamada `setup()` instrumenta o grafo, as ferramentas e cada etapa de LLM.

> [card] [Vercel AI SDK](/docs/pt-BR/ai-studio/integrations/frameworks/vercel-ai.md#observability)
>
> SDKs para Python e TypeScript com telemetria experimental do OpenTelemetry.

> [card] [Pydantic AI](/docs/pt-BR/ai-studio/integrations/frameworks/pydantic-ai.md#observability)
>
> Instrumentação baseada em Logfire para agentes, ferramentas e streaming.

> [card] [OpenAI Agents](/docs/pt-BR/ai-studio/integrations/frameworks/openai-agents.md#observability)
>
> Tracing automático via `OpenAIAgentsInstrumentor`.

> [card] [Agno](/docs/pt-BR/ai-studio/integrations/frameworks/agno.md#observability)
>
> Instrumentação OpenInference para agentes e ferramentas.

> [card] [Google ADK](/docs/pt-BR/ai-studio/integrations/frameworks/google-ai.md#observability)
>
> Rastreie workflows de agentes, chamadas de ferramentas e interações com modelos Gemini.

> [card] [Mastra](/docs/pt-BR/ai-studio/integrations/frameworks/mastra.md#observability)
>
> Agentes e workflows em TypeScript com tracing do OpenTelemetry.

> [card] [Claude Agent SDK](/docs/pt-BR/ai-studio/integrations/frameworks/claude-agent-sdk.md#observability)
>
> Instrumentação baseada em hooks para turnos do agente e uso de ferramentas.

> [card] [Ver todos os frameworks](/docs/pt-BR/ai-studio/integrations/frameworks/overview.md)
>
> Lista completa de frameworks compatíveis e guias de configuração.

### 5. Visualize os traces

Execute o agente e abra [**Traces**](https://router.toqan.ai/eu) no **AI Studio**. Cada solicitação aparece com modelo, latência, contagem de tokens e custo. Em frameworks de agentes, as chamadas de ferramentas e as etapas individuais aparecem como spans filhos.

### 6. Analise os traces com MCP

Se o servidor **Toqan Router MCP** ainda não estiver conectado, instale-o no editor ou no assistente de IA e peça ao assistente de programação:

```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Show me the 10 slowest traces from the last 24 hours and explain what might be causing the latency
```

O assistente consulta o **Toqan Router MCP** e retorna uma análise como esta:

> [!TIP]
>
> Para uma análise estruturada de falhas, a Toqan Router Skill **analyze-traces** lê os traces de produção, monta uma taxonomia de falhas e categoriza os problemas.

## Solução de problemas

> [accordion] Erro de autenticação: 401 Unauthorized
>
> 1. Confirme que a variável está definida: `echo $TOQAN_API_KEY`
> 2. Verifique se a chave está ativa em **Settings > API Keys**
> 3. Confirme que a chave é passada no cabeçalho `Authorization: Bearer` do exportador OTLP, e não como parâmetro de consulta

> [accordion] Os traces não aparecem no Studio
>
> 1. Confirme que o endpoint OTLP está definido como `https://router.toqan.ai/eu/v2/otel` (ou `/v2/otel/v1/traces` para exportadores que exigem o caminho completo)
>
> 2. Verifique se o workspace da chave de API corresponde ao workspace do **AI Studio** que está sendo visualizado
>
> 3. Os traces podem levar alguns segundos para aparecer; aguarde 10 segundos e atualize
>
> 4. Faça o flush do tracer provider antes que um script curto termine. O processador em lote retém os spans por até 5 segundos, e um processo que termina antes disso os perde:
>
>    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
>    provider.shutdown()  # flush and stop the batch processor before exit
>    ```
>
>    ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
>    await sdk.shutdown();  // flush and stop the batch processor before exit
>    ```
>
> 5. Confirme que o sampler não está descartando tudo, por exemplo `OTEL_TRACES_SAMPLER=always_off` ou uma proporção de `0`
>
> 6. Um `415` com `unsupported content type: expected application/x-protobuf or application/json` significa que o cabeçalho `Content-Type` não é `application/x-protobuf` nem `application/json`. Use um exportador OTLP HTTP, que define o cabeçalho de acordo com a codificação do corpo

***

> [card] [Anotar traces](/docs/pt-BR/ai-studio/observability/annotation-queues.md)
>
> Rotule e revise spans para criar datasets de avaliação de alta qualidade a partir do tráfego real de produção.

> [card] [Configurar análises](/docs/pt-BR/ai-studio/observability/reporting-api.md)
>
> Acompanhe custo, latência, taxas de erro e uso de tokens entre modelos e deployments ao longo do tempo.


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