Recipe 24 — OpenTelemetry traces from the SDK

Status: ✅ runnable SDK surface: ClientConfig(telemetry_enabled=True) + configure_console_exporter / configure_otlp_exporter helpers TZ reference: TZ-10 §26.5 (opt-in OTel) + §20.7.1 (exporter detail)

The SDK ships a no-op tracer by default. To start emitting one OpenTelemetry span per SDK request:

Install the optional [telemetry-exporters] extra (Python) or the OTel peer-deps (TS).
Call configure_console_exporter() or configure_otlp_exporter(endpoint) before constructing the client.
Set telemetry_enabled=True on the client config.

Each span carries: cryptoai.endpoint, cryptoai.request_id (echoes the server's X-Request-ID response header), http.request.method, http.status_code.

Install

# Python — adds OTel SDK + OTLP/HTTP exporter
pip install 'cryptoai-gateway[telemetry-exporters]'

# TypeScript — peer-deps (the SDK declares them as optional)
npm install @opentelemetry/api @opentelemetry/sdk-trace-node \
            @opentelemetry/exporter-trace-otlp-http

The base SDK install (no extras) still works — configure_*_exporter helpers raise RuntimeError (Python) / Error (TS) with a clear install hint, and spans are no-ops without an exporter.

Public surface (M5-S2)

Helper	Behavior
`configure_console_exporter()`	Installs `BatchSpanProcessor(ConsoleSpanExporter())`. Pretty-prints spans to stdout.
`configure_otlp_exporter(endpoint=None, headers=...)`	Installs `BatchSpanProcessor(OTLPSpanExporter(...))`. `endpoint=None` falls back to TZ-10 §20.7.1 default `https://otel.cryptoai-gateway.com/v1/ingest`.
`_reset_for_tests()` / `_resetForTests()`	Test-only. Resets idempotency flags.

Both configure_* helpers are idempotent — calling twice is a no-op on the second call (no double-registered span processors).

Run

PYTHONPATH=packages/sdk-py/src python cookbook/recipes/24-opentelemetry-traces/python_example.py
npx tsx cookbook/recipes/24-opentelemetry-traces/typescript_example.ts

Notes

The TZ-10 §20.7.1 default OTLP endpoint (https://otel.cryptoai-gateway.com/v1/ingest) is M6+ deployment. Day-0 consumers should either pass an explicit endpoint or use the console exporter for local development.
When telemetry_enabled=False (default) the SDK is OTel-free — no spans are created and the opentelemetry-api import is not even attempted.
The OTel exporter helpers and telemetry_enabled are independent: an exporter installed without telemetry_enabled=True simply has nothing to flush. Both must be set to see spans.