> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/runtime/go-metrics/


# Goランタイムメトリクスに関するセマンティック規約

**ステータス**: [Development][DocumentStatus]

この文書では、OpenTelemetryにおけるGoランタイムメトリクスに関するセマンティック規約を定義します。
これらのメトリクスは、Goの[`runtime/metrics`][RuntimeMetrics]パッケージから取得されます。

## Goのメモリ

**Description:** 名前空間`go.memory.*`の下で取得されるGoランタイムメトリクス。

### メトリクス: `go.memory.used`

このメトリクスは[推奨][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` | Goランタイムが使用しているメモリ。[1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** `(/memory/classes/total:bytes - /memory/classes/heap/released:bytes)`から計算されます。

**Attributes:**

| Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values |
| --- | --- | --- | --- | --- | --- |
| [`go.memory.type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/go/) | ![Development](https://img.shields.io/badge/-development-blue) | `Recommended` | string | メモリの種別。 | `other`; `stack` |
| [`go.memory.detailed_type`](https://opentelemetry.io/docs/specs/semconv/registry/attributes/go/) | ![Development](https://img.shields.io/badge/-development-blue) | `Opt-In` | string | メモリの詳細な種別。[1] | `heap/objects`; `heap/free` |

**[1] `go.memory.detailed_type`:** 値は、`/memory/classes/...`の下でGoランタイムが報告する具体的なメモリクラスと一致すべきです（SHOULD）。取り得る値の一覧は、使用するGoのバージョンによって変わる場合があります。

---

`go.memory.type`には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `other` | この列挙で説明されている他のメモリ使用のカテゴリーを除いた、Goランタイムが使用するメモリ。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `stack` | ヒープから割り当てられ、現在使用中かどうかにかかわらずスタック空間として予約されているメモリ。[2] | ![Development](https://img.shields.io/badge/-development-blue) |

**[2]:** `/memory/classes/heap/stacks:bytes`から計算されます。

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

Go 1.26時点で、`go.memory.detailed_type`属性は`go.memory.type`属性に対して次の関係を持ちます。`go.memory.detailed_type`の値は、使用するGoのバージョンによって変わる場合があります。

| `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` |

### メトリクス: `go.memory.limit`

このメトリクスは[推奨][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ランタイムのメモリ上限（存在する場合）。[1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** `/gc/gomemlimit:bytes`から計算されます。Goランタイムから取得した上限が`math.MaxInt64`の場合、このメトリクスは対象から除外されます。

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

### メトリクス: `go.memory.allocated`

このメトリクスは[推奨][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` | アプリケーションによってヒープに割り当てられたメモリ。[1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** `/gc/heap/allocs:bytes`から計算されます。

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

### メトリクス: `go.memory.allocations`

このメトリクスは[推奨][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}` | アプリケーションによるヒープへの割り当ての回数。[1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** `/gc/heap/allocs:objects`から計算されます。

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

## Goのガーベジコレクション

**Description:** 名前空間`go.memory.gc.*`の下で取得されるGoメトリクス。

### メトリクス: `go.memory.gc.goal`

このメトリクスは[推奨][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` | GCサイクル終了時点のヒープサイズの目標値。[1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** `/gc/heap/goal:bytes`から計算されます。

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

### メトリクス: `go.memory.gc.cycles`

このメトリクスは[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}` | 完了したGCサイクルの数。[1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** `/gc/cycles/total:gc-cycles`から計算されます。

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

### メトリクス: `go.memory.gc.pause.duration`

このメトリクスは[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` | GCに関連する個々のstop-the-world一時停止のレイテンシーの分布。world停止を決定した時点からworldが再開されるまでの時間です。[1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** `/sched/pauses/total/gc:seconds`から計算されます。バケット境界はランタイムによって提供され、変更される場合があります。

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

## GoのCPU

**Description:** 名前空間`go.cpu.*`の下で取得されるGoランタイムメトリクス。

### メトリクス: `go.cpu.time`

このメトリクスは[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` | Goランタイムによって消費された推定CPU時間。[1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** `/cpu/classes/...`メトリクスから計算されます。このメトリクスは過大に見積もられており、システムのCPU時間の測定値と直接比較することはできません。他の`go.cpu.time`メトリクスとのみ比較してください。

**Attributes:**

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

**[1] `go.cpu.detailed_state`:** 値は、`/cpu/classes/...`の下でGoランタイムが報告する具体的なCPUクラスと一致すべきです（SHOULD）。取り得る値の一覧は、使用するGoのバージョンによって変わる場合があります。

---

`go.cpu.state`には、次のよく知られた値の一覧があります。いずれかが該当する場合はその値を使用しなければならず（MUST）、それ以外の場合は独自の値を使ってもかまいません（MAY）。

| Value | Description | Stability |
| --- | --- | --- |
| `gc` | ガーベジコレクションのタスクを実行するために消費されたCPU時間。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `idle` | GoまたはGoランタイムのコードを実行していない、利用可能なCPU時間。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `scavenge` | 未使用のメモリを基盤となるプラットフォームに返すために消費されたCPU時間。 | ![Development](https://img.shields.io/badge/-development-blue) |
| `user` | ユーザーのGoコードの実行に消費されたCPU時間。 | ![Development](https://img.shields.io/badge/-development-blue) |

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

Go 1.26時点で、`go.cpu.detailed_state`属性は`go.cpu.state`属性に対して次の関係を持ちます。`go.cpu.detailed_state`の値は、使用するGoのバージョンによって変わる場合があります。

| `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のgoroutine

**Description:** 名前空間`go.goroutine.*`の下で取得されるGoメトリクス。

### メトリクス: `go.goroutine.count`

このメトリクスは[推奨][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}` | 生存しているgoroutineの数。[1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** `/sched/goroutines:goroutines`から計算されます。

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

## Goのプロセッサー

**Description:** 名前空間`go.processor.*`の下で取得されるGoメトリクス。

### メトリクス: `go.processor.limit`

このメトリクスは[推奨][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}` | ユーザーレベルのGoコードを同時に実行できるOSスレッドの数。[1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** `/sched/gomaxprocs:threads`から計算されます。

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

## Goのスケジューラー

**Description:** 名前空間`go.schedule.*`の下で取得されるGoメトリクス。

### メトリクス: `go.schedule.duration`

このメトリクスは[推奨][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` | goroutineが実際に実行される前に、実行可能な状態でスケジューラーに滞在した時間。[1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** `/sched/latencies:seconds`から計算されます。バケット境界はランタイムによって提供され、変更される場合があります。

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

## Goランタイムの設定

**Description:** 名前空間`go.config.*`の下で取得されるGoメトリクス。

### メトリクス: `go.config.gogc`

このメトリクスは[推奨][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 | `%` | ユーザーが設定したヒープサイズ目標のパーセンテージ。未設定の場合は100。[1] | ![Development](https://img.shields.io/badge/-development-blue) | |

**[1]:** 値の範囲は[0.0,100.0]です。`/gc/gogc:percent`から計算されます。

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

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