How do I trace an agent built with LangChain and deployed to a Docker container?
Rius traces a LangChain agent in a Docker container when you call init once at startup, before the chains run, and shut the client down when the container receives SIGTERM. Name the agent with service_name or RIUS_SERVICE_NAME, so it appears under that name in Rius. Chains, tools, retrievers and model calls arrive as a nested trace, with cost computed by Rius.
How it works
- Where init goes. The LangChain integration hooks LangChain’s callback system, so
init()has to run before your chains do. Put it at the top of the container’s entrypoint module, once per process. Anything that runs through the callbacks is traced: LCEL chains, agents and LangGraph nodes. The LangChain integration page lists what each step becomes in the trace. - Configuration comes from the environment. Both SDKs read
RIUS_API_KEYandRIUS_SERVICE_NAME, so you can set them in the container’s environment instead of baking a key into code or the image. - The agent name. The agent is grouped under
RIUS_AGENT_NAME, which defaults to the service name. Pick a stable name per deployable, such assupport-agent, so every container started from the same image lands under one agent. To compare releases on the Agents page, also setRIUS_MAIN_AGENT_VERSION. - Export is in the background. Spans are queued in the process and sent in batches, so tracing never sits on your agent’s request path. What you must handle is how the container ends, because queued spans that have not been sent are lost.
- Heartbeat. A container is a long-lived process, so the default heartbeat suits it. The agent shows its running instances, and a clean
shutdown()sends a finalstoppedping. An unhandledSIGTERMor aSIGKILLsends none, and the instance then reportsgone. The SDK installs no signal handlers of its own.
Set it up
- Add the integration to the image’s dependencies. The extra installs the instrumentation, not LangChain itself, so keep
langchainin your requirements. The integrations overview covers the other frameworks and clients.
pip install "glassflow-rius[langchain]" langchain-
Pass the key and the agent name through the container’s environment: set
RIUS_API_KEYto yourri_key andRIUS_SERVICE_NAMEto the agent name. Keep the key in your orchestrator’s secret store, not in the image. -
Call
init()first in the entrypoint, keep the client it returns, and shut it down when the container is told to stop.docker stopsendsSIGTERM, and Python’s default response ends the process without running the exit hook that would drain the queue, so handle it yourself. If your server already handlesSIGTERM, such as uvicorn, callclient.shutdown()in its shutdown hook instead, for example a FastAPI lifespan. 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 the final export needs longer.
import signal
import sys
import rius
client = rius.init(service_name="support-agent") # key from RIUS_API_KEY
# build and run your chains exactly as before
def stop(*_):
client.shutdown() # drain queued spans, send the final stopped ping
sys.exit(0)
signal.signal(signal.SIGTERM, stop)-
If the container runs a batch job or a one-shot command rather than a server, call
client.flush()before the job ends. A short process can finish before the first scheduled export fires. Do not callflush()inside request handlers, because it blocks until the export completes. Flush at process boundaries only. -
In TypeScript,
init()attaches integrations asynchronously, so awaitreadybefore the first call. The SDK registers no process-exit hook, so shutting down is required, not optional:
import { init } from '@glassflow-ai/rius'
const client = init({ serviceName: 'support-agent' }) // key from RIUS_API_KEY
await client.ready // resolves with the integrations that attached
// build and run your chains exactly as before
process.on('SIGTERM', async () => {
await client.shutdown() // flush, then stop
process.exit(0)
})- Run one chain that calls a model, then open the trace in the console. You should see the chain as nested spans, with the model-call span carrying model, tokens and cost. The reliability page covers batching, retries and what happens when an export fails.
What you get
- A trace per run that mirrors your LangChain graph: chains, tools, retrievers and model calls as nested spans, with messages and step inputs and outputs as content.
- Tokens and cost on each model call. Cost is a list-price estimate in US dollars, computed by Rius, and you never send it. Each call is counted once even when a client library is instrumented under LangChain, with one exception: text-completion models are still counted twice.
- One agent under the name you chose, with its running instances on the Agents page, and a clean
stoppedstate when your shutdown handler runs. - Spans from the last seconds before the container stops, because you flush or shut down before it exits.
When something else fits
- If the container runs several worker processes, each process that calls
init()gets its own instance, so a gunicorn app shows one instance per worker. - If the container runs on a Lambda-style runtime that freezes the process between invocations, call
client.flush()at the end of every invocation and turn the heartbeat off withRIUS_HEARTBEAT=false. - If you cannot change the entrypoint at all, the reliability page explains what an unclean stop can lose.