gemini-cli

Observability with OpenTelemetry

Learn how to enable and setup OpenTelemetry for Gemini CLI.

Key Benefits

OpenTelemetry Integration

Built on OpenTelemetry — the vendor-neutral, industry-standard observability framework — Gemini CLI’s observability system provides:

Configuration

All telemetry behavior is controlled through your .gemini/settings.json file. These settings can be overridden by environment variables or CLI flags.

Setting Environment Variable CLI Flag Description Values Default
enabled GEMINI_TELEMETRY_ENABLED --telemetry / --no-telemetry Enable or disable telemetry true/false false
target GEMINI_TELEMETRY_TARGET --telemetry-target <local\|gcp> Where to send telemetry data "gcp"/"local" "local"
otlpEndpoint GEMINI_TELEMETRY_OTLP_ENDPOINT --telemetry-otlp-endpoint <URL> OTLP collector endpoint URL string http://localhost:4317
otlpProtocol GEMINI_TELEMETRY_OTLP_PROTOCOL --telemetry-otlp-protocol <grpc\|http> OTLP transport protocol "grpc"/"http" "grpc"
outfile GEMINI_TELEMETRY_OUTFILE --telemetry-outfile <path> Save telemetry to file (overrides otlpEndpoint) file path -
logPrompts GEMINI_TELEMETRY_LOG_PROMPTS --telemetry-log-prompts / --no-telemetry-log-prompts Include prompts in telemetry logs true/false true
useCollector GEMINI_TELEMETRY_USE_COLLECTOR - Use external OTLP collector (advanced) true/false false

Note on boolean environment variables: For the boolean settings (enabled, logPrompts, useCollector), setting the corresponding environment variable to true or 1 will enable the feature. Any other value will disable it.

For detailed information about all configuration options, see the Configuration Guide.

Google Cloud Telemetry

Prerequisites

Before using either method below, complete these steps:

  1. Set your Google Cloud project ID:
    • For telemetry in a separate project from inference: 
      export OTLP_GOOGLE_CLOUD_PROJECT="your-telemetry-project-id"
    • For telemetry in the same project as inference: 
      export GOOGLE_CLOUD_PROJECT="your-project-id"
  2. Authenticate with Google Cloud:
    • If using a user account: 
      gcloud auth application-default login
    • If using a service account: 
      export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account.json"
  3. Make sure your account or service account has these IAM roles:
    • Cloud Trace Agent
    • Monitoring Metric Writer
    • Logs Writer
  4. Enable the required Google Cloud APIs (if not already enabled): 
    gcloud services enable \
  cloudtrace.googleapis.com \
  monitoring.googleapis.com \
  logging.googleapis.com \
  --project="$OTLP_GOOGLE_CLOUD_PROJECT"

Sends telemetry directly to Google Cloud services. No collector needed.

  1. Enable telemetry in your .gemini/settings.json: 
    {
  "telemetry": {
    "enabled": true,
    "target": "gcp"
  }
}
  2. Run Gemini CLI and send prompts.
  3. View logs and metrics:
    • Open the Google Cloud Console in your browser after sending prompts:
      • Logs: https://console.cloud.google.com/logs/
      • Metrics: https://console.cloud.google.com/monitoring/metrics-explorer
      • Traces: https://console.cloud.google.com/traces/list

Collector-Based Export (Advanced)

For custom processing, filtering, or routing, use an OpenTelemetry collector to forward data to Google Cloud.

  1. Configure your .gemini/settings.json: 
    {
  "telemetry": {
    "enabled": true,
    "target": "gcp",
    "useCollector": true
  }
}
  2. Run the automation script: 
    npm run telemetry -- --target=gcp

    This will:

    • Start a local OTEL collector that forwards to Google Cloud
    • Configure your workspace
    • Provide links to view traces, metrics, and logs in Google Cloud Console
    • Save collector logs to ~/.gemini/tmp/<projectHash>/otel/collector-gcp.log
    • Stop collector on exit (e.g. Ctrl+C)
  3. Run Gemini CLI and send prompts.
  4. View logs and metrics:
    • Open the Google Cloud Console in your browser after sending prompts:
      • Logs: https://console.cloud.google.com/logs/
      • Metrics: https://console.cloud.google.com/monitoring/metrics-explorer
      • Traces: https://console.cloud.google.com/traces/list
    • Open ~/.gemini/tmp/<projectHash>/otel/collector-gcp.log to view local collector logs.

Local Telemetry

For local development and debugging, you can capture telemetry data locally:

  1. Enable telemetry in your .gemini/settings.json: 
    {
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "",
    "outfile": ".gemini/telemetry.log"
  }
}
  2. Run Gemini CLI and send prompts.
  3. View logs and metrics in the specified file (e.g., .gemini/telemetry.log).

Collector-Based Export (Advanced)

  1. Run the automation script: 
    npm run telemetry -- --target=local

    This will:

    • Download and start Jaeger and OTEL collector
    • Configure your workspace for local telemetry
    • Provide a Jaeger UI at http://localhost:16686
    • Save logs/metrics to ~/.gemini/tmp/<projectHash>/otel/collector.log
    • Stop collector on exit (e.g. Ctrl+C)
  2. Run Gemini CLI and send prompts.
  3. View traces at http://localhost:16686 and logs/metrics in the collector log file.

Logs and Metrics

The following section describes the structure of logs and metrics generated for Gemini CLI.

Logs

Logs are timestamped records of specific events. The following events are logged for Gemini CLI:

Metrics

Metrics are numerical measurements of behavior over time.

Custom

GenAI Semantic Convention

The following metrics comply with OpenTelemetry GenAI semantic conventions for standardized observability across GenAI applications:

This site is open source. Improve this page.