How do I trace an agent built with CrewAI and deployed to a Docker container?
Rius traces a CrewAI agent in a Docker container when you call init once at the container’s entrypoint, before you build the crew. Set the agent’s name with the service name, and shut the client down when the container stops. Model calls arrive as generations with tokens and cost, and your observe wrappers give the run and its tools their shape.
How it works
CrewAI 1.x drives the OpenAI client natively, so the openai integration captures its model calls. If LiteLLM is installed in the image, CrewAI uses it instead and the litellm integration captures the calls. With a global init(), every installed integration turns on automatically, so there is nothing else to enable. The CrewAI integration page covers what lands in the trace.
Three things matter in a container:
- Where init runs. Call it at module level in the file the container starts, before any crew or agent is created. It reads
RIUS_API_KEYandRIUS_SERVICE_NAMEfrom the container’s environment, so the key stays out of the image. - The agent name. The service name is the agent’s name in Rius.
RIUS_AGENT_NAMEoverrides the name the agent is grouped under, and it defaults to the service name. Agents are found from traces and heartbeats, so there is nothing to register. - How spans leave. Spans are queued in memory and exported in batches from a background thread. Python flushes pending spans at a normal interpreter exit, but
docker stopsendsSIGTERM, and Python’s default response ends the process without running that exit hook, so the last batch is lost unless you handle the signal.
Set it up
-
Install the SDK with the
openaiextra and CrewAI in your image. The extra adds the instrumentation, not the library.pip install "glassflow-rius[openai]" crewai -
Set environment variables on the container:
RIUS_API_KEYwith yourri_key andRIUS_SERVICE_NAMEwith the agent’s name. Also setCREWAI_TRACING_ENABLED=false. CrewAI asks about its own tracing on first run, and in a container no terminal is attached to answer. SetRIUS_MAIN_AGENT_VERSIONto your image tag if you want the Agents page to compare versions. -
Call
init()at the top of the entrypoint, wrap the run as anAGENTspan, and wrap each tool body as aTOOLspan. Put@tooloutermost andobserveon the function body.import signal import sys import rius from crewai import Agent, Crew, Task from crewai.tools import tool from rius import SpanKind client = rius.init() # reads RIUS_API_KEY and RIUS_SERVICE_NAME signal.signal(signal.SIGTERM, lambda *_: sys.exit(0)) # runs the finally block @tool("account_status") @rius.observe(kind=SpanKind.TOOL) def account_status(email: str) -> str: """Fetch a customer's account standing by email.""" return lookup(email) support_agent = Agent( role="Support specialist", goal="Answer support tickets accurately and concisely.", backstory="You resolve product and account questions.", tools=[account_status], llm="gpt-5-mini", ) @rius.observe(name="handle-ticket", kind=SpanKind.AGENT) def handle_ticket(ticket: str) -> str: task = Task( description=f"Resolve this support ticket: {ticket}", expected_output="A short, direct answer.", agent=support_agent, ) return Crew(agents=[support_agent], tasks=[task]).kickoff().raw if __name__ == "__main__": try: print(handle_ticket("My invoice shows the wrong plan.")) finally: client.flush(timeout_millis=30_000) # force an export client.shutdown() # drain and stop cleanly -
Shut down according to how the container runs. A one-shot job flushes and shuts down in the
finallyblock, as above, and theSIGTERMhandler turnsdocker stopinto a normal exit so that block runs. A long-running service exports batches continuously and needsclient.shutdown()when it stops: call it from aSIGTERMhandler, or from 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. The reliability page lists the batching settings. -
Run one ticket that calls a tool and open the trace in the console. You should see the root
AGENTspan namedhandle-ticket, theLLMgenerations and yourTOOLspan.
What you get
- One trace per run, with the root
AGENTspan, a generation for each model call with model, tokens, cost and time to first token, and aTOOLspan for each tool. - Cost as a list-price estimate in US dollars, computed by Rius. You never send a cost value.
- The agent under your service name on the Agents page. With the heartbeat on (the default) and an API key set, each running container shows as an instance.
- A clean stop that is distinguishable from a crash.
shutdown()sends a finalstoppedping. An unhandledSIGTERMor aSIGKILLsends none, and the instance reportsgone.
Crews and tasks produce no spans of their own, and generation spans carry the generic name ChatCompletion. If you need to see which task a generation belongs to, wrap per-task entrypoints with observe.
When something else fits
- If your CrewAI project is not Python, the CrewAI integration does not apply, since it covers only the Python framework. See Integrations for what each language supports.
- If the container runs in a Lambda-style runtime that freezes the process between invocations, flush at the end of every invocation and turn the heartbeat off, as the reliability page describes.