Skip to Content

How do I trace an agent built with Pydantic AI and deployed to a Docker container?

Rius traces a Pydantic AI agent in a Docker container with two lines at startup: call rius.init() once, then Agent.instrument_all(True). Pydantic AI emits its own spans for runs, model requests and tool calls, and Rius adds tokens and cost. Flush spans before a short-lived container exits, and call shutdown() on SIGTERM in a long-running one so the last spans leave and the exit shows as clean. The agent is named from your service name, and the framework names the run’s root span after your agent.

How it works

Pydantic AI is OpenTelemetry-native, so no wrappers and no extra are needed. rius.init() installs the global tracer provider, and Agent.instrument_all(True) tells the framework to send its spans through it. Each agent run becomes a root span named invoke_agent followed by your agent’s name. Each model request becomes a generation named chat followed by the model, with tokens and cost. Each tool call becomes an execute_tool span.

In a container, the points that matter are where init runs, how spans leave the process, and which names you set:

  • Where to call init. Call it once at process start, at module level in your entrypoint, before you create agents or handle any request. Call Agent.instrument_all(True) right after it.
  • How spans leave. Spans are queued in memory and exported in batches from a background thread. In Python the exit hook drains the queue on a normal exit, but not when docker stop sends SIGTERM: Python’s default response ends the process without running it.
  • What names you set. The service name is the agent’s identity in Rius. See Pydantic AI for what lands in the trace.

Set it up

  1. Add the packages to your image. No extra is needed for Pydantic AI:
pip install glassflow-rius pydantic-ai
  1. Put the settings in the container’s environment, so the key is not baked into your code. The service name is what the agent shows up as, and RIUS_AGENT_NAME defaults to it:
export RIUS_API_KEY=ri_... export RIUS_SERVICE_NAME=support-agent
  1. Call init and instrument_all at the top of your entrypoint, then flush and shut down at the end. For a batch job or a one-shot container, flush forces the last export before the process ends. In Python you can also rely on the exit hook, but an explicit flush is safer for a short run:
import rius from pydantic_ai import Agent client = rius.init() Agent.instrument_all(True) support_agent = Agent( "openai:gpt-5-mini", instructions="Answer support questions.", ) if __name__ == "__main__": result = support_agent.run_sync("Where is my order?") print(result.output) client.flush(timeout_millis=30_000) # force an export client.shutdown() # drain, stop the thread, send the final stopped ping
  1. For a long-running server container, you do not need to flush on every request. Python batches continuously, so call client.shutdown() when the container stops. The SDK installs no signal handlers, so handle SIGTERM yourself, or call shutdown() in your server’s shutdown hook if it already handles the signal, such as a FastAPI lifespan under uvicorn. Start the app in exec form (CMD ["python", "app.py"]) so it is PID 1 and receives the signal. Docker waits 10 seconds before SIGKILL; raise that with --stop-timeout or stop_grace_period in Compose if needed. Never call flush() inside a request handler, because it blocks until the export completes.
import signal import sys def on_sigterm(signum, frame): client.shutdown() # drain queued spans, send the stopped heartbeat sys.exit(0) signal.signal(signal.SIGTERM, on_sigterm)
  1. Scope each conversation with rius.session(conversation_id) around the run, as the Pydantic AI page shows, so a conversation reads as one session.

  2. Optional: set RIUS_MAIN_AGENT_VERSION to the release you deploy. That sets rius.main_agent.version, the version the Agents page compares between releases.

  3. Run one request that calls a tool, then open the trace in the console. You should see the invoke_agent root, chat generations with model, tokens and cost, and execute_tool spans.

The Reliability page covers batching, retries and shutdown in full.

What you get

  • A trace per agent run with the same structure on every container: the invoke_agent root, the chat generations and the execute_tool spans, named after your agents, models and tools.
  • Tokens, time to first token and cost on each model request. Rius computes cost on the server, so you never send it.
  • An agent grouped under the name you set with RIUS_SERVICE_NAME or RIUS_AGENT_NAME.
  • With the heartbeat on (the default, and it needs credentials), the agent and its instances appear on the Agents page as soon as init() runs. Each process has its own instance ID.
  • A clean stopped ping when you call shutdown(). If the process ends on an unhandled SIGTERM or a SIGKILL, no stopped ping is sent and the instance reports gone, which is the crash signal. The SDK installs no signal handlers, which is why step 4 handles SIGTERM.
  • Content capture for prompts, completions and tool arguments is set on the framework side through Pydantic AI’s InstrumentationSettings, on top of the SDK’s own privacy controls.

When something else fits

  • If your container runs a Lambda-style runtime that freezes the process between invocations, set RIUS_HEARTBEAT=false and call client.flush() at the end of every invocation. Without it the heartbeat pings stop and the instance flaps between alive and stale or gone.
  • If you do not want the Rius SDK in the image, you can send Pydantic AI’s OpenTelemetry spans with any OpenTelemetry setup pointed at the Rius ingest endpoint. You then lose the SDK’s session helpers, heartbeat and privacy controls.
  • For other frameworks and client libraries, see Integrations.

Still stuck? Get help

Last updated on