From fa39b2e22baf9a2b8ea6c2d9f379b593e0707580 Mon Sep 17 00:00:00 2001 From: Owen Williams Date: Wed, 13 Nov 2024 12:39:31 -0500 Subject: [PATCH] rearrange and add content negotiation --- content/docs/guides/utf8.md | 71 +++++++++++++++++++++++-------------- 1 file changed, 45 insertions(+), 26 deletions(-) diff --git a/content/docs/guides/utf8.md b/content/docs/guides/utf8.md index 0dffb1b5a..4532c417c 100644 --- a/content/docs/guides/utf8.md +++ b/content/docs/guides/utf8.md @@ -13,7 +13,33 @@ There may also be circumstances where users want to enforce the legacy character set, perhaps for compatibility with an older system or one that does not yet support UTF-8. -# Configuring Name Validation +# Instrumentation + +Currently, metrics created by the client_golang library will reject UTF-8 names +by default. It is necessary to change the default validation scheme to allow +UTF-8. The requirement to set this value will be removed in a future version of +the common library. + +```golang +import "github.com/prometheus/common/model" + +func init() { + model.NameValidationScheme = model.UTF8Validation +} +``` + +If users want to enforce the legacy character set, they can set the validation +scheme to `LegacyValidation`. + +Setting the validation scheme must be done before the instantiation of metrics +and can be set on the fly if desired. + +## Instrumenting in other languages + +Other client libraries may have similar requirements to set the validation +scheme. Check the documentation for the library you are using. + +# Configuring Scrape Name Validation By default, Prometheus 3.0 accepts all UTF-8 strings as valid metric and label names. It is possible to override this behavior for scraped targets and reject @@ -36,36 +62,29 @@ scrape_configs: Scrape config settings override the global setting. -## Remote Write 2.0 - -Remote Write 2.0 automatically accepts all UTF-8 names in Prometheus 3.0. There -is no way to enforce the legacy character set validation with Remote Write 2.0. +## Content Negotiation -# Instrumentation +At scrape time, the scraping system **must** pass `escaping=allow-utf-8` in the +Accept header in order to be served UTF-8 names. If a system being scraped does +not see this header, it will automatically convert UTF-8 names to +legacy-compatible using underscore replacement. -Currently, metrics created by the client_golang library will reject UTF-8 names -by default. It is necessary to change the default validation scheme to allow -UTF-8. The requirement to set this value will be removed in a future version of -the common library. +Scraping systems can also request a specfic escaping method if desired by +setting the `escaping` header to a different value. -```golang -import "github.com/prometheus/common/model" +* `underscores`: The default: convert legacy-invalid characters to underscores. +* `dots`: similar to UnderscoreEscaping, except that dots are converted to + `_dot_` and pre-existing underscores are converted to `__`. This allows for + round-tripping of simple metric names that also contain dots. +* `values`: This mode prepends the name with `U__` and replaces all invalid + characters with the unicode value, surrounded by underscores. Single + underscores are replaced with double underscores. This mode allows for full + round-tripping of UTF-8 names with a legacy system. -func init() { - model.NameValidationScheme = model.UTF8Validation -} -``` - -If users want to enforce the legacy character set, they can set the validation -scheme to `LegacyValidation`. - -Setting the validation scheme must be done before the instantiation of metrics -and can be set on the fly if desired. - -## Instrumenting in other languages +## Remote Write 2.0 -Other client libraries may have similar requirements to set the validation -scheme. Check the documentation for the library you are using. +Remote Write 2.0 automatically accepts all UTF-8 names in Prometheus 3.0. There +is no way to enforce the legacy character set validation with Remote Write 2.0. # Querying