Skip to Content

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_KEY and RIUS_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 as support-agent, so every container started from the same image lands under one agent. To compare releases on the Agents page, also set RIUS_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 final stopped ping. An unhandled SIGTERM or a SIGKILL sends none, and the instance then reports gone. The SDK installs no signal handlers of its own.

Set it up

  1. Add the integration to the image’s dependencies. The extra installs the instrumentation, not LangChain itself, so keep langchain in your requirements. The integrations overview covers the other frameworks and clients.
pip install "glassflow-rius[langchain]" langchain
  1. Pass the key and the agent name through the container’s environment: set RIUS_API_KEY to your ri_ key and RIUS_SERVICE_NAME to the agent name. Keep the key in your orchestrator’s secret store, not in the image.

  2. Call init() first in the entrypoint, keep the client it returns, and shut it down when the container is told to stop. docker stop sends SIGTERM, 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 handles SIGTERM, such as uvicorn, call client.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 before SIGKILL; raise that with --stop-timeout or stop_grace_period in 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)
  1. 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 call flush() inside request handlers, because it blocks until the export completes. Flush at process boundaries only.

  2. In TypeScript, init() attaches integrations asynchronously, so await ready before 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) })
  1. 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 stopped state 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 with RIUS_HEARTBEAT=false.
  • If you cannot change the entrypoint at all, the reliability page explains what an unclean stop can lose.

Still stuck? Get help

Last updated on