[exporter/datadog] Add metrics::summaries::mode setting; deprecate metrics::report_quantiles (open-telemetry#8846)

* [exporter/datadog] Add `metrics::summaries::mode` setting; deprecate `metrics::report_quantiles`

* Add changelog entry

* Bump version of deprecation and removal

This won't make it into v0.48.0, so I am bumping to v0.49.0s

* Fix changelog

* Apply suggestions from code review

Co-authored-by: Kylian Serrania <kylian.serrania@datadoghq.com>

* Fix changelog after merge

Co-authored-by: Juraci Paixão Kröhling <juraci@kroehling.de>
Co-authored-by: Kylian Serrania <kylian.serrania@datadoghq.com>

Author: 3 people

CHANGELOG.md

@@ -12,6 +12,7 @@
 ### 🚩 Deprecations 🚩
 
 - `cumulativetodeltaprocessor`: Deprecated `metrics` configuration option in favor of `include` and `exclude` (#8952)
+- `datadogexporter`: Deprecate `metrics::report_quantiles` in favor of `metrics::summaries::mode` (#8846)
 
 ### 🚀 New components 🚀
 
@@ -28,6 +29,7 @@
 - `cmd/mdatagen`: Update generated functions to have simple parse function to handle string parsing consistently and limit code duplication across receivers (#7574)
 - `attributesprocessor`: Support filter by severity (#9132)
 - `processor/transform`: Add transformation of logs (#9368)
+- `datadogexporter`: Add `metrics::summaries::mode` to specify export mode for summaries (#8846)
 
 ### 🧰 Bug fixes 🧰
 

exporter/datadogexporter/README.md

@@ -105,6 +105,6 @@ There are a number of optional settings for configuring how to send your metrics
 |-|-|-|
 | `send_monotonic_counter` | Cumulative monotonic metrics are sent as deltas between successive measurements. Disable this flag to send get the raw, monotonically increasing value. | `true` |
 | `delta_ttl` | Maximum number of seconds values from cumulative monotonic metrics are kept in memory. | 3600 |
-| `report_quantiles` | Whether to report quantile values for summary type metrics. | `true` |
+| `summaries::mode` | Mode for summaries. Valid values are `noquantiles` (no quantiles metrics) and `gauges` (one metric per quantile). | `gauges` |
 | `histograms::mode` | Mode for histograms. Valid values are `nobuckets` (no bucket metrics), `counters` (one metric per bucket) and `distributions` (send as Datadog distributions, recommended). | `distributions` |
 | `histograms::send_count_sum_metrics` | Whether to report sum and count for histograms as separate metrics. | `false` |

exporter/datadogexporter/config/config.go

@@ -64,6 +64,7 @@ type APIConfig struct {
 type MetricsConfig struct {
 	// Quantiles states whether to report quantiles from summary metrics.
 	// By default, the minimum, maximum and average are reported.
+	// Deprecated: [v0.50.0] Use `metrics::summaries::mode` (SummaryConfig.Mode) instead.
 	Quantiles bool `mapstructure:"report_quantiles"`
 
 	// SendMonotonic states whether to report cumulative monotonic metrics as counters
@@ -87,6 +88,9 @@ type MetricsConfig struct {
 
 	// SumConfig defines the export of OTLP Sums.
 	SumConfig SumConfig `mapstructure:"sums"`
+
+	// SummaryConfig defines the export for OTLP Summaries.
+	SummaryConfig SummaryConfig `mapstructure:"summaries"`
 }
 
 // HistogramConfig customizes export of OTLP Histograms.
@@ -152,6 +156,42 @@ type SumConfig struct {
 	CumulativeMonotonicMode CumulativeMonotonicSumMode `mapstructure:"cumulative_monotonic_mode"`
 }
 
+// SummaryMode is the export mode for OTLP Summary metrics.
+type SummaryMode string
+
+const (
+	// SummaryModeNoQuantiles sends no `.quantile` metrics. `.sum` and `.count` metrics will still be sent.
+	SummaryModeNoQuantiles SummaryMode = "noquantiles"
+	// SummaryModeGauges sends `.quantile` metrics as gauges tagged by the quantile.
+	SummaryModeGauges SummaryMode = "gauges"
+)
+
+var _ encoding.TextUnmarshaler = (*SummaryMode)(nil)
+
+// UnmarshalText implements the encoding.TextUnmarshaler interface.
+func (sm *SummaryMode) UnmarshalText(in []byte) error {
+	switch mode := SummaryMode(in); mode {
+	case SummaryModeNoQuantiles,
+		SummaryModeGauges:
+		*sm = mode
+		return nil
+	default:
+		return fmt.Errorf("invalid summary mode %q", mode)
+	}
+}
+
+// SummaryConfig customizes export of OTLP Summaries.
+type SummaryConfig struct {
+	// Mode is the the mode for exporting OTLP Summaries.
+	// Valid values are 'noquantiles' or 'gauges'.
+	//  - 'noquantiles' sends no `.quantile` metrics. `.sum` and `.count` metrics will still be sent.
+	//  - 'gauges' sends `.quantile` metrics as gauges tagged by the quantile.
+	//
+	// The default is 'gauges'.
+	// See https://docs.datadoghq.com/metrics/otlp/?tab=summary#mapping for details and examples.
+	Mode SummaryMode `mapstructure:"mode"`
+}
+
 // MetricsExporterConfig provides options for a user to customize the behavior of the
 // metrics exporter
 type MetricsExporterConfig struct {

exporter/datadogexporter/config/config_test.go

@@ -207,6 +207,17 @@ func TestUnmarshal(t *testing.T) {
 			}),
 			err: "1 error(s) decoding:\n\n* error decoding 'host_metadata.hostname_source': invalid host metadata hostname source \"invalid_source\"",
 		},
+		{
+			name: "invalid summary mode",
+			configMap: config.NewMapFromStringMap(map[string]interface{}{
+				"metrics": map[string]interface{}{
+					"summaries": map[string]interface{}{
+						"mode": "invalid_mode",
+					},
+				},
+			}),
+			err: "1 error(s) decoding:\n\n* error decoding 'metrics.summaries.mode': invalid summary mode \"invalid_mode\"",
+		},
 	}
 
 	for _, testInstance := range tests {

exporter/datadogexporter/config/warn_envvars.go

@@ -46,6 +46,9 @@ func futureDefaultConfig() *Config {
 			SumConfig: SumConfig{
 				CumulativeMonotonicMode: CumulativeMonotonicSumModeToDelta,
 			},
+			SummaryConfig: SummaryConfig{
+				Mode: SummaryModeGauges,
+			},
 		},
 		Traces: TracesConfig{
 			SampleRate:      1,

exporter/datadogexporter/config/warning_deprecated.go

@@ -84,6 +84,19 @@ var renamedSettings = []renameError{
 			}
 		},
 	},
+	{
+		oldName:      "metrics::report_quantiles",
+		newName:      "metrics::summaries::mode",
+		oldRemovedIn: "v0.53.0",
+		issueNumber:  8845,
+		updateFn: func(c *Config) {
+			if c.Metrics.Quantiles {
+				c.Metrics.SummaryConfig.Mode = SummaryModeGauges
+			} else {
+				c.Metrics.SummaryConfig.Mode = SummaryModeNoQuantiles
+			}
+		},
+	},
 }
 
 // List of settings that have been removed, but for which we keep a custom error.

exporter/datadogexporter/example/config.yaml

@@ -101,6 +101,12 @@ exporters:
       #
       # send_monotonic_counter: true
 
+      ## @param report_quantiles - boolean - optional - default: true
+      ## Deprecated: [v0.50.0] Use `metrics::summaries::mode` instead.
+      ## Whether to report quantiles for summary metrics.
+      #
+      # report_quantiles: true
+
       ## @param - delta_ttl - integer - optional - default: 3600
       ## The amount of time (in seconds) that values are kept in memory for
       ## calculating deltas for cumulative monotonic metrics.
@@ -152,6 +158,16 @@ exporters:
         #
         # cumulative_monotonic_mode: to_delta
 
+      ## @param summaries - custom object - optional
+      ## Summaries specific configuration.
+        ## @param mode - string - optional - default: gauges
+        ## How to report summaries. Valid values are:
+        ## 
+        ## - `noquantiles` to not report quantile metrics
+        ## - `gauges` to report one gauge metric per quantile.
+        #
+        # mode: gauges
+
     ## @param traces - custom object - optional
     ## Trace exporter specific configuration.
     #

exporter/datadogexporter/factory.go

@@ -100,6 +100,9 @@ func (*factory) createDefaultConfig() config.Exporter {
 			SumConfig: ddconfig.SumConfig{
 				CumulativeMonotonicMode: ddconfig.CumulativeMonotonicSumModeToDelta,
 			},
+			SummaryConfig: ddconfig.SummaryConfig{
+				Mode: ddconfig.SummaryModeGauges,
+			},
 		},
 
 		Traces: ddconfig.TracesConfig{

exporter/datadogexporter/factory_test.go

@@ -88,6 +88,9 @@ func TestCreateDefaultConfig(t *testing.T) {
 			SumConfig: ddconfig.SumConfig{
 				CumulativeMonotonicMode: ddconfig.CumulativeMonotonicSumModeToDelta,
 			},
+			SummaryConfig: ddconfig.SummaryConfig{
+				Mode: ddconfig.SummaryModeGauges,
+			},
 		},
 
 		Traces: ddconfig.TracesConfig{
@@ -165,6 +168,9 @@ func TestLoadConfig(t *testing.T) {
 		SumConfig: ddconfig.SumConfig{
 			CumulativeMonotonicMode: ddconfig.CumulativeMonotonicSumModeToDelta,
 		},
+		SummaryConfig: ddconfig.SummaryConfig{
+			Mode: ddconfig.SummaryModeGauges,
+		},
 	}, apiConfig.Metrics)
 	assert.Equal(t, ddconfig.TracesConfig{
 		SampleRate: 1,
@@ -214,6 +220,9 @@ func TestLoadConfig(t *testing.T) {
 			SumConfig: ddconfig.SumConfig{
 				CumulativeMonotonicMode: ddconfig.CumulativeMonotonicSumModeToDelta,
 			},
+			SummaryConfig: ddconfig.SummaryConfig{
+				Mode: ddconfig.SummaryModeGauges,
+			},
 		},
 
 		Traces: ddconfig.TracesConfig{
@@ -312,6 +321,9 @@ func TestLoadConfigEnvVariables(t *testing.T) {
 			SumConfig: ddconfig.SumConfig{
 				CumulativeMonotonicMode: ddconfig.CumulativeMonotonicSumModeToDelta,
 			},
+			SummaryConfig: ddconfig.SummaryConfig{
+				Mode: ddconfig.SummaryModeNoQuantiles,
+			},
 		}, apiConfig.Metrics)
 	assert.Equal(t,
 		ddconfig.TracesConfig{
@@ -362,6 +374,9 @@ func TestLoadConfigEnvVariables(t *testing.T) {
 		SumConfig: ddconfig.SumConfig{
 			CumulativeMonotonicMode: ddconfig.CumulativeMonotonicSumModeToDelta,
 		},
+		SummaryConfig: ddconfig.SummaryConfig{
+			Mode: ddconfig.SummaryModeGauges,
+		},
 	}, defaultConfig.Metrics)
 	assert.Equal(t, ddconfig.TracesConfig{
 		SampleRate: 1,

exporter/datadogexporter/metrics_exporter.go

@@ -72,7 +72,8 @@ func translatorFromConfig(logger *zap.Logger, cfg *config.Config) (*translator.T
 		options = append(options, translator.WithCountSumMetrics())
 	}
 
-	if cfg.Metrics.Quantiles {
+	switch cfg.Metrics.SummaryConfig.Mode {
+	case config.SummaryModeGauges:
 		options = append(options, translator.WithQuantiles())
 	}