[scraperhelper] Add extension-based scraper controller support

.chloggen/extensionscrapercontroller.yaml

@@ -0,0 +1,25 @@
+# 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. receiver/otlp)
+component: pkg/scraperhelper
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add ControllerExtension interface for extensible scraper controllers
+
+# One or more tracking issues or pull requests related to the change
+issues: [12449]
+
+# (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:
+
+# 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: [api]

cmd/mdatagen/go.mod

@@ -71,6 +71,8 @@ require (
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
 	go.opentelemetry.io/collector/component/componentstatus v0.155.0 // indirect
 	go.opentelemetry.io/collector/consumer/consumererror v0.155.0 // indirect
+	go.opentelemetry.io/collector/extension v1.61.0 // indirect
+	go.opentelemetry.io/collector/extension/xextension v0.155.0 // indirect
 	go.opentelemetry.io/collector/internal/componentalias v0.155.0 // indirect
 	go.opentelemetry.io/collector/internal/fanoutconsumer v0.155.0 // indirect
 	go.opentelemetry.io/collector/pdata/testdata v0.155.0 // indirect

cmd/mdatagen/internal/samplescraper/README.md

@@ -21,8 +21,9 @@ This scraper is used for testing purposes to check the output of mdatagen.
 ## Configuration
 | Setting | Type | Default | Required | Description |
 | ------- | ---- | ------- | -------- | ----------- |
-| `collection_interval` | duration | 1m | no | Sets how frequently the scraper should be called and used as the context timeout to ensure that scrapers don't exceed the interval. |
+| `collection_interval` | duration | 1m | no | Sets how frequently the scraper should be called and used as the context timeout to ensure that scrapers don't exceed the interval. Must be positive, or zero to disable timer-based scraping (requires controllers to be non-empty). |
 | `component` | string |  | no | Identifies the scraper, used for telemetry and logging. |
+| `controllers` | []string |  | no | An optional list of extension IDs that control when scrapes occur. When specified, extensions can trigger scrapes based on external events. If controllers is non-empty, collection_interval may be zero to disable timer-based scraping entirely. |
 | `initial_delay` | duration | 1s | no | Sets the initial start delay for the scraper, any non positive value is assumed to be immediately. |
 | `job_name` | string | test_job | **yes** | Name of the scrape job, used to identify the source in telemetry. |
 | `log_level` | string (one of: debug, info, warn, error) | info | no | Logging level for the scraper. |

cmd/mdatagen/internal/samplescraper/config.schema.json

@@ -10,11 +10,18 @@
       "type": "object",
       "properties": {
         "collection_interval": {
-          "description": "Sets how frequently the scraper should be called and used as the context timeout to ensure that scrapers don't exceed the interval.",
+          "description": "Sets how frequently the scraper should be called and used as the context timeout to ensure that scrapers don't exceed the interval. Must be positive, or zero to disable timer-based scraping (requires controllers to be non-empty).",
           "type": "string",
           "default": "1m",
           "pattern": "^([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$"
         },
+        "controllers": {
+          "description": "An optional list of extension IDs that control when scrapes occur. When specified, extensions can trigger scrapes based on external events. If controllers is non-empty, collection_interval may be zero to disable timer-based scraping entirely.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
         "initial_delay": {
           "description": "Sets the initial start delay for the scraper, any non positive value is assumed to be immediately.",
           "type": "string",

docs/rfcs/scraper-controller-extension.md

@@ -32,39 +32,30 @@ The timer-based scraping will remain the default behavior but can be disabled vi
 Create a new extension interface (e.g. in `extension/extensionscrapercontroller`):
 
 ```golang
-// ControllerExtension is an extension that provides a means of registering scrapers,
-// and giving the extension control over when registered scrapers are invoked.
+// ControllerExtension is an extension that controls when scraper-based
+// receivers invoke their scrapers.
 type ControllerExtension interface {
     extension.Extension
 
-    // RegisterScraper registers a scraper with this controller extension.
-    // The extension will invoke the provided scrape function according to its implementation.
-    // Returns a registration handle that can be used to deregister the scraper.
-    RegisterScraper(ctx context.Context, scraperID component.ID, scrapeFunc func(context.Context) error) (RegistrationHandle, error)
+    // RegisterScraper registers a scraper with the extension. The extension
+    // will call the provided ScrapeFunc when it determines a scrape should
+    // occur. The returned DeregisterFunc must be called during shutdown to
+    // deregister the scraper from the controller.
+    //
+    // Implementations may call the ScrapeFunc concurrently. DeregisterFunc
+    // must not return until all in-flight calls to ScrapeFunc have completed,
+    // and must guarantee that ScrapeFunc will not be called again after it
+    // returns.
+    RegisterScraper(context.Context, ScrapeFunc) (DeregisterFunc, error)
 }
 
-// RegistrationHandle provides a way to deregister a scraper from a controller extension
-type RegistrationHandle interface {
-    // Deregister removes the scraper from the controller extension
-    Deregister(ctx context.Context) error
-}
-```
-
-We will define a `DeregisterFunc` function type implementing `RegistrationHandle` for convenience:
+// ScrapeFunc is a function that is registered with
+// ControllerExtension.RegisterScraper in order to perform a scrape.
+type ScrapeFunc func(context.Context) error
 
-```golang
-// DeregisterFunc implements RegistrationHandle using a simple function.
-//
-// If the function value is nil, the method call will be a no-op.
+// DeregisterFunc is a function returned by ControllerExtension.RegisterScraper
+// and is used to deregister the scraper during shutdown.
 type DeregisterFunc func(ctx context.Context) error
-
-// Deregister calls the underlying function to deregister the scraper.
-func (f DeregisterFunc) Deregister(ctx context.Context) error {
-    if f == nil {
-        return nil
-    }
-    return f(ctx)
-}
 ```
 
 ### 2. Configuration Changes
@@ -76,8 +67,8 @@ Modify `ControllerConfig` to support:
 ```golang
 type ControllerConfig struct {
     // CollectionInterval sets how frequently the scraper should be called.
-    // If zero or negative, the timer-based scraping is disabled.
-    // At least one controller extension must be configured if timer is disabled.
+    // Must be positive, or zero to disable timer-based scraping. If zero,
+    // at least one controller extension must be configured.
     CollectionInterval time.Duration `mapstructure:"collection_interval"`
 
     // InitialDelay sets the initial start delay for the scraper timer.
@@ -96,7 +87,7 @@ type ControllerConfig struct {
 ### 3. Controller Implementation Changes
 
 Modify `controller.Controller` to:
-- Support disabling the timer when `CollectionInterval <= 0`
+- Support disabling the timer when `CollectionInterval == 0` (negative values remain invalid)
 - Register scrapers with configured controller extensions during `Start()`
 - Deregister scrapers during `Shutdown()`
 - Validate that at least one controller extension is configured if timer is disabled

extension/xextension/extensionscrapercontroller/doc.go

@@ -0,0 +1,6 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// Package extensionscrapercontroller defines the interface for extensions
+// that control when scraper-based receivers invoke their scrapers.
+package extensionscrapercontroller // import "go.opentelemetry.io/collector/extension/xextension/extensionscrapercontroller"

extension/xextension/extensionscrapercontroller/extensionscrapercontroller.go

@@ -0,0 +1,37 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package extensionscrapercontroller // import "go.opentelemetry.io/collector/extension/xextension/extensionscrapercontroller"
+
+import (
+	"context"
+
+	"go.opentelemetry.io/collector/extension"
+)
+
+// ControllerExtension is an extension that controls when scraper-based
+// receivers invoke their scrapers.
+type ControllerExtension interface {
+	extension.Extension
+
+	// RegisterScraper registers a scraper with the extension. The extension
+	// will call the provided ScrapeFunc when it determines a scrape should
+	// occur. The returned DeregisterFunc must be called during shutdown to
+	// deregister the scraper from the controller.
+	//
+	// When err is nil, the returned DeregisterFunc must not be nil.
+	//
+	// Implementations may call the ScrapeFunc concurrently. DeregisterFunc
+	// must not return until all in-flight calls to ScrapeFunc have completed,
+	// and must guarantee that ScrapeFunc will not be called again after it
+	// returns.
+	RegisterScraper(context.Context, ScrapeFunc) (DeregisterFunc, error)
+}
+
+// ScrapeFunc is a function that is registered with
+// ControllerExtension.RegisterScraper in order to perform a scrape.
+type ScrapeFunc func(context.Context) error
+
+// DeregisterFunc is a function returned by ControllerExtension.RegisterScraper
+// and is used to deregister the scraper during shutdown.
+type DeregisterFunc func(ctx context.Context) error

scraper/scraperhelper/config.schema.json

@@ -8,11 +8,18 @@
       "type": "object",
       "properties": {
         "collection_interval": {
-          "description": "Sets how frequently the scraper should be called and used as the context timeout to ensure that scrapers don't exceed the interval.",
+          "description": "Sets how frequently the scraper should be called and used as the context timeout to ensure that scrapers don't exceed the interval. Must be positive, or zero to disable timer-based scraping (requires controllers to be non-empty).",
           "type": "string",
           "default": "1m",
           "pattern": "^([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$"
         },
+        "controllers": {
+          "description": "An optional list of extension IDs that control when scrapes occur. When specified, extensions can trigger scrapes based on external events. If controllers is non-empty, collection_interval may be zero to disable timer-based scraping entirely.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
         "initial_delay": {
           "description": "Sets the initial start delay for the scraper, any non positive value is assumed to be immediately.",
           "type": "string",

scraper/scraperhelper/config.schema.yaml

@@ -4,10 +4,16 @@ $defs:
     type: object
     properties:
       collection_interval:
-        description: CollectionInterval sets how frequently the scraper should be called and used as the context timeout to ensure that scrapers don't exceed the interval.
+        description: CollectionInterval sets how frequently the scraper should be called and used as the context timeout to ensure that scrapers don't exceed the interval. Must be positive, or zero to disable timer-based scraping (requires Controllers to be non-empty).
         type: string
         x-customType: time.Duration
         format: duration
+      controllers:
+        description: Controllers is a list of extension IDs that control when scrapes occur. When specified, extensions can trigger scrapes based on external events. If Controllers is non-empty, CollectionInterval may be zero to disable timer-based scraping entirely.
+        type: array
+        items:
+          type: string
+          x-customType: go.opentelemetry.io/collector/component.ID
       initial_delay:
         description: InitialDelay sets the initial start delay for the scraper, any non positive value is assumed to be immediately.
         type: string