> For the complete documentation index, see [llms.txt](https://docs.onum.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onum.com/listeners/listener-integrations/collect-data-using-opentelemetry.md).
# Collect data using OpenTelemetry
{% hint style="info" %}
See the changelog of the **OpenTelemetry** Listener [here](/listeners-changelog/opentelemetry-listener.md).
{% endhint %}
{% hint style="warning" %}
Note that the **OpenTelemetry** Listener is not currently available for all tenant types. If this Listener does not appear in the list of available options when you're creating a new Listener, this is due to a temporary limitation based on your tenant's deployment configuration. This is an expected behavior and we are working to extend its availability soon.
{% 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](broken://spaces/cSjT21I4EUhzghjc1rER/pages/nW8oZycpfVthtI5KYdQs) to get the cert information needed for TLS communication, which will be needed on the Listener setup.
## OpenTelemetry 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
The configuration process will change depending on your Falcon Onum deployment type:
### Cloud deployment
{% stepper %}
{% step %}
Log in to your Onum tenant and click **Listeners > New listener**.
{% endstep %}
{% step %}
Double-click the **OpenTelemetry** Listener.
{% endstep %}
{% step %}
Enter a **Name** for the new Listener. Optionally, add a **Description** and some **Tags** to identify the Listener.
{% endstep %}
{% step %}
In the **Protocol** section, you must choose either **HTTP** or **gRPC** as your protocol. If you choose **HTTP**, you must configure your custom paths:
* **Traces path** (default `/v1/traces`)
* **Metrics path** (default `/v1/metrics`)
* **Logs path** (default `/v1/logs`)
{% hint style="warning" %}
**Important:** **Disabling ALPN Enforcement for gRPC Clients**
The Onum cloud infrastructure does not advertise the h2 ALPN (Application-Layer Protocol Negotiation) protocol during the TLS handshake. Many gRPC client libraries now enforce ALPN by default, which causes connections to fail with a handshake error when the server does not advertise h2.
Clients must disable ALPN enforcement on their side. The method depends on the gRPC client library:\
\
**Go (grpc-go v1.67+) / Python (grpcio v1.67+) / C-core based clients:** Set the environment variable `GRPC_ENFORCE_ALPN_ENABLED=false`.
**Other clients:** Consult your gRPC client library documentation for how to disable ALPN enforcement.
{% endhint %}
{% endstep %}
{% step %}
Click **Create listener** when you're done. You'll see the **Network configuration** screen, which shows the **Address** and **Port** needed to communicate with Onum.
{% hint style="info" %}
You can access all this information in the Listener details after creation, so don't worry.
{% endhint %}
{% endstep %}
{% step %}
Click **Next**. Optionally, you can set labels to be used for internal Onum routing of data. By default, data will be set as **Unlabeled**. Click **Create labels** when you're done.
{% endstep %}
{% endstepper %}
### On-premises deployment
{% stepper %}
{% step %}
Log in to your Onum tenant and click **Listeners > New listener**.
{% endstep %}
{% step %}
Double-click the **OpenTelemetry** 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** to establish the connection with the protocol.
{% endstep %}
{% step %}
Set **Allow HTTP protocol** as **true** if you want to configure OTLP/HTTP:
* **HTTP Port** 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.
{% hint style="warning" %}
Note that the token name should be set to `Bearer` unless a custom or non-standard token name has been explicitly provided by the client.
{% endhint %}
{% 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**.
{% hint style="info" %}
Learn more about secrets in Onum in [this article](/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** from your [Secrets](/settings/organization-settings/secrets-management.md) or create one.
* Add your **Private Key** from your [Secrets](/settings/organization-settings/secrets-management.md) or create one.
* Add your **CA Chain** from your [Secrets](/settings/organization-settings/secrets-management.md) or create one.
* Select the **Minimum TLS Version** 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**.
{% hint style="info" %}
Learn more about labels in [this article](/listeners/labels.md).
{% endhint %}
{% endstep %}
{% step %}
Click **Create listener** when you're done.
{% endstep %}
{% endstepper %}
## Output Ports
The **OpenTelemetry** Listener has a single output port:
* **Default port** - Events are sent through this port if no error occurs while processing them.