Skip to content

architecture.md

Latest commit

 

History

History
45 lines (31 loc) · 1.79 KB

architecture.md

File metadata and controls

45 lines (31 loc) · 1.79 KB
Raw

Architecture

Thin SDK, smart collector. The SDK does minimal work in the hot path; everything heavy runs in the OpenTelemetry Collector.

What the SDK does

  • Generates a UUIDv7 run_id per event
  • Sets seven W3C Baggage keys on the active OTel context
  • Records token counts as span attributes
  • Exports spans via OTLP/HTTP

Target overhead: under 0.5 ms per request.

What the collector does

  • Cost calculation from token counts
  • Vendor normalization
  • Cardinality management
  • Aggregation and sampling
  • Belt-and-suspenders PII regex (SDK already scrubs captured content in-process — see botanu/sdk/pii.py)

SDK components

  • BotanuConfig — configuration dataclass. See Configuration.
  • RunContext — run metadata + serialization. See Run Context.
  • RunContextEnricher — OTel SpanProcessor that reads baggage and stamps span attributes.
  • Tracking helpers: track_llm_call, track_db_operation, track_storage_operation, track_messaging_operation.

Integration

from opentelemetry import trace
from botanu.processors.enricher import RunContextEnricher

provider = trace.get_tracer_provider()
provider.add_span_processor(RunContextEnricher())

If you already have an OTel setup, the SDK detects it and adds itself alongside. See Coexisting with existing OTel / Datadog.

See also