OpenTelemetry

Send OpenTelemetry traces to Adaline over OTLP/HTTP with minimal changes to your existing tracing setup.

OpenTelemetry

Use OpenTelemetry when you already have tracing in place and want Adaline to ingest those spans with minimal application changes. Adaline accepts OTLP/HTTP traces, and the @adaline/otel / adaline-otel packages help route them to the Adaline OTEL ingestion endpoint.

This integration is best when your application is already instrumented with OpenTelemetry, either manually or through a framework that emits OpenTelemetry spans.

Prerequisites

Before you start, make sure you have:

• An Adaline account.
• A workspace API key — create one under Settings → API keys.
• Your project ID — copy it from Monitor → Copy Project ID.

See Integrate your AI agent for a full walkthrough.

Set both as environment variables before running the examples on this page:

export ADALINE_API_KEY="your-api-key"
export ADALINE_PROJECT_ID="your-project-id"

Install

TypeScript

npm install @adaline/otel @opentelemetry/api @opentelemetry/sdk-trace-base @opentelemetry/sdk-trace-node

Python

pip install adaline-otel

Configure routing and auth

Set your Adaline credentials in environment variables, then attach the Adaline exporter or span processor to your existing OpenTelemetry pipeline.

ADALINE_API_KEY is required in all cases.

Use one of the following routing values:

• ADALINE_PROJECT_ID when you want spans to land directly in a project
• ADALINE_PARENT when you want downstream services to attach spans to an existing Adaline parent

.env

ADALINE_API_KEY=your-api-key
ADALINE_PROJECT_ID=your-project-id
ADALINE_API_URL=https://api.adaline.ai

Set either ADALINE_PROJECT_ID or ADALINE_PARENT, but not conflicting values for both.

For batching and flush tuning — interval, batch size, and queue limits — see Configuration options below.

Choose an integration path

Use whichever path matches your current setup:

• AdalineSpanProcessor if you want Adaline to manage batching for spans exported from your tracer provider
• AdalineExporter if you already manage your own BatchSpanProcessor or exporter chain
• raw OTLP configuration if you want to point an existing collector/exporter directly at Adaline without using the package

Configure the AdalineSpanProcessor

The application logic that creates spans does not need to change. You only need to add the Adaline span processor to the tracer provider you already use.

TypeScript

import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { AdalineSpanProcessor } from "@adaline/otel";

const provider = new NodeTracerProvider();

provider.addSpanProcessor(
  new AdalineSpanProcessor({
    apiKey: process.env.ADALINE_API_KEY,
    projectId: process.env.ADALINE_PROJECT_ID,
  }),
);

provider.register();

Python

import os

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.trace import set_tracer_provider

from adaline_otel import AdalineOtelConfig, AdalineSpanProcessor

provider = TracerProvider()
provider.add_span_processor(
    AdalineSpanProcessor(
        AdalineOtelConfig(
            api_key=os.environ["ADALINE_API_KEY"],
            project_id=os.environ["ADALINE_PROJECT_ID"],
        )
    )
)

set_tracer_provider(provider)

Configure the AdalineExporter

Use the exporter directly when you already manage your own batch processor and only want Adaline as the OTLP destination.

TypeScript

import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
import { AdalineExporter } from "@adaline/otel";

const provider = new NodeTracerProvider();

provider.addSpanProcessor(
  new BatchSpanProcessor(
    new AdalineExporter({
      apiKey: process.env.ADALINE_API_KEY,
      projectId: process.env.ADALINE_PROJECT_ID,
    }),
  ),
);

provider.register();

Python

import os

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.trace import set_tracer_provider

from adaline_otel import AdalineExporter, AdalineOtelConfig

provider = TracerProvider()
provider.add_span_processor(
    BatchSpanProcessor(
        AdalineExporter(
            AdalineOtelConfig(
                api_key=os.environ["ADALINE_API_KEY"],
                project_id=os.environ["ADALINE_PROJECT_ID"],
            )
        )
    )
)

set_tracer_provider(provider)

Send OTLP traces directly to Adaline

If you already have an OTLP HTTP exporter or collector in place, you can point it directly at Adaline without using the package helpers.

• endpoint: https://api.adaline.ai/otel/v1/traces
• required header: Authorization: Bearer <ADALINE_API_KEY>
• routing header: either x-adaline-project-id: <PROJECT_ID> or x-adaline-parent: <PARENT>

This is the same destination the Adaline OTel packages use internally.

Basic example

This example stays intentionally small: one manually-created GenAI span with prompt and completion attributes. That is enough to validate the OTEL wiring without turning the docs into a full sample application.

TypeScript

import { trace } from "@opentelemetry/api";

const tracer = trace.getTracer("adaline-otel-docs");

await tracer.startActiveSpan("gen_ai.chat", async (modelSpan) => {
  modelSpan.setAttribute("gen_ai.system", "openai");
  modelSpan.setAttribute("gen_ai.operation.name", "chat");
  modelSpan.setAttribute("gen_ai.request.model", "gpt-4o-mini");
  modelSpan.setAttribute("gen_ai.prompt.0.role", "user");
  modelSpan.setAttribute("gen_ai.prompt.0.content", "Summarize the invoice.");
  modelSpan.setAttribute("gen_ai.completion.0.role", "assistant");
  modelSpan.setAttribute("gen_ai.completion.0.content", "Invoice inv_123 is marked as paid.");
  modelSpan.end();
});

Python

from opentelemetry import trace

tracer = trace.get_tracer("adaline-otel-docs")

with tracer.start_as_current_span("gen_ai.chat") as model_span:
    model_span.set_attribute("gen_ai.system", "openai")
    model_span.set_attribute("gen_ai.operation.name", "chat")
    model_span.set_attribute("gen_ai.request.model", "gpt-4o-mini")
    model_span.set_attribute("gen_ai.prompt.0.role", "user")
    model_span.set_attribute("gen_ai.prompt.0.content", "Summarize the invoice.")

    model_span.set_attribute("gen_ai.completion.0.role", "assistant")
    model_span.set_attribute("gen_ai.completion.0.content", "Invoice inv_123 is marked as paid.")

The goal of this example is simply to confirm that your OpenTelemetry pipeline can export a GenAI-style span to Adaline successfully.

Distributed tracing and multi-service workflows

If one service starts the trace and another service continues the work, create the Adaline parent once and propagate it downstream. Child services can recover that parent from incoming headers and attach new spans to the same trace.

TypeScript

import { addParentToBaggage, parentFromHeaders } from "@adaline/otel";

const adalineParent = "project_id:your-project-id";
const ctx = addParentToBaggage(adalineParent);

// Pass standard OTEL headers plus baggage to downstream services.
// On the receiving side:
const parent = parentFromHeaders(request.headers);

new AdalineSpanProcessor({
  apiKey: process.env.ADALINE_API_KEY,
  parent,
});

Python

import os
from adaline_otel import add_parent_to_baggage, parent_from_headers
from adaline_otel import AdalineOtelConfig, AdalineSpanProcessor

adaline_parent = "project_id:your-project-id"
ctx = add_parent_to_baggage(adaline_parent)

# Pass standard OTEL headers plus baggage to downstream services.
# On the receiving side:
parent = parent_from_headers(dict(request.headers))

processor = AdalineSpanProcessor(
    AdalineOtelConfig(
        api_key=os.environ["ADALINE_API_KEY"],
        parent=parent,
    )
)

Use this pattern when spans for a single agent run are produced across multiple workers, queue consumers, or services.

AI span filtering

The Adaline OTel packages can optionally export only AI-related spans by setting ADALINE_OTEL_FILTER_AI_SPANS=true.

When that filter is enabled, the package keeps spans whose span name or attribute keys start with one of these prefixes:

• gen_ai.
• adaline.
• llm.
• ai.
• traceloop.

This behavior is implemented in the SDK packages directly. If you leave filtering disabled, all spans passed to the exporter are forwarded to Adaline.

Configuration options

Option	Description
ADALINE_API_KEY	Required. Authenticates OTLP exports to Adaline.
ADALINE_API_URL	Optional. Defaults to https://api.adaline.ai.
ADALINE_PROJECT_ID	Routes spans into a project when no explicit parent is supplied.
ADALINE_PARENT	Routes spans to an existing Adaline parent for distributed tracing.
ADALINE_OTEL_FILTER_AI_SPANS	When true, exports only spans identified as AI spans.
ADALINE_OTEL_FLUSH_INTERVAL	Batch flush interval in seconds. Defaults to 5.
ADALINE_OTEL_MAX_BATCH_SIZE	Maximum number of spans per export batch. Defaults to 100.
ADALINE_OTEL_MAX_QUEUE_SIZE	Maximum in-memory queue size before flush pressure applies. Defaults to 1000.

Supported span patterns

Adaline works best with AI-oriented OpenTelemetry spans, especially spans that already carry GenAI-style attributes. In practice, that means:

• spans with gen_ai.* attributes
• spans emitted by frameworks that already use OpenTelemetry for LLM, tool, or retrieval steps
• custom spans that you annotate yourself with AI-related attributes

This page intentionally focuses on transport and wiring. The exact trace shape you see in Adaline depends on the spans and attributes your instrumentation emits.

Next steps

Instrument with the Adaline SDK

Monitor lifecycle, buffering and batching, retries, serverless flushing, and graceful shutdown.

SDK reference

Full class and type reference for the TypeScript and Python SDKs.

All integrations

Browse every framework and AI-provider integration Adaline supports.

View your logs

Open Adaline to see traces and spans land in your project.