1ustat(8)                    System Manager's Manual                   ustat(8)
2
3
4

NAME

6       ustat,  javastat,  pythonstat,  rubystat,  nodestat, phpstat - Activity
7       stats from high-level languages.
8

SYNOPSIS

10       javastat [-C] [-S  {cload,excp,gc,method,objnew,thread}]  [-r  MAXROWS]
11       [-d] [interval [count]]
12       pythonstat  [-C] [-S {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
13       [-d] [interval [count]]
14       rubystat [-C] [-S  {cload,excp,gc,method,objnew,thread}]  [-r  MAXROWS]
15       [-d] [interval [count]]
16       nodestat  [-C]  [-S  {cload,excp,gc,method,objnew,thread}] [-r MAXROWS]
17       [-d] [interval [count]]
18       phpstat [-C]  [-S  {cload,excp,gc,method,objnew,thread}]  [-r  MAXROWS]
19       [-d] [interval [count]]
20       ustat       [-l       {java,python,ruby,node,php}]       [-C]       [-S
21       {cload,excp,gc,method,objnew,thread}]  [-r  MAXROWS]   [-d]   [interval
22       [count]]
23

DESCRIPTION

25       This  is  "top" for high-level language events, such as garbage collec‐
26       tions, exceptions, thread creations, object allocations, method  calls,
27       and  more.  The events are aggregated for each process and printed in a
28       top-like table, which can be sorted by various fields.
29
30       This uses in-kernel eBPF maps to store per process summaries for  effi‐
31       ciency.
32
33       This  tool relies on USDT probes embedded in many high-level languages,
34       such as Node, Java, Python,  Ruby,  and  PHP.  It  requires  a  runtime
35       instrumented  with  these probes, which in some cases requires building
36       from source with a USDT-specific flag,  such  as  "--enable-dtrace"  or
37       "--with-dtrace".  For Java, some probes are not enabled by default, and
38       can be turned on by running the Java process with  the  "-XX:+Extended‐
39       DTraceProbes"   flag.  For  PHP  processes,  the  environment  variable
40       USE_ZEND_DTRACE must be set to 1.
41
42       Newly-created processes will only be traced at the  next  interval.  If
43       you run this tool with a short interval (say, 1-5 seconds), this should
44       be virtually unnoticeable. For longer intervals, you  might  miss  pro‐
45       cesses that were started and terminated during the interval window.
46
47       Since this uses BPF, only the root user can use this tool.
48

REQUIREMENTS

50       CONFIG_BPF and bcc.
51

OPTIONS

53       -l {java,python,ruby,node,php}
54              The language to trace. By default, all languages are traced.
55
56       -C     Do not clear the screen between updates.
57
58       -S {cload,excp,gc,method,objnew,thread}
59              Sort the output by the specified field.
60
61       -r MAXROWS
62              Do not print more than this number of rows.
63
64       -d     Print the resulting BPF program, for debugging purposes.
65
66       interval
67              Interval between updates, seconds.
68
69       count  Number of interval summaries.
70

EXAMPLES

72       Summarize activity in high-level languages, 1 second refresh:
73              # ustat
74
75       Don't clear the screen, and top 8 rows only:
76              # ustat -Cr 8
77
78       5 second summaries, 10 times only:
79              # ustat 5 10
80

FIELDS

82       loadavg
83              The contents of /proc/loadavg
84
85       PID    Process ID.
86
87       CMDLINE
88              Process  command  line (often the second and following arguments
89              will give you a hint as to which application is being run.
90
91       METHOD/s
92              Count of method invocations during interval.
93
94       GC/s   Count of garbage collections during interval.
95
96       OBJNEW/s
97              Count of objects allocated during interval.
98
99       CLOAD/s
100              Count of classes loaded during interval.
101
102       EXC/s  Count of exceptions thrown during interval.
103
104       THR/s  Count of threads created during interval.
105

OVERHEAD

107       When using this tool with high-frequency events, such as method  calls,
108       a  very  significant  slow-down  can  be expected. However, many of the
109       high-level languages covered by this tool already have  a  fairly  high
110       per-method  invocation  cost,  especially  when  running in interpreted
111       mode. For the lower-frequency events, such as  garbage  collections  or
112       thread creations, the overhead should not be significant. Specifically,
113       when probing Java  processes  and  not  using  the  "-XX:+ExtendedDTra‐
114       ceProbes"  flag,  the  most  expensive  probes are not emitted, and the
115       overhead should be acceptable.
116

SOURCE

118       This is from bcc.
119
120              https://github.com/iovisor/bcc
121
122       Also look in the bcc distribution for  a  companion  _example.txt  file
123       containing example usage, output, and commentary for this tool.
124

OS

126       Linux
127

STABILITY

129       Unstable - in development.
130

AUTHOR

132       Sasha Goldshtein
133

SEE ALSO

135       trace(8), argdist(8), tplist(8)
136
137
138
139USER COMMANDS                     2016-11-07                          ustat(8)
Impressum