expfmt/encoder: Allow opt-in for OM created lines

Arthur Silva Sens · Arthur Silva Sens · commit 38e075889e79 · 2024-02-18T14:38:48.000-03:00
Signed-off-by: Arthur Silva Sens &lt;arthur.sens@coralogix.com&gt;
diff --git a/expfmt/encode.go b/expfmt/encode.go
@@ -139,7 +139,13 @@ func NegotiateIncludingOpenMetrics(h http.Header) Format {
 // interface is kept for backwards compatibility.
 // In cases where the Format does not allow for UTF-8 names, the global
 // NameEscapingScheme will be applied.
-func NewEncoder(w io.Writer, format Format) Encoder {
+//
+// NewEncoder can be called with additional options to customize the OpenMetrics text output.
+// For example:
+// NewEncoder(w, FmtOpenMetrics_1_0_0, WithCreatedLines())
+//
+// Extra options are ignored for all other formats.
+func NewEncoder(w io.Writer, format Format, options ...EncoderOption) Encoder {
 	escapingScheme := format.ToEscapingScheme()
 
 	switch format.FormatType() {
@@ -178,7 +184,7 @@ func NewEncoder(w io.Writer, format Format) Encoder {
 	case TypeOpenMetrics:
 		return encoderCloser{
 			encode: func(v *dto.MetricFamily) error {
-				_, err := MetricFamilyToOpenMetrics(w, model.EscapeMetricFamily(v, escapingScheme))
+				_, err := MetricFamilyToOpenMetrics(w, model.EscapeMetricFamily(v, escapingScheme), options...)
 				return err
 			},
 			close: func() error {
diff --git a/expfmt/openmetrics_create.go b/expfmt/openmetrics_create.go
@@ -28,14 +28,24 @@ import (
 	dto "github.com/prometheus/client_model/go"
 )
 
-type toOpenMetrics struct {
+type encoderOption struct {
 	withCreatedLines bool
 }
 
-type ToOpenMetricsOption func(*toOpenMetrics)
+type EncoderOption func(*encoderOption)
 
-func WithCreatedLines() ToOpenMetricsOption {
-	return func(t *toOpenMetrics) {
+// WithCreatedLines is an EncoderOption that configures the OpenMetrics encoder
+// to include _created lines (See
+// https://github.com/OpenObservability/OpenMetrics/blob/main/specification/OpenMetrics.md#counter-1).
+// Created timestamps can improve the accuracy of series reset detection, but
+// come with a bandwidth cost.
+//
+// At the time of writing, created timestamp ingestion is still experimental in
+// Prometheus and need to be enabled with the feature-flag
+// `--feature-flag=created-timestamp-zero-ingestion`, and breaking changes are
+// still possible. Therefore, it is recommended to use this feature with caution.
+func WithCreatedLines() EncoderOption {
+	return func(t *encoderOption) {
 		t.withCreatedLines = true
 	}
 }
@@ -85,8 +95,8 @@ func WithCreatedLines() ToOpenMetricsOption {
 //
 //   - The value of Counters is not checked. (OpenMetrics doesn't allow counters
 //     with a `NaN` value.)
-func MetricFamilyToOpenMetrics(out io.Writer, in *dto.MetricFamily, options ...ToOpenMetricsOption) (written int, err error) {
-	toOM := toOpenMetrics{}
+func MetricFamilyToOpenMetrics(out io.Writer, in *dto.MetricFamily, options ...EncoderOption) (written int, err error) {
+	toOM := encoderOption{}
 	for _, option := range options {
 		option(&toOM)
 	}
diff --git a/expfmt/openmetrics_create_test.go b/expfmt/openmetrics_create_test.go
@@ -42,7 +42,7 @@ func TestCreateOpenMetrics(t *testing.T) {
 
 	scenarios := []struct {
 		in      *dto.MetricFamily
-		options []ToOpenMetricsOption
+		options []EncoderOption
 		out     string
 	}{
 		// 0: Counter, timestamp given, no _total suffix.
@@ -343,7 +343,7 @@ unknown_name{name_1="value 1"} -1.23e-45
 					},
 				},
 			},
-			options: []ToOpenMetricsOption{WithCreatedLines()},
+			options: []EncoderOption{WithCreatedLines()},
 			out: `# HELP summary_name summary docstring
 # TYPE summary_name summary
 summary_name{quantile="0.5"} -1.23
@@ -398,7 +398,7 @@ summary_name_created{name_1="value 1",name_2="value 2"} 12345.6
 					},
 				},
 			},
-			options: []ToOpenMetricsOption{WithCreatedLines()},
+			options: []EncoderOption{WithCreatedLines()},
 			out: `# HELP request_duration_microseconds The response latency.
 # TYPE request_duration_microseconds histogram
 request_duration_microseconds_bucket{le="100.0"} 123
@@ -537,7 +537,7 @@ request_duration_microseconds_count 2693
 					},
 				},
 			},
-			options: []ToOpenMetricsOption{WithCreatedLines()},
+			options: []EncoderOption{WithCreatedLines()},
 			out: `# HELP foos Number of foos.
 # TYPE foos counter
 foos_total 42.0
