> ## Documentation Index
> Fetch the complete documentation index at: https://www.adaline.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Overview
> Send AI agent logs, traces, spans, sessions, feedback, and metadata to Adaline
Instrument is how your AI agent starts learning from production. Send logs from your application to Adaline so every important request, model call, tool call, retrieval step, command, outcome, and user signal can become evidence for Behaviors, Evaluators, Datasets, Improve cycles, and safer deployments.
The goal is not just visibility. Good instrumentation gives Adaline enough context to understand repeated patterns, triage issues, generate coverage, and suggest prompt improvements your team can review.
## What to instrument
Start by capturing the parts of the agent run that explain what happened.
| Evidence | What to send | Why it matters |
| ----------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| **Traces** | One trace for each request, conversation turn, job, or agent task. | Gives Adaline the full unit of work to inspect, search, group, and improve. |
| **Spans** | Model calls, tool calls, retrieval, embeddings, guardrails, functions, commands, and custom workflow steps. | Shows where the agent spent time, used tools, failed, retried, or produced the final answer. |
| **Sessions** | Stable session, conversation, journey, task, or trajectory identifiers. | Connects multiple traces into a user journey or coding-agent run. |
| **Inputs and outputs** | Prompt messages, model responses, tool arguments, tool responses, retrieved context, and safe summaries. | Lets reviewers and evaluators understand the exact evidence behind a result. |
| **Operational signals** | Status, latency, tokens, cost, model, provider, environment, release, route, prompt, and agent identity. | Makes filtering, release review, cost analysis, and regression investigation practical. |
| **Quality signals** | User feedback, application outcome, evaluator score, escalation state, task completion, or human-review result. | Helps Adaline distinguish healthy traffic from failures that need coverage or improvement. |
If you are starting from scratch, send one useful trace before trying to model everything. A useful trace has a readable name, spans for model/tool work, status, timing, model/provider details, environment metadata, and enough input/output context for a teammate to understand the run.
## Choose an integration path
Use the path that matches how much control you need.
| Path | Best for | What you get |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
| **[With Adaline Integrations](/docs/instrument/with-adaline-integrations)** | Apps already using AI frameworks, providers, gateways, agents, or OpenTelemetry. | Framework-native logging with less custom trace code. |
| **[With Adaline SDKs](/docs/instrument/with-adaline-sdks)** | TypeScript or Python applications that need explicit traces, spans, sessions, variables, and metadata. | Full control over how production evidence is structured. |
| **[With Adaline API](/docs/instrument/with-adaline-api)** | Any language, backend, queue, worker, edge runtime, CI job, or custom system. | Direct REST calls for traces, spans, updates, feedback, and platform resources. |
| **[With Adaline Proxy](/docs/instrument/with-adaline-proxy)** | Quick provider-compatible setup when changing the AI provider base URL is easiest. | Automatic traces for provider calls with minimal code changes. |
| **[Coding-agent integration](/docs/get-started/integrate-your-ai-agent#using-coding-agents)** | Teams using Cursor, Windsurf, Claude Code, Cline, or another coding agent. | Copy-paste integration context so your coding agent can wire Adaline into your app. |
## Integration methods
Use [Adaline Integrations](/docs/instrument/with-adaline-integrations) when your agent already runs through a supported framework, provider SDK, gateway, or OpenTelemetry pipeline.
Common starting points include LangChain, LangGraph, LlamaIndex, LiteLLM, Vercel AI SDK, OpenTelemetry, and provider integrations.
**Use this when:** you want Adaline logs without hand-modeling every span yourself.
Use [Adaline SDKs](/docs/instrument/with-adaline-sdks) when you want precise control over traces and spans.
```typescript theme={null}
import { Adaline } from "@adaline/client";
const adaline = new Adaline();
const monitor = adaline.initMonitor({ projectId: "your-project-id" });
const trace = monitor.logTrace({ name: "user-request" });
const span = trace.logSpan({ name: "model:answer-user" });
```
**Use this when:** your workflow has multiple agents, tools, retrieval steps, custom metadata, or sessions that need to be modeled clearly.
Use the [Adaline API](/docs/instrument/with-adaline-api) when you need language-agnostic logging or want to send traces from systems where the SDK is not available.
```bash theme={null}
POST /v2/logs/trace
Authorization: Bearer your-api-key
Content-Type: application/json
```
**Use this when:** logs come from a backend service, worker, queue, edge function, CI job, or custom runtime.
Use [Adaline Proxy](/docs/instrument/with-adaline-proxy) when your application already calls an AI provider with an OpenAI-compatible or provider SDK and you want the fastest path to logs.
```python theme={null}
from openai import OpenAI
client = OpenAI(
api_key="your-openai-key",
base_url="https://gateway.adaline.ai/v1/openai/",
default_headers={
"adaline-api-key": "your-adaline-key",
"adaline-project-id": "your-project-id",
"adaline-prompt-id": "your-prompt-id",
},
)
```
**Use this when:** changing the provider base URL is easier than adding SDK or API calls throughout your app.
## Metadata that makes logs useful
Metadata is what turns raw logs into product, engineering, support, and release workflows.
| Metadata | Examples | Used by |
| ---------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------- |
| **Environment** | `production`, `staging`, `qa` | Release review, filtering, dashboards, saved views. |
| **Release or build** | Commit SHA, deployment ID, version, experiment arm. | Drift investigation and post-release watch windows. |
| **Route or workflow** | `checkout-assistant`, `support-chat`, `training-plan-generator`. | Behavior maps, Monitor breakdowns, support triage. |
| **Prompt or agent identity** | Prompt name, prompt ID, agent name, agent type, workflow step. | Improve cycles, prompt ownership, evaluator routing. |
| **Session or trajectory ID** | Conversation ID, task ID, coding-agent run ID. | Sessions, trajectories, multi-turn investigation. |
| **Safe customer segment** | Plan tier, region, beta cohort, hashed tenant ID. | Customer-safe filtering without exposing private identifiers. |
| **Outcome** | Success, failed, escalated, partial, user-reported issue, task complete. | Behavior severity, issue detection, evaluation, and triage. |
Avoid raw emails, API keys, access tokens, secrets, unnecessary personal data, and private customer text that your team should not store.
## Verify your first trace
After instrumenting, run a known request in staging and inspect it in [Logs](/docs/monitor/analyze-log-traces).
You are integrated when:
1. The trace appears in Adaline within a few seconds.
2. The trace name describes the workflow or request.
3. Spans show the model calls, tool calls, retrieval, command, or custom steps that matter.
4. Status, latency, model, provider, tokens, and cost appear where supported.
5. Tags or attributes identify environment, release, route, prompt, agent, and session context.
6. A teammate can open the trace and understand what happened without asking the original engineer.
If the trace is hard to read, fix the names and metadata before sending more traffic. Clean evidence now makes Behaviors and Improve much stronger later.
## From logs to improvement
Instrumentation feeds every later Platform workflow:
| Workflow | How instrumentation helps |
| --------------------------- | --------------------------------------------------------------------------------------------------------------- |
| **Logs** | Gives your team exact traces, spans, sessions, filters, search, costs, latency, tokens, and evaluator scores. |
| **Behaviors** | Lets Adaline group repeated user, assistant, tool, and coding-agent patterns from production evidence. |
| **Evaluators and Datasets** | Turns real traces, feedback, edge cases, and outcomes into durable quality checks. |
| **Improve** | Gives improvement cycles enough evidence to propose prompt candidates with reviewable examples and regressions. |
| **Deploy** | Lets teams compare a release against the same metadata, behaviors, evals, and logs after shipping. |
Connect frameworks, providers, agents, gateways, and OpenTelemetry pipelines.
Create traces, spans, sessions, variables, and metadata from TypeScript or Python.
Send logs directly from any language, runtime, worker, or custom system.
Route provider calls through Adaline for fast logging with minimal code changes.
Attach user feedback, outcomes, and review signals to production traces.
Model complex workflows, streaming, custom spans, reference IDs, and multi-service traces.