bcc-pythongc(8)

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

NAME

6       ugc, javagc, pythongc, rubygc, nodegc - Trace garbage collection events
7       in high-level languages.
8

SYNOPSIS

10       javagc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
11       pythongc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
12       rubygc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
13       nodegc [-h] [-v] [-m] [-M MINIMUM] [-F FILTER] pid
14       ugc    [-h]    [-v]    [-m]    [-M    MINIMUM]    [-F    FILTER]    [-l
15       {java,python,ruby,node}] pid
16

DESCRIPTION

18       This  traces  garbage  collection events as they occur, including their
19       duration and any additional information (such as  generation  collected
20       or type of GC) provided by the respective language's runtime.
21
22       This  tool relies on USDT probes embedded in many high-level languages,
23       such as Node, Java, Python, and Ruby. It  requires  a  runtime  instru‐
24       mented  with  these  probes, which in some cases requires building from
25       source with a USDT-specific flag, such as "--enable-dtrace" or "--with-
26       dtrace".
27
28       Since this uses BPF, only the root user can use this tool.
29

REQUIREMENTS

31       CONFIG_BPF and bcc.
32

OPTIONS

34       -v     Print the resulting BPF program, for debugging purposes.
35
36       -m     Print times in milliseconds. The default is microseconds.
37
38       -M MINIMUM
39              Display  only  collections  that are longer than this threshold.
40              The value is given in milliseconds. The default  is  to  display
41              all collections.
42
43       -F FILTER
44              Display only collections whose textual description matches (con‐
45              tains) this string. The default is to display  all  collections.
46              Note that the filtering here is performed in user-space, and not
47              as part of the BPF program. This means that if  you  have  thou‐
48              sands  of  collection  events,  specifying  this filter will not
49              reduce the amount of data that has to be  transferred  from  the
50              BPF program to the user-space script.
51
52       {java,python,ruby,node}
53              The language to trace.
54
55       pid    The process id to trace.
56

EXAMPLES

58       Trace garbage collections in a specific Node process:
59              # ugc node 148
60
61       Trace  garbage  collections  in  a  specific Java process, and print GC
62       times in
63              milliseconds: # ugc -m java 6004
64
65       Trace garbage collections in a specific Java process, and display  them
66       only if
67              they are longer than 10ms and have the string "Tenured" in their
68              detailed description: # ugc -M 10 -F Tenured java 6004
69

FIELDS

71       START  The start time of the GC, in seconds from the beginning  of  the
72              trace.
73
74       TIME   The duration of the garbage collection event.
75
76       DESCRIPTION
77              The  runtime-provided  description  of  this  garbage collection
78              event.
79

OVERHEAD

81       Garbage collection events, even if frequent, should not produce a  con‐
82       siderable  overhead when traced because they are still not very common.
83       Even hundreds of GCs per second (which is a very high rate) will  still
84       produce a fairly negligible overhead.
85

SOURCE

87       This is from bcc.
88
89              https://github.com/iovisor/bcc
90
91       Also  look  in  the  bcc distribution for a companion _example.txt file
92       containing example usage, output, and commentary for this tool.
93

OS

95       Linux
96

STABILITY

98       Unstable - in development.
99

AUTHOR

101       Sasha Goldshtein
102