> For the complete documentation index, see [llms.txt](https://docs.kosmoslabs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kosmoslabs.ai/product-documentation/connecting-opentelemetry-preview.md).

# Connecting OpenTelemetry (Preview)

***

This guide walks you through sending OpenTelemetry (OTel) data to Kosmos for correlation with your incidents and deployments.

### Overview

Kosmos ingests traces, logs, and metrics via the OpenTelemetry Protocol (OTLP). Once connected, Kosmos correlates observability signals with your other data sources to surface root causes faster.

**Preview Status:** This integration is in Preview. Core functionality is stable, but we're actively refining the experience based on customer feedback.

***

### Prerequisites

* An OpenTelemetry Collector deployed in your environment
* Network access from your collector to `https://ingest.kosmoslabs.ai`
* Admin access to Kosmos to generate an API key

***

### Step 1: Generate Your API Key

1. In Kosmos, navigate to **Settings → Integrations**
2. Find the **OpenTelemetry** card and click **Configure**
3. Click **Generate API Key**
4. Copy both:
   * **OTLP Endpoint (Host):** `https://ingest.kosmoslabs.ai`
   * **Traces:** `https://ingest.kosmoslabs.ai/v1/traces`
   * **Metrics:** `https://ingest.kosmoslabs.ai/v1/metrics`
   * **Logs:** `https://ingest.kosmoslabs.ai/v1/logs`
   * **API Key:** Your unique key (starts with `kos_`)

Keep your API key secure. You can regenerate it at any time, but doing so will invalidate the previous key.

***

### Step 2: Configure Your Collector

Add Kosmos as an exporter in your OpenTelemetry Collector configuration. Select the config for your platform below.

#### Generic OTLP Exporter

Works with any OpenTelemetry Collector distribution.

```yaml
exporters:
  otlphttp/kosmos:
    endpoint: https://ingest.kosmoslabs.ai
    headers:
      X-Kosmos-API-Key: "${KOSMOS_API_KEY}"

service:
  pipelines:
    traces:
      exporters: [otlphttp/kosmos]
    logs:
      exporters: [otlphttp/kosmos]
    metrics:
      exporters: [otlphttp/kosmos]
```

***

#### Grafana Agent / Grafana Alloy

```yaml
traces:
  configs:
    - name: kosmos
      remote_write:
        - endpoint: ingest.kosmoslabs.ai:443
          headers:
            X-Kosmos-API-Key: ${KOSMOS_API_KEY}
          protocol: grpc
          tls:
            insecure: false

logs:
  configs:
    - name: kosmos
      clients:
        - url: https://ingest.kosmoslabs.ai/v1/logs
          headers:
            X-Kosmos-API-Key: ${KOSMOS_API_KEY}
```

***

#### Datadog Agent

Datadog Agent receives OTLP locally, then forward to Kosmos via a sidecar collector.

In your `datadog.yaml`:

```yaml
otlp_config:
  receiver:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
```

Then run a standalone OTel Collector with the generic config above to forward to Kosmos.

***

#### Splunk OpenTelemetry Collector

Add Kosmos as an additional exporter in your Splunk OTel config:

```yaml
exporters:
  otlphttp/kosmos:
    endpoint: https://ingest.kosmoslabs.ai
    headers:
      X-Kosmos-API-Key: "${KOSMOS_API_KEY}"

service:
  pipelines:
    traces:
      exporters: [sapm, otlphttp/kosmos]  # Keep Splunk, add Kosmos
    logs:
      exporters: [splunk_hec, otlphttp/kosmos]
    metrics:
      exporters: [signalfx, otlphttp/kosmos]
```

***

#### Dynatrace

Export from Dynatrace OneAgent via OpenTelemetry. Add to your OTel Collector config:

```yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  otlphttp/kosmos:
    endpoint: https://ingest.kosmoslabs.ai
    headers:
      X-Kosmos-API-Key: "${KOSMOS_API_KEY}"

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp/kosmos]
    logs:
      receivers: [otlp]
      exporters: [otlphttp/kosmos]
```

Configure Dynatrace OneAgent to export OTLP to this collector's endpoint.

***

#### AWS Distro for OpenTelemetry (ADOT)

Add Kosmos exporter to your ADOT config (`otel-config.yaml`):

```yaml
exporters:
  otlphttp/kosmos:
    endpoint: https://ingest.kosmoslabs.ai
    headers:
      X-Kosmos-API-Key: "${KOSMOS_API_KEY}"

service:
  pipelines:
    traces:
      receivers: [otlp, awsxray]
      exporters: [awsxray, otlphttp/kosmos]  # Keep X-Ray, add Kosmos
    metrics:
      receivers: [otlp]
      exporters: [awsemf, otlphttp/kosmos]   # Keep CloudWatch, add Kosmos
```

For ECS/EKS, set the `KOSMOS_API_KEY` environment variable in your task definition.

***

#### Google Cloud Ops Agent

The Ops Agent doesn't natively support custom OTLP exports. Deploy a sidecar OTel Collector:

1. Install the OpenTelemetry Collector alongside Ops Agent
2. Configure Ops Agent to send OTLP to localhost:4317
3. Configure the OTel Collector with the generic config above

Alternatively, use Cloud Run or GKE with the standard OTel Collector.

***

#### Azure Monitor (Application Insights)

Azure Monitor exports via the Azure Monitor OpenTelemetry Distro. Add a sidecar collector:

```yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317

exporters:
  otlphttp/kosmos:
    endpoint: https://ingest.kosmoslabs.ai
    headers:
      X-Kosmos-API-Key: "${KOSMOS_API_KEY}"

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [otlphttp/kosmos]
    logs:
      receivers: [otlp]
      exporters: [otlphttp/kosmos]
```

Configure your application's OpenTelemetry SDK to export to both Azure and this collector.

***

#### New Relic

New Relic supports OTLP natively. Add Kosmos as a secondary destination via a collector:

```yaml
exporters:
  otlphttp/newrelic:
    endpoint: https://otlp.nr-data.net
    headers:
      api-key: "${NEW_RELIC_LICENSE_KEY}"
  
  otlphttp/kosmos:
    endpoint: https://ingest.kosmoslabs.ai
    headers:
      X-Kosmos-API-Key: "${KOSMOS_API_KEY}"

service:
  pipelines:
    traces:
      exporters: [otlphttp/newrelic, otlphttp/kosmos]
    logs:
      exporters: [otlphttp/newrelic, otlphttp/kosmos]
```

***

### Step 3: Test the Connection

1. Deploy your updated collector configuration
2. Return to Kosmos **Settings → Integrations → OpenTelemetry**
3. Click **Test Connection**
4. Verify the status changes:
   * **Pending** → Waiting for first data
   * **Receiving** → Data arriving, processing
   * **Active** → Connection established and healthy

The **Last Data Received** timestamp shows when Kosmos last ingested data from your collector.

***

### Step 4: Verify in the Observability Tab

Once connected, navigate to **Observability** in the left sidebar.

You'll see:

* Connected OTel data sources
* Recent traces, logs, and metrics
* Correlation status with your other signals

The Observability tab shows a **(Preview)** label indicating this feature is still being refined.

***

### What Kosmos Does With Your Data

Kosmos processes OTel data in 15-minute batches to:

1. **Extract error signatures** from traces and logs
2. **Correlate with incidents** in Jira, Salesforce, ServiceNow, etc.
3. **Link to deployments** from GitHub/Bitbucket
4. **Surface in RCAs** as supporting evidence

Raw OTel data is retained for 7 days. Correlation metadata is retained with your other signals.

***

### Troubleshooting

**Connection stays "Pending"**

* Verify your collector can reach `https://ingest.kosmoslabs.ai`
* Check that your API key is correctly set in the `X-Kosmos-API-Key` header
* Confirm your collector is actually sending data (check collector logs)

**"Unauthorized" errors**

* Regenerate your API key in Kosmos
* Ensure the header format is `X-Kosmos-API-Key: kos_xxxxx`

**"Rate limited" errors**

* Default limit is 1,000 requests/minute per customer
* Consider batching more data per request (up to 5MB per payload)
* Contact your Kosmos team if you need higher limits

**Data not appearing in correlations**

* OTel data is processed in 15-minute batches
* Check the Observability tab to confirm data is arriving
* Correlations appear when OTel signals match incidents in your connected systems

***

### Revoking Access

To stop sending data to Kosmos:

1. Remove the Kosmos exporter from your collector configuration
2. In Kosmos, go to **Settings → Integrations → OpenTelemetry**
3. Click **Revoke API Key**

Revoking the API key immediately rejects any further data from that key.

***

### Data Access

For details on what Kosmos ingests and retains, see [Integration Permissions](/product-documentation/integration-permissions.md) and [Integration Limits](/product-documentation/integration-limits.md).

***

### Questions?

Contact your Kosmos team or email <support@kosmoslabs.ai>.

***

**Questions?** Contact <support@kosmoslabs.ai> | [app.kosmoslabs.ai](https://app.kosmoslabs.ai/)

© 2026 Kosmos AI Labs, Inc.