Skip to Content
Rius

How do I install the Rius SDK for Python?

Rius installs for Python with pip install glassflow-rius, and you import it as rius. It requires Python 3.10 or newer. Call rius.init() once with your API key and a service name, and every LLM library you have instrumented starts sending traces. The full option list is on the installation page.

How it works

The package on PyPI is glassflow-rius, and the module you import is rius. The SDK is MIT licensed.

  • Extras install instrumentation, not libraries. An extra such as glassflow-rius[anthropic] brings in the instrumentation for that library and expects the library itself to already be in your environment. Rius does not depend on provider SDKs, so it never pins or upgrades the versions your code runs against.
  • Available extras: openai, anthropic, langchain, llama-index, litellm and instruments. The instruments extra installs the instrumentation for all of them.
  • MCP needs no extra. It is built into the SDK and turns itself on whenever mcp is importable.
  • A missing library switches that integration off. If you install an extra without its library, init() logs a DependencyConflict from OpenTelemetry and that integration stays off.
  • Automatic by default. With a global init(), every installed integration is turned on. Pass instruments=["openai"] to restrict them, or instruments=[] to turn them all off. See Integrations for each library.
  • Order of precedence. Every init() argument is optional and can come from an environment variable. Explicit arguments win over environment variables, which win over defaults.

Set it up

  1. Install the package.
pip install glassflow-rius
  1. Add the extras for the libraries you call. Use one extra, or all of them.
pip install "glassflow-rius[openai]"
pip install "glassflow-rius[instruments]"

  1. Create an API key in the Rius console. Keys start with ri_. Older keys start with gf_ and keep working.

  2. Call init() once, as early as possible in your process.

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

  1. Set service_name explicitly. It becomes the service.name on every span and is how you find your agent in trace filters, analytics and cost breakdowns. It defaults to unknown_service. Keep it constant across replicas and deploys, because each process start becomes a new instance under the same name.

  2. Move settings to the environment if you prefer. Only the RIUS_* names are read.

export RIUS_API_KEY=ri_...
export RIUS_SERVICE_NAME=my-agent

The options worth knowing:

  • endpoint (RIUS_ENDPOINT): defaults to https://ingest.eu.console.rius-glassflow.com. Traces post to the endpoint plus /v1/traces.
  • service_version (RIUS_SERVICE_VERSION): your release or image tag, stamped as service.version.
  • main_agent_version (RIUS_MAIN_AGENT_VERSION): the version of the agent definition (prompt, tools, policy), which the Agents page compares.
  • agent_name (RIUS_AGENT_NAME): groups instances in the Agents view. It defaults to the service name. Set it separately only when several services form one logical agent.
  • sample_rate (RIUS_SAMPLE_RATE): head sampling of root traces, default 1.0.
  • capture_content (RIUS_CAPTURE_CONTENT): set to false to strip prompt and response content at export while metadata still flows. A mask callable redacts content instead.
  • disabled (RIUS_DISABLED): a kill switch that drops spans in-process.
  • heartbeat (RIUS_HEARTBEAT): on by default, so the Agents page knows the process is alive. It needs an API key or an Authorization header.

Boolean variables accept 1, true, yes, on, 0, false, no and off. An unrecognized value logs a warning and falls back to the default.

Calling a global init() twice logs a warning and returns the existing client. To reconfigure, call client.shutdown() first. If you need a separate pipeline next to an existing one, use rius.init(set_global=False, service_name="side-pipeline").

What you get

  • Spans for model calls, tool calls and agent steps from the libraries you installed extras for, with no manual span code.
  • Spans that carry your service name, version and agent identity, plus a unique service.instance.id for each process start, so a trace joins to the process that ran it.
  • Room for long tool-calling runs. init() raises OpenTelemetry’s per-span attribute limit from 128 to 4096, so spans in long agent loops do not silently lose data. A limit you set yourself in OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT or OTEL_ATTRIBUTE_COUNT_LIMIT wins.
  • A live view of your agent’s instances on the Agents page, driven by the heartbeat.
  • Cost computed by Rius from the model and token counts on the spans. You never send a cost value.

When something else fits

  • If your code runs on Node, use the TypeScript package @glassflow-ai/rius, which needs Node 18 or newer, instead of the Python one.
  • If you already export OpenTelemetry traces from an OpenTelemetry SDK or collector, you can send them to Rius over OTLP HTTP without installing the Rius SDK.

Still stuck? Get help

Last updated on
Quickstart