Connect tracing integrations

The Atlan SDK accepts native SDK spans, third-party OpenTelemetry spans, and framework callback spans through one exporter. You do not need a separate trace model for each provider. Choose the narrowest integration path your stack supports:

Path	Use it when	What you add
Native OpenTelemetry	The library already emits OTel spans	Share Atlan’s provider or processor, or point OTLP at Registry
Python auto-instrumentation	An installed AI instrumentor exposes the standard OTel entry point	`auto_instrument()` once at startup
Framework adapter	Atlan ships a tested callback or native telemetry adapter	Add the callback or wrapper to the framework call
Manual boundary	The library emits no usable spans	Wrap its top-level call with `traced` / `wrapTraced`

All four paths use asynchronous batch export by default. Call flush() before a short-lived process exits. Eval does this automatically, then reads every case trace back through the experiment filter before it writes results and finalizes a run. Registry derives the durable score summary during finalization. initLogger captures every OpenTelemetry scope by default. This includes any HTTP, database, or application instrumentors already attached to the same provider. Pass captureAll: false / capture_all=False to return to Atlan’s AI-focused allowlist, and apply privacy controls before sending third-party spans that may contain protected content.

Discover installed Python instrumentors

auto_instrument() discovers the standard opentelemetry_instrumentor entry points already installed in your environment. It enables only recognized AI instrumentors and does not begin tracing unrelated database or web-framework libraries. Call it before importing provider clients, then initialize the logger:

from atlanai.tracing import auto_instrument, init_logger

report = auto_instrument()
logger = init_logger(project_name="support-agent")

print("instrumented:", report.instrumented)
print("failed:", report.failed)

The Atlan package does not install every vendor instrumentor. Install the OTel instrumentation package approved for your provider, then let auto_instrument() discover it. Disable one installed integration with a Braintrust-compatible flag such as auto_instrument(openai=False).

Treat report.failed as a deployment failure when complete traces are a requirement. A running application does not prove that its provider spans were instrumented.

Vercel AI SDK

wrapAISDK injects the AI SDK’s native experimental_telemetry option into generation, streaming, embedding, reranking, and agent calls. It preserves telemetry metadata supplied by the caller and leaves unrelated exports untouched.

import * as ai from "ai";
import { initLogger, wrapAISDK } from "@atlanai/sdk/tracing";

const logger = initLogger({ projectName: "support-agent" });
const tracedAI = wrapAISDK(ai, {
  logger,
  metadata: { component: "answer-generation" },
});

try {
  const result = await tracedAI.generateText({
    model,
    prompt: "What is 2+2?",
  });
  console.log(result.text);
} finally {
  await logger.flush();
}

If you prefer not to wrap the module, pass telemetry to one call:

import { aiTelemetry } from "@atlanai/sdk/tracing";

const result = await ai.generateText({
  model,
  prompt,
  experimental_telemetry: aiTelemetry({ functionId: "answer" }),
});

Initialize the logger before the first AI SDK call. If a call already contains a tracer, wrapAISDK preserves it by default. Pass replaceTracer: true only when Atlan should replace that tracer.

LangChain and LangGraph

The Python callback maps framework run IDs, parents, model usage, tool calls, errors, and LangGraph interrupt/resume flow into one trace tree.

from atlanai.tracing import init_logger
from atlanai.tracing.langchain import CallbackHandler

logger = init_logger(project_name="support-agent")
handler = CallbackHandler()

try:
    result = graph.invoke(
        {"messages": [{"role": "user", "content": "What is 2+2?"}]},
        config={"callbacks": [handler]},
    )
finally:
    logger.flush()

For LangChain.js, use its OpenTelemetry integration when available. Otherwise, wrap graph.invoke with wrapTraced to preserve the agent boundary. Python automatically reuses a global SDK TracerProvider that your application registered first. You can also pass it explicitly:

from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from atlanai.tracing import init_logger

provider = TracerProvider(
    resource=Resource.create({"service.name": "support-agent"}),
)
trace.set_tracer_provider(provider)
logger = init_logger(
    project_name="support-agent",
    tracer_provider=provider,
)

OpenTelemetry JS allows only one global provider and does not let another SDK mutate it later. If your application owns that provider, initialize Atlan in isolated mode and add its processor when constructing the application provider:

import { resourceFromAttributes } from "@opentelemetry/resources";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { initLogger } from "@atlanai/sdk/tracing";

const logger = initLogger({
  projectName: "support-agent",
  isolated: true,
});

if (!logger.client.spanProcessor) {
  throw new Error("Atlan tracing is disabled");
}

const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({ "service.name": "support-agent" }),
  spanProcessors: [logger.client.spanProcessor],
});
provider.register();

Create provider and framework clients after this setup. Otherwise, those clients may retain a tracer from a different provider and their spans will not reach Registry.

Send direct OTLP

Java, Ruby, Go, sidecars, and other OpenTelemetry runtimes can send OTLP/HTTP protobuf without either Atlan SDK:

export ATLAN_BASE_URL="https://agentgateway.atlan.engineering"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="${ATLAN_BASE_URL}/otel/v1/traces"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20${ATLAN_API_KEY},X-Atlan-Workspace-Id=${ATLAN_WORKSPACE_ID}"

Populate these values through an approved secret store. Do not put headers in source code, container images, or deployment manifests.

Wrap an unsupported framework

Manual wrapping guarantees the agent boundary, input, output, latency, and failure. Calls from instrumented providers inside the wrapper become child spans automatically.

import { wrapTraced } from "@atlanai/sdk/tracing";

const runAgent = wrapTraced(
  agent.run.bind(agent),
  { name: "agent.run", type: "task" },
);

const result = await runAgent(input);

from atlanai.tracing import traced

@traced(name="agent.run", type="task")
def run_agent(input):
    return agent.run(input)

Manual wrapping cannot invent model, tool, token, or cost details that the framework does not expose. Add child spans or span.update(...) calls for those fields when you own the call site.

Integration coverage

Coverage describes the delivery contract, not every version of a third-party package:

Level	Meaning
Certified	An executable Atlan SDK test covers the adapter contract
Compatible	The integration emits OpenTelemetry or uses a stable callback contract consumed by one of the paths above
Manual	Wrap the framework boundary explicitly

Tracing libraries

Integration	Level	Recommended path
OpenTelemetry	Certified	Shared provider, Atlan processor, or direct OTLP
Temporal	Compatible	OpenTelemetry or direct OTLP
Vercel AI SDK	Certified	`wrapAISDK` or `aiTelemetry`
OpenRouter SDK	Compatible	Python auto-instrumentation or manual boundary
LangChain	Certified	Python `CallbackHandler`; OpenTelemetry for other runtimes
LangChain4j	Compatible	Direct OTLP
LangSmith	Manual	`traced` or `wrapTraced`
LlamaIndex	Compatible	Python auto-instrumentation or OpenTelemetry
Agno	Compatible	Python auto-instrumentation or OpenTelemetry
Apollo GraphQL	Compatible	OpenTelemetry
Cloudflare Workers AI	Compatible	OpenTelemetry or manual boundary
DSPy	Compatible	Python auto-instrumentation or OpenTelemetry
Instructor	Compatible	Python auto-instrumentation or OpenTelemetry
LiteLLM	Compatible	Python auto-instrumentation or OpenTelemetry
Ruby LLM	Compatible	Direct OTLP or manual boundary
Spring AI	Compatible	Direct OTLP
Traceloop	Compatible	Shared OpenTelemetry provider or direct OTLP
TrueFoundry	Compatible	Shared OpenTelemetry provider or direct OTLP

Agent frameworks

Integration	Level	Recommended path
OpenAI Agents SDK	Compatible	Python auto-instrumentation or OpenTelemetry
Claude Agent SDK	Manual	`traced` or `wrapTraced`
Pi Coding Agent	Manual	`traced` or `wrapTraced`
Deep Agents	Compatible	LangChain callback
LangGraph	Certified	Python `CallbackHandler`
CrewAI	Compatible	Python auto-instrumentation or OpenTelemetry
AutoGen	Compatible	OpenTelemetry
AgentScope	Compatible	Python auto-instrumentation or OpenTelemetry
Google ADK	Compatible	Python auto-instrumentation or OpenTelemetry
LiveKit Agents	Compatible	Python auto-instrumentation or OpenTelemetry
Mastra	Compatible	OpenTelemetry
Pipecat	Compatible	Python auto-instrumentation or OpenTelemetry
Pydantic AI	Compatible	Python auto-instrumentation or OpenTelemetry
Strands	Compatible	Python auto-instrumentation or OpenTelemetry
Cloudflare Agents	Compatible	OpenTelemetry or manual boundary
Cloudflare AI Chat	Compatible	`wrapAISDK` or `aiTelemetry`

Run one representative request after every framework or instrumentor upgrade. Confirm the root, provider call, tool calls, usage, and expected parent relationships in Agent Registry before promoting the build.

Preserve evaluation joins

Third-party spans created inside an Eval task inherit atlan.eval.experiment_id from the active context. The experiment result then stores the case’s root trace_id. Bench filters use the experiment attribute; case drill-down uses the result-to-trace join. If you run your own harness, execute it inside run.trace() in Python or propagateAttributes(run.traceOptions, fn) in TypeScript. Flush and verify the traces, upload complete result rows with their numeric score snapshots, then mark the experiment completed with one update. Consume the returned experiment’s summary; no separate summarize request is needed.

Next steps

Run evaluations

Create one trace and durable result for every case.

Privacy controls

Suppress or mask content from first-party and third-party spans.

Serverless delivery

Keep asynchronous exports alive before a function freezes.

Verify traces

Confirm ingestion and parent-child structure end to end.

Overview

CLI

SDK

Cookbooks

Operate safely

API reference

Discover installed Python instrumentors

Vercel AI SDK

LangChain and LangGraph

Send direct OTLP

Wrap an unsupported framework

Integration coverage

Tracing libraries

Agent frameworks

Preserve evaluation joins

Next steps

Run evaluations

Privacy controls

Serverless delivery

Verify traces

​Discover installed Python instrumentors

​Vercel AI SDK

​LangChain and LangGraph

​Share an application-owned OpenTelemetry provider

​Send direct OTLP

​Wrap an unsupported framework

​Integration coverage

​Tracing libraries

​Agent frameworks

​Preserve evaluation joins

​Next steps

Run evaluations

Privacy controls

Serverless delivery

Verify traces

Discover installed Python instrumentors

Vercel AI SDK

LangChain and LangGraph

Share an application-owned OpenTelemetry provider

Send direct OTLP

Wrap an unsupported framework

Integration coverage

Tracing libraries

Agent frameworks

Preserve evaluation joins

Next steps