...

パッケージ pprof

import "runtime/pprof"
概要
目次
サブディレクトリ

概要 ▾

pprof パッケージは,pprof 視覚化ツールのフォーマットでランタイムプロファイルデータを出力します。

Go プログラムのプロファイリング

Go プログラムをプロファイリングするための最初のステップは,プロファイリングを有効にすることです。 標準テストパッケージで構築されたプロファイリングベンチマークのサポートは go test に組み込まれています。 たとえば,次のコマンドは現在のディレクトリでベンチマークを実行し, CPU とメモリのプロファイルを cpu.prof と mem.prof に書き込みます。

go test -cpuprofile cpu.prof -memprofile mem.prof -bench .

スタンドアロンプ​​ログラムに同等のプロファイリングサポートを追加するには,メイン関数に次のようなコードを追加します。

var cpuprofile = flag.String("cpuprofile", "", "write cpu profile to `file`")
var memprofile = flag.String("memprofile", "", "write memory profile to `file`")

func main() {
    flag.Parse()
    if *cpuprofile != "" {
        f, err := os.Create(*cpuprofile)
        if err != nil {
            log.Fatal("could not create CPU profile: ", err)
        }
        defer f.Close()
        if err := pprof.StartCPUProfile(f); err != nil {
            log.Fatal("could not start CPU profile: ", err)
        }
        defer pprof.StopCPUProfile()
    }

    // ... プログラムの残りの部分 ...

    if *memprofile != "" {
        f, err := os.Create(*memprofile)
        if err != nil {
            log.Fatal("could not create memory profile: ", err)
        }
        defer f.Close()
        runtime.GC() // 最新統計を取得する
        if err := pprof.WriteHeapProfile(f); err != nil {
            log.Fatal("could not write memory profile: ", err)
        }
    }
}

データをプロファイリングするための標準 HTTP インターフェースもあります。 次の行を追加すると,ライブプロファイルをダウンロードするために /debug/pprof/URL の下にハンドラがインストールされます。

import _ "net/http/pprof"

詳細は net/http/pprof パッケージを見てください。

プロファイルは pprof ツールで視覚化することができます。

go tool pprof cpu.prof

pprof コマンドラインから使用できるコマンドはたくさんあります。 一般的に使用されるコマンドには,トッププログラムのホットスポットの概要を表示する "top" ,およびホットスポットとそれらのコールグラフのインタラクティブなグラフを開く "web" があります。 すべての pprof コマンドについては, "help" を使用してください。

pprof の詳細については, https://github.com/google/pprof/blob/master/doc/README.md を参照してください。

func Do 1.9

func Do(ctx context.Context, labels LabelSet, f func(context.Context))

指定されたラベルを親のラベルマップに追加して,親コンテキストのコピーで f を呼び出します。 f の実行中に生成されたゴルーチンは,拡張ラベルセットを継承します。ラベルの各キー / 値ペアは,指定された順序でラベルマップに挿入され,同じキーの以前の値を上書きします。拡張ラベルマップは, f の呼び出し中に設定され, f が返されると復元されます。

func ForLabels 1.9

func ForLabels(ctx context.Context, f func(key, value string) bool)

ForLabels は,各ラベルをコンテキストに設定して f を呼び出します。 関数 f は,繰り返しを継続するには true を返し,繰り返しを早く停止するには false を返す必要があります。

func Label 1.9

func Label(ctx context.Context, key string) (string, bool)

Label は, ctx に指定されたキーを持つラベルの値と,そのラベルが存在するかどうかを示すブール値を返します。

func SetGoroutineLabels 1.9

func SetGoroutineLabels(ctx context.Context)

SetGoroutineLabels は,現在のゴルーチンのラベルを ctx と一致するように設定します。新しいゴルーチンは,それを作成したゴルーチンのラベルを継承します。これは Do よりも低レベルの API であり,可能な場合は代わりに使用する必要があります。

func StartCPUProfile

func StartCPUProfile(w io.Writer) error

StartCPUProfile は,現在のプロセスの CPU プロファイリングを有効にします。 プロファイリングしている間,プロファイルはバッファされて w に書き込まれます。 プロファイリングがすでに有効になっている場合, StartCPUProfile はエラーを返します。

Unix 系システムでは, StartCPUProfile は, -buildmode=c- アーカイブまたは -buildmode=c-shared でビルドされた Go コードに対してはデフォルトでは機能しません。 StartCPUProfile は SIGPROF シグナルに依存しますが,そのシグナルは Go で使用されるものではなくメインプログラムの SIGPROF シグナルハンドラ (もしあれば) に配信されます。 これを機能させるには, syscall.SIGPROF に対して os/signal.Notify を呼び出しますが,これを行うとメインプログラムによって行われているプロファイリングが壊れる可能性があることに注意してください。

func StopCPUProfile

func StopCPUProfile()

StopCPUProfile は,現在の CPU プロファイルがあればそれを停止します。 StopCPUProfile は,プロファイルに対するすべての書き込みが完了した後にのみ戻ります。

func WithLabels 1.9

func WithLabels(ctx context.Context, labels LabelSet) context.Context

WithLabels は与えられたラベルを追加した新しい context.Context を返します。 ラベルは前のラベルを同じキーで上書きします。

func WriteHeapProfile

func WriteHeapProfile(w io.Writer) error

WriteHeapProfile は Lookup(" ヒープ ") の省略形です WriteTo(w, 0) 。 下位互換性のために残されています。

type LabelSet 1.9

LabelSet はラベルのセットです。

type LabelSet struct {
    // エクスポートされていないフィールドがあります
}

func Labels 1.9

func Labels(args ...string) LabelSet

Labels はキーと値のペアを表す偶数個の文字列を受け取り,それらを含む LabelSet を作成します。 ラベルは前のラベルを同じキーで上書きします。 Currently only CPU profile utilizes labels information. See https://golang.org/issue/23458 for details.

type Profile

Profile は,割り当てなど,特定のイベントのインスタンスにつながった呼び出しシーケンスを示すスタックトレースの集まりです。 パッケージは独自のプロファイルを作成および管理できます。 最も一般的な用途は,ファイルやネットワーク接続など,明示的に閉じる必要があるリソースを追跡することです。

Profile のメソッドは,複数のゴルーチンから平行に呼び出すことができます。

各プロファイルには一意の名前があります。 いくつかのプロファイルが事前定義されています。

goroutine    - 現在のすべての goroutine のスタックトレース
heap         - ライブオブジェクトのメモリ割り当てのサンプリング
alloc        - 過去のすべてのメモリ割り当てのサンプリング
threadcreate - 新しい OS スレッドの作成につながったスタックトレース
block        - 同期プリミティブのブロックにつながったスタックトレース
mutex        - 競合ミューテックスの所有者のスタックトレース

これらの定義済みプロファイルはそれ自体を維持し,明示的な Add または Remove メソッド呼び出しでパニックします。

ヒーププロファイルは,最後に完了したガベージコレクションの統計を報告します。 プロファイルをライブデータからゴミに傾けないようにするために,最近の割り当てを省略します。 ガベージコレクションがまったく行われていない場合,ヒーププロファイルはすべての既知の割り当てを報告します。 この例外は,主にガベージコレクションを有効にせずに実行されているプログラムで,通常はデバッグ目的で役立ちます。

ヒーププロファイルは,アプリケーションメモリ内のすべてのライブオブジェクトと,プログラムの開始以降に割り当てられたすべてのオブジェクトの両方の割り当てサイトを追跡します。 Pprof の -inuse_space, -inuse_objects, -alloc_space ,および -alloc_objects の各フラグは,どちらを表示するかを選択します。 デフォルトでは, -inuse_space (ライブオブジェクト,サイズでスケーリング) に設定されています。

allocs プロファイルはヒーププロファイルと同じですが,デフォルトの pprof 表示を,プログラムの開始以降に割り当てられた総バイト数 (ガベージコレクションされたバイトを含む) の -alloc_space に変更します。

CPU プロファイルはプロファイルとしては使用できません。 プロファイリング中に出力をライターにストリームするため,特別な API , StartCPUProfile 関数と StopCPUProfile 関数があります。

type Profile struct {
    // エクスポートされていないフィールドがあります
}

func Lookup

func Lookup(name string) *Profile

Lookup は与えられた名前のプロファイルを返します。 そのようなプロファイルが存在しない場合は nil を返します。

func NewProfile

func NewProfile(name string) *Profile

NewProfile は,指定された名前で新しいプロファイルを作成します。 その名前のプロファイルが既に存在する場合, NewProfile はパニックします。 慣用的に 'import/path' を使用します。 各パッケージに別々のネームスペースを作成するための接頭辞。 pprof データを読み取るさまざまなツールとの互換性のために,プロファイル名にスペースを入れないでください。

func Profiles

func Profiles() []*Profile

Profiles は,名前順にソートされた,既知のすべてのプロファイルのスライスを返します。

func (*Profile) Add

func (p *Profile) Add(value interface{}, skip int)

Add は現在の実行スタックを value に関連付けられたプロファイルに追加します。 値を内部マップに格納するので, value はマップキーとしての使用に適している必要があり,対応する Remove の呼び出しまでガベージコレクションされません。 プロファイルにすでに値のスタックが含まれている場合はパニックを追加します。

skip パラメータは, runtime.Caller の skip と同じ意味を持ち,スタックトレースの開始位置を制御します。 skip=0 を渡すと, Add を呼び出す関数内でトレースが開始されます。 たとえば,次の実行スタックがあるとします。

Add
called from rpc.NewClient
called from mypkg.Run
called from main.main

skip=0 を渡すと, rpc.NewClient 内で Add を呼び出したときにスタックトレースが開始されます。 skip=1 を渡すと, mypkg.Run 内の NewClient の呼び出し時にスタックトレースが開始されます。

func (*Profile) Count

func (p *Profile) Count() int

Count は,現在プロファイル内にある実行スタックの数を返します。

func (*Profile) Name

func (p *Profile) Name() string

Name はこのプロファイルの名前を返します。 これは,プロファイルを再取得するために Lookup に渡すことができます。

func (*Profile) Remove

func (p *Profile) Remove(value interface{})

Remove は,プロファイルから値に関連付けられた実行スタックを削除します。 値がプロファイルにない場合は,何もしません。

func (*Profile) WriteTo

func (p *Profile) WriteTo(w io.Writer, debug int) error

WriteTo は,プロファイルの pprof 形式のスナップショットを w に書き込みます。 w への書き込みがエラーを返す場合, WriteTo はそのエラーを返します。 そうでなければ, WriteTo は nil を返します。

debug パラメータは追加の出力を有効にします。 debug=0 を渡すと, pprof が必要とする 16 進数アドレスのみが出力されます。 debug=1 を渡すと,アドレスを関数名と行番号に変換するコメントが追加されるため,プログラマはツールなしでプロファイルを読むことができます。

事前定義プロファイルは他のデバッグ値に意味を割り当てることができます。 例えば, "goroutine" プロファイルを表示するとき, debug=2 は, Go プログラムが回復不能なパニックのために死ぬときに使用するのと同じ形式で goroutine スタックを表示することを意味します。

サブディレクトリ

名前 概要
..