bcc-ustat(8)

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

NAME

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

SYNOPSIS

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       ustat     [-l      {java,perl,python,ruby,node,php}]      [-C]      [-S
23       {cload,excp,gc,method,objnew,thread}]   [-r   MAXROWS]  [-d]  [interval
24       [count]]
25

DESCRIPTION

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

REQUIREMENTS

53       CONFIG_BPF and bcc.
54

OPTIONS

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

EXAMPLES

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

FIELDS

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

OVERHEAD

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

SOURCE

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

OS

129       Linux
130

STABILITY

132       Unstable - in development.
133

AUTHOR

135       Sasha Goldshtein
136