1ustat(8) System Manager's Manual ustat(8)
2
3
4
6 ustat, javastat, nodestat, perlstat, phpstat, pythonstat, rubystat,
7 tclstat - Activity stats from high-level languages.
8
10 javastat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
11 [-d] [interval [count]]
12 nodestat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
13 [-d] [interval [count]]
14 perlstat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
15 [-d] [interval [count]]
16 phpstat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
17 [-d] [interval [count]]
18 pythonstat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
19 [-d] [interval [count]]
20 rubystat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
21 [-d] [interval [count]]
22 tclstat [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
23 [-d] [interval [count]]
24 ustat [-l {java,node,perl,php,python,ruby,tcl}] [-C] [-S
25 {cload,excp,gc,method,objnew,thread}] [-r MAXROWS] [-d] [interval
26 [count]]
27
29 This is "top" for high-level language events, such as garbage collec‐
30 tions, exceptions, thread creations, object allocations, method calls,
31 and more. The events are aggregated for each process and printed in a
32 top-like table, which can be sorted by various fields. Not all language
33 runtimes provide the same set of details.
34
35 This uses in-kernel eBPF maps to store per process summaries for effi‐
36 ciency.
37
38 This tool relies on USDT probes embedded in many high-level languages,
39 such as Java, Node, Perl, PHP, Python, Ruby, and Tcl. It requires a
40 runtime instrumented with these probes, which in some cases requires
41 building from source with a USDT-specific flag, such as "--enable-
42 dtrace" or "--with-dtrace". For Java, some probes are not enabled by
43 default, and can be turned on by running the Java process with the
44 "-XX:+ExtendedDTraceProbes" flag. For PHP processes, the environment
45 variable USE_ZEND_DTRACE must be set to 1.
46
47 Newly-created processes will only be traced at the next interval. If
48 you run this tool with a short interval (say, 1-5 seconds), this should
49 be virtually unnoticeable. For longer intervals, you might miss pro‐
50 cesses that were started and terminated during the interval window.
51
52 Since this uses BPF, only the root user can use this tool.
53
55 CONFIG_BPF and bcc.
56
58 -l {java,node,perl,php,python,ruby,tcl}
59 The language to trace. By default, all languages are traced.
60
61 -C Do not clear the screen between updates.
62
63 -S {cload,excp,gc,method,objnew,thread}
64 Sort the output by the specified field.
65
66 -r MAXROWS
67 Do not print more than this number of rows.
68
69 -d Print the resulting BPF program, for debugging purposes.
70
71 interval
72 Interval between updates, seconds.
73
74 count Number of interval summaries.
75
77 Summarize activity in high-level languages, 1 second refresh:
78 # ustat
79
80 Don't clear the screen, and top 8 rows only:
81 # ustat -Cr 8
82
83 5 second summaries, 10 times only:
84 # ustat 5 10
85
87 loadavg
88 The contents of /proc/loadavg
89
90 PID Process ID.
91
92 CMDLINE
93 Process command line (often the second and following arguments
94 will give you a hint as to which application is being run.
95
96 METHOD/s
97 Count of method invocations during interval.
98
99 GC/s Count of garbage collections during interval.
100
101 OBJNEW/s
102 Count of objects allocated during interval.
103
104 CLOAD/s
105 Count of classes loaded during interval.
106
107 EXC/s Count of exceptions thrown during interval.
108
109 THR/s Count of threads created during interval.
110
112 When using this tool with high-frequency events, such as method calls,
113 a very significant slow-down can be expected. However, many of the
114 high-level languages covered by this tool already have a fairly high
115 per-method invocation cost, especially when running in interpreted
116 mode. For the lower-frequency events, such as garbage collections or
117 thread creations, the overhead should not be significant. Specifically,
118 when probing Java processes and not using the "-XX:+ExtendedDTra‐
119 ceProbes" flag, the most expensive probes are not emitted, and the
120 overhead should be acceptable.
121
123 This is from bcc.
124
125 https://github.com/iovisor/bcc
126
127 Also look in the bcc distribution for a companion _example.txt file
128 containing example usage, output, and commentary for this tool.
129
131 Linux
132
134 Unstable - in development.
135
137 Sasha Goldshtein
138
140 trace(8), argdist(8), tplist(8)
141
142
143
144USER COMMANDS 2018-10-09 ustat(8)