# Collect data using OpenTelemetry

{% hint style="info" %}
See the changelog of the **OpenTelemetry** Listener type [here](/listeners/opentelemetry-listener.md).
{% endhint %}

## Overview

Onum supports integration with the [OpenTelemetry](https://opentelemetry.io/).

OpenTelemetry is a collection of APIs, SDKs, and tools. Use it to instrument, generate, collect, and export telemetry data (metrics, logs, and traces) to help you analyze your software’s performance and behavior.

## Prerequisites

[Contact Onum](/support/support.md) to get the cert information needed for TLS communication, which will be needed on the Listener setup.

## Open Telemetry Setup

In order to begin sending data, you must firstly Implement OpenTelemetry SDK and Instrumentation. 

Then, you'll need to **configure the OpenTelemetry Collector.**

The Collector is configured via a YAML file (`config.yaml`), which defines a processing pipeline with three main component types:

* Receivers: Define how the Collector accepts incoming telemetry. The most common is `otlp` (OpenTelemetry Protocol), which listens for data from your applications over gRPC (port 4317) or HTTP (port 4318).
* Processors: Define how data is modified, filtered, or enriched (e.g., `batch` for efficient export, `memory_limiter` to prevent crashes, or processors to add metadata).
* Exporters: Define where the Collector sends the data. 

A minimal configuration to receive OTLP data and export it to an external backend looks like this:

```yaml
receivers:
  otlp:
    protocols:
      grpc:
      http:

processors:
  batch:

exporters:
  otlp/example:  # OTLP exporter to send to your backend service
    endpoint: "YOUR_BACKEND_ADDRESS:4317" # Replace with your observability tool's OTLP endpoint
    insecure: false  # Use true for HTTP, false for HTTPS/TLS

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/example]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/example]
```

Start the Collector, pointing it to your configuration file.

```bash
otelcol --config=config.yaml
```

Set an environment variable in your application's host environment:

* `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318` (as you will be running the collector locally over HTTP).

The application will now generate telemetry and send it to Onum.

## Onum Setup

{% stepper %}
{% step %}
Log in to your Onum tenant and click **Listeners > New listener**.
{% endstep %}

{% step %}
Double-click the **Open Telemetry** Listener.
{% endstep %}

{% step %}
Enter a **Name** for the new Listener. Optionally, add a **Description** and some **Tags** to identify the Listener.
{% endstep %}

{% step %}
Configure your OTLP/gRPC or OTLP/HTTP endpoint. Set the desired type as *true* to enable more options. 

Set **Allow gRPC protocol** as *true* if you want to configure the **gRPC port**<mark style="color:red;">**\***</mark> to establish the connection with the protocol.
{% endstep %}

{% step %}
Set **Allow HTTP protocol** as *true* if you want to configure OTLP/HTTP:

* **HTTP Port**<mark style="color:red;">**\***</mark> to establish the connection with the protocol.
* The **traces path** for the endpoint URL e.g. `http://collector:port/v1/traces`
* The **metrics path** for the endpoint URL e.g. `http://collector:port/v1/metrics`
* The **logs path** for the endpoint URL e.g. `http://collector:port/v1/logs`
  {% endstep %}

{% step %}
Choose your required authentication method in the **Authentication Type** parameter (Choose **None** if you don't need any authentication method).

Enter your **Username** and **Password** for **basic** authentication, or enter your **Token Name** and choose the required **Bearer** **Token** for authentication.
{% endstep %}

{% step %}
The credentials are saved in Onum as Secrets. In the authentication form, click **New secret** to create a new one:

* Give the token a **Name**.
* Turn off the **Expiration date** option.
* Click **Add new value.**
* Click **Save**.

<figure><picture><source srcset="/files/NeeWsSQzoChVxRIY76Nt" media="(prefers-color-scheme: dark)"><img src="/files/1oTccyPmgZJ1laY7IhZH" alt=""></picture><figcaption></figcaption></figure>

{% hint style="info" %}
Learn more about secrets in Onum in [this article](/administration/global-settings/organization-settings/secrets-management.md).
{% endhint %}

You can now select the secret you just created in the **Token/Password** fields.
{% endstep %}

{% step %}
Set **Allow TLS configuration** as *true* if you decide to include TLS authentication in this Listener:

* Add your TLS **Certificate**<mark style="color:red;">**\***</mark> from your [Secrets](/administration/global-settings/organization-settings/secrets-management.md) or create one.
* Add your **Private Key**<mark style="color:red;">**\***</mark> from your [Secrets](/administration/global-settings/organization-settings/secrets-management.md) or create one.
* Add your **CA Chain**<mark style="color:red;">**\***</mark> from your [Secrets](/administration/global-settings/organization-settings/secrets-management.md) or create one.
* Select the **Minimum TLS Version**<mark style="color:red;">**\***</mark>  from the menu.
  {% endstep %}

{% step %}
Finally, click **Create labels**. Optionally, you can set labels to be used for internal Onum routing of data. By default, data will be set as **Unlabeled**. Click **Create listener** when you're done.

{% hint style="info" %}
Learn more about labels in [this article](/the-workspace/listeners/labels.md).
{% endhint %}
{% endstep %}
{% endstepper %}

Click **Create listener** when you're done.


---

# 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.onum.com/the-workspace/listeners/listener-integrations/collect-data-using-opentelemetry.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.