docs(telemetry): improve telemetry documentation

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 is contained in:
jerop 2025-06-10 20:28:24 +00:00 committed by Jerop Kipruto
parent 6f4226fde1
commit f0f7a30d9f
1 changed files with 28 additions and 8 deletions

View File

@ -10,6 +10,8 @@ This entire system is built on the **[OpenTelemetry] (OTEL)** standard, allowing
You can enable telemetry in multiple ways. [Configuration](configuration.md) is primarily managed via the `.gemini/settings.json` file and environment variables, but CLI flags can override these settings for a specific session.
> **A Note on Sandbox Mode:** Telemetry is not compatible with sandbox mode at this time. Turn off sandbox mode before enabling telemetry. Tracked in #894.
**Order of Precedence:**
1. **CLI Flag (`--telemetry`):** These override all other settings for the current session.
@ -17,13 +19,12 @@ You can enable telemetry in multiple ways. [Configuration](configuration.md) is
3. **User Settings File (`~/.gemini/settings.json`):** If not set by a flag or workspace settings, the value from this global user file is used.
4. **Default:** If telemetry is not configured by a flag or in any settings file, it is disabled.
Add this line to enable telemetry by in workspace (`.gemini/settings.json`) or user (`~/.gemini/settings.json`) settings:
Add these lines to enable telemetry by in workspace (`.gemini/settings.json`) or user (`~/.gemini/settings.json`) settings:
```json
{
"telemetry": {
"enabled": true
}
"telemetry": true,
"sandbox": false
}
```
@ -51,6 +52,14 @@ Learn more about OTEL exporter standard configuration in [documentation][otel-co
An OTEL Collector is a service that receives, processes, and exports telemetry data. Below are common setups.
### Configurations
Create a folder for the OTEL configurations:
```
mkdir .gemini/otel
```
### Local
This setup prints all telemetry from the Gemini CLI to your terminal using a local Docker container.
@ -122,7 +131,17 @@ This setup sends all telemetry to Google Cloud for robust, long-term analysis.
- **APIs Enabled**: Cloud Trace, Cloud Monitoring, Cloud Logging.
- **Authentication**: A Service Account with the roles `Cloud Trace Agent`, `Monitoring Metric Writer`, and `Logs Writer`. Ensure your environment is authenticated (e.g., via `gcloud auth application-default login` or a service account key file).
**2. Create a Configuration File**
**2. Set environment variables**
Set the `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION`, and `GOOGLE_GENAI_USE_VERTEXAI` environment variables:
```bash
GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"
GOOGLE_CLOUD_LOCATION="YOUR_PROJECT_LOCATION" # e.g., us-central1
GOOGLE_GENAI_USE_VERTEXAI=true
```
**3. Create a Configuration File**
Create `.gemini/otel/collector-gcp.yaml`:
@ -162,7 +181,7 @@ service:
EOF
```
**3. Run the Collector**
**4. Run the Collector**
This command mounts your Google Cloud credentials into the container.
@ -171,7 +190,8 @@ If using application default credentials:
```bash
docker run --rm --name otel-collector-gcp \
-p 4317:4317 \
-v "/home/user/.config/gcloud/application_default_credentials.json":/etc/gcp/credentials.json \
--user "$(id -u):$(id -g)" \
-v "$HOME/.config/gcloud/application_default_credentials.json":/etc/gcp/credentials.json \
-e "GOOGLE_APPLICATION_CREDENTIALS=/etc/gcp/credentials.json" \
-v "$(pwd)/.gemini/otel/collector-gcp.yaml":/etc/otelcol-contrib/config.yaml \
otel/opentelemetry-collector-contrib:latest --config /etc/otelcol-contrib/config.yaml
@ -190,7 +210,7 @@ docker run --rm --name otel-collector-gcp \
Your telemetry data will now appear in Cloud Trace, Monitoring, and Logging.
**3. Stop the Collector**
**5. Stop the Collector**
```bash
docker stop otel-collector-gcp