Skip to content

docs(coding-agents): Gemini CLI application session tracing (TH-8285) - #922

Merged
nik13 merged 9 commits into
mainfrom
feat/th-8285-gemini-cli
Nov 6, 2026
Merged

nik13 merged 9 commits into
mainfrom
feat/th-8285-gemini-cli

Conversation

@nik13

@nik13 nik13 commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Summary

  • Add native Gemini CLI session tracing through a local OpenTelemetry Collector, scoped to Gemini CLI 0.64.0 on macOS in non-sandbox interactive and non-interactive modes.
  • Preserve default content/error redaction, local-identity filtering, session mapping and uncompressed OTLP export; explain the content opt-in and native trace limitations.
  • Register the guide in the shared integration catalog and remove obsolete sidebar edits and customer-facing QA instructions.
  • Clear inherited OTLP endpoint overrides in the Gemini launch terminal so telemetry cannot bypass the privacy-filtering collector.
  • Add page contracts for endpoint cleanup and real-collector privacy regression checks.

Validation

  • Published Gemini CLI 0.64.0 and Collector Contrib 0.162.0 confirmed.
  • Documentation, links, browser checks and collector privacy checks run in GitHub Actions; no local tests or builds.

TH-8285

🤖 Generated with Claude Code

nik13 and others added 4 commits October 14, 2026 20:09
Recipe for Gemini CLI's built-in OpenTelemetry export (telemetry.enabled,
traces: true, logPrompts: false, target local, OTLP/HTTP) through a local
otelcol-contrib in front of Future AGI. The collector adds the Future AGI
headers and project_name (Gemini CLI 0.64.0 has no OTLP header setting),
drops logs and metrics (Future AGI ingests traces only), strips the system
prompt, tool schemas, message attributes and process.command_args (N-06
privacy default), maps Gemini CLI's operation names to span kinds, names
tool spans after the tool, copies the session id to session.id, and exports
uncompressed (fi-collector answers gzip with 400).

Includes run_e2e.sh (isolated HOME) and a contract test that runs the
shipped config in a real otelcol-contrib against spans recorded from Gemini
CLI 0.64.0. Tested end to end against a local Future AGI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ctor (TH-8285)

The default config already removed prompts, system instructions, tool
schemas and process.command_args, and a fresh default session confirms 0
spans with gen_ai.system_instructions and 0 '/Users/' hits. But when
OTEL_NODE_RESOURCE_DETECTORS=env (documented as optional) is not set,
Node's process and host detectors also exported process.executable.path,
process.owner and host.name: local paths (under the home directory for
nvm installs), the OS user name and the machine name. The collector now
deletes process.command, process.executable.path/name, process.owner,
host.name and host.id as well, keeping runtime and arch.

The contract test fixture now carries these attributes with a /Users/
path; the test fails on the previous config and passes on this one. The
page's privacy text names them and spells out that the content opt-in
also exports the system prompt (GEMINI.md memory, working directory).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-8285)

Review fixes for docs#922.

- Collector: error stack traces (Gemini CLI install paths, OS user name)
  are deleted always; by default exception messages are deleted and the
  status message of an ERROR span becomes the error class, plus the HTTP
  status for Gemini API errors ("ApiError HTTP 503", "ENOENT", or "error").
  Full error text only with the content opt-in. Collector self-metrics off
  (service.telemetry.metrics.level: none) so port 8888 never collides.
- Tests: fixture gains a real 0.64.0 API-error llm_call (exception event,
  stack trace) and a thrown tool error with a local path; default asserts
  no path/user/stack trace/error body, opt-in keeps messages but no stack
  traces; shipped config checked for metrics level none and no compression.
- Page: tool failures a tool returns (not throws) end OK in 0.64.0;
  traces:false still emits model, tool names, system prompt and tool
  schemas (only tokens are dropped); agent_call carries
  gen_ai.agent.name=gemini-cli, not the subagent name; error text and
  stack traces in Privacy; GEMINI_TELEMETRY_ENABLED=false did not stop the
  export in 0.64.0 (settings file does); Vertex AI instrumentor in "not the
  same as"; curl for the collector config; port-in-use troubleshooting.
- run_e2e.sh: fails if the collector is not listening, checks what the
  collector forwarded (marker, home, user, host) and exits non-zero on a
  leak, gemini stdin from /dev/null, deletes its work dir on success,
  documents GEMINI_OTLP_PORT.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… (TH-8285)

Gemini CLI 0.64.0 interactive mode wraps every turn in a user_prompt root
span and the tool-result follow-up in a system_prompt child span. The
collector now labels both CHAIN (same as schedule_tool_calls and the
hook-to-otlp turn span). The contract test fixture gains a real
user_prompt/system_prompt pair from an interactive session.

The page now describes interactive mode (one trace per prompt, queued
prompts nest under the running turn, slash commands give an empty
user_prompt trace) and -p mode (no turn span) separately. Gemini CLI
records no content on the turn spans, also with logPrompts true.

run_e2e.sh fails when another process owns the port and when the
collector forwarded no spans, instead of passing on an empty capture.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@nik13
nik13 marked this pull request as ready for review October 21, 2026 22:18
Base automatically changed from feat/th-8229-cursor-hook-to-otlp to main October 29, 2026 05:37
nik13 and others added 5 commits November 5, 2026 16:27
Use the shared integration catalog instead of restoring the obsolete literal coding-agent sidebar.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Replace public QA notes with a version-scoped non-sandbox setup, register the page in the shared catalog, and keep the shipped collector privacy filters intact. Add page contracts and cloud-only collector regression checks for default and opt-in exports.

Co-Authored-By: Claude Code <noreply@anthropic.com>
The PR build completed, but Playwright 1.56.1 cannot install Chromium on the ubuntu-latest 26.04 image. Keep all browser checks enabled on Ubuntu 24.04.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Integrate the current docs main branch and retain its supported Ubuntu browser runner and explanatory comment.

Co-Authored-By: Claude Code <noreply@anthropic.com>
Gemini CLI resolves its telemetry endpoint from environment variables before the settings file. Clear both endpoint overrides in the launch terminal so inherited configuration cannot bypass the privacy-filtering collector, and preserve this prerequisite in the page contract.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@nik13
nik13 merged commit 1e70b34 into main Nov 6, 2026
9 checks passed
@nik13
nik13 deleted the feat/th-8285-gemini-cli branch November 6, 2026 07:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant