OpenTelemetry

XeroML is built on OpenTelemetry. If your framework or language has an OTEL exporter, you can send traces to XeroML by pointing the exporter at XeroML’s OTLP endpoint.

OTLP Endpoint

XeroML accepts traces via the OTLP/HTTP protocol:

https://cloud.xeroml.com/api/public/otel/v1/traces

For self-hosted deployments, replace with your instance URL.

Authentication

XeroML uses Basic auth for OTEL ingestion. Set the Authorization header:

Authorization: Basic <base64(pk-xm-...:sk-xm-...)>

Python Example

Using the standard OTEL Python SDK:

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

# Encode credentials
credentials = base64.b64encode(b"pk-xm-...:sk-xm-...").decode()

exporter = OTLPSpanExporter(
    endpoint="https://cloud.xeroml.com/api/public/otel/v1/traces",
    headers={"Authorization": f"Basic {credentials}"},
)

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

tracer = trace.get_tracer("my-service")

with tracer.start_as_current_span("my-operation") as span:
    span.set_attribute("xeroml.user.id", "user-123")
    span.set_attribute("xeroml.session.id", "session-abc")
    result = do_work()
    span.set_attribute("xeroml.output", result)

XeroML-Specific Attributes

When using raw OTEL, set these span attributes to enable XeroML-specific features:

OTEL Attribute	XeroML Field
xeroml.user.id	User tracking
xeroml.session.id	Session grouping
xeroml.environment	Environment filtering
xeroml.tags	Trace tags (comma-separated)
xeroml.metadata	JSON string metadata
gen_ai.system	Model provider (for cost tracking)
gen_ai.request.model	Model name
gen_ai.usage.input_tokens	Input token count
gen_ai.usage.output_tokens	Output token count

TypeScript Example

import { NodeSDK } from "@opentelemetry/sdk-node";
import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";

const credentials = Buffer.from("pk-xm-...:sk-xm-...").toString("base64");

const exporter = new OTLPTraceExporter({
  url: "https://cloud.xeroml.com/api/public/otel/v1/traces",
  headers: { Authorization: `Basic ${credentials}` },
});

const sdk = new NodeSDK({ traceExporter: exporter });
sdk.start();

Sending to Multiple Backends

Because XeroML is OTEL-native, you can send traces to XeroML and another backend simultaneously using a MultiSpanExporter:

from opentelemetry.sdk.trace.export import MultiSpanExporter, BatchSpanProcessor

exporter = MultiSpanExporter([
    xeroml_exporter,
    your_other_exporter,
])
provider.add_span_processor(BatchSpanProcessor(exporter))

This eliminates vendor lock-in — your instrumentation code doesn’t need to change if you add or remove XeroML.