About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / trace / events.txt




Custom Search

Based on kernel version 4.13.3. Page generated on 2017-09-23 13:56 EST.

1				     Event Tracing
2	
3			Documentation written by Theodore Ts'o
4			Updated by Li Zefan and Tom Zanussi
5	
6	1. Introduction
7	===============
8	
9	Tracepoints (see Documentation/trace/tracepoints.txt) can be used
10	without creating custom kernel modules to register probe functions
11	using the event tracing infrastructure.
12	
13	Not all tracepoints can be traced using the event tracing system;
14	the kernel developer must provide code snippets which define how the
15	tracing information is saved into the tracing buffer, and how the
16	tracing information should be printed.
17	
18	2. Using Event Tracing
19	======================
20	
21	2.1 Via the 'set_event' interface
22	---------------------------------
23	
24	The events which are available for tracing can be found in the file
25	/sys/kernel/debug/tracing/available_events.
26	
27	To enable a particular event, such as 'sched_wakeup', simply echo it
28	to /sys/kernel/debug/tracing/set_event. For example:
29	
30		# echo sched_wakeup >> /sys/kernel/debug/tracing/set_event
31	
32	[ Note: '>>' is necessary, otherwise it will firstly disable
33	  all the events. ]
34	
35	To disable an event, echo the event name to the set_event file prefixed
36	with an exclamation point:
37	
38		# echo '!sched_wakeup' >> /sys/kernel/debug/tracing/set_event
39	
40	To disable all events, echo an empty line to the set_event file:
41	
42		# echo > /sys/kernel/debug/tracing/set_event
43	
44	To enable all events, echo '*:*' or '*:' to the set_event file:
45	
46		# echo *:* > /sys/kernel/debug/tracing/set_event
47	
48	The events are organized into subsystems, such as ext4, irq, sched,
49	etc., and a full event name looks like this: <subsystem>:<event>.  The
50	subsystem name is optional, but it is displayed in the available_events
51	file.  All of the events in a subsystem can be specified via the syntax
52	"<subsystem>:*"; for example, to enable all irq events, you can use the
53	command:
54	
55		# echo 'irq:*' > /sys/kernel/debug/tracing/set_event
56	
57	2.2 Via the 'enable' toggle
58	---------------------------
59	
60	The events available are also listed in /sys/kernel/debug/tracing/events/ hierarchy
61	of directories.
62	
63	To enable event 'sched_wakeup':
64	
65		# echo 1 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable
66	
67	To disable it:
68	
69		# echo 0 > /sys/kernel/debug/tracing/events/sched/sched_wakeup/enable
70	
71	To enable all events in sched subsystem:
72	
73		# echo 1 > /sys/kernel/debug/tracing/events/sched/enable
74	
75	To enable all events:
76	
77		# echo 1 > /sys/kernel/debug/tracing/events/enable
78	
79	When reading one of these enable files, there are four results:
80	
81	 0 - all events this file affects are disabled
82	 1 - all events this file affects are enabled
83	 X - there is a mixture of events enabled and disabled
84	 ? - this file does not affect any event
85	
86	2.3 Boot option
87	---------------
88	
89	In order to facilitate early boot debugging, use boot option:
90	
91		trace_event=[event-list]
92	
93	event-list is a comma separated list of events. See section 2.1 for event
94	format.
95	
96	3. Defining an event-enabled tracepoint
97	=======================================
98	
99	See The example provided in samples/trace_events
100	
101	4. Event formats
102	================
103	
104	Each trace event has a 'format' file associated with it that contains
105	a description of each field in a logged event.  This information can
106	be used to parse the binary trace stream, and is also the place to
107	find the field names that can be used in event filters (see section 5).
108	
109	It also displays the format string that will be used to print the
110	event in text mode, along with the event name and ID used for
111	profiling.
112	
113	Every event has a set of 'common' fields associated with it; these are
114	the fields prefixed with 'common_'.  The other fields vary between
115	events and correspond to the fields defined in the TRACE_EVENT
116	definition for that event.
117	
118	Each field in the format has the form:
119	
120	     field:field-type field-name; offset:N; size:N;
121	
122	where offset is the offset of the field in the trace record and size
123	is the size of the data item, in bytes.
124	
125	For example, here's the information displayed for the 'sched_wakeup'
126	event:
127	
128	# cat /sys/kernel/debug/tracing/events/sched/sched_wakeup/format
129	
130	name: sched_wakeup
131	ID: 60
132	format:
133		field:unsigned short common_type;	offset:0;	size:2;
134		field:unsigned char common_flags;	offset:2;	size:1;
135		field:unsigned char common_preempt_count;	offset:3;	size:1;
136		field:int common_pid;	offset:4;	size:4;
137		field:int common_tgid;	offset:8;	size:4;
138	
139		field:char comm[TASK_COMM_LEN];	offset:12;	size:16;
140		field:pid_t pid;	offset:28;	size:4;
141		field:int prio;	offset:32;	size:4;
142		field:int success;	offset:36;	size:4;
143		field:int cpu;	offset:40;	size:4;
144	
145	print fmt: "task %s:%d [%d] success=%d [%03d]", REC->comm, REC->pid,
146		   REC->prio, REC->success, REC->cpu
147	
148	This event contains 10 fields, the first 5 common and the remaining 5
149	event-specific.  All the fields for this event are numeric, except for
150	'comm' which is a string, a distinction important for event filtering.
151	
152	5. Event filtering
153	==================
154	
155	Trace events can be filtered in the kernel by associating boolean
156	'filter expressions' with them.  As soon as an event is logged into
157	the trace buffer, its fields are checked against the filter expression
158	associated with that event type.  An event with field values that
159	'match' the filter will appear in the trace output, and an event whose
160	values don't match will be discarded.  An event with no filter
161	associated with it matches everything, and is the default when no
162	filter has been set for an event.
163	
164	5.1 Expression syntax
165	---------------------
166	
167	A filter expression consists of one or more 'predicates' that can be
168	combined using the logical operators '&&' and '||'.  A predicate is
169	simply a clause that compares the value of a field contained within a
170	logged event with a constant value and returns either 0 or 1 depending
171	on whether the field value matched (1) or didn't match (0):
172	
173		  field-name relational-operator value
174	
175	Parentheses can be used to provide arbitrary logical groupings and
176	double-quotes can be used to prevent the shell from interpreting
177	operators as shell metacharacters.
178	
179	The field-names available for use in filters can be found in the
180	'format' files for trace events (see section 4).
181	
182	The relational-operators depend on the type of the field being tested:
183	
184	The operators available for numeric fields are:
185	
186	==, !=, <, <=, >, >=, &
187	
188	And for string fields they are:
189	
190	==, !=, ~
191	
192	The glob (~) accepts a wild card character (*,?) and character classes
193	([). For example:
194	
195	  prev_comm ~ "*sh"
196	  prev_comm ~ "sh*"
197	  prev_comm ~ "*sh*"
198	  prev_comm ~ "ba*sh"
199	
200	5.2 Setting filters
201	-------------------
202	
203	A filter for an individual event is set by writing a filter expression
204	to the 'filter' file for the given event.
205	
206	For example:
207	
208	# cd /sys/kernel/debug/tracing/events/sched/sched_wakeup
209	# echo "common_preempt_count > 4" > filter
210	
211	A slightly more involved example:
212	
213	# cd /sys/kernel/debug/tracing/events/signal/signal_generate
214	# echo "((sig >= 10 && sig < 15) || sig == 17) && comm != bash" > filter
215	
216	If there is an error in the expression, you'll get an 'Invalid
217	argument' error when setting it, and the erroneous string along with
218	an error message can be seen by looking at the filter e.g.:
219	
220	# cd /sys/kernel/debug/tracing/events/signal/signal_generate
221	# echo "((sig >= 10 && sig < 15) || dsig == 17) && comm != bash" > filter
222	-bash: echo: write error: Invalid argument
223	# cat filter
224	((sig >= 10 && sig < 15) || dsig == 17) && comm != bash
225	^
226	parse_error: Field not found
227	
228	Currently the caret ('^') for an error always appears at the beginning of
229	the filter string; the error message should still be useful though
230	even without more accurate position info.
231	
232	5.3 Clearing filters
233	--------------------
234	
235	To clear the filter for an event, write a '0' to the event's filter
236	file.
237	
238	To clear the filters for all events in a subsystem, write a '0' to the
239	subsystem's filter file.
240	
241	5.3 Subsystem filters
242	---------------------
243	
244	For convenience, filters for every event in a subsystem can be set or
245	cleared as a group by writing a filter expression into the filter file
246	at the root of the subsystem.  Note however, that if a filter for any
247	event within the subsystem lacks a field specified in the subsystem
248	filter, or if the filter can't be applied for any other reason, the
249	filter for that event will retain its previous setting.  This can
250	result in an unintended mixture of filters which could lead to
251	confusing (to the user who might think different filters are in
252	effect) trace output.  Only filters that reference just the common
253	fields can be guaranteed to propagate successfully to all events.
254	
255	Here are a few subsystem filter examples that also illustrate the
256	above points:
257	
258	Clear the filters on all events in the sched subsystem:
259	
260	# cd /sys/kernel/debug/tracing/events/sched
261	# echo 0 > filter
262	# cat sched_switch/filter
263	none
264	# cat sched_wakeup/filter
265	none
266	
267	Set a filter using only common fields for all events in the sched
268	subsystem (all events end up with the same filter):
269	
270	# cd /sys/kernel/debug/tracing/events/sched
271	# echo common_pid == 0 > filter
272	# cat sched_switch/filter
273	common_pid == 0
274	# cat sched_wakeup/filter
275	common_pid == 0
276	
277	Attempt to set a filter using a non-common field for all events in the
278	sched subsystem (all events but those that have a prev_pid field retain
279	their old filters):
280	
281	# cd /sys/kernel/debug/tracing/events/sched
282	# echo prev_pid == 0 > filter
283	# cat sched_switch/filter
284	prev_pid == 0
285	# cat sched_wakeup/filter
286	common_pid == 0
287	
288	5.4 PID filtering
289	-----------------
290	
291	The set_event_pid file in the same directory as the top events directory
292	exists, will filter all events from tracing any task that does not have the
293	PID listed in the set_event_pid file.
294	
295	# cd /sys/kernel/debug/tracing
296	# echo $$ > set_event_pid
297	# echo 1 > events/enabled
298	
299	Will only trace events for the current task.
300	
301	To add more PIDs without losing the PIDs already included, use '>>'.
302	
303	# echo 123 244 1 >> set_event_pid
304	
305	
306	6. Event triggers
307	=================
308	
309	Trace events can be made to conditionally invoke trigger 'commands'
310	which can take various forms and are described in detail below;
311	examples would be enabling or disabling other trace events or invoking
312	a stack trace whenever the trace event is hit.  Whenever a trace event
313	with attached triggers is invoked, the set of trigger commands
314	associated with that event is invoked.  Any given trigger can
315	additionally have an event filter of the same form as described in
316	section 5 (Event filtering) associated with it - the command will only
317	be invoked if the event being invoked passes the associated filter.
318	If no filter is associated with the trigger, it always passes.
319	
320	Triggers are added to and removed from a particular event by writing
321	trigger expressions to the 'trigger' file for the given event.
322	
323	A given event can have any number of triggers associated with it,
324	subject to any restrictions that individual commands may have in that
325	regard.
326	
327	Event triggers are implemented on top of "soft" mode, which means that
328	whenever a trace event has one or more triggers associated with it,
329	the event is activated even if it isn't actually enabled, but is
330	disabled in a "soft" mode.  That is, the tracepoint will be called,
331	but just will not be traced, unless of course it's actually enabled.
332	This scheme allows triggers to be invoked even for events that aren't
333	enabled, and also allows the current event filter implementation to be
334	used for conditionally invoking triggers.
335	
336	The syntax for event triggers is roughly based on the syntax for
337	set_ftrace_filter 'ftrace filter commands' (see the 'Filter commands'
338	section of Documentation/trace/ftrace.txt), but there are major
339	differences and the implementation isn't currently tied to it in any
340	way, so beware about making generalizations between the two.
341	
342	6.1 Expression syntax
343	---------------------
344	
345	Triggers are added by echoing the command to the 'trigger' file:
346	
347	  # echo 'command[:count] [if filter]' > trigger
348	
349	Triggers are removed by echoing the same command but starting with '!'
350	to the 'trigger' file:
351	
352	  # echo '!command[:count] [if filter]' > trigger
353	
354	The [if filter] part isn't used in matching commands when removing, so
355	leaving that off in a '!' command will accomplish the same thing as
356	having it in.
357	
358	The filter syntax is the same as that described in the 'Event
359	filtering' section above.
360	
361	For ease of use, writing to the trigger file using '>' currently just
362	adds or removes a single trigger and there's no explicit '>>' support
363	('>' actually behaves like '>>') or truncation support to remove all
364	triggers (you have to use '!' for each one added.)
365	
366	6.2 Supported trigger commands
367	------------------------------
368	
369	The following commands are supported:
370	
371	- enable_event/disable_event
372	
373	  These commands can enable or disable another trace event whenever
374	  the triggering event is hit.  When these commands are registered,
375	  the other trace event is activated, but disabled in a "soft" mode.
376	  That is, the tracepoint will be called, but just will not be traced.
377	  The event tracepoint stays in this mode as long as there's a trigger
378	  in effect that can trigger it.
379	
380	  For example, the following trigger causes kmalloc events to be
381	  traced when a read system call is entered, and the :1 at the end
382	  specifies that this enablement happens only once:
383	
384	  # echo 'enable_event:kmem:kmalloc:1' > \
385	      /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger
386	
387	  The following trigger causes kmalloc events to stop being traced
388	  when a read system call exits.  This disablement happens on every
389	  read system call exit:
390	
391	  # echo 'disable_event:kmem:kmalloc' > \
392	      /sys/kernel/debug/tracing/events/syscalls/sys_exit_read/trigger
393	
394	  The format is:
395	
396	      enable_event:<system>:<event>[:count]
397	      disable_event:<system>:<event>[:count]
398	
399	  To remove the above commands:
400	
401	  # echo '!enable_event:kmem:kmalloc:1' > \
402	      /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger
403	
404	  # echo '!disable_event:kmem:kmalloc' > \
405	      /sys/kernel/debug/tracing/events/syscalls/sys_exit_read/trigger
406	
407	  Note that there can be any number of enable/disable_event triggers
408	  per triggering event, but there can only be one trigger per
409	  triggered event. e.g. sys_enter_read can have triggers enabling both
410	  kmem:kmalloc and sched:sched_switch, but can't have two kmem:kmalloc
411	  versions such as kmem:kmalloc and kmem:kmalloc:1 or 'kmem:kmalloc if
412	  bytes_req == 256' and 'kmem:kmalloc if bytes_alloc == 256' (they
413	  could be combined into a single filter on kmem:kmalloc though).
414	
415	- stacktrace
416	
417	  This command dumps a stacktrace in the trace buffer whenever the
418	  triggering event occurs.
419	
420	  For example, the following trigger dumps a stacktrace every time the
421	  kmalloc tracepoint is hit:
422	
423	  # echo 'stacktrace' > \
424	        /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
425	
426	  The following trigger dumps a stacktrace the first 5 times a kmalloc
427	  request happens with a size >= 64K
428	
429	  # echo 'stacktrace:5 if bytes_req >= 65536' > \
430	        /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
431	
432	  The format is:
433	
434	      stacktrace[:count]
435	
436	  To remove the above commands:
437	
438	  # echo '!stacktrace' > \
439	        /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
440	
441	  # echo '!stacktrace:5 if bytes_req >= 65536' > \
442	        /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
443	
444	  The latter can also be removed more simply by the following (without
445	  the filter):
446	
447	  # echo '!stacktrace:5' > \
448	        /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
449	
450	  Note that there can be only one stacktrace trigger per triggering
451	  event.
452	
453	- snapshot
454	
455	  This command causes a snapshot to be triggered whenever the
456	  triggering event occurs.
457	
458	  The following command creates a snapshot every time a block request
459	  queue is unplugged with a depth > 1.  If you were tracing a set of
460	  events or functions at the time, the snapshot trace buffer would
461	  capture those events when the trigger event occurred:
462	
463	  # echo 'snapshot if nr_rq > 1' > \
464	        /sys/kernel/debug/tracing/events/block/block_unplug/trigger
465	
466	  To only snapshot once:
467	
468	  # echo 'snapshot:1 if nr_rq > 1' > \
469	        /sys/kernel/debug/tracing/events/block/block_unplug/trigger
470	
471	  To remove the above commands:
472	
473	  # echo '!snapshot if nr_rq > 1' > \
474	        /sys/kernel/debug/tracing/events/block/block_unplug/trigger
475	
476	  # echo '!snapshot:1 if nr_rq > 1' > \
477	        /sys/kernel/debug/tracing/events/block/block_unplug/trigger
478	
479	  Note that there can be only one snapshot trigger per triggering
480	  event.
481	
482	- traceon/traceoff
483	
484	  These commands turn tracing on and off when the specified events are
485	  hit. The parameter determines how many times the tracing system is
486	  turned on and off. If unspecified, there is no limit.
487	
488	  The following command turns tracing off the first time a block
489	  request queue is unplugged with a depth > 1.  If you were tracing a
490	  set of events or functions at the time, you could then examine the
491	  trace buffer to see the sequence of events that led up to the
492	  trigger event:
493	
494	  # echo 'traceoff:1 if nr_rq > 1' > \
495	        /sys/kernel/debug/tracing/events/block/block_unplug/trigger
496	
497	  To always disable tracing when nr_rq  > 1 :
498	
499	  # echo 'traceoff if nr_rq > 1' > \
500	        /sys/kernel/debug/tracing/events/block/block_unplug/trigger
501	
502	  To remove the above commands:
503	
504	  # echo '!traceoff:1 if nr_rq > 1' > \
505	        /sys/kernel/debug/tracing/events/block/block_unplug/trigger
506	
507	  # echo '!traceoff if nr_rq > 1' > \
508	        /sys/kernel/debug/tracing/events/block/block_unplug/trigger
509	
510	  Note that there can be only one traceon or traceoff trigger per
511	  triggering event.
512	
513	- hist
514	
515	  This command aggregates event hits into a hash table keyed on one or
516	  more trace event format fields (or stacktrace) and a set of running
517	  totals derived from one or more trace event format fields and/or
518	  event counts (hitcount).
519	
520	  The format of a hist trigger is as follows:
521	
522	        hist:keys=<field1[,field2,...]>[:values=<field1[,field2,...]>]
523	          [:sort=<field1[,field2,...]>][:size=#entries][:pause][:continue]
524	          [:clear][:name=histname1] [if <filter>]
525	
526	  When a matching event is hit, an entry is added to a hash table
527	  using the key(s) and value(s) named.  Keys and values correspond to
528	  fields in the event's format description.  Values must correspond to
529	  numeric fields - on an event hit, the value(s) will be added to a
530	  sum kept for that field.  The special string 'hitcount' can be used
531	  in place of an explicit value field - this is simply a count of
532	  event hits.  If 'values' isn't specified, an implicit 'hitcount'
533	  value will be automatically created and used as the only value.
534	  Keys can be any field, or the special string 'stacktrace', which
535	  will use the event's kernel stacktrace as the key.  The keywords
536	  'keys' or 'key' can be used to specify keys, and the keywords
537	  'values', 'vals', or 'val' can be used to specify values.  Compound
538	  keys consisting of up to two fields can be specified by the 'keys'
539	  keyword.  Hashing a compound key produces a unique entry in the
540	  table for each unique combination of component keys, and can be
541	  useful for providing more fine-grained summaries of event data.
542	  Additionally, sort keys consisting of up to two fields can be
543	  specified by the 'sort' keyword.  If more than one field is
544	  specified, the result will be a 'sort within a sort': the first key
545	  is taken to be the primary sort key and the second the secondary
546	  key.  If a hist trigger is given a name using the 'name' parameter,
547	  its histogram data will be shared with other triggers of the same
548	  name, and trigger hits will update this common data.  Only triggers
549	  with 'compatible' fields can be combined in this way; triggers are
550	  'compatible' if the fields named in the trigger share the same
551	  number and type of fields and those fields also have the same names.
552	  Note that any two events always share the compatible 'hitcount' and
553	  'stacktrace' fields and can therefore be combined using those
554	  fields, however pointless that may be.
555	
556	  'hist' triggers add a 'hist' file to each event's subdirectory.
557	  Reading the 'hist' file for the event will dump the hash table in
558	  its entirety to stdout.  If there are multiple hist triggers
559	  attached to an event, there will be a table for each trigger in the
560	  output.  The table displayed for a named trigger will be the same as
561	  any other instance having the same name. Each printed hash table
562	  entry is a simple list of the keys and values comprising the entry;
563	  keys are printed first and are delineated by curly braces, and are
564	  followed by the set of value fields for the entry.  By default,
565	  numeric fields are displayed as base-10 integers.  This can be
566	  modified by appending any of the following modifiers to the field
567	  name:
568	
569	        .hex        display a number as a hex value
570		.sym        display an address as a symbol
571		.sym-offset display an address as a symbol and offset
572		.syscall    display a syscall id as a system call name
573		.execname   display a common_pid as a program name
574	
575	  Note that in general the semantics of a given field aren't
576	  interpreted when applying a modifier to it, but there are some
577	  restrictions to be aware of in this regard:
578	
579	    - only the 'hex' modifier can be used for values (because values
580	      are essentially sums, and the other modifiers don't make sense
581	      in that context).
582	    - the 'execname' modifier can only be used on a 'common_pid'.  The
583	      reason for this is that the execname is simply the 'comm' value
584	      saved for the 'current' process when an event was triggered,
585	      which is the same as the common_pid value saved by the event
586	      tracing code.  Trying to apply that comm value to other pid
587	      values wouldn't be correct, and typically events that care save
588	      pid-specific comm fields in the event itself.
589	
590	  A typical usage scenario would be the following to enable a hist
591	  trigger, read its current contents, and then turn it off:
592	
593	  # echo 'hist:keys=skbaddr.hex:vals=len' > \
594	    /sys/kernel/debug/tracing/events/net/netif_rx/trigger
595	
596	  # cat /sys/kernel/debug/tracing/events/net/netif_rx/hist
597	
598	  # echo '!hist:keys=skbaddr.hex:vals=len' > \
599	    /sys/kernel/debug/tracing/events/net/netif_rx/trigger
600	
601	  The trigger file itself can be read to show the details of the
602	  currently attached hist trigger.  This information is also displayed
603	  at the top of the 'hist' file when read.
604	
605	  By default, the size of the hash table is 2048 entries.  The 'size'
606	  parameter can be used to specify more or fewer than that.  The units
607	  are in terms of hashtable entries - if a run uses more entries than
608	  specified, the results will show the number of 'drops', the number
609	  of hits that were ignored.  The size should be a power of 2 between
610	  128 and 131072 (any non- power-of-2 number specified will be rounded
611	  up).
612	
613	  The 'sort' parameter can be used to specify a value field to sort
614	  on.  The default if unspecified is 'hitcount' and the default sort
615	  order is 'ascending'.  To sort in the opposite direction, append
616	  .descending' to the sort key.
617	
618	  The 'pause' parameter can be used to pause an existing hist trigger
619	  or to start a hist trigger but not log any events until told to do
620	  so.  'continue' or 'cont' can be used to start or restart a paused
621	  hist trigger.
622	
623	  The 'clear' parameter will clear the contents of a running hist
624	  trigger and leave its current paused/active state.
625	
626	  Note that the 'pause', 'cont', and 'clear' parameters should be
627	  applied using 'append' shell operator ('>>') if applied to an
628	  existing trigger, rather than via the '>' operator, which will cause
629	  the trigger to be removed through truncation.
630	
631	- enable_hist/disable_hist
632	
633	  The enable_hist and disable_hist triggers can be used to have one
634	  event conditionally start and stop another event's already-attached
635	  hist trigger.  Any number of enable_hist and disable_hist triggers
636	  can be attached to a given event, allowing that event to kick off
637	  and stop aggregations on a host of other events.
638	
639	  The format is very similar to the enable/disable_event triggers:
640	
641	      enable_hist:<system>:<event>[:count]
642	      disable_hist:<system>:<event>[:count]
643	
644	  Instead of enabling or disabling the tracing of the target event
645	  into the trace buffer as the enable/disable_event triggers do, the
646	  enable/disable_hist triggers enable or disable the aggregation of
647	  the target event into a hash table.
648	
649	  A typical usage scenario for the enable_hist/disable_hist triggers
650	  would be to first set up a paused hist trigger on some event,
651	  followed by an enable_hist/disable_hist pair that turns the hist
652	  aggregation on and off when conditions of interest are hit:
653	
654	  # echo 'hist:keys=skbaddr.hex:vals=len:pause' > \
655	    /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
656	
657	  # echo 'enable_hist:net:netif_receive_skb if filename==/usr/bin/wget' > \
658	    /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger
659	
660	  # echo 'disable_hist:net:netif_receive_skb if comm==wget' > \
661	    /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger
662	
663	  The above sets up an initially paused hist trigger which is unpaused
664	  and starts aggregating events when a given program is executed, and
665	  which stops aggregating when the process exits and the hist trigger
666	  is paused again.
667	
668	  The examples below provide a more concrete illustration of the
669	  concepts and typical usage patterns discussed above.
670	
671	
672	6.2 'hist' trigger examples
673	---------------------------
674	
675	  The first set of examples creates aggregations using the kmalloc
676	  event.  The fields that can be used for the hist trigger are listed
677	  in the kmalloc event's format file:
678	
679	    # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/format
680	    name: kmalloc
681	    ID: 374
682	    format:
683		field:unsigned short common_type;	offset:0;	size:2;	signed:0;
684		field:unsigned char common_flags;	offset:2;	size:1;	signed:0;
685		field:unsigned char common_preempt_count;		offset:3;	size:1;	signed:0;
686		field:int common_pid;					offset:4;	size:4;	signed:1;
687	
688		field:unsigned long call_site;				offset:8;	size:8;	signed:0;
689		field:const void * ptr;					offset:16;	size:8;	signed:0;
690		field:size_t bytes_req;					offset:24;	size:8;	signed:0;
691		field:size_t bytes_alloc;				offset:32;	size:8;	signed:0;
692		field:gfp_t gfp_flags;					offset:40;	size:4;	signed:0;
693	
694	  We'll start by creating a hist trigger that generates a simple table
695	  that lists the total number of bytes requested for each function in
696	  the kernel that made one or more calls to kmalloc:
697	
698	    # echo 'hist:key=call_site:val=bytes_req' > \
699	            /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
700	
701	  This tells the tracing system to create a 'hist' trigger using the
702	  call_site field of the kmalloc event as the key for the table, which
703	  just means that each unique call_site address will have an entry
704	  created for it in the table.  The 'val=bytes_req' parameter tells
705	  the hist trigger that for each unique entry (call_site) in the
706	  table, it should keep a running total of the number of bytes
707	  requested by that call_site.
708	
709	  We'll let it run for awhile and then dump the contents of the 'hist'
710	  file in the kmalloc event's subdirectory (for readability, a number
711	  of entries have been omitted):
712	
713	    # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist
714	    # trigger info: hist:keys=call_site:vals=bytes_req:sort=hitcount:size=2048 [active]
715	
716	    { call_site: 18446744072106379007 } hitcount:          1  bytes_req:        176
717	    { call_site: 18446744071579557049 } hitcount:          1  bytes_req:       1024
718	    { call_site: 18446744071580608289 } hitcount:          1  bytes_req:      16384
719	    { call_site: 18446744071581827654 } hitcount:          1  bytes_req:         24
720	    { call_site: 18446744071580700980 } hitcount:          1  bytes_req:          8
721	    { call_site: 18446744071579359876 } hitcount:          1  bytes_req:        152
722	    { call_site: 18446744071580795365 } hitcount:          3  bytes_req:        144
723	    { call_site: 18446744071581303129 } hitcount:          3  bytes_req:        144
724	    { call_site: 18446744071580713234 } hitcount:          4  bytes_req:       2560
725	    { call_site: 18446744071580933750 } hitcount:          4  bytes_req:        736
726	    .
727	    .
728	    .
729	    { call_site: 18446744072106047046 } hitcount:         69  bytes_req:       5576
730	    { call_site: 18446744071582116407 } hitcount:         73  bytes_req:       2336
731	    { call_site: 18446744072106054684 } hitcount:        136  bytes_req:     140504
732	    { call_site: 18446744072106224230 } hitcount:        136  bytes_req:      19584
733	    { call_site: 18446744072106078074 } hitcount:        153  bytes_req:       2448
734	    { call_site: 18446744072106062406 } hitcount:        153  bytes_req:      36720
735	    { call_site: 18446744071582507929 } hitcount:        153  bytes_req:      37088
736	    { call_site: 18446744072102520590 } hitcount:        273  bytes_req:      10920
737	    { call_site: 18446744071582143559 } hitcount:        358  bytes_req:        716
738	    { call_site: 18446744072106465852 } hitcount:        417  bytes_req:      56712
739	    { call_site: 18446744072102523378 } hitcount:        485  bytes_req:      27160
740	    { call_site: 18446744072099568646 } hitcount:       1676  bytes_req:      33520
741	
742	    Totals:
743	        Hits: 4610
744	        Entries: 45
745	        Dropped: 0
746	
747	  The output displays a line for each entry, beginning with the key
748	  specified in the trigger, followed by the value(s) also specified in
749	  the trigger.  At the beginning of the output is a line that displays
750	  the trigger info, which can also be displayed by reading the
751	  'trigger' file:
752	
753	    # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
754	    hist:keys=call_site:vals=bytes_req:sort=hitcount:size=2048 [active]
755	
756	  At the end of the output are a few lines that display the overall
757	  totals for the run.  The 'Hits' field shows the total number of
758	  times the event trigger was hit, the 'Entries' field shows the total
759	  number of used entries in the hash table, and the 'Dropped' field
760	  shows the number of hits that were dropped because the number of
761	  used entries for the run exceeded the maximum number of entries
762	  allowed for the table (normally 0, but if not a hint that you may
763	  want to increase the size of the table using the 'size' parameter).
764	
765	  Notice in the above output that there's an extra field, 'hitcount',
766	  which wasn't specified in the trigger.  Also notice that in the
767	  trigger info output, there's a parameter, 'sort=hitcount', which
768	  wasn't specified in the trigger either.  The reason for that is that
769	  every trigger implicitly keeps a count of the total number of hits
770	  attributed to a given entry, called the 'hitcount'.  That hitcount
771	  information is explicitly displayed in the output, and in the
772	  absence of a user-specified sort parameter, is used as the default
773	  sort field.
774	
775	  The value 'hitcount' can be used in place of an explicit value in
776	  the 'values' parameter if you don't really need to have any
777	  particular field summed and are mainly interested in hit
778	  frequencies.
779	
780	  To turn the hist trigger off, simply call up the trigger in the
781	  command history and re-execute it with a '!' prepended:
782	
783	    # echo '!hist:key=call_site:val=bytes_req' > \
784	           /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
785	
786	  Finally, notice that the call_site as displayed in the output above
787	  isn't really very useful.  It's an address, but normally addresses
788	  are displayed in hex.  To have a numeric field displayed as a hex
789	  value, simply append '.hex' to the field name in the trigger:
790	
791	    # echo 'hist:key=call_site.hex:val=bytes_req' > \
792	           /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
793	
794	    # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist
795	    # trigger info: hist:keys=call_site.hex:vals=bytes_req:sort=hitcount:size=2048 [active]
796	
797	    { call_site: ffffffffa026b291 } hitcount:          1  bytes_req:        433
798	    { call_site: ffffffffa07186ff } hitcount:          1  bytes_req:        176
799	    { call_site: ffffffff811ae721 } hitcount:          1  bytes_req:      16384
800	    { call_site: ffffffff811c5134 } hitcount:          1  bytes_req:          8
801	    { call_site: ffffffffa04a9ebb } hitcount:          1  bytes_req:        511
802	    { call_site: ffffffff8122e0a6 } hitcount:          1  bytes_req:         12
803	    { call_site: ffffffff8107da84 } hitcount:          1  bytes_req:        152
804	    { call_site: ffffffff812d8246 } hitcount:          1  bytes_req:         24
805	    { call_site: ffffffff811dc1e5 } hitcount:          3  bytes_req:        144
806	    { call_site: ffffffffa02515e8 } hitcount:          3  bytes_req:        648
807	    { call_site: ffffffff81258159 } hitcount:          3  bytes_req:        144
808	    { call_site: ffffffff811c80f4 } hitcount:          4  bytes_req:        544
809	    .
810	    .
811	    .
812	    { call_site: ffffffffa06c7646 } hitcount:        106  bytes_req:       8024
813	    { call_site: ffffffffa06cb246 } hitcount:        132  bytes_req:      31680
814	    { call_site: ffffffffa06cef7a } hitcount:        132  bytes_req:       2112
815	    { call_site: ffffffff8137e399 } hitcount:        132  bytes_req:      23232
816	    { call_site: ffffffffa06c941c } hitcount:        185  bytes_req:     171360
817	    { call_site: ffffffffa06f2a66 } hitcount:        185  bytes_req:      26640
818	    { call_site: ffffffffa036a70e } hitcount:        265  bytes_req:      10600
819	    { call_site: ffffffff81325447 } hitcount:        292  bytes_req:        584
820	    { call_site: ffffffffa072da3c } hitcount:        446  bytes_req:      60656
821	    { call_site: ffffffffa036b1f2 } hitcount:        526  bytes_req:      29456
822	    { call_site: ffffffffa0099c06 } hitcount:       1780  bytes_req:      35600
823	
824	    Totals:
825	        Hits: 4775
826	        Entries: 46
827	        Dropped: 0
828	
829	  Even that's only marginally more useful - while hex values do look
830	  more like addresses, what users are typically more interested in
831	  when looking at text addresses are the corresponding symbols
832	  instead.  To have an address displayed as symbolic value instead,
833	  simply append '.sym' or '.sym-offset' to the field name in the
834	  trigger:
835	
836	    # echo 'hist:key=call_site.sym:val=bytes_req' > \
837	           /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
838	
839	    # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist
840	    # trigger info: hist:keys=call_site.sym:vals=bytes_req:sort=hitcount:size=2048 [active]
841	
842	    { call_site: [ffffffff810adcb9] syslog_print_all                              } hitcount:          1  bytes_req:       1024
843	    { call_site: [ffffffff8154bc62] usb_control_msg                               } hitcount:          1  bytes_req:          8
844	    { call_site: [ffffffffa00bf6fe] hidraw_send_report [hid]                      } hitcount:          1  bytes_req:          7
845	    { call_site: [ffffffff8154acbe] usb_alloc_urb                                 } hitcount:          1  bytes_req:        192
846	    { call_site: [ffffffffa00bf1ca] hidraw_report_event [hid]                     } hitcount:          1  bytes_req:          7
847	    { call_site: [ffffffff811e3a25] __seq_open_private                            } hitcount:          1  bytes_req:         40
848	    { call_site: [ffffffff8109524a] alloc_fair_sched_group                        } hitcount:          2  bytes_req:        128
849	    { call_site: [ffffffff811febd5] fsnotify_alloc_group                          } hitcount:          2  bytes_req:        528
850	    { call_site: [ffffffff81440f58] __tty_buffer_request_room                     } hitcount:          2  bytes_req:       2624
851	    { call_site: [ffffffff81200ba6] inotify_new_group                             } hitcount:          2  bytes_req:         96
852	    { call_site: [ffffffffa05e19af] ieee80211_start_tx_ba_session [mac80211]      } hitcount:          2  bytes_req:        464
853	    { call_site: [ffffffff81672406] tcp_get_metrics                               } hitcount:          2  bytes_req:        304
854	    { call_site: [ffffffff81097ec2] alloc_rt_sched_group                          } hitcount:          2  bytes_req:        128
855	    { call_site: [ffffffff81089b05] sched_create_group                            } hitcount:          2  bytes_req:       1424
856	    .
857	    .
858	    .
859	    { call_site: [ffffffffa04a580c] intel_crtc_page_flip [i915]                   } hitcount:       1185  bytes_req:     123240
860	    { call_site: [ffffffffa0287592] drm_mode_page_flip_ioctl [drm]                } hitcount:       1185  bytes_req:     104280
861	    { call_site: [ffffffffa04c4a3c] intel_plane_duplicate_state [i915]            } hitcount:       1402  bytes_req:     190672
862	    { call_site: [ffffffff812891ca] ext4_find_extent                              } hitcount:       1518  bytes_req:     146208
863	    { call_site: [ffffffffa029070e] drm_vma_node_allow [drm]                      } hitcount:       1746  bytes_req:      69840
864	    { call_site: [ffffffffa045e7c4] i915_gem_do_execbuffer.isra.23 [i915]         } hitcount:       2021  bytes_req:     792312
865	    { call_site: [ffffffffa02911f2] drm_modeset_lock_crtc [drm]                   } hitcount:       2592  bytes_req:     145152
866	    { call_site: [ffffffffa0489a66] intel_ring_begin [i915]                       } hitcount:       2629  bytes_req:     378576
867	    { call_site: [ffffffffa046041c] i915_gem_execbuffer2 [i915]                   } hitcount:       2629  bytes_req:    3783248
868	    { call_site: [ffffffff81325607] apparmor_file_alloc_security                  } hitcount:       5192  bytes_req:      10384
869	    { call_site: [ffffffffa00b7c06] hid_report_raw_event [hid]                    } hitcount:       5529  bytes_req:     110584
870	    { call_site: [ffffffff8131ebf7] aa_alloc_task_context                         } hitcount:      21943  bytes_req:     702176
871	    { call_site: [ffffffff8125847d] ext4_htree_store_dirent                       } hitcount:      55759  bytes_req:    5074265
872	
873	    Totals:
874	        Hits: 109928
875	        Entries: 71
876	        Dropped: 0
877	
878	  Because the default sort key above is 'hitcount', the above shows a
879	  the list of call_sites by increasing hitcount, so that at the bottom
880	  we see the functions that made the most kmalloc calls during the
881	  run.  If instead we we wanted to see the top kmalloc callers in
882	  terms of the number of bytes requested rather than the number of
883	  calls, and we wanted the top caller to appear at the top, we can use
884	  the 'sort' parameter, along with the 'descending' modifier:
885	
886	    # echo 'hist:key=call_site.sym:val=bytes_req:sort=bytes_req.descending' > \
887	           /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
888	
889	    # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist
890	    # trigger info: hist:keys=call_site.sym:vals=bytes_req:sort=bytes_req.descending:size=2048 [active]
891	
892	    { call_site: [ffffffffa046041c] i915_gem_execbuffer2 [i915]                   } hitcount:       2186  bytes_req:    3397464
893	    { call_site: [ffffffffa045e7c4] i915_gem_do_execbuffer.isra.23 [i915]         } hitcount:       1790  bytes_req:     712176
894	    { call_site: [ffffffff8125847d] ext4_htree_store_dirent                       } hitcount:       8132  bytes_req:     513135
895	    { call_site: [ffffffff811e2a1b] seq_buf_alloc                                 } hitcount:        106  bytes_req:     440128
896	    { call_site: [ffffffffa0489a66] intel_ring_begin [i915]                       } hitcount:       2186  bytes_req:     314784
897	    { call_site: [ffffffff812891ca] ext4_find_extent                              } hitcount:       2174  bytes_req:     208992
898	    { call_site: [ffffffff811ae8e1] __kmalloc                                     } hitcount:          8  bytes_req:     131072
899	    { call_site: [ffffffffa04c4a3c] intel_plane_duplicate_state [i915]            } hitcount:        859  bytes_req:     116824
900	    { call_site: [ffffffffa02911f2] drm_modeset_lock_crtc [drm]                   } hitcount:       1834  bytes_req:     102704
901	    { call_site: [ffffffffa04a580c] intel_crtc_page_flip [i915]                   } hitcount:        972  bytes_req:     101088
902	    { call_site: [ffffffffa0287592] drm_mode_page_flip_ioctl [drm]                } hitcount:        972  bytes_req:      85536
903	    { call_site: [ffffffffa00b7c06] hid_report_raw_event [hid]                    } hitcount:       3333  bytes_req:      66664
904	    { call_site: [ffffffff8137e559] sg_kmalloc                                    } hitcount:        209  bytes_req:      61632
905	    .
906	    .
907	    .
908	    { call_site: [ffffffff81095225] alloc_fair_sched_group                        } hitcount:          2  bytes_req:        128
909	    { call_site: [ffffffff81097ec2] alloc_rt_sched_group                          } hitcount:          2  bytes_req:        128
910	    { call_site: [ffffffff812d8406] copy_semundo                                  } hitcount:          2  bytes_req:         48
911	    { call_site: [ffffffff81200ba6] inotify_new_group                             } hitcount:          1  bytes_req:         48
912	    { call_site: [ffffffffa027121a] drm_getmagic [drm]                            } hitcount:          1  bytes_req:         48
913	    { call_site: [ffffffff811e3a25] __seq_open_private                            } hitcount:          1  bytes_req:         40
914	    { call_site: [ffffffff811c52f4] bprm_change_interp                            } hitcount:          2  bytes_req:         16
915	    { call_site: [ffffffff8154bc62] usb_control_msg                               } hitcount:          1  bytes_req:          8
916	    { call_site: [ffffffffa00bf1ca] hidraw_report_event [hid]                     } hitcount:          1  bytes_req:          7
917	    { call_site: [ffffffffa00bf6fe] hidraw_send_report [hid]                      } hitcount:          1  bytes_req:          7
918	
919	    Totals:
920	        Hits: 32133
921	        Entries: 81
922	        Dropped: 0
923	
924	  To display the offset and size information in addition to the symbol
925	  name, just use 'sym-offset' instead:
926	
927	    # echo 'hist:key=call_site.sym-offset:val=bytes_req:sort=bytes_req.descending' > \
928	           /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
929	
930	    # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist
931	    # trigger info: hist:keys=call_site.sym-offset:vals=bytes_req:sort=bytes_req.descending:size=2048 [active]
932	
933	    { call_site: [ffffffffa046041c] i915_gem_execbuffer2+0x6c/0x2c0 [i915]                  } hitcount:       4569  bytes_req:    3163720
934	    { call_site: [ffffffffa0489a66] intel_ring_begin+0xc6/0x1f0 [i915]                      } hitcount:       4569  bytes_req:     657936
935	    { call_site: [ffffffffa045e7c4] i915_gem_do_execbuffer.isra.23+0x694/0x1020 [i915]      } hitcount:       1519  bytes_req:     472936
936	    { call_site: [ffffffffa045e646] i915_gem_do_execbuffer.isra.23+0x516/0x1020 [i915]      } hitcount:       3050  bytes_req:     211832
937	    { call_site: [ffffffff811e2a1b] seq_buf_alloc+0x1b/0x50                                 } hitcount:         34  bytes_req:     148384
938	    { call_site: [ffffffffa04a580c] intel_crtc_page_flip+0xbc/0x870 [i915]                  } hitcount:       1385  bytes_req:     144040
939	    { call_site: [ffffffff811ae8e1] __kmalloc+0x191/0x1b0                                   } hitcount:          8  bytes_req:     131072
940	    { call_site: [ffffffffa0287592] drm_mode_page_flip_ioctl+0x282/0x360 [drm]              } hitcount:       1385  bytes_req:     121880
941	    { call_site: [ffffffffa02911f2] drm_modeset_lock_crtc+0x32/0x100 [drm]                  } hitcount:       1848  bytes_req:     103488
942	    { call_site: [ffffffffa04c4a3c] intel_plane_duplicate_state+0x2c/0xa0 [i915]            } hitcount:        461  bytes_req:      62696
943	    { call_site: [ffffffffa029070e] drm_vma_node_allow+0x2e/0xd0 [drm]                      } hitcount:       1541  bytes_req:      61640
944	    { call_site: [ffffffff815f8d7b] sk_prot_alloc+0xcb/0x1b0                                } hitcount:         57  bytes_req:      57456
945	    .
946	    .
947	    .
948	    { call_site: [ffffffff8109524a] alloc_fair_sched_group+0x5a/0x1a0                       } hitcount:          2  bytes_req:        128
949	    { call_site: [ffffffffa027b921] drm_vm_open_locked+0x31/0xa0 [drm]                      } hitcount:          3  bytes_req:         96
950	    { call_site: [ffffffff8122e266] proc_self_follow_link+0x76/0xb0                         } hitcount:          8  bytes_req:         96
951	    { call_site: [ffffffff81213e80] load_elf_binary+0x240/0x1650                            } hitcount:          3  bytes_req:         84
952	    { call_site: [ffffffff8154bc62] usb_control_msg+0x42/0x110                              } hitcount:          1  bytes_req:          8
953	    { call_site: [ffffffffa00bf6fe] hidraw_send_report+0x7e/0x1a0 [hid]                     } hitcount:          1  bytes_req:          7
954	    { call_site: [ffffffffa00bf1ca] hidraw_report_event+0x8a/0x120 [hid]                    } hitcount:          1  bytes_req:          7
955	
956	    Totals:
957	        Hits: 26098
958	        Entries: 64
959	        Dropped: 0
960	
961	  We can also add multiple fields to the 'values' parameter.  For
962	  example, we might want to see the total number of bytes allocated
963	  alongside bytes requested, and display the result sorted by bytes
964	  allocated in a descending order:
965	
966	    # echo 'hist:keys=call_site.sym:values=bytes_req,bytes_alloc:sort=bytes_alloc.descending' > \
967	           /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
968	
969	    # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist
970	    # trigger info: hist:keys=call_site.sym:vals=bytes_req,bytes_alloc:sort=bytes_alloc.descending:size=2048 [active]
971	
972	    { call_site: [ffffffffa046041c] i915_gem_execbuffer2 [i915]                   } hitcount:       7403  bytes_req:    4084360  bytes_alloc:    5958016
973	    { call_site: [ffffffff811e2a1b] seq_buf_alloc                                 } hitcount:        541  bytes_req:    2213968  bytes_alloc:    2228224
974	    { call_site: [ffffffffa0489a66] intel_ring_begin [i915]                       } hitcount:       7404  bytes_req:    1066176  bytes_alloc:    1421568
975	    { call_site: [ffffffffa045e7c4] i915_gem_do_execbuffer.isra.23 [i915]         } hitcount:       1565  bytes_req:     557368  bytes_alloc:    1037760
976	    { call_site: [ffffffff8125847d] ext4_htree_store_dirent                       } hitcount:       9557  bytes_req:     595778  bytes_alloc:     695744
977	    { call_site: [ffffffffa045e646] i915_gem_do_execbuffer.isra.23 [i915]         } hitcount:       5839  bytes_req:     430680  bytes_alloc:     470400
978	    { call_site: [ffffffffa04c4a3c] intel_plane_duplicate_state [i915]            } hitcount:       2388  bytes_req:     324768  bytes_alloc:     458496
979	    { call_site: [ffffffffa02911f2] drm_modeset_lock_crtc [drm]                   } hitcount:       3911  bytes_req:     219016  bytes_alloc:     250304
980	    { call_site: [ffffffff815f8d7b] sk_prot_alloc                                 } hitcount:        235  bytes_req:     236880  bytes_alloc:     240640
981	    { call_site: [ffffffff8137e559] sg_kmalloc                                    } hitcount:        557  bytes_req:     169024  bytes_alloc:     221760
982	    { call_site: [ffffffffa00b7c06] hid_report_raw_event [hid]                    } hitcount:       9378  bytes_req:     187548  bytes_alloc:     206312
983	    { call_site: [ffffffffa04a580c] intel_crtc_page_flip [i915]                   } hitcount:       1519  bytes_req:     157976  bytes_alloc:     194432
984	    .
985	    .
986	    .
987	    { call_site: [ffffffff8109bd3b] sched_autogroup_create_attach                 } hitcount:          2  bytes_req:        144  bytes_alloc:        192
988	    { call_site: [ffffffff81097ee8] alloc_rt_sched_group                          } hitcount:          2  bytes_req:        128  bytes_alloc:        128
989	    { call_site: [ffffffff8109524a] alloc_fair_sched_group                        } hitcount:          2  bytes_req:        128  bytes_alloc:        128
990	    { call_site: [ffffffff81095225] alloc_fair_sched_group                        } hitcount:          2  bytes_req:        128  bytes_alloc:        128
991	    { call_site: [ffffffff81097ec2] alloc_rt_sched_group                          } hitcount:          2  bytes_req:        128  bytes_alloc:        128
992	    { call_site: [ffffffff81213e80] load_elf_binary                               } hitcount:          3  bytes_req:         84  bytes_alloc:         96
993	    { call_site: [ffffffff81079a2e] kthread_create_on_node                        } hitcount:          1  bytes_req:         56  bytes_alloc:         64
994	    { call_site: [ffffffffa00bf6fe] hidraw_send_report [hid]                      } hitcount:          1  bytes_req:          7  bytes_alloc:          8
995	    { call_site: [ffffffff8154bc62] usb_control_msg                               } hitcount:          1  bytes_req:          8  bytes_alloc:          8
996	    { call_site: [ffffffffa00bf1ca] hidraw_report_event [hid]                     } hitcount:          1  bytes_req:          7  bytes_alloc:          8
997	
998	    Totals:
999	        Hits: 66598
1000	        Entries: 65
1001	        Dropped: 0
1002	
1003	  Finally, to finish off our kmalloc example, instead of simply having
1004	  the hist trigger display symbolic call_sites, we can have the hist
1005	  trigger additionally display the complete set of kernel stack traces
1006	  that led to each call_site.  To do that, we simply use the special
1007	  value 'stacktrace' for the key parameter:
1008	
1009	    # echo 'hist:keys=stacktrace:values=bytes_req,bytes_alloc:sort=bytes_alloc' > \
1010	           /sys/kernel/debug/tracing/events/kmem/kmalloc/trigger
1011	
1012	  The above trigger will use the kernel stack trace in effect when an
1013	  event is triggered as the key for the hash table.  This allows the
1014	  enumeration of every kernel callpath that led up to a particular
1015	  event, along with a running total of any of the event fields for
1016	  that event.  Here we tally bytes requested and bytes allocated for
1017	  every callpath in the system that led up to a kmalloc (in this case
1018	  every callpath to a kmalloc for a kernel compile):
1019	
1020	    # cat /sys/kernel/debug/tracing/events/kmem/kmalloc/hist
1021	    # trigger info: hist:keys=stacktrace:vals=bytes_req,bytes_alloc:sort=bytes_alloc:size=2048 [active]
1022	
1023	    { stacktrace:
1024	         __kmalloc_track_caller+0x10b/0x1a0
1025	         kmemdup+0x20/0x50
1026	         hidraw_report_event+0x8a/0x120 [hid]
1027	         hid_report_raw_event+0x3ea/0x440 [hid]
1028	         hid_input_report+0x112/0x190 [hid]
1029	         hid_irq_in+0xc2/0x260 [usbhid]
1030	         __usb_hcd_giveback_urb+0x72/0x120
1031	         usb_giveback_urb_bh+0x9e/0xe0
1032	         tasklet_hi_action+0xf8/0x100
1033	         __do_softirq+0x114/0x2c0
1034	         irq_exit+0xa5/0xb0
1035	         do_IRQ+0x5a/0xf0
1036	         ret_from_intr+0x0/0x30
1037	         cpuidle_enter+0x17/0x20
1038	         cpu_startup_entry+0x315/0x3e0
1039	         rest_init+0x7c/0x80
1040	    } hitcount:          3  bytes_req:         21  bytes_alloc:         24
1041	    { stacktrace:
1042	         __kmalloc_track_caller+0x10b/0x1a0
1043	         kmemdup+0x20/0x50
1044	         hidraw_report_event+0x8a/0x120 [hid]
1045	         hid_report_raw_event+0x3ea/0x440 [hid]
1046	         hid_input_report+0x112/0x190 [hid]
1047	         hid_irq_in+0xc2/0x260 [usbhid]
1048	         __usb_hcd_giveback_urb+0x72/0x120
1049	         usb_giveback_urb_bh+0x9e/0xe0
1050	         tasklet_hi_action+0xf8/0x100
1051	         __do_softirq+0x114/0x2c0
1052	         irq_exit+0xa5/0xb0
1053	         do_IRQ+0x5a/0xf0
1054	         ret_from_intr+0x0/0x30
1055	    } hitcount:          3  bytes_req:         21  bytes_alloc:         24
1056	    { stacktrace:
1057	         kmem_cache_alloc_trace+0xeb/0x150
1058	         aa_alloc_task_context+0x27/0x40
1059	         apparmor_cred_prepare+0x1f/0x50
1060	         security_prepare_creds+0x16/0x20
1061	         prepare_creds+0xdf/0x1a0
1062	         SyS_capset+0xb5/0x200
1063	         system_call_fastpath+0x12/0x6a
1064	    } hitcount:          1  bytes_req:         32  bytes_alloc:         32
1065	    .
1066	    .
1067	    .
1068	    { stacktrace:
1069	         __kmalloc+0x11b/0x1b0
1070	         i915_gem_execbuffer2+0x6c/0x2c0 [i915]
1071	         drm_ioctl+0x349/0x670 [drm]
1072	         do_vfs_ioctl+0x2f0/0x4f0
1073	         SyS_ioctl+0x81/0xa0
1074	         system_call_fastpath+0x12/0x6a
1075	    } hitcount:      17726  bytes_req:   13944120  bytes_alloc:   19593808
1076	    { stacktrace:
1077	         __kmalloc+0x11b/0x1b0
1078	         load_elf_phdrs+0x76/0xa0
1079	         load_elf_binary+0x102/0x1650
1080	         search_binary_handler+0x97/0x1d0
1081	         do_execveat_common.isra.34+0x551/0x6e0
1082	         SyS_execve+0x3a/0x50
1083	         return_from_execve+0x0/0x23
1084	    } hitcount:      33348  bytes_req:   17152128  bytes_alloc:   20226048
1085	    { stacktrace:
1086	         kmem_cache_alloc_trace+0xeb/0x150
1087	         apparmor_file_alloc_security+0x27/0x40
1088	         security_file_alloc+0x16/0x20
1089	         get_empty_filp+0x93/0x1c0
1090	         path_openat+0x31/0x5f0
1091	         do_filp_open+0x3a/0x90
1092	         do_sys_open+0x128/0x220
1093	         SyS_open+0x1e/0x20
1094	         system_call_fastpath+0x12/0x6a
1095	    } hitcount:    4766422  bytes_req:    9532844  bytes_alloc:   38131376
1096	    { stacktrace:
1097	         __kmalloc+0x11b/0x1b0
1098	         seq_buf_alloc+0x1b/0x50
1099	         seq_read+0x2cc/0x370
1100	         proc_reg_read+0x3d/0x80
1101	         __vfs_read+0x28/0xe0
1102	         vfs_read+0x86/0x140
1103	         SyS_read+0x46/0xb0
1104	         system_call_fastpath+0x12/0x6a
1105	    } hitcount:      19133  bytes_req:   78368768  bytes_alloc:   78368768
1106	
1107	    Totals:
1108	        Hits: 6085872
1109	        Entries: 253
1110	        Dropped: 0
1111	
1112	  If you key a hist trigger on common_pid, in order for example to
1113	  gather and display sorted totals for each process, you can use the
1114	  special .execname modifier to display the executable names for the
1115	  processes in the table rather than raw pids.  The example below
1116	  keeps a per-process sum of total bytes read:
1117	
1118	    # echo 'hist:key=common_pid.execname:val=count:sort=count.descending' > \
1119	           /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/trigger
1120	
1121	    # cat /sys/kernel/debug/tracing/events/syscalls/sys_enter_read/hist
1122	    # trigger info: hist:keys=common_pid.execname:vals=count:sort=count.descending:size=2048 [active]
1123	
1124	    { common_pid: gnome-terminal  [      3196] } hitcount:        280  count:    1093512
1125	    { common_pid: Xorg            [      1309] } hitcount:        525  count:     256640
1126	    { common_pid: compiz          [      2889] } hitcount:         59  count:     254400
1127	    { common_pid: bash            [      8710] } hitcount:          3  count:      66369
1128	    { common_pid: dbus-daemon-lau [      8703] } hitcount:         49  count:      47739
1129	    { common_pid: irqbalance      [      1252] } hitcount:         27  count:      27648
1130	    { common_pid: 01ifupdown      [      8705] } hitcount:          3  count:      17216
1131	    { common_pid: dbus-daemon     [       772] } hitcount:         10  count:      12396
1132	    { common_pid: Socket Thread   [      8342] } hitcount:         11  count:      11264
1133	    { common_pid: nm-dhcp-client. [      8701] } hitcount:          6  count:       7424
1134	    { common_pid: gmain           [      1315] } hitcount:         18  count:       6336
1135	    .
1136	    .
1137	    .
1138	    { common_pid: postgres        [      1892] } hitcount:          2  count:         32
1139	    { common_pid: postgres        [      1891] } hitcount:          2  count:         32
1140	    { common_pid: gmain           [      8704] } hitcount:          2  count:         32
1141	    { common_pid: upstart-dbus-br [      2740] } hitcount:         21  count:         21
1142	    { common_pid: nm-dispatcher.a [      8696] } hitcount:          1  count:         16
1143	    { common_pid: indicator-datet [      2904] } hitcount:          1  count:         16
1144	    { common_pid: gdbus           [      2998] } hitcount:          1  count:         16
1145	    { common_pid: rtkit-daemon    [      2052] } hitcount:          1  count:          8
1146	    { common_pid: init            [         1] } hitcount:          2  count:          2
1147	
1148	    Totals:
1149	        Hits: 2116
1150	        Entries: 51
1151	        Dropped: 0
1152	
1153	  Similarly, if you key a hist trigger on syscall id, for example to
1154	  gather and display a list of systemwide syscall hits, you can use
1155	  the special .syscall modifier to display the syscall names rather
1156	  than raw ids.  The example below keeps a running total of syscall
1157	  counts for the system during the run:
1158	
1159	    # echo 'hist:key=id.syscall:val=hitcount' > \
1160	           /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger
1161	
1162	    # cat /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/hist
1163	    # trigger info: hist:keys=id.syscall:vals=hitcount:sort=hitcount:size=2048 [active]
1164	
1165	    { id: sys_fsync                     [ 74] } hitcount:          1
1166	    { id: sys_newuname                  [ 63] } hitcount:          1
1167	    { id: sys_prctl                     [157] } hitcount:          1
1168	    { id: sys_statfs                    [137] } hitcount:          1
1169	    { id: sys_symlink                   [ 88] } hitcount:          1
1170	    { id: sys_sendmmsg                  [307] } hitcount:          1
1171	    { id: sys_semctl                    [ 66] } hitcount:          1
1172	    { id: sys_readlink                  [ 89] } hitcount:          3
1173	    { id: sys_bind                      [ 49] } hitcount:          3
1174	    { id: sys_getsockname               [ 51] } hitcount:          3
1175	    { id: sys_unlink                    [ 87] } hitcount:          3
1176	    { id: sys_rename                    [ 82] } hitcount:          4
1177	    { id: unknown_syscall               [ 58] } hitcount:          4
1178	    { id: sys_connect                   [ 42] } hitcount:          4
1179	    { id: sys_getpid                    [ 39] } hitcount:          4
1180	    .
1181	    .
1182	    .
1183	    { id: sys_rt_sigprocmask            [ 14] } hitcount:        952
1184	    { id: sys_futex                     [202] } hitcount:       1534
1185	    { id: sys_write                     [  1] } hitcount:       2689
1186	    { id: sys_setitimer                 [ 38] } hitcount:       2797
1187	    { id: sys_read                      [  0] } hitcount:       3202
1188	    { id: sys_select                    [ 23] } hitcount:       3773
1189	    { id: sys_writev                    [ 20] } hitcount:       4531
1190	    { id: sys_poll                      [  7] } hitcount:       8314
1191	    { id: sys_recvmsg                   [ 47] } hitcount:      13738
1192	    { id: sys_ioctl                     [ 16] } hitcount:      21843
1193	
1194	    Totals:
1195	        Hits: 67612
1196	        Entries: 72
1197	        Dropped: 0
1198	
1199	    The syscall counts above provide a rough overall picture of system
1200	    call activity on the system; we can see for example that the most
1201	    popular system call on this system was the 'sys_ioctl' system call.
1202	
1203	    We can use 'compound' keys to refine that number and provide some
1204	    further insight as to which processes exactly contribute to the
1205	    overall ioctl count.
1206	
1207	    The command below keeps a hitcount for every unique combination of
1208	    system call id and pid - the end result is essentially a table
1209	    that keeps a per-pid sum of system call hits.  The results are
1210	    sorted using the system call id as the primary key, and the
1211	    hitcount sum as the secondary key:
1212	
1213	    # echo 'hist:key=id.syscall,common_pid.execname:val=hitcount:sort=id,hitcount' > \
1214	           /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger
1215	
1216	    # cat /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/hist
1217	    # trigger info: hist:keys=id.syscall,common_pid.execname:vals=hitcount:sort=id.syscall,hitcount:size=2048 [active]
1218	
1219	    { id: sys_read                      [  0], common_pid: rtkit-daemon    [      1877] } hitcount:          1
1220	    { id: sys_read                      [  0], common_pid: gdbus           [      2976] } hitcount:          1
1221	    { id: sys_read                      [  0], common_pid: console-kit-dae [      3400] } hitcount:          1
1222	    { id: sys_read                      [  0], common_pid: postgres        [      1865] } hitcount:          1
1223	    { id: sys_read                      [  0], common_pid: deja-dup-monito [      3543] } hitcount:          2
1224	    { id: sys_read                      [  0], common_pid: NetworkManager  [       890] } hitcount:          2
1225	    { id: sys_read                      [  0], common_pid: evolution-calen [      3048] } hitcount:          2
1226	    { id: sys_read                      [  0], common_pid: postgres        [      1864] } hitcount:          2
1227	    { id: sys_read                      [  0], common_pid: nm-applet       [      3022] } hitcount:          2
1228	    { id: sys_read                      [  0], common_pid: whoopsie        [      1212] } hitcount:          2
1229	    .
1230	    .
1231	    .
1232	    { id: sys_ioctl                     [ 16], common_pid: bash            [      8479] } hitcount:          1
1233	    { id: sys_ioctl                     [ 16], common_pid: bash            [      3472] } hitcount:         12
1234	    { id: sys_ioctl                     [ 16], common_pid: gnome-terminal  [      3199] } hitcount:         16
1235	    { id: sys_ioctl                     [ 16], common_pid: Xorg            [      1267] } hitcount:       1808
1236	    { id: sys_ioctl                     [ 16], common_pid: compiz          [      2994] } hitcount:       5580
1237	    .
1238	    .
1239	    .
1240	    { id: sys_waitid                    [247], common_pid: upstart-dbus-br [      2690] } hitcount:          3
1241	    { id: sys_waitid                    [247], common_pid: upstart-dbus-br [      2688] } hitcount:         16
1242	    { id: sys_inotify_add_watch         [254], common_pid: gmain           [       975] } hitcount:          2
1243	    { id: sys_inotify_add_watch         [254], common_pid: gmain           [      3204] } hitcount:          4
1244	    { id: sys_inotify_add_watch         [254], common_pid: gmain           [      2888] } hitcount:          4
1245	    { id: sys_inotify_add_watch         [254], common_pid: gmain           [      3003] } hitcount:          4
1246	    { id: sys_inotify_add_watch         [254], common_pid: gmain           [      2873] } hitcount:          4
1247	    { id: sys_inotify_add_watch         [254], common_pid: gmain           [      3196] } hitcount:          6
1248	    { id: sys_openat                    [257], common_pid: java            [      2623] } hitcount:          2
1249	    { id: sys_eventfd2                  [290], common_pid: ibus-ui-gtk3    [      2760] } hitcount:          4
1250	    { id: sys_eventfd2                  [290], common_pid: compiz          [      2994] } hitcount:          6
1251	
1252	    Totals:
1253	        Hits: 31536
1254	        Entries: 323
1255	        Dropped: 0
1256	
1257	    The above list does give us a breakdown of the ioctl syscall by
1258	    pid, but it also gives us quite a bit more than that, which we
1259	    don't really care about at the moment.  Since we know the syscall
1260	    id for sys_ioctl (16, displayed next to the sys_ioctl name), we
1261	    can use that to filter out all the other syscalls:
1262	
1263	    # echo 'hist:key=id.syscall,common_pid.execname:val=hitcount:sort=id,hitcount if id == 16' > \
1264	           /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/trigger
1265	
1266	    # cat /sys/kernel/debug/tracing/events/raw_syscalls/sys_enter/hist
1267	    # trigger info: hist:keys=id.syscall,common_pid.execname:vals=hitcount:sort=id.syscall,hitcount:size=2048 if id == 16 [active]
1268	
1269	    { id: sys_ioctl                     [ 16], common_pid: gmain           [      2769] } hitcount:          1
1270	    { id: sys_ioctl                     [ 16], common_pid: evolution-addre [      8571] } hitcount:          1
1271	    { id: sys_ioctl                     [ 16], common_pid: gmain           [      3003] } hitcount:          1
1272	    { id: sys_ioctl                     [ 16], common_pid: gmain           [      2781] } hitcount:          1
1273	    { id: sys_ioctl                     [ 16], common_pid: gmain           [      2829] } hitcount:          1
1274	    { id: sys_ioctl                     [ 16], common_pid: bash            [      8726] } hitcount:          1
1275	    { id: sys_ioctl                     [ 16], common_pid: bash            [      8508] } hitcount:          1
1276	    { id: sys_ioctl                     [ 16], common_pid: gmain           [      2970] } hitcount:          1
1277	    { id: sys_ioctl                     [ 16], common_pid: gmain           [      2768] } hitcount:          1
1278	    .
1279	    .
1280	    .
1281	    { id: sys_ioctl                     [ 16], common_pid: pool            [      8559] } hitcount:         45
1282	    { id: sys_ioctl                     [ 16], common_pid: pool            [      8555] } hitcount:         48
1283	    { id: sys_ioctl                     [ 16], common_pid: pool            [      8551] } hitcount:         48
1284	    { id: sys_ioctl                     [ 16], common_pid: avahi-daemon    [       896] } hitcount:         66
1285	    { id: sys_ioctl                     [ 16], common_pid: Xorg            [      1267] } hitcount:      26674
1286	    { id: sys_ioctl                     [ 16], common_pid: compiz          [      2994] } hitcount:      73443
1287	
1288	    Totals:
1289	        Hits: 101162
1290	        Entries: 103
1291	        Dropped: 0
1292	
1293	    The above output shows that 'compiz' and 'Xorg' are far and away
1294	    the heaviest ioctl callers (which might lead to questions about
1295	    whether they really need to be making all those calls and to
1296	    possible avenues for further investigation.)
1297	
1298	    The compound key examples used a key and a sum value (hitcount) to
1299	    sort the output, but we can just as easily use two keys instead.
1300	    Here's an example where we use a compound key composed of the the
1301	    common_pid and size event fields.  Sorting with pid as the primary
1302	    key and 'size' as the secondary key allows us to display an
1303	    ordered summary of the recvfrom sizes, with counts, received by
1304	    each process:
1305	
1306	    # echo 'hist:key=common_pid.execname,size:val=hitcount:sort=common_pid,size' > \
1307	           /sys/kernel/debug/tracing/events/syscalls/sys_enter_recvfrom/trigger
1308	
1309	    # cat /sys/kernel/debug/tracing/events/syscalls/sys_enter_recvfrom/hist
1310	    # trigger info: hist:keys=common_pid.execname,size:vals=hitcount:sort=common_pid.execname,size:size=2048 [active]
1311	
1312	    { common_pid: smbd            [       784], size:          4 } hitcount:          1
1313	    { common_pid: dnsmasq         [      1412], size:       4096 } hitcount:        672
1314	    { common_pid: postgres        [      1796], size:       1000 } hitcount:          6
1315	    { common_pid: postgres        [      1867], size:       1000 } hitcount:         10
1316	    { common_pid: bamfdaemon      [      2787], size:         28 } hitcount:          2
1317	    { common_pid: bamfdaemon      [      2787], size:      14360 } hitcount:          1
1318	    { common_pid: compiz          [      2994], size:          8 } hitcount:          1
1319	    { common_pid: compiz          [      2994], size:         20 } hitcount:         11
1320	    { common_pid: gnome-terminal  [      3199], size:          4 } hitcount:          2
1321	    { common_pid: firefox         [      8817], size:          4 } hitcount:          1
1322	    { common_pid: firefox         [      8817], size:          8 } hitcount:          5
1323	    { common_pid: firefox         [      8817], size:        588 } hitcount:          2
1324	    { common_pid: firefox         [      8817], size:        628 } hitcount:          1
1325	    { common_pid: firefox         [      8817], size:       6944 } hitcount:          1
1326	    { common_pid: firefox         [      8817], size:     408880 } hitcount:          2
1327	    { common_pid: firefox         [      8822], size:          8 } hitcount:          2
1328	    { common_pid: firefox         [      8822], size:        160 } hitcount:          2
1329	    { common_pid: firefox         [      8822], size:        320 } hitcount:          2
1330	    { common_pid: firefox         [      8822], size:        352 } hitcount:          1
1331	    .
1332	    .
1333	    .
1334	    { common_pid: pool            [      8923], size:       1960 } hitcount:         10
1335	    { common_pid: pool            [      8923], size:       2048 } hitcount:         10
1336	    { common_pid: pool            [      8924], size:       1960 } hitcount:         10
1337	    { common_pid: pool            [      8924], size:       2048 } hitcount:         10
1338	    { common_pid: pool            [      8928], size:       1964 } hitcount:          4
1339	    { common_pid: pool            [      8928], size:       1965 } hitcount:          2
1340	    { common_pid: pool            [      8928], size:       2048 } hitcount:          6
1341	    { common_pid: pool            [      8929], size:       1982 } hitcount:          1
1342	    { common_pid: pool            [      8929], size:       2048 } hitcount:          1
1343	
1344	    Totals:
1345	        Hits: 2016
1346	        Entries: 224
1347	        Dropped: 0
1348	
1349	  The above example also illustrates the fact that although a compound
1350	  key is treated as a single entity for hashing purposes, the sub-keys
1351	  it's composed of can be accessed independently.
1352	
1353	  The next example uses a string field as the hash key and
1354	  demonstrates how you can manually pause and continue a hist trigger.
1355	  In this example, we'll aggregate fork counts and don't expect a
1356	  large number of entries in the hash table, so we'll drop it to a
1357	  much smaller number, say 256:
1358	
1359	    # echo 'hist:key=child_comm:val=hitcount:size=256' > \
1360	           /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger
1361	
1362	    # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist
1363	    # trigger info: hist:keys=child_comm:vals=hitcount:sort=hitcount:size=256 [active]
1364	
1365	    { child_comm: dconf worker                        } hitcount:          1
1366	    { child_comm: ibus-daemon                         } hitcount:          1
1367	    { child_comm: whoopsie                            } hitcount:          1
1368	    { child_comm: smbd                                } hitcount:          1
1369	    { child_comm: gdbus                               } hitcount:          1
1370	    { child_comm: kthreadd                            } hitcount:          1
1371	    { child_comm: dconf worker                        } hitcount:          1
1372	    { child_comm: evolution-alarm                     } hitcount:          2
1373	    { child_comm: Socket Thread                       } hitcount:          2
1374	    { child_comm: postgres                            } hitcount:          2
1375	    { child_comm: bash                                } hitcount:          3
1376	    { child_comm: compiz                              } hitcount:          3
1377	    { child_comm: evolution-sourc                     } hitcount:          4
1378	    { child_comm: dhclient                            } hitcount:          4
1379	    { child_comm: pool                                } hitcount:          5
1380	    { child_comm: nm-dispatcher.a                     } hitcount:          8
1381	    { child_comm: firefox                             } hitcount:          8
1382	    { child_comm: dbus-daemon                         } hitcount:          8
1383	    { child_comm: glib-pacrunner                      } hitcount:         10
1384	    { child_comm: evolution                           } hitcount:         23
1385	
1386	    Totals:
1387	        Hits: 89
1388	        Entries: 20
1389	        Dropped: 0
1390	
1391	  If we want to pause the hist trigger, we can simply append :pause to
1392	  the command that started the trigger.  Notice that the trigger info
1393	  displays as [paused]:
1394	
1395	    # echo 'hist:key=child_comm:val=hitcount:size=256:pause' >> \
1396	           /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger
1397	
1398	    # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist
1399	    # trigger info: hist:keys=child_comm:vals=hitcount:sort=hitcount:size=256 [paused]
1400	
1401	    { child_comm: dconf worker                        } hitcount:          1
1402	    { child_comm: kthreadd                            } hitcount:          1
1403	    { child_comm: dconf worker                        } hitcount:          1
1404	    { child_comm: gdbus                               } hitcount:          1
1405	    { child_comm: ibus-daemon                         } hitcount:          1
1406	    { child_comm: Socket Thread                       } hitcount:          2
1407	    { child_comm: evolution-alarm                     } hitcount:          2
1408	    { child_comm: smbd                                } hitcount:          2
1409	    { child_comm: bash                                } hitcount:          3
1410	    { child_comm: whoopsie                            } hitcount:          3
1411	    { child_comm: compiz                              } hitcount:          3
1412	    { child_comm: evolution-sourc                     } hitcount:          4
1413	    { child_comm: pool                                } hitcount:          5
1414	    { child_comm: postgres                            } hitcount:          6
1415	    { child_comm: firefox                             } hitcount:          8
1416	    { child_comm: dhclient                            } hitcount:         10
1417	    { child_comm: emacs                               } hitcount:         12
1418	    { child_comm: dbus-daemon                         } hitcount:         20
1419	    { child_comm: nm-dispatcher.a                     } hitcount:         20
1420	    { child_comm: evolution                           } hitcount:         35
1421	    { child_comm: glib-pacrunner                      } hitcount:         59
1422	
1423	    Totals:
1424	        Hits: 199
1425	        Entries: 21
1426	        Dropped: 0
1427	
1428	  To manually continue having the trigger aggregate events, append
1429	  :cont instead.  Notice that the trigger info displays as [active]
1430	  again, and the data has changed:
1431	
1432	    # echo 'hist:key=child_comm:val=hitcount:size=256:cont' >> \
1433	           /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger
1434	
1435	    # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist
1436	    # trigger info: hist:keys=child_comm:vals=hitcount:sort=hitcount:size=256 [active]
1437	
1438	    { child_comm: dconf worker                        } hitcount:          1
1439	    { child_comm: dconf worker                        } hitcount:          1
1440	    { child_comm: kthreadd                            } hitcount:          1
1441	    { child_comm: gdbus                               } hitcount:          1
1442	    { child_comm: ibus-daemon                         } hitcount:          1
1443	    { child_comm: Socket Thread                       } hitcount:          2
1444	    { child_comm: evolution-alarm                     } hitcount:          2
1445	    { child_comm: smbd                                } hitcount:          2
1446	    { child_comm: whoopsie                            } hitcount:          3
1447	    { child_comm: compiz                              } hitcount:          3
1448	    { child_comm: evolution-sourc                     } hitcount:          4
1449	    { child_comm: bash                                } hitcount:          5
1450	    { child_comm: pool                                } hitcount:          5
1451	    { child_comm: postgres                            } hitcount:          6
1452	    { child_comm: firefox                             } hitcount:          8
1453	    { child_comm: dhclient                            } hitcount:         11
1454	    { child_comm: emacs                               } hitcount:         12
1455	    { child_comm: dbus-daemon                         } hitcount:         22
1456	    { child_comm: nm-dispatcher.a                     } hitcount:         22
1457	    { child_comm: evolution                           } hitcount:         35
1458	    { child_comm: glib-pacrunner                      } hitcount:         59
1459	
1460	    Totals:
1461	        Hits: 206
1462	        Entries: 21
1463	        Dropped: 0
1464	
1465	  The previous example showed how to start and stop a hist trigger by
1466	  appending 'pause' and 'continue' to the hist trigger command.  A
1467	  hist trigger can also be started in a paused state by initially
1468	  starting the trigger with ':pause' appended.  This allows you to
1469	  start the trigger only when you're ready to start collecting data
1470	  and not before.  For example, you could start the trigger in a
1471	  paused state, then unpause it and do something you want to measure,
1472	  then pause the trigger again when done.
1473	
1474	  Of course, doing this manually can be difficult and error-prone, but
1475	  it is possible to automatically start and stop a hist trigger based
1476	  on some condition, via the enable_hist and disable_hist triggers.
1477	
1478	  For example, suppose we wanted to take a look at the relative
1479	  weights in terms of skb length for each callpath that leads to a
1480	  netif_receieve_skb event when downloading a decent-sized file using
1481	  wget.
1482	
1483	  First we set up an initially paused stacktrace trigger on the
1484	  netif_receive_skb event:
1485	
1486	    # echo 'hist:key=stacktrace:vals=len:pause' > \
1487	           /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
1488	
1489	  Next, we set up an 'enable_hist' trigger on the sched_process_exec
1490	  event, with an 'if filename==/usr/bin/wget' filter.  The effect of
1491	  this new trigger is that it will 'unpause' the hist trigger we just
1492	  set up on netif_receive_skb if and only if it sees a
1493	  sched_process_exec event with a filename of '/usr/bin/wget'.  When
1494	  that happens, all netif_receive_skb events are aggregated into a
1495	  hash table keyed on stacktrace:
1496	
1497	    # echo 'enable_hist:net:netif_receive_skb if filename==/usr/bin/wget' > \
1498	           /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger
1499	
1500	  The aggregation continues until the netif_receive_skb is paused
1501	  again, which is what the following disable_hist event does by
1502	  creating a similar setup on the sched_process_exit event, using the
1503	  filter 'comm==wget':
1504	
1505	    # echo 'disable_hist:net:netif_receive_skb if comm==wget' > \
1506	           /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger
1507	
1508	  Whenever a process exits and the comm field of the disable_hist
1509	  trigger filter matches 'comm==wget', the netif_receive_skb hist
1510	  trigger is disabled.
1511	
1512	  The overall effect is that netif_receive_skb events are aggregated
1513	  into the hash table for only the duration of the wget.  Executing a
1514	  wget command and then listing the 'hist' file will display the
1515	  output generated by the wget command:
1516	
1517	    $ wget https://www.kernel.org/pub/linux/kernel/v3.x/patch-3.19.xz
1518	
1519	    # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist
1520	    # trigger info: hist:keys=stacktrace:vals=len:sort=hitcount:size=2048 [paused]
1521	
1522	    { stacktrace:
1523	         __netif_receive_skb_core+0x46d/0x990
1524	         __netif_receive_skb+0x18/0x60
1525	         netif_receive_skb_internal+0x23/0x90
1526	         napi_gro_receive+0xc8/0x100
1527	         ieee80211_deliver_skb+0xd6/0x270 [mac80211]
1528	         ieee80211_rx_handlers+0xccf/0x22f0 [mac80211]
1529	         ieee80211_prepare_and_rx_handle+0x4e7/0xc40 [mac80211]
1530	         ieee80211_rx+0x31d/0x900 [mac80211]
1531	         iwlagn_rx_reply_rx+0x3db/0x6f0 [iwldvm]
1532	         iwl_rx_dispatch+0x8e/0xf0 [iwldvm]
1533	         iwl_pcie_irq_handler+0xe3c/0x12f0 [iwlwifi]
1534	         irq_thread_fn+0x20/0x50
1535	         irq_thread+0x11f/0x150
1536	         kthread+0xd2/0xf0
1537	         ret_from_fork+0x42/0x70
1538	    } hitcount:         85  len:      28884
1539	    { stacktrace:
1540	         __netif_receive_skb_core+0x46d/0x990
1541	         __netif_receive_skb+0x18/0x60
1542	         netif_receive_skb_internal+0x23/0x90
1543	         napi_gro_complete+0xa4/0xe0
1544	         dev_gro_receive+0x23a/0x360
1545	         napi_gro_receive+0x30/0x100
1546	         ieee80211_deliver_skb+0xd6/0x270 [mac80211]
1547	         ieee80211_rx_handlers+0xccf/0x22f0 [mac80211]
1548	         ieee80211_prepare_and_rx_handle+0x4e7/0xc40 [mac80211]
1549	         ieee80211_rx+0x31d/0x900 [mac80211]
1550	         iwlagn_rx_reply_rx+0x3db/0x6f0 [iwldvm]
1551	         iwl_rx_dispatch+0x8e/0xf0 [iwldvm]
1552	         iwl_pcie_irq_handler+0xe3c/0x12f0 [iwlwifi]
1553	         irq_thread_fn+0x20/0x50
1554	         irq_thread+0x11f/0x150
1555	         kthread+0xd2/0xf0
1556	    } hitcount:         98  len:     664329
1557	    { stacktrace:
1558	         __netif_receive_skb_core+0x46d/0x990
1559	         __netif_receive_skb+0x18/0x60
1560	         process_backlog+0xa8/0x150
1561	         net_rx_action+0x15d/0x340
1562	         __do_softirq+0x114/0x2c0
1563	         do_softirq_own_stack+0x1c/0x30
1564	         do_softirq+0x65/0x70
1565	         __local_bh_enable_ip+0xb5/0xc0
1566	         ip_finish_output+0x1f4/0x840
1567	         ip_output+0x6b/0xc0
1568	         ip_local_out_sk+0x31/0x40
1569	         ip_send_skb+0x1a/0x50
1570	         udp_send_skb+0x173/0x2a0
1571	         udp_sendmsg+0x2bf/0x9f0
1572	         inet_sendmsg+0x64/0xa0
1573	         sock_sendmsg+0x3d/0x50
1574	    } hitcount:        115  len:      13030
1575	    { stacktrace:
1576	         __netif_receive_skb_core+0x46d/0x990
1577	         __netif_receive_skb+0x18/0x60
1578	         netif_receive_skb_internal+0x23/0x90
1579	         napi_gro_complete+0xa4/0xe0
1580	         napi_gro_flush+0x6d/0x90
1581	         iwl_pcie_irq_handler+0x92a/0x12f0 [iwlwifi]
1582	         irq_thread_fn+0x20/0x50
1583	         irq_thread+0x11f/0x150
1584	         kthread+0xd2/0xf0
1585	         ret_from_fork+0x42/0x70
1586	    } hitcount:        934  len:    5512212
1587	
1588	    Totals:
1589	        Hits: 1232
1590	        Entries: 4
1591	        Dropped: 0
1592	
1593	  The above shows all the netif_receive_skb callpaths and their total
1594	  lengths for the duration of the wget command.
1595	
1596	  The 'clear' hist trigger param can be used to clear the hash table.
1597	  Suppose we wanted to try another run of the previous example but
1598	  this time also wanted to see the complete list of events that went
1599	  into the histogram.  In order to avoid having to set everything up
1600	  again, we can just clear the histogram first:
1601	
1602	    # echo 'hist:key=stacktrace:vals=len:clear' >> \
1603	           /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
1604	
1605	  Just to verify that it is in fact cleared, here's what we now see in
1606	  the hist file:
1607	
1608	    # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist
1609	    # trigger info: hist:keys=stacktrace:vals=len:sort=hitcount:size=2048 [paused]
1610	
1611	    Totals:
1612	        Hits: 0
1613	        Entries: 0
1614	        Dropped: 0
1615	
1616	  Since we want to see the detailed list of every netif_receive_skb
1617	  event occurring during the new run, which are in fact the same
1618	  events being aggregated into the hash table, we add some additional
1619	  'enable_event' events to the triggering sched_process_exec and
1620	  sched_process_exit events as such:
1621	
1622	    # echo 'enable_event:net:netif_receive_skb if filename==/usr/bin/wget' > \
1623	           /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger
1624	
1625	    # echo 'disable_event:net:netif_receive_skb if comm==wget' > \
1626	           /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger
1627	
1628	  If you read the trigger files for the sched_process_exec and
1629	  sched_process_exit triggers, you should see two triggers for each:
1630	  one enabling/disabling the hist aggregation and the other
1631	  enabling/disabling the logging of events:
1632	
1633	    # cat /sys/kernel/debug/tracing/events/sched/sched_process_exec/trigger
1634	    enable_event:net:netif_receive_skb:unlimited if filename==/usr/bin/wget
1635	    enable_hist:net:netif_receive_skb:unlimited if filename==/usr/bin/wget
1636	
1637	    # cat /sys/kernel/debug/tracing/events/sched/sched_process_exit/trigger
1638	    enable_event:net:netif_receive_skb:unlimited if comm==wget
1639	    disable_hist:net:netif_receive_skb:unlimited if comm==wget
1640	
1641	  In other words, whenever either of the sched_process_exec or
1642	  sched_process_exit events is hit and matches 'wget', it enables or
1643	  disables both the histogram and the event log, and what you end up
1644	  with is a hash table and set of events just covering the specified
1645	  duration.  Run the wget command again:
1646	
1647	    $ wget https://www.kernel.org/pub/linux/kernel/v3.x/patch-3.19.xz
1648	
1649	  Displaying the 'hist' file should show something similar to what you
1650	  saw in the last run, but this time you should also see the
1651	  individual events in the trace file:
1652	
1653	    # cat /sys/kernel/debug/tracing/trace
1654	
1655	    # tracer: nop
1656	    #
1657	    # entries-in-buffer/entries-written: 183/1426   #P:4
1658	    #
1659	    #                              _-----=> irqs-off
1660	    #                             / _----=> need-resched
1661	    #                            | / _---=> hardirq/softirq
1662	    #                            || / _--=> preempt-depth
1663	    #                            ||| /     delay
1664	    #           TASK-PID   CPU#  ||||    TIMESTAMP  FUNCTION
1665	    #              | |       |   ||||       |         |
1666	                wget-15108 [000] ..s1 31769.606929: netif_receive_skb: dev=lo skbaddr=ffff88009c353100 len=60
1667	                wget-15108 [000] ..s1 31769.606999: netif_receive_skb: dev=lo skbaddr=ffff88009c353200 len=60
1668	             dnsmasq-1382  [000] ..s1 31769.677652: netif_receive_skb: dev=lo skbaddr=ffff88009c352b00 len=130
1669	             dnsmasq-1382  [000] ..s1 31769.685917: netif_receive_skb: dev=lo skbaddr=ffff88009c352200 len=138
1670	    ##### CPU 2 buffer started ####
1671	      irq/29-iwlwifi-559   [002] ..s. 31772.031529: netif_receive_skb: dev=wlan0 skbaddr=ffff88009d433d00 len=2948
1672	      irq/29-iwlwifi-559   [002] ..s. 31772.031572: netif_receive_skb: dev=wlan0 skbaddr=ffff88009d432200 len=1500
1673	      irq/29-iwlwifi-559   [002] ..s. 31772.032196: netif_receive_skb: dev=wlan0 skbaddr=ffff88009d433100 len=2948
1674	      irq/29-iwlwifi-559   [002] ..s. 31772.032761: netif_receive_skb: dev=wlan0 skbaddr=ffff88009d433000 len=2948
1675	      irq/29-iwlwifi-559   [002] ..s. 31772.033220: netif_receive_skb: dev=wlan0 skbaddr=ffff88009d432e00 len=1500
1676	    .
1677	    .
1678	    .
1679	
1680	  The following example demonstrates how multiple hist triggers can be
1681	  attached to a given event.  This capability can be useful for
1682	  creating a set of different summaries derived from the same set of
1683	  events, or for comparing the effects of different filters, among
1684	  other things.
1685	
1686	    # echo 'hist:keys=skbaddr.hex:vals=len if len < 0' >> \
1687	           /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
1688	    # echo 'hist:keys=skbaddr.hex:vals=len if len > 4096' >> \
1689	           /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
1690	    # echo 'hist:keys=skbaddr.hex:vals=len if len == 256' >> \
1691	           /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
1692	    # echo 'hist:keys=skbaddr.hex:vals=len' >> \
1693	           /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
1694	    # echo 'hist:keys=len:vals=common_preempt_count' >> \
1695	           /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
1696	
1697	  The above set of commands create four triggers differing only in
1698	  their filters, along with a completely different though fairly
1699	  nonsensical trigger.  Note that in order to append multiple hist
1700	  triggers to the same file, you should use the '>>' operator to
1701	  append them ('>' will also add the new hist trigger, but will remove
1702	  any existing hist triggers beforehand).
1703	
1704	  Displaying the contents of the 'hist' file for the event shows the
1705	  contents of all five histograms:
1706	
1707	    # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist
1708	
1709	    # event histogram
1710	    #
1711	    # trigger info: hist:keys=len:vals=hitcount,common_preempt_count:sort=hitcount:size=2048 [active]
1712	    #
1713	
1714	    { len:        176 } hitcount:          1  common_preempt_count:          0
1715	    { len:        223 } hitcount:          1  common_preempt_count:          0
1716	    { len:       4854 } hitcount:          1  common_preempt_count:          0
1717	    { len:        395 } hitcount:          1  common_preempt_count:          0
1718	    { len:        177 } hitcount:          1  common_preempt_count:          0
1719	    { len:        446 } hitcount:          1  common_preempt_count:          0
1720	    { len:       1601 } hitcount:          1  common_preempt_count:          0
1721	    .
1722	    .
1723	    .
1724	    { len:       1280 } hitcount:         66  common_preempt_count:          0
1725	    { len:        116 } hitcount:         81  common_preempt_count:         40
1726	    { len:        708 } hitcount:        112  common_preempt_count:          0
1727	    { len:         46 } hitcount:        221  common_preempt_count:          0
1728	    { len:       1264 } hitcount:        458  common_preempt_count:          0
1729	
1730	    Totals:
1731	        Hits: 1428
1732	        Entries: 147
1733	        Dropped: 0
1734	
1735	
1736	    # event histogram
1737	    #
1738	    # trigger info: hist:keys=skbaddr.hex:vals=hitcount,len:sort=hitcount:size=2048 [active]
1739	    #
1740	
1741	    { skbaddr: ffff8800baee5e00 } hitcount:          1  len:        130
1742	    { skbaddr: ffff88005f3d5600 } hitcount:          1  len:       1280
1743	    { skbaddr: ffff88005f3d4900 } hitcount:          1  len:       1280
1744	    { skbaddr: ffff88009fed6300 } hitcount:          1  len:        115
1745	    { skbaddr: ffff88009fe0ad00 } hitcount:          1  len:        115
1746	    { skbaddr: ffff88008cdb1900 } hitcount:          1  len:         46
1747	    { skbaddr: ffff880064b5ef00 } hitcount:          1  len:        118
1748	    { skbaddr: ffff880044e3c700 } hitcount:          1  len:         60
1749	    { skbaddr: ffff880100065900 } hitcount:          1  len:         46
1750	    { skbaddr: ffff8800d46bd500 } hitcount:          1  len:        116
1751	    { skbaddr: ffff88005f3d5f00 } hitcount:          1  len:       1280
1752	    { skbaddr: ffff880100064700 } hitcount:          1  len:        365
1753	    { skbaddr: ffff8800badb6f00 } hitcount:          1  len:         60
1754	    .
1755	    .
1756	    .
1757	    { skbaddr: ffff88009fe0be00 } hitcount:         27  len:      24677
1758	    { skbaddr: ffff88009fe0a400 } hitcount:         27  len:      23052
1759	    { skbaddr: ffff88009fe0b700 } hitcount:         31  len:      25589
1760	    { skbaddr: ffff88009fe0b600 } hitcount:         32  len:      27326
1761	    { skbaddr: ffff88006a462800 } hitcount:         68  len:      71678
1762	    { skbaddr: ffff88006a463700 } hitcount:         70  len:      72678
1763	    { skbaddr: ffff88006a462b00 } hitcount:         71  len:      77589
1764	    { skbaddr: ffff88006a463600 } hitcount:         73  len:      71307
1765	    { skbaddr: ffff88006a462200 } hitcount:         81  len:      81032
1766	
1767	    Totals:
1768	        Hits: 1451
1769	        Entries: 318
1770	        Dropped: 0
1771	
1772	
1773	    # event histogram
1774	    #
1775	    # trigger info: hist:keys=skbaddr.hex:vals=hitcount,len:sort=hitcount:size=2048 if len == 256 [active]
1776	    #
1777	
1778	
1779	    Totals:
1780	        Hits: 0
1781	        Entries: 0
1782	        Dropped: 0
1783	
1784	
1785	    # event histogram
1786	    #
1787	    # trigger info: hist:keys=skbaddr.hex:vals=hitcount,len:sort=hitcount:size=2048 if len > 4096 [active]
1788	    #
1789	
1790	    { skbaddr: ffff88009fd2c300 } hitcount:          1  len:       7212
1791	    { skbaddr: ffff8800d2bcce00 } hitcount:          1  len:       7212
1792	    { skbaddr: ffff8800d2bcd700 } hitcount:          1  len:       7212
1793	    { skbaddr: ffff8800d2bcda00 } hitcount:          1  len:      21492
1794	    { skbaddr: ffff8800ae2e2d00 } hitcount:          1  len:       7212
1795	    { skbaddr: ffff8800d2bcdb00 } hitcount:          1  len:       7212
1796	    { skbaddr: ffff88006a4df500 } hitcount:          1  len:       4854
1797	    { skbaddr: ffff88008ce47b00 } hitcount:          1  len:      18636
1798	    { skbaddr: ffff8800ae2e2200 } hitcount:          1  len:      12924
1799	    { skbaddr: ffff88005f3e1000 } hitcount:          1  len:       4356
1800	    { skbaddr: ffff8800d2bcdc00 } hitcount:          2  len:      24420
1801	    { skbaddr: ffff8800d2bcc200 } hitcount:          2  len:      12996
1802	
1803	    Totals:
1804	        Hits: 14
1805	        Entries: 12
1806	        Dropped: 0
1807	
1808	
1809	    # event histogram
1810	    #
1811	    # trigger info: hist:keys=skbaddr.hex:vals=hitcount,len:sort=hitcount:size=2048 if len < 0 [active]
1812	    #
1813	
1814	
1815	    Totals:
1816	        Hits: 0
1817	        Entries: 0
1818	        Dropped: 0
1819	
1820	  Named triggers can be used to have triggers share a common set of
1821	  histogram data.  This capability is mostly useful for combining the
1822	  output of events generated by tracepoints contained inside inline
1823	  functions, but names can be used in a hist trigger on any event.
1824	  For example, these two triggers when hit will update the same 'len'
1825	  field in the shared 'foo' histogram data:
1826	
1827	    # echo 'hist:name=foo:keys=skbaddr.hex:vals=len' > \
1828	           /sys/kernel/debug/tracing/events/net/netif_receive_skb/trigger
1829	    # echo 'hist:name=foo:keys=skbaddr.hex:vals=len' > \
1830	           /sys/kernel/debug/tracing/events/net/netif_rx/trigger
1831	
1832	  You can see that they're updating common histogram data by reading
1833	  each event's hist files at the same time:
1834	
1835	    # cat /sys/kernel/debug/tracing/events/net/netif_receive_skb/hist;
1836	      cat /sys/kernel/debug/tracing/events/net/netif_rx/hist
1837	
1838	    # event histogram
1839	    #
1840	    # trigger info: hist:name=foo:keys=skbaddr.hex:vals=hitcount,len:sort=hitcount:size=2048 [active]
1841	    #
1842	
1843	    { skbaddr: ffff88000ad53500 } hitcount:          1  len:         46
1844	    { skbaddr: ffff8800af5a1500 } hitcount:          1  len:         76
1845	    { skbaddr: ffff8800d62a1900 } hitcount:          1  len:         46
1846	    { skbaddr: ffff8800d2bccb00 } hitcount:          1  len:        468
1847	    { skbaddr: ffff8800d3c69900 } hitcount:          1  len:         46
1848	    { skbaddr: ffff88009ff09100 } hitcount:          1  len:         52
1849	    { skbaddr: ffff88010f13ab00 } hitcount:          1  len:        168
1850	    { skbaddr: ffff88006a54f400 } hitcount:          1  len:         46
1851	    { skbaddr: ffff8800d2bcc500 } hitcount:          1  len:        260
1852	    { skbaddr: ffff880064505000 } hitcount:          1  len:         46
1853	    { skbaddr: ffff8800baf24e00 } hitcount:          1  len:         32
1854	    { skbaddr: ffff88009fe0ad00 } hitcount:          1  len:         46
1855	    { skbaddr: ffff8800d3edff00 } hitcount:          1  len:         44
1856	    { skbaddr: ffff88009fe0b400 } hitcount:          1  len:        168
1857	    { skbaddr: ffff8800a1c55a00 } hitcount:          1  len:         40
1858	    { skbaddr: ffff8800d2bcd100 } hitcount:          1  len:         40
1859	    { skbaddr: ffff880064505f00 } hitcount:          1  len:        174
1860	    { skbaddr: ffff8800a8bff200 } hitcount:          1  len:        160
1861	    { skbaddr: ffff880044e3cc00 } hitcount:          1  len:         76
1862	    { skbaddr: ffff8800a8bfe700 } hitcount:          1  len:         46
1863	    { skbaddr: ffff8800d2bcdc00 } hitcount:          1  len:         32
1864	    { skbaddr: ffff8800a1f64800 } hitcount:          1  len:         46
1865	    { skbaddr: ffff8800d2bcde00 } hitcount:          1  len:        988
1866	    { skbaddr: ffff88006a5dea00 } hitcount:          1  len:         46
1867	    { skbaddr: ffff88002e37a200 } hitcount:          1  len:         44
1868	    { skbaddr: ffff8800a1f32c00 } hitcount:          2  len:        676
1869	    { skbaddr: ffff88000ad52600 } hitcount:          2  len:        107
1870	    { skbaddr: ffff8800a1f91e00 } hitcount:          2  len:         92
1871	    { skbaddr: ffff8800af5a0200 } hitcount:          2  len:        142
1872	    { skbaddr: ffff8800d2bcc600 } hitcount:          2  len:        220
1873	    { skbaddr: ffff8800ba36f500 } hitcount:          2  len:         92
1874	    { skbaddr: ffff8800d021f800 } hitcount:          2  len:         92
1875	    { skbaddr: ffff8800a1f33600 } hitcount:          2  len:        675
1876	    { skbaddr: ffff8800a8bfff00 } hitcount:          3  len:        138
1877	    { skbaddr: ffff8800d62a1300 } hitcount:          3  len:        138
1878	    { skbaddr: ffff88002e37a100 } hitcount:          4  len:        184
1879	    { skbaddr: ffff880064504400 } hitcount:          4  len:        184
1880	    { skbaddr: ffff8800a8bfec00 } hitcount:          4  len:        184
1881	    { skbaddr: ffff88000ad53700 } hitcount:          5  len:        230
1882	    { skbaddr: ffff8800d2bcdb00 } hitcount:          5  len:        196
1883	    { skbaddr: ffff8800a1f90000 } hitcount:          6  len:        276
1884	    { skbaddr: ffff88006a54f900 } hitcount:          6  len:        276
1885	
1886	    Totals:
1887	        Hits: 81
1888	        Entries: 42
1889	        Dropped: 0
1890	    # event histogram
1891	    #
1892	    # trigger info: hist:name=foo:keys=skbaddr.hex:vals=hitcount,len:sort=hitcount:size=2048 [active]
1893	    #
1894	
1895	    { skbaddr: ffff88000ad53500 } hitcount:          1  len:         46
1896	    { skbaddr: ffff8800af5a1500 } hitcount:          1  len:         76
1897	    { skbaddr: ffff8800d62a1900 } hitcount:          1  len:         46
1898	    { skbaddr: ffff8800d2bccb00 } hitcount:          1  len:        468
1899	    { skbaddr: ffff8800d3c69900 } hitcount:          1  len:         46
1900	    { skbaddr: ffff88009ff09100 } hitcount:          1  len:         52
1901	    { skbaddr: ffff88010f13ab00 } hitcount:          1  len:        168
1902	    { skbaddr: ffff88006a54f400 } hitcount:          1  len:         46
1903	    { skbaddr: ffff8800d2bcc500 } hitcount:          1  len:        260
1904	    { skbaddr: ffff880064505000 } hitcount:          1  len:         46
1905	    { skbaddr: ffff8800baf24e00 } hitcount:          1  len:         32
1906	    { skbaddr: ffff88009fe0ad00 } hitcount:          1  len:         46
1907	    { skbaddr: ffff8800d3edff00 } hitcount:          1  len:         44
1908	    { skbaddr: ffff88009fe0b400 } hitcount:          1  len:        168
1909	    { skbaddr: ffff8800a1c55a00 } hitcount:          1  len:         40
1910	    { skbaddr: ffff8800d2bcd100 } hitcount:          1  len:         40
1911	    { skbaddr: ffff880064505f00 } hitcount:          1  len:        174
1912	    { skbaddr: ffff8800a8bff200 } hitcount:          1  len:        160
1913	    { skbaddr: ffff880044e3cc00 } hitcount:          1  len:         76
1914	    { skbaddr: ffff8800a8bfe700 } hitcount:          1  len:         46
1915	    { skbaddr: ffff8800d2bcdc00 } hitcount:          1  len:         32
1916	    { skbaddr: ffff8800a1f64800 } hitcount:          1  len:         46
1917	    { skbaddr: ffff8800d2bcde00 } hitcount:          1  len:        988
1918	    { skbaddr: ffff88006a5dea00 } hitcount:          1  len:         46
1919	    { skbaddr: ffff88002e37a200 } hitcount:          1  len:         44
1920	    { skbaddr: ffff8800a1f32c00 } hitcount:          2  len:        676
1921	    { skbaddr: ffff88000ad52600 } hitcount:          2  len:        107
1922	    { skbaddr: ffff8800a1f91e00 } hitcount:          2  len:         92
1923	    { skbaddr: ffff8800af5a0200 } hitcount:          2  len:        142
1924	    { skbaddr: ffff8800d2bcc600 } hitcount:          2  len:        220
1925	    { skbaddr: ffff8800ba36f500 } hitcount:          2  len:         92
1926	    { skbaddr: ffff8800d021f800 } hitcount:          2  len:         92
1927	    { skbaddr: ffff8800a1f33600 } hitcount:          2  len:        675
1928	    { skbaddr: ffff8800a8bfff00 } hitcount:          3  len:        138
1929	    { skbaddr: ffff8800d62a1300 } hitcount:          3  len:        138
1930	    { skbaddr: ffff88002e37a100 } hitcount:          4  len:        184
1931	    { skbaddr: ffff880064504400 } hitcount:          4  len:        184
1932	    { skbaddr: ffff8800a8bfec00 } hitcount:          4  len:        184
1933	    { skbaddr: ffff88000ad53700 } hitcount:          5  len:        230
1934	    { skbaddr: ffff8800d2bcdb00 } hitcount:          5  len:        196
1935	    { skbaddr: ffff8800a1f90000 } hitcount:          6  len:        276
1936	    { skbaddr: ffff88006a54f900 } hitcount:          6  len:        276
1937	
1938	    Totals:
1939	        Hits: 81
1940	        Entries: 42
1941	        Dropped: 0
1942	
1943	  And here's an example that shows how to combine histogram data from
1944	  any two events even if they don't share any 'compatible' fields
1945	  other than 'hitcount' and 'stacktrace'.  These commands create a
1946	  couple of triggers named 'bar' using those fields:
1947	
1948	    # echo 'hist:name=bar:key=stacktrace:val=hitcount' > \
1949	           /sys/kernel/debug/tracing/events/sched/sched_process_fork/trigger
1950	    # echo 'hist:name=bar:key=stacktrace:val=hitcount' > \
1951	          /sys/kernel/debug/tracing/events/net/netif_rx/trigger
1952	
1953	  And displaying the output of either shows some interesting if
1954	  somewhat confusing output:
1955	
1956	    # cat /sys/kernel/debug/tracing/events/sched/sched_process_fork/hist
1957	    # cat /sys/kernel/debug/tracing/events/net/netif_rx/hist
1958	
1959	    # event histogram
1960	    #
1961	    # trigger info: hist:name=bar:keys=stacktrace:vals=hitcount:sort=hitcount:size=2048 [active]
1962	    #
1963	
1964	    { stacktrace:
1965	             _do_fork+0x18e/0x330
1966	             kernel_thread+0x29/0x30
1967	             kthreadd+0x154/0x1b0
1968	             ret_from_fork+0x3f/0x70
1969	    } hitcount:          1
1970	    { stacktrace:
1971	             netif_rx_internal+0xb2/0xd0
1972	             netif_rx_ni+0x20/0x70
1973	             dev_loopback_xmit+0xaa/0xd0
1974	             ip_mc_output+0x126/0x240
1975	             ip_local_out_sk+0x31/0x40
1976	             igmp_send_report+0x1e9/0x230
1977	             igmp_timer_expire+0xe9/0x120
1978	             call_timer_fn+0x39/0xf0
1979	             run_timer_softirq+0x1e1/0x290
1980	             __do_softirq+0xfd/0x290
1981	             irq_exit+0x98/0xb0
1982	             smp_apic_timer_interrupt+0x4a/0x60
1983	             apic_timer_interrupt+0x6d/0x80
1984	             cpuidle_enter+0x17/0x20
1985	             call_cpuidle+0x3b/0x60
1986	             cpu_startup_entry+0x22d/0x310
1987	    } hitcount:          1
1988	    { stacktrace:
1989	             netif_rx_internal+0xb2/0xd0
1990	             netif_rx_ni+0x20/0x70
1991	             dev_loopback_xmit+0xaa/0xd0
1992	             ip_mc_output+0x17f/0x240
1993	             ip_local_out_sk+0x31/0x40
1994	             ip_send_skb+0x1a/0x50
1995	             udp_send_skb+0x13e/0x270
1996	             udp_sendmsg+0x2bf/0x980
1997	             inet_sendmsg+0x67/0xa0
1998	             sock_sendmsg+0x38/0x50
1999	             SYSC_sendto+0xef/0x170
2000	             SyS_sendto+0xe/0x10
2001	             entry_SYSCALL_64_fastpath+0x12/0x6a
2002	    } hitcount:          2
2003	    { stacktrace:
2004	             netif_rx_internal+0xb2/0xd0
2005	             netif_rx+0x1c/0x60
2006	             loopback_xmit+0x6c/0xb0
2007	             dev_hard_start_xmit+0x219/0x3a0
2008	             __dev_queue_xmit+0x415/0x4f0
2009	             dev_queue_xmit_sk+0x13/0x20
2010	             ip_finish_output2+0x237/0x340
2011	             ip_finish_output+0x113/0x1d0
2012	             ip_output+0x66/0xc0
2013	             ip_local_out_sk+0x31/0x40
2014	             ip_send_skb+0x1a/0x50
2015	             udp_send_skb+0x16d/0x270
2016	             udp_sendmsg+0x2bf/0x980
2017	             inet_sendmsg+0x67/0xa0
2018	             sock_sendmsg+0x38/0x50
2019	             ___sys_sendmsg+0x14e/0x270
2020	    } hitcount:         76
2021	    { stacktrace:
2022	             netif_rx_internal+0xb2/0xd0
2023	             netif_rx+0x1c/0x60
2024	             loopback_xmit+0x6c/0xb0
2025	             dev_hard_start_xmit+0x219/0x3a0
2026	             __dev_queue_xmit+0x415/0x4f0
2027	             dev_queue_xmit_sk+0x13/0x20
2028	             ip_finish_output2+0x237/0x340
2029	             ip_finish_output+0x113/0x1d0
2030	             ip_output+0x66/0xc0
2031	             ip_local_out_sk+0x31/0x40
2032	             ip_send_skb+0x1a/0x50
2033	             udp_send_skb+0x16d/0x270
2034	             udp_sendmsg+0x2bf/0x980
2035	             inet_sendmsg+0x67/0xa0
2036	             sock_sendmsg+0x38/0x50
2037	             ___sys_sendmsg+0x269/0x270
2038	    } hitcount:         77
2039	    { stacktrace:
2040	             netif_rx_internal+0xb2/0xd0
2041	             netif_rx+0x1c/0x60
2042	             loopback_xmit+0x6c/0xb0
2043	             dev_hard_start_xmit+0x219/0x3a0
2044	             __dev_queue_xmit+0x415/0x4f0
2045	             dev_queue_xmit_sk+0x13/0x20
2046	             ip_finish_output2+0x237/0x340
2047	             ip_finish_output+0x113/0x1d0
2048	             ip_output+0x66/0xc0
2049	             ip_local_out_sk+0x31/0x40
2050	             ip_send_skb+0x1a/0x50
2051	             udp_send_skb+0x16d/0x270
2052	             udp_sendmsg+0x2bf/0x980
2053	             inet_sendmsg+0x67/0xa0
2054	             sock_sendmsg+0x38/0x50
2055	             SYSC_sendto+0xef/0x170
2056	    } hitcount:         88
2057	    { stacktrace:
2058	             _do_fork+0x18e/0x330
2059	             SyS_clone+0x19/0x20
2060	             entry_SYSCALL_64_fastpath+0x12/0x6a
2061	    } hitcount:        244
2062	
2063	    Totals:
2064	        Hits: 489
2065	        Entries: 7
2066	        Dropped: 0
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.