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 Go.
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 examples 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 competitor 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 started with Uptrace by downloading a DEB/RPM package or a pre-compiled Go binary.
What's next?
Next, you can install OpenTelemetry Collector to monitor infrastructure metrics, for example, PostgreSQL, MySQL, Kafka, and more.
Popular instrumentations:
