internal/exp/metrics: identity types (open-telemetry#31017)

Adds a new internal, _experimental_ package `metrics/identity` which
implements identity types for resource, scope, metric and stream.

This is closely related to work being done in open-telemetry#30707 and open-telemetry#30827.

The package is specifically experimental, as it shall be treated as an
internal component to above processors which may change at any moment as
long as those are under active initial development.

/cc @jpkrohling @djaglowski @RichieSams

.github/CODEOWNERS

@@ -120,6 +120,7 @@ internal/collectd/                                       @open-telemetry/collect
 internal/coreinternal/                                   @open-telemetry/collector-contrib-approvers @open-telemetry/collector-approvers
 internal/datadog/                                        @open-telemetry/collector-contrib-approvers @mx-psi @dineshg13
 internal/docker/                                         @open-telemetry/collector-contrib-approvers @rmfitzpatrick @jamesmoessis
+internal/exp/metrics/                                    @open-telemetry/collector-contrib-approvers @sh0rez @RichieSams
 internal/filter/                                         @open-telemetry/collector-contrib-approvers @open-telemetry/collector-approvers
 internal/k8sconfig/                                      @open-telemetry/collector-contrib-approvers @dmitryax
 internal/k8stest/                                        @open-telemetry/collector-contrib-approvers @crobert-1

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -118,6 +118,7 @@ body:
       - internal/core
       - internal/datadog
       - internal/docker
+      - internal/exp/metrics
       - internal/filter
       - internal/k8sconfig
       - internal/k8stest

.github/ISSUE_TEMPLATE/feature_request.yaml

@@ -112,6 +112,7 @@ body:
       - internal/core
       - internal/datadog
       - internal/docker
+      - internal/exp/metrics
       - internal/filter
       - internal/k8sconfig
       - internal/k8stest

.github/ISSUE_TEMPLATE/other.yaml

@@ -112,6 +112,7 @@ body:
       - internal/core
       - internal/datadog
       - internal/docker
+      - internal/exp/metrics
       - internal/filter
       - internal/k8sconfig
       - internal/k8stest

internal/exp/metrics/Makefile

@@ -0,0 +1 @@
+include ../../../Makefile.Common

internal/exp/metrics/go.mod

@@ -0,0 +1,28 @@
+module github.com/open-telemetry/opentelemetry-collector-contrib/internal/exp/metrics
+
+replace github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatautil => ../../../pkg/pdatautil
+
+require (
+	github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatautil v0.0.0-00010101000000-000000000000
+	go.opentelemetry.io/collector/pdata v1.1.0
+)
+
+require (
+	github.com/cespare/xxhash/v2 v2.2.0 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/golang/protobuf v1.5.3 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.2 // indirect
+	go.uber.org/multierr v1.11.0 // indirect
+	golang.org/x/net v0.18.0 // indirect
+	golang.org/x/sys v0.14.0 // indirect
+	golang.org/x/text v0.14.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20231106174013-bbf56f31fb17 // indirect
+	google.golang.org/grpc v1.61.0 // indirect
+	google.golang.org/protobuf v1.32.0 // indirect
+)
+
+go 1.21
+
+toolchain go1.21.1

internal/exp/metrics/identity/doc.go

@@ -0,0 +1,8 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+// identity types for metrics and sample streams.
+//
+// Use the `Of*(T) -> I` functions to obtain a unique, comparable (==) and
+// hashable (map key) identity value I for T.
+package identity // import "github.com/open-telemetry/opentelemetry-collector-contrib/internal/exp/metrics/identity"

internal/exp/metrics/identity/metric.go

@@ -0,0 +1,71 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package identity // import "github.com/open-telemetry/opentelemetry-collector-contrib/internal/exp/metrics/identity"
+
+import (
+	"hash"
+
+	"go.opentelemetry.io/collector/pdata/pcommon"
+	"go.opentelemetry.io/collector/pdata/pmetric"
+)
+
+type metric = Metric
+
+type Metric struct {
+	scope
+
+	name string
+	unit string
+	ty   pmetric.MetricType
+
+	monotonic   bool
+	temporality pmetric.AggregationTemporality
+}
+
+func (i Metric) Hash() hash.Hash64 {
+	sum := i.scope.Hash()
+	sum.Write([]byte(i.name))
+	sum.Write([]byte(i.unit))
+
+	var mono byte
+	if i.monotonic {
+		mono = 1
+	}
+	sum.Write([]byte{byte(i.ty), mono, byte(i.temporality)})
+	return sum
+}
+
+func (i Metric) Scope() Scope {
+	return i.scope
+}
+
+func OfMetric(scope Scope, m pmetric.Metric) Metric {
+	id := Metric{
+		scope: scope,
+		name:  m.Name(),
+		unit:  m.Unit(),
+		ty:    m.Type(),
+	}
+
+	switch m.Type() {
+	case pmetric.MetricTypeSum:
+		sum := m.Sum()
+		id.monotonic = sum.IsMonotonic()
+		id.temporality = sum.AggregationTemporality()
+	case pmetric.MetricTypeExponentialHistogram:
+		exp := m.ExponentialHistogram()
+		id.monotonic = true
+		id.temporality = exp.AggregationTemporality()
+	case pmetric.MetricTypeHistogram:
+		hist := m.Histogram()
+		id.monotonic = true
+		id.temporality = hist.AggregationTemporality()
+	}
+
+	return id
+}
+
+func OfResourceMetric(res pcommon.Resource, scope pcommon.InstrumentationScope, metric pmetric.Metric) Metric {
+	return OfMetric(OfScope(OfResource(res), scope), metric)
+}

internal/exp/metrics/identity/resource.go

@@ -0,0 +1,31 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package identity // import "github.com/open-telemetry/opentelemetry-collector-contrib/internal/exp/metrics/identity"
+
+import (
+	"hash"
+	"hash/fnv"
+
+	"go.opentelemetry.io/collector/pdata/pcommon"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatautil"
+)
+
+type resource = Resource
+
+type Resource struct {
+	attrs [16]byte
+}
+
+func (r Resource) Hash() hash.Hash64 {
+	sum := fnv.New64a()
+	sum.Write(r.attrs[:])
+	return sum
+}
+
+func OfResource(r pcommon.Resource) Resource {
+	return Resource{
+		attrs: pdatautil.MapHash(r.Attributes()),
+	}
+}

internal/exp/metrics/identity/scope.go

@@ -0,0 +1,43 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package identity // import "github.com/open-telemetry/opentelemetry-collector-contrib/internal/exp/metrics/identity"
+
+import (
+	"hash"
+
+	"go.opentelemetry.io/collector/pdata/pcommon"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatautil"
+)
+
+type scope = Scope
+
+type Scope struct {
+	resource resource
+
+	name    string
+	version string
+	attrs   [16]byte
+}
+
+func (s Scope) Hash() hash.Hash64 {
+	sum := s.resource.Hash()
+	sum.Write([]byte(s.name))
+	sum.Write([]byte(s.version))
+	sum.Write(s.attrs[:])
+	return sum
+}
+
+func (s Scope) Resource() Resource {
+	return s.resource
+}
+
+func OfScope(res Resource, scope pcommon.InstrumentationScope) Scope {
+	return Scope{
+		resource: res,
+		name:     scope.Name(),
+		version:  scope.Version(),
+		attrs:    pdatautil.MapHash(scope.Attributes()),
+	}
+}

internal/exp/metrics/identity/stream.go

@@ -0,0 +1,37 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package identity // import "github.com/open-telemetry/opentelemetry-collector-contrib/internal/exp/metrics/identity"
+
+import (
+	"hash"
+
+	"go.opentelemetry.io/collector/pdata/pcommon"
+	"go.opentelemetry.io/collector/pdata/pmetric"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/pkg/pdatautil"
+)
+
+type Stream struct {
+	metric
+	attrs [16]byte
+}
+
+func (i Stream) Hash() hash.Hash64 {
+	sum := i.metric.Hash()
+	sum.Write(i.attrs[:])
+	return sum
+}
+
+func (i Stream) Metric() Metric {
+	return i.metric
+}
+
+func OfStream[DataPoint attrPoint](m Metric, dp DataPoint) Stream {
+	return Stream{metric: m, attrs: pdatautil.MapHash(dp.Attributes())}
+}
+
+type attrPoint interface {
+	pmetric.NumberDataPoint | pmetric.HistogramDataPoint | pmetric.ExponentialHistogramDataPoint | pmetric.SummaryDataPoint
+	Attributes() pcommon.Map
+}

internal/exp/metrics/identity/strings.go

@@ -0,0 +1,24 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package identity // import "github.com/open-telemetry/opentelemetry-collector-contrib/internal/exp/metrics/identity"
+
+import (
+	"fmt"
+)
+
+func (r Resource) String() string {
+	return fmt.Sprintf("resource/%x", r.Hash().Sum64())
+}
+
+func (s Scope) String() string {
+	return fmt.Sprintf("scope/%x", s.Hash().Sum64())
+}
+
+func (m Metric) String() string {
+	return fmt.Sprintf("metric/%x", m.Hash().Sum64())
+}
+
+func (s Stream) String() string {
+	return fmt.Sprintf("stream/%x", s.Hash().Sum64())
+}

internal/exp/metrics/metadata.yaml

@@ -0,0 +1,3 @@
+status:
+  codeowners:
+    active: [sh0rez, RichieSams]

versions.yaml

@@ -116,6 +116,7 @@ module-sets:
       - github.com/open-telemetry/opentelemetry-collector-contrib/internal/common
       - github.com/open-telemetry/opentelemetry-collector-contrib/internal/coreinternal
       - github.com/open-telemetry/opentelemetry-collector-contrib/internal/docker
+      - github.com/open-telemetry/opentelemetry-collector-contrib/internal/exp/metrics
       - github.com/open-telemetry/opentelemetry-collector-contrib/internal/filter
       - github.com/open-telemetry/opentelemetry-collector-contrib/internal/k8sconfig
       - github.com/open-telemetry/opentelemetry-collector-contrib/internal/k8stest