How does Rius read OpenLLMetry agent name attributes?

Rius reads the name of a function you decorate as an agent with OpenLLMetry (Traceloop’s SDK) and turns it into the invoked agent’s name, so you can search and filter on it. The decorator’s traceloop.span.kind of agent sets the span’s kind, and the decorated entity’s name becomes the agent name. The original traceloop.entity.name key also stays on the span. You change nothing in your instrumentation: point the exporter at Rius and the mapping happens at ingest.

How it works

OpenLLMetry marks decorated code with traceloop.span.kind, which is one of workflow, task, agent or tool, and records the decorated entity’s name under traceloop.entity.*. When the spans reach Rius, the platform normalizes them onto its canonical keys before storage:

• Span kind. The Traceloop decorator kinds become the span taxonomy. For an agent, that is the AGENT kind with the invoke_agent operation. Set either one and Rius derives the other.
• Agent name. The decorated entity’s name becomes the invoked agent’s name. On an invoke_agent span the canonical key is gen_ai.agent.name. For a tool, the name goes to gen_ai.tool.name instead.
• Kept source key. traceloop.entity.name stays on the span on purpose, so you see it next to the canonical key.
• Input and output. traceloop.entity.input and traceloop.entity.output become input.value and output.value.

Native gen_ai.* keys always win. Normalization fills gaps and never overwrites a value your spans already carry.

The agent name is also what Rius groups by. It files a span under the first of these that is set and is not a placeholder such as unknown_service:

1. the resource gen_ai.main_agent.name
2. the resource rius.main_agent.name
3. the resource gen_ai.agent.name
4. the span’s gen_ai.agent.name
5. service.name

The name from an OpenLLMetry agent decorator is a span-level gen_ai.agent.name, so it is used when none of the resource-level names is set. If your telemetry sets gen_ai.main_agent.name on the resource, that name wins for grouping, and the decorated name stays on the span.

Set it up

1. Point OpenLLMetry’s exporter at Rius. This is the only setup the mapping needs. It uses OpenLLMetry’s default OTLP/HTTP protobuf export, which the endpoint expects.

from traceloop.sdk import Traceloop
 
Traceloop.init(
    app_name="my-agent",
    api_endpoint="https://ingest.eu.console.rius-glassflow.com",
    headers={"Authorization": "Bearer <your API key>"},
)

2. Keep your Traceloop agent decorator on the function that runs the agent. Its traceloop.span.kind of agent and the function’s name are what Rius reads. Give the function the name you want to see as the agent name.
3. If you want one fixed agent name for the whole process regardless of decorators, set gen_ai.main_agent.name as a resource attribute on your telemetry. It takes precedence in the grouping order above.
4. On an older OpenLLMetry release that records messages one attribute per field, raise OpenTelemetry’s per-span attribute limit for long agent runs. Past 128 attributes, a span can lose its model, tools, usage or messages. The span attribute reference has the setting.
5. Run one traced call and open the trace in the console. Check that the agent span shows the agent name, then search on gen_ai.agent.name, the canonical key. A search on the source key traceloop.entity.name also finds the span, because that key is kept.

The full exporter setup, including the environment-variable route, is on the OpenLLMetry page. The rest of the conventions Rius normalizes are in the interoperability overview and in Trace LLM calls with OpenTelemetry.

What you get

• Agent spans from OpenLLMetry classified as agent steps, with the decorated function’s name as the agent name.
• One canonical key, gen_ai.agent.name, to search and filter on, whichever OpenLLMetry release produced the span.
• The original traceloop.entity.name kept on the span for reference.
• Agent input and output stored as input.value and output.value.
• Tool spans named by gen_ai.tool.name, from the same decorator mapping.
• Model, token and cost analytics that work across OpenLLMetry versions, because the older usage and message spellings are normalized as well. Cost is a list-price estimate in US dollars that Rius computes from the model and token counts, so you never send it.

Two things are not mapped yet and are stored under their own names: the per-completion gen_ai.completion.N.finish_reason of older releases, and the flattened tool definitions under llm.request.functions.*.

When something else fits

• If you need the agent name to be stable across code changes, set gen_ai.main_agent.name on the resource instead of relying on a decorated function’s name.
• If your app is not instrumented with OpenLLMetry, the span attribute reference shows which attributes to set from any OpenTelemetry sender, such as gen_ai.agent.name on an invoke_agent span.

Related