bcc-ustat(8)

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

NAME

6       ustat,  javastat,  nodestat,  perlstat,  phpstat, pythonstat, rubystat,
7       tclstat - 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       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

DESCRIPTION

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

REQUIREMENTS

55       CONFIG_BPF and bcc.
56

OPTIONS

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

EXAMPLES

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

FIELDS

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

OVERHEAD

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

SOURCE

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

OS

131       Linux
132

STABILITY

134       Unstable - in development.
135

AUTHOR

137       Sasha Goldshtein
138