# OpenClaw integration with Coralogix

Stream gateway sessions, token usage, costs, model runs, message flow, and webhook activity from OpenClaw directly into Coralogix. OpenClaw emits traces, metrics, and logs over OpenTelemetry (OTel) natively through the `diagnostics-otel` plugin—activate it in your config and data flows automatically.

## Supported environments

- Any environment where OpenClaw gateway runs

## What you need

- A Coralogix account with a **Send-Your-Data [API key](https://coralogix.com/docs/user-guides/account-management/api-keys/send-your-data-api-key/index.md)**. In Coralogix, navigate to **Settings**, then **API Keys**.
- Your Coralogix OTLP endpoint: `ingress.[[DOMAIN_VALUE]]:443`. Use the domain selector at the top of this page to select your region.
- OpenClaw installed and running. See the [OpenClaw getting started guide](https://docs.openclaw.ai/start/getting-started).

## Set up

### Configure

OpenClaw stores all configuration in `~/.openclaw/openclaw.json`. Add the following two blocks to your existing config file—do not replace the file, as it contains your channels, auth, and agent settings.

Open `~/.openclaw/openclaw.json` and merge in:

```json
{
  "plugins": {
    "allow": ["diagnostics-otel"],
    "entries": {
      "diagnostics-otel": { "enabled": true }
    }
  },
  "diagnostics": {
    "enabled": true,
    "otel": {
      "enabled": true,
      "endpoint": "ingress.[[DOMAIN_VALUE]]:443",
      "protocol": "http/protobuf",
      "serviceName": "openclaw-gateway",
      "traces": true,
      "metrics": true,
      "logs": false,
      "flushIntervalMs": 60000,
      "sampleRate": 1.0,
      "headers": {
        "Authorization": "Bearer <your-send-your-data-api-key>",
        "cx-application-name": "openclaw",
        "cx-subsystem-name": "openclaw-gateway"
      }
    }
  }
}
```

If your config already has a `plugins` block, add `"diagnostics-otel"` to the existing `allow` array and `entries` object rather than creating a second block.

Replace the following placeholders:

| Placeholder                     | Value                                                            |
| ------------------------------- | ---------------------------------------------------------------- |
| `<your-send-your-data-api-key>` | Your Send-Your-Data API key from **Settings**, then **API Keys** |
| `cx-application-name`           | Any name to group data under in Coralogix (default: `openclaw`)  |
| `cx-subsystem-name`             | Any subsystem name for routing (default: `openclaw-gateway`)     |

### Restart the gateway

```bash
openclaw gateway restart
```

OpenClaw now streams telemetry to Coralogix.

## Validate the integration

After starting the gateway and running a session, confirm that data is flowing:

1. In Coralogix, navigate to **Metrics Explorer** and search for `openclaw`. Metrics appear within one flush interval (default 60 seconds).
1. Navigate to **Explore**, then **Tracing** and filter by service name `openclaw-gateway`.
1. If you turned on log export, navigate to **Logs** and filter by application name `openclaw` and subsystem `openclaw-gateway`.

## Configuration examples

### Reduce the flush interval during testing

Add to the `otel` block in `~/.openclaw/openclaw.json`:

```json
"flushIntervalMs": 10000
```

### Activate log export

Set `logs` to `true` in the `otel` block. Log export is off by default to keep volume manageable.

```json
"logs": true
```

### Reduce trace sampling

Lower the sampling rate to reduce trace volume in high-throughput environments:

```json
"sampleRate": 0.5
```

This samples 50% of root spans. Child spans follow the root span's sampling decision.

## Data reference

### Metrics

All metrics appear in Metrics Explorer when you search `openclaw`. Filter by `cx_subsystem_name = openclaw-gateway` for the full list.

| OTel metric                  | Prometheus name in Coralogix                          | What it tracks                                                                            |
| ---------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `openclaw.tokens`            | `openclaw_tokens_1_total`                             | Token usage (`openclaw_token`, `openclaw_model`, `openclaw_provider`, `openclaw_channel`) |
| `openclaw.cost.usd`          | `openclaw_cost_usd_1_total`                           | Cost in USD (`openclaw_channel`, `openclaw_provider`, `openclaw_model`)                   |
| `openclaw.run.duration_ms`   | `openclaw_run_duration_ms_{bucket,sum,count,min,max}` | Model run duration                                                                        |
| `openclaw.message.processed` | `openclaw_message_processed_1_total`                  | Messages processed per channel and outcome                                                |
| `openclaw.queue.depth`       | `openclaw_queue_depth_1_{bucket,sum,count,min,max}`   | Command queue depth per lane                                                              |
| `openclaw.session.state`     | `openclaw_session_state_1_total`                      | Session state transitions                                                                 |

### Traces

Trace spans cover every model run, webhook, and message processing event. Filter in **Tracing** by service name `openclaw-gateway`.

| Span                         | Key attributes                                                                                       |
| ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| `openclaw.model.usage`       | `openclaw.tokens.*`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.sessionId` |
| `openclaw.message.processed` | `openclaw.channel`, `openclaw.outcome`, `openclaw.sessionId`                                         |
| `openclaw.webhook.processed` | `openclaw.channel`, `openclaw.webhook`, `openclaw.chatId`                                            |
| `openclaw.webhook.error`     | `openclaw.channel`, `openclaw.webhook`, `openclaw.error`                                             |
| `openclaw.session.stuck`     | `openclaw.state`, `openclaw.ageMs`, `openclaw.sessionId`                                             |

### Logs

Log export is off by default (`logs: false`). When turned on, OpenClaw exports its structured gateway logs as OTel log records over OTLP. Query them in **Logs** filtered by application name `openclaw` and subsystem `openclaw-gateway`.

## Advanced configuration

| Setting                            | Default    | Purpose                                                      |
| ---------------------------------- | ---------- | ------------------------------------------------------------ |
| `diagnostics.otel.flushIntervalMs` | `60000` ms | How often metrics and logs flush                             |
| `diagnostics.otel.sampleRate`      | `1.0`      | Trace sampling rate (0.0 to 1.0, root spans only)            |
| `diagnostics.otel.traces`          | `true`     | Turn trace export on or off                                  |
| `diagnostics.otel.metrics`         | `true`     | Turn metric export on or off                                 |
| `diagnostics.otel.logs`            | `false`    | Turn on OTLP log export (can produce high volume)            |
| `diagnostics.flags`                | —          | Turn on targeted debug logs without raising global log level |

## Permissions

| Resource               | Action                           | Description                                  |
| ---------------------- | -------------------------------- | -------------------------------------------- |
| Send-Your-Data API key | Ingest metrics, logs, and traces | Required to export OTel signals to Coralogix |

For details, see [Roles and permissions](https://coralogix.com/docs/user-guides/account-management/user-management/create-roles-and-permissions/index.md).

## Troubleshoot

**No data appears after restarting the gateway** Cause: the `diagnostics-otel` plugin is not active. Fix: confirm both `plugins.allow` includes `"diagnostics-otel"` and `plugins.entries.diagnostics-otel.enabled` is set to `true` in `~/.openclaw/openclaw.json`.

**Metrics appear but traces do not** Cause: `diagnostics.otel.traces` is set to `false`. Fix: set it to `true` and restart the gateway.

**High log volume after turning on log export** Cause: OpenClaw exports all structured gateway logs when `logs` is `true`. Fix: set `diagnostics.otel.logs` to `false` or reduce the flush interval to batch exports more efficiently.

## Related links

- [Code Agents Observability](https://coralogix.com/docs/user-guides/ai-observability/code-agents/index.md)
- [Coralogix AI Agent Instrumentation — GitHub repository](https://github.com/coralogix/ai-agent-instrumentation/tree/master/openclaw)
- [OpenClaw logging and diagnostics documentation](https://docs.openclaw.ai/logging)
- [OpenClaw diagnostics flags reference](https://docs.openclaw.ai/diagnostics/flags)
- [Metrics Explorer](https://coralogix.com/docs/user-guides/data_exploration/metric-explorer/index.md)
- [DataPrime query language](https://coralogix.com/docs/dataprime/index.md)

## Next steps

Once your integration is set up, explore the [AI Center Overview](https://coralogix.com/docs/user-guides/ai/monitor/index.md) to monitor performance, costs, quality issues, and security across all your AI applications — and to set up [Guardrails](https://coralogix.com/docs/user-guides/ai/guardrails/index.md) for real-time policy enforcement.