OpenTelemetry Integration & Telemetry Control Flag #762
Conversation
This commit introduces a `--telemetry` flag to the CLI, allowing users to explicitly enable or disable telemetry. Key changes: - Added a `--telemetry` boolean flag to `packages/cli/src/config/config.ts`. - The flag defaults to `false` if not provided. - If the flag is not used, the value from `settings.telemetry` is used. - If neither the flag nor a setting is present, telemetry defaults to `false`. - Updated `packages/cli/src/config/settings.ts` to include `telemetry` in the `Settings` interface. - Updated `packages/core/src/config/config.ts` to include `telemetry` in `ConfigParameters` and the `Config` class, defaulting to `false`. - Added comprehensive tests in both `packages/cli` and `packages/core` to cover the new flag and its interaction with settings. This provides users with clear control over telemetry data collection.
This commit introduces OpenTelemetry (OTEL) instrumentation for key events within the Gemini CLI and adds comprehensive documentation for telemetry setup and export. Key changes include: - Instrumentation: - User prompts, tool calls (including duration and success/error status), and API interactions (requests, responses, errors with duration and status) are now instrumented using OpenTelemetry. - Telemetry data is collected when the telemetry feature is enabled. - Relevant OpenTelemetry packages (`@opentelemetry/api`, `@opentelemetry/sdk-node`, OTLP exporters) have been added as dependencies. - Documentation (`docs/core/telemetry.md`): - Added a new guide explaining telemetry concepts, collected events, and how to run a local OTEL collector. - Detailed instructions for exporting telemetry data to Google Cloud, including example collector configuration and Docker commands for running the collector with GCP authentication. - Covers configuration for traces, metrics (with `gemini_code` prefix), and logs. - Core Logic Updates: - `Config` now initializes telemetry and provides the OTLP endpoint. - `GeminiClient` and `CoreToolScheduler` have been updated to log telemetry events. - New `packages/core/src/telemetry/` directory contains the telemetry initialization and logging functions.
Refactors the `telemetry.ts` module into multiple, more focused files within the `packages/core/src/telemetry/` directory. This change improves organization and maintainability by separating concerns such as type definitions, constants, metrics, logging, and SDK management.
Moves the logging logic for API requests, responses, and errors into private methods (_logApiRequest, _logApiResponse, _logApiError) within the GeminiClient class. This improves code organization and reusability of the telemetry calls.
packages/core/src/config/config.ts
Outdated
There was a problem hiding this comment.
For my own knowledge is 4317 the default port for some otel tool? Would it be possible to align this setting with what Claude code has for their setup?
There was a problem hiding this comment.
For my own knowledge is 4317 the default port for some otel tool?
Yes, it's the default port for OTEL exporter endpoint:
- gRPC: "http://localhost:4317"
- HTTP: "http://localhost:4318"
https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/#otel_exporter_otlp_endpoint
There was a problem hiding this comment.
Would it be possible to align this setting with what Claude code has for their setup?
Yes, it's the default port in Claude code too - https://docs.anthropic.com/en/docs/claude-code/monitoring-usage#quick-start
packages/core/src/core/client.ts
Outdated
There was a problem hiding this comment.
Is this a follow up?
| const allToolCallsCompleteHandler: AllToolCallsCompleteHandler = ( | ||
| completedToolCalls, | ||
| ) => { | ||
| completedToolCalls.forEach((call) => { |
There was a problem hiding this comment.
May want to consider having this at the core tool scheduler layer so that interactiveToolScheduelr (headless mode) gets this as well
| model, | ||
| contents, | ||
| }); | ||
| inputTokenCount = totalTokens || 0; |
There was a problem hiding this comment.
I think the 3 buckets of tokens we care about (hopefully all acheivable) is input tokens, output tokens and cached input tokens
|
|
||
| const otlpEndpoint = config.getTelemetryOtlpEndpoint(); | ||
| const grpcParsedEndpoint = parseGrpcEndpoint(otlpEndpoint); | ||
| const useOtlp = !!grpcParsedEndpoint; |
There was a problem hiding this comment.
This contradicts the docs above. The user would need to explicitly set the endpoint to an invalid format to actually get the console versions.
5 participants
This change introduces OpenTelemetry (OTel) instrumentation for key events (user prompts, tool calls, API interactions) and adds a --telemetry flag for explicit user control over data collection.
--telemetryFlag: Users can enable/disable telemetry via CLI flag, with settings support.docs/core/telemetry.mdguide details setup, collected data, and export to any backend (local and cloud).packages/core/src/telemetry/directory for instrumentation logic;Config,GeminiClient, andCoreToolSchedulerupdated to log events.#750