Add telemetry command and refactor telemetry settings (#1060)

#750 

### Telemetry Settings
Refactors telemetry configuration to use a nested `telemetry` object in `settings.json`, for example:

```json
{
  "telemetry": {
    "enabled": true,
    "target": "gcp"
    "log-prompts": "true"
  },
  "sandbox": false
}
```

The above includes
- Centralized telemetry settings under a `telemetry` object in `settings.json`.
- CLI flags for the `gemini` command to override all telemetry sub-settings:
    - `--telemetry` / `--no-telemetry`
    - `--telemetry-target <local|gcp>`
    - `--telemetry-otlp-endpoint <URL>`
    - `--telemetry-log-prompts` / `--no-telemetry-log-prompts`
- Updates `packages/cli/src/config/config.ts` and `packages/core/src/config/config.ts` to read from the new settings structure and respect the new CLI flags.
- Modifies `scripts/handle-telemetry.js`, `scripts/local_telemetry.js`, and `scripts/telemetry_utils.js` to align with the new settings structure.
- Updates `docs/core/telemetry.md` to reflect the new settings structure, CLI flags, and order of precedence.
- Renames `logUserPromptsEnabled` to `logPrompts` for brevity.

### `npm run telemetry`

Add a new `npm run telemetry` command that uses `scripts/telemetry.js`, automates the entire process of setting up a local and GCP telemetry pipelines, including configuring the necessary settings in the `.gemini/settings.json` workspace file and installing required binaries (e.g. `otelcol-contrib`).

---
```shell
$ npm run telemetry -- --target=gcp

> gemini-cli@0.1.0 telemetry
> node scripts/telemetry.js --target=gcp

⚙️  Using command-line target: gcp
🚀 Running telemetry script for target: gcp.
✨ Starting Local Telemetry Exporter for Google Cloud ✨
⚙️  Enabled telemetry in workspace settings.
🔧 Set telemetry OTLP endpoint to http://localhost:4317.
🎯 Set telemetry target to gcp.
✅ 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: 17013)...
✅ OTEL collector started successfully on port 4317.

✨ Local OTEL collector for GCP is running.

🚀 To send telemetry, run the Gemini CLI in a separate terminal window.

📄 Collector logs are being written to: /Users/jerop/github/gemini-cli/.gemini/otel/collector-gcp.log

📊 View your telemetry data in Google Cloud Console:
   - Logs: https://console.cloud.google.com/logs/query;query=logName%3D%22projects%2Ffoo-bar%2Flogs%2Fgemini_cli%22?project=foo-bar
   - Metrics: https://console.cloud.google.com/monitoring/metrics-explorer?project=foo-bar
   - Traces: https://console.cloud.google.com/traces/list?project=foo-bar

Press Ctrl+C to exit.
^C
👋 Shutting down...
⚙️  Disabled telemetry in workspace settings.
🔧 Cleared telemetry OTLP endpoint.
🎯 Cleared telemetry target.
✅ Workspace settings updated.
🛑 Stopping otelcol-contrib (PID: 17013)...
✅ otelcol-contrib stopped.
```

scripts/local_telemetry.js

@@ -348,8 +348,13 @@ async function main() {
 
     // Restore original settings
     const finalSettings = readJsonFile(WORKSPACE_SETTINGS_FILE);
-    delete finalSettings.telemetry;
-    delete finalSettings.telemetryOtlpEndpoint;
+    if (finalSettings.telemetry) {
+      delete finalSettings.telemetry.enabled;
+      delete finalSettings.telemetry.otlpEndpoint;
+      if (Object.keys(finalSettings.telemetry).length === 0) {
+        delete finalSettings.telemetry;
+      }
+    }
     finalSettings.sandbox = originalSandboxSetting;
     writeJsonFile(WORKSPACE_SETTINGS_FILE, finalSettings);
     console.log('✅ Restored original telemetry and sandbox settings.');
@@ -393,8 +398,12 @@ async function main() {
   const originalSandboxSetting = workspaceSettings.sandbox;
   let settingsModified = false;
 
-  if (workspaceSettings.telemetry !== true) {
-    workspaceSettings.telemetry = true;
+  if (typeof workspaceSettings.telemetry !== 'object') {
+    workspaceSettings.telemetry = {};
+  }
+
+  if (workspaceSettings.telemetry.enabled !== true) {
+    workspaceSettings.telemetry.enabled = true;
     settingsModified = true;
     console.log('⚙️  Enabled telemetry in workspace settings.');
   }
@@ -405,12 +414,18 @@ async function main() {
     console.log('✅ Disabled sandbox mode for local telemetry.');
   }
 
-  if (workspaceSettings.telemetryOtlpEndpoint !== 'http://localhost:4317') {
-    workspaceSettings.telemetryOtlpEndpoint = 'http://localhost:4317';
+  if (workspaceSettings.telemetry.otlpEndpoint !== 'http://localhost:4317') {
+    workspaceSettings.telemetry.otlpEndpoint = 'http://localhost:4317';
     settingsModified = true;
     console.log('🔧 Set telemetry endpoint to http://localhost:4317.');
   }
 
+  if (workspaceSettings.telemetry.target !== 'local') {
+    workspaceSettings.telemetry.target = 'local';
+    settingsModified = true;
+    console.log('🎯 Set telemetry target to local.');
+  }
+
   if (settingsModified) {
     writeJsonFile(WORKSPACE_SETTINGS_FILE, workspaceSettings);
     console.log('✅ Workspace settings updated.');

scripts/telemetry.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { execSync } from 'child_process';
+import { join } from 'path';
+import { existsSync, readFileSync } from 'fs';
+
+const projectRoot = join(import.meta.dirname, '..');
+
+const SETTINGS_DIRECTORY_NAME = '.gemini';
+const USER_SETTINGS_DIR = join(
+  process.env.HOME || process.env.USERPROFILE || process.env.HOMEPATH || '',
+  SETTINGS_DIRECTORY_NAME,
+);
+const USER_SETTINGS_PATH = join(USER_SETTINGS_DIR, 'settings.json');
+const WORKSPACE_SETTINGS_PATH = join(
+  projectRoot,
+  SETTINGS_DIRECTORY_NAME,
+  'settings.json',
+);
+
+let settingsTarget = undefined;
+
+function loadSettingsValue(filePath) {
+  try {
+    if (existsSync(filePath)) {
+      const content = readFileSync(filePath, 'utf-8');
+      const jsonContent = content.replace(/\/\/[^\n]*/g, '');
+      const settings = JSON.parse(jsonContent);
+      return settings.telemetry?.target;
+    }
+  } catch (e) {
+    console.warn(
+      `⚠️ Warning: Could not parse settings file at ${filePath}: ${e.message}`,
+    );
+  }
+  return undefined;
+}
+
+settingsTarget = loadSettingsValue(WORKSPACE_SETTINGS_PATH);
+
+if (!settingsTarget) {
+  settingsTarget = loadSettingsValue(USER_SETTINGS_PATH);
+}
+
+let target = settingsTarget || 'local';
+const allowedTargets = ['local', 'gcp'];
+
+const targetArg = process.argv.find((arg) => arg.startsWith('--target='));
+if (targetArg) {
+  const potentialTarget = targetArg.split('=')[1];
+  if (allowedTargets.includes(potentialTarget)) {
+    target = potentialTarget;
+    console.log(`⚙️  Using command-line target: ${target}`);
+  } else {
+    console.error(
+      `🛑 Error: Invalid target '${potentialTarget}'. Allowed targets are: ${allowedTargets.join(', ')}.`,
+    );
+    process.exit(1);
+  }
+} else if (settingsTarget) {
+  console.log(
+    `⚙️ Using telemetry target from settings.json: ${settingsTarget}`,
+  );
+}
+
+const scriptPath = join(
+  projectRoot,
+  'scripts',
+  target === 'gcp' ? 'telemetry_gcp.js' : 'local_telemetry.js',
+);
+
+try {
+  console.log(`🚀 Running telemetry script for target: ${target}.`);
+  execSync(`node ${scriptPath}`, { stdio: 'inherit', cwd: projectRoot });
+} catch (error) {
+  console.error(`🛑 Failed to run telemetry script for target: ${target}`);
+  console.error(error);
+  process.exit(1);
+}

scripts/telemetry_gcp.js

@@ -70,6 +70,7 @@ async function main() {
   const originalSandboxSetting = manageTelemetrySettings(
     true,
     'http://localhost:4317',
+    'gcp',
   );
   registerCleanup(
     () => [collectorProcess].filter((p) => p), // Function to get processes
@@ -80,9 +81,12 @@ async function main() {
   const projectId = process.env.GOOGLE_CLOUD_PROJECT;
   if (!projectId) {
     console.error(
-      '🛑 Error: GOOGLE_CLOUD_PROJECT environment variable is not set.',
+      '🛑 Error: GOOGLE_CLOUD_PROJECT environment variable is not exported.',
     );
-    console.log('Please set it to your Google Cloud Project ID and try again.');
+    console.log(
+      '   Please set it to your Google Cloud Project ID and try again.',
+    );
+    console.log('   `export GOOGLE_CLOUD_PROJECT=your-project-id`');
     process.exit(1);
   }
   console.log(`✅ Using Google Cloud Project ID: ${projectId}`);
@@ -167,13 +171,13 @@ async function main() {
   console.log(`\n📄 Collector logs are being written to: ${OTEL_LOG_FILE}`);
   console.log(`\n📊 View your telemetry data in Google Cloud Console:`);
   console.log(
-    `   - Traces: https://console.cloud.google.com/traces/list?project=${projectId}`,
+    `   - Logs: https://console.cloud.google.com/logs/query;query=logName%3D%22projects%2F${projectId}%2Flogs%2Fgemini_cli%22?project=${projectId}`,
   );
   console.log(
     `   - Metrics: https://console.cloud.google.com/monitoring/metrics-explorer?project=${projectId}`,
   );
   console.log(
-    `   - Logs: https://console.cloud.google.com/logs/query;query=logName%3D%22projects%2F${projectId}%2Flogs%2Fgemini_cli%22?project=${projectId}`,
+    `   - Traces: https://console.cloud.google.com/traces/list?project=${projectId}`,
   );
   console.log(`\nPress Ctrl+C to exit.`);
 }

scripts/telemetry_utils.js

@@ -10,7 +10,7 @@ import path from 'path';
 import fs from 'fs';
 import net from 'net';
 import os from 'os';
-import { execSync } from 'child_process'; // Removed spawn, it's not used here
+import { execSync } from 'child_process';
 import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -251,15 +251,20 @@ export async function ensureBinary(
 export function manageTelemetrySettings(
   enable,
   oTelEndpoint = 'http://localhost:4317',
+  target = 'local',
   originalSandboxSettingToRestore,
 ) {
   const workspaceSettings = readJsonFile(WORKSPACE_SETTINGS_FILE);
   const currentSandboxSetting = workspaceSettings.sandbox;
   let settingsModified = false;
 
+  if (typeof workspaceSettings.telemetry !== 'object') {
+    workspaceSettings.telemetry = {};
+  }
+
   if (enable) {
-    if (workspaceSettings.telemetry !== true) {
-      workspaceSettings.telemetry = true;
+    if (workspaceSettings.telemetry.enabled !== true) {
+      workspaceSettings.telemetry.enabled = true;
       settingsModified = true;
       console.log('⚙️  Enabled telemetry in workspace settings.');
     }
@@ -268,22 +273,36 @@ export function manageTelemetrySettings(
       settingsModified = true;
       console.log('✅ Disabled sandbox mode for telemetry.');
     }
-    if (workspaceSettings.telemetryOtlpEndpoint !== oTelEndpoint) {
-      workspaceSettings.telemetryOtlpEndpoint = oTelEndpoint;
+    if (workspaceSettings.telemetry.otlpEndpoint !== oTelEndpoint) {
+      workspaceSettings.telemetry.otlpEndpoint = oTelEndpoint;
       settingsModified = true;
       console.log(`🔧 Set telemetry OTLP endpoint to ${oTelEndpoint}.`);
     }
-  } else {
-    if (workspaceSettings.telemetry === true) {
-      delete workspaceSettings.telemetry;
+    if (workspaceSettings.telemetry.target !== target) {
+      workspaceSettings.telemetry.target = target;
       settingsModified = true;
-      console.log('⚙️ Disabled telemetry in workspace settings.');
+      console.log(`🎯 Set telemetry target to ${target}.`);
     }
-    if (workspaceSettings.telemetryOtlpEndpoint) {
-      delete workspaceSettings.telemetryOtlpEndpoint;
+  } else {
+    if (workspaceSettings.telemetry.enabled === true) {
+      delete workspaceSettings.telemetry.enabled;
+      settingsModified = true;
+      console.log('⚙️  Disabled telemetry in workspace settings.');
+    }
+    if (workspaceSettings.telemetry.otlpEndpoint) {
+      delete workspaceSettings.telemetry.otlpEndpoint;
       settingsModified = true;
       console.log('🔧 Cleared telemetry OTLP endpoint.');
     }
+    if (workspaceSettings.telemetry.target) {
+      delete workspaceSettings.telemetry.target;
+      settingsModified = true;
+      console.log('🎯 Cleared telemetry target.');
+    }
+    if (Object.keys(workspaceSettings.telemetry).length === 0) {
+      delete workspaceSettings.telemetry;
+    }
+
     if (
       originalSandboxSettingToRestore !== undefined &&
       workspaceSettings.sandbox !== originalSandboxSettingToRestore