Add subtract_initial_point strategy skeleton (#38380)

#### Description

Add a skeleton for the `subtract_initial_point` strategy. The
implementation will follow in subsequent PRs.

#### Link to tracking issue

Part of
#37186,
and #38379

#### Testing

Added config_test.go

#### Documentation

Updated the README.

Author: dashpole

.chloggen/metricstarttime-subtract-initial.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# 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: metricstarttimeprocessor
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add the subtract_initial_point strategy skeleton
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [37186, 38379]
+
+# (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 subtract_initial_point strategy is not fully implemented
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

processor/metricstarttimeprocessor/README.md

@@ -50,3 +50,20 @@ Cons:
 * The True Reset point doesn't make sense semantically. It has a zero duration, but non-zero values.
 * Many backends reject points with equal start and end timestamps.
     * If the True Reset point is rejected, the next point will appear to have a very large rate.
+
+### Strategy: Subtract Initial Point
+
+The `subtract_initial_point` strategy handles missing start times for
+cumulative points by dropping the first point in a cumulative series,
+"subtracting" that point's value from subsequent points and using the initial
+point's timestamp as the start timestamp for subsequent points.
+
+Pros:
+
+* Cumulative semantics are preserved. This means that for a point with a given `[start, end]` interval, the cumulative value occurred in that interval.
+* Rates over resulting timeseries are correct, even if points are lost. This strategy is not stateful.
+
+Cons:
+
+* The absolute value of counters is modified. This is generally not an issue, since counters are usually used to compute rates.
+* The initial point is dropped, which loses information.

processor/metricstarttimeprocessor/config.go

@@ -9,6 +9,7 @@ import (
 
 	"go.opentelemetry.io/collector/component"
 
+	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstarttimeprocessor/internal/subtractinitial"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstarttimeprocessor/internal/truereset"
 )
 
@@ -29,8 +30,11 @@ func createDefaultConfig() component.Config {
 
 // Validate checks the configuration is valid
 func (cfg *Config) Validate() error {
-	if cfg.Strategy != truereset.Type {
-		return fmt.Errorf("%v is not a valid strategy", cfg.Strategy)
+	switch cfg.Strategy {
+	case truereset.Type:
+	case subtractinitial.Type:
+	default:
+		return fmt.Errorf("%q is not a valid strategy", cfg.Strategy)
 	}
 	if cfg.GCInterval <= 0 {
 		return fmt.Errorf("gc_interval must be positive")

processor/metricstarttimeprocessor/config_test.go

@@ -0,0 +1,80 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package metricstarttimeprocessor
+
+import (
+	"path/filepath"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"go.opentelemetry.io/collector/component"
+	"go.opentelemetry.io/collector/confmap/confmaptest"
+	"go.opentelemetry.io/collector/confmap/xconfmap"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstarttimeprocessor/internal/metadata"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstarttimeprocessor/internal/subtractinitial"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstarttimeprocessor/internal/truereset"
+)
+
+func TestLoadConfig(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		id           component.ID
+		expected     component.Config
+		errorMessage string
+	}{
+		{
+			id: component.NewIDWithName(metadata.Type, ""),
+			expected: &Config{
+				Strategy:   truereset.Type,
+				GCInterval: 10 * time.Minute,
+			},
+		},
+		{
+			id: component.NewIDWithName(metadata.Type, "subtract_initial_point"),
+			expected: &Config{
+				Strategy:   subtractinitial.Type,
+				GCInterval: 10 * time.Minute,
+			},
+		},
+		{
+			id: component.NewIDWithName(metadata.Type, "gc_interval"),
+			expected: &Config{
+				Strategy:   truereset.Type,
+				GCInterval: 1 * time.Hour,
+			},
+		},
+		{
+			id:           component.NewIDWithName(metadata.Type, "negative_interval"),
+			errorMessage: "gc_interval must be positive",
+		},
+		{
+			id:           component.NewIDWithName(metadata.Type, "invalid_strategy"),
+			errorMessage: "\"bad\" is not a valid strategy",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.id.String(), func(t *testing.T) {
+			cm, err := confmaptest.LoadConf(filepath.Join("testdata", "config.yaml"))
+			require.NoError(t, err)
+
+			factory := NewFactory()
+			cfg := factory.CreateDefaultConfig()
+			sub, err := cm.Sub(tt.id.String())
+			require.NoError(t, err)
+			require.NoError(t, sub.Unmarshal(cfg))
+
+			if tt.expected == nil {
+				assert.EqualError(t, xconfmap.Validate(cfg), tt.errorMessage)
+				return
+			}
+			assert.NoError(t, xconfmap.Validate(cfg))
+			assert.Equal(t, tt.expected, cfg)
+		})
+	}
+}

processor/metricstarttimeprocessor/factory.go

@@ -12,6 +12,7 @@ import (
 	"go.opentelemetry.io/collector/processor/processorhelper"
 
 	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstarttimeprocessor/internal/metadata"
+	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstarttimeprocessor/internal/subtractinitial"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstarttimeprocessor/internal/truereset"
 )
 
@@ -32,13 +33,22 @@ func createMetricsProcessor(
 ) (processor.Metrics, error) {
 	rCfg := cfg.(*Config)
 
-	adjuster := truereset.NewAdjuster(set.TelemetrySettings, rCfg.GCInterval)
+	var adjustMetrics processorhelper.ProcessMetricsFunc
+
+	switch rCfg.Strategy {
+	case truereset.Type:
+		adjuster := truereset.NewAdjuster(set.TelemetrySettings, rCfg.GCInterval)
+		adjustMetrics = adjuster.AdjustMetrics
+	case subtractinitial.Type:
+		adjuster := subtractinitial.NewAdjuster(set.TelemetrySettings, rCfg.GCInterval)
+		adjustMetrics = adjuster.AdjustMetrics
+	}
 
 	return processorhelper.NewMetrics(
 		ctx,
 		set,
 		cfg,
 		nextConsumer,
-		adjuster.AdjustMetrics,
+		adjustMetrics,
 		processorhelper.WithCapabilities(consumer.Capabilities{MutatesData: true}))
 }

processor/metricstarttimeprocessor/go.mod

@@ -8,6 +8,7 @@ require (
 	go.opentelemetry.io/collector/component v1.27.0
 	go.opentelemetry.io/collector/component/componenttest v0.121.0
 	go.opentelemetry.io/collector/confmap v1.27.0
+	go.opentelemetry.io/collector/confmap/xconfmap v0.121.0
 	go.opentelemetry.io/collector/consumer v1.27.0
 	go.opentelemetry.io/collector/consumer/consumertest v0.121.0
 	go.opentelemetry.io/collector/pdata v1.27.0

processor/metricstarttimeprocessor/go.sum

@@ -0,0 +1,37 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package subtractinitial // import "github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstarttimeprocessor/internal/subtractinitial"
+
+import (
+	"context"
+	"errors"
+	"time"
+
+	"go.opentelemetry.io/collector/component"
+	"go.opentelemetry.io/collector/pdata/pmetric"
+)
+
+// Type is the value users can use to configure the subtract initial point adjuster.
+// The subtract initial point adjuster sets the start time of all points in a series by:
+//   - Dropping the initial point, and recording its value and timestamp.
+//   - Subtracting the initial point from all subsequent points, and using the timestamp of the initial point as the start timestamp.
+const Type = "subtract_initial_point"
+
+type Adjuster struct {
+	set component.TelemetrySettings
+}
+
+// NewAdjuster returns a new Adjuster which adjust metrics' start times based on the initial received points.
+func NewAdjuster(set component.TelemetrySettings, _ time.Duration) *Adjuster {
+	return &Adjuster{
+		set: set,
+	}
+}
+
+// AdjustMetrics takes a sequence of metrics and adjust their start times based on the initial and
+// previous points in the timeseriesMap.
+func (a *Adjuster) AdjustMetrics(_ context.Context, metrics pmetric.Metrics) (pmetric.Metrics, error) {
+	// TODO(#38379): Implement the subtract_initial_point adjuster
+	return metrics, errors.New("not implemented")
+}

processor/metricstarttimeprocessor/internal/subtractinitial/adjuster.go

@@ -0,0 +1,13 @@
+metricstarttime:
+
+metricstarttime/subtract_initial_point:
+  strategy: subtract_initial_point
+
+metricstarttime/gc_interval:
+  gc_interval: 1h
+
+metricstarttime/negative_interval:
+  gc_interval: -1h
+
+metricstarttime/invalid_strategy:
+  strategy: bad