Python SDK
Migrating from radicas_otel
Move from the bench's setup_telemetry() connection layer to radicas.init() — a mapping table and what you gain.
shared/python/radicas_otel (the env-only setup_telemetry() layer used by the bench
examples) is superseded by the SDK for end users. The SDK's transport is adapted from it —
same providers, same exporters, same env contract — so migration is mechanical and the two
produce compatible telemetry.
Code mapping
| radicas_otel | radicas SDK |
|---|---|
pip install -e shared/python | pip install "radicas[adk]" (pick your extra) |
from radicas_otel import setup_telemetry | import radicas |
setup_telemetry() | radicas.init() |
shutdown_telemetry() | radicas.shutdown() (also atexit-registered by init()) |
FeatureTagProcessor (added for you) | still added for you — plus radicas.feature() / radicas.user() runtime scoping |
| — (not available) | connectivity validation at init (validate=) |
| — (not available) | framework auto-instrumentation (instrument="auto") |
| — (not available) | client-side normalization of llm.* sources at export |
Environment mapping
Your existing .env keeps working — the SDK reads the same OTel contract, plus friendlier
RADICAS_* twins:
| radicas_otel env | SDK equivalent | Notes |
|---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT | still honored; or RADICAS_ENDPOINT / endpoint= | LOCAL default http://localhost:4317 applies when unset and no key is present |
OTEL_EXPORTER_OTLP_PROTOCOL | still honored; or RADICAS_PROTOCOL / protocol= | auto-detected from endpoint/mode when unset |
OTEL_EXPORTER_OTLP_HEADERS=authorization=Bearer ... | replaced by RADICAS_API_KEY / api_key= | the SDK builds the header; hand-set headers still work if you skip the key |
OTEL_SERVICE_NAME | still honored; or RADICAS_SERVICE / service= | |
FEATURE_NAME | still honored (legacy); prefer RADICAS_FEATURE / feature= | |
TENANT_ID | still honored (legacy); prefer RADICAS_TENANT_ID | LOCAL lab only — ONLINE tenancy comes from the key (authentication) |
RADICAS_SOURCE | unchanged | |
OTEL_SEMCONV_STABILITY_OPT_IN | set for you (gen_ai_latest_experimental) | remove from your .env if you like |
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT | still honored; prefer RADICAS_CAPTURE_CONTENT / capture_content= | note: the SDK default is OFF (opt-in) — the old examples set it on explicitly |
METRIC_EXPORT_INTERVAL_SECONDS | unchanged |
Before / after
# before (bench style)
from radicas_otel import setup_telemetry, shutdown_telemetry
setup_telemetry()
try:
run_agent()
finally:
shutdown_telemetry()# after
import radicas
radicas.init(service="my-agent", feature="my-feature")
run_agent()
radicas.shutdown() # optional — atexit covers normal exitsBehavioral differences to know about
- Content capture default.
radicas_otelrelied on the example.envsettingEVENT_ONLY; the SDK defaults content capture to off (privacy-first). Re-enable withcapture_content=True. - Tenant in ONLINE mode.
radicas_otelforwarded whateverOTEL_RESOURCE_ATTRIBUTESsaid; the SDK never sendsradicas.tenant_idwhen an API key is present (the gateway derives and enforces it anyway). - Validation.
init()probes the endpoint and warns immediately instead of failing silently at the first flush. Disable withvalidate=Falseif you must init offline. - Normalization. Spans from recognized non-
gen_aisources are renamed client-side at export (originals kept) and stampedradicas.source_framework.
The bench examples themselves keep using radicas_otel — it remains the minimal reference
wiring for deep-dives.