Skip to content

docs: Guide on how to setup UTF-8 mode in Cortex#7439

Open
RaphSku wants to merge 2 commits intocortexproject:masterfrom
RaphSku:docs/utf8-support-guide
Open

docs: Guide on how to setup UTF-8 mode in Cortex#7439
RaphSku wants to merge 2 commits intocortexproject:masterfrom
RaphSku:docs/utf8-support-guide

Conversation

@RaphSku
Copy link
Copy Markdown

@RaphSku RaphSku commented Apr 18, 2026

What this PR does:
Introduces a Guide on how to setup UTF-8 mode in Cortex

Which issue(s) this PR fixes:
Fixes #7091

Checklist

  • Tests updated (does not apply)
  • Documentation added
  • CHANGELOG.md updated - the order of entries should be [CHANGE], [FEATURE], [ENHANCEMENT], [BUGFIX]
  • docs/configuration/v1-guarantees.md updated if this PR introduces experimental flags (does not apply)

Signed-off-by: Raphael Skuza <rapsku.dev@gmail.com>
Comment thread docs/guides/utf8-support.md Outdated
name_validation_scheme: utf8
```

### Impact on Cortex components
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the Distributor is a sub-item, it would be better to increase to the ##.

Suggested change
### Impact on Cortex components
## Impact on Cortex components

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Typo, thank you for pointing it out

@SungJin1212
Copy link
Copy Markdown
Member

@RaphSku
In the "Impact on Cortex components" section, an explanation is needed regarding how Ruler and Alertmanager work when we enable the utf8.

Comment thread CHANGELOG.md Outdated
* [FEATURE] Ingester: Add experimental active series queried metric. #7173
* [FEATURE] Update prometheus Alertmanager version to v0.31.1 and add new integration to IncidentIO and Mattermost. #7092 #7267
* [FEATURE] Tenant Federation: Add experimental support for partial responses using the `-tenant-federation.allow-partial-data` flag. When enabled, failures from individual tenants during a federated query are treated as warnings, allowing results from successful tenants to be returned. #7232
* [ENHANCEMENT] Docs: Guide on UTF-8 Support in Cortex #7091
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it's necessary to leave it in the changelog.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed :)

Signed-off-by: Raphael Skuza <rapsku.dev@gmail.com>
@RaphSku
Copy link
Copy Markdown
Author

RaphSku commented May 3, 2026

@RaphSku In the "Impact on Cortex components" section, an explanation is needed regarding how Ruler and Alertmanager work when we enable the utf8.

I've added the mentioned components to the guide, thank you for the review. If there is something in particular I should mention about either component, let me know.

@SungJin1212
Copy link
Copy Markdown
Member

@RaphSku
To make it even more practical for users, I think it would be highly beneficial to explicitly cover the scenarios we are validating in utf8_test.go.

  • Querying: Mention that PromQL queries, as well as API endpoints like LabelNames, Series, and LabelValues, fully support UTF-8 (e.g., querying {"test.utf8.metric"="😄"}).
  • Alertmanager: Highlight that UTF-8 can be safely used in config matchers, group_by fields, and Silence matchers.
  • Ruler: Note that rule names, rule labels, and rule group labels support UTF-8 characters.

Adding a few short YAML or PromQL snippets based on our tests would perfectly bridge the gap between the configuration and actual usage.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document for How to setup UTF-8 supporting mode on Cortex

2 participants