Skip to content

Commit

Permalink
Add WithScopeAttributes MeterOption to metric API package (open-telem…
Browse files Browse the repository at this point in the history
…etry#3132)

* Add WithScopeAttributes MeterOption to metric pkg

* Add MeterConfig unit tests

* Add changes to changelog

* Fix import linting

* Update MeterProvider documentation

Include information about how to use WithScopeAttributes.
  • Loading branch information
MrAlias authored Sep 1, 2022
1 parent 0078fae commit 81a9bab
Show file tree
Hide file tree
Showing 4 changed files with 131 additions and 8 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
- Upgrade go.opentelemetry.io/proto/otlp from v0.18.0 to v0.19.0 (#3107)
- Add an `Attribute` field to the `Scope` type in `go.opentelemetry.io/otel/sdk/instrumentation`. (#3131)
- Add the `WithScopeAttributes` `TracerOption` to the `go.opentelemetry.io/otel/trace` package. (#3131)
- Add the `WithScopeAttributes` `MeterOption` to the `go.opentelemetry.io/otel/metric` package. (#3132)

### Changed

Expand Down
18 changes: 18 additions & 0 deletions metric/config.go
Original file line number Diff line number Diff line change
Expand Up @@ -14,10 +14,13 @@

package metric // import "go.opentelemetry.io/otel/metric"

import "go.opentelemetry.io/otel/attribute"

// MeterConfig contains options for Meters.
type MeterConfig struct {
instrumentationVersion string
schemaURL string
attributes attribute.Set
}

// InstrumentationVersion is the version of the library providing instrumentation.
Expand All @@ -30,6 +33,11 @@ func (cfg MeterConfig) SchemaURL() string {
return cfg.schemaURL
}

// Attributes returns the scope attribute set of the Meter.
func (t MeterConfig) Attributes() attribute.Set {
return t.attributes
}

// MeterOption is an interface for applying Meter options.
type MeterOption interface {
// applyMeter is used to set a MeterOption value of a MeterConfig.
Expand Down Expand Up @@ -67,3 +75,13 @@ func WithSchemaURL(schemaURL string) MeterOption {
return config
})
}

// WithScopeAttributes sets the attributes for the scope of a Meter. The
// attributes are stored as an attribute set. Duplicate values are removed, the
// last value is used.
func WithScopeAttributes(attr ...attribute.KeyValue) MeterOption {
return meterOptionFunc(func(cfg MeterConfig) MeterConfig {
cfg.attributes = attribute.NewSet(attr...)
return cfg
})
}
69 changes: 69 additions & 0 deletions metric/config_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
// Copyright The 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 // import "go.opentelemetry.io/otel/metric"

import (
"testing"

"github.com/stretchr/testify/assert"

"go.opentelemetry.io/otel/attribute"
)

func TestMeterConfig(t *testing.T) {
t.Run("Empty", func(t *testing.T) {
assert.Equal(t, NewMeterConfig(), MeterConfig{})
})

t.Run("InstrumentationVersion", func(t *testing.T) {
v0, v1 := "v0.1.0", "v1.0.0"

assert.Equal(t, NewMeterConfig(
WithInstrumentationVersion(v0),
).InstrumentationVersion(), v0)

assert.Equal(t, NewMeterConfig(
WithInstrumentationVersion(v0),
WithInstrumentationVersion(v1),
).InstrumentationVersion(), v1, "last option has precedence")
})

t.Run("SchemaURL", func(t *testing.T) {
s120 := "https://opentelemetry.io/schemas/1.2.0"
s130 := "https://opentelemetry.io/schemas/1.3.0"

assert.Equal(t, NewMeterConfig(
WithSchemaURL(s120),
).SchemaURL(), s120)

assert.Equal(t, NewMeterConfig(
WithSchemaURL(s120),
WithSchemaURL(s130),
).SchemaURL(), s130, "last option has precedence")
})

t.Run("Attributes", func(t *testing.T) {
one, two := attribute.Int("key", 1), attribute.Int("key", 2)

assert.Equal(t, NewMeterConfig(
WithScopeAttributes(one, two),
).Attributes(), attribute.NewSet(two), "last attribute is used")

assert.Equal(t, NewMeterConfig(
WithScopeAttributes(two),
WithScopeAttributes(one),
).Attributes(), attribute.NewSet(one), "last option has precedence")
})
}
51 changes: 43 additions & 8 deletions metric/meter.go
Original file line number Diff line number Diff line change
Expand Up @@ -24,15 +24,50 @@ import (
"go.opentelemetry.io/otel/metric/instrument/syncint64"
)

// MeterProvider provides access to named Meter instances, for instrumenting
// an application or library.
// MeterProvider provides Meters that are used by instrumentation code to
// create instruments that measure code operations.
//
// A MeterProvider is the collection destination of all measurements made from
// instruments the provided Meters created, it represents a unique telemetry
// collection pipeline. How that pipeline is defined, meaning how those
// measurements are collected, processed, and where they are exported, depends
// on its implementation. Instrumentation authors do not need to define this
// implementation, rather just use the provided Meters to instrument code.
//
// Commonly, instrumentation code will accept a MeterProvider implementation at
// runtime from its users or it can simply use the globally registered one (see
// https://pkg.go.dev/go.opentelemetry.io/otel/metric/global#MeterProvider).
//
// Warning: methods may be added to this interface in minor releases.
type MeterProvider interface {
// Meter creates an instance of a `Meter` interface. The instrumentationName
// must be the name of the library providing instrumentation. This name may
// be the same as the instrumented code only if that code provides built-in
// instrumentation. If the instrumentationName is empty, then a
// implementation defined default name will be used instead.
Meter(instrumentationName string, opts ...MeterOption) Meter
// Meter returns a unique Meter scoped to be used by instrumentation code
// to measure code operations. The scope and identity of that
// instrumentation code is uniquely defined by the name and options passed.
//
// The passed name needs to uniquely identify instrumentation code.
// Therefore, it is recommended that name is the Go package name of the
// library providing instrumentation (note: not the code being
// instrumented). Instrumentation libraries can have multiple versions,
// therefore, the WithInstrumentationVersion option should be used to
// distinguish these different codebases. Additionally, instrumentation
// libraries may sometimes use metric measurements to communicate different
// domains of code operations data (i.e. using different Meters to
// communicate user experience and back-end operations). If this is the
// case, the WithScopeAttributes option should be used to uniquely identify
// Meters that handle the different domains of code operations data.
//
// If the same name and options are passed multiple times, the same Meter
// will be returned (it is up to the implementation if this will be the
// same underlying instance of that Meter or not). It is not necessary to
// call this multiple times with the same name and options to get an
// up-to-date Meter. All implementations will ensure any MeterProvider
// configuration changes are propagated to all provided Meters.
//
// If name is empty, then an implementation defined default name will be
// used instead.
//
// This method is safe to call concurrently.
Meter(name string, options ...MeterOption) Meter
}

// Meter provides access to instrument instances for recording metrics.
Expand Down

0 comments on commit 81a9bab

Please sign in to comment.