From 53753f0455458dda4055f42ca9caf3aa898bc3c4 Mon Sep 17 00:00:00 2001 From: Jerop Kipruto Date: Sun, 15 Jun 2025 00:47:32 -0400 Subject: Add telemetry command and refactor telemetry settings (#1060) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit #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 ` - `--telemetry-otlp-endpoint ` - `--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. ``` --- packages/cli/src/config/config.test.ts | 97 ++++++++++++++++++++++++++++++++-- packages/cli/src/config/config.ts | 39 +++++++++++--- packages/cli/src/config/settings.ts | 4 +- 3 files changed, 127 insertions(+), 13 deletions(-) (limited to 'packages/cli/src') 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 { @@ -93,7 +97,24 @@ async function parseArguments(): Promise { }) .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; -- cgit v1.2.3