[receiver/memcached] remove direction attribute

receiver/memcachedreceiver/README.md

@@ -42,5 +42,50 @@ receivers:
 The full list of settings exposed for this receiver are documented [here](./config.go)
 with detailed sample configurations [here](./testdata/config.yaml).
 
+## Metrics
+
+Details about the metrics produced by this receiver can be found in [metadata.yaml](./metadata.yaml) with further documentation in [documentation.md](./documentation.md)
+
+### Feature gate configurations
+
+#### Transition from metrics with "direction" attribute
+
+Some memcached 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):
+
+- `memcached.network` will become:
+  - `memcached.network.sent`
+  - `memcached.network.received`
+
+The following feature gates control the transition process:
+
+- **receiver.memcachedreceiver.emitMetricsWithoutDirectionAttribute**: controls if the new metrics without
+  `direction` attribute are emitted by the receiver.
+- **receiver.memcachedreceiver.emitMetricsWithDirectionAttribute**: controls if the deprecated metrics with
+  `direction`
+  attribute are emitted by the receiver.
+
+##### Transition schedule:
+
+1. 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.memcachedreceiver.emitMetricsWithDirectionAttribute` is enabled by default.
+- `receiver.memcachedreceiver.emitMetricsWithoutDirectionAttribute` is disabled by default.
+
+2. v0.58.0, August 2022:
+
+- The new metrics are enabled by default, deprecated metrics disabled, they can be enabled with the feature gates.
+- `receiver.memcachedreceiver.emitMetricsWithDirectionAttribute` is disabled by default.
+- `receiver.memcachedreceiver.emitMetricsWithoutDirectionAttribute` is enabled by default.
+
+3. 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.
+
 [beta]:https://github.com/open-telemetry/opentelemetry-collector#beta
 [contrib]:https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-contrib

receiver/memcachedreceiver/documentation.md

@@ -16,6 +16,8 @@ These are the metrics available for this scraper.
 | **memcached.current_items** | Number of items currently stored in the cache. | {items} | Sum(Int) | <ul> </ul> |
 | **memcached.evictions** | Cache item evictions. | {evictions} | Sum(Int) | <ul> </ul> |
 | **memcached.network** | Bytes transferred over the network. | by | Sum(Int) | <ul> <li>direction</li> </ul> |
+| **memcached.network.received** | Bytes received over the network. | by | Sum(Int) | <ul> </ul> |
+| **memcached.network.sent** | Bytes sent over the network. | by | Sum(Int) | <ul> </ul> |
 | **memcached.operation_hit_ratio** | Hit ratio for operations, expressed as a percentage value between 0.0 and 100.0. | % | Gauge(Double) | <ul> <li>operation</li> </ul> |
 | **memcached.operations** | Operation counts. | {operations} | Sum(Int) | <ul> <li>type</li> <li>operation</li> </ul> |
 | **memcached.threads** | Number of threads used by the memcached instance. | {threads} | Sum(Int) | <ul> </ul> |

receiver/memcachedreceiver/metadata.yaml

@@ -8,12 +8,12 @@ attributes:
     - set
     - flush
     - touch
-  direction: 
+  direction:
     description: Direction of data flow.
     enum:
     - sent
     - received
-  type: 
+  type:
     description: Result of cache request.
     enum:
     - hit
@@ -83,6 +83,7 @@ metrics:
       monotonic: true
       aggregation: cumulative
     attributes: []
+  # produced when receiver.memcachedreceiver.emitMetricsWithDirectionAttribute feature gate is enabled
   memcached.network:
     enabled: true
     description: Bytes transferred over the network.
@@ -92,6 +93,26 @@ metrics:
       monotonic: true
       aggregation: cumulative
     attributes: [direction]
+  # produced when receiver.memcachedreceiver.emitMetricsWithoutDirectionAttribute feature gate is enabled
+  memcached.network.sent:
+    enabled: true
+    description: Bytes sent over the network.
+    unit: by
+    sum:
+      value_type: int
+      monotonic: true
+      aggregation: cumulative
+    attributes: []
+  # produced when receiver.memcachedreceiver.emitMetricsWithoutDirectionAttribute feature gate is enabled
+  memcached.network.received:
+    enabled: true
+    description: Bytes received over the network.
+    unit: by
+    sum:
+      value_type: int
+      monotonic: true
+      aggregation: cumulative
+    attributes: []
   memcached.operations:
     enabled: true
     description:  Operation counts.

receiver/memcachedreceiver/scraper.go

@@ -22,27 +22,64 @@ import (
 	"go.opentelemetry.io/collector/component"
 	"go.opentelemetry.io/collector/pdata/pcommon"
 	"go.opentelemetry.io/collector/pdata/pmetric"
+	"go.opentelemetry.io/collector/service/featuregate"
 	"go.uber.org/zap"
 
 	"github.com/open-telemetry/opentelemetry-collector-contrib/receiver/memcachedreceiver/internal/metadata"
 )
 
+const (
+	emitMetricsWithDirectionAttributeFeatureGateID    = "receiver.memcached.emitMetricsWithDirectionAttribute"
+	emitMetricsWithoutDirectionAttributeFeatureGateID = "receiver.memcached.emitMetricsWithoutDirectionAttribute"
+)
+
+var (
+	emitMetricsWithDirectionAttributeFeatureGate = featuregate.Gate{
+		ID:      emitMetricsWithDirectionAttributeFeatureGateID,
+		Enabled: true,
+		Description: "Some memcached 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/memcachedreceiver/README.md#feature-gate-configurations",
+	}
+
+	emitMetricsWithoutDirectionAttributeFeatureGate = featuregate.Gate{
+		ID:      emitMetricsWithoutDirectionAttributeFeatureGateID,
+		Enabled: false,
+		Description: "Some memcached 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/memcachedreceiver/README.md#feature-gate-configurations",
+	}
+)
+
+func init() {
+	featuregate.GetRegistry().MustRegister(emitMetricsWithDirectionAttributeFeatureGate)
+	featuregate.GetRegistry().MustRegister(emitMetricsWithoutDirectionAttributeFeatureGate)
+}
+
 type memcachedScraper struct {
-	logger    *zap.Logger
-	config    *Config
-	mb        *metadata.MetricsBuilder
-	newClient newMemcachedClientFunc
+	logger                               *zap.Logger
+	config                               *Config
+	mb                                   *metadata.MetricsBuilder
+	newClient                            newMemcachedClientFunc
+	emitMetricsWithDirectionAttribute    bool
+	emitMetricsWithoutDirectionAttribute bool
 }
 
 func newMemcachedScraper(
 	settings component.ReceiverCreateSettings,
 	config *Config,
 ) memcachedScraper {
 	return memcachedScraper{
-		logger:    settings.Logger,
-		config:    config,
-		newClient: newMemcachedClient,
-		mb:        metadata.NewMetricsBuilder(config.Metrics, settings.BuildInfo),
+		logger:                               settings.Logger,
+		config:                               config,
+		newClient:                            newMemcachedClient,
+		mb:                                   metadata.NewMetricsBuilder(config.Metrics, settings.BuildInfo),
+		emitMetricsWithDirectionAttribute:    featuregate.GetRegistry().IsEnabled(emitMetricsWithDirectionAttributeFeatureGateID),
+		emitMetricsWithoutDirectionAttribute: featuregate.GetRegistry().IsEnabled(emitMetricsWithoutDirectionAttributeFeatureGateID),
 	}
 }
 
@@ -110,11 +147,21 @@ func (r *memcachedScraper) scrape(_ context.Context) (pmetric.Metrics, error) {
 				}
 			case "bytes_read":
 				if parsedV, ok := r.parseInt(k, v); ok {
-					r.mb.RecordMemcachedNetworkDataPoint(now, parsedV, metadata.AttributeDirectionReceived)
+					if r.emitMetricsWithDirectionAttribute {
+						r.mb.RecordMemcachedNetworkDataPoint(now, parsedV, metadata.AttributeDirectionReceived)
+					}
+					if r.emitMetricsWithoutDirectionAttribute {
+						r.mb.RecordMemcachedNetworkReceivedDataPoint(now, parsedV)
+					}
 				}
 			case "bytes_written":
 				if parsedV, ok := r.parseInt(k, v); ok {
-					r.mb.RecordMemcachedNetworkDataPoint(now, parsedV, metadata.AttributeDirectionSent)
+					if r.emitMetricsWithDirectionAttribute {
+						r.mb.RecordMemcachedNetworkDataPoint(now, parsedV, metadata.AttributeDirectionSent)
+					}
+					if r.emitMetricsWithoutDirectionAttribute {
+						r.mb.RecordMemcachedNetworkSentDataPoint(now, parsedV)
+					}
 				}
 			case "get_hits":
 				if parsedV, ok := r.parseInt(k, v); ok {