...

パッケージ trace

import "runtime/trace"
概要
目次

概要 ▾

trace パッケージは,Go 実行トレーサ用トレースを生成するプログラムのための機能を含みます。

ランタイムアクティビティのトレース

実行トレースは,ゴルーチンの作成/ブロック/ブロック解除,システムコールの開始/終了/ブロック, GC 関連のイベント,ヒープサイズの変更,プロセッサの開始/停止など,さまざまな実行イベントをキャプチャします。 スタックトレースはほとんどのイベントに対してキャプチャされます。 生成されたトレースは `go tool trace` を使って解釈できます。

標準のテストパッケージで構築されたトレーステストとベンチマークのサポートは `go test` に組み込まれています。 たとえば,次のコマンドは現在のディレクトリでテストを実行し,トレースファイル (trace.out) を書き込みます。

go test -trace=test.out

この runtime/trace パッケージは,スタンドアロンプ​​ログラムに同等のトレースサポートを追加するための API を提供します。 この API を使用してトレースを有効にする方法を示す例を参照してください。

データをトレースするための標準の HTTP インターフェースもあります。 次の行を追加すると, /debug/pprof/trace URL にハンドラをインストールしてライブトレースをダウンロードします。

import _ "net/http/pprof"

このインポートによってインストールされたすべてのデバッグエンドポイントの詳細については, net/http/pprof パッケージを参照してください。

ユーザー注釈

trace パッケージは,実行中に興味深いイベントを記録するために使用できるユーザー注釈 API を提供します。

ユーザー注釈には,ログメッセージ,地域,およびタスクの 3 種類があります。

Log は,メッセージのカテゴリや Log という名前のルーチンなどの追加情報とともにタイムスタンプ付きのメッセージを実行トレースに送信します。 実行トレーサは,ログカテゴリと Log で渡されるメッセージを使用してゴルーチンをフィルタしグループ化するための UI を提供します。

リージョンは,ゴルーチンの実行中に時間間隔を記録するためのものです。 定義上,リージョンは同じゴルーチンで開始および終了します。 リージョンは,サブインターバルを表すためにネストできます。 たとえば,次のコードでは,実行トレースに 4 つの領域を記録して,カプチーノ作成操作の順次ステップの期間をトレースします。

trace.WithRegion(ctx, "makeCappuccino", func() {

   // orderID は,多くのカプチーノ注文地域レコードの中から
   // 特定の注文を識別することを可能にします。
   trace.Log(ctx, "orderID", orderID)

   trace.WithRegion(ctx, "steamMilk", steamMilk)
   trace.WithRegion(ctx, "extractCoffee", extractCoffee)
   trace.WithRegion(ctx, "mixMilkCoffee", mixMilkCoffee)
})

taks は, RPC リクエスト, HTTP リクエスト,または複数のゴルーチンが一緒に動作することを必要とする可能性がある興味深いローカルオペレーションなどの論理オペレーションのトレースを支援する,より高レベルのコンポーネントです。 タスクは複数のゴルーチンを含むことができるので,それらは context.Context オブジェクトを通して追跡されます。 NewTask は新しいタスクを作成し,それを返された context.Context オブジェクトに埋め込みます。 ログメッセージとリージョンは,もしあれば, Log と WithRegion に渡された Context でタスクに添付されます。

たとえば,牛乳を泡立て,コーヒーを抽出し,牛乳とコーヒーを別々のゴルーチンで混ぜることにしたとします。 タスクを使って,トレースツールは特定のカプチーノ注文に関連するゴルーチンを識別することができます。

ctx, task := trace.NewTask(ctx, "makeCappuccino")
trace.Log(ctx, "orderID", orderID)

milk := make(chan bool)
espresso := make(chan bool)

go func() {
        trace.WithRegion(ctx, "steamMilk", steamMilk)
        milk <- true
}()
go func() {
        trace.WithRegion(ctx, "extractCoffee", extractCoffee)
        espresso <- true
}()
go func() {
        defer task.End() // When assemble is done, the order is complete.
        <-espresso
        <-milk
        trace.WithRegion(ctx, "mixMilkCoffee", mixMilkCoffee)
}()

トレースツールは,タスクの作成からタスクの終了までの時間を測定することによってタスクの待ち時間を計算し,トレースで見つかった各タスク型の待ち時間分布を提供します。

例では, Go プログラムの実行をトレースするための trace パッケージの使用方法を示します。 トレース出力はファイル trace.out に書き込まれます。

コード:

package trace_test

import (
    "fmt"
    "log"
    "os"
    "runtime/trace"
)

// 例では, Go プログラムの実行をトレースするための trace パッケージの使用方法を示します。
// トレース出力はファイル trace.out に書き込まれます。
func Example() {
    f, err := os.Create("trace.out")
    if err != nil {
        log.Fatalf("failed to create trace output file: %v", err)
    }
    defer func() {
        if err := f.Close(); err != nil {
            log.Fatalf("failed to close trace file: %v", err)
        }
    }()

    if err := trace.Start(f); err != nil {
        log.Fatalf("failed to start trace: %v", err)
    }
    defer trace.Stop()

    // ここにあなたのプログラムを書きます
    RunMyProgram()
}

func RunMyProgram() {
    fmt.Printf("this function will be traced")
}

func IsEnabled 1.11

func IsEnabled() bool

IsEnabled は,トレースが有効かどうかを報告します。 情報は助言のみです。 この関数が戻るまでにトレース状況が変わった可能性があります。

func Log 1.11

func Log(ctx context.Context, category, message string)

Log は与えられたカテゴリとメッセージで一回限りのイベントを発行します。 カテゴリは空にすることができ, API はシステム内に固有のカテゴリがほんの一握りしかないと見なします。

func Logf 1.11

func Logf(ctx context.Context, category, format string, args ...interface{})

Logf は Log と似ていますが,値は指定されたフォーマット仕様を使用してフォーマットされます。

func Start 1.5

func Start(w io.Writer) error

Start は現在のプログラムのトレースを有効にします。 トレース中に,トレースはバッファーに入れられ, w に書き込まれます。 トレースがすでに有効になっている場合, Start はエラーを返します。

func Stop 1.5

func Stop()

Stop は,現在のトレースがあれば,停止します。 トレースのすべての書き込みが完了した後にのみ停止を返します。

func WithRegion 1.11

func WithRegion(ctx context.Context, regionType string, fn func())

WithRegion は,呼び出し元のゴルーチンに関連付けられているリージョンを開始し, fn を実行してからリージョンを終了します。 コンテキストがタスクを実行している場合,領域はタスクに関連付けられています。 それ以外の場合,領域はバックグラウンドタスクに関連付けられています。

regionType は地域を分類するために使用されるので,ほんの一握りのユニークな地域型があるべきです。

type Region 1.11

Region は,実行時間間隔がトレースされるコードの領域です。

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

func StartRegion 1.11

func StartRegion(ctx context.Context, regionType string) *Region

StartRegion はリージョンを開始し,リージョンの終わりを示す関数を返します。 返された Region の End 関数は,リージョンが開始されたのと同じゴルーチンから呼び出されなければなりません。 各ゴルーチン内で,地域はネストしなければなりません。 つまり,この領域の後に開始された領域は,この領域を終了させる前に終了させる必要があります。 おすすめの使い方は

defer trace.StartRegion(ctx, "myTracedRegion").End()

func (*Region) End 1.11

func (r *Region) End()

終了は,トレースされたコード領域の終わりを示します。

type Task 1.11

Task は,ユーザー定義の論理操作をトレースするためのデータ型です。

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

func NewTask 1.11

func NewTask(pctx context.Context, taskType string) (ctx context.Context, task *Task)

NewTask は, taskType 型を持つタスクインスタンスを作成し,それをタスクを運ぶ Context と共に返します。 入力コンテキストにタスクが含まれている場合,新しいタスクはそのサブタスクです。

taskType は,タスクインスタンスを分類するために使用されます。 Go 実行トレーサーのような分析ツールは,システム内に限られた数の固有のタスク型しかないと仮定することができます。

返された終了関数は,タスクの終了を示すために使用されます。 トレースツールは,タスクの作成から終了関数が呼び出されるまでの時間としてタスクの待ち時間を測定し,タスク型ごとの待ち時間分布を提供します。 終了関数が複数回呼び出されると,最初の呼び出しだけが待ち時間測定に使用されます。

ctx, task := trace.NewTask(ctx, "awesomeTask")
trace.WithRegion(ctx, "preparation", prepWork)
// タスクの準備
go func() {  // 別のゴルーチンでタスクの処理を続行します。
    defer task.End()
    trace.WithRegion(ctx, "remainingWork", remainingWork)
}()

func (*Task) End 1.11

func (t *Task) End()

End は,タスクによって表される操作の終了を示します。