put direction change behind feature gate

open-telemetry · Jun 29, 2022 · c9e63c4 · c9e63c4
1 parent 4b26ad3
commit c9e63c4
Show file tree

Hide file tree

Showing 8 changed files with 504 additions and 50 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,24 +8,24 @@
   - If users were disabling this feature gate, they may have to update
     monitoring for a few Kubernetes cpu metrics. For more details see [feature-gate-configurations](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/v0.54.0/receiver/k8sclusterreceiver#feature-gate-configurations).
 - `prometheusexporter`: Automatically rename metrics with units to follow Prometheus naming convention (#8950)
-- `hostmetricsreceiver`: remove direction attribute (#11820)
-  - `system.network.dropped` becomes:
+
+### 🚩 Deprecations 🚩
+
+- `logzioexporter`: Announcing `custom_endpoint`, `drain_interval`, `queue_capacity`, `queue_max_length` configuration options will be deprecated in upcoming releases (#10821)
+- `hostmetricsreceiver`: remove direction attribute. The feature gate: `receiver.hostmetricsreceiver.removeDirectionAttribute` can be set to apply the following (#11820)
+  - `system.network.dropped` will become:
     - `system.network.dropped.receive`
     - `system.network.dropped.transmit`
-  - `system.network.errors` becomes:
+  - `system.network.errors` will become:
     - `system.network.errors.receive`
     - `system.network.errors.transmit`
-  - `system.network.io` becomes:
+  - `system.network.io` will become:
     - `system.network.io.receive`
     - `system.network.io.transmit`
-  - `system.network.packets` becomes:
+  - `system.network.packets` will become:
     - `system.network.packets.receive`
     - `system.network.packets.transmit`
 
-### 🚩 Deprecations 🚩
-
-- `logzioexporter`: Announcing `custom_endpoint`, `drain_interval`, `queue_capacity`, `queue_max_length` configuration options will be deprecated in upcoming releases (#10821)
-
 ### 🚀 New components 🚀
 
 ### 💡 Enhancements 💡

diff --git a/receiver/hostmetricsreceiver/README.md b/receiver/hostmetricsreceiver/README.md
@@ -1,7 +1,7 @@
 # Host Metrics Receiver
 
 | Status                   |                   |
-| ------------------------ |-------------------|
+| ------------------------ | ----------------- |
 | Stability                | [beta]            |
 | Supported pipeline types | metrics           |
 | Distributions            | [core], [contrib] |
@@ -27,14 +27,14 @@ hostmetrics:
 The available scrapers are:
 
 | Scraper    | Supported OSs                | Description                                            |
-|------------|------------------------------|--------------------------------------------------------|
+| ---------- | ---------------------------- | ------------------------------------------------------ |
 | cpu        | All except Mac<sup>[1]</sup> | CPU utilization metrics                                |
 | disk       | All except Mac<sup>[1]</sup> | Disk I/O metrics                                       |
 | load       | All                          | CPU load metrics                                       |
 | filesystem | All                          | File System utilization metrics                        |
 | memory     | All                          | Memory utilization metrics                             |
 | network    | All                          | Network interface I/O metrics & TCP connection metrics |
-| paging     | All                          | Paging/Swap space utilization and I/O metrics
+| paging     | All                          | Paging/Swap space utilization and I/O metrics          |
 | processes  | Linux                        | Process count metrics                                  |
 | process    | Linux & Windows              | Per process CPU, Memory, and Disk I/O metrics          |
 
@@ -130,6 +130,50 @@ service:
       receivers: [hostmetrics, hostmetrics/disk]
 ```
 
+### 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.k8sclusterreceiver.reportCpuMetricsAsDouble
+    - Start the otelcol with the feature gate disabled:
+      - otelcol {other_arguments} --feature-gates=-receiver.k8sclusterreceiver.reportCpuMetricsAsDouble
+  - 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
 [core]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol

diff --git a/receiver/hostmetricsreceiver/hostmetrics_receiver_test.go b/receiver/hostmetricsreceiver/hostmetrics_receiver_test.go
@@ -58,14 +58,10 @@ var standardMetrics = []string{
 	"system.filesystem.usage",
 	"system.memory.usage",
 	"system.network.connections",
-	"system.network.dropped.receive",
-	"system.network.dropped.transmit",
-	"system.network.errors.receive",
-	"system.network.errors.transmit",
-	"system.network.io.receive",
-	"system.network.io.transmit",
-	"system.network.packets.receive",
-	"system.network.packets.transmit",
+	"system.network.dropped",
+	"system.network.errors",
+	"system.network.io",
+	"system.network.packets",
 	"system.paging.operations",
 	"system.paging.usage",
 }

diff --git a/receiver/hostmetricsreceiver/internal/scraper/networkscraper/documentation.md b/receiver/hostmetricsreceiver/internal/scraper/networkscraper/documentation.md
@@ -9,12 +9,16 @@ These are the metrics available for this scraper.
 | Name | Description | Unit | Type | Attributes |
 | ---- | ----------- | ---- | ---- | ---------- |
 | **system.network.connections** | The number of connections. | {connections} | Sum(Int) | <ul> <li>protocol</li> <li>state</li> </ul> |
+| **system.network.dropped** | The number of packets dropped. (Deprecated) | {packets} | Sum(Int) | <ul> <li>device</li> <li>direction</li> </ul> |
 | **system.network.dropped.receive** | The number of packets dropped on receive. | {packets} | Sum(Int) | <ul> <li>device</li> </ul> |
 | **system.network.dropped.transmit** | The number of packets dropped on transmit. | {packets} | Sum(Int) | <ul> <li>device</li> </ul> |
+| **system.network.errors** | The number of errors encountered. (Deprecated) | {errors} | Sum(Int) | <ul> <li>device</li> <li>direction</li> </ul> |
 | **system.network.errors.receive** | The number of errors encountered on receive. | {errors} | Sum(Int) | <ul> <li>device</li> </ul> |
 | **system.network.errors.transmit** | The number of errors encountered on transmit. | {errors} | Sum(Int) | <ul> <li>device</li> </ul> |
+| **system.network.io** | The number of bytes transmitted and received. (Deprecated) | By | Sum(Int) | <ul> <li>device</li> <li>direction</li> </ul> |
 | **system.network.io.receive** | The number of bytes received. | By | Sum(Int) | <ul> <li>device</li> </ul> |
 | **system.network.io.transmit** | The number of bytes transmitted. | By | Sum(Int) | <ul> <li>device</li> </ul> |
+| **system.network.packets** | The number of packets transferred. (Deprecated) | {packets} | Sum(Int) | <ul> <li>device</li> <li>direction</li> </ul> |
 | **system.network.packets.receive** | The number of packets received. | {packets} | Sum(Int) | <ul> <li>device</li> </ul> |
 | **system.network.packets.transmit** | The number of packets transmitted. | {packets} | Sum(Int) | <ul> <li>device</li> </ul> |
 
@@ -32,5 +36,6 @@ metrics:
 | Name | Description | Values |
 | ---- | ----------- | ------ |
 | device | Name of the network interface. |  |
+| direction | Direction of flow of bytes/operations (receive or transmit). | receive, transmit |
 | protocol | Network protocol, e.g. TCP or UDP. | tcp |
 | state | State of the network connection. |  |