Package trace

import "runtime/trace"
Overview
Index
Examples

Overview ▾

包跟踪包含用于程序生成Go执行跟踪器跟踪的工具.

Tracing runtime activities

The execution trace captures a wide range of execution events such as goroutine creation/blocking/unblocking, syscall enter/exit/block, GC-related events, changes of heap size, processor start/stop, etc. A precise nanosecond-precision timestamp and a stack trace is captured for most events. The generated trace can be interpreted using `go tool trace`.

Support for tracing tests and benchmarks built with the standard testing package is built into `go test`. " go test"内置了对使用标准测试包构建的跟踪测试和基准的支持. For example, the following command runs the test in the current directory and writes the trace file (trace.out). 例如,以下命令在当前目录中运行测试并写入跟踪文件(trace.out).

go test -trace=test.out

此运行时/跟踪程序包提供API,以向独立程序添加等效的跟踪支持. 请参阅示例,该示例演示如何使用此API启用跟踪.

还有一个标准的HTTP接口来跟踪数据. 添加以下行将在/ debug / pprof / trace URL下安装一个处理程序,以下载实时跟踪:

import _ "net/http/pprof"

有关此导入安装的所有调试端点的更多详细信息,请参见net / http / pprof软件包.

User annotation

程序包跟踪提供了用户注释API,可用于在执行期间记录有趣的事件.

用户注释有三种类型:日志消息,区域和任务.

Log向执行跟踪发出带有时间戳的消息以及其他信息,例如消息的类别和称为Log的goroutine. 执行跟踪程序提供UI来使用日志类别和Log中提供的消息来过滤和分组goroutine.

区域用于记录goroutine执行期间的时间间隔. 根据定义,区域在同一goroutine中开始和结束. 区域可以嵌套以表示子间隔. 例如,以下代码在执行跟踪中记录四个区域,以跟踪卡布奇诺咖啡制作操作中顺序步骤的持续时间.

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

   // orderID allows to identify a specific order
   // among many cappuccino order region records.
   trace.Log(ctx, "orderID", orderID)

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

任务是高级组件,有助于跟踪逻辑操作,例如RPC请求,HTTP请求或有趣的本地操作,这些操作可能需要多个goroutine一起工作. 由于任务可能涉及多个goroutine,因此可以通过context.Context对象对其进行跟踪. NewTask创建一个新任务,并将其嵌入到返回的context.Context对象中. 在传递给Log和WithRegion的Context中,日志消息和区域将附加到任务(如果有).

例如,假设我们决定使牛奶起泡,提取咖啡,并将牛奶和咖啡混合在单独的goroutine中. 通过执行任务,跟踪工具可以识别特定卡布奇诺咖啡顺序中涉及的goroutine.

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)
}()

跟踪工具通过测量任务创建和任务结束之间的时间来计算任务的延迟,并为跟踪中找到的每种任务类型提供延迟分布.

Example

示例演示了使用跟踪包来跟踪Go程序的执行情况. 跟踪输出将被写入文件trace.out

func IsEnabled 1.11

func IsEnabled() bool

IsEnabled报告是否启用了跟踪. 该信息仅供参考. 该函数返回时,跟踪状态可能已更改.

func Log 1.11

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

日志发出带有给定类别和消息的一次性事件. 类别可以为空,并且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

通过启动可以跟踪当前程序. 跟踪时,跟踪将被缓冲并写入w. 如果已经启用了跟踪,则Start将返回错误.

func Stop 1.5

func Stop()

Stop停止当前跟踪(如果有). 仅在跟踪的所有写操作完成后才返回Stop.

func WithRegion 1.11

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

WithRegion启动与其调用goroutine关联的区域,运行fn,然后结束该区域. 如果上下文承载任务,则将区域与任务关联. 否则,该区域将附加到后台任务.

regionType用于对区域进行分类,因此应该只有少数唯一的区域类型.

type Region 1.11

区域是跟踪执行时间间隔的代码区域.

type Region struct {
    // contains filtered or unexported fields
}

func StartRegion 1.11

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

StartRegion启动一个区域并返回一个用于标记该区域结束的函数. 返回的Region的End函数必须从启动该区域的同一个goroutine中调用. 在每个goroutine中,区域必须嵌套. 即,必须先终止在该区域之后开始的区域,然后才能终止该区域. 推荐用法是

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

func (*Region) End 1.11

func (r *Region) End()

结束标记跟踪的代码区域的结束.

type Task 1.11

任务是用于跟踪用户定义的逻辑操作的数据类型.

type Task struct {
    // contains filtered or unexported fields
}

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)
// preparation of the task
go func() {  // continue processing the task in a separate goroutine.
    defer task.End()
    trace.WithRegion(ctx, "remainingWork", remainingWork)
}()

func (*Task) End 1.11

func (t *Task) End()

结束标记任务代表的操作的结束.

by  ICOPY.SITE