rearrange and add content negotiation

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