18
18
* in Prometheus exposition formats. However, if metrics are exposed in OpenTelemetry format the dots are retained.
19
19
*/
20
20
public class PrometheusNaming {
21
+ // nameValidationScheme determines the method of name validation to be used by
22
+ // all calls to validateMetricName() and isValidMetricName(). Setting UTF-8 mode
23
+ // in isolation from other components that don't support UTF-8 may result in
24
+ // bugs or other undefined behavior. This value is intended to be set by
25
+ // UTF-8-aware binaries as part of their startup via a properties file.
21
26
public static ValidationScheme nameValidationScheme = initValidationScheme ();
22
27
28
+ // nameEscapingScheme defines the default way that names will be
29
+ // escaped when presented to systems that do not support UTF-8 names. If the
30
+ // Accept "escaping" term is specified, that will override this value.
23
31
public static EscapingScheme nameEscapingScheme = EscapingScheme .VALUE_ENCODING_ESCAPING ;
24
32
33
+ // ESCAPING_KEY is the key in an Accept header that defines how
34
+ // metric and label names that do not conform to the legacy character
35
+ // requirements should be escaped when being scraped by a legacy Prometheus
36
+ // system. If a system does not explicitly pass an escaping parameter in the
37
+ // Accept header, the default nameEscapingScheme will be used.
25
38
public static final String ESCAPING_KEY = "escaping" ;
26
39
27
40
private static final String LOWERHEX = "0123456789abcdef" ;
@@ -258,6 +271,8 @@ private static String replaceIllegalCharsInLabelName(String name) {
258
271
return new String (sanitized );
259
272
}
260
273
274
+ // escapeMetricSnapshot escapes the given metric names and labels with the given
275
+ // escaping scheme.
261
276
public static MetricSnapshot escapeMetricSnapshot (MetricSnapshot v , EscapingScheme scheme ) {
262
277
if (v == null ) {
263
278
return null ;
@@ -269,6 +284,7 @@ public static MetricSnapshot escapeMetricSnapshot(MetricSnapshot v, EscapingSche
269
284
270
285
String outName ;
271
286
287
+ // If the name is null, copy as-is, don't try to escape.
272
288
if (v .getMetadata ().getPrometheusName () == null || isValidLegacyMetricName (v .getMetadata ().getPrometheusName ())) {
273
289
outName = v .getMetadata ().getPrometheusName ();
274
290
} else {
@@ -453,6 +469,10 @@ static boolean metricNeedsEscaping(DataPointSnapshot d) {
453
469
return false ;
454
470
}
455
471
472
+ // escapeName escapes the incoming name according to the provided escaping
473
+ // scheme. Depending on the rules of escaping, this may cause no change in the
474
+ // string that is returned (especially NO_ESCAPING, which by definition is a
475
+ // noop). This method does not do any validation of the name.
456
476
static String escapeName (String name , EscapingScheme scheme ) {
457
477
if (name .isEmpty ()) {
458
478
return name ;
@@ -475,6 +495,7 @@ static String escapeName(String name, EscapingScheme scheme) {
475
495
}
476
496
return escaped .toString ();
477
497
case DOTS_ESCAPING :
498
+ // Do not early return for legacy valid names, we still escape underscores.
478
499
for (int i = 0 ; i < name .length (); i ++) {
479
500
char c = name .charAt (i );
480
501
if (c == '_' ) {
@@ -519,6 +540,9 @@ static String escapeName(String name, EscapingScheme scheme) {
519
540
}
520
541
}
521
542
543
+ // unescapeName unescapes the incoming name according to the provided escaping
544
+ // scheme if possible. Some schemes are partially or totally non-roundtripable.
545
+ // If any error is encountered, returns the original input.
522
546
static String unescapeName (String name , EscapingScheme scheme ) {
523
547
if (name .isEmpty ()) {
524
548
return name ;
0 commit comments