Semantic Conventions for Go Runtime Metrics

Status: Experimental

This document describes semantic conventions for Go runtime metrics in OpenTelemetry. These metrics are obtained from Go’s runtime/metrics package.

Go Memory

Description: Go runtime metrics captured under the namespace go.memory.*

Metric: go.memory.used

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
go.memory.used	UpDownCounter	By	Memory used by the Go runtime. [1]

[1]: Computed from (/memory/classes/total:bytes - /memory/classes/heap/released:bytes).

Attribute	Type	Description	Examples	Requirement Level	Stability
go.memory.type	string	The type of memory.	other; stack	Recommended

go.memory.type has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.

Value	Description	Stability
other	Memory used by the Go runtime, excluding other categories of memory usage described in this enumeration.
stack	Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use. [1]

[1]: Computed from /memory/classes/heap/stacks:bytes.

Metric: go.memory.limit

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
go.memory.limit	UpDownCounter	By	Go runtime memory limit configured by the user, if a limit exists. [1]

[1]: Computed from /gc/gomemlimit:bytes. This metric is excluded if the limit obtained from the Go runtime is math.MaxInt64.

Metric: go.memory.allocated

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
go.memory.allocated	Counter	By	Memory allocated to the heap by the application. [1]

[1]: Computed from /gc/heap/allocs:bytes.

Metric: go.memory.allocations

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
go.memory.allocations	Counter	{allocation}	Count of allocations to the heap by the application. [1]

[1]: Computed from /gc/heap/allocs:objects.

Go Garbage Collection

Description: Go metrics captured under the namespace go.memory.gc.*

Metric: go.memory.gc.goal

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
go.memory.gc.goal	UpDownCounter	By	Heap size target for the end of the GC cycle. [1]

[1]: Computed from /gc/heap/goal:bytes.

Go Goroutines

Description: Go metrics captured under the namespace go.goroutine.*

Metric: go.goroutine.count

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
go.goroutine.count	UpDownCounter	{goroutine}	Count of live goroutines. [1]

[1]: Computed from /sched/goroutines:goroutines.

Go Processor

Description: Go metrics captured under the namespace go.processor.*

Metric: go.processor.limit

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
go.processor.limit	UpDownCounter	{thread}	The number of OS threads that can execute user-level Go code simultaneously. [1]

[1]: Computed from /sched/gomaxprocs:threads.

Go Scheduler

Description: Go metrics captured under the namespace go.schedule.*

Metric: go.schedule.duration

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
go.schedule.duration	Histogram	s	The time goroutines have spent in the scheduler in a runnable state before actually running. [1]

[1]: Computed from /sched/latencies:seconds. Bucket boundaries are provided by the runtime, and are subject to change.

Go Runtime Configuration

Description: Go metrics captured under the namespace go.config.*

Metric: go.config.gogc

This metric is recommended.

Name	Instrument Type	Unit (UCUM)	Description	Stability
go.config.gogc	UpDownCounter	%	Heap size target percentage configured by the user, otherwise 100. [1]

[1]: The value range is [0.0,100.0]. Computed from /gc/gogc:percent.