1// Copyright 2015 The Go Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style 3// license that can be found in the LICENSE file. 4 5// Package trace contains facilities for programs to generate trace 6// for Go execution tracer. 7// 8// The execution trace captures a wide range of execution events such as 9// goroutine creation/blocking/unblocking, syscall enter/exit/block, 10// GC-related events, changes of heap size, processor start/stop, etc. 11// A precise nanosecond-precision timestamp and a stack trace is 12// captured for most events. The generated trace can be interpreted 13// using `go tool trace`. 14// 15// Tracing a Go program 16// 17// Support for tracing tests and benchmarks built with the standard 18// testing package is built into `go test`. For example, the following 19// command runs the test in the current directory and writes the trace 20// file (trace.out). 21// 22// go test -trace=test.out 23// 24// This runtime/trace package provides APIs to add equivalent tracing 25// support to a standalone program. See the Example that demonstrates 26// how to use this API to enable tracing. 27// 28// There is also a standard HTTP interface to profiling data. Adding the 29// following line will install handlers under the /debug/pprof/trace URL 30// to download live profiles: 31// 32// import _ "net/http/pprof" 33// 34// See the net/http/pprof package for more details. 35package trace 36 37import ( 38 "io" 39 "runtime" 40) 41 42// Start enables tracing for the current program. 43// While tracing, the trace will be buffered and written to w. 44// Start returns an error if tracing is already enabled. 45func Start(w io.Writer) error { 46 if err := runtime.StartTrace(); err != nil { 47 return err 48 } 49 go func() { 50 for { 51 data := runtime.ReadTrace() 52 if data == nil { 53 break 54 } 55 w.Write(data) 56 } 57 }() 58 return nil 59} 60 61// Stop stops the current tracing, if any. 62// Stop only returns after all the writes for the trace have completed. 63func Stop() { 64 runtime.StopTrace() 65} 66