OpenTelemetry Metrics API for Go

Introduction

This document teaches how to use OpenTelemetry Metrics Go API. To learn how to install and configure OpenTelemetry Go SDK, see Getting started with OpenTelemetry Goopen in new window.

If you are not familiar with metrics terminology like timeseries or additive/synchronous/asynchronous instruments, read the introduction to OpenTelemetry Metrics first.

Getting started

To get started with metrics, you need a MeterProvider which you can use to create meters:

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

// Meter can be a global/package variable.
var Meter = global.MeterProvider().Meter("app_or_package_name")

Using the meter, you can create instruments to measure performance. The simplest Counter instrument looks like this:

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

counter := Meter.SyncInt64().Counter(
	"test.my_counter",
    instrument.WithUnit("1"),
	instrument.WithDescription("Just a test counter"),
)

// Increment the counter.
counter.Add(ctx, 1, attribute.String("foo", "bar"))
counter.Add(ctx, 10, attribute.String("hello", "world"))

You can find more examplesopen in new window at GitHub.

Counter

Counter is a synchronous instrument that measures additive non-decreasing values.

// counter demonstrates how to measure non-decreasing numbers, for example,
// number of requests or connections.
func counter(ctx context.Context) {
	counter, _ := meter.SyncInt64().Counter(
		"some.prefix.counter",
		instrument.WithUnit("1"),
		instrument.WithDescription("TODO"),
	)

	for {
		counter.Add(ctx, 1)
		time.Sleep(time.Millisecond)
	}
}

You can get more interesting results by adding attributes to your measurements:

// counterWithLabels demonstrates how to add different labels ("hits" and "misses")
// to measurements. Using this simple trick, you can get number of hits, misses,
// sum = hits + misses, and hit_rate = hits / (hits + misses).
func counterWithLabels(ctx context.Context) {
	counter, _ := meter.SyncInt64().Counter(
		"some.prefix.cache",
		instrument.WithDescription("Cache hits and misses"),
	)
	for {
		if rand.Float64() < 0.3 {
			// increment hits
			counter.Add(ctx, 1, attribute.String("type", "hits"))
		} else {
			// increments misses
			counter.Add(ctx, 1, attribute.String("type", "misses"))
		}

		time.Sleep(time.Millisecond)
	}
}

UpDownCounter

UpDownCounter is a synchronous instrument which measures additive values that increase or decrease with time.

// upDownCounter demonstrates how to measure numbers that can go up and down, for example,
// number of goroutines or customers.
func upDownCounter(ctx context.Context) {
	counter, _ := meter.SyncInt64().UpDownCounter(
		"some.prefix.up_down_counter",
		instrument.WithUnit("1"),
		instrument.WithDescription("TODO"),
	)

	for {
		if rand.Float64() >= 0.5 {
			counter.Add(ctx, +1)
		} else {
			counter.Add(ctx, -1)
		}

		time.Sleep(time.Second)
	}
}

Histogram

Histogram is a synchronous instrument that produces a histogram from recorded values.

// histogram demonstrates how to record a distribution of individual values, for example,
// request or query timings. With this instrument you get total number of records,
// avg/min/max values, and heatmaps/percentiles.
func histogram(ctx context.Context) {
	durRecorder, _ := meter.SyncInt64().Histogram(
		"some.prefix.histogram",
		instrument.WithUnit("microseconds"),
		instrument.WithDescription("TODO"),
	)

	for {
		dur := time.Duration(rand.NormFloat64()*5000000) * time.Microsecond
		durRecorder.Record(ctx, dur.Microseconds())

		time.Sleep(time.Millisecond)
	}
}

CounterObserver

CounterObserver is an asynchronous instrument that measures additive non-decreasing values.

// counterObserver demonstrates how to measure monotonic (non-decreasing) numbers,
// for example, number of requests or connections.
func counterObserver(ctx context.Context) {
	counter, _ := meter.AsyncInt64().Counter(
		"some.prefix.counter_observer",
		instrument.WithUnit("1"),
		instrument.WithDescription("TODO"),
	)

	var number int64
	if err := meter.RegisterCallback(
		[]instrument.Asynchronous{
			counter,
		},
		// SDK periodically calls this function to collect data.
		func(ctx context.Context) {
			number++
			counter.Observe(ctx, number)
		},
	); err != nil {
		panic(err)
	}
}

UpDownCounterOserver

UpDownCounterOserver is an asynchronous instrument that measures additive values that can increase or decrease with time.

// upDownCounterObserver demonstrates how to measure numbers that can go up and down,
// for example, number of goroutines or customers.
func upDownCounterObserver(ctx context.Context) {
	counter, err := meter.AsyncInt64().UpDownCounter(
		"some.prefix.up_down_counter",
		instrument.WithUnit("1"),
		instrument.WithDescription("TODO"),
	)
	if err != nil {
		panic(err)
	}

	if err := meter.RegisterCallback(
		[]instrument.Asynchronous{
			counter,
		},
		func(ctx context.Context) {
			num := runtime.NumGoroutine()
			counter.Observe(ctx, int64(num))
		},
	); err != nil {
		panic(err)
	}
}

GaugeObserver

GaugeObserver is an asynchronous instrument that measures non-additive values for which sum does not produce a meaningful correct result.

// gaugeObserver demonstrates how to measure non-additive numbers that can go up and down,
// for example, cache hit rate or memory utilization.
func gaugeObserver(ctx context.Context) {
	gauge, _ := meter.AsyncFloat64().Gauge(
		"some.prefix.gauge_observer",
		instrument.WithUnit("1"),
		instrument.WithDescription("TODO"),
	)

	if err := meter.RegisterCallback(
		[]instrument.Asynchronous{
			gauge,
		},
		func(ctx context.Context) {
			gauge.Observe(ctx, rand.Float64())
		},
	); err != nil {
		panic(err)
	}
}

Metrics storage

Uptrace is an open source DataDog competitoropen in new window with an intuitive query builder, rich dashboards, alerting rules, and integrations for most languages and frameworks. It can process billions of spans and metrics on a single server and allows to monitor your applications at 10x lower cost.

Uptrace uses ClickHouse database to store traces, metrics, and logs. You can use it to monitor applications and set up automatic alerts to receive notifications via email, Slack, Telegram, and more.

You can get startedopen in new window with Uptrace by downloading a DEB/RPM package or a pre-compiled Go binary.

What's next?

Next, you can installopen in new window OpenTelemetry Collector to monitor infrastructure metrics, for example, PostgreSQLopen in new window, MySQLopen in new window, Kafkaopen in new window, and more.

Popular instrumentations:

Last Updated: