[receiver/memcached] remove direction attribute (open-telemetry#12404)

* generate memcached metrics without direction attribute

* add memcached direction attribute featuregates

* abide by featuregates when recording memcached network metrics

* update readme

* add changelog

* reference pr# in changelog

* add comment to metadata.yaml

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 {