View all connectors

Gemini CLI (OTel)

By integrating Gemini CLI with DX via OpenTelemetry (OTel), you can import per-user daily usage metrics including session counts, lines of code added and removed, file operations, tool call decisions, and per-model token consumption.

Use the schema explorer to see the Gemini CLI tables DX imports.

How it works

Gemini CLI supports OpenTelemetry Protocol (OTLP) export for usage telemetry. When configured, Gemini CLI sends OTLP metrics directly to DX.

DX accepts Gemini CLI metrics at a dedicated OTLP HTTP endpoint and processes them into Gemini daily usage tables. The connector imports:

  • Sessions - Gemini CLI session counts.
  • Code changes - Lines of code added and removed.
  • File operations - File create, read, and update counts.
  • Tool decisions - Accepted and rejected tool calls.
  • Token usage - Input, output, cache read, thought, and tool tokens by model.
  • Approval mode - The active approval mode reported by Gemini CLI.

DX processes delta metrics. Set Gemini CLI to export metrics with delta temporality because cumulative metrics are ignored.

Prerequisites

To connect Gemini CLI to DX, you need:

  • DX admin access to create a data connector.
  • Gemini CLI installed on each developer machine where telemetry should be collected.
  • A Gemini CLI version that supports OTel metric export.
  • Permission to edit the Gemini CLI settings file (~/.gemini/settings.json) and set environment variables or managed shell configuration for Gemini CLI users.
  • Outbound HTTPS access from developer machines to your DX API host.

Setup instructions

Follow the steps below to connect Gemini CLI to DX via OTel.

Step 1

Navigate to the connections page in DX and select + Connection in the top right.

Select Gemini CLI (OTel) as the connector type and save the connection. DX will generate a secure ingest token for the connection.

Step 2

Copy the ingest token from the connection settings page. The token is separate from your DX API token and is used only by the Gemini CLI OTel endpoint.

Step 3

Configure Gemini CLI telemetry in its settings file. Add the telemetry block below to your user settings (~/.gemini/settings.json) or workspace settings (.gemini/settings.json). Set otlpEndpoint to your DX API host with /api/gemini appended. Gemini CLI appends the metrics path when exporting metrics.

{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "useCollector": true,
    "otlpEndpoint": "https://<your-dx-host>/api/gemini",
    "otlpProtocol": "http"
  }
}

The connection settings page in DX generates this exact telemetry block for your host — copy it directly from there.

For the full list of Gemini CLI telemetry settings, see the Gemini CLI telemetry docs.

Step 4

Start Gemini CLI with the OTel exporter environment variables below:

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <GEMINI_CLI_OTEL_INGEST_TOKEN>"
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE="delta"
export OTEL_RESOURCE_ATTRIBUTES="user.email=<USER_EMAIL>"
export OTEL_TRACES_EXPORTER=none
export OTEL_LOGS_EXPORTER=none
export OTEL_METRICS_EXPORTER=otlp
gemini

Set OTEL_RESOURCE_ATTRIBUTES separately for each developer. DX uses user.email to link Gemini CLI activity to DX users. If user.email is missing or invalid, DX skips the metric data because it cannot attribute the activity to a user.

You can also include user.name for display names:

export OTEL_RESOURCE_ATTRIBUTES="user.email=<USER_EMAIL>,user.name=First%20Last"

Note: White space is not allowed in OTEL_RESOURCE_ATTRIBUTES. Replace spaces with %20.

Ingest endpoint

DX exposes the following OTLP HTTP endpoint for receiving Gemini CLI telemetry. Signal-specific paths are appended automatically by the OTel exporter.

Endpoint Signal
POST /api/gemini/v1/metrics Metrics (sessions, LOC, file operations, tool decisions, tokens, approval mode)

Requests are authenticated with a Bearer token in the Authorization header. DX accepts JSON OTLP metric payloads for this endpoint.

Gemini CLI logs and traces are not imported by this connector. Keep OTEL_LOGS_EXPORTER and OTEL_TRACES_EXPORTER set to none when starting Gemini CLI.

Verify data in DX

After Gemini CLI sends telemetry, wait for the OTel processing job to run. DX processes pending Gemini CLI OTel events every 10 minutes.

Go to DX → Data Studio and run the following query:

SELECT
    gu.email,
    COUNT(gdum.id) AS metric_count,
    MIN(gdum.date) AS earliest_date,
    MAX(gdum.date) AS latest_date,
    COUNT(CASE WHEN gdum.is_active = true THEN 1 END) AS active_days
FROM gemini_daily_user_metrics gdum
JOIN gemini_users gu ON gu.id = gdum.user_id
GROUP BY gu.email
HAVING COUNT(gdum.id) > 0
ORDER BY metric_count DESC, gu.email

If the connector is working, the query returns Gemini CLI users with daily activity. Use the schema explorer to inspect the full gemini_ table family.

Troubleshooting

No data appearing in DX after setup

  • Confirm the Gemini CLI process was started with OTEL_METRICS_EXPORTER=otlp and OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta.
  • Confirm OTEL_EXPORTER_OTLP_HEADERS contains the ingest token from the Gemini CLI (OTel) connection settings page.
  • Confirm OTEL_RESOURCE_ATTRIBUTES includes a valid user.email value for the developer running Gemini CLI.
  • Confirm outbound HTTPS traffic to your DX API host is allowed.
  • Confirm the telemetry block in ~/.gemini/settings.json has enabled: true, the DX otlpEndpoint, and otlpProtocol: "http". Environment variables (GEMINI_TELEMETRY_*) override the settings file, so make sure none are set to conflicting values.

Data is attributed to the wrong user

Check the user.email value in OTEL_RESOURCE_ATTRIBUTES on the affected machine. If you distribute this configuration centrally, template the email value per developer instead of using a shared static value.