metric

Documentation

Overview

Package metric provides an implementation of the metrics part of the OpenTelemetry API.

This package is currently in a pre-GA phase. Backwards incompatible changes may be introduced in subsequent minor version releases as we work to track the evolving OpenTelemetry specification and user feedback.

Index

• type Meter
• type MeterConfig
  • func NewMeterConfig(opts ...MeterOption) MeterConfig
  • func (cfg MeterConfig) InstrumentationVersion() string
  • func (cfg MeterConfig) SchemaURL() string
• type MeterOption
  • func WithInstrumentationVersion(version string) MeterOption
  • func WithSchemaURL(schemaURL string) MeterOption
• type MeterProvider

Examples

• Meter (Asynchronous_multiple)
• Meter (Asynchronous_single)
• Meter (Synchronous)

Types

type Meter

type Meter interface {
	// AsyncInt64 is the namespace for the Asynchronous Integer instruments.
	//
	// To Observe data with instruments it must be registered in a callback.
	AsyncInt64() asyncint64.InstrumentProvider

	// AsyncFloat64 is the namespace for the Asynchronous Float instruments
	//
	// To Observe data with instruments it must be registered in a callback.
	AsyncFloat64() asyncfloat64.InstrumentProvider

	// RegisterCallback captures the function that will be called during Collect.
	//
	// It is only valid to call Observe within the scope of the passed function,
	// and only on the instruments that were registered with this call.
	RegisterCallback(insts []instrument.Asynchronous, function func(context.Context)) error

	// SyncInt64 is the namespace for the Synchronous Integer instruments
	SyncInt64() syncint64.InstrumentProvider
	// SyncFloat64 is the namespace for the Synchronous Float instruments
	SyncFloat64() syncfloat64.InstrumentProvider
}

Meter provides access to instrument instances for recording metrics.

Example (Asynchronous_multiple)

package main

import (
	"context"
	"fmt"
	"runtime"

	"go.opentelemetry.io/otel/metric/instrument"
	"go.opentelemetry.io/otel/metric/instrument/syncfloat64"
	"go.opentelemetry.io/otel/metric/nonrecording"
)

func main() {
	meterProvider := nonrecording.NewNoopMeterProvider()
	meter := meterProvider.Meter("go.opentelemetry.io/otel/metric#MultiAsyncExample")

	// This is just a sample of memory stats to record from the Memstats
	heapAlloc, _ := meter.AsyncInt64().UpDownCounter("heapAllocs")
	gcCount, _ := meter.AsyncInt64().Counter("gcCount")
	gcPause, _ := meter.SyncFloat64().Histogram("gcPause")

	err := meter.RegisterCallback([]instrument.Asynchronous{
		heapAlloc,
		gcCount,
	},
		func(ctx context.Context) {
			memStats := &runtime.MemStats{}
			// This call does work
			runtime.ReadMemStats(memStats)

			heapAlloc.Observe(ctx, int64(memStats.HeapAlloc))
			gcCount.Observe(ctx, int64(memStats.NumGC))

			// This function synchronously records the pauses
			computeGCPauses(ctx, gcPause, memStats.PauseNs[:])
		},
	)

	if err != nil {
		fmt.Println("Failed to register callback")
		panic(err)
	}
}

// This is just an example, see the the contrib runtime instrumentation for real implementation.
func computeGCPauses(ctx context.Context, recorder syncfloat64.Histogram, pauseBuff []uint64) {

}

Example (Asynchronous_single)

package main

import (
	"context"
	"fmt"

	"go.opentelemetry.io/otel/metric/instrument"
	"go.opentelemetry.io/otel/metric/nonrecording"
	"go.opentelemetry.io/otel/metric/unit"
)

func main() {
	// In a library or program this would be provided by otel.GetMeterProvider().
	meterProvider := nonrecording.NewNoopMeterProvider()
	meter := meterProvider.Meter("go.opentelemetry.io/otel/metric#AsyncExample")

	memoryUsage, err := meter.AsyncInt64().Gauge(
		"MemoryUsage",
		instrument.WithUnit(unit.Bytes),
	)
	if err != nil {
		fmt.Println("Failed to register instrument")
		panic(err)
	}

	err = meter.RegisterCallback([]instrument.Asynchronous{memoryUsage},
		func(ctx context.Context) {
			// instrument.WithCallbackFunc(func(ctx context.Context) {
			//Do Work to get the real memoryUsage
			// mem := GatherMemory(ctx)
			mem := 75000

			memoryUsage.Observe(ctx, int64(mem))
		})
	if err != nil {
		fmt.Println("Failed to register callback")
		panic(err)
	}
}

Example (Synchronous)

package main

import (
	"context"
	"fmt"
	"time"

	"go.opentelemetry.io/otel/metric/instrument"
	"go.opentelemetry.io/otel/metric/nonrecording"
	"go.opentelemetry.io/otel/metric/unit"
)

func main() {
	// In a library or program this would be provided by otel.GetMeterProvider().
	meterProvider := nonrecording.NewNoopMeterProvider()

	workDuration, err := meterProvider.Meter("go.opentelemetry.io/otel/metric#SyncExample").SyncInt64().Histogram(
		"workDuration",
		instrument.WithUnit(unit.Milliseconds))
	if err != nil {
		fmt.Println("Failed to register instrument")
		panic(err)
	}

	startTime := time.Now()
	ctx := context.Background()
	// Do work
	// ...
	workDuration.Record(ctx, time.Since(startTime).Milliseconds())

}

type MeterConfig

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

MeterConfig contains options for Meters.

func NewMeterConfig

func NewMeterConfig(opts ...MeterOption) MeterConfig

NewMeterConfig creates a new MeterConfig and applies all the given options.

func (MeterConfig) InstrumentationVersion

func (cfg MeterConfig) InstrumentationVersion() string

InstrumentationVersion is the version of the library providing instrumentation.

func (MeterConfig) SchemaURL

func (cfg MeterConfig) SchemaURL() string

SchemaURL is the schema_url of the library providing instrumentation.

type MeterOption

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

MeterOption is an interface for applying Meter options.

func WithInstrumentationVersion

func WithInstrumentationVersion(version string) MeterOption

WithInstrumentationVersion sets the instrumentation version.

func WithSchemaURL

func WithSchemaURL(schemaURL string) MeterOption

WithSchemaURL sets the schema URL.

type MeterProvider

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
}

MeterProvider provides access to named Meter instances, for instrumenting an application or library.