> 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)

Step-by-step guide to connecting OpenTelemetry observability data

***

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 2.25 MB per payload, measured after decompression), or enabling gzip compression in your collector's OTLP exporter to reduce bandwidth
* 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.