debug

Documentation

Overview

debug パッケージには、プログラムが実行中に自己デバッグするための機能が含まれています。

Index

• func FreeOSMemory()
• func PrintStack()
• func ReadGCStats(stats *GCStats)
• func SetCrashOutput(f *os.File, opts CrashOptions) error
• func SetGCPercent(percent int) int
• func SetMaxStack(bytes int) int
• func SetMaxThreads(threads int) int
• func SetMemoryLimit(limit int64) int64
• func SetPanicOnFault(enabled bool) bool
• func SetTraceback(level string)
• func Stack() []byte
• func WriteHeapDump(fd uintptr)
• type BuildInfo
  • func ParseBuildInfo(data string) (bi *BuildInfo, err error)
  • func ReadBuildInfo() (info *BuildInfo, ok bool)
  • func (bi *BuildInfo) String() string
• type BuildSetting
• type CrashOptions
• type GCStats
• type Module

Examples

• SetCrashOutput (Monitor)

Functions

func FreeOSMemory

func FreeOSMemory()

FreeOSMemoryはガベージコレクションを強制的に行い、可能なだけ多くのメモリをオペレーティングシステムに返す試みをします。 (これが呼ばれなくても、ランタイムはバックグラウンドで徐々にメモリをオペレーティングシステムに返します。)

func PrintStack

func PrintStack()

PrintStackはruntime.Stackによって返されたスタックトレースを標準エラー出力に出力します。

func ReadGCStats

func ReadGCStats(stats *GCStats)

ReadGCStatsはゴミ収集に関する統計情報をstatsに読み込みます。 一時停止履歴のエントリ数はシステムに依存します。 stats.Pauseスライスは十分に大きければ再利用され、そうでなければ再割り当てされます。 ReadGCStatsはstats.Pauseスライスの容量をフルに使用する可能性があります。 もしstats.PauseQuantilesが空でない場合、ReadGCStatsは一時停止時間の分布を要約した 分位数をstats.PauseQuantilesに埋め込みます。 例えば、len(stats.PauseQuantiles)が5の場合、最小値、25%、50%、75%、最大値の一時停止時間が埋め込まれます。

func SetCrashOutput

func SetCrashOutput(f *os.File, opts CrashOptions) error

SetCrashOutput configures a single additional file where unhandled panics and other fatal errors are printed, in addition to standard error. There is only one additional file: calling SetCrashOutput again overrides any earlier call. SetCrashOutput duplicates f's file descriptor, so the caller may safely close f as soon as SetCrashOutput returns. To disable this additional crash output, call SetCrashOutput(nil). If called concurrently with a crash, some in-progress output may be written to the old file even after an overriding SetCrashOutput returns.

Example (Monitor)

ExampleSetCrashOutput_monitor shows an example of using debug.SetCrashOutput to direct crashes to a "monitor" process, for automated crash reporting. The monitor is the same executable, invoked in a special mode indicated by an environment variable.

appmain()

// This Example doesn't actually run as a test because its
// purpose is to crash, so it has no "Output:" comment
// within the function body.
//
// To observe the monitor in action, replace the entire text
// of this comment with "Output:" and run this command:
//
//    $ go test -run=ExampleSetCrashOutput_monitor runtime/debug
//    panic: oops
//    ...stack...
//    monitor: saved crash report at /tmp/10804884239807998216.crash

func SetGCPercent

func SetGCPercent(percent int) int

SetGCPercentはガベージコレクションの目標パーセンテージを設定します： 前回のコレクション後に残ったデータの生存データに対する最新割り当てデータの比率が このパーセンテージに達した時にコレクションがトリガーされます。 SetGCPercentは以前の設定を返します。 初期設定は起動時のGOGC環境変数の値、または変数が設定されていない場合は100です。 この設定はメモリ制限を維持するために効果的に減少させることができます。 マイナスのパーセンテージは、メモリ制限が達成されない限り、ガベージコレクションを 実質的に無効にします。 詳細については、SetMemoryLimitを参照してください。

func SetMaxStack

func SetMaxStack(bytes int) int

SetMaxStackは、個々のゴルーチンスタックが使用可能なメモリの最大量を設定します。 スタックを成長させながらこの制限を超える場合、プログラムはクラッシュします。 SetMaxStackは、前の設定を返します。 初期設定は、64ビットシステムでは1GB、32ビットシステムでは250MBです。 SetMaxStackに提供される値に関係なく、システムによって設定された最大スタック制限がある場合があります。

SetMaxStackは、無限再帰に入るゴルーチンによって引き起こされるダメージを制限するために主に役立ちます。 これは将来のスタックの成長のみを制限します。

func SetMaxThreads

func SetMaxThreads(threads int) int

SetMaxThreadsはGoプログラムが使用できるオペレーティングシステムの最大スレッド数を設定します。これ以上のスレッドを使用しようとすると、プログラムはクラッシュします。 SetMaxThreadsは前の設定を返します。 初期設定は10,000スレッドです。

制限はオペレーティングシステムのスレッド数を制御しますが、ゴルーチンの数を制御しません。Goプログラムは、既存のすべてのスレッドがシステムコール、CGOコールにブロックされているか、runtime.LockOSThreadの使用により他のゴルーチンにロックされている場合にのみ新しいスレッドを作成します。

SetMaxThreadsは、無制限の数のスレッドを作成するプログラムによる被害を制限するために主に役立ちます。アイデアは、プログラムがオペレーティングシステムをダウンさせる前にプログラム自体をダウンさせることです。

func SetMemoryLimit

func SetMemoryLimit(limit int64) int64

SetMemoryLimitはランタイムにソフトメモリ制限を提供します。

ランタイムは、ガベージコレクションの頻度の調整やメモリをより積極的に 下位システムに返却するなど、このメモリ制限を尊重するためにいくつかの プロセスを実行します。この制限は、GOGC=off (または、SetGCPercent(-1)が実行された場合も)であっても尊重されます。

入力制限はバイト単位で提供され、Goランタイムによってマップされた、管理された、リリースされていないすべてのメモリを含みます。特に、 Goバイナリによって使用されるスペースや、Go以外のメモリ(プロセスの 代わりに下位システムによって管理されるメモリや、同じプロセス内の 非Goコードによって管理されるメモリなど)は考慮されません。除外される メモリソースの例には、プロセスのために保持されたOSカーネルメモリ、 Cコードによって割り当てられたメモリ、syscall.Mmapによってマップされた メモリ(それはGoランタイムによって管理されていないため)が含まれます。

より具体的には、次の式が制限としてランタイムが維持しようとする値を 正確に反映しています：

runtime.MemStats.Sys - runtime.MemStats.HeapReleased

またはruntime/metricsパッケージを使用して：

/memory/classes/total:bytes - /memory/classes/heap/released:bytes

ゼロの制限やGoランタイムによって使用されるメモリ量よりも低い制限は、 ガベージコレクタがほぼ連続的に実行される原因となるかもしれません。 ただし、アプリケーションは引き続き進行する可能性があります。

メモリ制限は常にGoランタイムによって尊重されますので、 この挙動を効果的に無効にするには、制限を非常に高く設定します。 math.MaxInt64 は制限を無効にするための標準的な値ですが、 制限値が基礎となるシステムの利用可能なメモリよりもはるかに大きい場合でも、 同様に機能します。

詳細なガイドと共に、ソフトメモリ制限について詳しく説明したガイドおよび さまざまな一般的な使用例とシナリオについては、 https://go.dev/doc/gc-guideを参照してください。

初期設定はmath.MaxInt64ですが、GOMEMLIMIT環境変数が設定されている場合は、初期設定を提供します。GOMEMLIMITは、バイト単位の数値で、 オプションの単位接尾辞を持ちます。サポートされる接尾辞には、B、KiB、 MiB、GiB、TiBがあります。これらの接尾辞は、IEC 80000-13規格で定義されるバイトの数量を表します。つまり、KiBは2^10バイトを、 MiBは2^20バイトを意味し、それ以降も同様です。

SetMemoryLimitは以前に設定されたメモリ制限を返します。 負の入力は制限を調整せず、現在設定されたメモリ制限を取得することができます。

func SetPanicOnFault

func SetPanicOnFault(enabled bool) bool

SetPanicOnFaultは、プログラムが予期しない（非nil）アドレスでの障害が発生した場合、ランタイムの動作を制御します。 このような障害は通常、ランタイムのメモリ破損などのバグによって引き起こされるため、デフォルトの応答はプログラムをクラッシュさせることです。 メモリマップドファイルやメモリの安全でない操作を行うプログラムは、非nilアドレスでの障害を劇的な状況で引き起こすかもしれません。 SetPanicOnFaultは、そのようなプログラムがクラッシュではなくパニックのみを要求できるようにします。 ランタイムがパニックするときにランタイムがパニックするruntime.Errorには、追加のメソッドが存在する場合があります： Addr() uintptr もしAddrメソッドが存在する場合、それは障害を引き起こしたメモリアドレスを返します。 Addrの結果はベストエフォートであり、結果の信頼性はプラットフォームに依存する可能性があります。 SetPanicOnFaultは現在のゴルーチンにのみ適用されます。 それは前の設定を返します。

func SetTraceback

func SetTraceback(level string)

SetTracebackは、ランタイムがパニックや内部ランタイムエラーによる終了前に出力するトレースバックの詳細度を設定します。 level引数は、GOTRACEBACK環境変数と同じ値を受け取ります。例えば、SetTraceback("all")は、プログラムがクラッシュしたときにすべてのゴルーチンを出力することを保証します。 詳細については、パッケージランタイムのドキュメントを参照してください。 SetTracebackが環境変数よりも低いレベルで呼び出された場合、呼び出しは無視されます。

func Stack

func Stack() []byte

Stackはそれを呼び出すgoroutineのフォーマットされたスタックトレースを返します。 runtime.Stack を呼び出して、トレース全体をキャプチャする十分に大きなバッファを使用します。

func WriteHeapDump

func WriteHeapDump(fd uintptr)

WriteHeapDumpはヒープとその中のオブジェクトの説明を指定されたファイルディスクリプタに書き込みます。

WriteHeapDumpはヒープダンプが完全に書き込まれるまですべてのゴルーチンの実行を一時停止します。したがって、ファイルディスクリプタは、同じGoプロセスのもう一方のエンドがあるパイプやソケットに接続してはいけません。代わりに、一時ファイルまたはネットワークソケットを使用してください。

ヒープダンプの形式はhttps://golang.org/s/go15heapdumpで定義されています。

Types

type BuildInfo

type BuildInfo struct {
	// GoVersionはバイナリをビルドしたGoツールチェーンのバージョンです
	// （例: "go1.19.2"）。
	GoVersion string `json:",omitempty"`

	// Pathはバイナリのメインパッケージのパッケージパスです
	// （例: "golang.org/x/tools/cmd/stringer"）。
	Path string `json:",omitempty"`

	// Mainはバイナリのメインパッケージを含むモジュールを記述します。
	Main Module `json:""`

	// Depsは、このバイナリのビルドに寄与したすべての依存モジュール（直接・間接両方）を記述します。
	Deps []*Module `json:",omitempty"`

	// Settingsはバイナリのビルドに使用されたビルド設定を記述します。
	Settings []BuildSetting `json:",omitempty"`
}

BuildInfoはGoバイナリから読み取られるビルド情報を表します。

func ParseBuildInfo

func ParseBuildInfo(data string) (bi *BuildInfo, err error)

ParseBuildInfoは[*BuildInfo.String]が返す文字列を解析し、 元のBuildInfoを復元します。 ただしGoVersionフィールドは設定されません。 通常プログラムはこの関数を呼び出すべきではなく、 代わりに[ReadBuildInfo]、debug/buildinfo.ReadFile、 または debug/buildinfo.Read を呼び出してください。

func ReadBuildInfo

func ReadBuildInfo() (info *BuildInfo, ok bool)

ReadBuildInfoは実行中のバイナリに埋め込まれたビルド情報を返します。 この情報はモジュールサポートでビルドされたバイナリでのみ利用可能です。

func (*BuildInfo) String

func (bi *BuildInfo) String() string

Stringは[BuildInfo]の文字列表現を返します。

type BuildSetting

type BuildSetting struct {
	// KeyとValueはビルド設定を表します。
	// Keyには等号、スペース、タブ、改行を含めてはいけません。
	Key string `json:",omitempty"`
	// Valueには改行（'\n'）を含めてはいけません。
	Value string `json:",omitempty"`
}

BuildSettingはビルドに影響を与える1つの設定を表すキーと値のペアです。

定義されたキーには以下のものがあります:

• -buildmode: 使用されたbuildmodeフラグ（通常は "exe"）
• -compiler: 使用されたコンパイラツールチェーンフラグ（通常は "gc"）
• CGO_ENABLED: 有効なCGO_ENABLED環境変数
• CGO_CFLAGS: 有効なCGO_CFLAGS環境変数
• CGO_CPPFLAGS: 有効なCGO_CPPFLAGS環境変数
• CGO_CXXFLAGS: 有効なCGO_CXXFLAGS環境変数
• CGO_LDFLAGS: 有効なCGO_LDFLAGS環境変数
• DefaultGODEBUG: 有効なGODEBUG設定
• GOARCH: アーキテクチャターゲット
• GOAMD64/GOARM/GO386/etc: GOARCHのアーキテクチャ機能レベル
• GOOS: オペレーティングシステムターゲット
• GOFIPS140: 固定されたFIPS 140-3モジュールバージョン（存在する場合）
• vcs: ビルドが実行されたソースツリーのバージョン管理システム
• vcs.revision: 現在のコミットまたはチェックアウトのリビジョン識別子
• vcs.time: vcs.revisionに関連付けられた変更日時（RFC3339形式）
• vcs.modified: ソースツリーにローカル変更があったかどうか（trueまたはfalse）

type CrashOptions

type CrashOptions struct {
}

CrashOptions provides options that control the formatting of the fatal crash message.

type GCStats

type GCStats struct {
	LastGC         time.Time
	NumGC          int64
	PauseTotal     time.Duration
	Pause          []time.Duration
	PauseEnd       []time.Time
	PauseQuantiles []time.Duration
}

GCStatsは最近のガベージコレクションに関する情報を収集します。

type Module

type Module struct {
	Path    string  `json:",omitempty"`
	Version string  `json:",omitempty"`
	Sum     string  `json:",omitempty"`
	Replace *Module `json:",omitempty"`
}

Moduleはビルドに含まれる単一のモジュールを記述します。