---
title: "Gemini CLI (OTel)"
canonical_url: "https://docs.getdx.com/connectors/gemini-cli-otel/"
md_url: "https://docs.getdx.com/connectors/gemini-cli-otel.md"
last_updated: "2026-07-16"
---

# 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](https://docs.getdx.com/schema/) 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.

```json
{
  "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](https://geminicli.com/docs/cli/telemetry/).

#### Step 4

Start Gemini CLI with the OTel exporter environment variables below:

```sh
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:

```sh
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:

```sql
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](https://docs.getdx.com/schema/) 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.
---

## Sitemap

[Overview of all docs pages](/llms.txt)