Documentationbreadcrumb arrow Grafana Cloudbreadcrumb arrow Instrument and send databreadcrumb arrow Grafana Alloybreadcrumb arrow Referencebreadcrumb arrow Componentsbreadcrumb arrow pyroscopebreadcrumb arrow pyroscope.relabel
General availability (GA) Open source Grafana Cloud

pyroscope.relabel

The pyroscope.relabel component rewrites the label set of each profile passed to its receiver by applying one or more relabeling rules and forwards the results to the list of receivers.

If no rules are defined or applicable to some profiles, then those profiles are forwarded as-is to each receiver passed in the component’s arguments. The profile is dropped if no labels remain after the relabeling rules are applied.

The most common use of pyroscope.relabel is to filter profiles or standardize the label set that is passed to one or more downstream receivers. The rule blocks are applied to the label set of each profile in order of their appearance in the configuration file.

Usage

Alloy 
pyroscope.relabel "<LABEL>" {
    forward_to = <RECEIVER_LIST>

    rule {
        ...
    }

    ...
}

Arguments

You can use the following arguments with pyroscope.relabel:

NameTypeDescriptionDefaultRequired
forward_tolist(pyroscope.Appendable)List of receivers to forward profiles to after relabelingyes
max_cache_sizenumberMaximum number of entries in the label cache10000no

Blocks

You can use the following block with pyroscope.relabel:

NameDescriptionRequired
ruleRelabeling rules to apply to received profile entries.no

rule

The rule block contains the definition of any relabeling rules that can be applied to an input metric. If more than one rule block is defined, the transformations are applied in top-down order.

The following arguments can be used to configure a rule. All arguments are optional. Omitted fields take their default values.

NameTypeDescriptionDefaultRequired
actionstringThe relabeling action to perform.replaceno
modulusuintA positive integer used to calculate the modulus of the hashed source label values.no
regexstringA valid RE2 expression with support for parenthesized capture groups. Used to match the extracted value from the combination of the source_label and separator fields or filter labels during the labelkeep/labeldrop/labelmap actions.(.*)no
replacementstringThe value against which a regular expression replace is performed, if the regular expression matches the extracted value. Supports previously captured groups."$1"no
separatorstringThe separator used to concatenate the values present in source_labels.;no
source_labelslist(string)The list of labels whose values are to be selected. Their content is concatenated using the separator and matched against regex.no
target_labelstringLabel to which the resulting value will be written to.no

You can use the following actions:

  • drop - Drops metrics where regex matches the string extracted using the source_labels and separator.
  • dropequal - Drop targets for which the concatenated source_labels do match target_label.
  • hashmod - Hashes the concatenated labels, calculates its modulo modulus and writes the result to the target_label.
  • keep - Keeps metrics where regex matches the string extracted using the source_labels and separator.
  • keepequal - Drop targets for which the concatenated source_labels don’t match target_label.
  • labeldrop - Matches regex against all label names. Any labels that match are removed from the metric’s label set.
  • labelkeep - Matches regex against all label names. Any labels that don’t match are removed from the metric’s label set.
  • labelmap - Matches regex against all label names. Any labels that match are renamed according to the contents of the replacement field.
  • lowercase - Sets target_label to the lowercase form of the concatenated source_labels.
  • replace - Matches regex to the concatenated labels. If there’s a match, it replaces the content of the target_label using the contents of the replacement field.
  • uppercase - Sets target_label to the uppercase form of the concatenated source_labels.

Note

The regular expression capture groups can be referred to using either the $CAPTURE_GROUP_NUMBER or ${CAPTURE_GROUP_NUMBER} notation.

Exported fields

The following fields are exported and can be referenced by other components:

NameTypeDescription
receiverProfilesReceiverA receiver that accepts profiles for relabeling.
rules[]relabel.ConfigThe list of relabeling rules.

Component health

pyroscope.relabel is reported as unhealthy if it is given an invalid configuration.

Debug metrics

  • pyroscope_relabel_cache_hits (counter): Total number of cache hits.
  • pyroscope_relabel_cache_misses (counter): Total number of cache misses.
  • pyroscope_relabel_cache_size (gauge): Total size of relabel cache.
  • pyroscope_relabel_profiles_dropped (counter): Total number of profiles dropped by relabeling rules.
  • pyroscope_relabel_profiles_processed (counter): Total number of profiles processed.
  • pyroscope_relabel_profiles_written (counter): Total number of profiles forwarded.

Example

Alloy 
pyroscope.receive_http "default" {
    forward_to = [pyroscope.relabel.filter_profiles.receiver]

    http {
        listen_address = "0.0.0.0"
        listen_port = 9999
    }
}

pyroscope.relabel "filter_profiles" {
    forward_to = [pyroscope.write.staging.receiver]

    // This creates a consistent hash value (0 or 1) for each unique combination of labels
    // Using multiple source labels provides better sampling distribution across your profiles
    rule {
        source_labels = ["env"]
        target_label = "__tmp_hash"
        action = "hashmod"
        modulus = 2
    }

    // This effectively samples ~50% of profile series
    // The same combination of source label values will always hash to the same number,
    // ensuring consistent sampling
    rule {
        source_labels = ["__tmp_hash"]
        action       = "drop"
        regex        = "^1$"
    }
}

pyroscope.write "staging" {
  endpoint {
    url = "http://pyroscope-staging:4040"
  }
}

Compatible components

pyroscope.relabel can accept arguments from the following components:

pyroscope.relabel has exports that can be consumed by the following components:

Note

Connecting some components may not be sensible or components may require further configuration to make the connection work correctly. Refer to the linked documentation for more details.