Documentation
Ingestion Options
Choose between Guardy-native SDK tracking and OpenTelemetry trace ingestion.
Guardy supports two ingestion paths. You can use the Guardy SDK for the richest agent-aware experience, or send OpenTelemetry traces when you already have an OTel pipeline.
Best for new integrations, agent sessions, tool calls, prompt variants, costs, and Guardy-specific workflows.
OpenTelemetryBest when your agents already emit OTel spans or you need vendor-neutral collection through an existing collector.
Which Path Should I Use?
Use the Guardy SDK when you want the most complete Guardy experience with minimal mapping:
begin()andfinish()sessions- automatic tool and LLM wrappers
convo_idgrouping- production prompt variant routing with
getVariant() - automatic run classification after completion
Use OpenTelemetry when you already have traces:
- existing OTel SDKs or collectors
- GenAI semantic convention spans
- multi-vendor observability pipelines
- gradual migration from another tracing tool
Data Model Mapping
| Concept | Guardy SDK | OpenTelemetry |
|---|---|---|
| Run | Session created by begin() or create_session() | One trace becomes one Guardy session |
| Timeline item | SDK event, tool call, or decision | Each span becomes a Guardy event |
| Conversation grouping | convo_id / convoId | conversation.id, guardy.convo_id, thread.id, or trace fallback |
| User grouping | user_id / userId | user.id, enduser.id, or guardy.user_id |
| Prompt variants | getVariant() returns sticky assignment | Add assignment attributes to spans after routing |
| Classification | Runs are classified after terminal status | Imported traces are classified after ingest |
Recommendation
Start with the Guardy SDK unless your application already has mature OpenTelemetry traces. Use OTel when you need interoperability, but keep Guardy attributes on the root span so sessions, conversations, experiments, and classifications line up cleanly.