1 // Copyright 2013 The Go Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style 3 // license that can be found in the LICENSE file. 4 5 package debug 6 7 import ( 8 "runtime" 9 "sort" 10 "time" 11 ) 12 13 // GCStats collect information about recent garbage collections. 14 type GCStats struct { 15 LastGC time.Time // time of last collection 16 NumGC int64 // number of garbage collections 17 PauseTotal time.Duration // total pause for all collections 18 Pause []time.Duration // pause history, most recent first 19 PauseEnd []time.Time // pause end times history, most recent first 20 PauseQuantiles []time.Duration 21 } 22 23 // ReadGCStats reads statistics about garbage collection into stats. 24 // The number of entries in the pause history is system-dependent; 25 // stats.Pause slice will be reused if large enough, reallocated otherwise. 26 // ReadGCStats may use the full capacity of the stats.Pause slice. 27 // If stats.PauseQuantiles is non-empty, ReadGCStats fills it with quantiles 28 // summarizing the distribution of pause time. For example, if 29 // len(stats.PauseQuantiles) is 5, it will be filled with the minimum, 30 // 25%, 50%, 75%, and maximum pause times. 31 func ReadGCStats(stats *GCStats) { 32 // Create a buffer with space for at least two copies of the 33 // pause history tracked by the runtime. One will be returned 34 // to the caller and the other will be used as transfer buffer 35 // for end times history and as a temporary buffer for 36 // computing quantiles. 37 const maxPause = len(((*runtime.MemStats)(nil)).PauseNs) 38 if cap(stats.Pause) < 2*maxPause+3 { 39 stats.Pause = make([]time.Duration, 2*maxPause+3) 40 } 41 42 // readGCStats fills in the pause and end times histories (up to 43 // maxPause entries) and then three more: Unix ns time of last GC, 44 // number of GC, and total pause time in nanoseconds. Here we 45 // depend on the fact that time.Duration's native unit is 46 // nanoseconds, so the pauses and the total pause time do not need 47 // any conversion. 48 readGCStats(&stats.Pause) 49 n := len(stats.Pause) - 3 50 stats.LastGC = time.Unix(0, int64(stats.Pause[n])) 51 stats.NumGC = int64(stats.Pause[n+1]) 52 stats.PauseTotal = stats.Pause[n+2] 53 n /= 2 // buffer holds pauses and end times 54 stats.Pause = stats.Pause[:n] 55 56 if cap(stats.PauseEnd) < maxPause { 57 stats.PauseEnd = make([]time.Time, 0, maxPause) 58 } 59 stats.PauseEnd = stats.PauseEnd[:0] 60 for _, ns := range stats.Pause[n : n+n] { 61 stats.PauseEnd = append(stats.PauseEnd, time.Unix(0, int64(ns))) 62 } 63 64 if len(stats.PauseQuantiles) > 0 { 65 if n == 0 { 66 for i := range stats.PauseQuantiles { 67 stats.PauseQuantiles[i] = 0 68 } 69 } else { 70 // There's room for a second copy of the data in stats.Pause. 71 // See the allocation at the top of the function. 72 sorted := stats.Pause[n : n+n] 73 copy(sorted, stats.Pause) 74 sort.Slice(sorted, func(i, j int) bool { return sorted[i] < sorted[j] }) 75 nq := len(stats.PauseQuantiles) - 1 76 for i := 0; i < nq; i++ { 77 stats.PauseQuantiles[i] = sorted[len(sorted)*i/nq] 78 } 79 stats.PauseQuantiles[nq] = sorted[len(sorted)-1] 80 } 81 } 82 } 83 84 // SetGCPercent sets the garbage collection target percentage: 85 // a collection is triggered when the ratio of freshly allocated data 86 // to live data remaining after the previous collection reaches this percentage. 87 // SetGCPercent returns the previous setting. 88 // The initial setting is the value of the GOGC environment variable 89 // at startup, or 100 if the variable is not set. 90 // This setting may be effectively reduced in order to maintain a memory 91 // limit. 92 // A negative percentage effectively disables garbage collection, unless 93 // the memory limit is reached. 94 // See SetMemoryLimit for more details. 95 func SetGCPercent(percent int) int { 96 return int(setGCPercent(int32(percent))) 97 } 98 99 // FreeOSMemory forces a garbage collection followed by an 100 // attempt to return as much memory to the operating system 101 // as possible. (Even if this is not called, the runtime gradually 102 // returns memory to the operating system in a background task.) 103 func FreeOSMemory() { 104 freeOSMemory() 105 } 106 107 // SetMaxStack sets the maximum amount of memory that 108 // can be used by a single goroutine stack. 109 // If any goroutine exceeds this limit while growing its stack, 110 // the program crashes. 111 // SetMaxStack returns the previous setting. 112 // The initial setting is 1 GB on 64-bit systems, 250 MB on 32-bit systems. 113 // There may be a system-imposed maximum stack limit regardless 114 // of the value provided to SetMaxStack. 115 // 116 // SetMaxStack is useful mainly for limiting the damage done by 117 // goroutines that enter an infinite recursion. It only limits future 118 // stack growth. 119 func SetMaxStack(bytes int) int { 120 return setMaxStack(bytes) 121 } 122 123 // SetMaxThreads sets the maximum number of operating system 124 // threads that the Go program can use. If it attempts to use more than 125 // this many, the program crashes. 126 // SetMaxThreads returns the previous setting. 127 // The initial setting is 10,000 threads. 128 // 129 // The limit controls the number of operating system threads, not the number 130 // of goroutines. A Go program creates a new thread only when a goroutine 131 // is ready to run but all the existing threads are blocked in system calls, cgo calls, 132 // or are locked to other goroutines due to use of runtime.LockOSThread. 133 // 134 // SetMaxThreads is useful mainly for limiting the damage done by 135 // programs that create an unbounded number of threads. The idea is 136 // to take down the program before it takes down the operating system. 137 func SetMaxThreads(threads int) int { 138 return setMaxThreads(threads) 139 } 140 141 // SetPanicOnFault controls the runtime's behavior when a program faults 142 // at an unexpected (non-nil) address. Such faults are typically caused by 143 // bugs such as runtime memory corruption, so the default response is to crash 144 // the program. Programs working with memory-mapped files or unsafe 145 // manipulation of memory may cause faults at non-nil addresses in less 146 // dramatic situations; SetPanicOnFault allows such programs to request 147 // that the runtime trigger only a panic, not a crash. 148 // The runtime.Error that the runtime panics with may have an additional method: 149 // 150 // Addr() uintptr 151 // 152 // If that method exists, it returns the memory address which triggered the fault. 153 // The results of Addr are best-effort and the veracity of the result 154 // may depend on the platform. 155 // SetPanicOnFault applies only to the current goroutine. 156 // It returns the previous setting. 157 func SetPanicOnFault(enabled bool) bool { 158 return setPanicOnFault(enabled) 159 } 160 161 // WriteHeapDump writes a description of the heap and the objects in 162 // it to the given file descriptor. 163 // 164 // WriteHeapDump suspends the execution of all goroutines until the heap 165 // dump is completely written. Thus, the file descriptor must not be 166 // connected to a pipe or socket whose other end is in the same Go 167 // process; instead, use a temporary file or network socket. 168 // 169 // The heap dump format is defined at https://golang.org/s/go15heapdump. 170 func WriteHeapDump(fd uintptr) 171 172 // SetTraceback sets the amount of detail printed by the runtime in 173 // the traceback it prints before exiting due to an unrecovered panic 174 // or an internal runtime error. 175 // The level argument takes the same values as the GOTRACEBACK 176 // environment variable. For example, SetTraceback("all") ensure 177 // that the program prints all goroutines when it crashes. 178 // See the package runtime documentation for details. 179 // If SetTraceback is called with a level lower than that of the 180 // environment variable, the call is ignored. 181 func SetTraceback(level string) 182 183 // SetMemoryLimit provides the runtime with a soft memory limit. 184 // 185 // The runtime undertakes several processes to try to respect this 186 // memory limit, including adjustments to the frequency of garbage 187 // collections and returning memory to the underlying system more 188 // aggressively. This limit will be respected even if GOGC=off (or, 189 // if SetGCPercent(-1) is executed). 190 // 191 // The input limit is provided as bytes, and includes all memory 192 // mapped, managed, and not released by the Go runtime. Notably, it 193 // does not account for space used by the Go binary and memory 194 // external to Go, such as memory managed by the underlying system 195 // on behalf of the process, or memory managed by non-Go code inside 196 // the same process. Examples of excluded memory sources include: OS 197 // kernel memory held on behalf of the process, memory allocated by 198 // C code, and memory mapped by syscall.Mmap (because it is not 199 // managed by the Go runtime). 200 // 201 // More specifically, the following expression accurately reflects 202 // the value the runtime attempts to maintain as the limit: 203 // 204 // runtime.MemStats.Sys - runtime.MemStats.HeapReleased 205 // 206 // or in terms of the runtime/metrics package: 207 // 208 // /memory/classes/total:bytes - /memory/classes/heap/released:bytes 209 // 210 // A zero limit or a limit that's lower than the amount of memory 211 // used by the Go runtime may cause the garbage collector to run 212 // nearly continuously. However, the application may still make 213 // progress. 214 // 215 // The memory limit is always respected by the Go runtime, so to 216 // effectively disable this behavior, set the limit very high. 217 // [math.MaxInt64] is the canonical value for disabling the limit, 218 // but values much greater than the available memory on the underlying 219 // system work just as well. 220 // 221 // See https://go.dev/doc/gc-guide for a detailed guide explaining 222 // the soft memory limit in more detail, as well as a variety of common 223 // use-cases and scenarios. 224 // 225 // The initial setting is math.MaxInt64 unless the GOMEMLIMIT 226 // environment variable is set, in which case it provides the initial 227 // setting. GOMEMLIMIT is a numeric value in bytes with an optional 228 // unit suffix. The supported suffixes include B, KiB, MiB, GiB, and 229 // TiB. These suffixes represent quantities of bytes as defined by 230 // the IEC 80000-13 standard. That is, they are based on powers of 231 // two: KiB means 2^10 bytes, MiB means 2^20 bytes, and so on. 232 // 233 // SetMemoryLimit returns the previously set memory limit. 234 // A negative input does not adjust the limit, and allows for 235 // retrieval of the currently set memory limit. 236 func SetMemoryLimit(limit int64) int64 { 237 return setMemoryLimit(limit) 238 } 239