Skip to main content
Orq.ai 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 Orq.ai 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 Frameworks in Integrations
1

Create an Orq.ai account

Sign up for a free Orq.ai account and set up a workspace.
2

Get an API key

Open Settings > Organization > 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.
3

Instrument with OpenTelemetry

Install the OpenTelemetry SDK and the OTLP HTTP exporter:
Set the environment variables that point the OpenTelemetry SDK at the Orq.ai collector:
Initialize the tracer provider once at application startup. The exporter reads the endpoint, headers, and resource from the environment variables above:
The exporter accepts both https://api.orq.ai/v2/otel and the full path https://api.orq.ai/v2/otel/v1/traces. Spans from any OpenTelemetry-instrumented code are exported automatically.
4

Connect a framework

Using a framework? Instrument the framework with its own setup instead of manual span creation. Each page in Integrations 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.
5

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.
6

Analyze traces with MCP

Install the Orq MCP server in the editor or AI assistant, then ask the coding assistant:
The assistant queries the Orq MCP and returns an analysis like this:
Orq MCP trace analysis output showing slowest traces and latency causes

Orq MCP trace analysis output

For structured failure analysis, the analyze-trace-failures Orq Skill reads production traces, builds a failure taxonomy, and categorizes issues.

Troubleshooting

  1. Confirm the variable is set: echo $ORQ_API_KEY
  2. Verify the key is active under Settings > Organization > API Keys
  3. Confirm the key is passed in the Authorization: Bearer header on the OTLP exporter, not as a query parameter
  1. Confirm the OTLP endpoint is set to https://api.orq.ai/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

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.

Run an experiment

Use traced data as a baseline to compare prompts, models, and configurations side by side.

Build an agent

Build and deploy a native Orq.ai agent with tools, memory, and full AI Studio management.