register()¶

Configure the Coalex OTLP exporter. Call once at application startup before any other Coalex SDK calls.

Signature¶

PythonTypeScript

def register(
    *,
    endpoint: str = "https://traces.azure.coalex.ai",
    api_key: str = "dev",
    service_name: str = "coalex-sdk-python",
    filter_non_ai_spans: bool = False,
    suppress_export_errors: bool = True,
) -> None

interface RegisterOptions {
    endpoint?: string;          // default: "https://traces.azure.coalex.ai"
    apiKey?: string;            // default: "dev"
    serviceName?: string;       // default: "coalex-sdk-typescript"
    filterNonAiSpans?: boolean; // default: false
    suppressExportErrors?: boolean; // default: true
}

function register(options?: RegisterOptions): void

Parameters¶

Parameter	Type	Default	Description
`endpoint`	`str`	`"https://traces.azure.coalex.ai"`	Coalex proxy HTTP endpoint. Optional — the default points to the Azure-hosted cloud. Only override for on-prem, GCP deployments, or local development.
`api_key`	`str`	`"dev"`	API key for proxy authentication. Use `"dev"` for local development with `docker compose`.
`service_name`	`str`	`"coalex-sdk-python"`	OpenTelemetry service name. Appears in the Coalex dashboard as the service identifier.
`filter_non_ai_spans`	`bool`	`False`	When `True`, only AI/LLM spans are exported. HTTP, DB, and other non-AI spans are dropped before export.
`suppress_export_errors`	`bool`	`True`	When `True`, export errors are logged but do not raise exceptions. Set to `False` for debugging connectivity issues.

All parameters are keyword-only (enforced by *).

Returns¶

None. The function configures global state as a side effect.

What it does¶

Calling register() performs the following setup:

Creates an OpenTelemetry Resource with service.name set to service_name.
Creates an OTLPSpanExporter pointing at {endpoint}/v1/traces with an Authorization: Bearer {api_key} header.
Wraps the exporter in a SafeOTLPSpanExporter (suppresses transient network errors when suppress_export_errors=True).
Optionally wraps in a FilteringSpanExporter (when filter_non_ai_spans=True).
Creates a TracerProvider with a CoalexAttributePropagator (copies coalex.* attributes from parent to child spans) and a BatchSpanProcessor.
Sets the TracerProvider as the global OpenTelemetry tracer provider via trace.set_tracer_provider().

Call once only

register() sets the global TracerProvider. Calling it multiple times replaces the provider, which can cause spans to be dropped. Always call it once at the top of your application entrypoint.

Examples¶

Production (Azure — default)¶

No endpoint needed. The SDK connects to traces.azure.coalex.ai by default.

PythonTypeScript

import os
import coalex

coalex.register(
    api_key=os.environ["COALEX_API_KEY"],
    service_name="claims-agent",
)

import { register } from "@coalex-ai/sdk";

register({
    apiKey: process.env.COALEX_API_KEY!,
    serviceName: "claims-agent",
});

On-prem or GCP deployment¶

Only set endpoint when using a self-hosted proxy or a non-default cloud region.

PythonTypeScript

import os
import coalex

coalex.register(
    endpoint=os.environ["COALEX_ENDPOINT"],  # e.g. "https://traces.gcp.coalex.ai"
    api_key=os.environ["COALEX_API_KEY"],
    service_name="claims-agent",
)

import { register } from "@coalex-ai/sdk";

register({
    endpoint: process.env.COALEX_ENDPOINT!, // e.g. "https://traces.gcp.coalex.ai"
    apiKey: process.env.COALEX_API_KEY!,
    serviceName: "claims-agent",
});

Local development¶

PythonTypeScript

import coalex

coalex.register(
    endpoint="http://localhost:8080",
    api_key="dev",
    service_name="my-agent-dev",
)

import { register } from "@coalex-ai/sdk";

register({
    endpoint: "http://localhost:8080",
    apiKey: "dev",
    serviceName: "my-agent-dev",
});

Debugging export issues¶

PythonTypeScript

import coalex

coalex.register(
    api_key="your-api-key",
    service_name="my-agent",
    suppress_export_errors=False,  # raises on export failure
)

import { register } from "@coalex-ai/sdk";

register({
    apiKey: "your-api-key",
    serviceName: "my-agent",
    suppressExportErrors: false, // throws on export failure
});

Filtering non-AI spans¶

PythonTypeScript

import coalex

coalex.register(
    api_key="your-api-key",
    service_name="my-agent",
    filter_non_ai_spans=True,  # only export LLM/AI spans
)

import { register } from "@coalex-ai/sdk";

register({
    apiKey: "your-api-key",
    serviceName: "my-agent",
    filterNonAiSpans: true, // only export LLM/AI spans
});

Notes¶

The SDK always sends traces through the proxy (via load balancer) so that authentication is validated in the request path. Never point endpoint directly at the collector.
The api_key is sent as a Bearer token in the Authorization header on every OTLP export request.
The BatchSpanProcessor buffers spans and exports them in batches asynchronously, so register() returns immediately.
If you need to use a custom TracerProvider (e.g., with additional processors or exporters), configure it yourself and pass it to auto_instrument(tracer_provider=...) instead of calling register().

API Reference¶

coalex.register ¶

register(
    *,
    endpoint: str = "https://traces.azure.coalex.ai",
    api_key: str = "dev",
    service_name: str = "coalex-sdk-python",
    filter_non_ai_spans: bool = False,
    suppress_export_errors: bool = True,
) -> None

Configure the Coalex OTLP exporter.

Call once at application startup. Sets the global TracerProvider with a BatchSpanProcessor exporting OTLP/HTTP to the Coalex proxy.

The SDK always sends through the proxy (via LB) so that auth validation is in the path. Never send directly to the collector.

Parameters:

Name	Type	Description	Default
`endpoint`	`str`	Coalex proxy HTTP endpoint (default: cloud).	`'https://traces.azure.coalex.ai'`
`api_key`	`str`	API key for proxy authentication (default: "dev" for local).	`'dev'`
`service_name`	`str`	Service name for OTLP resource (default: "coalex-sdk-python").	`'coalex-sdk-python'`
`filter_non_ai_spans`	`bool`	If True, only export AI/LLM spans (default: False).	`False`
`suppress_export_errors`	`bool`	If True, suppress export errors gracefully (default: True).	`True`

Source code in coalex/__init__.py

def register(
    *,
    endpoint: str = "https://traces.azure.coalex.ai",
    api_key: str = "dev",
    service_name: str = "coalex-sdk-python",
    filter_non_ai_spans: bool = False,
    suppress_export_errors: bool = True,
) -> None:
    """Configure the Coalex OTLP exporter.

    Call once at application startup. Sets the global TracerProvider
    with a BatchSpanProcessor exporting OTLP/HTTP to the Coalex proxy.

    The SDK always sends through the proxy (via LB) so that auth
    validation is in the path. Never send directly to the collector.

    Args:
        endpoint: Coalex proxy HTTP endpoint (default: cloud).
        api_key: API key for proxy authentication (default: "dev" for local).
        service_name: Service name for OTLP resource (default: "coalex-sdk-python").
        filter_non_ai_spans: If True, only export AI/LLM spans (default: False).
        suppress_export_errors: If True, suppress export errors gracefully (default: True).
    """
    global _config, _api_key

    from opentelemetry import trace
    from opentelemetry.exporter.otlp.proto.http.trace_exporter import (
        OTLPSpanExporter,
    )
    from opentelemetry.sdk.resources import Resource
    from opentelemetry.sdk.trace import TracerProvider
    from opentelemetry.sdk.trace.export import BatchSpanProcessor

    from coalex.filtering_exporter import FilteringSpanExporter
    from coalex.safe_exporter import SafeOTLPSpanExporter
    from coalex.span_processor import CoalexAttributePropagator

    _config = CoalexConfig(endpoint=endpoint, service_name=service_name)
    _api_key = api_key

    resource = Resource({"service.name": service_name})

    base_exporter = OTLPSpanExporter(
        endpoint=f"{_config.endpoint}/v1/traces",
        headers={"Authorization": f"Bearer {api_key}"},
    )

    # Wrap exporter chain: OTLP -> Safe -> Filtering (when enabled)
    safe_exporter = SafeOTLPSpanExporter(base_exporter, suppress_errors=suppress_export_errors)
    final_exporter = FilteringSpanExporter(safe_exporter) if filter_non_ai_spans else safe_exporter

    provider = TracerProvider(resource=resource)
    provider.add_span_processor(CoalexAttributePropagator())
    provider.add_span_processor(BatchSpanProcessor(final_exporter))
    trace.set_tracer_provider(provider)