Metrics proposal for Go

api/metric/additive.go

@@ -0,0 +1,25 @@
+// Copyright 2019, OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package metric
+
+type Float64AdditiveHandle struct {
+	Handle
+}
+
+func NewFloat64Additive(name string, mos ...Option) *Float64AdditiveHandle {
+	g := &Float64AdditiveHandle{}
+	registerMetric(name, Additive, mos, &g.Handle)
+	return g
+}

api/metric/aggregation/descriptor.go

@@ -0,0 +1,28 @@
+// Copyright 2019, OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package aggregation
+
+//go:generate stringer -type=Operator
+type Operator int
+
+const (
+	NONE Operator = iota
+	SUM
+	COUNT
+	MIN
+	MAX
+	LAST_VALUE
+	DISTRIBUTION
+)

api/metric/api.go

@@ -18,32 +18,51 @@ import (
 	"context"
 
 	"go.opentelemetry.io/api/core"
+	"go.opentelemetry.io/api/metric/aggregation"
 	"go.opentelemetry.io/api/registry"
 	"go.opentelemetry.io/api/unit"
 )
 
-type MetricType int
+type Type int
 
+//go:generate stringer -type=Type
 const (
-	Invalid    MetricType = iota
-	Gauge                 // Supports Set()
-	Cumulative            // Supports Inc()
+	Invalid    Type = iota
+	Gauge           // Supports Set()
+	Cumulative      // Supports Inc(): only positive values
+	Additive        // Supports Add(): positive or negative
+	Measure         // Supports Record()
 )
 
 type Meter interface {
-	// TODO more Metric types
-	GetFloat64Gauge(ctx context.Context, gauge *Float64GaugeHandle, labels ...core.KeyValue) Float64Gauge
+	GetFloat64Gauge(context.Context, *Float64GaugeHandle, ...core.KeyValue) Float64Gauge
+	GetFloat64Cumulative(context.Context, *Float64CumulativeHandle, ...core.KeyValue) Float64Cumulative
+	GetFloat64Additive(context.Context, *Float64AdditiveHandle, ...core.KeyValue) Float64Additive
+	GetFloat64Measure(context.Context, *Float64MeasureHandle, ...core.KeyValue) Float64Measure
 }
 
 type Float64Gauge interface {
 	Set(ctx context.Context, value float64, labels ...core.KeyValue)
 }
 
+type Float64Cumulative interface {
+	Inc(ctx context.Context, value float64, labels ...core.KeyValue)
+}
+
+type Float64Additive interface {
+	Add(ctx context.Context, value float64, labels ...core.KeyValue)
+}
+
+type Float64Measure interface {
+	Record(ctx context.Context, value float64, labels ...core.KeyValue)
+}
+
 type Handle struct {
 	Variable registry.Variable
 
-	Type MetricType
-	Keys []core.Key
+	Type        Type
+	Keys        []core.Key
+	Aggregation aggregation.Operator
 }
 
 type Option func(*Handle, *[]registry.Option)
@@ -62,20 +81,25 @@ func WithUnit(unit unit.Unit) Option {
 	}
 }
 
-// WithKeys applies the provided dimension keys.
+// WithKeys applies recommended dimension keys.  Multiple `WithKeys`
+// options accumulate.  The keys specified in this way are taken as
+// the recommended aggregation keys for Gauge, Cumulative, and
+// Additive metrics.  For Measure metrics, the keys recommended here
+// are taken as the default for aggregations.
 func WithKeys(keys ...core.Key) Option {
 	return func(m *Handle, _ *[]registry.Option) {
-		m.Keys = keys
+		m.Keys = append(m.Keys, keys...)
 	}
 }
 
-func (mtype MetricType) String() string {
-	switch mtype {
-	case Gauge:
-		return "gauge"
-	case Cumulative:
-		return "cumulative"
-	default:
-		return "unknown"
+// WithAggregation applies a user-recommended aggregation to this
+// metric, useful particularly for Measure type metrics.
+func WithAggregation(aggr aggregation.Operator) Option {
+	return func(m *Handle, _ *[]registry.Option) {
+		m.Aggregation = aggr
 	}
 }
+
+func (h Handle) Defined() bool {
+	return h.Variable.Defined()
+}

api/metric/common.go

@@ -18,7 +18,7 @@ import (
 	"go.opentelemetry.io/api/registry"
 )
 
-func registerMetric(name string, mtype MetricType, opts []Option, metric *Handle) {
+func registerMetric(name string, mtype Type, opts []Option, metric *Handle) {
 	var varOpts []registry.Option
 
 	for _, opt := range opts {

api/metric/cumulative.go

@@ -0,0 +1,25 @@
+// Copyright 2019, OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package metric
+
+type Float64CumulativeHandle struct {
+	Handle
+}
+
+func NewFloat64Cumulative(name string, mos ...Option) *Float64CumulativeHandle {
+	g := &Float64CumulativeHandle{}
+	registerMetric(name, Cumulative, mos, &g.Handle)
+	return g
+}

api/metric/measure.go

@@ -0,0 +1,25 @@
+// Copyright 2019, OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package metric
+
+type Float64MeasureHandle struct {
+	Handle
+}
+
+func NewFloat64Measure(name string, mos ...Option) *Float64MeasureHandle {
+	g := &Float64MeasureHandle{}
+	registerMetric(name, Measure, mos, &g.Handle)
+	return g
+}

api/metric/noop_meter.go

@@ -13,10 +13,34 @@ type noopMetric struct{}
 var _ Meter = noopMeter{}
 
 var _ Float64Gauge = noopMetric{}
+var _ Float64Cumulative = noopMetric{}
+var _ Float64Additive = noopMetric{}
+var _ Float64Measure = noopMetric{}
 
 func (noopMeter) GetFloat64Gauge(ctx context.Context, gauge *Float64GaugeHandle, labels ...core.KeyValue) Float64Gauge {
 	return noopMetric{}
 }
 
+func (noopMeter) GetFloat64Cumulative(ctx context.Context, gauge *Float64CumulativeHandle, labels ...core.KeyValue) Float64Cumulative {
+	return noopMetric{}
+}
+
+func (noopMeter) GetFloat64Additive(ctx context.Context, gauge *Float64AdditiveHandle, labels ...core.KeyValue) Float64Additive {
+	return noopMetric{}
+}
+
+func (noopMeter) GetFloat64Measure(ctx context.Context, gauge *Float64MeasureHandle, labels ...core.KeyValue) Float64Measure {
+	return noopMetric{}
+}
+
 func (noopMetric) Set(ctx context.Context, value float64, labels ...core.KeyValue) {
 }
+
+func (noopMetric) Inc(ctx context.Context, value float64, labels ...core.KeyValue) {
+}
+
+func (noopMetric) Add(ctx context.Context, value float64, labels ...core.KeyValue) {
+}
+
+func (noopMetric) Record(ctx context.Context, value float64, labels ...core.KeyValue) {
+}