What does the service.name attribute mean in Rius?

In Rius, service.name is the resource attribute that names your service, and every trace view and filter groups by it. You set it once per process, and Rius also uses it as the agent name when nothing more specific is set. Always set it, because a missing value falls back to the placeholder unknown_service.

How it works

• What it holds. The name of the service that produced the spans, for example my-agent. It is an OpenTelemetry resource attribute, so you set it once for the process instead of on each span.
• What Rius does with it. Trace views and filters group by service.name. It is the first thing to check when you cannot find traces: traces from different services sit under different names.
• Agent name fallback. 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 gen_ai.agent.name, and finally service.name. If you set none of the agent keys, your service name is the agent name on the Agents page.
• SDK default for the agent name. In the Rius SDKs, the agent name setting RIUS_AGENT_NAME defaults to the service name.
• Default value. When you set nothing, the SDKs send unknown_service. Rius treats that as a placeholder, so it does not make a useful agent name.
• Related resource attributes. service.version records the build or release the process runs. service.instance.id identifies the process that produced the span, and the SDKs send the same id in their heartbeats, which joins traces to the Agents view. Together they separate versions and instances of one service without changing its name.

The full list of attributes Rius reads is on the span attribute reference.

Set it up

1. Pick a stable, readable name for each service or agent, such as support-agent or billing-worker. Keep it the same across deployments so traces from every release land in one group. Put the release in service.version, not in the name.
2. If you use the Rius SDK, pass the name to init. The Python SDK takes service_name, and the TypeScript SDK takes serviceName.

import rius
 
client = rius.init(
    api_key="ri_...",
    service_name="my-agent",
)

3. Or set it from the environment, which the SDKs read as RIUS_SERVICE_NAME:

export RIUS_SERVICE_NAME=my-agent

4. If you send spans from a vanilla OpenTelemetry SDK, a collector or another language, set service.name as a resource attribute in your own exporter setup. The attribute reference lists it with the other resource attributes, and Trace LLM calls with OpenTelemetry walks through the senders.
5. If you want the Agents page to show a different name from the service, set RIUS_AGENT_NAME in the SDK. Without the SDK, set gen_ai.main_agent.name as a resource attribute. Either one takes priority over service.name for the agent name.
6. Send a trace and check that the name you chose appears in the trace list filter.

What you get

• Trace views and filters that group by the service name you chose.
• An agent entry on the Agents page named after your service when you set no other agent name.
• A clear way to separate services: one service.name per service, with service.version and service.instance.id telling releases and processes apart inside it.
• Spans from SDK and non-SDK senders that group together, as long as they use the same service.name.

When something else fits

• If one service runs several differently named agents, set the agent name separately with RIUS_AGENT_NAME or gen_ai.main_agent.name, so the Agents page shows each agent and not one service name.
• If you want to group traces by conversation or by end user, use session.id or user.id. They are separate attributes, and service.name does not replace them.

Related