| # Observability with OpenTelemetry |
|
|
| Observability is the key to turning experimental AI into reliable software. |
| Gemini CLI provides built-in support for OpenTelemetry, transforming every agent |
| interaction into a rich stream of logs, metrics, and traces. This three-pillar |
| approach gives you the high-fidelity visibility needed to understand agent |
| behavior, optimize performance, and ensure reliability across your entire |
| workflow. |
|
|
| Whether you are debugging a complex tool interaction locally or monitoring |
| enterprise-wide usage in the cloud, Gemini CLI's observability system provides |
| the actionable intelligence needed to move from "black box" AI to predictable, |
| high-performance systems. |
|
|
| ## OpenTelemetry integration |
|
|
| Gemini CLI integrates with **[OpenTelemetry]**, a vendor-neutral, |
| industry-standard observability framework. |
|
|
| The observability system provides: |
|
|
| - Universal compatibility: Export to any OpenTelemetry backend (Google Cloud, |
| Jaeger, Prometheus, Datadog, etc.). |
| - Standardized data: Use consistent formats and collection methods across your |
| toolchain. |
| - Future-proof integration: Connect with existing and future observability |
| infrastructure. |
| - No vendor lock-in: Switch between backends without changing your |
| instrumentation. |
|
|
| [OpenTelemetry]: https://opentelemetry.io/ |
|
|
| ## Configuration |
|
|
| You control telemetry behavior through the `.gemini/settings.json` file. |
| Environment variables can override these settings. |
|
|
| | Setting | Environment Variable | Description | Values | Default | |
| | -------------- | --------------------------------- | --------------------------------------------------- | ----------------- | ----------------------- | |
| | `enabled` | `GEMINI_TELEMETRY_ENABLED` | Enable or disable telemetry | `true`/`false` | `false` | |
| | `traces` | `GEMINI_TELEMETRY_TRACES_ENABLED` | Enable detailed attribute tracing | `true`/`false` | `false` | |
| | `target` | `GEMINI_TELEMETRY_TARGET` | Where to send telemetry data | `"gcp"`/`"local"` | `"local"` | |
| | `otlpEndpoint` | `GEMINI_TELEMETRY_OTLP_ENDPOINT` | OTLP collector endpoint | URL string | `http://localhost:4317` | |
| | `otlpProtocol` | `GEMINI_TELEMETRY_OTLP_PROTOCOL` | OTLP transport protocol | `"grpc"`/`"http"` | `"grpc"` | |
| | `outfile` | `GEMINI_TELEMETRY_OUTFILE` | Save telemetry to file (overrides `otlpEndpoint`) | file path | - | |
| | `logPrompts` | `GEMINI_TELEMETRY_LOG_PROMPTS` | Include prompts in telemetry logs | `true`/`false` | `true` | |
| | `useCollector` | `GEMINI_TELEMETRY_USE_COLLECTOR` | Use external OTLP collector (advanced) | `true`/`false` | `false` | |
| | `useCliAuth` | `GEMINI_TELEMETRY_USE_CLI_AUTH` | Use CLI credentials for telemetry (GCP target only) | `true`/`false` | `false` | |
| | - | `GEMINI_CLI_SURFACE` | Optional custom label for traffic reporting | string | - | |
|
|
| **Note on boolean environment variables:** For boolean settings like `enabled`, |
| setting the environment variable to `true` or `1` enables the feature. |
|
|
| For detailed configuration information, see the |
| [Configuration guide](../reference/configuration.md). |
|
|
| ## Google Cloud telemetry |
|
|
| You can export telemetry data directly to Google Cloud Trace, Cloud Monitoring, |
| and Cloud Logging. |
|
|
| ### Prerequisites |
|
|
| You must complete several setup steps before enabling Google Cloud telemetry. |
|
|
| 1. Set your Google Cloud project ID: |
|
|
| - To send telemetry to a separate project: |
|
|
| **macOS/Linux** |
| |
| ```bash |
| export OTLP_GOOGLE_CLOUD_PROJECT="your-telemetry-project-id" |
| ``` |
| |
| **Windows (PowerShell)** |
| |
| ```powershell |
| $env:OTLP_GOOGLE_CLOUD_PROJECT="your-telemetry-project-id" |
| ``` |
| |
| - To send telemetry to the same project as inference: |
|
|
| **macOS/Linux** |
| |
| ```bash |
| export GOOGLE_CLOUD_PROJECT="your-project-id" |
| ``` |
| |
| **Windows (PowerShell)** |
| |
| ```powershell |
| $env:GOOGLE_CLOUD_PROJECT="your-project-id" |
| ``` |
| |
| 2. Authenticate with Google Cloud using one of these methods: |
|
|
| - **Method A: Application Default Credentials (ADC)**: Use this method for |
| service accounts or standard `gcloud` authentication. |
| |
| - For user accounts: |
| ```bash |
| gcloud auth application-default login |
| ``` |
| - For service accounts: |
| |
| **macOS/Linux** |
| |
| ```bash |
| export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account.json" |
| ``` |
| |
| **Windows (PowerShell)** |
| |
| ```powershell |
| $env:GOOGLE_APPLICATION_CREDENTIALS="C:\path\to\your\service-account.json" |
| ``` |
| |
| * **Method B: CLI Auth** (Direct export only): Simplest method for local |
| users. Gemini CLI uses the same OAuth credentials you used for login. To |
| enable this, set `useCliAuth: true` in your `.gemini/settings.json`: |
| |
| ```json |
| { |
| "telemetry": { |
| "enabled": true, |
| "target": "gcp", |
| "useCliAuth": true |
| } |
| } |
| ``` |
| |
| <!-- prettier-ignore --> |
| > [!NOTE] |
| > This setting requires **Direct export** (in-process exporters) |
| > and cannot be used when `useCollector` is `true`. If both are enabled, |
| > telemetry will be disabled. |
|
|
| 3. Ensure your account or service account has these IAM roles: |
|
|
| - Cloud Trace Agent |
| - Monitoring Metric Writer |
| - Logs Writer |
|
|
| 4. Enable the required Google Cloud APIs: |
| ```bash |
| gcloud services enable \ |
| cloudtrace.googleapis.com \ |
| monitoring.googleapis.com \ |
| logging.googleapis.com \ |
| --project="$OTLP_GOOGLE_CLOUD_PROJECT" |
| ``` |
| |
| ### Direct export |
|
|
| We recommend using direct export to send telemetry directly to Google Cloud |
| services. |
|
|
| 1. Enable telemetry in `.gemini/settings.json`: |
| ```json |
| { |
| "telemetry": { |
| "enabled": true, |
| "target": "gcp" |
| } |
| } |
| ``` |
| 2. Run Gemini CLI and send prompts. |
| 3. View logs, metrics, and traces in the Google Cloud Console. See |
| [View Google Cloud telemetry](#view-google-cloud-telemetry) for details. |
| |
| ### View Google Cloud telemetry |
|
|
| After you enable telemetry and run Gemini CLI, you can view your data in the |
| Google Cloud Console. |
|
|
| - **Logs:** [Logs Explorer](https://console.cloud.google.com/logs/) |
| - **Metrics:** |
| [Metrics Explorer](https://console.cloud.google.com/monitoring/metrics-explorer) |
| - **Traces:** [Trace Explorer](https://console.cloud.google.com/traces/list) |
|
|
| For detailed information on how to use these tools, see the following official |
| Google Cloud documentation: |
|
|
| - [View and analyze logs with Logs Explorer](https://cloud.google.com/logging/docs/view/logs-explorer-interface) |
| - [Create charts with Metrics Explorer](https://cloud.google.com/monitoring/charts/metrics-explorer) |
| - [Find and explore traces](https://cloud.google.com/trace/docs/finding-traces) |
|
|
| #### Monitoring dashboards |
|
|
| Gemini CLI provides a pre-configured |
| [Google Cloud Monitoring](https://cloud.google.com/monitoring) dashboard to |
| visualize your telemetry. |
|
|
| Find this dashboard under **Google Cloud Monitoring Dashboard Templates** as |
| "**Gemini CLI Monitoring**". |
|
|
|  |
|
|
|  |
|
|
|  |
|
|
| To learn more, see |
| [Instant insights: Gemini CLI’s pre-configured monitoring dashboards](https://cloud.google.com/blog/topics/developers-practitioners/instant-insights-gemini-clis-new-pre-configured-monitoring-dashboards/). |
|
|
| ## Local telemetry |
|
|
| You can capture telemetry data locally for development and debugging. We |
| recommend using file-based output for local development. |
|
|
| 1. Enable telemetry in `.gemini/settings.json`: |
| ```json |
| { |
| "telemetry": { |
| "enabled": true, |
| "target": "local", |
| "outfile": ".gemini/telemetry.log" |
| } |
| } |
| ``` |
| 2. Run Gemini CLI and send prompts. |
| 3. View logs and metrics in `.gemini/telemetry.log`. |
| |
| For advanced local telemetry setups (such as Jaeger or Genkit), see the |
| [Local development guide](../local-development.md#viewing-traces). |
|
|
| ## Client identification |
|
|
| Gemini CLI includes identifiers in its `User-Agent` header to help you |
| differentiate and report on API traffic from different environments (for |
| example, identifying calls from Gemini Code Assist versus a standard terminal). |
|
|
| ### Automatic identification |
|
|
| Most integrated environments are identified automatically without additional |
| configuration. The identifier is included as a prefix to the `User-Agent` and as |
| a "surface" tag in the parenthetical metadata. |
|
|
| | Environment | User-Agent Prefix | Surface Tag | |
| | :---------------------------------- | :--------------------------- | :---------- | |
| | **Gemini Code Assist (Agent Mode)** | `GeminiCLI-a2a-server` | `vscode` | |
| | **Zed (via ACP)** | `GeminiCLI-acp-zed` | `zed` | |
| | **XCode (via ACP)** | `GeminiCLI-acp-xcode` | `xcode` | |
| | **IntelliJ IDEA (via ACP)** | `GeminiCLI-acp-intellijidea` | `jetbrains` | |
| | **Standard Terminal** | `GeminiCLI` | `terminal` | |
|
|
| **Example User-Agent:** |
| `GeminiCLI-a2a-server/0.34.0/gemini-pro (linux; x64; vscode)` |
|
|
| ### Custom identification |
|
|
| You can provide a custom identifier for your own scripts or automation by |
| setting the `GEMINI_CLI_SURFACE` environment variable. This is useful for |
| tracking specific internal tools or distribution channels in your GCP logs. |
|
|
| **macOS/Linux** |
|
|
| ```bash |
| export GEMINI_CLI_SURFACE="my-custom-tool" |
| ``` |
|
|
| **Windows (PowerShell)** |
|
|
| ```powershell |
| $env:GEMINI_CLI_SURFACE="my-custom-tool" |
| ``` |
|
|
| When set, the value appears at the end of the `User-Agent` parenthetical: |
| `GeminiCLI/0.34.0/gemini-pro (linux; x64; my-custom-tool)` |
|
|
| ## Logs, metrics, and traces |
|
|
| This section describes the structure of logs, metrics, and traces generated by |
| Gemini CLI. |
|
|
| Gemini CLI includes `session.id`, `installation.id`, `active_approval_mode`, and |
| `user.email` (when authenticated) as common attributes on all data. |
|
|
| ### Logs |
|
|
| Logs provide timestamped records of specific events. Gemini CLI logs events |
| across several categories. |
|
|
| #### Sessions |
|
|
| Session logs capture startup configuration and prompt submissions. |
|
|
| ##### `gemini_cli.config` |
| |
| Emitted at startup with the CLI configuration. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `model` (string) |
| - `embedding_model` (string) |
| - `sandbox_enabled` (boolean) |
| - `core_tools_enabled` (string) |
| - `approval_mode` (string) |
| - `api_key_enabled` (boolean) |
| - `vertex_ai_enabled` (boolean) |
| - `log_user_prompts_enabled` (boolean) |
| - `file_filtering_respect_git_ignore` (boolean) |
| - `debug_mode` (boolean) |
| - `mcp_servers` (string) |
| - `mcp_servers_count` (int) |
| - `mcp_tools` (string) |
| - `mcp_tools_count` (int) |
| - `output_format` (string) |
| - `extensions` (string) |
| - `extension_ids` (string) |
| - `extensions_count` (int) |
| - `auth_type` (string) |
| - `worktree_active` (boolean) |
| - `github_workflow_name` (string, optional) |
| - `github_repository_hash` (string, optional) |
| - `github_event_name` (string, optional) |
| - `github_pr_number` (string, optional) |
| - `github_issue_number` (string, optional) |
| - `github_custom_tracking_id` (string, optional) |
|
|
| </details> |
|
|
| ##### `gemini_cli.user_prompt` |
|
|
| Emitted when you submit a prompt. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `prompt_length` (int) |
| - `prompt_id` (string) |
| - `prompt` (string; excluded if `telemetry.logPrompts` is `false`) |
| - `auth_type` (string) |
|
|
| </details> |
|
|
| #### Approval mode |
|
|
| These logs track changes to and usage of different approval modes. |
|
|
| ##### Lifecycle |
|
|
| ##### `approval_mode_switch` |
|
|
| Logs when you change the approval mode. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `from_mode` (string) |
| - `to_mode` (string) |
|
|
| </details> |
|
|
| ##### `approval_mode_duration` |
|
|
| Records time spent in an approval mode. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `mode` (string) |
| - `duration_ms` (int) |
|
|
| </details> |
|
|
| ##### Execution |
|
|
| ##### `plan_execution` |
| |
| Logs when you execute a plan and switch from plan mode to active execution. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `approval_mode` (string) |
|
|
| </details> |
|
|
| #### Tools |
|
|
| Tool logs capture executions, truncation, and edit behavior. |
|
|
| ##### `gemini_cli.tool_call` |
|
|
| Emitted for each tool (function) call. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `function_name` (string) |
| - `function_args` (string) |
| - `duration_ms` (int) |
| - `success` (boolean) |
| - `decision` (string: "accept", "reject", "auto_accept", or "modify") |
| - `error` (string, optional) |
| - `error_type` (string, optional) |
| - `prompt_id` (string) |
| - `tool_type` (string: "native" or "mcp") |
| - `mcp_server_name` (string, optional) |
| - `extension_name` (string, optional) |
| - `extension_id` (string, optional) |
| - `content_length` (int, optional) |
| - `start_time` (number, optional) |
| - `end_time` (number, optional) |
| - `metadata` (object, optional), which may include: |
| - `model_added_lines` (number) |
| - `model_removed_lines` (number) |
| - `user_added_lines` (number) |
| - `user_removed_lines` (number) |
| - `ask_user` (object) |
|
|
| </details> |
|
|
| ##### `gemini_cli.tool_output_truncated` |
| |
| Logs when tool output is truncated. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `tool_name` (string) |
| - `original_content_length` (int) |
| - `truncated_content_length` (int) |
| - `threshold` (int) |
| - `lines` (int) |
| - `prompt_id` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.edit_strategy` |
|
|
| Records the chosen edit strategy. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `strategy` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.edit_correction` |
|
|
| Records the result of an edit correction. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `correction` (string: "success" or "failure") |
|
|
| </details> |
|
|
| ##### `gen_ai.client.inference.operation.details` |
| |
| Provides detailed GenAI operation data aligned with OpenTelemetry conventions. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `gen_ai.request.model` (string) |
| - `gen_ai.provider.name` (string) |
| - `gen_ai.operation.name` (string) |
| - `gen_ai.input.messages` (json string) |
| - `gen_ai.output.messages` (json string) |
| - `gen_ai.response.finish_reasons` (array of strings) |
| - `gen_ai.usage.input_tokens` (int) |
| - `gen_ai.usage.output_tokens` (int) |
| - `gen_ai.request.temperature` (float) |
| - `gen_ai.request.top_p` (float) |
| - `gen_ai.request.top_k` (int) |
| - `gen_ai.request.max_tokens` (int) |
| - `gen_ai.system_instructions` (json string) |
| - `server.address` (string) |
| - `server.port` (int) |
|
|
| </details> |
|
|
| #### Files |
|
|
| File logs track operations performed by tools. |
|
|
| ##### `gemini_cli.file_operation` |
|
|
| Emitted for each file creation, read, or update. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `tool_name` (string) |
| - `operation` (string: "create", "read", or "update") |
| - `lines` (int, optional) |
| - `mimetype` (string, optional) |
| - `extension` (string, optional) |
| - `programming_language` (string, optional) |
|
|
| </details> |
|
|
| #### API |
|
|
| API logs capture requests, responses, and errors from Gemini API. |
|
|
| ##### `gemini_cli.api_request` |
|
|
| Request sent to Gemini API. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `model` (string) |
| - `prompt_id` (string) |
| - `role` (string: "user", "model", or "system") |
| - `request_text` (string, optional) |
|
|
| </details> |
|
|
| ##### `gemini_cli.api_response` |
|
|
| Response received from Gemini API. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `model` (string) |
| - `status_code` (int or string) |
| - `duration_ms` (int) |
| - `input_token_count` (int) |
| - `output_token_count` (int) |
| - `cached_content_token_count` (int) |
| - `thoughts_token_count` (int) |
| - `tool_token_count` (int) |
| - `total_token_count` (int) |
| - `prompt_id` (string) |
| - `auth_type` (string) |
| - `finish_reasons` (array of strings) |
| - `response_text` (string, optional) |
|
|
| </details> |
|
|
| ##### `gemini_cli.api_error` |
|
|
| Logs when an API request fails. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `error.message` (string) |
| - `model_name` (string) |
| - `duration` (int) |
| - `prompt_id` (string) |
| - `auth_type` (string) |
| - `error_type` (string, optional) |
| - `status_code` (int or string, optional) |
| - `role` (string, optional) |
|
|
| </details> |
|
|
| ##### `gemini_cli.malformed_json_response` |
| |
| Logs when a JSON response cannot be parsed. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `model` (string) |
| |
| </details> |
| |
| #### Model routing |
| |
| These logs track how Gemini CLI selects and routes requests to models. |
| |
| ##### `gemini_cli.slash_command` |
| |
| Logs slash command execution. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `command` (string) |
| - `subcommand` (string, optional) |
| - `status` (string: "success" or "error") |
| |
| </details> |
| |
| ##### `gemini_cli.slash_command.model` |
| |
| Logs model selection via slash command. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `model_name` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.model_routing` |
|
|
| Records model router decisions and reasoning. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `decision_model` (string) |
| - `decision_source` (string) |
| - `routing_latency_ms` (int) |
| - `reasoning` (string, optional) |
| - `failed` (boolean) |
| - `error_message` (string, optional) |
| - `approval_mode` (string) |
|
|
| </details> |
|
|
| #### Chat and streaming |
|
|
| These logs track chat context compression and streaming chunk errors. |
|
|
| ##### `gemini_cli.chat_compression` |
|
|
| Logs chat context compression events. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `tokens_before` (int) |
| - `tokens_after` (int) |
|
|
| </details> |
|
|
| ##### `gemini_cli.chat.invalid_chunk` |
|
|
| Logs invalid chunks received in a stream. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `error_message` (string, optional) |
|
|
| </details> |
|
|
| ##### `gemini_cli.chat.content_retry` |
|
|
| Logs retries due to content errors. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `attempt_number` (int) |
| - `error_type` (string) |
| - `retry_delay_ms` (int) |
| - `model` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.chat.content_retry_failure` |
| |
| Logs when all content retries fail. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `total_attempts` (int) |
| - `final_error_type` (string) |
| - `total_duration_ms` (int, optional) |
| - `model` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.conversation_finished` |
|
|
| Logs when a conversation session ends. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `approvalMode` (string) |
| - `turnCount` (int) |
|
|
| </details> |
|
|
| #### Resilience |
|
|
| Resilience logs record fallback mechanisms and recovery attempts. |
|
|
| ##### `gemini_cli.flash_fallback` |
|
|
| Logs switch to a flash model fallback. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `auth_type` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.ripgrep_fallback` |
|
|
| Logs fallback to standard grep. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `error` (string, optional) |
|
|
| </details> |
|
|
| ##### `gemini_cli.web_fetch_fallback_attempt` |
|
|
| Logs web-fetch fallback attempts. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `reason` (string: "private_ip" or "primary_failed") |
|
|
| </details> |
|
|
| ##### `gemini_cli.agent.recovery_attempt` |
|
|
| Logs attempts to recover from agent errors. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `agent_name` (string) |
| - `attempt_number` (int) |
| - `success` (boolean) |
| - `error_type` (string, optional) |
|
|
| </details> |
|
|
| #### Extensions |
|
|
| Extension logs track lifecycle events and settings changes. |
|
|
| ##### `gemini_cli.extension_install` |
|
|
| Logs when you install an extension. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `extension_name` (string) |
| - `extension_version` (string) |
| - `extension_source` (string) |
| - `status` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.extension_uninstall` |
|
|
| Logs when you uninstall an extension. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `extension_name` (string) |
| - `status` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.extension_enable` |
|
|
| Logs when you enable an extension. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `extension_name` (string) |
| - `setting_scope` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.extension_disable` |
|
|
| Logs when you disable an extension. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `extension_name` (string) |
| - `setting_scope` (string) |
|
|
| </details> |
|
|
| #### Agent runs |
|
|
| Agent logs track the lifecycle of agent executions. |
|
|
| ##### `gemini_cli.agent.start` |
| |
| Logs when an agent run begins. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `agent_id` (string) |
| - `agent_name` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.agent.finish` |
| |
| Logs when an agent run completes. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `agent_id` (string) |
| - `agent_name` (string) |
| - `duration_ms` (int) |
| - `turn_count` (int) |
| - `terminate_reason` (string) |
|
|
| </details> |
|
|
| #### IDE |
|
|
| IDE logs capture connectivity events for the IDE companion. |
|
|
| ##### `gemini_cli.ide_connection` |
|
|
| Logs IDE companion connections. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `connection_type` (string) |
|
|
| </details> |
|
|
| #### UI |
|
|
| UI logs track terminal rendering issues. |
|
|
| ##### `kitty_sequence_overflow` |
|
|
| Logs terminal control sequence overflows. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `sequence_length` (int) |
| - `truncated_sequence` (string) |
|
|
| </details> |
|
|
| #### Miscellaneous |
|
|
| ##### `gemini_cli.rewind` |
| |
| Logs when the conversation state is rewound. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `outcome` (string) |
| |
| </details> |
| |
| ##### `gemini_cli.conseca.verdict` |
|
|
| Logs security verdicts from ConSeca. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `verdict` (string) |
| - `decision` (string: "accept", "reject", or "modify") |
| - `reason` (string, optional) |
| - `tool_name` (string, optional) |
|
|
| </details> |
|
|
| ##### `gemini_cli.hook_call` |
|
|
| Logs execution of lifecycle hooks. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `hook_name` (string) |
| - `hook_type` (string) |
| - `duration_ms` (int) |
| - `success` (boolean) |
|
|
| </details> |
|
|
| ##### `gemini_cli.tool_output_masking` |
| |
| Logs when tool output is masked for privacy. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `tokens_before` (int) |
| - `tokens_after` (int) |
| - `masked_count` (int) |
| - `total_prunable_tokens` (int) |
|
|
| </details> |
|
|
| ##### `gemini_cli.keychain.availability` |
| |
| Logs keychain availability checks. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `available` (boolean) |
| |
| ##### `gemini_cli.startup_stats` |
| |
| Logs detailed startup performance statistics. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `phases` (json array of startup phases) |
| - `os_platform` (string) |
| - `os_release` (string) |
| - `is_docker` (boolean) |
|
|
| </details> |
|
|
| </details> |
|
|
| ### Metrics |
|
|
| Metrics provide numerical measurements of behavior over time. |
|
|
| #### Custom metrics |
|
|
| Gemini CLI exports several custom metrics. |
|
|
| ##### Sessions |
|
|
| ##### `gemini_cli.session.count` |
| |
| Incremented once per CLI startup. |
| |
| ##### Onboarding |
| |
| Tracks onboarding flow from authentication to the user |
| |
| - `gemini_cli.onboarding.start` (Counter, Int): Incremented when the |
| authentication flow begins. |
|
|
| - `gemini_cli.onboarding.success` (Counter, Int): Incremented when the user |
| onboarding flow completes successfully. |
| <details> |
| <summary>Attributes (Success)</summary> |
|
|
| - `user_tier` (string) |
|
|
| ##### Tools |
|
|
| ##### `gemini_cli.tool.call.count` |
| |
| Counts tool calls. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `function_name` (string) |
| - `success` (boolean) |
| - `decision` (string: "accept", "reject", "modify", or "auto_accept") |
| - `tool_type` (string: "mcp" or "native") |
|
|
| </details> |
|
|
| ##### `gemini_cli.tool.call.latency` |
| |
| Measures tool call latency (in ms). |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `function_name` (string) |
|
|
| </details> |
|
|
| ##### API |
|
|
| ##### `gemini_cli.api.request.count` |
| |
| Counts all API requests. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `model` (string) |
| - `status_code` (int or string) |
| - `error_type` (string, optional) |
|
|
| </details> |
|
|
| ##### `gemini_cli.api.request.latency` |
| |
| Measures API request latency (in ms). |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `model` (string) |
| |
| </details> |
| |
| ##### Token usage |
| |
| ##### `gemini_cli.token.usage` |
|
|
| Counts input, output, thought, cache, and tool tokens. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `model` (string) |
| - `type` (string: "input", "output", "thought", "cache", or "tool") |
|
|
| </details> |
|
|
| ##### Files |
|
|
| ##### `gemini_cli.file.operation.count` |
| |
| Counts file operations. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `operation` (string: "create", "read", or "update") |
| - `lines` (int, optional) |
| - `mimetype` (string, optional) |
| - `extension` (string, optional) |
| - `programming_language` (string, optional) |
|
|
| </details> |
|
|
| ##### `gemini_cli.lines.changed` |
| |
| Counts added or removed lines. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `function_name` (string, optional) |
| - `type` (string: "added" or "removed") |
|
|
| </details> |
|
|
| ##### Chat and streaming |
|
|
| ##### `gemini_cli.chat_compression` |
|
|
| Counts compression operations. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `tokens_before` (int) |
| - `tokens_after` (int) |
|
|
| </details> |
|
|
| ##### `gemini_cli.chat.invalid_chunk.count` |
|
|
| Counts invalid stream chunks. |
|
|
| ##### `gemini_cli.chat.content_retry.count` |
|
|
| Counts content error retries. |
|
|
| ##### `gemini_cli.chat.content_retry_failure.count` |
| |
| Counts requests where all retries failed. |
| |
| ##### Model routing |
| |
| ##### `gemini_cli.slash_command.model.call_count` |
|
|
| Counts model selections. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `slash_command.model.model_name` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.model_routing.latency` |
|
|
| Measures routing decision latency. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `routing.decision_model` (string) |
| - `routing.decision_source` (string) |
| - `routing.approval_mode` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.model_routing.failure.count` |
|
|
| Counts routing failures. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `routing.decision_source` (string) |
| - `routing.error_message` (string) |
| - `routing.approval_mode` (string) |
|
|
| </details> |
|
|
| ##### Agent runs |
|
|
| ##### `gemini_cli.agent.run.count` |
| |
| Counts agent runs. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `agent_name` (string) |
| - `terminate_reason` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.agent.duration` |
| |
| Measures agent run duration. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `agent_name` (string) |
|
|
| </details> |
|
|
| ##### `gemini_cli.agent.turns` |
| |
| Counts turns per agent run. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `agent_name` (string) |
|
|
| </details> |
|
|
| ##### Approval mode |
|
|
| ##### `gemini_cli.plan.execution.count` |
| |
| Counts plan executions. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `approval_mode` (string) |
|
|
| </details> |
|
|
| ##### UI |
|
|
| ##### `gemini_cli.ui.flicker.count` |
| |
| Counts terminal flicker events. |
| |
| ##### Performance |
| |
| Gemini CLI provides detailed performance metrics for advanced monitoring. |
| |
| ##### `gemini_cli.startup.duration` |
|
|
| Measures startup time by phase. |
|
|
| <details> |
| <summary>Attributes</summary> |
|
|
| - `phase` (string) |
| - `details` (map, optional) |
|
|
| </details> |
|
|
| ##### `gemini_cli.memory.usage` |
| |
| Measures heap and RSS memory. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `memory_type` (string: "heap_used", "heap_total", "external", "rss") |
| - `component` (string, optional) |
|
|
| </details> |
|
|
| ##### `gemini_cli.cpu.usage` |
| |
| Measures CPU usage percentage. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `component` (string, optional) |
| |
| </details> |
| |
| ##### `gemini_cli.tool.queue.depth` |
|
|
| Measures tool execution queue depth. |
|
|
| ##### `gemini_cli.tool.execution.breakdown` |
| |
| Breaks down tool time by phase. |
| |
| <details> |
| <summary>Attributes</summary> |
| |
| - `function_name` (string) |
| - `phase` (string: "validation", "preparation", "execution", |
| "result_processing") |
| |
| </details> |
| |
| #### GenAI semantic convention |
| |
| These metrics follow standard [OpenTelemetry GenAI semantic conventions]. |
| |
| - `gen_ai.client.token.usage`: Counts tokens used per operation. |
| - `gen_ai.client.operation.duration`: Measures operation duration in seconds. |
|
|
| [OpenTelemetry GenAI semantic conventions]: |
| https://github.com/open-telemetry/semantic-conventions/blob/main/docs/gen-ai/gen-ai-metrics.md |
|
|
| ### Traces |
|
|
| Traces provide an "under-the-hood" view of agent and backend operations. Use |
| traces to debug tool interactions and optimize performance. |
|
|
| <!-- prettier-ignore --> |
| > [!NOTE] |
| > Detailed trace attributes (like full prompts and tool outputs) are disabled by default |
| > to minimize overhead. You must explicitly set `telemetry.traces` to `true` (or set |
| > `GEMINI_TELEMETRY_TRACES_ENABLED=true`) to capture them. |
| |
| Every trace captures rich metadata via standard span attributes. |
| |
| <details open> |
| <summary>Standard span attributes</summary> |
| |
| - `gen_ai.operation.name`: High-level operation (for example, `tool_call`, |
| `llm_call`, `user_prompt`, `system_prompt`, `agent_call`, or |
| `schedule_tool_calls`). |
| - `gen_ai.agent.name`: Set to `gemini-cli`. |
| - `gen_ai.agent.description`: The service agent description. |
| - `gen_ai.input.messages`: Input data or metadata. |
| - `gen_ai.output.messages`: Output data or results. |
| - `gen_ai.request.model`: Request model name. |
| - `gen_ai.response.model`: Response model name. |
| - `gen_ai.prompt.name`: The prompt name. |
| - `gen_ai.tool.name`: Executed tool name. |
| - `gen_ai.tool.call_id`: Unique ID for the tool call. |
| - `gen_ai.tool.description`: Tool description. |
| - `gen_ai.tool.definitions`: Tool definitions in JSON format. |
| - `gen_ai.usage.input_tokens`: Number of input tokens. |
| - `gen_ai.usage.output_tokens`: Number of output tokens. |
| - `gen_ai.system_instructions`: System instructions in JSON format. |
| - `gen_ai.conversation.id`: The CLI session ID. |
|
|
| </details> |
|
|
| For more details on semantic conventions for events, see the |
| [OpenTelemetry documentation](https://github.com/open-telemetry/semantic-conventions/blob/8b4f210f43136e57c1f6f47292eb6d38e3bf30bb/docs/gen-ai/gen-ai-events.md). |
|
|
