Skip to content

config.md

Latest commit

 

History

History
220 lines (157 loc) · 17.7 KB

config.md

File metadata and controls

220 lines (157 loc) · 17.7 KB
title Config
weight 1

{{< toc >}}

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]({{< relref "/exporters/httpserver.md" >}}) 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=9401 when starting your application.
  • Environment variables: Set IO_PROMETHEUS_EXPORTER_HTTP_SERVER_PORT=9401

Location of the Properties File

The properties file is searched in the following locations:

  • /prometheus.properties in 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.

Property Naming Conventions

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

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

Property Precedence

When the same property is defined in multiple sources, the following precedence order applies (highest to lowest):

  1. External properties (passed explicitly via API)
  2. Environment variables
  3. System properties (command line -D flags)
  4. Properties file (from file or classpath)

Metrics Properties

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.

Exemplar 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()

Exporter Properties

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.

Exporter Filter Properties

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.

Exporter HTTPServer Properties

Name Javadoc Note
io.prometheus.exporter.http_server.port HTTPServer.Builder.port()

Exporter OpenTelemetry Properties

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.

Exporter PushGateway Properties

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]({{< relref "../exporters/unicode.md" >}}).