What a trace holds
Every span carries
session.id, user.id, project.id, the organization, the agent’s id and the kind of credential the turn ran with, so a trace is found again from any of them. A conversation that belongs to no project (Klara outside a project) is not traced: traces are filed by project.
What never rides a span
The caller’s token and identity header never leave the platform: spans are exported under the platform’s own service identity, with the user and project named as attributes. Tool results appear in traces as the agent saw them, so a tool that returns sensitive data puts it in the trace; bind agents to the data they need and no more.With gwenflow
gwenflow, the agent framework the platform’s agents run on, is instrumented: every agent run opens anAGENT span, every model call an LLM span, every tool call a TOOL span, the same shapes the platform’s own traces have. An agent of your own, run anywhere, reports to the platform with one Telemetry() and a session scope naming the user and the project.
Telemetry() installs the OpenTelemetry provider, the OTLP exporter and gwenflow’s context processor; call it once, before the first run. tracer.session(...) stamps session.id and user.id on every span of the block, so a conversation of several turns is one session in the traces; metadata= adds any attribute of your own. Everything also reads the standard environment (OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_SERVICE_NAME) and GWENFLOW_TELEMETRY_API_KEY, so a deployed agent needs no telemetry code at all.
Two settings worth knowing: report_llm_usage=False on Telemetry() when the model is served by an endpoint that already emits a span per call, or the tokens are counted twice; and OTEL_SDK_DISABLED=true turns everything off.
Sending your own spans
The telemetry service speaks OTLP over HTTP, so an application of yours can file its traces under one of your projects with the standard OpenTelemetry SDK: point the exporter at the platform, authenticate with an API key created in that project, and the spans land next to the agents’ traces.user.id on a span names the person the trace is about, which is how the platform lists traces per user. Keep the standard attribute names (gen_ai.* for model calls) so your spans read like the agents’ ones.
The same exporter configured through the environment works for any instrumented library, with no code of your own:
Builds and models
Builds are not traced this way: a build has its log, and a training its experiment. Model calls made from a build through the platform are attributed to the build’s identity for usage and quota, not traced as spans.Traces are browsed from the Atlas interface. Reading them back over an API is not offered yet.