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.