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

> [email protected] 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.
```

3 files changed, 127 insertions, 13 deletions

diff --git a/packages/cli/src/config/config.test.ts b/packages/cli/src/config/config.test.ts
index 1d8c486a..6afe7f6e 100644
--- a/packages/cli/src/config/config.test.ts
+++ b/packages/cli/src/config/config.test.ts
@@ -127,31 +127,120 @@ describe('loadCliConfig telemetry', () => {
 
   it('should use telemetry value from settings if CLI flag is not present (settings true)', async () => {
     process.argv = ['node', 'script.js'];
-    const settings: Settings = { telemetry: true };
+    const settings: Settings = { telemetry: { enabled: true } };
     const config = await loadCliConfig(settings, [], [], 'test-session');
     expect(config.getTelemetryEnabled()).toBe(true);
   });
 
   it('should use telemetry value from settings if CLI flag is not present (settings false)', async () => {
     process.argv = ['node', 'script.js'];
-    const settings: Settings = { telemetry: false };
+    const settings: Settings = { telemetry: { enabled: false } };
     const config = await loadCliConfig(settings, [], [], 'test-session');
     expect(config.getTelemetryEnabled()).toBe(false);
   });
 
   it('should prioritize --telemetry CLI flag (true) over settings (false)', async () => {
     process.argv = ['node', 'script.js', '--telemetry'];
-    const settings: Settings = { telemetry: false };
+    const settings: Settings = { telemetry: { enabled: false } };
     const config = await loadCliConfig(settings, [], [], 'test-session');
     expect(config.getTelemetryEnabled()).toBe(true);
   });
 
   it('should prioritize --no-telemetry CLI flag (false) over settings (true)', async () => {
     process.argv = ['node', 'script.js', '--no-telemetry'];
-    const settings: Settings = { telemetry: true };
+    const settings: Settings = { telemetry: { enabled: true } };
     const config = await loadCliConfig(settings, [], [], 'test-session');
     expect(config.getTelemetryEnabled()).toBe(false);
   });
+
+  it('should use telemetry OTLP endpoint from settings if CLI flag is not present', async () => {
+    process.argv = ['node', 'script.js'];
+    const settings: Settings = {
+      telemetry: { otlpEndpoint: 'http://settings.example.com' },
+    };
+    const config = await loadCliConfig(settings, [], [], 'test-session');
+    expect(config.getTelemetryOtlpEndpoint()).toBe(
+      'http://settings.example.com',
+    );
+  });
+
+  it('should prioritize --telemetry-otlp-endpoint CLI flag over settings', async () => {
+    process.argv = [
+      'node',
+      'script.js',
+      '--telemetry-otlp-endpoint',
+      'http://cli.example.com',
+    ];
+    const settings: Settings = {
+      telemetry: { otlpEndpoint: 'http://settings.example.com' },
+    };
+    const config = await loadCliConfig(settings, [], [], 'test-session');
+    expect(config.getTelemetryOtlpEndpoint()).toBe('http://cli.example.com');
+  });
+
+  it('should use default endpoint if no OTLP endpoint is provided via CLI or settings', async () => {
+    process.argv = ['node', 'script.js'];
+    const settings: Settings = { telemetry: { enabled: true } };
+    const config = await loadCliConfig(settings, [], [], 'test-session');
+    expect(config.getTelemetryOtlpEndpoint()).toBe('http://localhost:4317');
+  });
+
+  it('should use telemetry target from settings if CLI flag is not present', async () => {
+    process.argv = ['node', 'script.js'];
+    const settings: Settings = {
+      telemetry: { target: ServerConfig.DEFAULT_TELEMETRY_TARGET },
+    };
+    const config = await loadCliConfig(settings, [], [], 'test-session');
+    expect(config.getTelemetryTarget()).toBe(
+      ServerConfig.DEFAULT_TELEMETRY_TARGET,
+    );
+  });
+
+  it('should prioritize --telemetry-target CLI flag over settings', async () => {
+    process.argv = ['node', 'script.js', '--telemetry-target', 'gcp'];
+    const settings: Settings = {
+      telemetry: { target: ServerConfig.DEFAULT_TELEMETRY_TARGET },
+    };
+    const config = await loadCliConfig(settings, [], [], 'test-session');
+    expect(config.getTelemetryTarget()).toBe('gcp');
+  });
+
+  it('should use default target if no target is provided via CLI or settings', async () => {
+    process.argv = ['node', 'script.js'];
+    const settings: Settings = { telemetry: { enabled: true } };
+    const config = await loadCliConfig(settings, [], [], 'test-session');
+    expect(config.getTelemetryTarget()).toBe(
+      ServerConfig.DEFAULT_TELEMETRY_TARGET,
+    );
+  });
+
+  it('should use telemetry log prompts from settings if CLI flag is not present', async () => {
+    process.argv = ['node', 'script.js'];
+    const settings: Settings = { telemetry: { logPrompts: false } };
+    const config = await loadCliConfig(settings, [], [], 'test-session');
+    expect(config.getTelemetryLogPromptsEnabled()).toBe(false);
+  });
+
+  it('should prioritize --telemetry-log-prompts CLI flag (true) over settings (false)', async () => {
+    process.argv = ['node', 'script.js', '--telemetry-log-prompts'];
+    const settings: Settings = { telemetry: { logPrompts: false } };
+    const config = await loadCliConfig(settings, [], [], 'test-session');
+    expect(config.getTelemetryLogPromptsEnabled()).toBe(true);
+  });
+
+  it('should prioritize --no-telemetry-log-prompts CLI flag (false) over settings (true)', async () => {
+    process.argv = ['node', 'script.js', '--no-telemetry-log-prompts'];
+    const settings: Settings = { telemetry: { logPrompts: true } };
+    const config = await loadCliConfig(settings, [], [], 'test-session');
+    expect(config.getTelemetryLogPromptsEnabled()).toBe(false);
+  });
+
+  it('should use default log prompts (true) if no value is provided via CLI or settings', async () => {
+    process.argv = ['node', 'script.js'];
+    const settings: Settings = { telemetry: { enabled: true } };
+    const config = await loadCliConfig(settings, [], [], 'test-session');
+    expect(config.getTelemetryLogPromptsEnabled()).toBe(true);
+  });
 });
 
 describe('API Key Handling', () => {
diff --git a/packages/cli/src/config/config.ts b/packages/cli/src/config/config.ts
index ca7cfa48..b737daa4 100644
--- a/packages/cli/src/config/config.ts
+++ b/packages/cli/src/config/config.ts
@@ -18,6 +18,7 @@ import {
   DEFAULT_GEMINI_MODEL,
   DEFAULT_GEMINI_EMBEDDING_MODEL,
   FileDiscoveryService,
+  TelemetryTarget,
 } from '@gemini-cli/core';
 import { Settings } from './settings.js';
 import { getEffectiveModel } from '../utils/modelCheck.js';
@@ -47,6 +48,9 @@ interface CliArgs {
   yolo: boolean | undefined;
   telemetry: boolean | undefined;
   checkpoint: boolean | undefined;
+  telemetryTarget: string | undefined;
+  telemetryOtlpEndpoint: string | undefined;
+  telemetryLogPrompts: boolean | undefined;
 }
 
 async function parseArguments(): Promise<CliArgs> {
@@ -93,7 +97,24 @@ async function parseArguments(): Promise<CliArgs> {
     })
     .option('telemetry', {
       type: 'boolean',
-      description: 'Enable telemetry?',
+      description:
+        'Enable telemetry? This flag specifically controls if telemetry is sent. Other --telemetry-* flags set specific values but do not enable telemetry on their own.',
+    })
+    .option('telemetry-target', {
+      type: 'string',
+      choices: ['local', 'gcp'],
+      description:
+        'Set the telemetry target (local or gcp). Overrides settings files.',
+    })
+    .option('telemetry-otlp-endpoint', {
+      type: 'string',
+      description:
+        'Set the OTLP endpoint for telemetry. Overrides environment variables and settings files.',
+    })
+    .option('telemetry-log-prompts', {
+      type: 'boolean',
+      description:
+        'Enable or disable logging of user prompts for telemetry. Overrides settings files.',
     })
     .option('checkpoint', {
       alias: 'c',
@@ -190,10 +211,16 @@ export async function loadCliConfig(
     showMemoryUsage:
       argv.show_memory_usage || settings.showMemoryUsage || false,
     accessibility: settings.accessibility,
-    telemetry:
-      argv.telemetry !== undefined
-        ? argv.telemetry
-        : (settings.telemetry ?? false),
+    telemetry: {
+      enabled: argv.telemetry ?? settings.telemetry?.enabled,
+      target: (argv.telemetryTarget ??
+        settings.telemetry?.target) as TelemetryTarget,
+      otlpEndpoint:
+        argv.telemetryOtlpEndpoint ??
+        process.env.OTEL_EXPORTER_OTLP_ENDPOINT ??
+        settings.telemetry?.otlpEndpoint,
+      logPrompts: argv.telemetryLogPrompts ?? settings.telemetry?.logPrompts,
+    },
     // Git-aware file filtering settings
     fileFilteringRespectGitIgnore: settings.fileFiltering?.respectGitIgnore,
     checkpoint: argv.checkpoint,
@@ -203,8 +230,6 @@ export async function loadCliConfig(
       process.env.HTTP_PROXY ||
       process.env.http_proxy,
     cwd: process.cwd(),
-    telemetryOtlpEndpoint:
-      process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? settings.telemetryOtlpEndpoint,
     fileDiscoveryService: fileService,
     bugCommand: settings.bugCommand,
   });
diff --git a/packages/cli/src/config/settings.ts b/packages/cli/src/config/settings.ts
index a0030a05..b17b4c9d 100644
--- a/packages/cli/src/config/settings.ts
+++ b/packages/cli/src/config/settings.ts
@@ -11,6 +11,7 @@ import {
   MCPServerConfig,
   getErrorMessage,
   BugCommandSettings,
+  TelemetrySettings,
 } from '@gemini-cli/core';
 import stripJsonComments from 'strip-json-comments';
 import { DefaultLight } from '../ui/themes/default-light.js';
@@ -41,8 +42,7 @@ export interface Settings {
   showMemoryUsage?: boolean;
   contextFileName?: string | string[];
   accessibility?: AccessibilitySettings;
-  telemetry?: boolean;
-  telemetryOtlpEndpoint?: string;
+  telemetry?: TelemetrySettings;
   preferredEditor?: string;
   bugCommand?: BugCommandSettings;