> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/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 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**
* For framework-specific setup, see the [Frameworks in Integrations](/ai-studio/integrations/frameworks/overview)
[Sign up](https://my.orq.ai/auth/signup) for a free **Orq.ai** account and set up a workspace.
Open **Settings > Organization > [API Keys](/ai-studio/organization/api-keys)** in the [AI Studio](https://my.orq.ai). 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.
```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"github-dark"}}
export ORQ_API_KEY="your-api-key-here"
```
```powershell Windows theme={"theme":{"light":"github-light","dark":"github-dark"}}
$env:ORQ_API_KEY = "your-api-key-here"
```
Paste this prompt into the coding agent to add tracing to the app:
```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
Install the Orq.ai CLI, run `orq setup`, and add Orq.ai tracing to my app.
```
Or install the CLI directly:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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**.
Connecting a coding assistant directly? See [Orq Skills](/ai-studio/integrations/code-assistants/orq-skills) and [Orq MCP](/ai-studio/integrations/code-assistants/orq-mcp).
Full command list: [CLI reference](/reference/cli).
`orq setup` writes the key to `~/.orq/env` as a POSIX shell export. Source it from bash or zsh so the code samples in the next steps can read it:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
source ~/.orq/env
```
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 **Orq.ai** collector:
```bash macOS / Linux theme={"theme":{"light":"github-light","dark":"github-dark"}}
export OTEL_EXPORTER_OTLP_ENDPOINT="https://my.orq.ai/v2/otel"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $ORQ_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://my.orq.ai/v2/otel"
$env:OTEL_EXPORTER_OTLP_HEADERS = "Authorization=Bearer $env:ORQ_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();
```
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](/reference/base-urls).
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:
One `setup()` call instruments the graph, tools, and every LLM step.
Python and TypeScript SDKs with experimental OpenTelemetry telemetry.
Logfire-based instrumentation for agents, tools, and streaming.
Automatic tracing via `OpenAIAgentsInstrumentor`.
OpenInference instrumentation for agents and tools.
Trace agent workflows, tool calls, and Gemini model interactions.
TypeScript agents and workflows with OpenTelemetry tracing.
Hooks-based instrumentation for agent turns and tool use.
Full list of supported frameworks and setup guides.
Run the agent and open [**Traces**](https://my.orq.ai) 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.
If the [**Orq MCP** server](/ai-studio/integrations/code-assistants/orq-mcp) 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 **Orq MCP** and returns an analysis like this:
For structured failure analysis, the [**analyze-traces** Orq Skill](/ai-studio/integrations/code-assistants/orq-skills) 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://my.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
***
Label and review spans to build high-quality evaluation datasets from real production traffic.
Track cost, latency, error rates, and token usage across models and deployments over time.
Use traced data as a baseline to compare prompts, models, and configurations side by side.
Build and deploy a native **Orq.ai** agent with tools, memory, and full **AI Studio** management.