Open-source project
google/gops avatar
google/gops

google/gops: inspecting running Go processes

A tool to list and diagnose Go processes currently running on your system

7,024 stars333 forksGoBSD-3-Clause

At a glance

What is it?
gops lists every Go process on a machine and, when the target program starts the diagnostics agent, exposes stack traces, memory stats, GC controls and pprof profiles. It is a small CLI, but its useful half depends on code you add to the target.
Who is it for?
Adopt gops if you operate Go services on hosts you control and can add agent.Listen to the binaries, because that pairing is what turns a process list into stack traces, memstats, GC control and pprof profiles. Skip it if the processes you care about are built by someone else and you cannot edit their main function, since the agent is opt-in and the README does not document a way to attach it after the fact.
Can I use it commercially?
Yes. BSD-3-Clause is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 122 days ago.
What is it written in?
Mainly Go, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • google/gops7,024 ★ · +5
Star history
Repository2026-09-232026-11-15
google/gops7k7k

5 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What gops solves, and for whom

A machine running several Go binaries does not label them as such in ps or top. The go version used to build a program, its parent process, and the path of the binary are spread across different tools. gops collapses that into one listing. The README's example output has five columns: PID, PPID, program name, Go version, and the location of the associated program.

The audience is narrow and specific. It is an operator or developer who has shell access to the host, knows which user owns the process, and wants to answer questions like "which of these processes is the old build" or "what is this binary doing right now". It is not a cluster-wide observability tool. It has no server component, no aggregation across hosts, and no history. Everything it reports is read at the moment you run the command.

The second audience is the developer of the target program. The diagnostics half of gops only works for processes that call agent.Listen, which means someone has to add an import and a few lines to the program being inspected. That is the central design decision of the project, and it shapes everything else.

The agent is the whole mechanism

gops itself is a client. The README shows the target side as a small program that imports github.com/google/gops/agent and calls agent.Listen(agent.Options{}) in main, then sleeps. Once that call succeeds, the process appears in the listing with an asterisk next to its PID, and the diagnostic subcommands become usable against it.

The README describes two modes. Local mode uses the process PID as the target and requires that the target binary runs as the same user as the gops binary. Remote mode uses a host:port combination and requires knowing the target's agent address. That is the data flow: the agent listens on an address, gops connects, and the subcommands issue requests over that connection. The repository layout reflects the split, with agent/, goprocess/, internal/ and signal/ directories alongside cmd.go and main.go.

Because the agent lives inside the target, gops inherits the target's permissions and lifetime. If the process exits, the agent exits. If the agent never starts, the process still shows up in the plain listing but the agent-only diagnostic subcommands have nothing to connect to. The README does not describe a fallback that attaches to a process without the agent.

Installing gops and running the first commands

The README gives two install paths. The first is the older go get form, the second the module-aware form, which also accepts a pinned version such as v0.3.19. The module declares go 1.18, so a recent toolchain is expected.

bash
go install github.com/google/gops@latest

After that, running gops with no arguments prints the local process table. The header line in the README's sample output shows the columns in order, and processes running the agent are marked with an asterisk next to the PID.

bash
gops

To get the per-process report, pass a PID. The README documents an optional duration argument parsed like time.ParseDuration, which adds a second CPU line measured over that window rather than at a single instant.

bash
gops <pid> 2s

The output includes parent PID, thread count, memory usage, cpu usage, username, cmd+args and the local/remote socket pairs with their state. If you want the tree instead of the flat table, gops tree prints a hierarchy with the Go version in braces next to each entry.

bash
gops tree

For a process that started the agent, the diagnostic subcommands take either a PID or an address: gops stack, gops memstats, gops gc, gops setgc, gops version and gops stats. The README also documents gops pprof-cpu and gops pprof-heap, which shell out to go tool pprof for interactive examination, and gops trace, which starts the runtime tracer for 5 seconds.

GOPS_CONFIG_DIR and where state lives

The README states that gops uses the current user's home directory by default, AppData on Windows, and that the GOPS_CONFIG_DIR environment variable overrides that choice. This matters in containers and on shared hosts, where the home directory may be read-only or may not exist for the user running the binary. Setting the variable to a writable path before invoking gops is the documented way to move that location.

The README does not describe what is stored there, how large it grows, or how to clear it. That is a thin spot. If you are deploying gops in an image, treat the variable as a required piece of configuration rather than an optional one, and check that the path is writable by the user that will run the command.

Where gops is the wrong tool

The clearest limitation is the opt-in agent. If you are debugging a Go binary you did not build, or one whose main function you cannot change, the diagnostic commands have nothing to talk to. The README offers no alternative path for that case. The listing still works, because it is derived from the process table, but stack, memstats, gc, version, stats, pprof and trace all require the agent.

The second limitation is the local-mode user requirement. The README states plainly that local mode requires starting the target binary as the same user that runs the gops binary. On a host where services run under dedicated accounts, that means either running gops as that account or falling back to remote mode with a known agent address.

Third, the destructive commands deserve respect. gops gc forces garbage collection and blocks until it completes. gops setgc changes the GC target percentage, and the README documents an off value that turns the collector off entirely. Those are not read-only operations, and running them against a production process changes its runtime behaviour. The README does not document a dry-run or a confirmation step.

Finally, gops is not a metrics pipeline. There is no exporter, no scrape endpoint described in the README, and no retention. A single number sampled when you happen to type the command is all you get.

gops compared with pprof and runtime introspection

The obvious alternative is going straight to net/http/pprof or runtime/pprof in the target. The difference in approach is where the endpoint comes from. pprof requires you to import the package and, in the common case, register handlers on an HTTP server you already run; gops requires you to call agent.Listen, after which the profile commands are available through the gops client, which then shells out to go tool pprof for the interactive view.

So gops is not a replacement for pprof. It is a way to reach it, plus a set of process-level commands that pprof does not have: the process tree, the Go version of an arbitrary local Go binary, the socket list, and the GC controls. The trade-off is that gops adds a dependency and an always-listening agent to the target, while pprof on an existing HTTP server may cost you nothing new if that server is already exposed.

A second alternative is reading /proc directly, or using a general process tool. That gives you the process table without any dependency, but it cannot tell you which binary was built with which Go version, and it has no notion of an agent address.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-07-16. Recent releases are v0.3.29 on 2026-01-08, v0.3.28 on 2023-08-10 and v0.3.27 on 2023-02-21. The gap between v0.3.28 and v0.3.29 is more than two years, which is worth knowing if you are pinning a version: the project moves in bursts rather than on a schedule.

The module requires go 1.18 and pulls in gopsutil v3, cobra, treeprint, golang.org/x/sys and rsc.io/goversion, with a longer list of indirect dependencies. Upgrading gops means accepting whatever those transitive modules bring, so a pinned go.sum is the practical way to control the blast radius.

The licence is BSD-3-Clause, stated in the repository's LICENSE file. That is a permissive licence, but the obligations it carries, particularly around retaining the copyright notice and disclaimer in redistributed source or binary form, are a question for your own legal review rather than something this article can settle.

Editorial conclusion

Adopt gops if you operate Go services on hosts you control and can add agent.Listen to the binaries, because that pairing is what turns a process list into stack traces, memstats, GC control and pprof profiles. Skip it if the processes you care about are built by someone else and you cannot edit their main function, since the agent is opt-in and the README does not document a way to attach it after the fact. Verify first that the target runs as the same user as the gops binary for local mode, and that the agent port is reachable for remote mode. If neither holds, the agent's diagnostic subcommands will not work.

Frequently asked questions

How do I install google/gops?

The README gives two commands: go get github.com/google/gops, or go install github.com/google/gops@latest. A specific version can be pinned by appending it, for example go install github.com/google/[email protected].

Why does google/gops show no stack trace or memstats for a process?

Those subcommands only work for processes that started the diagnostics agent by calling agent.Listen(agent.Options{}) in the target program. Without it, the process still appears in the listing but the diagnostic commands have nothing to connect to.

Can I use google/gops against a process owned by another user?

The README states that local mode requires starting the target binary as the same user that runs the gops binary. To target a process under a different account you need remote mode, which requires knowing the target's agent address as a host:port combination.

Where does google/gops keep its configuration?

By default it uses the current user's home directory, or AppData on Windows. The GOPS_CONFIG_DIR environment variable can be set to assign a different config directory.

Does google/gops change the target process when I run a command?

Some subcommands do. gops gc forces garbage collection and blocks until it completes, and gops setgc changes the GC target percentage, including an off value that turns the collector off. The README documents no dry-run or confirmation step for these.

Official sources

  1. google/gops on GitHub
  2. Issues
  3. License: BSD-3-Clause
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/google-gops.svg)](https://hysenlabs.com/projects/google-gops)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/google-gops.svg)](https://hysenlabs.com/projects/google-gops)

Was this useful?