Quick Start

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.

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

Create a Toqan Router account

Set up Toqan Router

Open Settings > API Keys in the AI Studio. Click Create API Key, 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.

export TOQAN_API_KEY="your-api-key-here"

$env:TOQAN_API_KEY = "your-api-key-here"

Instrument with OpenTelemetry

Install the OpenTelemetry SDK and the OTLP HTTP exporter:

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

npm install @opentelemetry/sdk-node @opentelemetry/exporter-trace-otlp-http

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

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"

$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:

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)

import { NodeSDK } from '@opentelemetry/sdk-node';
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';

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

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.

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:

LangGraph

One setup() call instruments the graph, tools, and every LLM step.

Vercel AI SDK

Python and TypeScript SDKs with experimental OpenTelemetry telemetry.

Pydantic AI

Logfire-based instrumentation for agents, tools, and streaming.

OpenAI Agents

Automatic tracing via OpenAIAgentsInstrumentor.

Agno

OpenInference instrumentation for agents and tools.

Google ADK

Trace agent workflows, tool calls, and Gemini model interactions.

Mastra

TypeScript agents and workflows with OpenTelemetry tracing.

Claude Agent SDK

Hooks-based instrumentation for agent turns and tool use.

See all frameworks

Full list of supported frameworks and setup guides.

View traces

Run the agent and open Traces 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.

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:

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:

For structured failure analysis, the analyze-traces Toqan Router Skill reads production traces, builds a failure taxonomy, and categorizes issues.

Troubleshooting

Authentication error: 401 Unauthorized

Confirm the variable is set: echo $TOQAN_API_KEY
Verify the key is active under Settings > API Keys
Confirm the key is passed in the Authorization: Bearer header on the OTLP exporter, not as a query parameter

Traces not appearing in the Studio

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)
Check that the workspace in the API key matches the AI Studio workspace being viewed
Traces can take a few seconds to appear, wait 10 seconds and refresh
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:
provider.shutdown() # flush and stop the batch processor before exit
await sdk.shutdown(); // flush and stop the batch processor before exit
Confirm the sampler is not discarding everything, for example OTEL_TRACES_SAMPLER=always_off or a ratio of 0
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

Annotate traces

Label and review spans to build high-quality evaluation datasets from real production traffic.

Set up analytics

Track cost, latency, error rates, and token usage across models and deployments over time.

Overview

Instrument your app

Explore

Monitor

Export

Review

Data privacy & security

Framework integrations

Create a Toqan Router account

Set up Toqan Router

Instrument with OpenTelemetry

Connect a framework

LangGraph

Vercel AI SDK

Pydantic AI

OpenAI Agents

Agno

Google ADK

Mastra

Claude Agent SDK

See all frameworks

View traces

Analyze traces with MCP

Troubleshooting

Annotate traces

Set up analytics

Create a Toqan Router account

Set up Toqan Router

Instrument with OpenTelemetry

Connect a framework

LangGraph

Vercel AI SDK

Pydantic AI

OpenAI Agents

Agno

Google ADK

Mastra

Claude Agent SDK

See all frameworks

View traces

Analyze traces with MCP

​Troubleshooting

Annotate traces

Set up analytics

Troubleshooting