Skip to content

Commit ffc8609

Browse files
zeitlingerzeitlinger
committed
docs
Signed-off-by: Gregor Zeitlinger <[email protected]>
1 parent 330eb16 commit ffc8609

File tree

10 files changed

+46
-30
lines changed

10 files changed

+46
-30
lines changed

‎docs/content/config/config.md‎

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ Future releases will add more options, like configuration via environment variab
1515
Example:
1616

1717
```properties
18-
io.prometheus.exporter.httpServer.port = 9401
18+
io.prometheus.exporter.httpServer.port=9401
1919
```
2020

2121
The property above changes the port for the
@@ -39,7 +39,7 @@ The properties file is searched in the following locations:
3939
<!-- editorconfig-checker-disable -->
4040

4141
| Name | Javadoc | Note |
42-
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
42+
|-----------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
4343
| io.prometheus.metrics.exemplarsEnabled | [Counter.Builder.withExemplars()](</client_java/api/io/prometheus/metrics/core/metrics/Counter.Builder.html#withExemplars()>) | (1) (2) |
4444
| io.prometheus.metrics.histogramNativeOnly | [Histogram.Builder.nativeOnly()](</client_java/api/io/prometheus/metrics/core/metrics/Histogram.Builder.html#nativeOnly()>) | (2) |
4545
| io.prometheus.metrics.histogramClassicOnly | [Histogram.Builder.classicOnly()](</client_java/api/io/prometheus/metrics/core/metrics/Histogram.Builder.html#classicOnly()>) | (2) |
@@ -71,13 +71,13 @@ metric only by specifying the metric name. Example:
7171
Let's say you have a histogram named `latency_seconds`.
7272

7373
```properties
74-
io.prometheus.metrics.histogramClassicUpperBounds = 0.2, 0.4, 0.8, 1.0
74+
io.prometheus.metrics.histogramClassicUpperBounds=0.2, 0.4, 0.8, 1.0
7575
```
7676

7777
The line above sets histogram buckets for all histograms. However:
7878

7979
```properties
80-
io.prometheus.metrics.latency_seconds.histogramClassicUpperBounds = 0.2, 0.4, 0.8, 1.0
80+
io.prometheus.metrics.latency_seconds.histogramClassicUpperBounds=0.2, 0.4, 0.8, 1.0
8181
```
8282

8383
The line above sets histogram buckets only for the histogram named `latency_seconds`.
@@ -89,7 +89,7 @@ This works for all Metrics properties.
8989
<!-- editorconfig-checker-disable -->
9090

9191
| Name | Javadoc | Note |
92-
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
92+
|----------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
9393
| io.prometheus.exemplars.minRetentionPeriodSeconds | [ExemplarsProperties.getMinRetentionPeriodSeconds()](</client_java/api/io/prometheus/metrics/config/ExemplarsProperties.html#getMinRetentionPeriodSeconds()>) | |
9494
| io.prometheus.exemplars.maxRetentionPeriodSeconds | [ExemplarsProperties.getMaxRetentionPeriodSeconds()](</client_java/api/io/prometheus/metrics/config/ExemplarsProperties.html#getMaxRetentionPeriodSeconds()>) | |
9595
| io.prometheus.exemplars.sampleIntervalMilliseconds | [ExemplarsProperties.getSampleIntervalMilliseconds()](</client_java/api/io/prometheus/metrics/config/ExemplarsProperties.html#getSampleIntervalMilliseconds()>) | |
@@ -101,7 +101,7 @@ This works for all Metrics properties.
101101
<!-- editorconfig-checker-disable -->
102102

103103
| Name | Javadoc | Note |
104-
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
104+
|--------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
105105
| io.prometheus.exporter.includeCreatedTimestamps | [ExporterProperties.getIncludeCreatedTimestamps()](</client_java/api/io/prometheus/metrics/config/ExporterProperties.html#getIncludeCreatedTimestamps()>) | (1) |
106106
| io.prometheus.exporter.exemplarsOnAllMetricTypes | [ExporterProperties.getExemplarsOnAllMetricTypes()](</client_java/api/io/prometheus/metrics/config/ExporterProperties.html#getExemplarsOnAllMetricTypes()>) | (1) |
107107

@@ -114,7 +114,7 @@ This works for all Metrics properties.
114114
<!-- editorconfig-checker-disable -->
115115

116116
| Name | Javadoc | Note |
117-
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
117+
|----------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
118118
| io.prometheus.exporter.filter.metricNameMustBeEqualTo | [ExporterFilterProperties.getAllowedMetricNames()](</client_java/api/io/prometheus/metrics/config/ExporterFilterProperties.html#getAllowedMetricNames()>) | (1) |
119119
| io.prometheus.exporter.filter.metricNameMustNotBeEqualTo | [ExporterFilterProperties.getExcludedMetricNames()](</client_java/api/io/prometheus/metrics/config/ExporterFilterProperties.html#getExcludedMetricNames()>) | (2) |
120120
| io.prometheus.exporter.filter.metricNameMustStartWith | [ExporterFilterProperties.getAllowedMetricNamePrefixes()](</client_java/api/io/prometheus/metrics/config/ExporterFilterProperties.html#getAllowedMetricNamePrefixes()>) | (3) |
@@ -133,7 +133,7 @@ Only metrics starting with these prefixes will be exposed.<br/>
133133
<!-- editorconfig-checker-disable -->
134134

135135
| Name | Javadoc | Note |
136-
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---- |
136+
|----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------|------|
137137
| io.prometheus.exporter.httpServer.port | [HTTPServer.Builder.port()](</client_java/api/io/prometheus/metrics/exporter/httpserver/HTTPServer.Builder.html#port(int)>) | |
138138

139139
<!-- editorconfig-checker-enable -->
@@ -143,7 +143,7 @@ Only metrics starting with these prefixes will be exposed.<br/>
143143
<!-- editorconfig-checker-disable -->
144144

145145
| Name | Javadoc | Note |
146-
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
146+
|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
147147
| io.prometheus.exporter.opentelemetry.protocol | [OpenTelemetryExporter.Builder.protocol()](</client_java/api/io/prometheus/metrics/exporter/opentelemetry/OpenTelemetryExporter.Builder.html#protocol(java.lang.String)>) | (1) |
148148
| io.prometheus.exporter.opentelemetry.endpoint | [OpenTelemetryExporter.Builder.endpoint()](</client_java/api/io/prometheus/metrics/exporter/opentelemetry/OpenTelemetryExporter.Builder.html#endpoint(java.lang.String)>) | |
149149
| io.prometheus.exporter.opentelemetry.headers | [OpenTelemetryExporter.Builder.headers()](</client_java/api/io/prometheus/metrics/exporter/opentelemetry/OpenTelemetryExporter.Builder.html#header(java.lang.String,java.lang.String)>) | (2) |
@@ -170,10 +170,14 @@ See Javadoc for details.
170170

171171
<!-- editorconfig-checker-disable -->
172172

173-
| Name | Javadoc | Note |
174-
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---- |
175-
| io.prometheus.exporter.pushgateway.address | [PushGateway.Builder.address()](</client_java/api/io/prometheus/metrics/exporter/pushgateway/PushGateway.Builder.html#address(java.lang.String)>) | |
176-
| io.prometheus.exporter.pushgateway.scheme | [PushGateway.Builder.scheme()](</client_java/api/io/prometheus/metrics/exporter/pushgateway/PushGateway.Builder.html#scheme(java.lang.String)>) | |
177-
| io.prometheus.exporter.pushgateway.job | [PushGateway.Builder.job()](</client_java/api/io/prometheus/metrics/exporter/pushgateway/PushGateway.Builder.html#job(java.lang.String)>) | |
173+
| Name | Javadoc | Note |
174+
|---------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------|
175+
| io.prometheus.exporter.pushgateway.address | [PushGateway.Builder.address()](</client_java/api/io/prometheus/metrics/exporter/pushgateway/PushGateway.Builder.html#address(java.lang.String)>) | |
176+
| io.prometheus.exporter.pushgateway.scheme | [PushGateway.Builder.scheme()](</client_java/api/io/prometheus/metrics/exporter/pushgateway/PushGateway.Builder.html#scheme(java.lang.String)>) | |
177+
| io.prometheus.exporter.pushgateway.job | [PushGateway.Builder.job()](</client_java/api/io/prometheus/metrics/exporter/pushgateway/PushGateway.Builder.html#job(java.lang.String)>) | |
178+
| io.prometheus.exporter.pushgateway.escapingScheme | [PushGateway.Builder.escapingScheme()](</client_java/api/io/prometheus/metrics/exporter/pushgateway/PushGateway.Builder.html#escapingScheme(io.prometheus.metrics.config.EscapingScheme)>) | (1) |
178179

179180
<!-- editorconfig-checker-enable -->
181+
182+
(1) Escaping scheme can be `allow-utf-8`, `underscores`, `dots`, or `values` as described in
183+
[escaping schemes](https://github.com/prometheus/docs/blob/main/docs/instrumenting/escaping_schemes.md#escaping-schemes)

‎docs/content/exporters/unicode.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,10 @@ character set (`a-zA-Z0-9_:`), with underscores by default.
2020
When `escaping=allow-utf-8` is passed, add valid UTF-8 characters to the metric and label names
2121
without replacing them. This allows you to use dots in metric and label names, as well as
2222
other UTF-8 characters, without any replacements.
23+
24+
## PushGateway
25+
26+
When using the [Pushgateway](/exporters/pushgateway/), Unicode support has to be enabled
27+
explicitly by setting `io.prometheus.exporter.pushgateway.escapingScheme` to `allow-utf-8` in the
28+
Pushgateway configuration file - see
29+
[Pushgateway configuration]({{< relref "/config/config.md#exporter-pushgateway-properties" >}})

‎prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/EscapingScheme.java‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
package io.prometheus.metrics.config;
22

3+
import javax.annotation.Nullable;
4+
35
public enum EscapingScheme {
46
/** NO_ESCAPING indicates that a name will not be escaped. */
57
NO_ESCAPING("allow-utf-8"),
@@ -40,7 +42,7 @@ public final String getValue() {
4042
* contains an escaping=allow-utf-8 term, it will select NO_ESCAPING. If a valid "escaping" term
4143
* exists, that will be used. Otherwise, the global default will be returned.
4244
*/
43-
public static EscapingScheme fromAcceptHeader(String acceptHeader) {
45+
public static EscapingScheme fromAcceptHeader(@Nullable String acceptHeader) {
4446
if (acceptHeader != null) {
4547
for (String p : acceptHeader.split(";")) {
4648
String[] toks = p.split("=");

‎prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterPushgatewayProperties.java‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -85,7 +85,7 @@ static ExporterPushgatewayProperties load(Map<Object, Object> properties)
8585
return null;
8686
}
8787
switch (scheme) {
88-
case "no-escaping":
88+
case "allow-utf-8":
8989
return EscapingScheme.NO_ESCAPING;
9090
case "values":
9191
return EscapingScheme.VALUE_ENCODING_ESCAPING;
@@ -96,7 +96,7 @@ static ExporterPushgatewayProperties load(Map<Object, Object> properties)
9696
default:
9797
throw new PrometheusPropertiesException(
9898
String.format(
99-
"%s.%s: Illegal value. Expecting 'no-escaping', 'values', 'underscores', "
99+
"%s.%s: Illegal value. Expecting 'allow-utf-8', 'values', 'underscores', "
100100
+ "or 'dots'. Found: %s",
101101
PREFIX, ESCAPING_SCHEME, scheme));
102102
}
@@ -110,6 +110,7 @@ public static class Builder {
110110
@Nullable private String address;
111111
@Nullable private String job;
112112
@Nullable private String scheme;
113+
@Nullable private EscapingScheme escapingScheme;
113114

114115
private Builder() {}
115116

@@ -128,8 +129,13 @@ public Builder scheme(String scheme) {
128129
return this;
129130
}
130131

132+
public Builder escapingScheme(EscapingScheme escapingScheme) {
133+
this.escapingScheme = escapingScheme;
134+
return this;
135+
}
136+
131137
public ExporterPushgatewayProperties build() {
132-
return new ExporterPushgatewayProperties(address, job, scheme);
138+
return new ExporterPushgatewayProperties(address, job, scheme, escapingScheme);
133139
}
134140
}
135141
}

‎prometheus-metrics-config/src/test/java/io/prometheus/metrics/config/ExporterPushgatewayPropertiesTest.java‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,10 +40,12 @@ void builder() {
4040
.address("http://localhost")
4141
.job("job")
4242
.scheme("http")
43+
.escapingScheme(EscapingScheme.DOTS_ESCAPING)
4344
.build();
4445

4546
assertThat(properties.getAddress()).isEqualTo("http://localhost");
4647
assertThat(properties.getJob()).isEqualTo("job");
4748
assertThat(properties.getScheme()).isEqualTo("http");
49+
assertThat(properties.getEscapingScheme()).isEqualTo(EscapingScheme.DOTS_ESCAPING);
4850
}
4951
}

‎prometheus-metrics-exporter-pushgateway/src/main/java/io/prometheus/metrics/exporter/pushgateway/PushGateway.java‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -439,11 +439,11 @@ private String getJob(@Nullable ExporterPushgatewayProperties properties) {
439439
}
440440
}
441441

442-
private EscapingScheme getEscapingScheme(ExporterPushgatewayProperties properties) {
442+
private EscapingScheme getEscapingScheme(@Nullable ExporterPushgatewayProperties properties) {
443443
if (properties != null && properties.getEscapingScheme() != null) {
444444
return properties.getEscapingScheme();
445445
}
446-
return EscapingScheme.NO_ESCAPING;
446+
return EscapingScheme.UNDERSCORE_ESCAPING;
447447
}
448448

449449
private Format getFormat() {

‎prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/CounterSnapshot.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ public CounterDataPointSnapshot(
8282
public CounterDataPointSnapshot(
8383
double value,
8484
Labels labels,
85-
Exemplar exemplar,
85+
@Nullable Exemplar exemplar,
8686
long createdTimestampMillis,
8787
long scrapeTimestampMillis,
8888
boolean internal) {

‎prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/GaugeSnapshot.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,7 @@ public GaugeDataPointSnapshot(
7171
private GaugeDataPointSnapshot(
7272
double value,
7373
Labels labels,
74-
Exemplar exemplar,
74+
@Nullable Exemplar exemplar,
7575
long scrapeTimestampMillis,
7676
boolean internal) {
7777
super(labels, 0L, scrapeTimestampMillis, internal);

‎prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/SnapshotEscaper.java‎

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,7 @@ public class SnapshotEscaper {
1010
private SnapshotEscaper() {}
1111

1212
/** Escapes the given metric names and labels with the given escaping scheme. */
13-
@Nullable
14-
public static MetricSnapshot escapeMetricSnapshot(
15-
@Nullable MetricSnapshot v, EscapingScheme scheme) {
16-
if (v == null) {
17-
return null;
18-
}
19-
13+
public static MetricSnapshot escapeMetricSnapshot(MetricSnapshot v, EscapingScheme scheme) {
2014
if (scheme == EscapingScheme.NO_ESCAPING || scheme == EscapingScheme.UNDERSCORE_ESCAPING) {
2115
// we re-use the prometheus name for underscore escaping as an optimization
2216
return v;
@@ -120,6 +114,7 @@ public static Exemplars escapeExemplars(Exemplars exemplars, EscapingScheme sche
120114
return Exemplars.of(escapedExemplars);
121115
}
122116

117+
@Nullable
123118
public static Exemplar escapeExemplar(@Nullable Exemplar exemplar, EscapingScheme scheme) {
124119
if (exemplar == null) {
125120
return null;

‎prometheus-metrics-model/src/main/java/io/prometheus/metrics/model/snapshots/UnknownSnapshot.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ public UnknownDataPointSnapshot(
7272
private UnknownDataPointSnapshot(
7373
double value,
7474
Labels labels,
75-
Exemplar exemplar,
75+
@Nullable Exemplar exemplar,
7676
long scrapeTimestampMillis,
7777
boolean internal) {
7878
super(labels, 0L, scrapeTimestampMillis, internal);

0 commit comments

Comments
 (0)