Trace Gemini CLI sessions, agent steps, model calls, and tool invocations in Phoenix for full observability.
Trace your Gemini CLI sessions in Phoenix with the coding-harness-tracing toolkit — every turn shows up as a trace with the model call, each tool it runs, and token usage, grouped into its session. No application code changes required: the toolkit hooks into Gemini CLI’s lifecycle events and streams OpenInference spans to Phoenix.
Launch Phoenix#
The fastest way to get started with Phoenix is by signing up for a free Phoenix Cloud account. If you prefer, you can also run Phoenix in a notebook, self-host it, or use it directly from your terminal.
Go to the settings page in your Phoenix instance to find your endpoint and API key. A self-hosted Phoenix defaults to http://localhost:6006; the API key is only required when auth is enabled.
Install#
The curl installer is the simplest — it runs a short wizard that saves your Phoenix credentials for you. Use a local clone if you’d rather run the installer from a checkout of the source.
Curl installer (recommended)#
macOS / Linux:
Windows (PowerShell):
Local clone#
The installer prompts for your backend — select Phoenix, then enter your endpoint and optional API key — and your project name, writes them to ~/.arize/harness/config.json, and registers the hooks in ~/.gemini/settings.json.
Configuration#
Credentials live in ~/.arize/harness/config.json. Environment variables override values in config.json and can be set in your shell profile.
On the Phoenix backend, set the project name with PHOENIX_PROJECT (or PHOENIX_PROJECT_NAME); ARIZE_PROJECT_NAME is Arize-only and ignored here. ARIZE_TRACE_ENABLED is a backend-agnostic harness setting and keeps the ARIZE_ prefix regardless of destination.
Redaction controls#
Each ARIZE_LOG_* flag accepts "true" or "false" and defaults to "true". Set to "false" to opt out per category:
| Flag | Redacts |
|---|---|
ARIZE_LOG_PROMPTS | User prompt and assistant response text |
ARIZE_LOG_TOOL_DETAILS | Tool names and arguments |
ARIZE_LOG_TOOL_CONTENT | Tool call output content |
Observe#
Once tracing is enabled, Gemini CLI activity is streamed to Phoenix. You’ll see:
- Turn traces — each agent turn as a
Turn(CHAIN) span, with the prompt as input and the final response as output - LLM spans — one
LLM: <model>span per model call, with model name and token counts - Tool spans — one per tool call (
read_file,run_shell_command, and others), with input, output, and duration - Session grouping — all turns from the same session grouped by
session_id
Reference#
For the full list of environment variables, default file paths, and troubleshooting steps, see the Gemini tracing README.