この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/runtime/go-metrics/

翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）

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

ステータス: Development

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

Goのメモリ

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

メトリクス: go.memory.used

このメトリクスは推奨です。

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.used	UpDownCounter	By	Goランタイムが使用しているメモリ。[1]

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

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
go.memory.type		Recommended	string	メモリの種別。	other; stack
go.memory.detailed_type		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ランタイムが使用するメモリ。
stack	ヒープから割り当てられ、現在使用中かどうかにかかわらずスタック空間として予約されているメモリ。[2]

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

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

メトリクス: go.memory.limit

このメトリクスは推奨です。

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.limit	UpDownCounter	By	ユーザーが設定したGoランタイムのメモリ上限（存在する場合）。[1]

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

メトリクス: go.memory.allocated

このメトリクスは推奨です。

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.allocated	Counter	By	アプリケーションによってヒープに割り当てられたメモリ。[1]

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

メトリクス: go.memory.allocations

このメトリクスは推奨です。

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.allocations	Counter	{allocation}	アプリケーションによるヒープへの割り当ての回数。[1]

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

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

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

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

このメトリクスは推奨です。

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.gc.goal	UpDownCounter	By	GCサイクル終了時点のヒープサイズの目標値。[1]

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

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

このメトリクスはopt-inです。

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.gc.cycles	Counter	{gc_cycle}	完了したGCサイクルの数。[1]

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

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

このメトリクスはopt-inです。

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.memory.gc.pause.duration	Histogram	s	GCに関連する個々のstop-the-world一時停止のレイテンシーの分布。world停止を決定した時点からworldが再開されるまでの時間です。[1]

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

GoのCPU

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

メトリクス: go.cpu.time

このメトリクスはopt-inです。

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.cpu.time	Counter	s	Goランタイムによって消費された推定CPU時間。[1]

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

Attributes:

Key	Stability	Requirement Level	Value Type	Description	Example Values
go.cpu.state		Required	string	CPUの状態。	user; gc
go.cpu.detailed_state		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時間。
idle	GoまたはGoランタイムのコードを実行していない、利用可能なCPU時間。
scavenge	未使用のメモリを基盤となるプラットフォームに返すために消費されたCPU時間。
user	ユーザーのGoコードの実行に消費されたCPU時間。

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

Goのgoroutine

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

メトリクス: go.goroutine.count

このメトリクスは推奨です。

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.goroutine.count	UpDownCounter	{goroutine}	生存しているgoroutineの数。[1]

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

Goのプロセッサー

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

メトリクス: go.processor.limit

このメトリクスは推奨です。

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.processor.limit	UpDownCounter	{thread}	ユーザーレベルのGoコードを同時に実行できるOSスレッドの数。[1]

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

Goのスケジューラー

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

メトリクス: go.schedule.duration

このメトリクスは推奨です。

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.schedule.duration	Histogram	s	goroutineが実際に実行される前に、実行可能な状態でスケジューラーに滞在した時間。[1]

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

Goランタイムの設定

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

メトリクス: go.config.gogc

このメトリクスは推奨です。

Name	Instrument Type	Unit (UCUM)	Description	Stability	Entity Associations
go.config.gogc	UpDownCounter	%	ユーザーが設定したヒープサイズ目標のパーセンテージ。未設定の場合は100。[1]

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