version: 1.10

package trace

import "runtime/trace"

Overview

Package trace contains facilities for programs to generate trace for Go execution tracer.

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.

Tracing a Go program

Support for tracing tests and benchmarks built with the standard testing package is built into go test. For example, the following command runs the test in the current directory and writes the trace file (trace.out).

  1. go test -trace=test.out

This runtime/trace package provides APIs to add equivalent tracing support to a standalone program. See the Example that demonstrates how to use this API to enable tracing.

There is also a standard HTTP interface to profiling data. Adding the following line will install handlers under the /debug/pprof/trace URL to download live profiles:

  1. import _ "net/http/pprof"

See the net/http/pprof package for more details.

Example:

  1. package trace_test
  3. import (
  4.     "fmt"
  5.     "log"
  6.     "os"
  7.     "runtime/trace"
  8. )
  10. // Example demonstrates the use of the trace package to trace
  11. // the execution of a Go program. The trace output will be
  12. // written to the file trace.out
  13. func Example() {
  14.     f, err := os.Create("trace.out")
  15.     if err != nil {
  16.         log.Fatalf("failed to create trace output file: %v", err)
  17.     }
  18.     defer func() {
  19.         if err := f.Close(); err != nil {
  20.             log.Fatalf("failed to close trace file: %v", err)
  21.         }
  22.     }()
  24.     if err := trace.Start(f); err != nil {
  25.         log.Fatalf("failed to start trace: %v", err)
  26.     }
  27.     defer trace.Stop()
  29.     // your program here
  30.     RunMyProgram()
  31. }
  33. func RunMyProgram() {
  34.     fmt.Printf("this function will be traced")
  35. }

Index

Examples

Package files

trace.go

func Start 

  1. func Start(w io.Writer) error

Start enables tracing for the current program. While tracing, the trace will be buffered and written to w. Start returns an error if tracing is already enabled.

func Stop 

  1. func Stop()

Stop stops the current tracing, if any. Stop only returns after all the writes for the trace have completed.