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. CallAgent.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 stopsendsSIGTERM: 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
- Add the packages to your image. No extra is needed for Pydantic AI:
pip install glassflow-rius pydantic-ai- 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_NAMEdefaults to it:
export RIUS_API_KEY=ri_...
export RIUS_SERVICE_NAME=support-agent- Call
initandinstrument_allat the top of your entrypoint, then flush and shut down at the end. For a batch job or a one-shot container,flushforces 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- 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 handleSIGTERMyourself, or callshutdown()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 beforeSIGKILL; raise that with--stop-timeoutorstop_grace_periodin Compose if needed. Never callflush()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)-
Scope each conversation with
rius.session(conversation_id)around the run, as the Pydantic AI page shows, so a conversation reads as one session. -
Optional: set
RIUS_MAIN_AGENT_VERSIONto the release you deploy. That setsrius.main_agent.version, the version the Agents page compares between releases. -
Run one request that calls a tool, then open the trace in the console. You should see the
invoke_agentroot,chatgenerations with model, tokens and cost, andexecute_toolspans.
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_agentroot, thechatgenerations and theexecute_toolspans, 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_NAMEorRIUS_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
stoppedping when you callshutdown(). If the process ends on an unhandledSIGTERMor aSIGKILL, nostoppedping is sent and the instance reportsgone, which is the crash signal. The SDK installs no signal handlers, which is why step 4 handlesSIGTERM. - 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=falseand callclient.flush()at the end of every invocation. Without it the heartbeat pings stop and the instance flaps between alive andstaleorgone. - 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.