api.go 8.11 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
// Copyright 2016 The go-ethereum Authors
// This file is part of the go-ethereum library.
//
// The go-ethereum library is free software: you can redistribute it and/or modify
// it under the terms of the GNU Lesser General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// The go-ethereum library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public License
// along with the go-ethereum library. If not, see <http://www.gnu.org/licenses/>.

// Package debug interfaces Go runtime debugging facilities.
// This package is mostly glue code making these facilities available
// through the CLI and RPC subsystem. If you want to use them from Go code,
// use package runtime instead.
package debug

import (
24
	"bytes"
25 26 27 28 29
	"errors"
	"io"
	"os"
	"os/user"
	"path/filepath"
30
	"regexp"
31
	"runtime"
32
	"runtime/debug"
33 34 35 36 37
	"runtime/pprof"
	"strings"
	"sync"
	"time"

38
	"github.com/ethereum/go-ethereum/log"
39
	"github.com/hashicorp/go-bexpr"
40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55
)

// Handler is the global debugging handler.
var Handler = new(HandlerT)

// HandlerT implements the debugging API.
// Do not create values of this type, use the one
// in the Handler variable instead.
type HandlerT struct {
	mu        sync.Mutex
	cpuW      io.WriteCloser
	cpuFile   string
	traceW    io.WriteCloser
	traceFile string
}

56 57
// Verbosity sets the log verbosity ceiling. The verbosity of individual packages
// and source files can be raised using Vmodule.
58
func (*HandlerT) Verbosity(level int) {
59
	glogger.Verbosity(log.Lvl(level))
60 61
}

62 63
// Vmodule sets the log verbosity pattern. See package log for details on the
// pattern syntax.
64
func (*HandlerT) Vmodule(pattern string) error {
65
	return glogger.Vmodule(pattern)
66 67
}

68 69
// BacktraceAt sets the log backtrace location. See package log for details on
// the pattern syntax.
70
func (*HandlerT) BacktraceAt(location string) error {
71
	return glogger.BacktraceAt(location)
72 73
}

74 75 76 77 78 79 80 81 82 83 84 85 86 87
// MemStats returns detailed runtime memory statistics.
func (*HandlerT) MemStats() *runtime.MemStats {
	s := new(runtime.MemStats)
	runtime.ReadMemStats(s)
	return s
}

// GcStats returns GC statistics.
func (*HandlerT) GcStats() *debug.GCStats {
	s := new(debug.GCStats)
	debug.ReadGCStats(s)
	return s
}

88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115
// CpuProfile turns on CPU profiling for nsec seconds and writes
// profile data to file.
func (h *HandlerT) CpuProfile(file string, nsec uint) error {
	if err := h.StartCPUProfile(file); err != nil {
		return err
	}
	time.Sleep(time.Duration(nsec) * time.Second)
	h.StopCPUProfile()
	return nil
}

// StartCPUProfile turns on CPU profiling, writing to the given file.
func (h *HandlerT) StartCPUProfile(file string) error {
	h.mu.Lock()
	defer h.mu.Unlock()
	if h.cpuW != nil {
		return errors.New("CPU profiling already in progress")
	}
	f, err := os.Create(expandHome(file))
	if err != nil {
		return err
	}
	if err := pprof.StartCPUProfile(f); err != nil {
		f.Close()
		return err
	}
	h.cpuW = f
	h.cpuFile = file
116
	log.Info("CPU profiling started", "dump", h.cpuFile)
117 118 119 120 121 122 123 124 125 126 127
	return nil
}

// StopCPUProfile stops an ongoing CPU profile.
func (h *HandlerT) StopCPUProfile() error {
	h.mu.Lock()
	defer h.mu.Unlock()
	pprof.StopCPUProfile()
	if h.cpuW == nil {
		return errors.New("CPU profiling not in progress")
	}
128
	log.Info("Done writing CPU profile", "dump", h.cpuFile)
129 130 131 132 133 134
	h.cpuW.Close()
	h.cpuW = nil
	h.cpuFile = ""
	return nil
}

135
// GoTrace turns on tracing for nsec seconds and writes
136
// trace data to file.
137
func (h *HandlerT) GoTrace(file string, nsec uint) error {
138
	if err := h.StartGoTrace(file); err != nil {
139 140 141
		return err
	}
	time.Sleep(time.Duration(nsec) * time.Second)
142
	h.StopGoTrace()
143 144 145
	return nil
}

146 147 148
// BlockProfile turns on goroutine profiling for nsec seconds and writes profile data to
// file. It uses a profile rate of 1 for most accurate information. If a different rate is
// desired, set the rate and write the profile manually.
149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
func (*HandlerT) BlockProfile(file string, nsec uint) error {
	runtime.SetBlockProfileRate(1)
	time.Sleep(time.Duration(nsec) * time.Second)
	defer runtime.SetBlockProfileRate(0)
	return writeProfile("block", file)
}

// SetBlockProfileRate sets the rate of goroutine block profile data collection.
// rate 0 disables block profiling.
func (*HandlerT) SetBlockProfileRate(rate int) {
	runtime.SetBlockProfileRate(rate)
}

// WriteBlockProfile writes a goroutine blocking profile to the given file.
func (*HandlerT) WriteBlockProfile(file string) error {
	return writeProfile("block", file)
}

167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186
// MutexProfile turns on mutex profiling for nsec seconds and writes profile data to file.
// It uses a profile rate of 1 for most accurate information. If a different rate is
// desired, set the rate and write the profile manually.
func (*HandlerT) MutexProfile(file string, nsec uint) error {
	runtime.SetMutexProfileFraction(1)
	time.Sleep(time.Duration(nsec) * time.Second)
	defer runtime.SetMutexProfileFraction(0)
	return writeProfile("mutex", file)
}

// SetMutexProfileFraction sets the rate of mutex profiling.
func (*HandlerT) SetMutexProfileFraction(rate int) {
	runtime.SetMutexProfileFraction(rate)
}

// WriteMutexProfile writes a goroutine blocking profile to the given file.
func (*HandlerT) WriteMutexProfile(file string) error {
	return writeProfile("mutex", file)
}

187 188 189 190 191 192 193
// WriteMemProfile writes an allocation profile to the given file.
// Note that the profiling rate cannot be set through the API,
// it must be set on the command line.
func (*HandlerT) WriteMemProfile(file string) error {
	return writeProfile("heap", file)
}

194 195 196 197
// Stacks returns a printed representation of the stacks of all goroutines. It
// also permits the following optional filters to be used:
//   - filter: boolean expression of packages to filter for
func (*HandlerT) Stacks(filter *string) string {
198 199
	buf := new(bytes.Buffer)
	pprof.Lookup("goroutine").WriteTo(buf, 2)
200 201 202 203 204 205 206 207 208 209

	// If any filtering was requested, execute them now
	if filter != nil && len(*filter) > 0 {
		expanded := *filter

		// The input filter is a logical expression of package names. Transform
		// it into a proper boolean expression that can be fed into a parser and
		// interpreter:
		//
		// E.g. (eth || snap) && !p2p -> (eth in Value || snap in Value) && p2p not in Value
210
		expanded = regexp.MustCompile(`[:/\.A-Za-z0-9_-]+`).ReplaceAllString(expanded, "`$0` in Value")
211
		expanded = regexp.MustCompile("!(`[:/\\.A-Za-z0-9_-]+`)").ReplaceAllString(expanded, "$1 not")
212 213
		expanded = strings.ReplaceAll(expanded, "||", "or")
		expanded = strings.ReplaceAll(expanded, "&&", "and")
214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231
		log.Info("Expanded filter expression", "filter", *filter, "expanded", expanded)

		expr, err := bexpr.CreateEvaluator(expanded)
		if err != nil {
			log.Error("Failed to parse filter expression", "expanded", expanded, "err", err)
			return ""
		}
		// Split the goroutine dump into segments and filter each
		dump := buf.String()
		buf.Reset()

		for _, trace := range strings.Split(dump, "\n\n") {
			if ok, _ := expr.Evaluate(map[string]string{"Value": trace}); ok {
				buf.WriteString(trace)
				buf.WriteString("\n\n")
			}
		}
	}
232
	return buf.String()
233 234
}

235
// FreeOSMemory forces a garbage collection.
236 237 238 239
func (*HandlerT) FreeOSMemory() {
	debug.FreeOSMemory()
}

240 241 242 243 244 245
// SetGCPercent sets the garbage collection target percentage. It returns the previous
// setting. A negative value disables GC.
func (*HandlerT) SetGCPercent(v int) int {
	return debug.SetGCPercent(v)
}

246 247
func writeProfile(name, file string) error {
	p := pprof.Lookup(name)
248
	log.Info("Writing profile records", "count", p.Count(), "type", name, "dump", file)
249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272
	f, err := os.Create(expandHome(file))
	if err != nil {
		return err
	}
	defer f.Close()
	return p.WriteTo(f, 0)
}

// expands home directory in file paths.
// ~someuser/tmp will not be expanded.
func expandHome(p string) string {
	if strings.HasPrefix(p, "~/") || strings.HasPrefix(p, "~\\") {
		home := os.Getenv("HOME")
		if home == "" {
			if usr, err := user.Current(); err == nil {
				home = usr.HomeDir
			}
		}
		if home != "" {
			p = home + p[1:]
		}
	}
	return filepath.Clean(p)
}