[receiver/hostmetrics] Unify feature gates for direction removal (#…

…12105)
open-telemetry · Jul 6, 2022 · 195abd8 · 195abd8
1 parent 27b48ca
commit 195abd8
Show file tree

Hide file tree

Showing 18 changed files with 393 additions and 368 deletions.
diff --git a/receiver/hostmetricsreceiver/README.md b/receiver/hostmetricsreceiver/README.md
@@ -132,111 +132,101 @@ service:
 
 ### Feature gate configurations
 
-- `receiver.hostmetricsreceiver.removeDirectionAttributeNetworkMetrics`
-  - Description
-    - Some network metrics reported by the hostmetricsreceiver are transitioning from being reported
-		with a direction attribute to being reported with the direction included in the metric name to adhere to the
-		OpenTelemetry specification. Please update any monitoring this might affect.
-  - Affected Metrics
-    - `system.network.dropped` will become:
-      - `system.network.dropped.receive`
-      - `system.network.dropped.transmit`
-    - `system.network.errors` will become:
-      - `system.network.errors.receive`
-      - `system.network.errors.transmit`
-    - `system.network.io` will become:
-      - `system.network.io.receive`
-      - `system.network.io.transmit`
-    - `system.network.packets` will become:
-      - `system.network.packets.receive`
-      - `system.network.packets.transmit`
-  - Stages and Timeline
-    - Alpha (current stage)
-      - In this stage the feature gate is disabled by default and must be enabled by the user. This allows users to preemptively opt in and start using the bug fix by enabling the feature gate.
-      - Collector version: v0.55.0
-      - Release Date: Early July 2022
-    - Beta
-      - In this stage the feature gate is enabled by default and can be disabled by the user.
-      - Collector version: v0.57.0
-      - Release Date: Early August 2022
-    - Generally Available
-      - In this stage the feature gate is permanently enabled and the feature gate is no longer available for anyone.
-      - Users could experience some friction in this stage, they may have to update monitoring for the affected metrics or be blocked from upgrading the collector to versions v0.59.0 and newer.
-      - Collector version: v0.59.0
-      - Release Date: Early September 2022
-  - Usage
-    - Feature gate identifiers prefixed with - will disable the gate and prefixing with + or with no prefix will enable the gate.
-    - Start the otelcol with the feature gate enabled:
-      - otelcol {other_arguments} --feature-gates=receiver.hostmetricsreceiver.removeDirectionAttributeNetworkMetrics
-    - Start the otelcol with the feature gate disabled:
-      - otelcol {other_arguments} --feature-gates=-receiver.hostmetricsreceiver.removeDirectionAttributeNetworkMetrics
-  - More information:
-    - https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/11815
-    - https://github.com/open-telemetry/opentelemetry-specification/pull/2617
-- `receiver.hostmetricsreceiver.removeDirectionAttributePagingMetrics`
-  - Description
-    - Some paging metrics reported by the hostmetricsreceiver are transitioning from being reported
-		with a direction attribute to being reported with the direction included in the metric name to adhere to the
-		OpenTelemetry specification. Please update any monitoring this might affect.
-  - Affected Metrics
-    - `system.paging.operations` will become:
-      - `system.paging.operations.page_in`
-      - `system.paging.operations.page_out`
-  - Stages and Timeline
-    - Alpha (current stage)
-      - In this stage the feature gate is disabled by default and must be enabled by the user. This allows users to preemptively opt in and start using the bug fix by enabling the feature gate.
-      - Collector version: v0.55.0
-      - Release Date: Early July 2022
-    - Beta
-      - In this stage the feature gate is enabled by default and can be disabled by the user.
-      - Collector version: v0.57.0
-      - Release Date: Early August 2022
-    - Generally Available
-      - In this stage the feature gate is permanently enabled and the feature gate is no longer available for anyone.
-      - Users could experience some friction in this stage, they may have to update monitoring for the affected metrics or be blocked from upgrading the collector to versions v0.59.0 and newer.
-      - Collector version: v0.59.0
-      - Release Date: Early September 2022
-  - Usage
-    - Feature gate identifiers prefixed with - will disable the gate and prefixing with + or with no prefix will enable the gate.
-    - Start the otelcol with the feature gate enabled:
-      - otelcol {other_arguments} --feature-gates=receiver.hostmetricsreceiver.removeDirectionAttributePagingMetrics
-    - Start the otelcol with the feature gate disabled:
-      - otelcol {other_arguments} --feature-gates=-receiver.hostmetricsreceiver.removeDirectionAttributePagingMetrics
-  - More information:
-    - https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/11815
-    - https://github.com/open-telemetry/opentelemetry-specification/pull/2617
-- `receiver.hostmetricsreceiver.removeDirectionAttributeProcessMetrics`
-  - Description
-    - Some process metrics reported by the hostmetricsreceiver are transitioning from being reported
-		with a direction attribute to being reported with the direction included in the metric name to adhere to the
-		OpenTelemetry specification. Please update any monitoring this might affect.
-  - Affected Metrics
-    - `process.disk.io` will become:
-      - `process.disk.io.read`
-      - `process.disk.io.write`
-  - Stages and Timeline
-    - Alpha (current stage)
-      - In this stage the feature gate is disabled by default and must be enabled by the user. This allows users to preemptively opt in and start using the bug fix by enabling the feature gate.
-      - Collector version: v0.55.0
-      - Release Date: Early July 2022
-    - Beta
-      - In this stage the feature gate is enabled by default and can be disabled by the user.
-      - Collector version: v0.57.0
-      - Release Date: Early August 2022
-    - Generally Available
-      - In this stage the feature gate is permanently enabled and the feature gate is no longer available for anyone.
-      - Users could experience some friction in this stage, they may have to update monitoring for the affected metrics or be blocked from upgrading the collector to versions v0.59.0 and newer.
-      - Collector version: v0.59.0
-      - Release Date: Early September 2022
-  - Usage
-    - Feature gate identifiers prefixed with - will disable the gate and prefixing with + or with no prefix will enable the gate.
-    - Start the otelcol with the feature gate enabled:
-      - otelcol {other_arguments} --feature-gates=receiver.hostmetricsreceiver.removeDirectionAttributeProcessMetrics
-    - Start the otelcol with the feature gate disabled:
-      - otelcol {other_arguments} --feature-gates=-receiver.hostmetricsreceiver.removeDirectionAttributeProcessMetrics
-  - More information:
-    - https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/11815
-    - https://github.com/open-telemetry/opentelemetry-specification/pull/2617
+#### Transition from metrics with "direction" attribute
+
+Some host metrics reported are transitioning from being reported with a `direction` attribute to being reported with the
+direction included in the metric name to adhere to the OpenTelemetry specification
+(https://github.com/open-telemetry/opentelemetry-specification/pull/2617):
+
+- `network` scraper metrics:
+  - `system.network.dropped` will become:
+    - `system.network.dropped.receive`
+    - `system.network.dropped.transmit`
+  - `system.network.errors` will become:
+    - `system.network.errors.receive`
+    - `system.network.errors.transmit`
+  - `system.network.io` will become:
+    - `system.network.io.receive`
+    - `system.network.io.transmit`
+  - `system.network.packets` will become:
+    - `system.network.packets.receive`
+    - `system.network.packets.transmit`
+- `paging` scraper metrics:
+  - `system.paging.operations` will become:
+    - `system.paging.operations.page_in`
+    - `system.paging.operations.page_out`
+- `process` scraper metrics:
+  - `process.disk.io` will become:
+    - `process.disk.io.read`
+    - `process.disk.io.write`
+
+The following feature gates control the transition process:
+
+- **receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute**: controls if the new metrics without
+  `direction` attribute are emitted by the receiver.
+- **receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute**: controls if the deprecated metrics with 
+  `direction`
+  attribute are emitted by the receiver.
+
+##### Transition schedule:
+
+1. v0.55.0, July 2022:
+
+- Most of the scrapers except for `disk` scraper can emit the new metrics without the `direction` attribute if 
+  feature gates enabled.
+- `receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute` is enabled by default.
+- `receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute` is disabled by default.
+
+2. v0.56.0, July 2022:
+
+- The new metrics are available for all scrapers, but disabled by default, they can be enabled with the feature gates.
+- The old metrics with `direction` attribute are deprecated with a warning.
+- `receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute` is enabled by default.
+- `receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute` is disabled by default.
+
+3. v0.58.0, August 2022:
+
+- The new metrics are enabled by default, deprecated metrics disabled, they can be enabled with the feature gates.
+- `receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute` is disabled by default.
+- `receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute` is enabled by default.
+
+4. v0.60.0, September 2022:
+
+- The feature gates are removed.
+- The new metrics without `direction` attribute are always emitted.
+- The deprecated metrics with `direction` attribute are no longer available.
+
+##### Usage:
+
+To enable the new metrics without `direction` attribute and disable the deprecated metrics, run OTel Collector with the 
+following arguments:
+
+```sh
+otelcol --feature-gates=-receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute,+receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute
+```
+
+It's also possible to emit both the deprecated and the new metrics:
+
+```sh
+otelcol --feature-gates=+receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute,+receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute
+```
+
+If both feature gates are enabled, each particular metric can be disabled with the user settings, for example:
+
+```yaml
+receivers:
+  hostmetrics:
+    scrapers:
+      paging:
+        metrics:
+          system.paging.operations:
+            enabled: false
+```
+
+##### More information:
+
+- https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/11815
+- https://github.com/open-telemetry/opentelemetry-specification/pull/2617
 
 [beta]: https://github.com/open-telemetry/opentelemetry-collector#beta
 [contrib]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib

diff --git a/receiver/hostmetricsreceiver/internal/scraper.go b/receiver/hostmetricsreceiver/internal/scraper.go
@@ -19,8 +19,41 @@ import (
 
 	"go.opentelemetry.io/collector/component"
 	"go.opentelemetry.io/collector/receiver/scraperhelper"
+	"go.opentelemetry.io/collector/service/featuregate"
 )
 
+const (
+	EmitMetricsWithDirectionAttributeFeatureGateID    = "receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute"
+	EmitMetricsWithoutDirectionAttributeFeatureGateID = "receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute"
+)
+
+var (
+	emitMetricsWithDirectionAttributeFeatureGate = featuregate.Gate{
+		ID:      EmitMetricsWithDirectionAttributeFeatureGateID,
+		Enabled: true,
+		Description: "Some process host metrics reported are transitioning from being reported with a direction " +
+			"attribute to being reported with the direction included in the metric name to adhere to the " +
+			"OpenTelemetry specification. This feature gate controls emitting the old metrics with the direction " +
+			"attribute. For more details, see: " +
+			"https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/hostmetricsreceiver/README.md#feature-gate-configurations",
+	}
+
+	emitMetricsWithoutDirectionAttributeFeatureGate = featuregate.Gate{
+		ID:      EmitMetricsWithoutDirectionAttributeFeatureGateID,
+		Enabled: false,
+		Description: "Some process host metrics reported are transitioning from being reported with a direction " +
+			"attribute to being reported with the direction included in the metric name to adhere to the " +
+			"OpenTelemetry specification. This feature gate controls emitting the new metrics without the direction " +
+			"attribute. For more details, see: " +
+			"https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/hostmetricsreceiver/README.md#feature-gate-configurations",
+	}
+)
+
+func init() {
+	featuregate.GetRegistry().MustRegister(emitMetricsWithDirectionAttributeFeatureGate)
+	featuregate.GetRegistry().MustRegister(emitMetricsWithoutDirectionAttributeFeatureGate)
+}
+
 // ScraperFactory can create a MetricScraper.
 type ScraperFactory interface {
 	// CreateDefaultConfig creates the default configuration for the Scraper.

diff --git a/receiver/hostmetricsreceiver/internal/scraper/networkscraper/metadata.yaml b/receiver/hostmetricsreceiver/internal/scraper/networkscraper/metadata.yaml
@@ -18,6 +18,7 @@ attributes:
     description: State of the network connection.
 
 metrics:
+  # produced when receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute feature gate is enabled
   system.network.packets:
     enabled: true
     description: The number of packets transferred. (Deprecated)
@@ -28,7 +29,7 @@ metrics:
       monotonic: true
     attributes: [device, direction]
 
-# produced when receiver.hostmetricsreceiver.removeDirectionAttributeNetworkMetrics feature gate is enabled
+  # produced when receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute feature gate is enabled
   system.network.packets.transmit:
     enabled: true
     description: The number of packets transmitted.
@@ -39,7 +40,7 @@ metrics:
       monotonic: true
     attributes: [device]
 
-# produced when receiver.hostmetricsreceiver.removeDirectionAttributeNetworkMetrics feature gate is enabled
+  # produced when receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute feature gate is enabled
   system.network.packets.receive:
     enabled: true
     description: The number of packets received.
@@ -50,6 +51,7 @@ metrics:
       monotonic: true
     attributes: [device]
 
+  # produced when receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute feature gate is enabled
   system.network.dropped:
     enabled: true
     description: The number of packets dropped. (Deprecated)
@@ -60,7 +62,7 @@ metrics:
       monotonic: true
     attributes: [device, direction]
 
-# produced when receiver.hostmetricsreceiver.removeDirectionAttributeNetworkMetrics feature gate is enabled
+  # produced when receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute feature gate is enabled
   system.network.dropped.transmit:
     enabled: true
     description: The number of packets dropped on transmit.
@@ -71,7 +73,7 @@ metrics:
       monotonic: true
     attributes: [device]
 
-# produced when receiver.hostmetricsreceiver.removeDirectionAttributeNetworkMetrics feature gate is enabled
+  # produced when receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute feature gate is enabled
   system.network.dropped.receive:
     enabled: true
     description: The number of packets dropped on receive.
@@ -82,6 +84,7 @@ metrics:
       monotonic: true
     attributes: [device]
 
+  # produced when receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute feature gate is enabled
   system.network.errors:
     enabled: true
     description: The number of errors encountered. (Deprecated)
@@ -92,7 +95,7 @@ metrics:
       monotonic: true
     attributes: [device, direction]
 
-# produced when receiver.hostmetricsreceiver.removeDirectionAttributeNetworkMetrics feature gate is enabled
+  # produced when receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute feature gate is enabled
   system.network.errors.transmit:
     enabled: true
     description: The number of errors encountered on transmit.
@@ -103,7 +106,7 @@ metrics:
       monotonic: true
     attributes: [device]
 
-# produced when receiver.hostmetricsreceiver.removeDirectionAttributeNetworkMetrics feature gate is enabled
+  # produced when receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute feature gate is enabled
   system.network.errors.receive:
     enabled: true
     description: The number of errors encountered on receive.
@@ -114,6 +117,7 @@ metrics:
       monotonic: true
     attributes: [device]
 
+  # produced when receiver.hostmetricsreceiver.emitMetricsWithDirectionAttribute feature gate is enabled
   system.network.io:
     enabled: true
     description: The number of bytes transmitted and received. (Deprecated)
@@ -124,7 +128,7 @@ metrics:
       monotonic: true
     attributes: [device, direction]
 
-# produced when receiver.hostmetricsreceiver.removeDirectionAttributeNetworkMetrics feature gate is enabled
+  # produced when receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute feature gate is enabled
   system.network.io.transmit:
     enabled: true
     description: The number of bytes transmitted.
@@ -135,7 +139,7 @@ metrics:
       monotonic: true
     attributes: [device]
 
-# produced when receiver.hostmetricsreceiver.removeDirectionAttributeNetworkMetrics feature gate is enabled
+  # produced when receiver.hostmetricsreceiver.emitMetricsWithoutDirectionAttribute feature gate is enabled
   system.network.io.receive:
     enabled: true
     description: The number of bytes received.