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:
202 -------------------
204 A filter for an individual event is set by writing a filter expression
205 to the 'filter' file for the given event.
223 -bash: echo: write error: Invalid argument
234 --------------------
236 To clear the filter for an event, write a '0' to the event's filter
243 ---------------------
245 For convenience, filters for every event in a subsystem can be set or
248 event within the subsystem lacks a field specified in the subsystem
250 filter for that event will retain its previous setting. This can
278 Attempt to set a filter using a non-common field for all events in the
290 -----------------
309 6. Event triggers
315 a stack trace whenever the trace event is hit. Whenever a trace event
317 associated with that event is invoked. Any given trigger can
318 additionally have an event filter of the same form as described in
319 section 5 (Event filtering) associated with it - the command will only
320 be invoked if the event being invoked passes the associated filter.
323 Triggers are added to and removed from a particular event by writing
324 trigger expressions to the 'trigger' file for the given event.
326 A given event can have any number of triggers associated with it,
330 Event triggers are implemented on top of "soft" mode, which means that
331 whenever a trace event has one or more triggers associated with it,
332 the event is activated even if it isn't actually enabled, but is
336 enabled, and also allows the current event filter implementation to be
339 The syntax for event triggers is roughly based on the syntax for
351 ---------------------
366 The filter syntax is the same as that described in the 'Event
375 ------------------------------
379 - enable_event/disable_event
381 These commands can enable or disable another trace event whenever
382 the triggering event is hit. When these commands are registered,
383 the other trace event is activated, but disabled in a "soft" mode.
385 The event tracepoint stays in this mode as long as there's a trigger
404 enable_event:<system>:<event>[:count]
405 disable_event:<system>:<event>[:count]
416 per triggering event, but there can only be one trigger per
417 triggered event. e.g. sys_enter_read can have triggers enabling both
423 - stacktrace
426 triggering event occurs.
459 event.
461 - snapshot
464 triggering event occurs.
469 capture those events when the trigger event occurred::
488 event.
490 - traceon/traceoff
500 trigger event::
519 triggering event.
521 - hist
523 This command aggregates event hits into a hash table keyed on one or
524 more trace event format fields (or stacktrace) and a set of running
525 totals derived from one or more trace event format fields and/or
526 event counts (hitcount).
530 7. In-kernel trace event API
533 In most cases, the command-line interface to trace events is more than
536 series of linked command-line expressions, or putting together sets of
539 maintain an in-kernel state machine detecting, for instance, when an
542 The trace event subsystem provides an in-kernel API allowing modules
543 or other kernel code to generate user-defined 'synthetic' events at
547 A similar in-kernel API is also available for creating kprobe and
550 Both the synthetic event and k/ret/probe event APIs are built on top
551 of a lower-level "dynevent_cmd" event command API, which is also
553 higher-level trace event APIs.
558 - dynamically creating synthetic event definitions
559 - dynamically creating kprobe and kretprobe event definitions
560 - tracing synthetic events from in-kernel code
561 - the low-level "dynevent_cmd" API
563 7.1 Dyamically creating synthetic event definitions
564 ---------------------------------------------------
566 There are a couple ways to create a new synthetic event from a kernel
569 The first creates the event in one step, using synth_event_create().
570 In this method, the name of the event to create and an array defining
572 synthetic event with that name and fields will exist following that
573 call. For example, to create a new "schedtest" synthetic event::
579 synth_field_desc, each of which describes an event field by type and
580 name::
583 { .type = "pid_t", .name = "next_pid_field" },
584 { .type = "char[16]", .name = "next_comm_field" },
585 { .type = "u64", .name = "ts_ns" },
586 { .type = "u64", .name = "ts_ms" },
587 { .type = "unsigned int", .name = "cpu" },
588 { .type = "char[64]", .name = "my_string_field" },
589 { .type = "int", .name = "my_int_field" },
597 be a dynamic array, which will only take as much space in the event as
600 Because space for an event is reserved before assigning field values
601 to the event, using dynamic arrays implies that the piecewise
602 in-kernel API described below can't be used with dynamic arrays. The
603 other non-piecewise in-kernel APIs can, however, be used with dynamic
606 If the event is created from within a module, a pointer to the module
611 At this point, the event object is ready to be used for generating new
614 In the second method, the event is created in several steps. This
618 To use this method, an empty or partially empty synthetic event should
621 the name of the event along with one or more pairs of args each pair
623 supplied. For synth_event_gen_cmd_array_start(), the name of the
624 event along with an array of struct synth_field_desc should be
629 For example, to create a new "schedtest" synthetic event with two
651 Once the synthetic event object has been created, it can then be
654 type, and a field name. For example, to add a new int field named
669 synth_event_add_field_str() can be used to add it as-is; it will
672 Once all the fields have been added, the event should be finalized and
677 At this point, the event object is ready to be used for tracing new
680 7.2 Tracing synthetic events from in-kernel code
681 ------------------------------------------------
683 To trace a synthetic event, there are several options. The first
684 option is to trace the event in one call, using synth_event_trace()
687 need for a pre-formed array of values or list of arguments, via
692 7.2.1 Tracing a synthetic event all at once
693 -------------------------------------------
695 To trace a synthetic event all at once, the synth_event_trace() or
699 representing the synthetic event (which can be retrieved using
700 trace_get_event_file() using the synthetic event name, "synthetic" as
701 the system name, and the trace instance name (NULL if using the global
703 synthetic event field, and the number of values being passed.
705 So, to trace an event corresponding to the synthetic event definition
719 the event for the string, using these pointers.
723 representing the synthetic event (which can be retrieved using
724 trace_get_event_file() using the synthetic event name, "synthetic" as
725 the system name, and the trace instance name (NULL if using the global
727 event field.
729 To trace an event corresponding to the synthetic event definition
743 match the number of field in the synthetic event, and which must be in
744 the same order as the synthetic event fields.
748 the event for the string, using these pointers.
750 In order to trace a synthetic event, a pointer to the trace event file
752 it - it will find the file in the given trace instance (in this case
759 Before tracing the event, it should be enabled in some way, otherwise
760 the synthetic event won't actually show up in the trace buffer.
762 To enable a synthetic event from the kernel, trace_array_set_clr_event()
764 the "synthetic" system name to be specified explicitly).
766 To enable the event, pass 'true' to it::
768 trace_array_set_clr_event(schedtest_event_file->tr,
773 trace_array_set_clr_event(schedtest_event_file->tr,
777 event, which should be visible in the trace buffer afterwards::
782 To remove the synthetic event, the event should be disabled, and the
785 trace_array_set_clr_event(schedtest_event_file->tr,
790 remove the event::
794 7.2.2 Tracing a synthetic event piecewise
795 -----------------------------------------
799 event trace::
805 It's passed the trace_event_file representing the synthetic event
810 Once the event has been opened, which means space for it has been
813 the event, which requires no lookups, or by name, which does. The
820 along with the value to set the next field in the event. After each
824 this method would be (without error-handling code)::
849 the synth_event_trace_start(), along with the field name of the field
851 the above examples using this method would be (without error-handling
865 incompatible if used within the same trace of an event - either one
868 Finally, the event won't be actually traced until it's 'closed',
875 of whether any of the add calls failed (say due to a bad field name
878 7.3 Dyamically creating kprobe and kretprobe event definitions
879 --------------------------------------------------------------
881 To create a kprobe or kretprobe trace event from kernel code, the
885 To create a kprobe event, an empty or partially empty kprobe event
886 should first be created using kprobe_event_gen_cmd_start(). The name
887 of the event and the probe location should be specfied along with one
893 For example, to create a new "schedtest" kprobe event with two fields::
905 * Define the gen_kprobe_test event with the first 2 kprobe
911 Once the kprobe event object has been created, it can then be
919 Once all the fields have been added, the event should be finalized and
930 At this point, the event object is ready to be used for tracing new
933 Similarly, a kretprobe event can be created using
934 kretprobe_event_gen_cmd_start() with a probe name and location and
940 Similar to the synthetic event case, code like the following can be
941 used to enable the newly created kprobe event::
945 ret = trace_array_set_clr_event(gen_kprobe_test->tr,
949 used to give the kprobe event file back and delete the event::
955 7.4 The "dynevent_cmd" low-level API
956 ------------------------------------
958 Both the in-kernel synthetic event and kprobe interfaces are built on
959 top of a lower-level "dynevent_cmd" interface. This interface is
960 meant to provide the basis for higher-level interfaces such as the
963 The basic idea is simple and amounts to providing a general-purpose
964 layer that can be used to generate trace event commands. The
965 generated command strings can then be passed to the command-parsing
966 and event creation code that already exists in the trace event
969 In a nutshell, the way it works is that the higher-level interface
989 The dynevent_cmd initialization needs to be given a user-specified
991 for this purpose - at 2k it's generally too big to be comfortably put
994 correct command type, and a pointer to an event-specific run_command()
995 callback that will be called to actually execute the event-specific
999 calls to argument-adding functions.
1004 a whitespace-separated argument to the command::
1010 arg.str = name;
1016 optional sanity-checking function or separator appended to the end of
1029 arg_pair.rhs = name;
1040 add a string as-is, with no spaces, delimeters, or arg check.
1043 (until its length surpasses cmd->maxlen). When all the arguments have
1050 At that point, if the return value is 0, the dynamic event has been