Пакет debug

• import "runtime/debug"
• Обзор
• Индекс
• Примеры

Обзор

Пакет debug содержит средства для отладки программ во время их выполнения.

Индекс

• func FreeOSMemory()
• func PrintStack()
• func ReadGCStats(stats *GCStats)
• func SetCrashOutput(f *os.File, opts CrashOptions) error
• func SetGCPercent(percent int) int
• func SetMaxStack(bytes int) int
• func SetMaxThreads(threads int) int
• func SetMemoryLimit(limit int64) int64
• func SetPanicOnFault(enabled bool) bool
• func SetTraceback(level string)
• func Stack() []byte
• func WriteHeapDump(fd uintptr)
• тип BuildInfo
• func ParseBuildInfo(data string) (bi *BuildInfo, err error)
• func ReadBuildInfo() (info *BuildInfo, ok bool)
• func (bi *BuildInfo) String() string
• тип BuildSetting
• тип CrashOptions
• тип GCStats
• тип Module

Файлы пакета

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.

Пример (Монитор)

ПримерSetCrashOutput_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")
    cmd.Env = append(os.Environ(), 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 позволяет таким программам запросить, чтобы среда выполнения запускала только панику, а не аварийное завершение.

Addr() uintptr

Если этот метод существует, он возвращает адрес памяти, вызвавший ошибку. Результаты Addr – это наилучшие усилия, и достоверность результата может зависеть от платформы. SetPanicOnFault применяется только к текущей горутине. Он возвращает предыдущее значение.

func SetTraceback 1.6

func SetTraceback(level string)

SetTraceback устанавливает степень детализации, выводимой средой выполнения в трассировке стека, которую она выводит перед завершением из-за необработанной паники или внутренней ошибки среды выполнения. Аргумент уровня принимает те же значения, что и переменная среды 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.

тип 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 // 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

    // Main describes the module that contains the main package for the binary.
    Main Module

    // Deps describes all the dependency modules, both direct and indirect,
    // that contributed packages to the build of this binary.
    Deps []*Module

    // Settings describes the build settings used to build the binary.
    Settings []BuildSetting // Go 1.18
}

func ParseBuildInfo 1.18

func ParseBuildInfo(data string) (bi *BuildInfo, err error)

func ReadBuildInfo 1.12

func ReadBuildInfo() (info *BuildInfo, ok bool)

ReadBuildInfo возвращает информацию о сборке, встроенную в исполняемый файл. Информация доступна только в бинарниках, собранных с поддержкой модулей.

func (*BuildInfo) String 1.18

func (bi *BuildInfo) String() string

тип 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
• GOARCH: целевая архитектура
• GOAMD64/GOARM/GO386/etc: уровень архитектурных особенностей для GOARCH
• GOOS: целевая операционная система
• 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.
    // Value must not contain newlines ('\n').
    Key, Value string
}

тип CrashOptions 1.23

CrashOptions предоставляет параметры, которые контролируют форматирование сообщения об ошибке при аварийном завершении.

type CrashOptions struct {
}

тип 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
}

тип Module 1.12

Module описывает отдельный модуль, включённый в сборку.

type Module struct {
    Path    string  // module path
    Version string  // module version
    Sum     string  // checksum
    Replace *Module // replaced by this module
}