Asset 31Asset 32
Navigate back to the homepage

Go Runtime Environment Variables

Sebastian Ojeda
October 27th, 2019 · 3 min read

This post will be a rundown of all the Go runtime environment variables, what they mean, and what they are used for.

The following variables are available in the latest release of Go, which at the time of writing is 1.13.

GOGC

GOGC refers to a target percentage at which to run the garbage collector relative to the amount of data left from the latest run. For example, a GOGC variable set to 100 (the default) means that the garbage collector will run when the heap roughly doubles in size. In other words, a higher percentage means garbage will be collected less often, and a lower percentage means it will collect garbage more often. If you set the variable to off, then garbage collection will be turned off entirely.

GOMAXPROCS

GOMAXPROCS controls the number of OS threads that can used to execute Go simultaneously. It defaults to the number of CPUs available to the program at runtime.

GORACE

GORACE sets the options for the Go race detector and should be in key=value format, with multiple pairs separated by a single space. The options are:

  • log_path: The race detector will write a report to stdout be default. This can also be set to either stderr or a path. If a path is specified, it will write the report to a file named log_path.pid at the path specifed.
  • exitcode: The status code to use when exiting after a detected race. The default is 66.
  • strip_path_prefix: This strips the given prefix from reported file paths. The default prefix is the empty string "".
  • history_size: The per-goroutine memory access history is 32K * 2**history_size elements. Increasing this value can avoid a “failed to restore the stack” error in reports, at the cost of increased memory usage. The default is 1.
  • halt_on_error: Controls whether the program exits after the first data race is detected. The default is 0.

GOTRACEBACK

GOTRACEBACK will control the amount of log information given when a Go program fails. The available options are:

  • single (the default): Prints a stack trace of the current goroutine, if available. Otherwise, it will give a stacktrace of all goroutines.
  • none: Omits goroutine stack traces.
  • all: Adds all user-defined goroutine stack traces.
  • system: Similar to all but it also includes stack traces for internal goroutines as well as frames for runtime functions.
  • crash: Similar to system but it will also force a seg fault or access violation, if permitted by the operating system. This is useful for debugging when you want a “snapshot” of the RAM at the time the program panics.

GOARCH, GOOS

The GOARCH and GOOS variables are used when building a Go program. GOARCH is the target architecture and GOOS is the target operating system. Valid combintations are as follows:

1$GOOS $GOARCH
2aix ppc64
3android 386
4android amd64
5android arm
6android arm64
7darwin 386
8darwin amd64
9darwin arm
10darwin arm64
11dragonfly amd64
12freebsd 386
13freebsd amd64
14freebsd arm
15illumos amd64
16js wasm
17linux 386
18linux amd64
19linux arm
20linux arm64
21linux ppc64
22linux ppc64le
23linux mips
24linux mipsle
25linux mips64
26linux mips64le
27linux s390x
28netbsd 386
29netbsd amd64
30netbsd arm
31openbsd 386
32openbsd amd64
33openbsd arm
34openbsd arm64
35plan9 386
36plan9 amd64
37plan9 arm
38solaris amd64
39windows 386
40windows amd64

This is useful when you are compiling your Go programs for other operating systems. For example, if I wanted a package to target macOS amd64 machines I could run

1GOOS=darmin GOARCH=amd64 go build packageName

GOPATH, GOROOT

GOPATH specifies the location of your workspace. It defaults to a directory named go inside your home directory. This is separate from the install location of Go. Typically, a workspace is comprised of two directories at its root, src, which contains Go source files, and bin, which contains compiled Go executables. Binaries are downloaded into the bin directory.

The GOROOT variable points to the installation of Go and should not be set by the user as it is already embedded in the go toolchain.

GODEBUG

The GODEBUG variable controls debugging variables within the runtime. It is defined using key=value pairs and has many, many options so I decided to quote the Go docs on this one:

From https://golang.org/pkg/runtime/ the options are:

1allocfreetrace: setting allocfreetrace=1 causes every allocation to be
2profiled and a stack trace printed on each object's allocation and free.
3
4clobberfree: setting clobberfree=1 causes the garbage collector to
5clobber the memory content of an object with bad content when it frees
6the object.
7
8cgocheck: setting cgocheck=0 disables all checks for packages
9using cgo to incorrectly pass Go pointers to non-Go code.
10Setting cgocheck=1 (the default) enables relatively cheap
11checks that may miss some errors. Setting cgocheck=2 enables
12expensive checks that should not miss any errors, but will
13cause your program to run slower.
14
15efence: setting efence=1 causes the allocator to run in a mode
16where each object is allocated on a unique page and addresses are
17never recycled.
18
19gccheckmark: setting gccheckmark=1 enables verification of the
20garbage collector's concurrent mark phase by performing a
21second mark pass while the world is stopped. If the second
22pass finds a reachable object that was not found by concurrent
23mark, the garbage collector will panic.
24
25gcpacertrace: setting gcpacertrace=1 causes the garbage collector to
26print information about the internal state of the concurrent pacer.
27
28gcshrinkstackoff: setting gcshrinkstackoff=1 disables moving goroutines
29onto smaller stacks. In this mode, a goroutine's stack can only grow.
30
31gcstoptheworld: setting gcstoptheworld=1 disables concurrent garbage collection,
32making every garbage collection a stop-the-world event. Setting gcstoptheworld=2
33also disables concurrent sweeping after the garbage collection finishes.
34
35gctrace: setting gctrace=1 causes the garbage collector to emit a single line to standard
36error at each collection, summarizing the amount of memory collected and the
37length of the pause. The format of this line is subject to change.
38Currently, it is:
39 gc # @#s #%: #+#+# ms clock, #+#/#/#+# ms cpu, #->#-># MB, # MB goal, # P
40where the fields are as follows:
41 gc # the GC number, incremented at each GC
42 @#s time in seconds since program start
43 #% percentage of time spent in GC since program start
44 #+...+# wall-clock/CPU times for the phases of the GC
45 #->#-># MB heap size at GC start, at GC end, and live heap
46 # MB goal goal heap size
47 # P number of processors used
48The phases are stop-the-world (STW) sweep termination, concurrent
49mark and scan, and STW mark termination. The CPU times
50for mark/scan are broken down in to assist time (GC performed in
51line with allocation), background GC time, and idle GC time.
52If the line ends with "(forced)", this GC was forced by a
53runtime.GC() call.
54
55Setting gctrace to any value > 0 also causes the garbage collector
56to emit a summary when memory is released back to the system.
57This process of returning memory to the system is called scavenging.
58The format of this summary is subject to change.
59Currently it is:
60 scvg#: # MB released printed only if non-zero
61 scvg#: inuse: # idle: # sys: # released: # consumed: # (MB)
62where the fields are as follows:
63 scvg# the scavenge cycle number, incremented at each scavenge
64 inuse: # MB used or partially used spans
65 idle: # MB spans pending scavenging
66 sys: # MB mapped from the system
67 released: # MB released to the system
68 consumed: # MB allocated from the system
69
70madvdontneed: setting madvdontneed=1 will use MADV_DONTNEED
71instead of MADV_FREE on Linux when returning memory to the
72kernel. This is less efficient, but causes RSS numbers to drop
73more quickly.
74
75memprofilerate: setting memprofilerate=X will update the value of runtime.MemProfileRate.
76When set to 0 memory profiling is disabled. Refer to the description of
77MemProfileRate for the default value.
78
79invalidptr: defaults to invalidptr=1, causing the garbage collector and stack
80copier to crash the program if an invalid pointer value (for example, 1)
81is found in a pointer-typed location. Setting invalidptr=0 disables this check.
82This should only be used as a temporary workaround to diagnose buggy code.
83The real fix is to not store integers in pointer-typed locations.
84
85sbrk: setting sbrk=1 replaces the memory allocator and garbage collector
86with a trivial allocator that obtains memory from the operating system and
87never reclaims any memory.
88
89scavenge: scavenge=1 enables debugging mode of heap scavenger.
90
91scheddetail: setting schedtrace=X and scheddetail=1 causes the scheduler to emit
92detailed multiline info every X milliseconds, describing state of the scheduler,
93processors, threads and goroutines.
94
95schedtrace: setting schedtrace=X causes the scheduler to emit a single line to standard
96error every X milliseconds, summarizing the scheduler state.
97
98tracebackancestors: setting tracebackancestors=N extends tracebacks with the stacks at
99which goroutines were created, where N limits the number of ancestor goroutines to
100report. This also extends the information returned by runtime.Stack. Ancestor's goroutine
101IDs will refer to the ID of the goroutine at the time of creation; it's possible for this
102ID to be reused for another goroutine. Setting N to 0 will report no ancestry information.

Miscellaneous

Finally, here is a quick list of other general environemnt variables gathered from the Go docs:

  • GCCGO: The gccgo command to run for ‘go build -compiler=gccgo’.
  • GOBIN: The directory where ‘go install’ will install a command.
  • GOCACHE: The directory where the go command will store cached information for reuse in future builds.
  • GOENV: The location of the Go environment configuration file. Cannot be set using ‘go env -w’.
  • GOFLAGS: A space-separated list of -flag=value settings to apply to go commands by default, when the given flag is known by the current command. Each entry must be a standalone flag. Because the entries are space-separated, flag values must not contain spaces. Flags listed on the command line are applied after this list and therefore override it.
  • GOPROXY: URL of Go module proxy.
  • GOPRIVATE, GONOPROXY, GONOSUMDB: Comma-separated list of glob patterns (in the syntax of Go’s path.Match) of module path prefixes that should always be fetched directly or that should not be compared against the checksum database.
  • GOSUMDB: The name of checksum database to use and optionally its public key and URL.
  • GOTMPDIR: The directory where the go command will write temporary source files, packages, and binaries.

Hopefully this is helpful to those who were curious about all the variables available to the Go runtime. If you are interested in learning more, I recommend heading over to the Go docs for more information.

More articles from Fullstack Go

Dockerize your Go Microservice

My favorite language and the world's most popular containerization platform come together in the most beautiful way.

September 30th, 2019 · 2 min read

Prefix Trees in Go

A prefix tree (or trie) data structure is great for text searching. Let's try implementing one in Go.

September 25th, 2019 · 2 min read
© 2019 Fullstack Go
Link to $https://twitter.com/fullstack_goLink to $https://github.com/fullstackgo