Пакет debug
Обзор
Пакет debug содержит средства, позволяющие программам отлаживать себя во время выполнения.
Индекс
Примеры
Файлы пакета
garbage.go mod.go stack.go stubs.go
func FreeOSMemory 1.1
func FreeOSMemory()
FreeOSMemory принудительно запускает сборку мусора, а затем пытается вернуть операционной системе как можно больше памяти. (Даже если эта функция не вызывается, среда выполнения постепенно возвращает память операционной системе в фоновой задаче.)
func PrintStack
func PrintStack()
PrintStack выводит в стандартный поток ошибок трассировку стека, возвращаемую runtime.Stack.
func ReadGCStats 1.1
func ReadGCStats(stats *GCStats)
ReadGCStats считывает статистику сборки мусора в stats. Количество записей в истории пауз зависит от системы; срез stats.Pause будет использован повторно, если его емкости достаточно, иначе будет выделен заново. ReadGCStats может использовать всю емкость среза stats.Pause. Если stats.PauseQuantiles не пуст, ReadGCStats заполняет его квантилями, суммирующими распределение времени пауз. Например, если len(stats.PauseQuantiles) равно 5, он будет заполнен минимальным, 25-м, 50-м, 75-м процентилями и максимальным временем паузы.
func SetCrashOutput 1.23
func SetCrashOutput(f *os.File, opts CrashOptions) error
SetCrashOutput настраивает один дополнительный файл, в который выводятся необработанные паники и другие фатальные ошибки в дополнение к стандартному потоку ошибок. Дополнительный файл может быть только один: повторный вызов SetCrashOutput переопределяет все предыдущие вызовы. SetCrashOutput дублирует файловый дескриптор f, поэтому вызывающий код может безопасно закрыть f сразу после возврата SetCrashOutput. Чтобы отключить этот дополнительный вывод при сбое, вызовите SetCrashOutput(nil). Если вызов выполняется одновременно со сбоем, часть уже выполняемого вывода может быть записана в старый файл даже после возврата переопределяющего вызова SetCrashOutput.
Пример (Monitor)
ExampleSetCrashOutput_monitor демонстрирует использование [debug.SetCrashOutput] для перенаправления сообщений о сбоях в процесс «монитор» для автоматизированного формирования отчетов о сбоях. Монитор — это тот же исполняемый файл, запущенный в специальном режиме, который определяется переменной среды.
Код:
package debug_test
import (
"io"
"log"
"os"
"os/exec"
"runtime/debug"
)
// ExampleSetCrashOutput_monitor shows an example of using
// [debug.SetCrashOutput] to direct crashes to a "monitor" process,
// for automated crash reporting. The monitor is the same executable,
// invoked in a special mode indicated by an environment variable.
func ExampleSetCrashOutput_monitor() {
appmain()
// This Example doesn't actually run as a test because its
// purpose is to crash, so it has no "Output:" comment
// within the function body.
//
// To observe the monitor in action, replace the entire text
// of this comment with "Output:" and run this command:
//
// $ go test -run=ExampleSetCrashOutput_monitor runtime/debug
// panic: oops
// ...stack...
// monitor: saved crash report at /tmp/10804884239807998216.crash
}
// appmain represents the 'main' function of your application.
func appmain() {
monitor()
// Run the application.
println("hello")
panic("oops")
}
// monitor starts the monitor process, which performs automated
// crash reporting. Call this function immediately within main.
//
// This function re-executes the same executable as a child process,
// in a special mode. In that mode, the call to monitor will never
// return.
func monitor() {
const monitorVar = "RUNTIME_DEBUG_MONITOR"
if os.Getenv(monitorVar) != "" {
// This is the monitor (child) process.
log.SetFlags(0)
log.SetPrefix("monitor: ")
crash, err := io.ReadAll(os.Stdin)
if err != nil {
log.Fatalf("failed to read from input pipe: %v", err)
}
if len(crash) == 0 {
// Parent process terminated without reporting a crash.
os.Exit(0)
}
// Save the crash report securely in the file system.
f, err := os.CreateTemp("", "*.crash")
if err != nil {
log.Fatal(err)
}
if _, err := f.Write(crash); err != nil {
log.Fatal(err)
}
if err := f.Close(); err != nil {
log.Fatal(err)
}
log.Fatalf("saved crash report at %s", f.Name())
}
// This is the application process.
// Fork+exec the same executable in monitor mode.
exe, err := os.Executable()
if err != nil {
log.Fatal(err)
}
cmd := exec.Command(exe, "-test.run=^ExampleSetCrashOutput_monitor$")
// Be selective in which variables we allow the child to inherit.
// Depending on the application, some may be necessary,
// while others (e.g. GOGC, GOMEMLIMIT) may be harmful; see #73490.
cmd.Env = []string{monitorVar + "=1"}
cmd.Stderr = os.Stderr
cmd.Stdout = os.Stderr
pipe, err := cmd.StdinPipe()
if err != nil {
log.Fatalf("StdinPipe: %v", err)
}
debug.SetCrashOutput(pipe.(*os.File), debug.CrashOptions{}) // (this conversion is safe)
if err := cmd.Start(); err != nil {
log.Fatalf("can't start monitor: %v", err)
}
// Now return and start the application proper...
}
func SetGCPercent 1.1
func SetGCPercent(percent int) int
SetGCPercent задает целевой процент сборки мусора: сборка запускается, когда отношение недавно выделенных данных к живым данным, оставшимся после предыдущей сборки, достигает этого значения. SetGCPercent возвращает предыдущее значение. Начальное значение равно значению переменной среды GOGC при запуске или 100, если переменная не задана. Это значение может быть фактически уменьшено для соблюдения ограничения памяти. Отрицательное значение эффективно отключает сборку мусора, если только не достигнуто ограничение памяти. Подробнее см. SetMemoryLimit.
func SetMaxStack 1.2
func SetMaxStack(bytes int) int
SetMaxStack задает максимальный объем памяти, который может использовать стек одной горутины. Если при увеличении стека какая-либо горутина превысит это ограничение, программа аварийно завершится. SetMaxStack возвращает предыдущее значение. Начальное значение — 1 ГБ в 64-разрядных системах и 250 МБ в 32-разрядных системах. Независимо от значения, переданного SetMaxStack, система может устанавливать собственное максимальное ограничение стека.
SetMaxStack полезна главным образом для ограничения ущерба, наносимого горутинами, попавшими в бесконечную рекурсию. Она ограничивает только дальнейший рост стека.
func SetMaxThreads 1.2
func SetMaxThreads(threads int) int
SetMaxThreads задает максимальное количество потоков операционной системы, которое может использовать программа Go. Если программа попытается использовать больше потоков, она аварийно завершится. SetMaxThreads возвращает предыдущее значение. Начальное значение — 10 000 потоков.
Ограничение регулирует количество потоков операционной системы, а не количество горутин. Программа Go создает новый поток только тогда, когда горутина готова к выполнению, но все существующие потоки заблокированы системными вызовами, вызовами cgo или привязаны к другим горутинам из-за использования runtime.LockOSThread.
SetMaxThreads полезна главным образом для ограничения ущерба от программ, создающих неограниченное количество потоков. Идея состоит в том, чтобы остановить программу до того, как она остановит операционную систему.
func SetMemoryLimit 1.19
func SetMemoryLimit(limit int64) int64
SetMemoryLimit задает для среды выполнения мягкое ограничение памяти.
Среда выполнения предпринимает ряд действий, чтобы соблюдать это ограничение, в том числе регулирует частоту сборки мусора и активнее возвращает память базовой системе. Это ограничение будет соблюдаться даже при GOGC=off (или если выполнена функция SetGCPercent(-1)).
Ограничение задается в байтах и включает всю отображенную в память, управляемую и не освобожденную средой выполнения Go память. В частности, оно не учитывает место, занимаемое двоичным файлом Go, и память вне Go, например память, управляемую базовой системой от имени процесса, или память, управляемую кодом не на Go в том же процессе. Примеры исключенных источников памяти: память ядра ОС, выделенная для процесса, память, выделенная кодом C, и память, отображенная с помощью syscall.Mmap (поскольку она не управляется средой выполнения Go).
Точнее, следующее выражение корректно отражает значение, которое среда выполнения стремится поддерживать в качестве ограничения:
runtime.MemStats.Sys - runtime.MemStats.HeapReleased
или в терминах пакета runtime/metrics:
/memory/classes/total:bytes - /memory/classes/heap/released:bytes
Нулевое ограничение или ограничение, значение которого ниже объема памяти, используемой средой выполнения Go, может привести к почти непрерывной работе сборщика мусора. Однако приложение может продолжать работу.
Среда выполнения Go всегда соблюдает ограничение памяти, поэтому, чтобы фактически отключить это поведение, задайте очень высокое ограничение. math.MaxInt64 — каноническое значение для отключения ограничения, но значения, значительно превышающие объем доступной памяти базовой системы, также подходят.
Подробное руководство по мягкому ограничению памяти, а также различные распространенные варианты использования и сценарии см. на странице https://go.dev/doc/gc-guide.
Начальное значение — math.MaxInt64, если не задана переменная среды GOMEMLIMIT; в этом случае она задает начальное значение. GOMEMLIMIT — числовое значение в байтах с необязательным суффиксом единицы измерения. Поддерживаются суффиксы B, KiB, MiB, GiB и TiB. Они обозначают количества байтов согласно стандарту IEC 80000-13. То есть они основаны на степенях двойки: KiB означает 2^10 байт, MiB — 2^20 байт и так далее.
SetMemoryLimit возвращает ранее установленное ограничение памяти. Отрицательное входное значение не изменяет ограничение и позволяет получить текущее установленное ограничение памяти.
func SetPanicOnFault 1.3
func SetPanicOnFault(enabled bool) bool
SetPanicOnFault управляет поведением среды выполнения, когда программа получает ошибку доступа по неожиданному (ненулевому) адресу. Такие ошибки обычно вызваны дефектами, например повреждением памяти во время выполнения, поэтому по умолчанию программа аварийно завершается. Программы, работающие с файлами, отображенными в память, или небезопасно манипулирующие памятью, могут получать ошибки доступа по ненулевым адресам и в менее критичных ситуациях; SetPanicOnFault позволяет таким программам запросить, чтобы среда выполнения вызвала только панику, а не аварийно завершила работу. Тип runtime.Error, с которым среда выполнения вызывает панику, может иметь дополнительный метод:
Addr() uintptr
Если этот метод существует, он возвращает адрес памяти, вызвавший ошибку доступа. Результаты Addr являются наилучшей оценкой, и их достоверность может зависеть от платформы. SetPanicOnFault применяется только к текущей горутине. Функция возвращает предыдущее значение.
func SetTraceback 1.6
func SetTraceback(level string)
SetTraceback задает объем подробностей, выводимых средой выполнения в трассировке перед завершением программы из-за необработанной паники или внутренней ошибки среды выполнения. Аргумент level принимает те же значения, что и переменная среды GOTRACEBACK. Например, SetTraceback("all") гарантирует, что при аварийном завершении программа выведет сведения обо всех горутинах. Подробнее см. документацию пакета runtime. Если SetTraceback вызывается с уровнем ниже значения переменной среды, вызов игнорируется.
func Stack
func Stack() []byte
Stack возвращает форматированную трассировку стека горутины, которая ее вызывает. Функция вызывает runtime.Stack с буфером достаточного размера, чтобы сохранить всю трассировку.
func WriteHeapDump 1.3
func WriteHeapDump(fd uintptr)
WriteHeapDump записывает описание кучи и содержащихся в ней объектов в указанный файловый дескриптор.
WriteHeapDump приостанавливает выполнение всех горутин до полной записи дампа кучи. Поэтому файловый дескриптор не должен быть подключен к каналу или сокету, другой конец которого находится в том же процессе Go; вместо этого используйте временный файл или сетевой сокет.
Формат дампа кучи определен по адресу https://golang.org/s/go15heapdump.
type BuildInfo 1.12
BuildInfo представляет информацию о сборке, считанную из двоичного файла Go.
type BuildInfo struct {
// GoVersion is the version of the Go toolchain that built the binary
// (for example, "go1.19.2").
GoVersion string `json:",omitempty"` // Go 1.18
// Path is the package path of the main package for the binary
// (for example, "golang.org/x/tools/cmd/stringer").
Path string `json:",omitempty"`
// Main describes the module that contains the main package for the binary.
Main Module `json:""`
// Deps describes all the dependency modules, both direct and indirect,
// that contributed packages to the build of this binary.
Deps []*Module `json:",omitempty"`
// Settings describes the build settings used to build the binary.
Settings []BuildSetting `json:",omitempty"` // Go 1.18
}
func ParseBuildInfo 1.18
func ParseBuildInfo(data string) (bi *BuildInfo, err error)
ParseBuildInfo разбирает строку, возвращенную функцией *BuildInfo.String, восстанавливая исходный BuildInfo, за исключением того, что поле GoVersion не задается. Обычно программы не должны вызывать эту функцию, а должны вызывать ReadBuildInfo, debug/buildinfo.ReadFile или debug/buildinfo.Read.
func ReadBuildInfo 1.12
func ReadBuildInfo() (info *BuildInfo, ok bool)
ReadBuildInfo возвращает информацию о сборке, встроенную в выполняемый двоичный файл. Эта информация доступна только в двоичных файлах, собранных с поддержкой модулей.
func (*BuildInfo) String 1.18
func (bi *BuildInfo) String() string
String возвращает строковое представление BuildInfo.
type BuildSetting 1.18
BuildSetting — это пара ключ-значение, описывающая один параметр, повлиявший на сборку.
К определенным ключам относятся:
- -buildmode: используемый флаг buildmode (обычно "exe")
- -compiler: используемый флаг цепочки инструментов компилятора (обычно "gc")
- CGO_ENABLED: фактическое значение переменной среды CGO_ENABLED
- CGO_CFLAGS: фактическое значение переменной среды CGO_CFLAGS
- CGO_CPPFLAGS: фактическое значение переменной среды CGO_CPPFLAGS
- CGO_CXXFLAGS: фактическое значение переменной среды CGO_CXXFLAGS
- CGO_LDFLAGS: фактическое значение переменной среды CGO_LDFLAGS
- DefaultGODEBUG: фактические параметры GODEBUG
- GOARCH: целевая архитектура
- GOAMD64/GOARM/GO386/etc: уровень возможностей архитектуры для GOARCH
- GOOS: целевая операционная система
- GOFIPS140: зафиксированная версия модуля FIPS 140-3, если есть
- vcs: система контроля версий дерева исходного кода, в котором выполнялась сборка
- vcs.revision: идентификатор ревизии текущего коммита или рабочей копии
- vcs.time: время изменения, связанное с vcs.revision, в формате RFC3339
- vcs.modified: true или false, указывающее, были ли локальные изменения в дереве исходного кода
type BuildSetting struct {
// Key and Value describe the build setting.
// Key must not contain an equals sign, space, tab, or newline.
Key string `json:",omitempty"`
// Value must not contain newlines ('\n').
Value string `json:",omitempty"`
}
type CrashOptions 1.23
CrashOptions предоставляет параметры, управляющие форматированием сообщения о фатальном сбое.
type CrashOptions struct {
}
type GCStats 1.1
GCStats собирает сведения о недавних сборках мусора.
type GCStats struct {
LastGC time.Time // time of last collection
NumGC int64 // number of garbage collections
PauseTotal time.Duration // total pause for all collections
Pause []time.Duration // pause history, most recent first
PauseEnd []time.Time // pause end times history, most recent first; added in Go 1.4
PauseQuantiles []time.Duration
}
type Module 1.12
Module описывает отдельный модуль, включенный в сборку.
type Module struct {
Path string `json:",omitempty"` // module path
Version string `json:",omitempty"` // module version
Sum string `json:",omitempty"` // checksum
Replace *Module `json:",omitempty"` // replaced by this module
}
© Google, Inc.
Licensed under the Creative Commons Attribution License 3.0.
http://golang.org/pkg/runtime/debug/
