Lines Matching +full:event +full:- +full:name
2 Event Tracing
13 using the event tracing infrastructure.
15 Not all tracepoints can be traced using the event tracing system;
20 2. Using Event Tracing
24 ---------------------------------
29 To enable a particular event, such as 'sched_wakeup', simply echo it
36 To disable an event, echo the event name to the set_event file prefixed
50 etc., and a full event name looks like this: <subsystem>:<event>. The
51 subsystem name is optional, but it is displayed in the available_events
59 ---------------------------
64 To enable event 'sched_wakeup'::
82 - 0 - all events this file affects are disabled
83 - 1 - all events this file affects are enabled
84 - X - there is a mixture of events enabled and disabled
85 - ? - this file does not affect any event
88 ---------------
92 trace_event=[event-list]
94 event-list is a comma separated list of events. See section 2.1 for event
97 3. Defining an event-enabled tracepoint
102 4. Event formats
105 Each trace event has a 'format' file associated with it that contains
106 a description of each field in a logged event. This information can
108 find the field names that can be used in event filters (see section 5).
111 event in text mode, along with the event name and ID used for
114 Every event has a set of ``common`` fields associated with it; these are
117 definition for that event.
121 field:field-type field-name; offset:N; size:N;
127 event::
131 name: sched_wakeup
146 print fmt: "task %s:%d [%d] success=%d [%03d]", REC->comm, REC->pid,
147 REC->prio, REC->success, REC->cpu
149 This event contains 10 fields, the first 5 common and the remaining 5
150 event-specific. All the fields for this event are numeric, except for
151 'comm' which is a string, a distinction important for event filtering.
153 5. Event filtering
157 'filter expressions' with them. As soon as an event is logged into
159 associated with that event type. An event with field values that
160 'match' the filter will appear in the trace output, and an event whose
161 values don't match will be discarded. An event with no filter
163 filter has been set for an event.
166 ---------------------
171 logged event with a constant value and returns either 0 or 1 depending
174 field-name relational-operator value
177 double-quotes can be used to prevent the shell from interpreting
180 The field-names available for use in filters can be found in the
183 The relational-operators depend on the type of the field being tested:
203 field name::
210 You can convert any long type to a function address and search by function name::
223 a user-provided cpumask in cpulist format. The format is as follows::
234 target_cpu & CPUS{17-42}
237 -------------------
239 A filter for an individual event is set by writing a filter expression
240 to the 'filter' file for the given event.
258 -bash: echo: write error: Invalid argument
269 ------------------------
279 --------------------
281 To clear the filter for an event, write a '0' to the event's filter
288 ---------------------
290 For convenience, filters for every event in a subsystem can be set or
293 event within the subsystem lacks a field specified in the subsystem
295 filter for that event will retain its previous setting. This can
323 Attempt to set a filter using a non-common field for all events in the
335 -----------------
354 6. Event triggers
360 a stack trace whenever the trace event is hit. Whenever a trace event
362 associated with that event is invoked. Any given trigger can
363 additionally have an event filter of the same form as described in
364 section 5 (Event filtering) associated with it - the command will only
365 be invoked if the event being invoked passes the associated filter.
368 Triggers are added to and removed from a particular event by writing
369 trigger expressions to the 'trigger' file for the given event.
371 A given event can have any number of triggers associated with it,
375 Event triggers are implemented on top of "soft" mode, which means that
376 whenever a trace event has one or more triggers associated with it,
377 the event is activated even if it isn't actually enabled, but is
381 enabled, and also allows the current event filter implementation to be
384 The syntax for event triggers is roughly based on the syntax for
396 ---------------------
411 The filter syntax is the same as that described in the 'Event
420 ------------------------------
424 - enable_event/disable_event
426 These commands can enable or disable another trace event whenever
427 the triggering event is hit. When these commands are registered,
428 the other trace event is activated, but disabled in a "soft" mode.
430 The event tracepoint stays in this mode as long as there's a trigger
449 enable_event:<system>:<event>[:count]
450 disable_event:<system>:<event>[:count]
461 per triggering event, but there can only be one trigger per
462 triggered event. e.g. sys_enter_read can have triggers enabling both
468 - stacktrace
471 triggering event occurs.
504 event.
506 - snapshot
509 triggering event occurs.
514 capture those events when the trigger event occurred::
533 event.
535 - traceon/traceoff
545 trigger event::
564 triggering event.
566 - hist
568 This command aggregates event hits into a hash table keyed on one or
569 more trace event format fields (or stacktrace) and a set of running
570 totals derived from one or more trace event format fields and/or
571 event counts (hitcount).
575 7. In-kernel trace event API
578 In most cases, the command-line interface to trace events is more than
581 series of linked command-line expressions, or putting together sets of
584 maintain an in-kernel state machine detecting, for instance, when an
587 The trace event subsystem provides an in-kernel API allowing modules
588 or other kernel code to generate user-defined 'synthetic' events at
592 A similar in-kernel API is also available for creating kprobe and
595 Both the synthetic event and k/ret/probe event APIs are built on top
596 of a lower-level "dynevent_cmd" event command API, which is also
598 higher-level trace event APIs.
603 - dynamically creating synthetic event definitions
604 - dynamically creating kprobe and kretprobe event definitions
605 - tracing synthetic events from in-kernel code
606 - the low-level "dynevent_cmd" API
608 7.1 Dyamically creating synthetic event definitions
609 ---------------------------------------------------
611 There are a couple ways to create a new synthetic event from a kernel
614 The first creates the event in one step, using synth_event_create().
615 In this method, the name of the event to create and an array defining
617 synthetic event with that name and fields will exist following that
618 call. For example, to create a new "schedtest" synthetic event::
624 synth_field_desc, each of which describes an event field by type and
625 name::
628 { .type = "pid_t", .name = "next_pid_field" },
629 { .type = "char[16]", .name = "next_comm_field" },
630 { .type = "u64", .name = "ts_ns" },
631 { .type = "u64", .name = "ts_ms" },
632 { .type = "unsigned int", .name = "cpu" },
633 { .type = "char[64]", .name = "my_string_field" },
634 { .type = "int", .name = "my_int_field" },
642 be a dynamic array, which will only take as much space in the event as
645 Because space for an event is reserved before assigning field values
646 to the event, using dynamic arrays implies that the piecewise
647 in-kernel API described below can't be used with dynamic arrays. The
648 other non-piecewise in-kernel APIs can, however, be used with dynamic
651 If the event is created from within a module, a pointer to the module
656 At this point, the event object is ready to be used for generating new
659 In the second method, the event is created in several steps. This
663 To use this method, an empty or partially empty synthetic event should
666 the name of the event along with one or more pairs of args each pair
668 supplied. For synth_event_gen_cmd_array_start(), the name of the
669 event along with an array of struct synth_field_desc should be
674 For example, to create a new "schedtest" synthetic event with two
696 Once the synthetic event object has been created, it can then be
699 type, and a field name. For example, to add a new int field named
714 synth_event_add_field_str() can be used to add it as-is; it will
717 Once all the fields have been added, the event should be finalized and
722 At this point, the event object is ready to be used for tracing new
725 7.2 Tracing synthetic events from in-kernel code
726 ------------------------------------------------
728 To trace a synthetic event, there are several options. The first
729 option is to trace the event in one call, using synth_event_trace()
732 need for a pre-formed array of values or list of arguments, via
737 7.2.1 Tracing a synthetic event all at once
738 -------------------------------------------
740 To trace a synthetic event all at once, the synth_event_trace() or
744 representing the synthetic event (which can be retrieved using
745 trace_get_event_file() using the synthetic event name, "synthetic" as
746 the system name, and the trace instance name (NULL if using the global
748 synthetic event field, and the number of values being passed.
750 So, to trace an event corresponding to the synthetic event definition
764 the event for the string, using these pointers.
768 representing the synthetic event (which can be retrieved using
769 trace_get_event_file() using the synthetic event name, "synthetic" as
770 the system name, and the trace instance name (NULL if using the global
772 event field.
774 To trace an event corresponding to the synthetic event definition
788 match the number of field in the synthetic event, and which must be in
789 the same order as the synthetic event fields.
793 the event for the string, using these pointers.
795 In order to trace a synthetic event, a pointer to the trace event file
797 it - it will find the file in the given trace instance (in this case
804 Before tracing the event, it should be enabled in some way, otherwise
805 the synthetic event won't actually show up in the trace buffer.
807 To enable a synthetic event from the kernel, trace_array_set_clr_event()
809 the "synthetic" system name to be specified explicitly).
811 To enable the event, pass 'true' to it::
813 trace_array_set_clr_event(schedtest_event_file->tr,
818 trace_array_set_clr_event(schedtest_event_file->tr,
822 event, which should be visible in the trace buffer afterwards::
827 To remove the synthetic event, the event should be disabled, and the
830 trace_array_set_clr_event(schedtest_event_file->tr,
835 remove the event::
839 7.2.2 Tracing a synthetic event piecewise
840 -----------------------------------------
844 event trace::
850 It's passed the trace_event_file representing the synthetic event
855 Once the event has been opened, which means space for it has been
858 the event, which requires no lookups, or by name, which does. The
865 along with the value to set the next field in the event. After each
869 this method would be (without error-handling code)::
894 the synth_event_trace_start(), along with the field name of the field
896 the above examples using this method would be (without error-handling
910 incompatible if used within the same trace of an event - either one
913 Finally, the event won't be actually traced until it's 'closed',
920 of whether any of the add calls failed (say due to a bad field name
923 7.3 Dyamically creating kprobe and kretprobe event definitions
924 --------------------------------------------------------------
926 To create a kprobe or kretprobe trace event from kernel code, the
930 To create a kprobe event, an empty or partially empty kprobe event
931 should first be created using kprobe_event_gen_cmd_start(). The name
932 of the event and the probe location should be specified along with one
938 For example, to create a new "schedtest" kprobe event with two fields::
950 * Define the gen_kprobe_test event with the first 2 kprobe
956 Once the kprobe event object has been created, it can then be
964 Once all the fields have been added, the event should be finalized and
975 At this point, the event object is ready to be used for tracing new
978 Similarly, a kretprobe event can be created using
979 kretprobe_event_gen_cmd_start() with a probe name and location and
985 Similar to the synthetic event case, code like the following can be
986 used to enable the newly created kprobe event::
990 ret = trace_array_set_clr_event(gen_kprobe_test->tr,
994 used to give the kprobe event file back and delete the event::
1000 7.4 The "dynevent_cmd" low-level API
1001 ------------------------------------
1003 Both the in-kernel synthetic event and kprobe interfaces are built on
1004 top of a lower-level "dynevent_cmd" interface. This interface is
1005 meant to provide the basis for higher-level interfaces such as the
1008 The basic idea is simple and amounts to providing a general-purpose
1009 layer that can be used to generate trace event commands. The
1010 generated command strings can then be passed to the command-parsing
1011 and event creation code that already exists in the trace event
1014 In a nutshell, the way it works is that the higher-level interface
1034 The dynevent_cmd initialization needs to be given a user-specified
1036 for this purpose - at 2k it's generally too big to be comfortably put
1039 correct command type, and a pointer to an event-specific run_command()
1040 callback that will be called to actually execute the event-specific
1044 calls to argument-adding functions.
1049 a whitespace-separated argument to the command::
1055 arg.str = name;
1061 optional sanity-checking function or separator appended to the end of
1074 arg_pair.rhs = name;
1085 add a string as-is, with no spaces, delimiters, or arg check.
1088 (until its length surpasses cmd->maxlen). When all the arguments have
1095 At that point, if the return value is 0, the dynamic event has been