runtime

Documentation

Overview

Package runtime implements the conventional runtime metrics specified by OpenTelemetry.

The metric events produced are:

runtime.go.cgo.calls         -          Number of cgo calls made by the current process
runtime.go.gc.count          -          Number of completed garbage collection cycles
runtime.go.gc.pause_ns       (ns)       Amount of nanoseconds in GC stop-the-world pauses
runtime.go.gc.pause_total_ns (ns)       Cumulative nanoseconds in GC stop-the-world pauses since the program started
runtime.go.goroutines        -          Number of goroutines that currently exist
runtime.go.lookups           -          Number of pointer lookups performed by the runtime
runtime.go.mem.heap_alloc    (bytes)    Bytes of allocated heap objects
runtime.go.mem.heap_idle     (bytes)    Bytes in idle (unused) spans
runtime.go.mem.heap_inuse    (bytes)    Bytes in in-use spans
runtime.go.mem.heap_objects  -          Number of allocated heap objects
runtime.go.mem.heap_released (bytes)    Bytes of idle spans whose physical memory has been returned to the OS
runtime.go.mem.heap_sys      (bytes)    Bytes of heap memory obtained from the OS
runtime.go.mem.live_objects  -          Number of live objects is the number of cumulative Mallocs - Frees
runtime.uptime               (ms)       Milliseconds since application was initialized

When the OTEL_GO_X_DEPRECATED_RUNTIME_METRICS environment variable is set to false, the metrics produced are:

go.memory.used          By            Memory used by the Go runtime.
go.memory.limit         By            Go runtime memory limit configured by the user, if a limit exists.
go.memory.allocated     By            Memory allocated to the heap by the application.
go.memory.allocations   {allocation}  Count of allocations to the heap by the application.
go.memory.gc.goal       By            Heap size target for the end of the GC cycle.
go.goroutine.count      {goroutine}   Count of live goroutines.
go.processor.limit      {thread}      The number of OS threads that can execute user-level Go code simultaneously.
go.config.gogc          %             Heap size target percentage configured by the user, otherwise 100.

Example

package main

import (
	"context"
	"log"
	"time"

	"go.opentelemetry.io/contrib/instrumentation/runtime"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/sdk/metric"
)

func main() {
	// This reader is used as a stand-in for a reader that will actually export
	// data. See https://pkg.go.dev/go.opentelemetry.io/otel/exporters for
	// exporters that can be used as or with readers.
	reader := metric.NewManualReader(
		// Add the runtime producer to get histograms from the Go runtime.
		metric.WithProducer(runtime.NewProducer()),
	)
	provider := metric.NewMeterProvider(metric.WithReader(reader))
	defer func() {
		err := provider.Shutdown(context.Background())
		if err != nil {
			log.Fatal(err)
		}
	}()
	otel.SetMeterProvider(provider)

	// Start go runtime metric collection.
	err := runtime.Start(runtime.WithMinimumReadMemStatsInterval(time.Second))
	if err != nil {
		log.Fatal(err)
	}
}

Index

• Constants
• func SemVersion() string
• func Start(opts ...Option) error
• func Version() string
• type Option
  • func WithMeterProvider(provider metric.MeterProvider) Option
  • func WithMinimumReadMemStatsInterval(d time.Duration) Option
• type Producer
  • func NewProducer(opts ...ProducerOption) *Producer
  • func (p *Producer) Produce(context.Context) ([]metricdata.ScopeMetrics, error)
• type ProducerOption

Examples

• Package

Constants

const DefaultMinimumReadMemStatsInterval time.Duration = 15 * time.Second

DefaultMinimumReadMemStatsInterval is the default minimum interval between calls to runtime.ReadMemStats(). Use the WithMinimumReadMemStatsInterval() option to modify this setting in Start().

const ScopeName = "go.opentelemetry.io/contrib/instrumentation/runtime"

ScopeName is the instrumentation scope name.

Functions

func SemVersion

func SemVersion() string

SemVersion is the semantic version to be supplied to tracer/meter creation.

Deprecated: Use Version instead.

func Start

func Start(opts ...Option) error

Start initializes reporting of runtime metrics using the supplied config. For goroutine scheduling metrics, additionally see NewProducer.

func Version

func Version() string

Version is the current release version of the runtime instrumentation.

Types

type Option

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

Option supports configuring optional settings for runtime metrics.

func WithMeterProvider

func WithMeterProvider(provider metric.MeterProvider) Option

WithMeterProvider sets the Metric implementation to use for reporting. If this option is not used, the global metric.MeterProvider will be used. `provider` must be non-nil.

func WithMinimumReadMemStatsInterval

func WithMinimumReadMemStatsInterval(d time.Duration) Option

WithMinimumReadMemStatsInterval sets a minimum interval between calls to runtime.ReadMemStats(), which is a relatively expensive call to make frequently. This setting is ignored when `d` is negative.

type Producer

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

Producer is a metric.Producer, which provides precomputed histogram metrics from the go runtime.

func NewProducer

func NewProducer(opts ...ProducerOption) *Producer

NewProducer creates a Producer which provides precomputed histogram metrics from the go runtime.

func (*Producer) Produce

func (p *Producer) Produce(context.Context) ([]metricdata.ScopeMetrics, error)

Produce returns precomputed histogram metrics from the go runtime, or an error if unsuccessful.

type ProducerOption

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

ProducerOption supports configuring optional settings for runtime metrics using a metric producer in addition to standard instrumentation.