[exporter/datadog] Add support for metrics::sums::initial_cumulative_…

…monotonic_value (#24544)

**Description:** 

Add support for `metrics::sums::initial_cumulative_monotonic_value`
setting. This is similar to #21905 but for the Datadog exporter legacy
cumulative to delta logic.

Keeping as draft until its counterpart on the Datadog Agent
(DataDog/datadog-agent/pull/18371) is approved

Relates to DataDog/opentelemetry-mapping-go/issues/100

.chloggen/mx-psi_cumulative-opts.yaml

@@ -0,0 +1,21 @@
+# Use this changelog template to create an entry for release notes.
+# If your change doesn't affect end users, such as a test fix or a tooling change,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. filelogreceiver)
+component: datadogexporter
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Add support for the `metrics::sums::initial_cumulative_monotonic_value` setting"
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [24544]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  The setting has the same values and semantics as the `initial_value` setting from the `cumulativetodelta` processor

exporter/datadogexporter/config.go

@@ -149,6 +149,37 @@ func (sm *CumulativeMonotonicSumMode) UnmarshalText(in []byte) error {
 	}
 }
 
+// InitialValueMode defines what the exporter should do with the initial value
+// of a time series when transforming from cumulative to delta.
+type InitialValueMode string
+
+const (
+	// InitialValueModeAuto reports the initial value if its start timestamp
+	// is set and it happens after the process was started.
+	InitialValueModeAuto InitialValueMode = "auto"
+
+	// InitialValueModeDrop always drops the initial value.
+	InitialValueModeDrop InitialValueMode = "drop"
+
+	// InitialValueModeKeep always reports the initial value.
+	InitialValueModeKeep InitialValueMode = "keep"
+)
+
+var _ encoding.TextUnmarshaler = (*InitialValueMode)(nil)
+
+// UnmarshalText implements the encoding.TextUnmarshaler interface.
+func (iv *InitialValueMode) UnmarshalText(in []byte) error {
+	switch mode := InitialValueMode(in); mode {
+	case InitialValueModeAuto,
+		InitialValueModeDrop,
+		InitialValueModeKeep:
+		*iv = mode
+		return nil
+	default:
+		return fmt.Errorf("invalid initial value mode %q", mode)
+	}
+}
+
 // SumConfig customizes export of OTLP Sums.
 type SumConfig struct {
 	// CumulativeMonotonicMode is the mode for exporting OTLP Cumulative Monotonic Sums.
@@ -159,6 +190,10 @@ type SumConfig struct {
 	// The default is 'to_delta'.
 	// See https://docs.datadoghq.com/metrics/otlp/?tab=sum#mapping for details and examples.
 	CumulativeMonotonicMode CumulativeMonotonicSumMode `mapstructure:"cumulative_monotonic_mode"`
+
+	// InitialCumulativeMonotonicMode defines the behavior of the exporter when receiving the first value
+	// of a cumulative monotonic sum.
+	InitialCumulativeMonotonicMode InitialValueMode `mapstructure:"initial_cumulative_monotonic_value"`
 }
 
 // SummaryMode is the export mode for OTLP Summary metrics.
@@ -529,5 +564,14 @@ func (c *Config) Unmarshal(configMap *confmap.Conf) error {
 		return errEmptyEndpoint
 	}
 
+	const (
+		initialValueSetting = "metrics::sums::initial_cumulative_monotonic_value"
+		cumulMonoMode       = "metrics::sums::cumulative_monotonic_mode"
+	)
+	if configMap.IsSet(initialValueSetting) && c.Metrics.SumConfig.CumulativeMonotonicMode != CumulativeMonotonicSumModeToDelta {
+		return fmt.Errorf("%q can only be configured when %q is set to %q",
+			initialValueSetting, cumulMonoMode, CumulativeMonotonicSumModeToDelta)
+	}
+
 	return nil
 }

exporter/datadogexporter/config_test.go

@@ -227,6 +227,29 @@ func TestUnmarshal(t *testing.T) {
 			}),
 			err: errEmptyEndpoint.Error(),
 		},
+		{
+			name: "invalid initial cumulative monotonic value mode",
+			configMap: confmap.NewFromStringMap(map[string]interface{}{
+				"metrics": map[string]interface{}{
+					"sums": map[string]interface{}{
+						"initial_cumulative_monotonic_value": "invalid_mode",
+					},
+				},
+			}),
+			err: "1 error(s) decoding:\n\n* error decoding 'metrics.sums.initial_cumulative_monotonic_value': invalid initial value mode \"invalid_mode\"",
+		},
+		{
+			name: "initial cumulative monotonic value mode set with raw_value",
+			configMap: confmap.NewFromStringMap(map[string]interface{}{
+				"metrics": map[string]interface{}{
+					"sums": map[string]interface{}{
+						"cumulative_monotonic_mode":          "raw_value",
+						"initial_cumulative_monotonic_value": "drop",
+					},
+				},
+			}),
+			err: "\"metrics::sums::initial_cumulative_monotonic_value\" can only be configured when \"metrics::sums::cumulative_monotonic_mode\" is set to \"to_delta\"",
+		},
 	}
 
 	f := NewFactory()

exporter/datadogexporter/examples/collector.yaml

@@ -272,6 +272,15 @@ exporters:
         #
         # cumulative_monotonic_mode: to_delta
 
+        ## @param initial_cumulative_monotonic_value - string - optional - default: auto
+        ## How to report the initial value for cumulative monotonic sums. Valid values are:
+        ##
+        ## - `auto` reports the initial value if its start timestamp is set and it happens after the process was started.
+        ## - `drop` always drops the initial value.
+        ## - `keep` always reports the initial value.
+        #
+        # initial_cumulative_monotonic_value: auto        
+
       ## @param summaries - custom object - optional
       ## Summaries specific configuration.
         ## @param mode - string - optional - default: gauges

exporter/datadogexporter/factory.go

@@ -170,7 +170,8 @@ func (f *factory) createDefaultConfig() component.Config {
 				SendAggregations: false,
 			},
 			SumConfig: SumConfig{
-				CumulativeMonotonicMode: CumulativeMonotonicSumModeToDelta,
+				CumulativeMonotonicMode:        CumulativeMonotonicSumModeToDelta,
+				InitialCumulativeMonotonicMode: InitialValueModeAuto,
 			},
 			SummaryConfig: SummaryConfig{
 				Mode: SummaryModeGauges,

exporter/datadogexporter/factory_test.go

@@ -88,7 +88,8 @@ func TestCreateDefaultConfig(t *testing.T) {
 				SendAggregations: false,
 			},
 			SumConfig: SumConfig{
-				CumulativeMonotonicMode: CumulativeMonotonicSumModeToDelta,
+				CumulativeMonotonicMode:        CumulativeMonotonicSumModeToDelta,
+				InitialCumulativeMonotonicMode: InitialValueModeAuto,
 			},
 			SummaryConfig: SummaryConfig{
 				Mode: SummaryModeGauges,
@@ -149,7 +150,8 @@ func TestLoadConfig(t *testing.T) {
 						SendAggregations: false,
 					},
 					SumConfig: SumConfig{
-						CumulativeMonotonicMode: CumulativeMonotonicSumModeToDelta,
+						CumulativeMonotonicMode:        CumulativeMonotonicSumModeToDelta,
+						InitialCumulativeMonotonicMode: InitialValueModeAuto,
 					},
 					SummaryConfig: SummaryConfig{
 						Mode: SummaryModeGauges,
@@ -198,7 +200,8 @@ func TestLoadConfig(t *testing.T) {
 						SendAggregations: false,
 					},
 					SumConfig: SumConfig{
-						CumulativeMonotonicMode: CumulativeMonotonicSumModeToDelta,
+						CumulativeMonotonicMode:        CumulativeMonotonicSumModeToDelta,
+						InitialCumulativeMonotonicMode: InitialValueModeAuto,
 					},
 					SummaryConfig: SummaryConfig{
 						Mode: SummaryModeGauges,
@@ -251,7 +254,8 @@ func TestLoadConfig(t *testing.T) {
 						SendAggregations: false,
 					},
 					SumConfig: SumConfig{
-						CumulativeMonotonicMode: CumulativeMonotonicSumModeToDelta,
+						CumulativeMonotonicMode:        CumulativeMonotonicSumModeToDelta,
+						InitialCumulativeMonotonicMode: InitialValueModeAuto,
 					},
 					SummaryConfig: SummaryConfig{
 						Mode: SummaryModeGauges,

exporter/datadogexporter/metrics_exporter.go

@@ -82,8 +82,9 @@ func translatorFromConfig(logger *zap.Logger, cfg *Config, sourceProvider source
 	case CumulativeMonotonicSumModeToDelta:
 		numberMode = otlpmetrics.NumberModeCumulativeToDelta
 	}
-
 	options = append(options, otlpmetrics.WithNumberMode(numberMode))
+	options = append(options, otlpmetrics.WithInitialCumulMonoValueMode(
+		otlpmetrics.InitialCumulMonoValueMode(cfg.Metrics.SumConfig.InitialCumulativeMonotonicMode)))
 
 	return otlpmetrics.NewTranslator(logger, options...)
 }