1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
|
# gops
[](https://circleci.com/gh/google/gops)
[](https://godoc.org/github.com/google/gops/agent)
gops is a command to list and diagnose Go processes currently running on your system.
```
$ gops
983 uplink-soecks (/usr/local/bin/uplink-soecks)
52697 gops (/Users/jbd/bin/gops)
4132* foops (/Users/jbd/bin/foops)
51130 gocode (/Users/jbd/bin/gocode)
```
## Installation
```
$ go get -u github.com/google/gops
```
## Diagnostics
For processes that starts the diagnostics agent, gops can report
additional information such as the current stack trace, Go version, memory
stats, etc.
In order to start the diagnostics agent, see the [hello example](https://github.com/google/gops/blob/master/examples/hello/main.go).
``` go
package main
import (
"log"
"time"
"github.com/google/gops/agent"
)
func main() {
if err := agent.Listen(nil); err != nil {
log.Fatal(err)
}
time.Sleep(time.Hour)
}
```
### Manual
It is possible to use gops tool both in local and remote mode.
Local mode requires that you start the target binary as the same user that runs gops binary.
To use gops in a remote mode you need to know target's agent address.
In Local mode use process's PID as a target; in Remote mode target is a `host:port` combination.
#### 0. Listing all processes running locally
To print all go processes, run `gops` without arguments:
```sh
$ gops
983 uplink-soecks (/usr/local/bin/uplink-soecks)
52697 gops (/Users/jbd/bin/gops)
4132* foops (/Users/jbd/bin/foops)
51130 gocode (/Users/jbd/bin/gocode)
```
Note that processes running the agent are marked with `*` next to the PID (e.g. `4132*`).
#### $ gops stack (\<pid\>|\<addr\>)
In order to print the current stack trace from a target program, run the following command:
```sh
$ gops stack (<pid>|<addr>)
gops stack 85709
goroutine 8 [running]:
runtime/pprof.writeGoroutineStacks(0x13c7bc0, 0xc42000e008, 0xc420ec8520, 0xc420ec8520)
/Users/jbd/go/src/runtime/pprof/pprof.go:603 +0x79
runtime/pprof.writeGoroutine(0x13c7bc0, 0xc42000e008, 0x2, 0xc428f1c048, 0xc420ec8608)
/Users/jbd/go/src/runtime/pprof/pprof.go:592 +0x44
runtime/pprof.(*Profile).WriteTo(0x13eeda0, 0x13c7bc0, 0xc42000e008, 0x2, 0xc42000e008, 0x0)
/Users/jbd/go/src/runtime/pprof/pprof.go:302 +0x3b5
github.com/google/gops/agent.handle(0x13cd560, 0xc42000e008, 0xc420186000, 0x1, 0x1, 0x0, 0x0)
/Users/jbd/src/github.com/google/gops/agent/agent.go:150 +0x1b3
github.com/google/gops/agent.listen()
/Users/jbd/src/github.com/google/gops/agent/agent.go:113 +0x2b2
created by github.com/google/gops/agent.Listen
/Users/jbd/src/github.com/google/gops/agent/agent.go:94 +0x480
# ...
```
#### $ gops memstats (\<pid\>|\<addr\>)
To print the current memory stats, run the following command:
```sh
$ gops memstats (<pid>|<addr>)
```
#### $ gops gc (\<pid\>|\<addr\>)
If you want to force run garbage collection on the target program, run `gc`.
It will block until the GC is completed.
#### $ gops version (\<pid\>|\<addr\>)
gops reports the Go version the target program is built with, if you run the following:
```sh
$ gops version (<pid>|<addr>)
devel +6a3c6c0 Sat Jan 14 05:57:07 2017 +0000
```
#### $ gops stats (\<pid\>|\<addr\>)
To print the runtime statistics such as number of goroutines and `GOMAXPROCS`.
#### Profiling
##### Pprof
gops supports CPU and heap pprof profiles. After reading either heap or CPU profile,
it shells out to the `go tool pprof` and let you interatively examine the profiles.
To enter the CPU profile, run:
```sh
$ gops pprof-cpu (<pid>|<addr>)
```
To enter the heap profile, run:
```sh
$ gops pprof-heap (<pid>|<addr>)
```
##### Execution trace
gops allows you to start the runtime tracer for 5 seconds and examine the results.
```sh
$ gops trace (<pid>|<addr>)
```
|
