OpenTelemetry integration

​

Send traces from any OTel-instrumented app (no Zespan SDK)

curl -X POST https://api.zespan.com/v1/traces \
  -H "x-api-key: $ZESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @export-trace-service-request.json

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter(
    endpoint="https://api.zespan.com/v1/traces",
    headers={"x-api-key": "zsp_..."},
)))

​

Attributes Zespan reads

​

AI gateways

• One model call per request. The gateway’s proxy, routing, infrastructure and retry or fallback attempt spans are stored as gateway spans, which are never counted as model calls (see span kinds). Only the span that carries the model call is a model call. Failed attempts keep their HTTP status, error type and provider so you can see why a request was retried or fell back. A failed LiteLLM request span is treated as an attempt only when the same export also holds a successful call of the same request (same trace and same parent span); a request that failed for good stays a failed model call, also when several requests share one trace.
• Cost uses Zespan’s prices. The gateway’s own figure is kept as evidence next to the span. It replaces Zespan’s price only for a model Zespan has no price for and only when GATEWAY_COST_FALLBACK=on is set on a self-hosted deployment. A gateway’s cache-hit or zero-cost figure never makes a call free. The two figures are never added.
• Gateway identity metadata is dropped at ingest. Some gateways (LiteLLM, Portkey) attach the end user’s e-mail, the requester’s IP address, key hashes and ids, team and key aliases or request headers to their spans. Zespan removes them before anything is stored, whatever your content capture settings are. The end-user id you set yourself (for example llm.user) stays. Self-hosted: GATEWAY_META_DENYLIST=off keeps them.
• Prompts and completions follow your capture settings. Many gateways export prompts and completions by default (LiteLLM, Portkey, Cloudflare), so check your project’s content capture and PII redaction settings before you point a gateway at Zespan: with prompt capture off none of that text is stored; with it on, redaction applies like it does to SDK data.
• A call your SDK also sees can have its tokens and cost counted once. If your app uses the Zespan SDK and calls the model through one of these gateways that also exports to Zespan, the same call arrives twice. When merging is on for your project, Zespan keeps both rows, nests the gateway’s span under the SDK span when they matched by trace link, and sets the tokens and cost of the row that arrived second to 0 (the gateway’s row is held back for a short time so the SDK’s row can arrive first). Call counts are not all merged: counts built from hourly totals still count both rows as calls. Matching uses the trace link when you turn on the SDK option below, and otherwise the provider’s response id (only an id that is long and random enough: a short or numeric id, such as some local OpenAI-compatible servers return, is not matched). A row without tokens or cost is never the one kept. When Zespan cannot tell, it counts both. Until merging is on, both rows are counted. See Using the SDK too.
• Check what arrived. Settings → Instrumentation → Gateway and OTLP data lists, per source, when data last arrived, how (JSON or Protobuf, gzip), and what share of model calls came with tokens, a span kind and text, with a one-line fix for each problem. Send one request, then press Refresh. See Instrumentation.

​

Using the SDK too

import { initZespan } from "@zespan/sdk";

initZespan({
  apiKey: process.env.ZESPAN_API_KEY!,
  gatewayCorrelation: { hosts: ["gateway.example.com"] },
});

import zespan

zespan.init(
    api_key="zsp_...",
    gateway_correlation={"hosts": ["gateway.example.com"]},
)

​

Finish and failure outcome

​

Tool spans from OTel frameworks

​

Tool definitions and Google ADK native spans (self-hosted, off by default)

• Tool definitions from gen_ai.tool.definitions and from OpenInference llm.tools.N.tool.json_schema, recorded with their parameter schemas (defaults, examples and constants removed, descriptions limited to 500 characters, never a partial list).
• Google ADK’s own spans: the request (gcp.vertex.agent.llm_request: the conversation, the system instructions, the tools, the response schema and whether JSON was requested) and the response (gcp.vertex.agent.llm_response: the text and the function calls). ADK’s own spans carry no GenAI content attributes unless your exporter adds them, so without this the answer and the definitions are not recorded; the callback handler in the Python or TypeScript SDK is more complete.
• The tool call id is gen_ai.tool.call.id only. It is no longer filled in with the tool name, because a name is not an id and breaks matching a request with its execution.
• The error code of a failed span is its own error.type when that is a short code, and the fixed value it always was otherwise.

​

Stack span kinds

await withSpan("rank-passages", async () => rerank(query, docs), { spanKind: "reranker" });

​

Dual-export to your own OTel backend

​

When to use this instead of startSpan

• You already export traces to an existing OTel backend and want Zespan’s spans to appear there too, dual-exported from the same instrumentation.
• You need direct access to the underlying OTel Span object — for example, to set attributes with span.setAttribute() or interoperate with another library that expects a native OTel span.
• You’re building an integration that needs a real TracerProvider registered globally (some auto-instrumentation libraries look for one).

​

Relationship to enableOTel / otelEndpoint

​

initOTel(config) / init_otel(config)

import { initOTel } from "@zespan/sdk";

const { tracer, provider } = initOTel({
  endpoint: "https://otel-collector.internal:4318/v1/traces",
  serviceName: "checkout-service",
  environment: "production",
  apiKey: process.env.ZESPAN_API_KEY,
});

from zespan import init_otel, OTelConfig

init_otel(OTelConfig(
    endpoint="https://otel-collector.internal:4318/v1/traces",
    service_name="checkout-service",
    environment="production",
    api_key=os.environ["ZESPAN_API_KEY"],
))

​

OTelConfig

​

getTracer() / get_tracer()

import { getTracer } from "@zespan/sdk";

const tracer = getTracer();

from zespan import get_tracer

tracer = get_tracer()

​

createSpan / create_span

import { createSpan, SpanKind } from "@zespan/sdk";

const span = createSpan({
  name: "cache-lookup",
  kind: SpanKind.CLIENT,
  attributes: { "cache.key": "user:123" },
});

try {
  const value = await lookupCache("user:123");
  span.setAttribute("cache.hit", value !== null);
} finally {
  span.end();
}

from zespan import create_span
from opentelemetry.trace import SpanKind

span = create_span(
    "cache-lookup",
    kind=SpanKind.CLIENT,
    attributes={"cache.key": "user:123"},
)

try:
    value = lookup_cache("user:123")
    span.set_attribute("cache.hit", value is not None)
finally:
    span.end()

​

withSpan / with_span

import { withSpan, SpanKind } from "@zespan/sdk";

const result = await withSpan(
  "process-payment",
  async (span) => {
    span.setAttribute("payment.provider", "stripe");
    return chargeCard(order);
  },
  { kind: SpanKind.CLIENT, attributes: { "order.id": order.id } }
);

from zespan import with_span
from opentelemetry.trace import SpanKind

async with with_span(
    "process-payment",
    kind=SpanKind.CLIENT,
    attributes={"order.id": order.id},
) as span:
    span.set_attribute("payment.provider", "stripe")
    result = await charge_card(order)

​

SpanKind values

​

SpanStatusCode values

​

BaggageSpanProcessor

import { BaggageSpanProcessor } from "@zespan/sdk";
import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";

const provider = new NodeTracerProvider({ /* ...resource, etc. */ });
provider.addSpanProcessor(new BaggageSpanProcessor());
provider.register();