From 73f6eeeaa543aa028a8acd5471ddb9aafcd2fcf9 Mon Sep 17 00:00:00 2001
From: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Date: Tue, 3 Nov 2026 13:48:05 +0000
Subject: [PATCH] docs: describe configuration sources and exporter options

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
---
 .../metrics/config/ExporterProperties.java    |  9 +++++-
 .../config/PrometheusPropertiesLoader.java    | 28 +++++++++++++++----
 2 files changed, 31 insertions(+), 6 deletions(-)

diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterProperties.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterProperties.java
index a1c67266a1..8d80139b2a 100644
--- a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterProperties.java
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/ExporterProperties.java
@@ -3,7 +3,14 @@
 import io.prometheus.metrics.annotations.StableApi;
 import javax.annotation.Nullable;
 
-/** Properties starting with io.prometheus.exporter */
+/**
+ * Configuration for common exporter behavior.
+ *
+ * <p>Properties use the {@code io.prometheus.exporter} prefix. Supported options are {@code
+ * include_created_timestamps}, {@code prometheus_timestamps_in_ms}, and {@code
+ * exemplars_on_all_metric_types}. Use {@link PrometheusPropertiesLoader} to load these options from
+ * configuration sources, or {@link #builder()} to create an instance directly.
+ */
 @StableApi
 public class ExporterProperties {
 
diff --git a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesLoader.java b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesLoader.java
index 26334a6ba4..940e7bd983 100644
--- a/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesLoader.java
+++ b/prometheus-metrics-config/src/main/java/io/prometheus/metrics/config/PrometheusPropertiesLoader.java
@@ -11,12 +11,20 @@
 import java.util.Set;
 
 /**
- * The Properties Loader is early stages.
+ * Loads Prometheus client configuration from supported property sources.
  *
- * <p>It would be great to implement a subset of <a
- * href="https://docs.spring.io/spring-boot/docs/3.1.x/reference/html/features.html#features.external-config">Spring
- * Boot's Externalized Configuration</a>, like support for YAML, Properties, and env vars, or
- * support for Spring's naming conventions for properties.
+ * <p>Configuration is read from a classpath {@code prometheus.properties} file, an optional
+ * properties file selected by {@code prometheus.config} or {@code PROMETHEUS_CONFIG}, Java system
+ * properties, {@code IO_PROMETHEUS_*} environment variables, and properties supplied explicitly to
+ * {@link #load(Map)}. Precedence is explicit properties, environment variables, system properties,
+ * the selected file, then the classpath file. {@code PROMETHEUS_CONFIG}, when set, takes precedence
+ * over the {@code prometheus.config} system property when selecting the optional file. Property
+ * names use dot-separated keys such as {@code io.prometheus.exporter.include_created_timestamps};
+ * environment variable names use underscores, such as {@code
+ * IO_PROMETHEUS_EXPORTER_INCLUDE_CREATED_TIMESTAMPS}.
+ *
+ * <p>Unrecognized properties under the {@code io.prometheus} or {@code io_prometheus} prefixes
+ * cause configuration loading to fail, which can help identify misspelled property names.
  */
 @StableApi
 public class PrometheusPropertiesLoader {
@@ -26,6 +34,16 @@ public static PrometheusProperties load() throws PrometheusPropertiesException {
     return load(new Properties());
   }
 
+  /**
+   * Loads configuration, using the supplied properties in addition to the standard property
+   * sources. Values in {@code externalProperties} take precedence over environment variables,
+   * system properties, and properties files.
+   *
+   * @param externalProperties properties supplied by the caller
+   * @return the loaded configuration
+   * @throws PrometheusPropertiesException if the selected properties file cannot be read or the
+   *     configuration contains an invalid or unrecognized property
+   */
   public static PrometheusProperties load(Map<Object, Object> externalProperties)
       throws PrometheusPropertiesException {
     PropertySource propertySource = loadProperties(externalProperties);