# Labels

{% embed url="<https://www.youtube.com/watch?v=0i0AyPgsESY>" %}

## Overview

Use Onum's **labels** to cut out the noise with filters and search criteria based on specific metadata. This way, you can categorize the events that Listeners receive before being processed in your [Pipelines](/the-workspace/pipelines.md).

As different log formats are being ingested in real-time, the same Listener may ingest different technologies. Labels are useful for categorizing events based on specific criteria.

When creating or editing a **Listener**, use **Labels** to categorize and assign filters to your data.

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

For most Listeners, you will see two main event categories on this screen:

* **All Data** - Events that follow the structure defined by the specified protocol, for example, Syslog events with the standard fields, or most of them. &#x20;
* **Unlabeled** - These are events that do not follow the structure defined in the selected protocol.

You can define filters and rules for each of these main categories.

## What are labels used for?

Once you've defined your labels to filter specific events, you can use them in your Pipelines.

Instead of using the whole set of events that come into your Listeners, you can use your defined labels to use only specific sets of data filtered by specific rules.

## Creating your first label

When you create a new Listener, you'll be prompted to the **Labels** screen after configuring your Listener data.

{% stepper %}
{% step %}
Click the **+** button under the set of data you want to filter (**All Data** or **Unlabeled**). You'll see your first label. Click the pencil icon a give it a name that describes the data that will filter out.
{% endstep %}

{% step %}
Below, see the **Filter** button. This is where you add the criteria to categorize the content under that label. Choose the field you want to filter by.
{% endstep %}

{% step %}
Now, define the filter criteria:

* **Condition** - Choose between:
  * **Contains** - Checks when the indicated value appears anywhere in the log.
  * **Equals** - Filters for exact matches of the value in the log.
  * **Matches** - Filters for exact matches of the value in the log, allowing for regular expressions.
* &#x20; **Value** - Enter the value to filter by.

{% hint style="warning" %}
**Using regular expressions**

Note that regular expressions need to be written in Golang syntax to function correctly (negative lookaheads are prohibited, as an example).
{% endhint %}
{% endstep %}

{% step %}
Click **Save** and see the header appear for your first label.

<figure><picture><source srcset="/files/gA7EnLkMONRjZctRiN50" media="(prefers-color-scheme: dark)"><img src="/files/K86Ij4SV5f6zTvNX6ihO" alt=""></picture><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

From here, you have various options:

<details>

<summary>Create a new label</summary>

To create a new subset of data, select the **+** sign that extends directly from the **All data** or **Unparsed** bars. Be aware that if you select the **+** sign extending from the header bar,  you will create a subheader.

</details>

<details>

<summary>Create a sub-label</summary>

You can create a branch from your primary header by clicking the plus button that extends from the main header. There is no limit to the amount that you can add.

Notice that the subheader shows a filter icon with a number next to it to indicate the string of filters applied to it already.

</details>

<details>

<summary>Duplicate a label</summary>

To duplicate a label, simply select the duplicate button in its row.&#x20;

</details>

<details>

<summary>Delete a label</summary>

To delete a label, simply select the delete button in its row.&#x20;

{% hint style="warning" %}
If you attempt to delete a Label that is being used in a Pipeline, you will be asked to confirm where to remove it from.
{% endhint %}

</details>

Once you have completed your chain, click **Save**.&#x20;

## Unlabeled data

Any data that has not been assigned a label will be automatically categorized as **unlabeled**. This allows you to see the data that is not being processed by any **Pipeline**, but has not been lost.&#x20;

This label will appear in the list of Labels for use in your Pipeline so that you can process the data in its unfiltered form.

Your Listener is now ready to use and will appear in the list.


---

# 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/labels.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.