docs(telemetry): Refine OTEL Collector setup instructions

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.

docs/core/telemetry.md

@@ -6,7 +6,7 @@ This entire system is built on the **[OpenTelemetry] (OTEL)** standard, allowing
 
 [OpenTelemetry]: https://opentelemetry.io/
 
-## Quick Start: Enabling Telemetry
+## Enabling Telemetry
 
 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.
 
@@ -28,31 +28,23 @@ Add these lines to enable telemetry by in workspace (`.gemini/settings.json`) or
 }
 ```
 
-#### Mode 1: Console Output (Default)
+## Running an OTEL Collector
-
-If you only set `"telemetry": true` and do nothing else, the CLI will output all telemetry data directly to your console. This is the simplest way to inspect events, metrics, and traces without any external tools.
-
-#### Mode 2: Sending to a Collector
-
-To send data to a local or remote OpenTelemetry collector, set the following environment variable:
-
-```bash
-export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
-```
 
+An OTEL Collector is a service that receives, processes, and exports telemetry data.
 The CLI sends data using the OTLP/gRPC protocol.
 
 Learn more about OTEL exporter standard configuration in [documentation][otel-config-docs].
 
 [otel-config-docs]: https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/
 
-## Running an OTEL Collector
+### Configuration
 
-An OTEL Collector is a service that receives, processes, and exports telemetry data. Below are common setups.
+1. Install [otelcol-contrib] or use [docker]
 
-### Configurations
+[otelcol-contrib]: https://github.com/open-telemetry/opentelemetry-collector-contrib
+[docker]: https://www.docker.com/
 
-Create a folder for the OTEL configurations:
+2. Create a folder for the OTEL configurations:
 
 ```
 mkdir .gemini/otel
@@ -60,7 +52,8 @@ mkdir .gemini/otel
 
 ### Local
 
-This setup prints all telemetry from the Gemini CLI to your terminal using a local Docker container.
+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.
 
 **1. Create a Configuration File**
 
@@ -104,7 +97,13 @@ EOF
 
 **2. Run the Collector**
 
-In your terminal, run this Docker command:
+You can run the collector using `docker` or using the `otelcol-contrib` binary directly.
+
+**_Option 1: Use Docker_**
+
+This is the simplest method if you have Docker installed.
+
+1.  **Run the Collector**:
 
     ```bash
     docker run --rm --name otel-collector-local \
@@ -113,12 +112,25 @@ docker run --rm --name otel-collector-local \
       otel/opentelemetry-collector-contrib:latest
     ```
 
-**3. Stop the Collector**
+2.  **Stop the Collector**:
-
     ```bash
     docker stop otel-collector-local
     ```
 
+**_Option 2: Use `otelcol-contrib`_**
+
+Use this method if you prefer not to use Docker.
+
+1.  **Run the Collector**:
+    Once installed, run the collector with the configuration file you created earlier:
+
+    ```bash
+    ./otelcol-contrib --config="$(pwd)/.gemini/otel/collector-local.yaml"
+    ```
+
+2.  **Stop the Collector**:
+    Press `Ctrl+C` in the terminal where the collector is running.
+
 ### Google Cloud
 
 This setup sends all telemetry to Google Cloud for robust, long-term analysis.
@@ -181,22 +193,28 @@ EOF
 
 **4. Run the Collector**
 
-This command mounts your Google Cloud credentials into the container.
+You can run the collector for Google Cloud using either Docker or a locally installed `otelcol` binary.
 
-If using application default credentials:
+**_Option 1: Use Docker _**
+
+This method encapsulates the collector and its dependencies within a container.
+
+1.  **Run the Collector**:
+    Choose the command that matches your authentication method.
+
+    - **If using Application Default Credentials (`gcloud auth application-default login`)**:
 
       ```bash
       docker run --rm --name otel-collector-gcp \
         -p 4317:4317 \
         --user "$(id -u):$(id -g)" \
-  -v "$HOME/.config/gcloud/application_default_credentials.json":/etc/gcp/credentials.json \
+        -v "$HOME/.config/gcloud/application_default_credentials.json":/etc/gcp/credentials.json:ro \
         -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
       ```
 
-If using sevice account key:
+    - **If using a Service Account Key File**:
-
       ```bash
       docker run --rm --name otel-collector-gcp \
         -p 4317:4317 \
@@ -206,14 +224,30 @@ docker run --rm --name otel-collector-gcp \
         otel/opentelemetry-collector-contrib:latest --config /etc/otelcol-contrib/config.yaml
       ```
 
-Your telemetry data will now appear in Cloud Trace, Monitoring, and Logging.
+2.  **Check Status**:
-
+    Your telemetry data will now appear in Google Cloud Trace, Monitoring, and Logging.
-**5. Stop the Collector**
 
+3.  **Stop the Collector**:
     ```bash
     docker stop otel-collector-gcp
     ```
 
+**_Option 2: Use `otelcol-contrib`_**
+
+Use this method if you prefer not to use Docker.
+
+1.  **Run the Collector**:
+
+    ```bash
+    ./otelcol-contrib --config="file:$(pwd)/.gemini/otel/collector-gcp.yaml"
+    ```
+
+2.  **Check Status**:
+    Your telemetry data will now appear in Google Cloud Trace, Monitoring, and Logging.
+
+3.  **Stop the Collector**:
+    Press `Ctrl+C` in the terminal where the collector is running.
+
 ---
 
 ## Data Reference: Logs & Metrics