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
72 The above will enable any system or event that ``<match>`` matches. If
75 To enable only a specific event within a system::
77 # echo '<system>:<event>:mod:<module>' > /sys/kernel/tracing/set_event
79 If ``<event>`` is ``"*"`` then it will match all events within the system
83 ---------------------------
88 To enable event 'sched_wakeup'::
106 - 0 - all events this file affects are disabled
107 - 1 - all events this file affects are enabled
108 - X - there is a mixture of events enabled and disabled
109 - ? - this file does not affect any event
112 ---------------
116 trace_event=[event-list]
118 event-list is a comma separated list of events. See section 2.1 for event
121 3. Defining an event-enabled tracepoint
126 4. Event formats
129 Each trace event has a 'format' file associated with it that contains
130 a description of each field in a logged event. This information can
132 find the field names that can be used in event filters (see section 5).
135 event in text mode, along with the event name and ID used for
138 Every event has a set of ``common`` fields associated with it; these are
141 definition for that event.
145 field:field-type field-name; offset:N; size:N;
151 event::
155 name: sched_wakeup
170 print fmt: "task %s:%d [%d] success=%d [%03d]", REC->comm, REC->pid,
171 REC->prio, REC->success, REC->cpu
173 This event contains 10 fields, the first 5 common and the remaining 5
174 event-specific. All the fields for this event are numeric, except for
175 'comm' which is a string, a distinction important for event filtering.
177 5. Event filtering
181 'filter expressions' with them. As soon as an event is logged into
183 associated with that event type. An event with field values that
184 'match' the filter will appear in the trace output, and an event whose
185 values don't match will be discarded. An event with no filter
187 filter has been set for an event.
190 ---------------------
195 logged event with a constant value and returns either 0 or 1 depending
198 field-name relational-operator value
201 double-quotes can be used to prevent the shell from interpreting
204 The field-names available for use in filters can be found in the
207 The relational-operators depend on the type of the field being tested:
227 field name::
234 You can convert any long type to a function address and search by function name::
247 a user-provided cpumask in cpulist format. The format is as follows::
258 target_cpu & CPUS{17-42}
261 -------------------
263 A filter for an individual event is set by writing a filter expression
264 to the 'filter' file for the given event.
282 -bash: echo: write error: Invalid argument
293 ------------------------
303 --------------------
305 To clear the filter for an event, write a '0' to the event's filter
312 ---------------------
314 For convenience, filters for every event in a subsystem can be set or
317 event within the subsystem lacks a field specified in the subsystem
319 filter for that event will retain its previous setting. This can
347 Attempt to set a filter using a non-common field for all events in the
359 -----------------
378 6. Event triggers
384 a stack trace whenever the trace event is hit. Whenever a trace event
386 associated with that event is invoked. Any given trigger can
387 additionally have an event filter of the same form as described in
388 section 5 (Event filtering) associated with it - the command will only
389 be invoked if the event being invoked passes the associated filter.
392 Triggers are added to and removed from a particular event by writing
393 trigger expressions to the 'trigger' file for the given event.
395 A given event can have any number of triggers associated with it,
399 Event triggers are implemented on top of "soft" mode, which means that
400 whenever a trace event has one or more triggers associated with it,
401 the event is activated even if it isn't actually enabled, but is
405 enabled, and also allows the current event filter implementation to be
408 The syntax for event triggers is roughly based on the syntax for
420 ---------------------
435 The filter syntax is the same as that described in the 'Event
444 ------------------------------
448 - enable_event/disable_event
450 These commands can enable or disable another trace event whenever
451 the triggering event is hit. When these commands are registered,
452 the other trace event is activated, but disabled in a "soft" mode.
454 The event tracepoint stays in this mode as long as there's a trigger
473 enable_event:<system>:<event>[:count]
474 disable_event:<system>:<event>[:count]
485 per triggering event, but there can only be one trigger per
486 triggered event. e.g. sys_enter_read can have triggers enabling both
492 - stacktrace
495 triggering event occurs.
528 event.
530 - snapshot
533 triggering event occurs.
538 capture those events when the trigger event occurred::
557 event.
559 - traceon/traceoff
569 trigger event::
588 triggering event.
590 - hist
592 This command aggregates event hits into a hash table keyed on one or
593 more trace event format fields (or stacktrace) and a set of running
594 totals derived from one or more trace event format fields and/or
595 event counts (hitcount).
599 7. In-kernel trace event API
602 In most cases, the command-line interface to trace events is more than
605 series of linked command-line expressions, or putting together sets of
608 maintain an in-kernel state machine detecting, for instance, when an
611 The trace event subsystem provides an in-kernel API allowing modules
612 or other kernel code to generate user-defined 'synthetic' events at
616 A similar in-kernel API is also available for creating kprobe and
619 Both the synthetic event and k/ret/probe event APIs are built on top
620 of a lower-level "dynevent_cmd" event command API, which is also
622 higher-level trace event APIs.
627 - dynamically creating synthetic event definitions
628 - dynamically creating kprobe and kretprobe event definitions
629 - tracing synthetic events from in-kernel code
630 - the low-level "dynevent_cmd" API
632 7.1 Dyamically creating synthetic event definitions
633 ---------------------------------------------------
635 There are a couple ways to create a new synthetic event from a kernel
638 The first creates the event in one step, using synth_event_create().
639 In this method, the name of the event to create and an array defining
641 synthetic event with that name and fields will exist following that
642 call. For example, to create a new "schedtest" synthetic event::
648 synth_field_desc, each of which describes an event field by type and
649 name::
652 { .type = "pid_t", .name = "next_pid_field" },
653 { .type = "char[16]", .name = "next_comm_field" },
654 { .type = "u64", .name = "ts_ns" },
655 { .type = "u64", .name = "ts_ms" },
656 { .type = "unsigned int", .name = "cpu" },
657 { .type = "char[64]", .name = "my_string_field" },
658 { .type = "int", .name = "my_int_field" },
666 be a dynamic array, which will only take as much space in the event as
669 Because space for an event is reserved before assigning field values
670 to the event, using dynamic arrays implies that the piecewise
671 in-kernel API described below can't be used with dynamic arrays. The
672 other non-piecewise in-kernel APIs can, however, be used with dynamic
675 If the event is created from within a module, a pointer to the module
680 At this point, the event object is ready to be used for generating new
683 In the second method, the event is created in several steps. This
687 To use this method, an empty or partially empty synthetic event should
690 the name of the event along with one or more pairs of args each pair
692 supplied. For synth_event_gen_cmd_array_start(), the name of the
693 event along with an array of struct synth_field_desc should be
698 For example, to create a new "schedtest" synthetic event with two
720 Once the synthetic event object has been created, it can then be
723 type, and a field name. For example, to add a new int field named
738 synth_event_add_field_str() can be used to add it as-is; it will
741 Once all the fields have been added, the event should be finalized and
746 At this point, the event object is ready to be used for tracing new
749 7.2 Tracing synthetic events from in-kernel code
750 ------------------------------------------------
752 To trace a synthetic event, there are several options. The first
753 option is to trace the event in one call, using synth_event_trace()
756 need for a pre-formed array of values or list of arguments, via
761 7.2.1 Tracing a synthetic event all at once
762 -------------------------------------------
764 To trace a synthetic event all at once, the synth_event_trace() or
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 synthetic event field, and the number of values being passed.
774 So, to trace an event corresponding to the synthetic event definition
788 the event for the string, using these pointers.
792 representing the synthetic event (which can be retrieved using
793 trace_get_event_file() using the synthetic event name, "synthetic" as
794 the system name, and the trace instance name (NULL if using the global
796 event field.
798 To trace an event corresponding to the synthetic event definition
812 match the number of field in the synthetic event, and which must be in
813 the same order as the synthetic event fields.
817 the event for the string, using these pointers.
819 In order to trace a synthetic event, a pointer to the trace event file
821 it - it will find the file in the given trace instance (in this case
828 Before tracing the event, it should be enabled in some way, otherwise
829 the synthetic event won't actually show up in the trace buffer.
831 To enable a synthetic event from the kernel, trace_array_set_clr_event()
833 the "synthetic" system name to be specified explicitly).
835 To enable the event, pass 'true' to it::
837 trace_array_set_clr_event(schedtest_event_file->tr,
842 trace_array_set_clr_event(schedtest_event_file->tr,
846 event, which should be visible in the trace buffer afterwards::
851 To remove the synthetic event, the event should be disabled, and the
854 trace_array_set_clr_event(schedtest_event_file->tr,
859 remove the event::
863 7.2.2 Tracing a synthetic event piecewise
864 -----------------------------------------
868 event trace::
874 It's passed the trace_event_file representing the synthetic event
879 Once the event has been opened, which means space for it has been
882 the event, which requires no lookups, or by name, which does. The
889 along with the value to set the next field in the event. After each
893 this method would be (without error-handling code)::
918 the synth_event_trace_start(), along with the field name of the field
920 the above examples using this method would be (without error-handling
934 incompatible if used within the same trace of an event - either one
937 Finally, the event won't be actually traced until it's 'closed',
944 of whether any of the add calls failed (say due to a bad field name
947 7.3 Dyamically creating kprobe and kretprobe event definitions
948 --------------------------------------------------------------
950 To create a kprobe or kretprobe trace event from kernel code, the
954 To create a kprobe event, an empty or partially empty kprobe event
955 should first be created using kprobe_event_gen_cmd_start(). The name
956 of the event and the probe location should be specified along with one
962 For example, to create a new "schedtest" kprobe event with two fields::
974 * Define the gen_kprobe_test event with the first 2 kprobe
980 Once the kprobe event object has been created, it can then be
988 Once all the fields have been added, the event should be finalized and
999 At this point, the event object is ready to be used for tracing new
1002 Similarly, a kretprobe event can be created using
1003 kretprobe_event_gen_cmd_start() with a probe name and location and
1009 Similar to the synthetic event case, code like the following can be
1010 used to enable the newly created kprobe event::
1014 ret = trace_array_set_clr_event(gen_kprobe_test->tr,
1018 used to give the kprobe event file back and delete the event::
1024 7.4 The "dynevent_cmd" low-level API
1025 ------------------------------------
1027 Both the in-kernel synthetic event and kprobe interfaces are built on
1028 top of a lower-level "dynevent_cmd" interface. This interface is
1029 meant to provide the basis for higher-level interfaces such as the
1032 The basic idea is simple and amounts to providing a general-purpose
1033 layer that can be used to generate trace event commands. The
1034 generated command strings can then be passed to the command-parsing
1035 and event creation code that already exists in the trace event
1038 In a nutshell, the way it works is that the higher-level interface
1058 The dynevent_cmd initialization needs to be given a user-specified
1060 for this purpose - at 2k it's generally too big to be comfortably put
1063 correct command type, and a pointer to an event-specific run_command()
1064 callback that will be called to actually execute the event-specific
1068 calls to argument-adding functions.
1073 a whitespace-separated argument to the command::
1079 arg.str = name;
1085 optional sanity-checking function or separator appended to the end of
1098 arg_pair.rhs = name;
1109 add a string as-is, with no spaces, delimiters, or arg check.
1112 (until its length surpasses cmd->maxlen). When all the arguments have
1119 At that point, if the return value is 0, the dynamic event has been