From ec9ec0293ab8d481ae8a3ce30a6d34c3b6dd1067 Mon Sep 17 00:00:00 2001 From: beorn7 Date: Wed, 13 May 2020 01:36:17 +0200 Subject: [PATCH] Document how to use empty label values in the grouping key Signed-off-by: beorn7 --- README.md | 37 ++++++++++++++++++++++++++++--------- 1 file changed, 28 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 30462651..7cf19a07 100644 --- a/README.md +++ b/README.md @@ -266,10 +266,20 @@ _will be overwritten to match the labels defined by the URL path!_ If `job` or any label name is suffixed with `@base64`, the following job name or label value is interpreted as a base64 encoded string according to [RFC 4648, using the URL and filename safe -alphabet](https://tools.ietf.org/html/rfc4648#section-5). (Padding is -optional.) This is the only way of using job names or label values that contain -a `/`. For other special characters, the usual URI component encoding works, -too, but the base64 might be more convenient. +alphabet](https://tools.ietf.org/html/rfc4648#section-5). (Padding is optional, +but a single `=` is required to encode an empty label value.) This is the only +way to handle the following cases: + +* A job name or a label value that contains a `/`, because the plain (or even + URI-encoded) `/` would otherwise be interpreted as a path separator. +* An empty label value, because the resulting `//` or trailing `/` would + disappear when the path is sanitized by the HTTP router code. Note that an + empty `job` name is invalid. Empty label values are valid but rarely + useful. To encode them with base64, you have to use at least one `=` padding + character to avoid the `//`. + +For other special characters, the usual URI component encoding works, too, but +the base64 might be more convenient. Ideally, client libraries take care of the suffixing and encoding. @@ -278,25 +288,34 @@ Examples: * To use the grouping key `job="directory_cleaner",path="/var/tmp"`, the following path will _not_ work: - /metrics/job/directory_cleaner/path//var/tmp - + /metrics/job/directory_cleaner/path//var/tmp + Instead, use the base64 URL-safe encoding for the label value and mark it by suffixing the label name with `@base64`: - /metrics/job/directory_cleaner/path@base64/L3Zhci90bXA - + /metrics/job/directory_cleaner/path@base64/L3Zhci90bXA + If you are not using a client library that handles the encoding for you, you can use encoding tools. For example, there is a command line tool `base64url` (Debian package `basez`), which you could combine with `curl` to push from the command line in the following way: echo 'some_metric{foo="bar"} 3.14' | curl --data-binary @- http://pushgateway.example.org:9091/metrics/job/directory_cleaner/path@base64/$(echo -n '/var/tmp' | base64url) + +* To use the grouping key `job="example",first_label="",second_label="foobar"`, + the following path will _not_ work: + /metrics/job/example/first_label//second_label/foobar + + Instead, use the following path including the `=` padding character: + + /metrics/job/example/first_label@base64/=/second_label/foobar + * The grouping key `job="titan",name="Προμηθεύς"` can be represented “traditionally” with URI encoding: /metrics/job/titan/name/%CE%A0%CF%81%CE%BF%CE%BC%CE%B7%CE%B8%CE%B5%CF%8D%CF%82 - + Or you can use the more compact base64 encoding: /metrics/job/titan/name@base64/zqDPgc6_zrzOt864zrXPjc-C