package pprof

import "runtime/pprof"

pprof包以pprof可视化工具期望的格式书写运行时剖面数据。

pprof的更多信息参见http://code.google.com/p/google-perftools/

Index

返回首页


  • func Profiles() []*Profile
  • func StartCPUProfile(w io.Writer) error
  • func StopCPUProfile()
  • func WriteHeapProfile(w io.Writer) error
  • type Profile
  • func Profiles

    func Profiles() []*Profile

    Profiles返回所有已知profile的切片,按名称排序。

    func StartCPUProfile

    func StartCPUProfile(w io.Writer) error

    StartCPUProfile为当前进程开启CPU profile。在分析时,分析报告会缓存并写入到w中。若分析已经开启,StartCPUProfile就会返回错误。

    func StopCPUProfile

    func StopCPUProfile()

    StopCPUProfile会停止当前的CPU profile(如果有)。StopCPUProfile 只会在所有的分析报告写入完毕后才会返回。

    func WriteHeapProfile

    func WriteHeapProfile(w io.Writer) error

    WriteHeapProfile是Lookup("heap").WriteTo(w, 0) 的简写。它是为了保持向后兼容性而存在的。

    type Profile

    type Profile struct {
        // 内含隐藏或非导出字段
    }

    Profile是一个调用栈踪迹的集合,显示导致特定事件(如内存分配)的实例的调用栈序列。包可以创建并维护它们自己的profile;它一般用于跟踪必须被显式关闭的资源,例如文件或网络连接。

    一个Profile的方法可被多个Go程同时调用。

    每个Profile都有唯一的名称。有些Profile是预定义的:

    goroutine      - 当前Go所有程的调用栈踪迹
    heap           - 所有堆分配的采样
    threadcreate   - 导致新的OS线程创建的调用栈踪迹
    block          - 导致同步原语水平的阻塞的调用栈踪迹

    这些预声明的Profile自我维护,如果对它们调用Add或者Remove时,将导致panic。

    CPU profile不能作为Profile使用。它有专门的API,即StartCPUProfile和StopCPUProfile函数,因为它在分析时是以流的形式输出到writer中的。

    func Lookup

    func Lookup(name string) *Profile

    Lookup返回具有指定名字的Profile;如果没有,会返回nil。

    func NewProfile

    func NewProfile(name string) *Profile

    以给定的名称创建一个新的Profile。若拥有该名称的Profile已存在,NewProfile就会panic。

    约定会使用'import/path.'前缀来为每个包创建单独的命名空间。

    func (*Profile) Name

    func (p *Profile) Name() string

    Name返回该Profile的名称,它可被传入Lookup来重新获取该Profile。

    func (*Profile) Add

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

    Add 将当前的执行栈添加到该分析中,并与value关联。Add在一个内部映射中存储值,因此value必须适于用作映射键,且在对应的Remove调用之前不会被垃圾收集。

    若分析的映射中已经存在value键,Add就会引发panic。

    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的调用开始;当skp=1时,堆调用踪迹从对rpc.NewClient的调用开始。

    func (*Profile) Count

    func (p *Profile) Count() int

    Count返回该Profile中当前执行栈的数量。

    func (*Profile) Remove

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

    Remove从该分析中移除与值value相关联的执行栈。若值value不在此分析中,则不做操作。

    func (*Profile) WriteTo

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

    函数将pprof格式的profile快照写入w中。若一个向w的写入返回一个错误,WriteTo就会返回该错误;否则会返回nil。

    debug 参数用于开启附加的输出。如果debug=0,只会打印pprof所需要的十六进制地址;如果debug=1,会将地址翻译为函数名和行号并添加注释,以便让程序员无需工具阅读分析报告。

    预定义Profile为其它debug值赋予了含义。例如,当打印“Go程”的分析报告时,debug=2意为:由于不可恢复的恐慌而濒临崩溃时,使用与Go程序相同的格式打印Go程的堆栈信息。

    Bugs

    NetBSD和OS X上的profile记录服务是不完整、不准确的,参见http://golang.org/issue/6047获取细节。