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

# Send OpenTelemetry data to nOps

> Point your AI gateways, agent tools, and services at nOps with a standard OpenTelemetry setup and an API key.

## Overview

nOps accepts telemetry from your own software using [OpenTelemetry](https://opentelemetry.io) (OTel), the open standard most AI gateways, coding agents, and application frameworks already support. Traces, logs, and metrics all work.

This is **push, not pull**. nOps can't fetch this data from your cloud account, because it only exists inside your running software. You configure your software once with the nOps address and an API key. After that it sends data every few seconds on its own until you remove the setting or revoke the key.

Every record nOps receives is tagged with your organization automatically, based on the API key. You don't add an ID yourself, and anything you send that tries to set one is overwritten.

<Note>
  You need nOps administrator access to create API keys, and the **Inform + Operate** plan, the same plan that includes the [Public API](/developers).
</Note>

## What you need

| You need | Value |
| - | - |
| **Endpoint** | `https://api.nops.io/otel` |
| **Protocol** | `http/protobuf` |
| **Auth header** | `Authorization: Bearer <your nOps API key>` |
| **Key permission** | `telemetry:write` |

<Warning>
  Only `http/protobuf` is supported. `http/json` and `grpc` are rejected. If your software can only send gRPC or can't set a custom header, use the [OpenTelemetry Collector](#use-an-opentelemetry-collector) option below.
</Warning>

## Step 1: Create an API key

1. Sign in to [nOps](https://clara.nops.io/dashboard) as an administrator.
2. Open **Settings → Security → API Keys**.
3. Create a key and name it after the sender, for example `ai-gateway-prod` or `claude-code-engineering`.
4. Give it **only** the `telemetry:write` permission.
5. Copy the key. nOps shows it once.

<Tip>
  Create one key per sender. If a key leaks, you can revoke it without cutting off your other senders, and nOps can tell which sender each record came from. A telemetry-only key can do nothing except send data, so the damage from a leak is limited.
</Tip>

## Step 2: Point your software at nOps

Pick the option that matches what you're sending from.

### Any OpenTelemetry SDK or tool

Every official OTel SDK reads the same standard environment variables:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.nops.io/otel
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<your-key>
OTEL_EXPORTER_OTLP_COMPRESSION=gzip
OTEL_SERVICE_NAME=<name-for-this-service>
```

* Set the endpoint **without** `/v1/traces`, `/v1/logs`, or `/v1/metrics`. The SDK adds the right path for each signal.
* The `%20` in the header stands for the space after `Bearer`. The OTel specification requires header values in this variable to be URL-encoded, and some SDKs reject a literal space.
* `OTEL_SERVICE_NAME` is how you'll tell your services apart in the data.

### Claude Code

Claude Code can export usage, cost, and session events over OpenTelemetry. Administrators can turn it on for everyone through Claude Code's managed settings file, in its `env` block:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://api.nops.io/otel",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer%20<your-key>"
  }
}
```

Individual developers can instead set the same values in their shell or in `~/.claude/settings.json`. Claude Code ignores these settings when they come from a repository's `.claude/settings.json`.

<Note>
  By default Claude Code does not include prompt text in telemetry. Leave `OTEL_LOG_USER_PROMPTS` and similar content settings off unless you intentionally want prompts and responses sent to nOps.
</Note>

### AI gateways

Most AI gateways, including LiteLLM, Portkey, and Kong, have an OpenTelemetry option in their config file or admin page. It asks for the same three things: an endpoint, a protocol, and an authorization header. Use the values from [What you need](#what-you-need). The exact field names differ by gateway, so check your gateway's documentation for its OTel or OTLP settings.

### Use an OpenTelemetry Collector

Use a Collector when your software only speaks gRPC, can't set custom headers, or already sends to a Collector. Run the standard OpenTelemetry Collector next to your software. It accepts telemetry on its normal ports and forwards it to nOps:

```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}}
receivers:
  otlp:
    protocols:
      grpc: { endpoint: 0.0.0.0:4317 }
      http: { endpoint: 0.0.0.0:4318 }

processors:
  batch: {}

exporters:
  otlphttp/nops:
    endpoint: https://api.nops.io/otel
    compression: gzip
    headers:
      Authorization: "Bearer ${env:NOPS_TELEMETRY_KEY}"

service:
  pipelines:
    traces:  { receivers: [otlp], processors: [batch], exporters: [otlphttp/nops] }
    metrics: { receivers: [otlp], processors: [batch], exporters: [otlphttp/nops] }
    logs:    { receivers: [otlp], processors: [batch], exporters: [otlphttp/nops] }
```

Already sending to another tool such as Datadog or Grafana? Keep your existing exporter and add `otlphttp/nops` beside it in each pipeline. The Collector sends to both.

## Step 3: Check that it works

Send a few test traces with `telemetrygen`, part of the OpenTelemetry Collector contrib project:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
telemetrygen traces --traces 5 --otlp-http \
  --otlp-endpoint api.nops.io:443 \
  --otlp-http-url-path /otel/v1/traces \
  --otlp-header 'Authorization="Bearer <your-key>"'
```

A successful request returns HTTP `200`. If you'd rather test with your real software, run it briefly and watch its logs for export errors.

## Limits

| Limit | Value |
| - | - |
| Request size | 4 MB per request. Use gzip and keep batches modest |
| Rate | Requests are limited per organization. OTel exporters retry automatically when they hit the limit |
| Format | Protobuf only |

## Troubleshooting

| Symptom | Likely cause |
| - | - |
| `401` | The key is wrong, revoked, or the header is malformed. If `Bearer%20<key>` fails in your tool, try a literal space instead |
| `403` | The key is missing the `telemetry:write` permission, or your organization isn't on the **Inform + Operate** plan |
| `404` | The endpoint includes `/v1/traces` twice, or points at the wrong host. The base should be `https://api.nops.io/otel` |
| `413` | A request is too large. Lower your exporter's batch size |
| `415` | Your software is sending JSON. Set the protocol to `http/protobuf` |
| `429` | You're sending faster than your limit allows. Exporters retry on their own, so brief bursts are fine. If it persists, contact support |
| `503` | nOps is temporarily unable to accept data. Exporters retry automatically |
| No requests at all | Your software is using gRPC (port 4317). Switch to `http/protobuf`, or use a Collector |
| `200` but no data | The exporter for that signal is turned off, for example `OTEL_TRACES_EXPORTER=none`, or your software doesn't emit that signal |

## FAQs

<AccordionGroup>
  <Accordion title="Can I send to nOps and another tool at the same time?">
    Yes. Use an OpenTelemetry Collector with more than one exporter, as shown above.
  </Accordion>

  <Accordion title="Can I set my own organization ID in the data?">
    No. nOps assigns your organization from the API key and removes any attribute you send whose name starts with `nops_` or `nops.`. Other attributes pass through unchanged.
  </Accordion>

  <Accordion title="What happens if I revoke a key?">
    Sending stops within a couple of minutes. Data already received stays in your organization's records.
  </Accordion>

  <Accordion title="Should I send prompt or response text?">
    Only if you need it. AI gateway and agent traces can include the full text of prompts and responses. Check your exporter's settings and remove sensitive content you don't want stored.
  </Accordion>

  <Accordion title="Does it work with the development environment?">
    If you've been given access to a nOps test environment, use the endpoint you were given in place of `https://api.nops.io/otel`, together with a key created in that environment.
  </Accordion>
</AccordionGroup>

## Related

* [Authentication](/developers/authentication)
* [Rate limits](/developers/rate-limits)
* [AI overview](/ai/introduction)


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