---
description: Everything starts with a good Listener
---

# Listeners

{% embed url="https://youtu.be/JWu0iQZeuPI" %}

## Overview

Essentially, Onum receives any data through **Listeners**. These are logical entities created within a [Distributor](../getting-started/architecture), acting as the gateway to the Onum system. Due to this, configuring a Listener involves defining an IP address, a listening port, and a transport layer protocol, along with additional settings depending on the type of Listener specialized in the data it will receive.&#x20;

A **Push** type of Listener passively sources data without explicitly requesting, whereas a **Pull** type is where the user actively requests data from an external source.&#x20;

{% hint style="warning" %}
If you are using more than one **Cluster,** it is recommended not to use a **Pull-type** Listener. You can find out the Listener type in the integration-specific articles below.
{% endhint %}

Click the **Listeners** tab on the left menu for a general overview of the Listeners configured in your Tenant and the events generated.

<figure><picture><source srcset="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FOMHcnXkXTZhV76cGohMo%2Fdark-large%20(24).png?alt=media&#x26;token=8679ac13-8749-4690-9178-b86cb6d0faf3" media="(prefers-color-scheme: dark)"><img src="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FAumB5X4Qmwlr90Yx5YNO%2Flight-large%20(13).png?alt=media&#x26;token=68440757-ee4a-4119-aa6e-b12c7573b32e" alt=""></picture><figcaption></figcaption></figure>

* The graph at the top plots the volume ingested by your listeners. Click **Events** to see the events in for all your Listeners, or **Bytes** to see a bar graph representing the bytes in. Learn more about this graph [in this article](../getting-started/understanding-the-essentials/graph-calculations).&#x20;
  * Use the **Stack Listeners** toggle to view each individual Listener on your graph and its metrics.&#x20;
* Hover over a point on the chart to show a tooltip containing the Events and Bytes OUT for the selected time, as well as a percentage of how much increase/decrease has occurred between the previous lapse of time and the one currently selected.

<figure><img src="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FbPQkwhUDfUep8tvi7WnP%2Fdark-medium%20(12).png?alt=media&#x26;token=e990bf55-151b-4313-8193-9213da2ba280" alt=""><figcaption></figcaption></figure>

At the bottom, you have a list of all the Listeners in your Tenant. You can switch between the **Cards** view, which shows each Listener in a card, and the **Table** view, which displays Listeners listed in a table. Learn more about the cards and table views [in this article](../getting-started/understanding-the-essentials/cards-and-table-views).

## Narrow Down Your Data

There are various ways to narrow down what you see in this view:

### **Add Filters**

Add filters to narrow down the Listeners you see in the list. Click the **+ Add filter** button and select the required filter type(s). You can filter by:

* **Name**: Select a **Condition** (**Contains**, **Equals**, or **Matches**) and a **Value** to filter Listeners by their names.
* **Type**: Choose the Listener type(s) you want to see in the list.
* **Version**: Filter Listeners by their version.&#x20;
* **Created by:** Selecting this option opens a **User** drop-down where you can filter by creator.
* **Updated by:** Selecting this option opens a **User** drop-down where you can filter by the last user to update a pipeline.

The filters applied will appear as tags at the top of the view.

{% hint style="warning" %}
Note that you can only add one filter of each type.
{% endhint %}

<figure><picture><source srcset="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FTs82sPd8It76jYed6rCJ%2Fdark-medium%20(18).png?alt=media&#x26;token=90b4c40e-da3e-497c-aa1f-73fc463fc621" media="(prefers-color-scheme: dark)"><img src="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FBSGfP5mqC1jkHLfn3OYR%2Flight-medium%20(19).png?alt=media&#x26;token=4d56eece-6fa2-4d10-ab55-8503013a696b" alt=""></picture><figcaption></figcaption></figure>

### **Select a Time Range**

If you wish to see data for a specific time period, this is the place to click. Go to [this article](../getting-started/understanding-the-essentials/the-time-range-selector) to dive into the specifics of how the time range works.

<figure><picture><source srcset="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2Fb13ZpSnUBWJhyHPWT6e3%2Fdark-large%20(11).png?alt=media&#x26;token=d08af458-f420-4265-9a9c-0cc08c92d464" media="(prefers-color-scheme: dark)"><img src="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FrqC83Z4pVrF0nRHaV0Bf%2Flight-large%20(14).png?alt=media&#x26;token=1201ea3e-762c-452d-a761-850c9b37de8b" alt=""></picture><figcaption></figcaption></figure>

### **Select Tags**

You can choose to view only those Listeners that have been assigned the desired tags. You can create these tags in the Listener settings or from the cards view. Press the `Enter` key to confirm the tag, then **Save**.

To filter by tags, click the **+ Tags** button, select the required tag(s) and click **Save**.

<figure><picture><source srcset="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FeM2ZeC1jj1KIoLCIpbR0%2Fdark-medium%20(23).png?alt=media&#x26;token=e453cbbf-d859-420e-b551-dfa497984861" media="(prefers-color-scheme: dark)"><img src="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FTn41pd7pQNPRDeZweogb%2Flight-medium%20(35).png?alt=media&#x26;token=d9552190-c125-4caa-8e01-f1f332a99e7f" alt=""></picture><figcaption></figcaption></figure>

***

## Create a Listener

Depending on your permissions, you can create a new Listener from this view.&#x20;

There are several ways to create a new Listener:

From the **Listeners** view:

<figure><picture><source srcset="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FtzofoNiy8k0TUx6GExli%2Fdark-medium%20(14).png?alt=media&#x26;token=f9d4cfe8-02dd-4a57-b692-dc02a8b737aa" media="(prefers-color-scheme: dark)"><img src="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FjAJ8vRyOmPQWWTDv6lC6%2Flight-medium%20(15).png?alt=media&#x26;token=7cae9793-8046-4754-86fa-d03d8e25ccde" alt=""></picture><figcaption></figcaption></figure>

***

Within a [**Pipeline**](pipelines)**:**&#x20;

<figure><picture><source srcset="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FQQr9OA1KLBCdtfvFzQno%2Fdark-medium%20(15).png?alt=media&#x26;token=2b0ec30c-e659-4d9a-8f8d-2a6d40c3667c" media="(prefers-color-scheme: dark)"><img src="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FROTPDi14cuSVTELoegAi%2Flight-medium%20(16).png?alt=media&#x26;token=37fb740c-43c2-4074-a5da-fc43aac9c7e9" alt=""></picture><figcaption></figcaption></figure>

***

From[ **the Home Page:**](home)

<figure><picture><source srcset="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FlfLT2t3yTPpmxDWTqDMW%2Fdark-medium%20(17).png?alt=media&#x26;token=3985888d-de3a-4c07-824f-93a52164e1a7" media="(prefers-color-scheme: dark)"><img src="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FuhYIAXT9Wzul0hg97pfG%2Flight-medium%20(18).png?alt=media&#x26;token=ebfe11cc-72cb-42e2-8364-7488137ace56" alt=""></picture><figcaption></figcaption></figure>

***

## Configure a Listener

Configuring your Listener involves various steps. You can open the configuration pane by creating a new Listener or by clicking a Listener in the **Listener** tab or the **Pipeline** view and selecting **Edit Listener** in the pane that opens.

Alternatively, click the ellipses in the card or table view and select **Edit.**

### 01. Type

The first step is to define the Listener **Type**. Select the desired type in this window and select **Configuration.**

<figure><picture><source srcset="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FtUi0bMnTkcrOnaKCSnG0%2Fselect%20type%20dark.png?alt=media&#x26;token=03c77264-0762-4722-adab-7528393c388c" media="(prefers-color-scheme: dark)"><img src="https://965373739-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkxZeV4nlXcIAjMGZxzLI%2Fuploads%2FItKxD0vzw7GQQbUfwHT5%2Fselect%20type%20light.png?alt=media&#x26;token=426d6cb4-dfa6-4816-b447-a5d49d0ad1c9" alt=""></picture><figcaption></figcaption></figure>

### 02. Configuration

The configuration is different for each Listener type. Check the different Listener types and how to configure them [in this section](listeners/listener-integrations).

{% hint style="warning" %}
If your Listener is deployed in the Cloud, you will see an extra step for the network properties. Learn more about Listeners in a Cloud deployment [in this article](listeners/cloud-listeners).
{% endhint %}

### 03. Labels

Use Onum's labels to cut out the noise with filters and search criteria based on specific metadata. This way, you can categorize events sent on and processed in your [Pipelines](https://onum.gitbook.io/onum-docs/the-workspace/pipelines).

Learn more about labels [in this article](listeners/labels).
