From 956bc08b66278b2ac1137050f371059b2660577e Mon Sep 17 00:00:00 2001 From: Arnab Nandy Date: Sat, 17 Oct 2026 00:47:19 +0530 Subject: [PATCH] docs: explain quoted Unicode metric names Signed-off-by: Arnab Nandy --- docs/content/exporters/unicode.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/docs/content/exporters/unicode.md b/docs/content/exporters/unicode.md index 232dcb1a57..15a972e92b 100644 --- a/docs/content/exporters/unicode.md +++ b/docs/content/exporters/unicode.md @@ -26,6 +26,19 @@ When `escaping=allow-utf-8` is passed, add valid UTF-8 characters to the metric without replacing them. This allows you to use dots in metric and label names, as well as other UTF-8 characters, without any replacements. +Names outside the legacy character set must use the quoted syntax in the Prometheus and +OpenMetrics 1.0 text formats. A quoted metric name is written inside braces, followed by its +labels. For example, a counter named `test_我喜欢茶` with a `test` label is exposed as: + +```text +# TYPE "test_我喜欢茶" counter +{"test_我喜欢茶_total",test="test_我喜欢茶"} 1.0 +``` + +The braces do not turn the metric name into a label. They are the required text-format notation +for a quoted metric name. See the [Prometheus exposition +format](https://prometheus.io/docs/instrumenting/exposition_formats/) for the complete syntax. + OpenMetrics 2.0 supports UTF-8 names natively, so when the OpenMetrics 2.0 writer serves a request that explicitly asks for `version=2.0.0`, names are not escaped unless the request also contains an `escaping` parameter.