feat(telemetry): add flag for enabling traces specifically

[spencer426]

Summary

Introduces a telemetry.traces configuration flag to explicitly decouple detailed attribute tracing from lightweight baseline telemetry. Heavy tracing spans (tool outputs, file reads, model responses) are now strictly opt-in, resolving friction between low-overhead monitoring and deep debugging.

Details

• Heavy tracing spans are now strictly opt-in via telemetry.traces in settings.json or the GEMINI_TELEMETRY_TRACES_ENABLED environment variable.
• Strictly enforces that an undefined flag disables traces (!tracesEnabled), guaranteeing a true opt-in architecture.
• Includes documentation updates in docs/reference/configuration.md.

Related Issues

Fixes #25402

How to Validate

1. Verify traces are disabled by default.
2. Enable traces via GEMINI_TELEMETRY_TRACES_ENABLED=true and confirm detailed input and output payload attributes are correctly appended to the telemetry spans.
3. Run the test suite: npm run test:ci -w @google/gemini-cli-core -- src/telemetry/trace.test.ts

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker

[gemini-cli]

Hi @spencer426, thank you so much for your contribution to Gemini CLI! We really appreciate the time and effort you've put into this.

We're making some updates to our contribution process to improve how we track and review changes. Please take a moment to review our recent discussion post: Improving Our Contribution Process & Introducing New Guidelines.

Key Update: Starting January 26, 2026, the Gemini CLI project will require all pull requests to be associated with an existing issue. Any pull requests not linked to an issue by that date will be automatically closed.

Thank you for your understanding and for being a part of our community!

[github-actions]

🛑 Action Required: Evaluation Approval

Steering changes have been detected in this PR. To prevent regressions, a maintainer must approve the evaluation run before this PR can be merged.

Maintainers:

1. Go to the Workflow Run Summary.
2. Click the yellow 'Review deployments' button.
3. Select the 'eval-gate' environment and click 'Approve'.

Once approved, the evaluation results will be posted here automatically.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request primarily enhances telemetry control by introducing a dedicated telemetry.traces configuration. This new setting allows users to explicitly manage the capture of detailed tracing attributes, such as tool outputs and model responses, ensuring that more verbose data collection is opt-in. This separation helps in balancing low-overhead monitoring with deep debugging needs. Additionally, the PR includes several cleanups and refactorings, such as removing outdated MCP server authentication parsing, simplifying policy chain resolution, and streamlining environment variables used during hook execution.

Highlights

• Telemetry Tracing Control: Introduced a new telemetry.traces configuration option and GEMINI_TELEMETRY_TRACES_ENABLED environment variable to explicitly enable or disable detailed tracing attributes within telemetry data. This decouples heavy tracing (e.g., tool outputs, file reads, model responses) from baseline telemetry, making it opt-in.
• MCP Server Authentication Refactoring: Removed deprecated or unused logic and schema definitions related to parsing authentication configurations within mcp_servers in the agent loader.
• Policy Chain Resolution Simplification: Streamlined the policy chain resolution by removing specific logic that applied SILENT_ACTIONS when ApprovalMode was set to PLAN.
• Hook Environment Variable Cleanup: Removed several GEMINI_ prefixed environment variables (GEMINI_PLANS_DIR, GEMINI_CWD, GEMINI_SESSION_ID) from the hook execution context and their corresponding command expansion logic.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[github-actions]

Size Change: +1.58 kB (0%)

Total Size: 33.7 MB

Filename	Size	Change
./bundle/chunk-4KZPUKLD.js	0 B	-674 kB (removed)	🏆
./bundle/chunk-6XKGCZRJ.js	0 B	-2.72 MB (removed)	🏆
./bundle/chunk-CSFLEDXW.js	0 B	-49.2 kB (removed)	🏆
./bundle/chunk-HJIAMJCZ.js	0 B	-3.8 kB (removed)	🏆
./bundle/chunk-KPMH5OHL.js	0 B	-14.5 MB (removed)	🏆
./bundle/chunk-OMLPW664.js	0 B	-3.43 kB (removed)	🏆
./bundle/core-KCJ6UZXS.js	0 B	-46.7 kB (removed)	🏆
./bundle/devtoolsService-UNSTBT2H.js	0 B	-28.4 kB (removed)	🏆
./bundle/gemini-JKLW4OY5.js	0 B	-576 kB (removed)	🏆
./bundle/interactiveCli-DXPKS52Q.js	0 B	-1.3 MB (removed)	🏆
./bundle/liteRtServerManager-IULQPK32.js	0 B	-2.08 kB (removed)	🏆
./bundle/oauth2-provider-L2LXI7YB.js	0 B	-9.16 kB (removed)	🏆
./bundle/chunk-3FLH4CBU.js	49.2 kB	+49.2 kB (new file)	🆕
./bundle/chunk-7JFGWKQM.js	674 kB	+674 kB (new file)	🆕
./bundle/chunk-CIK7LDPW.js	3.43 kB	+3.43 kB (new file)	🆕
./bundle/chunk-HVI2INW5.js	2.72 MB	+2.72 MB (new file)	🆕
./bundle/chunk-N3LYT5LI.js	3.8 kB	+3.8 kB (new file)	🆕
./bundle/chunk-UOAFZT7B.js	14.5 MB	+14.5 MB (new file)	🆕
./bundle/core-BOLPTZF4.js	46.7 kB	+46.7 kB (new file)	🆕
./bundle/devtoolsService-SW4OOECG.js	28.4 kB	+28.4 kB (new file)	🆕
./bundle/gemini-E4KP5OYL.js	576 kB	+576 kB (new file)	🆕
./bundle/interactiveCli-I6KGO37O.js	1.3 MB	+1.3 MB (new file)	🆕
./bundle/liteRtServerManager-WLSBQL5S.js	2.08 kB	+2.08 kB (new file)	🆕
./bundle/oauth2-provider-6DHRQIZB.js	9.16 kB	+9.16 kB (new file)	🆕

ℹ️ View Unchanged

Filename	Size	Change
./bundle/bundled/third_party/index.js	8 MB	0 B
./bundle/chunk-34MYV7JD.js	2.45 kB	0 B
./bundle/chunk-5AUYMPVF.js	858 B	0 B
./bundle/chunk-5PS3AYFU.js	1.18 kB	0 B
./bundle/chunk-664ZODQF.js	124 kB	0 B
./bundle/chunk-DAHVX5MI.js	206 kB	0 B
./bundle/chunk-IUUIT4SU.js	56.5 kB	0 B
./bundle/chunk-RJTRUG2J.js	39.8 kB	0 B
./bundle/chunk-YIPDXML5.js	1.97 MB	0 B
./bundle/cleanup-VY5PDR3D.js	0 B	-932 B (removed)	🏆
./bundle/devtools-36NN55EP.js	696 kB	0 B
./bundle/dist-T73EYRDX.js	356 B	0 B
./bundle/events-XB7DADIJ.js	418 B	0 B
./bundle/examples/hooks/scripts/on-start.js	188 B	0 B
./bundle/examples/mcp-server/example.js	1.43 kB	0 B
./bundle/gemini.js	4.97 kB	0 B
./bundle/getMachineId-bsd-TXG52NKR.js	1.55 kB	0 B
./bundle/getMachineId-darwin-7OE4DDZ6.js	1.55 kB	0 B
./bundle/getMachineId-linux-SHIFKOOX.js	1.34 kB	0 B
./bundle/getMachineId-unsupported-5U5DOEYY.js	1.06 kB	0 B
./bundle/getMachineId-win-6KLLGOI4.js	1.72 kB	0 B
./bundle/memoryDiscovery-NXEEFR74.js	980 B	0 B
./bundle/multipart-parser-KPBZEGQU.js	11.7 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/client/main.js	222 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/_client-assets.js	229 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/index.js	13.4 kB	0 B
./bundle/node_modules/@google/gemini-cli-devtools/dist/src/types.js	132 B	0 B
./bundle/sandbox-macos-permissive-open.sb	890 B	0 B
./bundle/sandbox-macos-permissive-proxied.sb	1.31 kB	0 B
./bundle/sandbox-macos-restrictive-open.sb	3.36 kB	0 B
./bundle/sandbox-macos-restrictive-proxied.sb	3.56 kB	0 B
./bundle/sandbox-macos-strict-open.sb	4.82 kB	0 B
./bundle/sandbox-macos-strict-proxied.sb	5.02 kB	0 B
./bundle/src-QVCVGIUX.js	47 kB	0 B
./bundle/start-N46YKBAM.js	0 B	-622 B (removed)	🏆
./bundle/tree-sitter-7U6MW5PS.js	274 kB	0 B
./bundle/tree-sitter-bash-34ZGLXVX.js	1.84 MB	0 B
./bundle/cleanup-L3AXAKO4.js	932 B	+932 B (new file)	🆕
./bundle/start-C3CEOC2M.js	622 B	+622 B (new file)	🆕

_{compressed-size-action}

[gemini-code-assist]

Code Review

This pull request introduces a new telemetry configuration option, traces, which allows users to enable or disable the capture of detailed traces containing large attributes like tool outputs and file reads. The changes span across documentation, configuration schemas, the core telemetry logic, and various components that report telemetry. Additionally, the PR includes some cleanup, such as removing deprecated MCP authentication schemas from the agent loader and simplifying environment variable handling in the hook runner. I have no feedback to provide.

[gemini-code-assist]

Code Review

This pull request introduces a new traces telemetry setting to capture detailed traces with large attributes, updating the configuration schema, documentation, and trace execution logic across the monorepo. However, the PR also includes several significant and seemingly unrelated removals, such as the auth property for MCP servers in agentLoader.ts, specific environment variables for hooks, and silent action policies for plan mode. Feedback correctly identifies a major regression regarding the removal of MCP authentication and suggests improving the tracesEnabled check to better handle undefined values and ensure strict opt-in behavior.

[jerop]

update telemetry.md as well 🙏🏾

[spencer426]

Hi @jerop, thank you for the sharp review! I've addressed all the feedback in the latest commit:

1. Privacy Gate Regression: You were completely right. I've updated types.ts to strictly require config.getTelemetryTracesEnabled() && config.getTelemetryLogPromptsEnabled() so we never accidentally leak prompts when traces are enabled but logPrompts is disabled.
2. Missing Test Assertions: I reverted my deletion of the assertions in loggers.test.ts. I updated the mock config to return true for getTelemetryTracesEnabled to explicitly prove that the payloads are logged when opted-in.
3. New Test Coverage: I added new, dedicated test cases for logApiResponse and logApiError that explicitly mock tracesEnabled to false and assert that the prompt payloads are safely dropped from the event logs.
4. Copy-paste error: I fixed the // Enabled comment on the disabled trace flag.

Everything has been verified with a full preflight run. Let me know if there's anything else!

[jerop]

have you verified this in GCP trace explorer?

[wissamblue69-dotcom]

Summary

Introduces a telemetry.traces configuration flag to explicitly decouple detailed attribute tracing from lightweight baseline telemetry. Heavy tracing spans (tool outputs, file reads, model responses) are now strictly opt-in, resolving friction between low-overhead monitoring and deep debugging.

Details

• Heavy tracing spans are now strictly opt-in via telemetry.traces in settings.json or the GEMINI_TELEMETRY_TRACES_ENABLED environment variable.
• Strictly enforces that an undefined flag disables traces (!tracesEnabled), guaranteeing a true opt-in architecture.
• Includes documentation updates in docs/reference/configuration.md.

Related Issues

Fixes #25402

How to Validate

1. Verify traces are disabled by default.
2. Enable traces via GEMINI_TELEMETRY_TRACES_ENABLED=true and confirm detailed input and output payload attributes are correctly appended to the telemetry spans.
3. Run the test suite: npm run test:ci -w @google/gemini-cli-core -- src/telemetry/trace.test.ts

Pre-Merge Checklist

• Updated relevant documentation and README (if needed)
• Added/updated tests (if needed)
• Noted breaking changes (if any)
• Validated on required platforms/methods:
  • MacOS
    • npm run
    • npx
    • Docker
    • Podman
    • Seatbelt
  • Windows
    • npm run
    • npx
    • Docker
  • Linux
    • npm run
    • npx
    • Docker