gops

Print all go processes running locally

$ gops

$ gops [pid]

$ gops tree

$ gops stack [pid|addr]

$ gops memstats [pid|addr]

gops <command> [options] [arguments]

Common invocations:
gops <pid>
gops <addr>
gops agents
gops stack <pid|addr>
gops cpu <pid|addr> [-o <file>] [-t <duration>]

<pid>
    The operating system Process ID of the target Go application. gops will attempt to connect to the agent running within this process.

<addr>
    The network address (e.g., 127.0.0.1:port) where the gops agent of the target Go application is listening. Useful for remote diagnostics or when PID is unknown/unstable.

agents
    Lists all gops agents currently running and discoverable on the local host. This helps in identifying the PIDs and addresses of instrumented Go processes.

stack
    Dumps the stack traces of all active goroutines in the target Go application. Critical for debugging deadlocks, long-running operations, and understanding concurrency state.

memstats
    Displays detailed Go runtime memory statistics, including heap usage, garbage collection information, and allocated objects. Useful for memory leak detection and profiling.

cpu
    Starts CPU profiling for a specified duration and saves the profile data. The output is typically consumed by go tool pprof for visualization and analysis.

heap
    Dumps the current heap profile of the Go application, showing memory allocations. Also consumable by go tool pprof.

goroutine
    Dumps the goroutine profile, showing where goroutines are blocked or active. Similar to stack but often used with pprof for visualization.

block
    Dumps the blocking profile, indicating where goroutines are blocked on synchronization primitives (e.g., mutexes, channels).

mutex
    Dumps the mutex contention profile, showing where mutexes are being heavily contended.

trace
    Starts an execution trace for a specified duration, providing detailed timeline information of goroutine events, system calls, and more. Analyzed with go tool trace.

stats
    Continuously prints Go runtime statistics at regular intervals, providing a live view of performance metrics like goroutine count, GC pauses, and memory.
Common options: -p <duration> (period for stats).

gc
    Forces an immediate garbage collection cycle in the target Go application.

version
    Prints the version of the gops tool.

-o <file>
    Common option used with profiling commands (e.g., cpu, heap) to specify the output file path for the generated profile data.

gops is a powerful command-line tool designed specifically for inspecting and diagnosing running Go processes. Unlike generic system utilities such as ps or top, gops provides deep insight into the Go runtime, leveraging an embedded agent within the target Go application. This allows it to expose rich, Go-specific metrics and diagnostic data, including goroutine stack traces, heap profiles, CPU profiles, runtime statistics (like GC pause times and goroutine counts), and more.

It's an indispensable tool for Go developers to pinpoint and troubleshoot issues such as memory leaks, CPU bottlenecks, goroutine deadlocks, and general performance regressions in both development and production environments. For gops to function, the target Go application must be instrumented by importing and initializing the gops agent within its codebase.

The primary limitation of gops is that it requires the target Go application to be explicitly instrumented with the gops agent. It cannot inspect arbitrary Go processes or non-Go applications.

The agent exposes sensitive runtime data, so proper security measures (e.g., firewall rules, network segmentation) should be in place, especially in production environments, to restrict access to the gops agent's listening port.

Profiling commands can introduce a performance overhead on the target application, which should be considered during live debugging.

gops is not a standard Linux command; it must be installed separately via the Go toolchain.

gops is not pre-installed on most Linux systems. It can be installed using the Go toolchain:

go install github.com/google/gops@latest

Ensure your $GOBIN (or $GOPATH/bin) is in your system's $PATH to run gops directly.

For a Go application to be diagnosable by gops, it must integrate the gops agent. This is typically done by importing the agent package and calling agent.Listen() early in the application's startup code:

import (
"log"
"github.com/google/gops/agent"
)

func main() {
if err := agent.Listen(agent.Options{}); err != nil {
log.Fatalf("gops agent Listen failed: %v", err)
}
// ... rest of your application code
}

The agent.Listen() call starts a goroutine that listens for diagnostic requests on a local socket or network port.

gops was developed by Google engineers as part of the broader Go ecosystem to address the need for a more convenient and lightweight way to diagnose Go applications in real-time, especially in production environments. While Go's built-in pprof package provides robust profiling capabilities, it often requires exposing HTTP endpoints or managing signal handlers. gops streamlined this process by providing a unified command-line interface that communicates with a small, embeddable agent.

Its development focused on making Go runtime diagnostics more accessible, allowing developers to quickly pull various profiles and statistics without restarting applications or complex setup. It has become a widely adopted tool within the Go community for debugging performance and concurrency issues.

ps(1), top(1), strace(1), perf(1), go(1), go tool pprof