view

package
v0.34.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 5, 2022 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package view provides types and functionality that customize the metric telemetry an SDK will produce. The View type is used when a Reader is registered with a MeterProvider in the go.opentelemetry.io/otel/sdk/metric package. See the WithReader option in that package for more information on how this registration takes place.

Deprecated: Use Instrument, InstrumentKind, View, and NewView in go.opentelemetry.io/otel/sdk/metric instead.

Example 
// The "active-users" instrument created by the
// "github.com/super/noisy/instrumentation/package" your project includes
// has a bug, it records a measurment any time a user has any activity.
// This is causing a lot of strain on your program without providing any
// value to you. The next version of
// "github.com/super/noisy/instrumentation/package" corrects the
// instrumentation to only record a value when a user logs in, but it
// isn't out yet.
//
// Use a View to drop these measurments while you wait for the fix to come
// from upstream.

v, err := New(
	MatchInstrumentName("active-users"),
	MatchInstrumentationScope(instrumentation.Scope{
		Name:    "github.com/super/noisy/instrumentation/package",
		Version: "v0.22.0", // Only match the problematic instrumentation version.
	}),
	WithSetAggregation(aggregation.Drop{}),
)
if err != nil {
	panic(err)
}

// The SDK this view is registered with calls TransformInstrument when an
// instrument is created. Test that our fix will work as intended.
i, _ := v.TransformInstrument(Instrument{
	Name: "active-users",
	Scope: instrumentation.Scope{
		Name:    "github.com/super/noisy/instrumentation/package",
		Version: "v0.22.0",
	},
	Aggregation: aggregation.LastValue{},
})
fmt.Printf("Instrument{%q: %s}: %#v\n", i.Name, i.Scope.Version, i.Aggregation)

// Also, ensure the next version will not be transformed.
_, ok := v.TransformInstrument(Instrument{
	Name: "active-users",
	Scope: instrumentation.Scope{
		Name:    "github.com/super/noisy/instrumentation/package",
		Version: "v0.23.0",
	},
	Aggregation: aggregation.LastValue{},
})
fmt.Printf("Instrument{\"active-users\": v0.23.0} matched: %t\n", ok)

Output:


Instrument{"active-users": v0.22.0}: aggregation.Drop{}
Instrument{"active-users": v0.23.0} matched: false

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Instrument deprecated 

type Instrument struct {
	Scope instrumentation.Scope

	Name        string
	Description string
	Kind        InstrumentKind
	Aggregation aggregation.Aggregation
}

Instrument uniquely identifies an instrument within a meter.

Deprecated: Use Instrument in go.opentelemetry.io/otel/sdk/metric instead.

type InstrumentKind deprecated 

type InstrumentKind uint8

InstrumentKind describes the kind of instrument a Meter can create.

Deprecated: Use InstrumentKind in go.opentelemetry.io/otel/sdk/metric instead. 

const (

	// SyncCounter is an instrument kind that records increasing values
	// synchronously in application code.
	//
	// Deprecated: Use InstrumentKindSyncCounter in
	// go.opentelemetry.io/otel/sdk/metric instead.
	SyncCounter InstrumentKind
	// SyncUpDownCounter is an instrument kind that records increasing and
	// decreasing values synchronously in application code.
	//
	// Deprecated: Use InstrumentKindSyncUpDownCounter in
	// go.opentelemetry.io/otel/sdk/metric instead.
	SyncUpDownCounter
	// SyncHistogram is an instrument kind that records a distribution of
	// values synchronously in application code.
	//
	// Deprecated: Use InstrumentKindSyncHistogram in
	// go.opentelemetry.io/otel/sdk/metric instead.
	SyncHistogram
	// AsyncCounter is an instrument kind that records increasing values in an
	// asynchronous callback.
	//
	// Deprecated: Use InstrumentKindAsyncCounter in
	// go.opentelemetry.io/otel/sdk/metric instead.
	AsyncCounter
	// AsyncUpDownCounter is an instrument kind that records increasing and
	// decreasing values in an asynchronous callback.
	//
	// Deprecated: Use InstrumentKindAsyncUpDownCounter in
	// go.opentelemetry.io/otel/sdk/metric instead.
	AsyncUpDownCounter
	// AsyncGauge is an instrument kind that records current values in an
	// asynchronous callback.
	//
	// Deprecated: Use InstrumentKindAsyncGauge in
	// go.opentelemetry.io/otel/sdk/metric instead.
	AsyncGauge
)

These are all the instrument kinds supported by the SDK.

type Option 

type Option interface {
	// contains filtered or unexported methods
}

Option applies a configuration option value to a View.

func MatchInstrumentKind 

func MatchInstrumentKind(kind InstrumentKind) Option

MatchInstrumentKind with match an instrument based on the instrument's kind. The default is to match all instrument kinds.

Example 
v, err := New(MatchInstrumentKind(SyncCounter))
if err != nil {
	panic(err)
}

for _, i := range []Instrument{
	{Name: "synchronous counter", Kind: SyncCounter},
	{Name: "synchronous histogram", Kind: SyncHistogram},
	{Name: "asynchronous counter", Kind: AsyncCounter},
} {
	// The SDK calls TransformInstrument when an instrument is created.
	_, ok := v.TransformInstrument(i)
	fmt.Printf("Instrument{%q} matched: %t\n", i.Name, ok)
}

Output:

Instrument{"synchronous counter"} matched: true
Instrument{"synchronous histogram"} matched: false
Instrument{"asynchronous counter"} matched: false

func MatchInstrumentName 

func MatchInstrumentName(name string) Option

MatchInstrumentName will match an instrument based on the its name. This will accept wildcards of * for zero or more characters, and ? for exactly one character. A name of "*" (default) will match all instruments.

Example 
v, err := New(MatchInstrumentName("request-*")) // Wildcard match.
if err != nil {
	panic(err)
}

for _, i := range []Instrument{
	{Name: "request-count"},
	{Name: "request-rate"},
	{Name: "latency"},
} {
	// The SDK calls TransformInstrument when an instrument is created.
	_, ok := v.TransformInstrument(i)
	fmt.Printf("Instrument{%q} matched: %t\n", i.Name, ok)
}

Output:

Instrument{"request-count"} matched: true
Instrument{"request-rate"} matched: true
Instrument{"latency"} matched: false

func MatchInstrumentationScope 

func MatchInstrumentationScope(scope instrumentation.Scope) Option

MatchInstrumentationScope will do an exact match on any instrumentation.Scope field that is non-empty (""). The default is to match all instrumentation scopes.

Example 
v, err := New(MatchInstrumentationScope(instrumentation.Scope{
	Name:    "custom/instrumentation/package",
	Version: "v0.22.0", // Only match this version of instrumentation.
}))
if err != nil {
	panic(err)
}

for _, i := range []Instrument{
	{Name: "v1.0.0 instrumentation", Scope: instrumentation.Scope{
		Name:    "custom/instrumentation/package",
		Version: "v1.0.0",
	}},
	{Name: "v0.22.0 instrumentation", Scope: instrumentation.Scope{
		Name:    "custom/instrumentation/package",
		Version: "v0.22.0",
	}},
} {
	// The SDK calls TransformInstrument when an instrument is created.
	_, ok := v.TransformInstrument(i)
	fmt.Printf("Instrument{%q} matched: %t\n", i.Name, ok)
}

Output:

Instrument{"v1.0.0 instrumentation"} matched: false
Instrument{"v0.22.0 instrumentation"} matched: true

func WithFilterAttributes 

func WithFilterAttributes(keys ...attribute.Key) Option

WithFilterAttributes will select attributes that have a matching key. If not used or empty no filter will be applied.

func WithRename 

func WithRename(name string) Option

WithRename will rename the instrument the view matches. If not used or empty the instrument name will not be changed. Must be used with a non-wildcard instrument name match. The default does not change the instrument name.

Example 
v, err := New(MatchInstrumentName("bad-name"), WithRename("good-name"))
if err != nil {
	panic(err)
}

// The SDK calls TransformInstrument when an instrument is created.
i, _ := v.TransformInstrument(Instrument{Name: "bad-name"})
fmt.Printf("Instrument{%q}\n", i.Name)

Output:

Instrument{"good-name"}

func WithSetAggregation 

func WithSetAggregation(a aggregation.Aggregation) Option

WithSetAggregation will use the aggregation a for matching instruments. If this option is not provided, the reader defined aggregation for the instrument will be used.

If a is misconfigured, it will not be used and an error will be logged.

Example 
v, err := New(MatchInstrumentationScope(instrumentation.Scope{
	Name: "super/noisy/instrumentation/package",
}), WithSetAggregation(aggregation.Drop{}))
if err != nil {
	panic(err)
}

// The SDK calls TransformInstrument when an instrument is created.
i, _ := v.TransformInstrument(Instrument{
	Name: "active-users",
	Scope: instrumentation.Scope{
		Name:    "super/noisy/instrumentation/package",
		Version: "v0.5.0",
	},
	Aggregation: aggregation.LastValue{},
})
fmt.Printf("Instrument{%q}: %#v\n", i.Name, i.Aggregation)

Output:

Instrument{"active-users"}: aggregation.Drop{}

func WithSetDescription 

func WithSetDescription(desc string) Option

WithSetDescription will change the description of the instruments the view matches to desc. If not used or empty the description will not be changed.

Example 
v, err := New(
	MatchInstrumentName("requests"),
	WithSetDescription("Number of requests received"),
)
if err != nil {
	panic(err)
}

// The SDK calls TransformInstrument when an instrument is created.
i, _ := v.TransformInstrument(Instrument{
	Name:        "requests",
	Description: "incorrect description",
})
fmt.Printf("Instrument{%q: %s}\n", i.Name, i.Description)

Output:

Instrument{"requests": Number of requests received}

type View deprecated 

type View struct {
	// contains filtered or unexported fields
}

View provides users with the flexibility to customize the metrics that are output by the SDK. A View can be used to ignore, change the name, description, and aggregation of, and customize which attribute(s) are to be reported by Instruments.

An empty View will match all instruments, and do no transformations.

Deprecated: Use View in go.opentelemetry.io/otel/sdk/metric instead.

func New deprecated 

func New(opts ...Option) (View, error)

New returns a new configured View. If there are any duplicate Options passed, the last one passed will take precedence. The unique, de-duplicated, Options are all applied to the View. An instrument needs to match all of the match Options passed for the View to be applied to it. Similarly, all transform operation Options are applied to matched Instruments.

Deprecated: Use NewView in go.opentelemetry.io/otel/sdk/metric instead.

func (View) AttributeFilter 

func (v View) AttributeFilter() func(attribute.Set) attribute.Set

AttributeFilter returns a function that returns only attributes specified by WithFilterAttributes. If no filter was provided nil is returned.

func (View) TransformInstrument 

func (v View) TransformInstrument(inst Instrument) (transformed Instrument, match bool)

TransformInstrument will check if an instrument matches this view and will convert it if it does.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.