@@ -160,7 +160,7 @@ func HandlerForTransactional(reg prometheus.TransactionalGatherer, opts HandlerO
160160 }
161161
162162 var contentType expfmt.Format
163- if opts .EnableOpenMetrics {
163+ if opts .EnableOpenMetrics || opts . OpenMetricsOptions . Enable {
164164 contentType = expfmt .NegotiateIncludingOpenMetrics (req .Header )
165165 } else {
166166 contentType = expfmt .Negotiate (req .Header )
@@ -181,7 +181,7 @@ func HandlerForTransactional(reg prometheus.TransactionalGatherer, opts HandlerO
181181 }
182182
183183 var enc expfmt.Encoder
184- if opts .EnableOpenMetricsCreatedMetrics {
184+ if opts .OpenMetricsOptions . EnableCreatedTimestamps {
185185 enc = expfmt .NewEncoder (w , contentType , expfmt .WithCreatedLines ())
186186 } else {
187187 enc = expfmt .NewEncoder (w , contentType )
@@ -366,31 +366,11 @@ type HandlerOpts struct {
366366 // away). Until the implementation is improved, it is recommended to
367367 // implement a separate timeout in potentially slow Collectors.
368368 Timeout time.Duration
369- // If true, the experimental OpenMetrics encoding is added to the
370- // possible options during content negotiation. Note that Prometheus
371- // 2.5.0+ will negotiate OpenMetrics as first priority. OpenMetrics is
372- // the only way to transmit exemplars. However, the move to OpenMetrics
373- // is not completely transparent. Most notably, the values of "quantile"
374- // labels of Summaries and "le" labels of Histograms are formatted with
375- // a trailing ".0" if they would otherwise look like integer numbers
376- // (which changes the identity of the resulting series on the Prometheus
377- // server).
369+ // Deprecated: Use OpenMetricsOptions.Enable instead.
378370 EnableOpenMetrics bool
379- // If 'EnableOpenMetrics' is true, 'EnableOpenMetricsCreatedMetrics' allows
380- // to add extra '_created' lines for counters, histograms and summaries,
381- // as defined in the OpenMetrics specification (see
382- // https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#counter-1).
383- // Created timestamps are used to improve the accuracy of reset detection,
384- // but be aware that it also increases the size of the payload.
385- //
386- // Prometheus introduced the feature flag 'created-timestamp-zero-ingestion'
387- // in version 2.50.0, but with support limited to the Prometheus protobuf
388- // format. Starting in Prometheus XXXX, the feature flag will be extended
389- // to the OpenMetrics text format. If using Prometheus XXXX or later, it
390- // is recommended to enable the feature flag in Prometheus, otherwise enabling
391- // _created lines will result in increased cardinality and no improvements
392- // in reset detection.
393- EnableOpenMetricsCreatedMetrics bool
371+ // OpenMetricsOptions holds settings for the experimental OpenMetrics encoding.
372+ // It can be used to enable OpenMetrics encoding and for setting extra options.
373+ OpenMetricsOptions OpenMetricsOptions
394374 // ProcessStartTime allows setting process start timevalue that will be exposed
395375 // with "Process-Start-Time-Unix" response header along with the metrics
396376 // payload. This allow callers to have efficient transformations to cumulative
@@ -401,6 +381,43 @@ type HandlerOpts struct {
401381 ProcessStartTime time.Time
402382}
403383
384+ type OpenMetricsOptions struct {
385+ // Enable specifies if the experimental OpenMetrics encoding is added to the
386+ // possible options during content negotiation.
387+ //
388+ // Note that Prometheus 2.5.0+ might negotiate OpenMetrics Text format
389+ // as first priority unless user uses custom scrape protocol prioritization or
390+ // histograms feature is enabled (then Prometheus proto format is prioritized,
391+ // which client_golang supports).
392+ //
393+ // Keep in mind that the move to OpenMetrics is not completely transparent. Most notably,
394+ // the values of "quantile" labels of Summaries and "le" labels of Histograms are
395+ // formatted with a trailing ".0" if they would otherwise look like integer numbers
396+ // (which changes the identity of the resulting series on the Prometheus
397+ // server).
398+ //
399+ // See other options in OpenMetricsOptions to learn how to enable some special
400+ // features e.g. potentially dangerous created timestamp series.
401+ Enable bool
402+ // EnableCreatedTimestamps specifies if this handler should add, extra, synthetic
403+ // Created Timestamps for counters, histograms and summaries, which for the current
404+ // version of OpenMetrics are defined as extra series with the same name and "_created"
405+ // suffix. See also the OpenMetrics specification for more details
406+ // https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#counter-1
407+ //
408+ // Created timestamps are used to improve the accuracy of reset detection,
409+ // but the way it's designed in OpenMetrics 1.0 it also dramatically increases cardinality
410+ // if the scraper does not handle those metrics correctly (converting to created timestamp
411+ // instead of leaving those series as-is). New OpenMetrics versions might improve
412+ // this situation.
413+ //
414+ // Prometheus introduced the feature flag 'created-timestamp-zero-ingestion'
415+ // in version 2.50.0, but only for the Prometheus protobuf format. Starting in
416+ // future Prometheus version, the feature flag will be extended to the OpenMetrics
417+ // text format, thus safe to be enabled to improve accuracy of counters in Prometheus.
418+ EnableCreatedTimestamps bool
419+ }
420+
404421// gzipAccepted returns whether the client will accept gzip-encoded content.
405422func gzipAccepted (header http.Header ) bool {
406423 a := header .Get (acceptEncodingHeader )
0 commit comments