Config
The Prometheus metrics library provides multiple options how to override configuration at runtime:
- Properties file
- System properties
- Environment variables
Example:
io.prometheus.exporter.http_server.port=9401
The property above changes the port for the HTTPServer exporter to 9401.
- Properties file: Add the line above to the properties file.
- System properties: Use the command line parameter
-Dio.prometheus.exporter.http_server.port=9401when starting your application. - Environment variables: Set
IO_PROMETHEUS_EXPORTER_HTTP_SERVER_PORT=9401
The properties file is searched in the following locations:
/prometheus.propertiesin the classpath. This is for bundling a properties file with your application.- System property
-Dprometheus.config=/path/to/prometheus.properties. - Environment variable
PROMETHEUS_CONFIG=/path/to/prometheus.properties.
Properties use snake_case format with underscores separating words
(e.g., http_server, exemplars_enabled).
For backward compatibility, camelCase property names are also supported in properties files and system properties, but snake_case is the preferred format.
Environment variables follow standard conventions:
- All uppercase letters:
IO_PROMETHEUS_EXPORTER_HTTP_SERVER_PORT - Underscores for all separators (both package and word boundaries)
- Prefix must be
IO_PROMETHEUS
The library automatically converts environment variables to the correct property format.
Examples:
| Environment Variable | Property Equivalent |
|---|---|
IO_PROMETHEUS_METRICS_EXEMPLARS_ENABLED | io.prometheus.metrics.exemplars_enabled |
IO_PROMETHEUS_EXPORTER_HTTP_SERVER_PORT | io.prometheus.exporter.http_server.port |
IO_PROMETHEUS_METRICS_HISTOGRAM_NATIVE_ONLY | io.prometheus.metrics.histogram_native_only |
When the same property is defined in multiple sources, the following precedence order applies (highest to lowest):
- External properties (passed explicitly via API)
- Environment variables
- System properties (command line
-Dflags) - Properties file (from file or classpath)
| Name | Javadoc | Note |
|---|---|---|
| io.prometheus.metrics.exemplars_enabled | Counter.Builder.withExemplars() | (1) (2) |
| io.prometheus.metrics.histogram_native_only | Histogram.Builder.nativeOnly() | (2) |
| io.prometheus.metrics.histogram_classic_only | Histogram.Builder.classicOnly() | (2) |
| io.prometheus.metrics.histogram_classic_upper_bounds | Histogram.Builder.classicUpperBounds() | (3) |
| io.prometheus.metrics.histogram_native_initial_schema | Histogram.Builder.nativeInitialSchema() | |
| io.prometheus.metrics.histogram_native_min_zero_threshold | Histogram.Builder.nativeMinZeroThreshold() | |
| io.prometheus.metrics.histogram_native_max_zero_threshold | Histogram.Builder.nativeMaxZeroThreshold() | |
| io.prometheus.metrics.histogram_native_max_number_of_buckets | Histogram.Builder.nativeMaxNumberOfBuckets() | |
| io.prometheus.metrics.histogram_native_reset_duration_seconds | Histogram.Builder.nativeResetDuration() | |
| io.prometheus.metrics.summary_quantiles | Summary.Builder.quantile(double) | (4) |
| io.prometheus.metrics.summary_quantile_errors | Summary.Builder.quantile(double, double) | (5) |
| io.prometheus.metrics.summary_max_age_seconds | Summary.Builder.maxAgeSeconds() | |
| io.prometheus.metrics.summary_number_of_age_buckets | Summary.Builder.numberOfAgeBuckets() |
Notes
(1) withExemplars() and withoutExemplars() are available for all metric types,
not just for counters
(2) Boolean value. Format: property=true or property=false.
(3) Comma-separated list. Example: .005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10.
(4) Comma-separated list. Example: 0.5, 0.95, 0.99.
(5) Comma-separated list. If specified, the list must have the same length as
io.prometheus.metrics.summary_quantiles. Example: 0.01, 0.005, 0.005.
There’s one special feature about metric properties: You can set a property for one specific
metric only by specifying the metric name. Example:
Let’s say you have a histogram named latency_seconds.
io.prometheus.metrics.histogram_classic_upper_bounds=0.2, 0.4, 0.8, 1.0
The line above sets histogram buckets for all histograms. However:
io.prometheus.metrics.latency_seconds.histogram_classic_upper_bounds=0.2, 0.4, 0.8, 1.0
The line above sets histogram buckets only for the histogram named latency_seconds.
This works for all Metrics properties.
| Name | Javadoc | Note |
|---|---|---|
| io.prometheus.exemplars.min_retention_period_seconds | ExemplarsProperties.getMinRetentionPeriodSeconds() | |
| io.prometheus.exemplars.max_retention_period_seconds | ExemplarsProperties.getMaxRetentionPeriodSeconds() | |
| io.prometheus.exemplars.sample_interval_milliseconds | ExemplarsProperties.getSampleIntervalMilliseconds() |
| Name | Javadoc | Note |
|---|---|---|
| io.prometheus.exporter.include_created_timestamps | ExporterProperties.getIncludeCreatedTimestamps() | (1) |
| io.prometheus.exporter.exemplars_on_all_metric_types | ExporterProperties.getExemplarsOnAllMetricTypes() | (1) |
(1) Boolean value, true or false. Default see Javadoc.
| Name | Javadoc | Note |
|---|---|---|
| io.prometheus.exporter.filter.metric_name_must_be_equal_to | ExporterFilterProperties.getAllowedMetricNames() | (1) |
| io.prometheus.exporter.filter.metric_name_must_not_be_equal_to | ExporterFilterProperties.getExcludedMetricNames() | (2) |
| io.prometheus.exporter.filter.metric_name_must_start_with | ExporterFilterProperties.getAllowedMetricNamePrefixes() | (3) |
| io.prometheus.exporter.filter.metric_name_must_not_start_with | ExporterFilterProperties.getExcludedMetricNamePrefixes() | (4) |
(1) Comma separated list of allowed metric names. Only these metrics will be exposed.
(2) Comma separated list of excluded metric names. These metrics will not be exposed.
(3) Comma separated list of prefixes.
Only metrics starting with these prefixes will be exposed.
(4) Comma separated list of prefixes. Metrics starting with these prefixes will not be exposed.
| Name | Javadoc | Note |
|---|---|---|
| io.prometheus.exporter.http_server.port | HTTPServer.Builder.port() |
| Name | Javadoc | Note |
|---|---|---|
| io.prometheus.exporter.opentelemetry.protocol | OpenTelemetryExporter.Builder.protocol() | (1) |
| io.prometheus.exporter.opentelemetry.endpoint | OpenTelemetryExporter.Builder.endpoint() | |
| io.prometheus.exporter.opentelemetry.headers | OpenTelemetryExporter.Builder.headers() | (2) |
| io.prometheus.exporter.opentelemetry.interval_seconds | OpenTelemetryExporter.Builder.intervalSeconds() | |
| io.prometheus.exporter.opentelemetry.timeout_seconds | OpenTelemetryExporter.Builder.timeoutSeconds() | |
| io.prometheus.exporter.opentelemetry.service_name | OpenTelemetryExporter.Builder.serviceName() | |
| io.prometheus.exporter.opentelemetry.service_namespace | OpenTelemetryExporter.Builder.serviceNamespace() | |
| io.prometheus.exporter.opentelemetry.service_instance_id | OpenTelemetryExporter.Builder.serviceInstanceId() | |
| io.prometheus.exporter.opentelemetry.service_version | OpenTelemetryExporter.Builder.serviceVersion() | |
| io.prometheus.exporter.opentelemetry.resource_attributes | OpenTelemetryExporter.Builder.resourceAttributes() | (3) |
(1) Protocol can be grpc or http/protobuf.
(2) Format: key1=value1,key2=value2
(3) Format: key1=value1,key2=value2
Many of these attributes can alternatively be configured via OpenTelemetry environment variables,
like OTEL_EXPORTER_OTLP_ENDPOINT.
The Prometheus metrics library has support for OpenTelemetry environment variables.
See Javadoc for details.
| Name | Javadoc | Note |
|---|---|---|
| io.prometheus.exporter.pushgateway.address | PushGateway.Builder.address() | |
| io.prometheus.exporter.pushgateway.scheme | PushGateway.Builder.scheme() | |
| io.prometheus.exporter.pushgateway.job | PushGateway.Builder.job() | |
| io.prometheus.exporter.pushgateway.escaping_scheme | PushGateway.Builder.escapingScheme() | (1) |
(1) Escaping scheme can be allow-utf-8, underscores, dots, or values as described in
escaping schemes and in the Unicode documentation.