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

# Quick Start

> Instrument an app with OpenTelemetry for full trace visibility and cost tracking in Toqan Router. Framework-specific setup is covered in the framework integration guides.

**Toqan Router** observability captures every LLM call, agent step, and tool use as searchable traces with latency, token counts, and cost. **OpenTelemetry** is the standard, framework-agnostic way to instrument it.

> [!NOTE]
>
> * Set the **Toqan Router** OTLP endpoint and authenticate with an API key
> * Configure the OpenTelemetry SDK in an existing application
> * See every LLM call, agent step, and tool use in **Traces**
> * For framework-specific setup, see the [framework integration guides](/docs/ai-studio/integrations/frameworks/overview.md)

### 1. Create a Toqan Router account

[Sign up](https://router.toqan.ai/eu/auth/signup) for a free **Toqan Router** account and set up a workspace.

### 2. Set up Toqan Router

Open **Settings > API Keys** in the [AI Studio](https://router.toqan.ai/eu). Click <kbd>Create API Key</kbd>, give it a name, and copy it.

Then open a terminal and run the command below, replacing `your-api-key-here` with the copied key. The code samples in the next steps read it from this environment variable.

```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. Instrument with OpenTelemetry

Install the OpenTelemetry SDK and the OTLP HTTP exporter:

```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
```

Set the environment variables that point the OpenTelemetry SDK at the **Toqan Router** collector:

```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"
```

Initialize the tracer provider once at application startup. The exporter reads the endpoint, headers, and resource from the environment variables above:

```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]
>
> The exporter accepts both `https://router.toqan.ai/eu/v2/otel` and the full path `https://router.toqan.ai/eu/v2/otel/v1/traces`. Spans from any OpenTelemetry-instrumented code are exported automatically.
>
> OTLP is served over HTTP, with either `http/protobuf` or `http/json`. Traces are received at `/v2/otel/v1/traces`, logs at `/v2/otel/v1/logs`, and metrics at `/v2/otel/v1/metrics`.
>
> For São Paulo, replace `/eu` with `/br`. See [Regions](/docs/toqan/regions.md).

### 4. Connect a framework

Using a framework? Instrument the framework with its own setup instead of manual span creation. Each framework guide shows the exact installation, environment variables, and instrumentation call:

> [card] [LangGraph](/docs/ai-studio/integrations/frameworks/langgraph.md#observability)
>
> One `setup()` call instruments the graph, tools, and every LLM step.

> [card] [Vercel AI SDK](/docs/ai-studio/integrations/frameworks/vercel-ai.md#observability)
>
> Python and TypeScript SDKs with experimental OpenTelemetry telemetry.

> [card] [Pydantic AI](/docs/ai-studio/integrations/frameworks/pydantic-ai.md#observability)
>
> Logfire-based instrumentation for agents, tools, and streaming.

> [card] [OpenAI Agents](/docs/ai-studio/integrations/frameworks/openai-agents.md#observability)
>
> Automatic tracing via `OpenAIAgentsInstrumentor`.

> [card] [Agno](/docs/ai-studio/integrations/frameworks/agno.md#observability)
>
> OpenInference instrumentation for agents and tools.

> [card] [Google ADK](/docs/ai-studio/integrations/frameworks/google-ai.md#observability)
>
> Trace agent workflows, tool calls, and Gemini model interactions.

> [card] [Mastra](/docs/ai-studio/integrations/frameworks/mastra.md#observability)
>
> TypeScript agents and workflows with OpenTelemetry tracing.

> [card] [Claude Agent SDK](/docs/ai-studio/integrations/frameworks/claude-agent-sdk.md#observability)
>
> Hooks-based instrumentation for agent turns and tool use.

> [card] [See all frameworks](/docs/ai-studio/integrations/frameworks/overview.md)
>
> Full list of supported frameworks and setup guides.

### 5. View traces

Run the agent and open [**Traces**](https://router.toqan.ai/eu) in the **AI Studio**. Every request appears with model, latency, token counts, and cost. For agentic frameworks, individual tool calls and steps appear as child spans.

### 6. Analyze traces with MCP

If the **Toqan Router MCP** server is not connected yet, install it in the editor or AI assistant, then ask the coding assistant:

```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
```

The assistant queries the **Toqan Router MCP** and returns an analysis like this:

> [!TIP]
>
> For structured failure analysis, the **analyze-traces** Toqan Router Skill reads production traces, builds a failure taxonomy, and categorizes issues.

## Troubleshooting

> [accordion] Authentication error: 401 Unauthorized
>
> 1. Confirm the variable is set: `echo $TOQAN_API_KEY`
> 2. Verify the key is active under **Settings > API Keys**
> 3. Confirm the key is passed in the `Authorization: Bearer` header on the OTLP exporter, not as a query parameter

> [accordion] Traces not appearing in the Studio
>
> 1. Confirm the OTLP endpoint is set to `https://router.toqan.ai/eu/v2/otel` (or `/v2/otel/v1/traces` for exporters that require the full path)
>
> 2. Check that the workspace in the API key matches the **AI Studio** workspace being viewed
>
> 3. Traces can take a few seconds to appear, wait 10 seconds and refresh
>
> 4. Flush the tracer provider before a short script exits. The batch processor holds spans for up to 5 seconds, and a process that exits first loses them:
>
>    ```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. Confirm the sampler is not discarding everything, for example `OTEL_TRACES_SAMPLER=always_off` or a ratio of `0`
>
> 6. A `415` with `unsupported content type: expected application/x-protobuf or application/json` means the `Content-Type` header is neither `application/x-protobuf` nor `application/json`. Use an HTTP OTLP exporter, which sets the header to match the body encoding

***

> [card] [Annotate traces](/docs/ai-studio/observability/annotation-queues.md)
>
> Label and review spans to build high-quality evaluation datasets from real production traffic.

> [card] [Set up analytics](/docs/ai-studio/observability/reporting-api.md)
>
> Track cost, latency, error rates, and token usage across models and deployments over time.


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