Set up Lens
Lens lets you inspect agent traces, investigate failures, and save useful runs as datasets. You can open it inside your LiteLLM dashboard or use it as a separate application.
In both cases, Lens runs as its own service and stores its data in ClickHouse. Your agent can keep its existing model provider.
Choose your starting point
| Your starting point | Follow this guide |
|---|---|
| You use LiteLLM and want Lens in its sidebar | Add Lens to LiteLLM |
| You already run Lens and want to connect it to a gateway | Connect your existing Lens deployment |
| You want to run Lens without a gateway | Start standalone Lens |
| Your team has already set up Lens | Send your first trace |
For a persistent standalone deployment, use Docker Compose on a server or Kubernetes. The local quickstart builds from source. See Releases and images for the release status.
Use Lens inside LiteLLM
A gateway administrator configures the connection once. Users then open Lens in the LiteLLM sidebar and use their existing LiteLLM session. They do not enter the standalone Lens admin token. LiteLLM supplies their identity and access scope to Lens.
If Lens is not configured, the dashboard shows its setup page. Connecting the service does not instrument your agents. After the connection is ready, send a trace from an agent.
Follow Add Lens to LiteLLM. If Lens already runs, use its current address, storage, and credentials. You do not need to install a second copy or move its data.
Use Lens on its own
Start Lens and ClickHouse, then sign in at the Lens URL with its admin token. A LiteLLM gateway and PostgreSQL are not required. You can record and inspect traces before you configure an analysis model.
Follow the standalone quickstart. Add an analysis model when you want to run investigations.
Check your first result
Open Lens, generate a tracing key, and follow Send your first trace. Open the resulting run and inspect its content. A health check confirms that the service is ready; a stored trace confirms that your exporter can send data and you can read it.
For help from a coding agent, copy the Set it up for me prompt in the Lens setup guide. It covers standalone setup, an existing gateway, and connecting an agent.
