> ## Documentation Index
> Fetch the complete documentation index at: https://docs.weaveos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenTelemetry Collector

> Use an OpenTelemetry Collector to send AI tool telemetry to Weave and other destinations simultaneously

If your organization already uses an OpenTelemetry Collector, or wants to send AI tool telemetry to multiple backends at once, you can route data through a collector and fan it out to Weave alongside your own observability stack.

This works with any AI tool that exports OTLP telemetry (Claude Code, Cline, [Hermes & OpenClaw](/integrations/ingest-api), etc.).
Gemini CLI is an exception for a standard OTLP/HTTP receiver: it uses one exact endpoint for logs
and metrics. Do not replace its generated endpoint with the collector base URL until both signals
have a verified demultiplexing path; see [Gemini CLI](/ai-tools/gemini-cli).

## How it works

Instead of pointing each AI tool directly at Weave's ingest endpoint, you point them at a local or shared OpenTelemetry Collector. The collector receives the telemetry and exports it to multiple destinations: Weave, Datadog, Grafana, a local file, or anything else with an OTLP-compatible receiver.

```
AI tool → OpenTelemetry Collector → Weave
                                  → Your observability platform
                                  → Local file / other destinations
```

## Setup

<Steps>
  <Step title="Create a telemetry API key in Weave">
    Go to **Data** → **Claude Code** → **Connect**, answer **How do you pay for Claude Code?**, click **Set up telemetry**, and create a new API key. For Cline, go to **Data** → **Cline** → **Connect** and click **Create API key**. Save the key. You'll need it for the collector config.
  </Step>

  <Step title="Create a collector config file">
    Create a file called `otel-collector-config.yaml`:

    ```yaml theme={null}
    receivers:
      otlp:
        protocols:
          http:
            endpoint: "0.0.0.0:4318"

    processors:
      batch:

    exporters:
      # Send to Weave
      otlphttp/weave:
        endpoint: "https://app.workweave.ai/ingest"
        headers:
          x-weave-token: "YOUR_WEAVE_API_KEY"

      # Example: also send to another OTLP-compatible backend
      # otlphttp/other:
      #   endpoint: "https://otel.example.com"
      #   headers:
      #     Authorization: "Bearer YOUR_OTHER_TOKEN"

      # Example: log to console for debugging
      # debug:
      #   verbosity: detailed

    service:
      pipelines:
        metrics:
          receivers: [otlp]
          processors: [batch]
          exporters: [otlphttp/weave]
        logs:
          receivers: [otlp]
          processors: [batch]
          exporters: [otlphttp/weave]
        # Copilot and Pi send traces; without this pipeline the collector rejects them
        traces:
          receivers: [otlp]
          processors: [batch]
          exporters: [otlphttp/weave]
    ```

    Replace `YOUR_WEAVE_API_KEY` with the API key from step 1. To send to additional destinations, uncomment and configure extra exporters, then add them to the relevant pipelines.

    The standard `batch` processor groups telemetry by batch size and timeout; it does not cap the number of distinct `weave.token` resource attributes or the encoded request size. Weave accepts mixed-token batches above 32 keys, with limits of 6 MiB per decompressed request and 4,096 resource groups. Keep exports under both limits and configure a durable sending queue for retryable failures. A 413 response means the request must be split or reduced before retrying.
  </Step>

  <Step title="Run the collector">
    Run the official OpenTelemetry Collector Docker image:

    ```bash theme={null}
    docker run -d \
      --name otel-collector \
      -p 4318:4318 \
      -v $(pwd)/otel-collector-config.yaml:/etc/otelcol/config.yaml \
      otel/opentelemetry-collector:latest
    ```
  </Step>

  <Step title="Point your AI tools at the collector">
    Configure each tool to send telemetry to `http://localhost:4318` instead of directly to Weave. Tools that take an exact OTLP logs URL, such as Hermes, use `http://localhost:4318/v1/logs`.

    **Claude Code** - update `managed-settings.json`:

    ```json theme={null}
    {
      "env": {
        "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4318"
      }
    }
    ```

    **Cline** - set environment variables:

    ```bash theme={null}
    export CLINE_OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:4318"
    ```

    <Note>
      Claude Code and Cursor collector mode send the OTLP payload without the
      Weave auth header; configure `x-weave-token` on the collector's Weave
      exporter. Keep the `weave.token` resource attribute through redaction so
      Weave can route the records. Cline can't set resource attributes, so it
      sends its token to your collector as an `x-weave-token` header; configure
      the collector's Weave exporter to forward the matching token.
    </Note>
  </Step>

  <Step title="Verify connection">
    Run an AI tool session and check that activity appears in Weave. The plugin
    install ping proves that the configured collector accepted a request; it
    does not prove that a custom processor or exporter forwarded it. If data
    isn't flowing, add the `debug` exporter and inspect the collector's exporter
    status before debugging the plugin.
  </Step>
</Steps>

## Example: fan out to multiple backends

To send telemetry to both Weave and another platform, add exporters and list them in the pipeline:

```yaml theme={null}
exporters:
  otlphttp/weave:
    endpoint: "https://app.workweave.ai/ingest"
    headers:
      x-weave-token: "YOUR_WEAVE_API_KEY"

  otlphttp/grafana:
    endpoint: "https://otlp-gateway.grafana.net/otlp"
    headers:
      Authorization: "Basic YOUR_GRAFANA_TOKEN"

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/weave, otlphttp/grafana]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/weave, otlphttp/grafana]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp/weave, otlphttp/grafana]
```

## Running in production

For shared or long-running environments, consider:

* **Docker Compose** - add the collector as a service alongside your existing stack
* **Kubernetes** - deploy as a DaemonSet or sidecar using the [OpenTelemetry Collector Helm chart](https://opentelemetry.io/docs/kubernetes/helm/collector/)
* **Secrets management** - store API keys in environment variables or a secrets manager rather than in the config file:

```yaml theme={null}
exporters:
  otlphttp/weave:
    endpoint: "https://app.workweave.ai/ingest"
    headers:
      x-weave-token: "${env:WEAVE_API_KEY}"
```

## Cost tracking

A collector only forwards what each tool emits, so cost tracking is unchanged by routing through it. If a tool's telemetry includes a cost or token signal (for example, Claude Code's `cost_usd` or Gemini CLI token usage), that estimated cost flows to Weave through the collector exactly as it would on a direct connection. For **actual billed cost**, you still connect the provider's admin/analytics API key on the tool's Data page — that path is separate from OTLP telemetry and doesn't go through the collector. See [AI tool costs](/metrics/ai-tool-costs) for which tools report real vs estimated cost.

## Troubleshooting

<AccordionGroup>
  <Accordion icon="plug" title="No data reaching Weave">
    1. Add the `debug` exporter to your pipeline to confirm the collector is receiving data
    2. Check that the Weave API key is valid
    3. Verify the collector can reach `https://app.workweave.ai` (no firewall or proxy blocking)
    4. Ensure the AI tool is pointed at the correct collector port (default `4318` for HTTP)
  </Accordion>

  <Accordion icon="rotate" title="Data reaching Weave but not other exporters">
    1. Verify the exporter name is listed in the pipeline's `exporters` array
    2. Check credentials for each destination
    3. Review collector logs for export errors (`docker logs otel-collector`)
  </Accordion>

  <Accordion icon="server" title="Collector won't start">
    1. Validate your YAML syntax
    2. Check that port `4318` isn't already in use
    3. Ensure the config file is mounted correctly in Docker
    4. Run with `debug` verbosity for detailed startup logs
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.