# package pprof `import "runtime/pprof"` pprof包以pprof可視化工具期望的格式書寫運行時剖面數據。 pprof的更多信息參見[http://code.google.com/p/google-perftools/](http://code.google.com/p/google-perftools/)。 ## Index * [func Profiles() []\*Profile](#Profiles) * [func StartCPUProfile(w io.Writer) error](#StartCPUProfile) * [func StopCPUProfile()](#StopCPUProfile) * [func WriteHeapProfile(w io.Writer) error](#WriteHeapProfile) * [type Profile](#Profile) * [func Lookup(name string) \*Profile](#Lookup) * [func NewProfile(name string) \*Profile](#NewProfile) * [func (p \*Profile) Name() string](#Profile.Name) * [func (p \*Profile) Add(value interface{}, skip int)](#Profile.Add) * [func (p \*Profile) Count() int](#Profile.Count) * [func (p \*Profile) Remove(value interface{})](#Profile.Remove) * [func (p \*Profile) WriteTo(w io.Writer, debug int) error](#Profile.WriteTo) ## func [Profiles](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L132 "View Source") ``` func Profiles() []*Profile ``` Profiles返回所有已知profile的切片，按名稱排序。 ## func [StartCPUProfile](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L565 "View Source") ``` func StartCPUProfile(w io.Writer) error ``` StartCPUProfile為當前進程開啟CPU profile。在分析時，分析報告會緩存并寫入到w中。若分析已經開啟，StartCPUProfile就會返回錯誤。 ## func [StopCPUProfile](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L612 "View Source") ``` func StopCPUProfile() ``` StopCPUProfile會停止當前的CPU profile（如果有）。StopCPUProfile?只會在所有的分析報告寫入完畢后才會返回。 ## func [WriteHeapProfile](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L369 "View Source") ``` func WriteHeapProfile(w io.Writer) error ``` WriteHeapProfile是Lookup("heap").WriteTo(w, 0)?的簡寫。它是為了保持向后兼容性而存在的。 ## type [Profile](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L48 "View Source") ``` 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](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L125 "View Source") ``` func Lookup(name string) *Profile ``` Lookup返回具有指定名字的Profile；如果沒有，會返回nil。 ### func [NewProfile](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L107 "View Source") ``` func NewProfile(name string) *Profile ``` 以給定的名稱創建一個新的Profile。若擁有該名稱的Profile已存在，NewProfile就會panic。 約定會使用'import/path.'前綴來為每個包創建單獨的命名空間。 ### func (\*Profile) [Name](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L152 "View Source") ``` func (p *Profile) Name() string ``` Name返回該Profile的名稱，它可被傳入Lookup來重新獲取該Profile。 ### func (\*Profile) [Add](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L184 "View Source") ``` 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](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L157 "View Source") ``` func (p *Profile) Count() int ``` Count返回該Profile中當前執行棧的數量。 ### func (\*Profile) [Remove](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L205 "View Source") ``` func (p *Profile) Remove(value interface{}) ``` Remove從該分析中移除與值value相關聯的執行棧。若值value不在此分析中，則不做操作。 ### func (\*Profile) [WriteTo](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L224 "View Source") ``` 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 [?](https://github.com/golang/go/blob/master/src/runtime/pprof/pprof.go#L23 "View Source") NetBSD和OS X上的profile記錄服務是不完整、不準確的，參見http://golang.org/issue/6047獲取細節。