​Labels

Labels are key-value pairs used to organize flows and executions.

Labels are key-value pairs that you can use to organize (and search for) your flows and executions based on your project, maintainers, or any other criteria.

The purpose of labels

Labels can be used to organize and filter flows and their executions. You can add labels to your flows to sort their executions across multiple dimensions.

Here is a simple example of a flow with labels:

id: flow_with_labels
namespace: example

labels:
  song: never-gonna-give-you-up
  artist: rick-astley

tasks:
  - id: hello
    type: io.kestra.core.tasks.log.Log
    message: hello from a flow with labels

Benefits of labels

Labels provide a simple and effective way to organize and filter flows and their executions. Here are some of the benefits of using labels:

• Observability: labels set during execution provide help in monitoring and troubleshooting.
• Filtering: labels make it easier to find specific executions; you can use it to track ML experiments, track responses from external APIs, or label executions based on runtime-specific flow inputs.
• Organization: labels help organize and manage workflow executions at scale, especially in complex environments and large-scale deployments. You can create custom dashboards based on labels to monitor specific executions, e.g. http://localhost:8080/ui/executions?labels=team:finance. You can use that pattern to build custom dashboards for specific teams, projects, flow maintainers or environments.

Execution labels propagated from flow labels

When you execute a flow with labels, the labels will be propagated to the created executions:

Set execution labels when executing a flow from the UI

When executing flows manually from the UI, you can override and define new labels at the flow execution start by expanding the Advanced configuration section:

Since Kestra 0.15.0, you can also set labels from the UI after the execution has completed. This feature is useful for collaboration and troubleshooting in the team. For example, you can add a label to a failed execution to indicate that it has been acknowledged and someone is working on a resolution, or that it has been resolved.

To set labels from the UI, go to the Overview tab of an Execution and click on the "Set labels" button. You can add multiple labels at once.

You can even set labels for multiple executions at once from the UI. This feature is helpful for bulk operations, such as acknowledging multiple failed executions at once after an outage.

Set labels based on flow inputs and task outputs

In Kestra 0.14.0, we introduced the ability to set execution labels from a dedicated Labels task. This task provides a dynamic way to label your flows, helping with observability, debugging, and monitoring of failures.

By using this task, you can set custom execution labels based on flow inputs, task outputs, or any other dynamic data within the workflow. There are two ways to set labels in this task:

1. Using a Map (Key-Value Pairs): ideal when the key is static and the value is dynamic. The key is the label name, and the value is a dynamic label value that might be derived from the flow inputs or task outputs. In the example below, the task update_labels overrides the default label song with the output of the get task, and adds a new label called artist.

id: labels_override
namespace: example

labels:
  song: never-gonna-give-you-up

tasks:
  - id: get
    type: io.kestra.core.tasks.debugs.Return
    format: never-gonna-stop

  - id: update_labels
    type: io.kestra.core.tasks.executions.Labels
    labels:
      song: "{{ outputs.get.value }}"
      artist: rick-astley # new label

2. Using a List of Key-Value Pairs: particularly useful if both the key and the value are dynamic properties.

id: labels
namespace: example

inputs:
  - id: user
    type: STRING
    defaults: Rick Astley

  - id: url
    type: STRING
    defaults: song_url

tasks:
  - id: update_labels_with_map
    type: io.kestra.core.tasks.executions.Labels
    labels:
      customerId: "{{ inputs.user }}"

  - id: get
    type: io.kestra.core.tasks.debugs.Return
    format: https://t.ly/Vemr0

  - id: update_labels_with_list
    type: io.kestra.core.tasks.executions.Labels
    labels:
      - key: "{{ inputs.url }}"
        value: "{{ outputs.get.value }}"

Overriding flow labels at runtime

You can set default labels at the flow level and override them at runtime. This approach is useful for overriding label values dynamically during execution based on the results of specific tasks.

The example below shows how to override the default label song with the output of the get task:

id: flow_with_labels
namespace: example

labels:
  song: never-gonna-give-you-up
  artist: rick-astley
  genre: pop

tasks:
  - id: get
    type: io.kestra.core.tasks.debugs.Return
    format: never-gonna-stop

  - id: update-list
    type: io.kestra.core.tasks.executions.Labels
    labels:
      song: "{{ outputs.get.value }}"

In this example, the default label song is overridden by the output of the get task.