gops: inspecting Go processes from the command line

Listing and diagnosing Go processes without code changes

gops is a command-line tool from Google that lists running Go processes and reports their stack traces, memory state, and CPU usage. It solves a central problem in production Go: understanding what a process is doing without instrumenting the code, restarting the binary, or attaching a debugger. Running `gops` with no arguments prints all Go processes on your system, showing their PID, parent PID, program name, Go version and binary location. Processes that have the diagnostics agent listening show a `*` marker next to the PID. When you need more detail, `gops <pid>` reports memory usage as a percentage of total system memory, instantaneous and sampled CPU usage, username, and the process's command line with arguments. It also lists active network connections for the process, showing local and remote addresses with their state. The tool operates in two modes: local mode, which works on any process but requires gops and the target binary to run as the same user, and remote mode, which requires the target to have started the diagnostics agent listening on a known host:port.

Installing gops and adding the diagnostics agent

Installation is straightforward. The simplest path is to use `go install` to add the gops binary to your Go toolchain:

go install github.com/google/gops@latest

After this runs, `gops` is available in your `GOBIN` directory. To add remote diagnostics to your own Go binary, import the gops agent and call it at startup. This requires a small code addition but unlocks the full range of diagnostic commands. Create a minimal example file with this agent setup:

package main

import (
	"log"
	"time"

	"github.com/google/gops/agent"
)

func main() {
	if err := agent.Listen(agent.Options{}); err != nil {
		log.Fatal(err)
	}
	time.Sleep(time.Hour)
}

Build and run this binary, then in another terminal run `gops` to see it listed with a `*` marker. From there, `gops <pid>` and all diagnostic commands become available. If you cannot modify your target binary, gops still works in local mode without any code changes, as long as you run the gops command as the same user that started the target process.

Accessing memory and garbage collection state

gops reports detailed memory statistics without interrupting the process. `gops memstats <pid>` prints the full output of Go's memory allocator, including heap size, allocated and free bytes, and garbage collection pause times. For garbage collection control, `gops gc <pid>` forces an immediate garbage collection cycle and blocks until it completes. `gops setgc <pid> 10` sets the garbage collection target to 10 percent of heap memory; `gops setgc <pid> off` disables the garbage collector entirely. This last command is rarely useful in production but can help isolate performance problems caused by GC pauses. CPU usage is also straightforward: `gops <pid>` shows instantaneous CPU usage, and `gops <pid> 2s` samples CPU usage over a 2-second window, formatted as expected by Go's time.ParseDuration function.

Profiling and analyzing goroutine stacks

Stack traces are the most common diagnostic need. `gops stack <pid>` prints the current call stack of all running goroutines, the same data you would get from a goroutine dump. This works with or without the agent, as long as gops runs as the same user. For deeper analysis, gops shells out to Go's built-in pprof tool. `gops pprof-cpu <pid>` captures a CPU profile for 30 seconds and opens an interactive pprof session where you can inspect hotspots by function, source line, or caller. `gops pprof-heap <pid>` does the same for heap allocations, showing which code paths are allocating memory. `gops trace <pid>` starts the Go runtime execution tracer for 5 seconds, captures the trace file, and opens it in the Chrome trace viewer. For viewing the process tree across your entire system, `gops tree` displays all running Go processes in a hierarchy, making it easy to understand parent-child relationships and spot unexpected processes.

Local mode requires user parity, remote mode needs the agent

The main constraint with gops is its dependence on user identity. Local mode, which works on any Go binary without code changes, requires the gops command and the target process to run as the same user. This works for development and testing but breaks when you need to inspect system services running as root or under a different service account. Remote mode solves this by requiring the target process to start the diagnostics agent with `agent.Listen(agent.Options{})`. The agent listens on localhost by default and allows gops to connect over the network without user matching. If you cannot modify your binary to add the agent and need to inspect a process running as a different user, you must run gops as that user or with administrator access. The README does not document how to configure the agent to listen on a remote address or change its port, only that local mode is the default and `GOPS_CONFIG_DIR` can set the configuration directory.

Comparing gops to continuous profiling and source-level debugging

gops fills a specific niche: lightweight, ad-hoc inspection of running processes. It differs from continuous profiling tools like Prometheus, which collect metrics over time and alert on thresholds. Prometheus is designed for sustained monitoring of many processes and requires instrumenting your code with a metrics library. gops needs no instrumentation in local mode and works immediately against any Go process. It also differs from source-level debuggers like GDB or the Go debugger, which let you set breakpoints and step through code but require stopping or attaching to the process. gops operates in the background without interruption. For the decision of which tool to reach for first, gops is the right choice when you notice a running process using unexpected CPU or memory and need to understand why right now. Prometheus is the right choice if you need to track these metrics across dozens of processes over time.

Go version reporting and statistics

`gops version <pid>` reports the exact Go version used to build the target binary, including the commit hash and build date for development versions. This is useful when you suspect a version-specific bug or when you need to verify that the right binary is running. `gops stats <pid>` prints runtime statistics such as the number of currently running goroutines and the value of GOMAXPROCS, the number of operating system threads Go will use for parallel execution. These are lightweight queries useful for spotting obvious problems: a process with ten thousand goroutines and GOMAXPROCS=1 is likely misconfigured, while a process with unexpected goroutine counts might have a goroutine leak.

Editorial conclusion

gops is essential for Go operators who need to understand process behavior in production. It belongs in every Go operator's toolkit, especially for diagnosing performance issues and inspecting running processes without restarts. Start with the basic `gops` listing, then run `gops <pid>` on suspect processes to examine CPU and memory usage, stack traces and garbage collection behavior. Verify that your target processes either start the diagnostics agent or run as the same user as the gops binary, since local mode works only when both run as the same user.

Frequently asked questions

Official sources

1. google/gops on GitHub
2. Issues
3. License: BSD-3-Clause
4. README
5. Releases