Add a local telemetry launcher (#1015)

1 files changed, 31 insertions, 3 deletions

diff --git a/docs/core/telemetry.md b/docs/core/telemetry.md
index 2e199465..2252e809 100644
--- a/docs/core/telemetry.md
+++ b/docs/core/telemetry.md
@@ -50,10 +50,38 @@ Learn more about OTEL exporter standard configuration in [documentation][otel-co
 mkdir .gemini/otel
 ```
 
-### Local
+### Local (Automated Script)
 
-This is the simplest way to inspect events, metrics, and traces without any external tools.
-This setup prints all telemetry from the Gemini CLI to your terminal using a local collector.
+For the most straightforward local setup, use the `scripts/local_telemetry.js` script. This script automates the entire process of setting up a local telemetry pipeline, including configuring the necessary settings in your `.gemini/settings.json` file.
+The script installs `otelcol-contrib` (The OpenTelemetry Collector) and `jaeger` (The Jaeger UI for viewing traces). To use it:
+
+1.  **Run the Script**:
+    Execute the script from the root of the repository:
+
+    ```bash
+    ./scripts/local_telemetry.js
+    ```
+
+    The script will:
+
+    - Download Jaeger and OTEL if needed.
+    - Start a local Jaeger instance.
+    - Start an OTEL collector configured to receive data from the Gemini CLI.
+    - Automatically enable telemetry in your workspace settings.
+    - On exit, disable telemetry.
+
+2.  **View Traces**:
+    Open your web browser and navigate to **http://localhost:16686** to access the Jaeger UI. Here you can inspect detailed traces of Gemini CLI operations.
+
+3.  **Inspect Logs and Metrics**:
+    The script redirects the OTEL collector's output (which includes logs and metrics) to `.gemini/otel/collector.log`. You can monitor this file to see the raw telemetry data:
+    ```bash
+    tail -f .gemini/otel/collector.log
+    ```
+4.  **Stop the Services**:
+    Press `Ctrl+C` in the terminal where the script is running to stop the OTEL Collector and Jaeger services.
+
+### Local (Manual Setup)
 
 **1. Create a Configuration File**