Updates the telemetry documentation and the GCP telemetry script to make it clearer that the Gemini CLI needs to be run in a separate terminal session after starting the collector script.
This addresses potential user confusion where they might expect telemetry data to appear without actively using the CLI.
#750
Related to https://b.corp.google.com/issues/423605555 - I figured this might be a simpler solution to start with, while still also being useful on its own even if we do implement that.
Adds a script - `scripts/telemetry_gcp.js` - to simplify setting up a local OpenTelemetry collector that forwards data to Google Cloud. This is a follow up to the script for local telemetry `scripts/local_telemetry.js` added in #1015.
This script automates downloading necessary binaries, configuring the collector, and updating workspace settings.
Also includes `scripts/telemetry_utils.js` with shared helper functions for telemetry scripts. Will refactor `scripts/local_t elemetry.js` in next steps to use this shared functionality.
Updates `docs/core/telemetry.md` to include:
- A new "Quick Start" section
- Detailed instructions for the new GCP automated script
- Reorganization of existing sections for clarity
#750
---
```
✨ Starting Local Telemetry Exporter for Google Cloud ✨⚙️ Enabled telemetry in workspace settings.
🔧 Set telemetry OTLP endpoint to http://localhost:4317.
✅ Workspace settings updated.
✅ Using Google Cloud Project ID: foo-bar
🔑 Please ensure you are authenticated with Google Cloud:
- Run `gcloud auth application-default login` OR ensure `GOOGLE_APPLICATION_CREDENTIALS` environment variable points to a valid service account key.
- The account needs "Cloud Trace Agent", "Monitoring Metric Writer", and "Logs Writer" roles.
✅ otelcol-contrib already exists at /Users/jerop/github/gemini-cli/.gemini/otel/bin/otelcol-contrib
🧹 Cleaning up old processes and logs...
✅ Deleted old GCP collector log.
📄 Wrote OTEL collector config to /Users/jerop/github/gemini-cli/.gemini/otel/collector-gcp.yaml
🚀 Starting OTEL collector for GCP... Logs: /Users/jerop/github/gemini-cli/.gemini/otel/collector-gcp.log
⏳ Waiting for OTEL collector to start (PID: 65145)...
✅ OTEL collector started successfully on port 4317.
✨ Local OTEL collector for GCP is running.
📄 Collector logs are being written to: /Users/jerop/github/gemini-cli/.gemini/otel/collector-gcp.log
📊 View your telemetry data in Google Cloud Console:
- Traces: https://console.cloud.google.com/traces/list?project=foo-bar
- Metrics: https://console.cloud.google.com/monitoring/metrics-explorer?project=foo-bar
- Logs: https://console.cloud.google.com/logs/query;query=logName%3D%22projects%2Ffoo-bar%2Flogs%2Fgemini_cli%22?project=foo-bar
Press Ctrl+C to exit.
^C
👋 Shutting down...
⚙️ Disabled telemetry in workspace settings.
🔧 Cleared telemetry OTLP endpoint.
✅ Workspace settings updated.
🛑 Stopping otelcol-contrib (PID: 65145)...
✅ otelcol-contrib stopped.
```
Make a pass through the docs/deployment.md file to hopefully improve readability and conciseness
Notably, I've proposed axing both the "Core Features" section - which feels too promotional this far down the folder hierarchy and which is somewhat repetitive to later in the page - and the "Basic Interaction" section - which is covered better, and makes more sense, in other parts of the documentation
This change simplifies telemetry setup for users who want to integrate with GCP, as they no longer need to configure a local collector or an explicit endpoint if their project is already set up in the environment.
This change updates the telemetry system to automatically export traces, logs, and metrics to Google Cloud Platform (GCP) if the `GOOGLE_CLOUD_PROJECT` environment variable is set and no explicit `telemetryOtlpEndpoint` is configured by the user.
Key changes:
- The default `telemetryOtlpEndpoint` in `Config` is now an empty string.
- The `initializeTelemetry` SDK logic now prioritizes:
- User-defined `telemetryOtlpEndpoint`.
- `GOOGLE_CLOUD_PROJECT` for direct GCP export.
- Console exporters as a fallback.
- If an invalid `telemetryOtlpEndpoint` is provided, it falls back to console exporters with a warning.
#750
Changes:
- Ensure proper shutdown in non-interactive mode
- Ensures the initial user prompt is logged in non-interactive mode
- Improve telemetry for streaming - handle chunks and input token count is now alongside other token counts in response
To test:
- Follow instructions in https://github.com/google-gemini/gemini-cli/blob/main/docs/core/telemetry.md#google-cloud
- Run CLI in non-interactive mode and observe logs/metrics in GCP Logs Explorer and Metrics Explorer
#750
Refactor OpenTelemetry logging for API requests, responses, and errors. Moved logging responsibility from GeminiClient to GeminiChat for more detailed logging.
#750
Add the user's decision (accept, reject, modify) to tool call telemetry to better understand user intent. The decision provides crucial context to the `success` metric, as a user can reject a call that would have succeeded or accept one that fails.
Also prettify the arguments json.
Example:
#750
Adds the following attributes to the event:
- embedding_model
- api_key_enabled
- code_assist_enabled
- debug_mode
- mcp_servers
This additional data will provide more insight into user configurations.
Adds the text content of the API response to the telemetry event. This provides more context for debugging and analysis without logging the entire, potentially large, response object.
- Adds an optional field to the type.
- Updates to include the field in the logged attributes.
- Modifies the to extract the response text using and pass it to the logger.
- Adds a new test file for the telemetry loggers, including tests for the function to verify the new functionality.
This commit refactors the telemetry system to pass a object to various logging and metrics functions. This change centralizes configuration management within the telemetry system, making it more modular and easier to maintain.
The constructor and various tool execution functions have been updated to accept the object, which is then passed down to the telemetry functions. This eliminates the need to pass individual configuration values, such as , through multiple layers of the application.
Standardizes on the distribution for local and Google Cloud setups.
Restructures the guide to present Docker and standalone binary as clear, parallel options and makes the Google Cloud command more robust.
This commit enhances the telemetry documentation with several key improvements for clarity and usability.
- Adds a prominent note clarifying that telemetry is currently incompatible with sandbox mode.
- Updates the example JSON configuration to explicitly include sandbox: false to prevent user confusion.
- Introduces a new Configurations section with instructions to create the directory.
- Adds a new step for setting necessary environment variables for the Google Cloud setup.
- Makes the command for Google Cloud more portable by using the environment variable instead of a hardcoded path.
- Re-numbers the steps in the Google Cloud setup guide to maintain a logical flow.
This commit adds a new `tutorials.md` file to the CLI documentation.
This section is intended to house various tutorials for using Gemini CLI.
The initial content includes a tutorial on setting up Model Context
Protocol (MCP) servers, using the GitHub MCP server as an example.
The `docs/cli/index.md` has been updated to include a link to this
new tutorials section.
This commit introduces the ability to use system environment variables
within the settings files (e.g., `settings.json`). Users can now
reference environment variables using the `${VAR_NAME}` syntax.
This enhancement improves security and flexibility, particularly
for configurations like MCP server settings, which often require
sensitive tokens.
Previously, to configure an MCP server, a token might be directly
embedded:
```json
"mcpServers": {
"github": {
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "pat_abc123"
}
// ...
}
}
```
With this change, the same configuration can securely reference an
environment variable:
```json
"mcpServers": {
"github": {
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
}
// ...
}
}
```
This allows users to avoid storing secrets directly in configuration files.
Jerop Kipruto
Allen Hutchison
Jacob MacDonald
Keir Mierle
Tommaso Sciortino
starsandskies
Billy Biggs
Anas H. Sulaiman
Eddie Santos
Mark McDonald
Leo
JingboWang1997-1
matt korwel
anj-s
Olcan
Brandon Keiji
N. Taylor Mullen
Bryan Morgan
cperry-goog
Keith Ballinger
Tolik Malibroda
Miguel Solorio
Riccardo Carlesso