How do I name my agent with OpenInference instrumentors?

Rius takes your agent’s name from the resource attributes of your tracer provider, so with OpenInference instrumentors you set gen_ai.main_agent.name and service.name there. The instrumentors record the model, tokens and content of each call, and the resource carries the agent’s name. With the Rius SDK, service_name in init() does the same job.

How it works

OpenInference instrumentors emit standard OpenTelemetry spans. Rius reads the span kind, content, model, tokens, session and user from them and normalizes these onto its own attribute keys at ingest. The agent’s name comes from the resource, which is the set of attributes attached to every span your tracer provider exports.

Rius files a span under the first of these that is set and is not a placeholder such as unknown_service:

• the resource gen_ai.main_agent.name
• the resource rius.main_agent.name
• the resource gen_ai.agent.name
• the span’s own gen_ai.agent.name
• service.name

So if you set only service.name, your agent is named after the service. Set gen_ai.main_agent.name as well when you want the agent name to be explicit, and it wins over the others. rius.main_agent.name is deprecated in favor of gen_ai.main_agent.name, so use the gen_ai key in new setups. The full list of resource attributes is in the span attribute reference.

If you run the instrumentors through the Rius SDK instead, you do not build the provider yourself. Pass service_name to init(), and set RIUS_AGENT_NAME if the agent’s name should differ from the service name.

Set it up

1. Choose one name and use it for both service.name and gen_ai.main_agent.name.
2. Attach the name as resource attributes on the tracer provider that you pass to the instrumentor. This is the OpenInference setup from OpenInference with a resource added. Replace my-agent with your agent’s name and the placeholder with your API key.

from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import SpanLimits, TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from openinference.instrumentation.openai import OpenAIInstrumentor
 
provider = TracerProvider(
    resource=Resource.create(
        {
            "service.name": "my-agent",
            "gen_ai.main_agent.name": "my-agent",
        }
    ),
    span_limits=SpanLimits(max_span_attributes=4096),
)
provider.add_span_processor(
    BatchSpanProcessor(
        OTLPSpanExporter(
            endpoint="https://ingest.eu.console.rius-glassflow.com/v1/traces",
            headers={"Authorization": "Bearer <your API key>"},
        )
    )
)
OpenAIInstrumentor().instrument(tracer_provider=provider)

3. Keep the raised span attribute limit. OpenInference writes one attribute per message and tool field, and OpenTelemetry keeps only 128 per span by default, so a long agent loop can lose the model or usage. The limit of 4096 in the code above handles it. For other languages, OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT does the same.
4. Run one traced call and open Traces in the console. Confirm the agent shows under the name you chose. The wider setup for this and other senders is in Trace LLM calls with OpenTelemetry.

What you get

• Your agent’s spans are filed under the name you set, instead of a placeholder such as unknown_service.
• The calls that the OpenInference instrumentor records keep their model analytics, token counts and server-side cost, because Rius normalizes the OpenInference attributes onto its own keys.
• A name you control. Changing it is a one-line edit to the resource, with no change to the instrumentor.
• Search and filter on the keys Rius stores, such as gen_ai.usage.input_tokens rather than llm.token_count.prompt.

When something else fits

• If your app is Python or TypeScript, the Rius SDK runs the same instrumentors for you and takes the name from service_name in init(). It also sends heartbeats, so the agent lists its running instances.
• With a plain OpenTelemetry exporter there are no heartbeats, so an agent that sends traces is marked no heartbeat and lists no instances. Use the SDK if you want instances.

Related