Advanced Features

Filtering by Instrumentation Scope

You can restrict which observations XeroML captures by configuring instrumentation scope filters. This is useful when you have third-party libraries that produce many spans you don’t care about.

from xeroml import get_client

xeroml = get_client(
    instrumentation_scope_filter=lambda scope: scope.startswith("xeroml")
)

TypeScript:

import { XeroMLSpanProcessor } from "@xeroml/otel";

const processor = new XeroMLSpanProcessor({
  instrumentationScopeFilter: (scope) => scope.startsWith("xeroml"),
});

Async and Concurrent Workloads

XeroML’s OpenTelemetry foundation handles async context propagation automatically in Python’s asyncio and Node.js’s event loop. Observations created in async functions correctly nest under their parent regardless of execution order.

import asyncio
from xeroml import observe, get_client

xeroml = get_client()

@observe(type="span")
async def parallel_retrieval(queries: list[str]) -> list[str]:
    # These run concurrently but each creates a properly nested child observation
    tasks = [retrieve(q) for q in queries]
    return await asyncio.gather(*tasks)

Disabling Tracing Temporarily

Disable tracing for a specific block without uninstalling the instrumentation:

from xeroml import disable_tracing

with disable_tracing():
    # Nothing in here is traced
    sensitive_operation()

Custom Observation IDs

When you need to correlate a XeroML trace with an external system, generate a predictable ID using create_trace_id():

from xeroml import create_trace_id, propagate_attributes

# The same seed always produces the same trace ID
trace_id = create_trace_id(seed=f"job-{job_id}")

with propagate_attributes(trace_id=trace_id):
    process_job(job_id)

This allows you to look up the XeroML trace by ID from your application code or external system.

Multi-Service / Distributed Tracing

For applications that span multiple services (e.g., a gateway that calls a separate inference service), XeroML supports W3C trace context propagation. Inject the trace context in the upstream service and extract it in the downstream service to create a single unified trace.

# Upstream service — inject context into outgoing headers
from opentelemetry.propagate import inject

headers = {}
inject(headers)
response = httpx.post("https://inference-service/generate", headers=headers, ...)

# Downstream service — extract context from incoming request
from opentelemetry.propagate import extract
from xeroml import get_client

xeroml = get_client()

context = extract(request.headers)
with xeroml.start_as_current_observation(
    name="inference",
    type="span",
    context=context
) as obs:
    result = generate(request.body)
    obs.update(output=result)

SDK Errors and Resilience

XeroML SDKs catch all internal errors and log them without propagating exceptions to your application. If the XeroML API is unreachable, your application continues running — traces are simply dropped after the retry budget is exhausted. This ensures XeroML instrumentation never becomes a point of failure in your production system.