Add OTLP headers for telemetry

[brandonin]

TLDR

Reopened version of https://github.com/google-gemini/gemini-cli/pull/10391

In most cases we will need to add authentication headers to send to our Otel Collector. This pull request adds support for custom OTLP headers in telemetry configuration for the Gemini CLI, allowing users to specify authentication and other headers for telemetry requests via settings files, environment variables, and CLI arguments.

Dive Deeper

It introduces a parsing and merging strategy for these headers, updates documentation, and ensures correct propagation of headers to both HTTP and gRPC exporters.

Telemetry configuration and parsing enhancements:

• Added support for specifying custom OTLP headers (otlpHeaders) in configuration files, environment variables (GEMINI_TELEMETRY_OTLP_HEADERS), and CLI arguments (--telemetry-otlp-header). Headers can be provided in JSON or key=value formats, and are merged with correct precedence (CLI > env > settings).
• Implemented the parseOtlpHeaders function to handle various input formats, and updated resolveTelemetrySettings to merge headers from all sources.

Documentation updates:

• Updated docs/get-started/configuration.md to document the new otlpHeaders option, environment variable, and CLI flag, including usage examples for authentication scenarios.

Telemetry SDK integration:

• Modified telemetry SDK initialization to pass custom headers to HTTP exporters and as gRPC metadata, ensuring correct transmission of authentication information.

This update makes it much easier to securely configure telemetry authentication for remote environments.

Reviewer Test Plan

Testing Matrix

	🍏	🪟	🐧
npm run	❓	❓	❓
npx	❓	❓	❓
Docker	❓	❓	❓
Podman	❓	-	-
Seatbelt	❓	-	-

Linked issues / bugs

[gemini-code-assist[bot]]

Summary of Changes

Hello @brandonin, I'm Gemini Code Assist[^1]! 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 significantly enhances the Gemini CLI's telemetry capabilities by introducing support for custom OTLP headers. This allows users to securely transmit telemetry data to collectors that require authentication, such as those protected by API keys or bearer tokens. The changes provide flexible configuration options through settings, environment variables, and CLI arguments, along with robust parsing and merging logic to handle various input formats and ensure proper precedence. The custom headers are seamlessly integrated into both HTTP and gRPC telemetry exporters, improving the overall security and configurability of telemetry within the CLI.

Highlights

• Custom OTLP Headers: Introduced support for specifying custom headers for OpenTelemetry Protocol (OTLP) telemetry requests, enabling secure communication with collectors.
• Flexible Configuration: Users can now configure OTLP headers via settings.json files, the GEMINI_TELEMETRY_OTLP_HEADERS environment variable, and the --telemetry-otlp-header CLI argument.
• Intelligent Merging Strategy: Implemented robust parsing and merging logic for OTLP headers, ensuring that CLI arguments take precedence over environment variables, which in turn override settings.
• Authentication Support: This feature facilitates secure telemetry by allowing the inclusion of authentication details like API keys or bearer tokens in telemetry requests.
• Exporter Integration: Custom headers are correctly propagated to both HTTP and gRPC OTLP exporters, with gRPC headers being appropriately converted to Metadata.
• Comprehensive Documentation: The docs/get-started/configuration.md file has been updated to detail the new header options and provide clear usage examples.

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 :thumbsup: and :thumbsdown: 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.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

[^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.

[jerop]

@brandonin please fix the lint issue so we can get this in - https://github.com/google-gemini/gemini-cli/actions/runs/18785825757/job/53782999467

[jerop]

@brandonin this is the command you need to run npm run lint:fix - tested in temporary PR #12374

also please address this feedback in the test PR: https://github.com/google-gemini/gemini-cli/pull/12374#discussion_r2481741577

[brandonin]

@jerop addressed all of the comments.

[cornmander]

We have a centralized credential handling mechanism in the codebase. Can you use that instead of introducing credential handling from env vars, config variables, and args?

[brandonin]

We have a centralized credential handling mechanism in the codebase. Can you use that instead of introducing credential handling from env vars, config variables, and args?

@cornmander If we used a centralized credential handling mechanism, does that allow us to send OTEL data to OTEL collectors outside of just google?

[brandonin]

We have a centralized credential handling mechanism in the codebase. Can you use that instead of introducing credential handling from env vars, config variables, and args?

@cornmander If we used a centralized credential handling mechanism, does that allow us to send OTEL data to OTEL collectors outside of just google?

@cornmander let me know if you have a reply for this one.

[haivanka]

Hey @brandonin @cornmander @jerop, any update on when this custom-headers support might go in? I’m interested in exporting telemetry but I’m blocked on this.

[deyim]

Please continue fixing this!

[brandonin]

I am still waiting on a response on the best way to approach this. My worry is that the ask is to utilize a centralized google product that doesn't allow for the ability to send it to any service. I personally would just like to follow the same solution that codex has provided and consider it best practice.

[haivanka]

@jerop @cornmander please support this by simply allowing custom (auth) headers, like Claude Code and Codex CLI do:

1. Claude Code — OTEL_EXPORTER_OTLP_HEADERS (https://code.claude.com/docs/en/monitoring-usage#common-configuration-variables)
2. Codex CLI — ... headers = { "x-otlp-api-key" = "${OTLP_TOKEN}" } ... (https://developers.openai.com/codex/local-config/#observibility-and-telemetry)

[gundermanc]

@brandonin I think this looks good overall. I agree that we should support non-Google auth.

• Can you share and/or document any assumptions you have for behavior when the token expires?
• Can you address this comment: https://github.com/google-gemini/gemini-cli/pull/11754#discussion_r2482265084
• Can you resolve the merge conflicts?