Instrument an app with OpenTelemetry for full trace visibility and cost tracking in Orq.ai. Framework-specific guides are in the Integrations section.
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
Sign up for a free Orq.ai account and set up a workspace.
2
Set up Orq.ai
API key only
Coding agent
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.
export ORQ_API_KEY="your-api-key-here"
$env:ORQ_API_KEY = "your-api-key-here"
Paste this prompt into the coding agent to add tracing to the app:
Install the Orq.ai CLI, run `orq setup`, and add Orq.ai tracing to my app.
Or install the CLI directly:
curl -fsSL https://cli.orq.ai/install.sh | sh
orq setup signs in, creates a project-scoped API key, and connects the coding agents already on the machine to Orq.ai, including the Orq MCP server and Orq Skills.
Initialize the tracer provider once at application startup. The exporter reads the endpoint, headers, and resource from the environment variables above:
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://my.orq.ai/v2/otel and the full path https://my.orq.ai/v2/otel/v1/traces. Spans from any OpenTelemetry-instrumented code are exported automatically.Self-hosted and on-premise deployments serve /v2/otel under their own hostname. See Base URLs.
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
If the Orq 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 Orq MCP and returns an analysis like this:
Orq MCP trace analysis output
For structured failure analysis, the analyze-traces Orq Skill reads production traces, builds a failure taxonomy, and categorizes issues.