feat(telemetry): support custom OTLP headers in telemetry configuration

[jesussamuel-byte]

This PR adds support for custom OTLP headers in the Gemini CLI telemetry configuration, allowing users to authenticate and pass custom metadata to OTLP HTTP and gRPC endpoints (such as Grafana Cloud, Honeycomb, Datadog, or authenticated OpenTelemetry Collectors).

Key Changes

• Core Telemetry Configuration (packages/core/src/config/config.ts, packages/core/src/telemetry/config.ts):
  • Added otlpHeaders?: Record<string, string> to TelemetrySettings and getTelemetryOtlpHeaders() to Config.
  • Added parseOtlpHeaders() supporting both JSON object format ({"Authorization":"Bearer token"}) and comma/semicolon-separated key=value pairs (Authorization=Bearer token,x-api-key=abc123), with RFC 7230 header name and control-character validation.
  • Resolved otlpHeaders in resolveTelemetrySettings() by merging settings.otlpHeaders (lowest precedence), OTEL_EXPORTER_OTLP_HEADERS, GEMINI_TELEMETRY_OTLP_HEADERS, and argv.telemetryOtlpHeaders (highest precedence) with case-insensitive header key deduplication.
• OTLP Exporters (packages/core/src/telemetry/sdk.ts):
  • Passed headers to HTTP OTLP exporters (OTLPTraceExporterHttp, OTLPLogExporterHttp, OTLPMetricExporterHttp) when otlpHeaders is non-empty.
  • Constructed @grpc/grpc-js Metadata from otlpHeaders and passed metadata to gRPC OTLP exporters (OTLPTraceExporter, OTLPLogExporter, OTLPMetricExporter) when otlpHeaders is non-empty.
• CLI Settings Schema & Documentation (packages/cli/src/config/settingsSchema.ts, schemas/settings.schema.json, docs/):
  • Added otlpHeaders to TelemetrySettings in settingsSchema.ts and schemas/settings.schema.json (which automatically supports $VAR_NAME / ${VAR_NAME} environment variable resolution in settings.json).
  • Documented otlpHeaders and GEMINI_TELEMETRY_OTLP_HEADERS in docs/cli/telemetry.md and docs/reference/configuration.md.

Related Issues

Fixes #11802

How to Validate

1. Run the telemetry and configuration unit tests:

   npx vitest run packages/core/src/telemetry/config.test.ts packages/core/src/telemetry/sdk.test.ts packages/core/src/config/config.test.ts packages/cli/src/config/settings.test.ts

2. Configure custom OTLP headers in .gemini/settings.json (with optional environment variable interpolation) or via GEMINI_TELEMETRY_OTLP_HEADERS / OTEL_EXPORTER_OTLP_HEADERS:

   {
     "telemetry": {
       "enabled": true,
       "otlpEndpoint": "https://otlp.example.com",
       "otlpProtocol": "http",
       "otlpHeaders": {
         "Authorization": "Bearer ${OTLP_AUTH_TOKEN}"
       }
     }
   }

[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 introduces a flexible mechanism for configuring custom headers for OTLP telemetry exporters. By allowing users to specify headers via configuration files, environment variables, or CLI arguments, it enables integration with authenticated telemetry backends like Grafana Cloud, Honeycomb, and Datadog. The implementation includes robust parsing, validation, and a precedence-based resolution strategy to ensure secure and reliable header management.

Highlights

• Custom OTLP Header Support: Added support for custom OTLP headers in telemetry configuration, enabling authentication and metadata passing for OTLP HTTP and gRPC endpoints.
• Header Parsing and Validation: Implemented parseOtlpHeaders() to support both JSON objects and key=value strings, including RFC 7230 validation for header names and values.
• Configuration Resolution: Updated resolveTelemetrySettings() to merge headers from settings, environment variables (OTEL_EXPORTER_OTLP_HEADERS, GEMINI_TELEMETRY_OTLP_HEADERS), and CLI arguments with case-insensitive deduplication.
• Exporter Integration: Updated OTLP exporters to inject custom headers into HTTP requests and gRPC metadata.

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 the 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 counterproductive. 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]

📊 PR Size: size/L

• Lines changed: 692
• Additions: +681
• Deletions: -11
• Files changed: 12

[gemini-code-assist]

Code Review

This pull request adds support for custom OTLP headers (otlpHeaders) in telemetry configuration, allowing users to configure them via settings, environment variables, or CLI arguments, and updates the telemetry SDK to pass these headers to HTTP and gRPC exporters. Feedback on the changes includes: (1) adhering to the repository style guide by using vi.stubEnv and vi.unstubAllEnvs() in tests instead of directly modifying process.env, (2) splitting OTLP headers only by commas instead of semicolons to prevent corrupting valid header values, and (3) wrapping gRPC metadata assignments in a try-catch block to avoid application crashes from invalid keys.

[jesussamuel-byte]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for custom OTLP headers (otlpHeaders) in telemetry configuration, allowing users to define headers via settings, environment variables (GEMINI_TELEMETRY_OTLP_HEADERS and OTEL_EXPORTER_OTLP_HEADERS), or command-line arguments. It implements robust parsing logic for both JSON objects and comma-separated key-value pairs, handles case-insensitive deduplication, and applies these headers to HTTP exporters or as metadata to gRPC exporters. The review feedback highlights a security improvement opportunity to sanitize the environment used for variable expansion in HTTP headers to prevent potential exfiltration of sensitive system environment variables by malicious extensions.

[jesussamuel-byte]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for custom OTLP headers (otlpHeaders) in telemetry configuration, allowing users to define headers via settings, environment variables (OTEL_EXPORTER_OTLP_HEADERS and GEMINI_TELEMETRY_OTLP_HEADERS), or CLI arguments. The changes include parsing, validation, and merging logic, as well as applying these headers to HTTP and gRPC exporters. The review feedback highlights critical security concerns regarding the potential exposure of sensitive credentials (such as bearer tokens) when raw header strings are interpolated directly into configuration error messages. Additionally, the feedback points out a potential runtime crash in validateHeadersObject if headers is null or an array, suggesting a safer type guard to prevent runtime TypeErrors.

[jesussamuel-byte]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for custom OTLP headers (otlpHeaders) in telemetry configuration, allowing headers to be defined via settings, environment variables, or command-line arguments, and integrates them into HTTP and gRPC exporters. Review feedback recommends percent-decoding parsed header keys and values to comply with the OpenTelemetry specification, and extracting repetitive error strings in the configuration resolver into a helper function to reduce duplication.

_{Note: Security Review did not run due to the size of the PR.}

[jesussamuel-byte]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces support for custom OTLP headers (otlpHeaders) in telemetry configuration, allowing users to configure custom headers via settings, environment variables (GEMINI_TELEMETRY_OTLP_HEADERS and OTEL_EXPORTER_OTLP_HEADERS), or CLI arguments. The changes include parsing logic for both JSON and comma-separated key-value formats, merging headers with case-insensitive deduplication, and applying them to HTTP and gRPC exporters. Documentation, schemas, and comprehensive unit tests have been updated accordingly. Feedback on the pull request suggests explicitly rejecting special keys like proto and constructor in isValidHeaderName to prevent potential prototype pollution when handling user-controlled header names.

[jesussamuel-byte]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds support for custom OTLP headers (otlpHeaders) in the telemetry configuration, allowing users to supply custom headers via settings, environment variables (GEMINI_TELEMETRY_OTLP_HEADERS and OTEL_EXPORTER_OTLP_HEADERS), or CLI arguments. The implementation includes robust parsing for both JSON and comma-separated key-value formats, validation against header injection and prototype pollution, and integration with both HTTP and gRPC exporters. Comprehensive unit tests and documentation updates have been added to support this feature. There are no review comments on this pull request, and I have no feedback to provide.