UTF-8 support

Why enable UTF-8 support?

There are a number of reasons why UTF-8 support in Cortex is useful:

  1. With Prometheus version 3.0 UTF-8 support has been released for metric and label names. Thus, UTF-8 support improves the interoperability between Cortex and modern Prometheus ecosystems.
  2. It makes Cortex more flexible for internationalized or externally sourced metadata which is useful when metrics or labels originate from systems, teams, or domains that do not fit neatly into ASCII-only naming.
  3. It keeps behavior consistent across ingestion, rules and alerting.

Before you enable UTF-8 support

Although UTF-8 support increases flexibility, the traditional naming style remains the safest choice for broad ecosystem compatibility, because downstream tools might assume legacy-compatible names. Check the compatibility of these tools before enabling UTF-8 support.

Before enabling UTF-8 support, review the systems that write metrics to Cortex, the rules evaluated by the Ruler, and the alerting configuration used by Alertmanager.

Enabling UTF-8 support changes validation behavior. Roll it out in a staging environment first and verify that ingestion, rule evaluation, and alert routing continue to work as expected.

Configure UTF-8 support

Cortex supports configuring how metric names and label names are validated through the -name-validation-scheme flag or name_validation_scheme in the YAML configuration file.

Supported values are:

  • legacy (default)
  • utf8

UTF-8 name validation was introduced in Cortex v1.20.0.

This guide explains how to enable UTF-8 support and how the selected validation scheme affects the Cortex components.

To enable UTF-8 validation, set the validation scheme to utf8.

CLI:

-name-validation-scheme=utf8

YAML:

name_validation_scheme: utf8

Using UTF-8

After enabling UTF-8 name validation, UTF-8 metric names and label names can be used. The following examples illustrate how to work with those names.

Querying

PromQL queries support UTF-8 metric names and label names. For example, a UTF-8 metric name can be queried with the following expression:

{"series.1", "test.utf8.metric"="😄"}

Note that the metric name series.1 is not valid under the legacy validation scheme. It is accepted only when UTF-8 validation is enabled. This is useful when metric or label names contain characters, such as ., that are supported by UTF-8 validation but not by the legacy validation scheme.

Alertmanager

Alertmanager configuration can use UTF-8 names in matchers, group_by fields, and silence matchers. For example, a route can group and match on UTF-8 label names:

route:
  receiver: default
  group_by:
    - "group.test.🙂"
  routes:
    - receiver: utf8-receiver
      matchers:
        - '"🙂.utf8.label"="😄"'

receivers:
  - name: default
  - name: utf8-receiver

Silences can also match alerts using UTF-8 label names and values. For example, a silence can contain the following matcher:

{
  "matchers": [
    {
      "name": "🙂.utf8.label",
      "value": "😄",
      "isRegex": false,
      "isEqual": true
    }
  ]
}

This is a partial silence object. Creating a silence through the API additionally requires startsAt, endsAt, createdBy, and comment.

Together, these capabilities support routing, grouping, and silencing alerts that contain UTF-8 label names and values.

Ruler

Ruler rule definitions can use UTF-8 names in rule names, rule labels and rule group labels. For example:

groups:
  - name: "test.utf8.group"
    labels:
      "test.utf8.group.label": "😄"
    rules:
      - record: "test.utf8.recording.rule"
        expr: up
        labels:
          "test.utf8.rule.label": "😄"
      - alert: "test.utf8.alert"
        expr: up == 0
        labels:
          "test.utf8.alert.label": "😄"

Impact on Cortex components

Distributor

The Distributor validates incoming metric names and label names during ingestion.

When name_validation_scheme is set to legacy, Cortex applies the legacy validation behavior. When it is set to utf8, the Distributor accepts names that are valid under the UTF-8 scheme.

In practice, this means that enabling UTF-8 support can change whether samples or series are accepted during ingestion by the Distributor. With legacy validation, samples containing invalid metric or label names are rejected during validation. With UTF-8 validation enabled, names that are valid under the UTF-8 scheme can pass validation. Writers that send UTF-8 metric or label names require the Distributor to run with utf8 validation enabled.

Ruler

The Ruler uses the selected scheme when validating rule definitions and external label names. With utf8, rule and external-label names that are valid under the UTF-8 scheme can be used.

Alertmanager

The Alertmanager uses the selected scheme directly when choosing how to parse matchers. Cortex maps legacy to Alertmanager’s classic-mode and utf8 to utf8-strict-mode during Alertmanager initialization. This affects parsing of matchers in Alertmanager configurations and validation of label names in fields such as group_by.

In UTF-8 strict mode, there is no fallback to classic matcher parsing. Existing Alertmanager configurations should be checked for strict-mode compatibility before enabling utf8, even if they do not use non-legacy label names.

  1. Inventory metric producers and consumers, Ruler rules, external labels, and Alertmanager configurations. Check whether any tools assume legacy metric and label names.
  2. Verify that existing Alertmanager route matchers parse in UTF-8 strict mode. Update ambiguous or incompatible matchers before switching modes.
  3. Enable utf8 in a staging environment. Ingest and query representative metrics with non-legacy names, and exercise label name, label value, and series API endpoints.
  4. Load representative recording and alerting rules, including group and rule labels, and verify evaluation and notifications.
  5. Test Alertmanager configuration loading, grouping, routing, and silence creation. Roll out consistently across the Cortex components that need the selected mode.

Rolling back to legacy

Switching name_validation_scheme from utf8 back to legacy does not remove previously ingested series with UTF-8 names. These series remain in storage and can still be queried. However, the rollback affects new ingestion and configuration validation:

  • Distributor: New samples containing metric or label names that are invalid under the legacy validation scheme are rejected during ingestion.
  • Ruler: Existing rule groups remain stored and can still load, but rule outputs with UTF-8 names are rejected during ingestion. Rules containing UTF-8 recording rule names or rule labels can no longer be uploaded or updated through the Ruler API.
  • Alertmanager: Configurations using UTF-8 label names in matchers or group_by fields fail to load in classic-mode. Incoming alerts containing UTF-8 label names are also rejected.
  • Limits validation: ruler_external_labels and metric_relabel_configs containing UTF-8 label names fail validation. Invalid default limits prevent Cortex from starting, while invalid per-tenant overrides cause the runtime configuration file to be rejected.

Before switching back to legacy, remove or rename UTF-8 metric and label names in Ruler rule groups, ruler_external_labels, metric_relabel_configs, and Alertmanager configurations to ensure compatibility with legacy validation.

Compatibility notes

  • Use legacy if you need to preserve the previous validation behavior.
  • Use utf8 if you want Cortex to accept UTF-8 metric names and label names.
  • Plan migration carefully when different systems in your environment assume different naming rules.
  • Refer to the configuration reference for the current flag and supported values.