[scraper helper] improve ease of use of scraper controller settings (#…

…7951)

- Reduce the complexity required in order to override values within
components
- Address feedback from
#7703 (comment)

.chloggen/msg_cleanup-scraper-helper.yaml

@@ -0,0 +1,16 @@
+# 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. otlpreceiver)
+component: scraperhelper
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Adding optional timeout field to scrapers
+
+# One or more tracking issues or pull requests related to the change
+issues: [7951]
+
+# (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:

receiver/scraperhelper/scrapercontroller.go

@@ -19,23 +19,6 @@ import (
 	"go.opentelemetry.io/collector/receiver/scrapererror"
 )
 
-// ScraperControllerSettings defines common settings for a scraper controller
-// configuration. Scraper controller receivers can embed this struct, instead
-// of receiver.Settings, and extend it with more fields if needed.
-type ScraperControllerSettings struct {
-	CollectionInterval time.Duration `mapstructure:"collection_interval"`
-	InitialDelay       time.Duration `mapstructure:"initial_delay"`
-}
-
-// NewDefaultScraperControllerSettings returns default scraper controller
-// settings with a collection interval of one minute.
-func NewDefaultScraperControllerSettings(component.Type) ScraperControllerSettings {
-	return ScraperControllerSettings{
-		CollectionInterval: time.Minute,
-		InitialDelay:       time.Second,
-	}
-}
-
 // ScraperControllerOption apply changes to internal options.
 type ScraperControllerOption func(*controller)
 
@@ -64,6 +47,7 @@ type controller struct {
 	logger             *zap.Logger
 	collectionInterval time.Duration
 	initialDelay       time.Duration
+	timeout            time.Duration
 	nextConsumer       consumer.Metrics
 
 	scrapers    []Scraper
@@ -108,6 +92,7 @@ func NewScraperControllerReceiver(
 		logger:             set.Logger,
 		collectionInterval: cfg.CollectionInterval,
 		initialDelay:       cfg.InitialDelay,
+		timeout:            cfg.Timeout,
 		nextConsumer:       nextConsumer,
 		done:               make(chan struct{}),
 		terminated:         make(chan struct{}),
@@ -181,15 +166,14 @@ func (sc *controller) startScraping() {
 
 			sc.tickerCh = ticker.C
 		}
-
 		// Call scrape method on initialision to ensure
 		// that scrapers start from when the component starts
 		// instead of waiting for the full duration to start.
-		sc.scrapeMetricsAndReport(context.Background())
+		sc.scrapeMetricsAndReport()
 		for {
 			select {
 			case <-sc.tickerCh:
-				sc.scrapeMetricsAndReport(context.Background())
+				sc.scrapeMetricsAndReport()
 			case <-sc.done:
 				sc.terminated <- struct{}{}
 				return
@@ -201,7 +185,10 @@ func (sc *controller) startScraping() {
 // scrapeMetricsAndReport calls the Scrape function for each of the configured
 // Scrapers, records observability information, and passes the scraped metrics
 // to the next component.
-func (sc *controller) scrapeMetricsAndReport(ctx context.Context) {
+func (sc *controller) scrapeMetricsAndReport() {
+	ctx, done := withScrapeContext(sc.timeout)
+	defer done()
+
 	metrics := pmetric.NewMetrics()
 
 	for i, scraper := range sc.scrapers {
@@ -230,3 +217,13 @@ func (sc *controller) scrapeMetricsAndReport(ctx context.Context) {
 func (sc *controller) stopScraping() {
 	close(sc.done)
 }
+
+// withScrapeContext will return a context that has no deadline if timeout is 0
+// which implies no explicit timeout had occurred, otherwise, a context
+// with a deadline of the provided timeout is returned.
+func withScrapeContext(timeout time.Duration) (context.Context, context.CancelFunc) {
+	if timeout == 0 {
+		return context.WithCancel(context.Background())
+	}
+	return context.WithTimeout(context.Background(), timeout)
+}

receiver/scraperhelper/scrapercontroller_test.go

@@ -407,7 +407,10 @@ func TestScrapeControllerInitialDelay(t *testing.T) {
 
 	var (
 		elapsed = make(chan time.Time, 1)
-		cfg     = NewDefaultScraperControllerSettings("my-delayed-scraper")
+		cfg     = ScraperControllerSettings{
+			CollectionInterval: time.Second,
+			InitialDelay:       300 * time.Millisecond,
+		}
 	)
 
 	scp, err := NewScraper("timed", func(ctx context.Context) (pmetric.Metrics, error) {

receiver/scraperhelper/settings.go

@@ -0,0 +1,53 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package scraperhelper // import "go.opentelemetry.io/collector/receiver/scraperhelper"
+
+import (
+	"errors"
+	"fmt"
+	"time"
+
+	"go.uber.org/multierr"
+
+	"go.opentelemetry.io/collector/component"
+)
+
+var (
+	errNonPositiveInterval = errors.New("requires positive value")
+)
+
+// ScraperControllerSettings defines common settings for a scraper controller
+// configuration. Scraper controller receivers can embed this struct, instead
+// of receiver.Settings, and extend it with more fields if needed.
+type ScraperControllerSettings struct {
+	// CollectionInterval sets the how frequently the scraper
+	// should be called and used as the context timeout
+	// to ensure that scrapers don't exceed the interval.
+	CollectionInterval time.Duration `mapstructure:"collection_interval"`
+	// InitialDelay sets the initial start delay for the scraper,
+	// any non positive value is assumed to be immediately.
+	InitialDelay time.Duration `mapstructure:"initial_delay"`
+	// Timeout is an optional value used to set scraper's context deadline.
+	Timeout time.Duration `mapstructure:"timeout"`
+}
+
+// NewDefaultScraperControllerSettings returns default scraper controller
+// settings with a collection interval of one minute.
+func NewDefaultScraperControllerSettings(component.Type) ScraperControllerSettings {
+	return ScraperControllerSettings{
+		CollectionInterval: time.Minute,
+		InitialDelay:       time.Second,
+		Timeout:            0,
+	}
+}
+
+func (set *ScraperControllerSettings) Validate() (errs error) {
+	if set.CollectionInterval <= 0 {
+		errs = multierr.Append(errs, fmt.Errorf(`"collection_interval": %w`, errNonPositiveInterval))
+	}
+	if set.Timeout < 0 {
+		errs = multierr.Append(errs, fmt.Errorf(`"timeout": %w`, errNonPositiveInterval))
+	}
+	return errs
+}

receiver/scraperhelper/settings_test.go

@@ -0,0 +1,52 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package scraperhelper
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestScrapeControllerSettings(t *testing.T) {
+	t.Parallel()
+
+	for _, tc := range []struct {
+		name   string
+		set    ScraperControllerSettings
+		errVal string
+	}{
+		{
+			name:   "default configuration",
+			set:    NewDefaultScraperControllerSettings(""),
+			errVal: "",
+		},
+		{
+			name:   "zero value configuration",
+			set:    ScraperControllerSettings{},
+			errVal: `"collection_interval": requires positive value`,
+		},
+		{
+			name: "invalid timeout",
+			set: ScraperControllerSettings{
+				CollectionInterval: time.Minute,
+				Timeout:            -1 * time.Minute,
+			},
+			errVal: `"timeout": requires positive value`,
+		},
+	} {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			err := tc.set.Validate()
+			if tc.errVal == "" {
+				assert.NoError(t, err, "Must not error")
+				return
+			}
+			assert.EqualError(t, err, tc.errVal, "Must match the expected error")
+		})
+	}
+}