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/core/src/config/config.test.ts | 91 +++++++++++++++++++++++++++-- packages/core/src/config/config.ts | 48 +++++++++------ packages/core/src/core/geminiChat.test.ts | 2 +- packages/core/src/core/geminiChat.ts | 2 +- packages/core/src/telemetry/index.ts | 9 +++ packages/core/src/telemetry/loggers.test.ts | 6 +- packages/core/src/telemetry/loggers.ts | 4 +- 7 files changed, 133 insertions(+), 29 deletions(-) (limited to 'packages/core/src') diff --git a/packages/core/src/config/config.test.ts b/packages/core/src/config/config.test.ts index ea555bd4..e8f56f75 100644 --- a/packages/core/src/config/config.test.ts +++ b/packages/core/src/config/config.test.ts @@ -8,6 +8,10 @@ import { describe, it, expect, vi, beforeEach } from 'vitest'; import { Config, ConfigParameters } from './config.js'; import * as path from 'path'; import { setGeminiMdFilename as mockSetGeminiMdFilename } from '../tools/memoryTool.js'; +import { + DEFAULT_TELEMETRY_TARGET, + DEFAULT_OTLP_ENDPOINT, +} from '../telemetry/index.js'; // Mock dependencies that might be called during Config construction or createServerConfig vi.mock('../tools/tool-registry', () => { @@ -38,6 +42,14 @@ vi.mock('../tools/memoryTool', () => ({ GEMINI_CONFIG_DIR: '.gemini', })); +vi.mock('../telemetry/index.js', async (importOriginal) => { + const actual = await importOriginal(); + return { + ...actual, + initializeTelemetry: vi.fn(), + }; +}); + describe('Server Config (config.ts)', () => { const API_KEY = 'server-api-key'; const MODEL = 'gemini-pro'; @@ -47,7 +59,7 @@ describe('Server Config (config.ts)', () => { const QUESTION = 'test question'; const FULL_CONTEXT = false; const USER_MEMORY = 'Test User Memory'; - const TELEMETRY = false; + const TELEMETRY_SETTINGS = { enabled: false }; const EMBEDDING_MODEL = 'gemini-embedding'; const SESSION_ID = 'test-session-id'; const baseParams: ConfigParameters = { @@ -63,7 +75,7 @@ describe('Server Config (config.ts)', () => { question: QUESTION, fullContext: FULL_CONTEXT, userMemory: USER_MEMORY, - telemetry: TELEMETRY, + telemetry: TELEMETRY_SETTINGS, sessionId: SESSION_ID, }; @@ -120,7 +132,7 @@ describe('Server Config (config.ts)', () => { it('Config constructor should set telemetry to true when provided as true', () => { const paramsWithTelemetry: ConfigParameters = { ...baseParams, - telemetry: true, + telemetry: { enabled: true }, }; const config = new Config(paramsWithTelemetry); expect(config.getTelemetryEnabled()).toBe(true); @@ -129,7 +141,7 @@ describe('Server Config (config.ts)', () => { it('Config constructor should set telemetry to false when provided as false', () => { const paramsWithTelemetry: ConfigParameters = { ...baseParams, - telemetry: false, + telemetry: { enabled: false }, }; const config = new Config(paramsWithTelemetry); expect(config.getTelemetryEnabled()).toBe(false); @@ -139,7 +151,7 @@ describe('Server Config (config.ts)', () => { const paramsWithoutTelemetry: ConfigParameters = { ...baseParams }; delete paramsWithoutTelemetry.telemetry; const config = new Config(paramsWithoutTelemetry); - expect(config.getTelemetryEnabled()).toBe(TELEMETRY); + expect(config.getTelemetryEnabled()).toBe(TELEMETRY_SETTINGS.enabled); }); it('should have a getFileService method that returns FileDiscoveryService', () => { @@ -147,4 +159,73 @@ describe('Server Config (config.ts)', () => { const fileService = config.getFileService(); expect(fileService).toBeDefined(); }); + + describe('Telemetry Settings', () => { + it('should return default telemetry target if not provided', () => { + const params: ConfigParameters = { + ...baseParams, + telemetry: { enabled: true }, + }; + const config = new Config(params); + expect(config.getTelemetryTarget()).toBe(DEFAULT_TELEMETRY_TARGET); + }); + + it('should return provided OTLP endpoint', () => { + const endpoint = 'http://custom.otel.collector:4317'; + const params: ConfigParameters = { + ...baseParams, + telemetry: { enabled: true, otlpEndpoint: endpoint }, + }; + const config = new Config(params); + expect(config.getTelemetryOtlpEndpoint()).toBe(endpoint); + }); + + it('should return default OTLP endpoint if not provided', () => { + const params: ConfigParameters = { + ...baseParams, + telemetry: { enabled: true }, + }; + const config = new Config(params); + expect(config.getTelemetryOtlpEndpoint()).toBe(DEFAULT_OTLP_ENDPOINT); + }); + + it('should return provided logPrompts setting', () => { + const params: ConfigParameters = { + ...baseParams, + telemetry: { enabled: true, logPrompts: false }, + }; + const config = new Config(params); + expect(config.getTelemetryLogPromptsEnabled()).toBe(false); + }); + + it('should return default logPrompts setting (true) if not provided', () => { + const params: ConfigParameters = { + ...baseParams, + telemetry: { enabled: true }, + }; + const config = new Config(params); + expect(config.getTelemetryLogPromptsEnabled()).toBe(true); + }); + + it('should return default logPrompts setting (true) if telemetry object is not provided', () => { + const paramsWithoutTelemetry: ConfigParameters = { ...baseParams }; + delete paramsWithoutTelemetry.telemetry; + const config = new Config(paramsWithoutTelemetry); + expect(config.getTelemetryLogPromptsEnabled()).toBe(true); + }); + + it('should return default telemetry target if telemetry object is not provided', () => { + const paramsWithoutTelemetry: ConfigParameters = { ...baseParams }; + delete paramsWithoutTelemetry.telemetry; + const config = new Config(paramsWithoutTelemetry); + expect(config.getTelemetryTarget()).toBe(DEFAULT_TELEMETRY_TARGET); + }); + + it('should return default OTLP endpoint if telemetry object is not provided', () => { + const paramsWithoutTelemetry: ConfigParameters = { ...baseParams }; + delete paramsWithoutTelemetry.telemetry; + const config = new Config(paramsWithoutTelemetry); + expect(config.getTelemetryOtlpEndpoint()).toBe(DEFAULT_OTLP_ENDPOINT); + }); + }); }); diff --git a/packages/core/src/config/config.ts b/packages/core/src/config/config.ts index d841f4b3..891b6302 100644 --- a/packages/core/src/config/config.ts +++ b/packages/core/src/config/config.ts @@ -23,7 +23,12 @@ import { GeminiClient } from '../core/client.js'; import { GEMINI_CONFIG_DIR as GEMINI_DIR } from '../tools/memoryTool.js'; import { FileDiscoveryService } from '../services/fileDiscoveryService.js'; import { GitService } from '../services/gitService.js'; -import { initializeTelemetry } from '../telemetry/index.js'; +import { + initializeTelemetry, + DEFAULT_TELEMETRY_TARGET, + DEFAULT_OTLP_ENDPOINT, + TelemetryTarget, +} from '../telemetry/index.js'; import { DEFAULT_GEMINI_EMBEDDING_MODEL } from './models.js'; export enum ApprovalMode { @@ -40,6 +45,13 @@ export interface BugCommandSettings { urlTemplate: string; } +export interface TelemetrySettings { + enabled?: boolean; + target?: TelemetryTarget; + otlpEndpoint?: string; + logPrompts?: boolean; +} + export class MCPServerConfig { constructor( // For stdio transport @@ -82,9 +94,7 @@ export interface ConfigParameters { showMemoryUsage?: boolean; contextFileName?: string | string[]; accessibility?: AccessibilitySettings; - telemetry?: boolean; - telemetryLogUserPromptsEnabled?: boolean; - telemetryOtlpEndpoint?: string; + telemetry?: TelemetrySettings; fileFilteringRespectGitIgnore?: boolean; checkpoint?: boolean; proxy?: string; @@ -114,9 +124,7 @@ export class Config { private approvalMode: ApprovalMode; private readonly showMemoryUsage: boolean; private readonly accessibility: AccessibilitySettings; - private readonly telemetry: boolean; - private readonly telemetryLogUserPromptsEnabled: boolean; - private readonly telemetryOtlpEndpoint: string; + private readonly telemetrySettings: TelemetrySettings; private readonly geminiClient: GeminiClient; private readonly fileFilteringRespectGitIgnore: boolean; private fileDiscoveryService: FileDiscoveryService | null = null; @@ -147,11 +155,13 @@ export class Config { this.approvalMode = params.approvalMode ?? ApprovalMode.DEFAULT; this.showMemoryUsage = params.showMemoryUsage ?? false; this.accessibility = params.accessibility ?? {}; - this.telemetry = params.telemetry ?? false; - this.telemetryLogUserPromptsEnabled = - params.telemetryLogUserPromptsEnabled ?? true; - this.telemetryOtlpEndpoint = - params.telemetryOtlpEndpoint ?? 'http://localhost:4317'; + this.telemetrySettings = { + enabled: params.telemetry?.enabled ?? false, + target: params.telemetry?.target ?? DEFAULT_TELEMETRY_TARGET, + otlpEndpoint: params.telemetry?.otlpEndpoint ?? DEFAULT_OTLP_ENDPOINT, + logPrompts: params.telemetry?.logPrompts ?? true, + }; + this.fileFilteringRespectGitIgnore = params.fileFilteringRespectGitIgnore ?? true; this.checkpoint = params.checkpoint ?? false; @@ -167,7 +177,7 @@ export class Config { this.toolRegistry = createToolRegistry(this); this.geminiClient = new GeminiClient(this); - if (this.telemetry) { + if (this.telemetrySettings.enabled) { initializeTelemetry(this); } } @@ -272,15 +282,19 @@ export class Config { } getTelemetryEnabled(): boolean { - return this.telemetry; + return this.telemetrySettings.enabled ?? false; } - getTelemetryLogUserPromptsEnabled(): boolean { - return this.telemetryLogUserPromptsEnabled; + getTelemetryLogPromptsEnabled(): boolean { + return this.telemetrySettings.logPrompts ?? true; } getTelemetryOtlpEndpoint(): string { - return this.telemetryOtlpEndpoint; + return this.telemetrySettings.otlpEndpoint ?? DEFAULT_OTLP_ENDPOINT; + } + + getTelemetryTarget(): TelemetryTarget { + return this.telemetrySettings.target ?? DEFAULT_TELEMETRY_TARGET; } getGeminiClient(): GeminiClient { diff --git a/packages/core/src/core/geminiChat.test.ts b/packages/core/src/core/geminiChat.test.ts index 24a7279d..9961103d 100644 --- a/packages/core/src/core/geminiChat.test.ts +++ b/packages/core/src/core/geminiChat.test.ts @@ -26,7 +26,7 @@ const mockModelsModule = { const mockConfig = { getSessionId: () => 'test-session-id', - getTelemetryLogUserPromptsEnabled: () => true, + getTelemetryLogPromptsEnabled: () => true, } as unknown as Config; describe('GeminiChat', () => { diff --git a/packages/core/src/core/geminiChat.ts b/packages/core/src/core/geminiChat.ts index eb740c4a..1268e8c2 100644 --- a/packages/core/src/core/geminiChat.ts +++ b/packages/core/src/core/geminiChat.ts @@ -153,7 +153,7 @@ export class GeminiChat { model: string, ): Promise { const shouldLogUserPrompts = (config: Config): boolean => - config.getTelemetryLogUserPromptsEnabled() ?? false; + config.getTelemetryLogPromptsEnabled() ?? false; const requestText = this._getRequestTextFromContents(contents); logApiRequest(this.config, { diff --git a/packages/core/src/telemetry/index.ts b/packages/core/src/telemetry/index.ts index e8248bf9..32e98144 100644 --- a/packages/core/src/telemetry/index.ts +++ b/packages/core/src/telemetry/index.ts @@ -4,6 +4,15 @@ * SPDX-License-Identifier: Apache-2.0 */ +export enum TelemetryTarget { + GCP = 'gcp', + LOCAL = 'local', +} + +const DEFAULT_TELEMETRY_TARGET = TelemetryTarget.LOCAL; +const DEFAULT_OTLP_ENDPOINT = 'http://localhost:4317'; + +export { DEFAULT_TELEMETRY_TARGET, DEFAULT_OTLP_ENDPOINT }; export { initializeTelemetry, shutdownTelemetry, diff --git a/packages/core/src/telemetry/loggers.test.ts b/packages/core/src/telemetry/loggers.test.ts index 2f909c22..6ec73853 100644 --- a/packages/core/src/telemetry/loggers.test.ts +++ b/packages/core/src/telemetry/loggers.test.ts @@ -60,7 +60,7 @@ describe('loggers', () => { vertexai: true, codeAssist: false, }), - getTelemetryLogUserPromptsEnabled: () => true, + getTelemetryLogPromptsEnabled: () => true, getFileFilteringRespectGitIgnore: () => true, getDebugMode: () => true, getMcpServers: () => ({ @@ -99,7 +99,7 @@ describe('loggers', () => { describe('logUserPrompt', () => { const mockConfig = { getSessionId: () => 'test-session-id', - getTelemetryLogUserPromptsEnabled: () => true, + getTelemetryLogPromptsEnabled: () => true, } as unknown as Config; it('should log a user prompt', () => { @@ -125,7 +125,7 @@ describe('loggers', () => { it('should not log prompt if disabled', () => { const mockConfig = { getSessionId: () => 'test-session-id', - getTelemetryLogUserPromptsEnabled: () => false, + getTelemetryLogPromptsEnabled: () => false, } as unknown as Config; const event = { prompt: 'test-prompt', diff --git a/packages/core/src/telemetry/loggers.ts b/packages/core/src/telemetry/loggers.ts index e788119c..01e83908 100644 --- a/packages/core/src/telemetry/loggers.ts +++ b/packages/core/src/telemetry/loggers.ts @@ -37,7 +37,7 @@ import { } from '@google/genai'; const shouldLogUserPrompts = (config: Config): boolean => - config.getTelemetryLogUserPromptsEnabled() ?? false; + config.getTelemetryLogPromptsEnabled() ?? false; function getCommonAttributes(config: Config): LogAttributes { return { @@ -86,7 +86,7 @@ export function logCliConfiguration(config: Config): void { api_key_enabled: !!generatorConfig.apiKey, vertex_ai_enabled: !!generatorConfig.vertexai, code_assist_enabled: !!generatorConfig.codeAssist, - log_user_prompts_enabled: config.getTelemetryLogUserPromptsEnabled(), + log_user_prompts_enabled: config.getTelemetryLogPromptsEnabled(), file_filtering_respect_git_ignore: config.getFileFilteringRespectGitIgnore(), debug_mode: config.getDebugMode(), -- cgit v1.2.3