Skip to main content
Gemini CLI reports every session over OpenTelemetry. The LangWatch command-line tool connects that report to your workspace, so you can read the cost of each session, the trace of each turn, and the prompts behind both. There are two ways to set it up:
  • langwatch gemini starts Gemini CLI and sets up the connection on the first run. Use it on a machine you work on.
  • langwatch instrument gemini writes the same setup and exits. Use it on a server, or when the telemetry must go to a team project.

​
Before you start

  • Install Gemini CLI.
  • Install the LangWatch command-line tool: npm install -g langwatch
  • Create an account at app.langwatch.ai, or run your own instance with npx @langwatch/server.

​
Run Gemini CLI through the wrapper

The first run asks one question: LangWatch remembers the answer, so later runs do not ask again. Everything else is unchanged: langwatch gemini accepts the same flags and the same subcommands as gemini, and it returns the same exit code.
For the gateway path, ~/.gemini/settings.json must have security.auth.selectedType set to "gemini-api-key". With "gemini-oauth" selected, Gemini CLI uses its cached login and ignores the key, so the calls bypass the gateway; the wrapper prints a warning in that case. The telemetry path works with either.

​
Set up a machine without starting Gemini CLI

langwatch instrument gemini writes a gemini function into your shell start file (~/.zshrc, ~/.bashrc, or ~/.config/fish/config.fish), which applies the LangWatch settings to that tool and to no other command. A plain gemini run in a new terminal then sends its telemetry to LangWatch.
Open a new terminal after the command, or read the start file again, so the function is in place.
The shell function needs zsh, bash or fish. On Windows, start Gemini CLI with langwatch gemini each time instead.

​
Choose where the telemetry goes

Pass one scope flag, and one only: The wrapper accepts the same flags: langwatch gemini --project acme-app pins the project and then starts Gemini CLI. --project and --personal are LangWatch flags; LangWatch removes them from the command line before Gemini CLI reads it.

​
Remove the setup

This deletes every connection the command-line tool wrote, for every tool.

​
What you get in LangWatch

Open your personal page at /me, or open the project you pinned Gemini CLI to.
  • Sessions: one row per Gemini CLI session, with the context it carried and how long it worked.
  • Traces: one trace per turn, with the model, the tokens and the timing of each step, and each tool call with its details.
  • Cost: the amount per session and per turn.
  • Content: the prompt of each turn.
Your agent can read all of this back. See Explore your usage with your own agent.

​
Content and privacy

The setup sets GEMINI_TELEMETRY_LOG_PROMPTS=true, which is what puts the text of your prompts on the wire; without it, Gemini CLI reports the prompt as a length and no text. It also sets GEMINI_TELEMETRY_TRACES_ENABLED=true, which adds the tool call details to the spans. Set GEMINI_TELEMETRY_LOG_PROMPTS=false in your own environment to keep prompt text off. To keep content out of storage organization-wide, use the data privacy policy. Who can open a stored session’s content is covered on Privacy.

​
Troubleshooting

Two cases skip the question. Your organization allows one connection path only, and LangWatch takes that path without asking. Or the run has no terminal attached, for example in CI: it keeps your own plan and sends telemetry only.To set the path on one run, use --tool-mode. It overrides the remembered answer.
Open a new terminal. The gemini function is read from the shell start file when a shell begins, so a terminal that was already open does not have it.Then run langwatch instrument gemini again and read what it prints. It names what it wrote and the destination the telemetry goes to.
GEMINI_TELEMETRY_TARGET accepts local or gcp only. A value of otlp, which older examples show, stops Gemini CLI with a configuration error. The LangWatch setup uses local with GEMINI_TELEMETRY_USE_COLLECTOR=true, which is what forwards to an OTLP endpoint.
Run langwatch instrument gemini --project <id-or-slug> to move it to a team project, or langwatch instrument gemini --personal to move it back to your own.
Check that the key is live and that the header reads Authorization=Bearer <key>. An ingest key can write traces and no other requests, so a key that works for ingestion still fails on other endpoints.On a machine with a login, run langwatch login --device again to refresh the session.
For more failure modes see CLI debug.

​
Manual OpenTelemetry setup

Use this when you cannot install the LangWatch command-line tool. The block below mirrors the variables the setup writes for you:
The header takes an ingest key (ik-lw-...), which can create traces and no other requests. Keep a full project API key (sk-lw-...) out of the configuration of a coding agent: it can read and change your project data, and a coding agent has no use for that. For a self-hosted instance, replace the endpoint host with the address of your instance and keep the /api/otel path. The exporters append the per-signal paths on their own.
Last modified on August 27, 2026