From f0f7a30d9f47bff291171ad0aeb45cf8e8e23cc8 Mon Sep 17 00:00:00 2001
From: jerop <jerop@google.com>
Date: Tue, 10 Jun 2025 20:28:24 +0000
Subject: 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.
---
 docs/core/telemetry.md | 36 ++++++++++++++++++++++++++++--------
 1 file changed, 28 insertions(+), 8 deletions(-)

(limited to 'docs/core')

diff --git a/docs/core/telemetry.md b/docs/core/telemetry.md
index 6f371eec..7587f0a5 100644
--- a/docs/core/telemetry.md
+++ b/docs/core/telemetry.md
@@ -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
-- 
cgit v1.2.3