# Semantic conventions for Go runtime metrics **Status**: [Development][DocumentStatus] This document describes semantic conventions for Go runtime metrics in OpenTelemetry. These metrics are obtained from Go's [`runtime/metrics`][RuntimeMetrics] package. - [Go memory](#go-memory) - [Metric: `go.memory.used`](#metric-gomemoryused) - [Metric: `go.memory.limit`](#metric-gomemorylimit) - [Metric: `go.memory.allocated`](#metric-gomemoryallocated) - [Metric: `go.memory.allocations`](#metric-gomemoryallocations) - [Go garbage collection](#go-garbage-collection) - [Metric: `go.memory.gc.goal`](#metric-gomemorygcgoal) - [Go goroutines](#go-goroutines) - [Metric: `go.goroutine.count`](#metric-gogoroutinecount) - [Go processor](#go-processor) - [Metric: `go.processor.limit`](#metric-goprocessorlimit) - [Go scheduler](#go-scheduler) - [Metric: `go.schedule.duration`](#metric-goscheduleduration) - [Go runtime configuration](#go-runtime-configuration) - [Metric: `go.config.gogc`](#metric-goconfiggogc) ## Go memory **Description:** Go runtime metrics captured under the namespace `go.memory.*` ### Metric: `go.memory.used` This metric is [recommended][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| | [`go.memory.type`](/docs/registry/attributes/go.md) | 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][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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][MetricRecommended]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `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`. [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [MetricRecommended]: /docs/general/metric-requirement-level.md#recommended [RuntimeMetrics]: https://pkg.go.dev/runtime/metrics