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 // A negative percentage disables garbage collection. 91 func SetGCPercent(percent int) int { 92 return int(setGCPercent(int32(percent))) 93 } 94 95 // FreeOSMemory forces a garbage collection followed by an 96 // attempt to return as much memory to the operating system 97 // as possible. (Even if this is not called, the runtime gradually 98 // returns memory to the operating system in a background task.) 99 func FreeOSMemory() { 100 freeOSMemory() 101 } 102 103 // SetMaxStack sets the maximum amount of memory that 104 // can be used by a single goroutine stack. 105 // If any goroutine exceeds this limit while growing its stack, 106 // the program crashes. 107 // SetMaxStack returns the previous setting. 108 // The initial setting is 1 GB on 64-bit systems, 250 MB on 32-bit systems. 109 // There may be a system-imposed maximum stack limit regardless 110 // of the value provided to SetMaxStack. 111 // 112 // SetMaxStack is useful mainly for limiting the damage done by 113 // goroutines that enter an infinite recursion. It only limits future 114 // stack growth. 115 func SetMaxStack(bytes int) int { 116 return setMaxStack(bytes) 117 } 118 119 // SetMaxThreads sets the maximum number of operating system 120 // threads that the Go program can use. If it attempts to use more than 121 // this many, the program crashes. 122 // SetMaxThreads returns the previous setting. 123 // The initial setting is 10,000 threads. 124 // 125 // The limit controls the number of operating system threads, not the number 126 // of goroutines. A Go program creates a new thread only when a goroutine 127 // is ready to run but all the existing threads are blocked in system calls, cgo calls, 128 // or are locked to other goroutines due to use of runtime.LockOSThread. 129 // 130 // SetMaxThreads is useful mainly for limiting the damage done by 131 // programs that create an unbounded number of threads. The idea is 132 // to take down the program before it takes down the operating system. 133 func SetMaxThreads(threads int) int { 134 return setMaxThreads(threads) 135 } 136 137 // SetPanicOnFault controls the runtime's behavior when a program faults 138 // at an unexpected (non-nil) address. Such faults are typically caused by 139 // bugs such as runtime memory corruption, so the default response is to crash 140 // the program. Programs working with memory-mapped files or unsafe 141 // manipulation of memory may cause faults at non-nil addresses in less 142 // dramatic situations; SetPanicOnFault allows such programs to request 143 // that the runtime trigger only a panic, not a crash. 144 // The runtime.Error that the runtime panics with may have an additional method: 145 // Addr() uintptr 146 // If that method exists, it returns the memory address which triggered the fault. 147 // The results of Addr are best-effort and the veracity of the result 148 // may depend on the platform. 149 // SetPanicOnFault applies only to the current goroutine. 150 // It returns the previous setting. 151 func SetPanicOnFault(enabled bool) bool { 152 return setPanicOnFault(enabled) 153 } 154 155 // WriteHeapDump writes a description of the heap and the objects in 156 // it to the given file descriptor. 157 // 158 // WriteHeapDump suspends the execution of all goroutines until the heap 159 // dump is completely written. Thus, the file descriptor must not be 160 // connected to a pipe or socket whose other end is in the same Go 161 // process; instead, use a temporary file or network socket. 162 // 163 // The heap dump format is defined at https://golang.org/s/go15heapdump. 164 func WriteHeapDump(fd uintptr) 165 166 // SetTraceback sets the amount of detail printed by the runtime in 167 // the traceback it prints before exiting due to an unrecovered panic 168 // or an internal runtime error. 169 // The level argument takes the same values as the GOTRACEBACK 170 // environment variable. For example, SetTraceback("all") ensure 171 // that the program prints all goroutines when it crashes. 172 // See the package runtime documentation for details. 173 // If SetTraceback is called with a level lower than that of the 174 // environment variable, the call is ignored. 175 func SetTraceback(level string) 176