# 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:** `https://ingest.kosmoslabs.ai/api/v1/otel`
   * **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/api/v1/otel
    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/api/v1/otel/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/api/v1/otel
    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/api/v1/otel
    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/api/v1/otel
    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/api/v1/otel
    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/api/v1/otel
    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](/integration-permissions.md) and [Integration Limits](/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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kosmoslabs.ai/connecting-opentelemetry-preview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.