Gemini CLI integration with Coralogix

Stream token usage, tool calls, API requests, model routing decisions, and session traces from every Gemini CLI session directly into Coralogix. Gemini CLI emits logs, metrics, and traces over OpenTelemetry (OTel) natively—point it at your Coralogix ingress endpoint and data flows automatically.

Supported environments

• OS: macOS, Linux (*nix)
• Shell: bash, zsh

What you need

• A Coralogix account with a Send-Your-Data API key. In Coralogix, navigate to Settings, then API Keys.
• Your Coralogix OTLP endpoint: ingress.:443. Use the domain selector at the top of this page to select your region.
• Gemini CLI installed on your machine (npm install -g @google/gemini-cli).

Set up

Install

1. Install Gemini CLI:

   npm install -g @google/gemini-cli
   

2. Authenticate with Google:

   gemini
   

   Follow the browser OAuth flow when prompted, or set an API key:

   export GEMINI_API_KEY="your-key-from-aistudio.google.com"
   

3. Clone the Coralogix AI agent instrumentation repository and navigate to the Gemini CLI directory:

   git clone https://github.com/coralogix/ai-agent-instrumentation.git
   cd ai-agent-instrumentation/gemini-cli
   

Configure

1. Copy the example environment file:

   cp .env.example .env
   

2. Open .env and set the following values:

   • CX_API_KEY — your Send-Your-Data API key
   • CX_OTLP_ENDPOINT — your OTLP endpoint (ingress.:443)

3. Activate the instrumentation and start Gemini CLI:

   source activate.sh
   gemini
   

   Gemini CLI sessions now stream telemetry to Coralogix.

Make it permanent

To activate instrumentation automatically in every new terminal session, add the following line to ~/.zshrc:

source /path/to/gemini-cli/activate.sh

if [ -f "$HOME/path/to/gemini-cli/.env" ]; then
  set -a; source "$HOME/path/to/gemini-cli/.env"; set +a
fi
export GEMINI_TELEMETRY_ENABLED=true
export GEMINI_TELEMETRY_TARGET=local
export GEMINI_TELEMETRY_OTLP_PROTOCOL=grpc
export GEMINI_TELEMETRY_OTLP_ENDPOINT="${CX_OTLP_ENDPOINT}"
export OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer ${CX_API_KEY},cx-application-name=${CX_APPLICATION_NAME},cx-subsystem-name=${CX_SUBSYSTEM_NAME}"
export OTEL_RESOURCE_ATTRIBUTES="cx.application.name=${CX_APPLICATION_NAME},cx.subsystem.name=${CX_SUBSYSTEM_NAME}"

cp settings.json.example ~/.gemini/settings.json

Validate the integration

After running a Gemini CLI session, confirm that data is flowing:

1. In Coralogix, navigate to Metrics Explorer and search for the metric prefix gemini_cli. Token usage and API request metrics appear within one export interval (~10 seconds).
2. Navigate to Logs and filter by application name gemini-cli. Search for logRecord.body:"CLI configuration loaded." to find the startup config event.
3. Navigate to Explore, then Tracing and filter by service name gemini-cli.

Monitor data in Coralogix

Import the dashboard

1. In Coralogix, navigate to Dashboards, then select New Dashboard, then Import from JSON.
2. Upload coralogix-gemini-cli-dashboard.json from the cloned repository.

Dashboard sections

Configuration examples

Activate prompt logging

activate.sh sets GEMINI_TELEMETRY_LOG_PROMPTS=false by default. Set it to true to include prompt text in log events:

export GEMINI_TELEMETRY_LOG_PROMPTS=true

Data reference

Metrics

All metrics appear in Metrics Explorer under the gemini_cli prefix. Coralogix inserts the OTel unit into the Prometheus metric name on ingestion, so the names differ from the OTel spec names.

OTel metric	Prometheus name in Coralogix	What it tracks
gemini_cli.session.count	gemini_cli_session_count_total	Sessions started
gemini_cli.token.usage	gemini_cli_token_usage_total	Token usage by type and model
gemini_cli.api.request.count	gemini_cli_api_request_count_total	API requests
gemini_cli.api.request.latency	gemini_cli_api_request_latency_ms_{bucket,sum,count,max,min}	API request latency
gemini_cli.tool.call.count	gemini_cli_tool_call_count_total	Tool calls
gemini_cli.tool.call.latency	gemini_cli_tool_call_latency_ms_{bucket,sum,count,max,min}	Tool call latency
gemini_cli.model_routing.latency	gemini_cli_model_routing_latency_ms_{bucket,sum,count,max,min}	Model routing latency
gemini_cli.file.operation.count	gemini_cli_file_operation_count_total	File operations
gemini_cli.lines.changed	gemini_cli_lines_changed_total	Lines changed

Log events

Log events use $d.logRecord.attributes['event.name'] for the event name. Filter in DataPrime:

source logs | filter $d.logRecord.attributes['event.name'] == 'gemini_cli.api_error'

For the full signal reference—event names, attributes, and trace span structure—see the Gemini CLI telemetry documentation.

Advanced configuration

The Gemini CLI settings.json file has no headers field. The @opentelemetry/exporter-*-otlp-grpc packages read the standard OTEL_EXPORTER_OTLP_HEADERS environment variable as gRPC metadata. activate.sh sets this variable with the authorization, cx-application-name, and cx-subsystem-name values.

Permissions

For details, see Roles and permissions.

Troubleshoot

No data appears in Coralogix Cause: environment variables were not exported into the active shell. Fix: run source activate.sh again in the same terminal you use to run gemini, or add the permanent setup to your shell profile.

Metrics appear but traces do not Cause: GEMINI_TELEMETRY_TARGET is not set to local. Fix: confirm you exported GEMINI_TELEMETRY_TARGET=local and GEMINI_TELEMETRY_OTLP_PROTOCOL=grpc.

Prompts appear in telemetry despite LOG_PROMPTS=false Cause: the -p flag passes the prompt as a process argument, which the OTel Node.js SDK captures automatically. Fix: use interactive mode (gemini, then type your prompt) to keep prompt content out of telemetry.