# Semantic conventions for Go runtime metrics

LLMS index: [llms.txt](/llms.txt)

---

**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.

<!-- START doctoc -->

- [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)
  - [Metric: `go.memory.gc.cycles`](#metric-gomemorygccycles)
  - [Metric: `go.memory.gc.pause.duration`](#metric-gomemorygcpauseduration)
- [Go CPU](#go-cpu)
  - [Metric: `go.cpu.time`](#metric-gocputime)
- [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)

<!-- END doctoc -->

## Go memory

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

### Metric: `go.memory.used`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.go.memory.used -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `go.memory.used` | UpDownCounter | `By` | Memory used by the Go runtime. [1] | ![Development](https://img.shields.io/badge/-development-blue) | |

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

**Attributes:**

| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`go.memory.type`](/docs/specs/semconv/registry/attributes/go.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | The type of memory. | `other`; `stack` |
| [`go.memory.detailed_type`](/docs/specs/semconv/registry/attributes/go.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | The detailed type of memory. [1] | `heap/objects`; `heap/free` |

**[1] `go.memory.detailed_type`:** Value SHOULD match the specific memory class reported by the Go runtime under `/memory/classes/...`. The list of possible values is subject to change with the Go version used.

---

`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. | ![Development](https://img.shields.io/badge/-development-blue) |
| `stack` | Memory allocated from the heap that is reserved for stack space, whether or not it is currently in-use. [2] | ![Development](https://img.shields.io/badge/-development-blue) |

**[2]:** Computed from `/memory/classes/heap/stacks:bytes`.

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

As of Go 1.26, the `go.memory.detailed_type` attribute has the following relationship to the `go.memory.type` attribute. Values for `go.memory.detailed_type` are subject to change with the Go version used:

| `go.memory.type` | `go.memory.detailed_type` |
| --- | --- |
| `other` | `heap/free` |
| `other` | `heap/objects` |
| `other` | `heap/unused` |
| `other` | `metadata/mcache/free` |
| `other` | `metadata/mcache/inuse` |
| `other` | `metadata/mspan/free` |
| `other` | `metadata/mspan/inuse` |
| `other` | `metadata/other` |
| `other` | `os-stacks` |
| `other` | `other` |
| `other` | `profiling/buckets` |
| `stack` | `heap/stacks` |

### Metric: `go.memory.limit`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.go.memory.limit -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| 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] | ![Development](https://img.shields.io/badge/-development-blue) | |

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

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

### Metric: `go.memory.allocated`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.go.memory.allocated -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `go.memory.allocated` | Counter | `By` | Memory allocated to the heap by the application. [1] | ![Development](https://img.shields.io/badge/-development-blue) | |

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

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

### Metric: `go.memory.allocations`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.go.memory.allocations -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `go.memory.allocations` | Counter | `{allocation}` | Count of allocations to the heap by the application. [1] | ![Development](https://img.shields.io/badge/-development-blue) | |

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

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

## Go garbage collection

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

### Metric: `go.memory.gc.goal`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.go.memory.gc.goal -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| 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] | ![Development](https://img.shields.io/badge/-development-blue) | |

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

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

### Metric: `go.memory.gc.cycles`

This metric is [opt-in][MetricOptIn].

<!-- semconv metric.go.memory.gc.cycles -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `go.memory.gc.cycles` | Counter | `{gc_cycle}` | Number of completed GC cycles. [1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** Computed from `/gc/cycles/total:gc-cycles`.

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

### Metric: `go.memory.gc.pause.duration`

This metric is [opt-in][MetricOptIn].

<!-- semconv metric.go.memory.gc.pause.duration -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `go.memory.gc.pause.duration` | Histogram | `s` | Distribution of individual GC-related stop-the-world pause latencies. This is the time from deciding to stop the world until the world is started again. [1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** Computed from `/sched/pauses/total/gc:seconds`. Bucket boundaries are provided by the runtime, and are subject to change.

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

## Go CPU

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

### Metric: `go.cpu.time`

This metric is [opt-in][MetricOptIn].

<!-- semconv metric.go.cpu.time -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `go.cpu.time` | Counter | `s` | Estimated CPU time spent by the Go runtime. [1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** Computed from `/cpu/classes/...` metrics. This metric is an overestimate, and not directly comparable to system CPU time measurements. Compare only with other `go.cpu.time` metrics.

**Attributes:**

| Key | Stability | [Requirement Level](/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`go.cpu.state`](/docs/specs/semconv/registry/attributes/go.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Required` | string | The state of the CPU. | `user`; `gc` |
| [`go.cpu.detailed_state`](/docs/specs/semconv/registry/attributes/go.md) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | The detailed state of the CPU. [1] | `gc/pause`; `gc/mark/assist` |

**[1] `go.cpu.detailed_state`:** Value SHOULD match the specific CPU class reported by the Go runtime under `/cpu/classes/...`. The list of possible values is subject to change with the Go version used.

---

`go.cpu.state` 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 |
| --- | --- | --- |
| `gc` | CPU time spent performing garbage collection tasks. | ![Development](https://img.shields.io/badge/-development-blue) |
| `idle` | Available CPU time not spent executing any Go or Go runtime code. | ![Development](https://img.shields.io/badge/-development-blue) |
| `scavenge` | CPU time spent returning unused memory to the underlying platform. | ![Development](https://img.shields.io/badge/-development-blue) |
| `user` | CPU time spent running user Go code. | ![Development](https://img.shields.io/badge/-development-blue) |

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

As of Go 1.26, the `go.cpu.detailed_state` attribute has the following relationship to the `go.cpu.state` attribute. Values for `go.cpu.detailed_state` are subject to change with the Go version used:

| `go.cpu.state` | `go.cpu.detailed_state` |
| --- | --- |
| `user` | `user` |
| `gc` | `gc/mark/assist` |
| `gc` | `gc/mark/dedicated` |
| `gc` | `gc/mark/idle` |
| `gc` | `gc/pause` |
| `scavenge` | `scavenge/assist` |
| `scavenge` | `scavenge/background` |
| `idle` | `idle` |

## Go goroutines

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

### Metric: `go.goroutine.count`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.go.goroutine.count -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `go.goroutine.count` | UpDownCounter | `{goroutine}` | Count of live goroutines. [1] | ![Development](https://img.shields.io/badge/-development-blue) | |

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

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

## Go processor

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

### Metric: `go.processor.limit`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.go.processor.limit -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| 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] | ![Development](https://img.shields.io/badge/-development-blue) | |

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

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

## Go scheduler

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

### Metric: `go.schedule.duration`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.go.schedule.duration -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| 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] | ![Development](https://img.shields.io/badge/-development-blue) | |

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

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

## Go runtime configuration

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

### Metric: `go.config.gogc`

This metric is [recommended][MetricRecommended].

<!-- semconv metric.go.config.gogc -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->

| Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations |
| -------- | --------------- | ----------- | -------------- | --------- | ------ |
| `go.config.gogc` | UpDownCounter | `%` | Heap size target percentage configured by the user, otherwise 100. [1] | ![Development](https://img.shields.io/badge/-development-blue) | |

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

<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->

[DocumentStatus]: /docs/specs/otel/document-status
[MetricRecommended]: /docs/specs/semconv/general/metric-requirement-level.md#recommended
[RuntimeMetrics]: https://pkg.go.dev/runtime/metrics
[MetricOptIn]: /docs/specs/semconv/general/metric-requirement-level.md#opt-in