LinuxCommandLibrary

gops

List running Go processes

TLDR

Print all go processes running locally

$ gops
copy

Print more information about a process
$ gops [pid]
copy

Display a process tree
$ gops tree
copy

Print the current stack trace from a target program
$ gops stack [pid|addr]
copy

Print the current runtime memory statistics
$ gops memstats [pid|addr]
copy

SYNOPSIS

gops [command] [pid]

PARAMETERS

help
    Displays help.

version
    Prints the gops version.

processes
    Lists all Go processes.

stack
    Prints stack trace of the specified process.
Requires a PID
.

stats
    Prints runtime statistics of the specified process.
Requires a PID
.

memstats
    Prints memory statistics of the specified process.
Requires a PID
.

gc
    Forces garbage collection in the specified process.
Requires a PID
.

setgc
    Set the garbage collection percentage.
Requires a PID and percentage value
.

flags
    Prints the flags used to compile the specified process.
Requires a PID
.

DESCRIPTION

The `gops` command is a diagnostic tool for Go programs. It allows you to list all running Go processes on a system and, more importantly, inspect their stack traces. This is invaluable for debugging deadlocks, performance bottlenecks, and other runtime issues within Go applications. `gops` works by communicating with a Go agent running within the target process, which exposes internal runtime information. It relies on the `runtime` package. Using `gops`, you can quickly identify the call stack of goroutines that are consuming excessive resources or are blocked, helping to isolate the root cause of problems. It's a lightweight and powerful tool for understanding the internal state of Go applications during development and in production environments. A common usage scenario is to identify a goroutine stuck in a `select` statement or a long-running function.

CAVEATS

  • Requires Go 1.8 or later.
  • The target Go process must import the `github.com/google/gops/agent` package and start the agent.
  • Security implications: By default, the agent listens on a randomly assigned port on localhost. Ensure proper firewall rules are in place, especially in production environments.

AGENT INITIALIZATION

To use gops with a Go program, you must initialize the agent within the target Go application:
import _ "github.com/google/gops/agent"
Place this import in your main package's init() function or at the beginning of the main() function.

SECURITY CONSIDERATIONS

The agent listens on a local port.
Ensure your system is properly configured to restrict access to this port, especially when running in production environments.
Consider using a firewall to prevent unauthorized access.

HISTORY

gops was created by Google to provide a straightforward means to inspect and debug Go processes. It fills a gap in standard system monitoring tools by providing Go-specific insights into the runtime. Its creation and open-sourcing have greatly aided the Go community by simplifying diagnosis of runtime issues.

SEE ALSO

go(1), top(1), ps(1)

Copied to clipboard