Skip to content

Commit 1956a75

Browse files
committed
Add some comments
Signed-off-by: Federico Torres <[email protected]>
1 parent a1b19ef commit 1956a75

File tree

5 files changed

+50
-0
lines changed

5 files changed

+50
-0
lines changed

prometheus-metrics-exposition-formats/src/main/java/io/prometheus/metrics/expositionformats/OpenMetricsTextFormatWriter.java

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -272,6 +272,8 @@ private void writeNameAndLabels(OutputStreamWriter writer, String name, String s
272272
private void writeNameAndLabels(OutputStreamWriter writer, String name, String suffix, Labels labels,
273273
String additionalLabelName, double additionalLabelValue) throws IOException {
274274
boolean metricInsideBraces = false;
275+
// If the name does not pass the legacy validity check, we must put the
276+
// metric name inside the braces.
275277
if (PrometheusNaming.validateLegacyMetricName(name) != null) {
276278
metricInsideBraces = true;
277279
writer.write('{');

prometheus-metrics-exposition-formats/src/main/java/io/prometheus/metrics/expositionformats/PrometheusTextFormatWriter.java

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -278,6 +278,8 @@ private void writeNameAndLabels(OutputStreamWriter writer, String name, String s
278278
private void writeNameAndLabels(OutputStreamWriter writer, String name, String suffix, Labels labels,
279279
String additionalLabelName, double additionalLabelValue) throws IOException {
280280
boolean metricInsideBraces = false;
281+
// If the name does not pass the legacy validity check, we must put the
282+
// metric name inside the braces.
281283
if (PrometheusNaming.validateLegacyMetricName(name) != null) {
282284
metricInsideBraces = true;
283285
writer.write('{');

prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/EscapingScheme.java

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,19 @@
44
import static io.prometheus.metrics.model.snapshots.PrometheusNaming.nameEscapingScheme;
55

66
public enum EscapingScheme {
7+
// NO_ESCAPING indicates that a name will not be escaped.
78
NO_ESCAPING("allow-utf-8"),
9+
10+
// UNDERSCORE_ESCAPING replaces all legacy-invalid characters with underscores.
811
UNDERSCORE_ESCAPING("underscores"),
12+
13+
// DOTS_ESCAPING is similar to UNDERSCORE_ESCAPING, except that dots are
14+
// converted to `_dot_` and pre-existing underscores are converted to `__`.
915
DOTS_ESCAPING("dots"),
16+
17+
// VALUE_ENCODING_ESCAPING prepends the name with `U__` and replaces all invalid
18+
// characters with the Unicode value, surrounded by underscores. Single
19+
// underscores are replaced with double underscores.
1020
VALUE_ENCODING_ESCAPING("values"),
1121
;
1222

@@ -20,6 +30,10 @@ public final String getValue() {
2030
this.value = value;
2131
}
2232

33+
// fromAcceptHeader returns an EscapingScheme depending on the Accept header. Iff the
34+
// header contains an escaping=allow-utf-8 term, it will select NO_ESCAPING. If a valid
35+
// "escaping" term exists, that will be used. Otherwise, the global default will
36+
// be returned.
2337
public static EscapingScheme fromAcceptHeader(String acceptHeader) {
2438
for (String p : acceptHeader.split(";")) {
2539
String[] toks = p.split("=");
@@ -32,6 +46,7 @@ public static EscapingScheme fromAcceptHeader(String acceptHeader) {
3246
try {
3347
return EscapingScheme.forString(value);
3448
} catch (IllegalArgumentException e) {
49+
// If the escaping parameter is unknown, ignore it.
3550
return nameEscapingScheme;
3651
}
3752
}

prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/PrometheusNaming.java

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,23 @@
1818
* in Prometheus exposition formats. However, if metrics are exposed in OpenTelemetry format the dots are retained.
1919
*/
2020
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.
2126
public static ValidationScheme nameValidationScheme = initValidationScheme();
2227

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.
2331
public static EscapingScheme nameEscapingScheme = EscapingScheme.VALUE_ENCODING_ESCAPING;
2432

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.
2538
public static final String ESCAPING_KEY = "escaping";
2639

2740
private static final String LOWERHEX = "0123456789abcdef";
@@ -258,6 +271,8 @@ private static String replaceIllegalCharsInLabelName(String name) {
258271
return new String(sanitized);
259272
}
260273

274+
// escapeMetricSnapshot escapes the given metric names and labels with the given
275+
// escaping scheme.
261276
public static MetricSnapshot escapeMetricSnapshot(MetricSnapshot v, EscapingScheme scheme) {
262277
if (v == null) {
263278
return null;
@@ -269,6 +284,7 @@ public static MetricSnapshot escapeMetricSnapshot(MetricSnapshot v, EscapingSche
269284

270285
String outName;
271286

287+
// If the name is null, copy as-is, don't try to escape.
272288
if (v.getMetadata().getPrometheusName() == null || isValidLegacyMetricName(v.getMetadata().getPrometheusName())) {
273289
outName = v.getMetadata().getPrometheusName();
274290
} else {
@@ -453,6 +469,10 @@ static boolean metricNeedsEscaping(DataPointSnapshot d) {
453469
return false;
454470
}
455471

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.
456476
static String escapeName(String name, EscapingScheme scheme) {
457477
if (name.isEmpty()) {
458478
return name;
@@ -475,6 +495,7 @@ static String escapeName(String name, EscapingScheme scheme) {
475495
}
476496
return escaped.toString();
477497
case DOTS_ESCAPING:
498+
// Do not early return for legacy valid names, we still escape underscores.
478499
for (int i = 0; i < name.length(); i++) {
479500
char c = name.charAt(i);
480501
if (c == '_') {
@@ -519,6 +540,9 @@ static String escapeName(String name, EscapingScheme scheme) {
519540
}
520541
}
521542

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.
522546
static String unescapeName(String name, EscapingScheme scheme) {
523547
if (name.isEmpty()) {
524548
return name;
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,13 @@
11
package io.prometheus.metrics.model.snapshots;
22

3+
// ValidationScheme is an enum for determining how metric and label names will
4+
// be validated by this library.
35
public enum ValidationScheme {
6+
// LEGACY_VALIDATION is a setting that requires that metric and label names
7+
// conform to the original character requirements.
48
LEGACY_VALIDATION,
9+
10+
// UTF_8_VALIDATION only requires that metric and label names be valid UTF-8
11+
// strings.
512
UTF_8_VALIDATION
613
}

0 commit comments

Comments
 (0)