From 933e3d54c021be56213b1475e5ac4fbebc7b48f1 Mon Sep 17 00:00:00 2001 From: Steven Rostedt Date: Fri, 9 Apr 2010 11:57:28 -0400 Subject: kerselshark/doc: Add html documentation on how to use kernelshark Add documentation on how to use kernelshark. Signed-off-by: Steven Rostedt --- Documentation/HTML/images/kshark-cursor-1.png | Bin 0 -> 61110 bytes .../HTML/images/kshark-filter-advance-1.png | Bin 0 -> 21625 bytes .../HTML/images/kshark-filter-del-adv.png | Bin 0 -> 21730 bytes .../HTML/images/kshark-filter-event-adv-list.png | Bin 0 -> 20674 bytes .../HTML/images/kshark-filter-events-sched.png | Bin 0 -> 19572 bytes Documentation/HTML/images/kshark-filter-events.png | Bin 0 -> 20090 bytes .../HTML/images/kshark-filter-list-adv-irq.png | Bin 0 -> 20789 bytes .../HTML/images/kshark-filter-sync-graph-1.png | Bin 0 -> 71003 bytes .../HTML/images/kshark-filter-task-menu.png | Bin 0 -> 83758 bytes Documentation/HTML/images/kshark-filter.png | Bin 0 -> 64849 bytes .../HTML/images/kshark-graph-info-line.png | Bin 0 -> 2476 bytes .../HTML/images/kshark-graph-plot-area.png | Bin 0 -> 5210 bytes .../HTML/images/kshark-graph-plot-title.png | Bin 0 -> 1144 bytes Documentation/HTML/images/kshark-list-adjust.png | Bin 0 -> 80113 bytes .../HTML/images/kshark-list-enable-filter-1.png | Bin 0 -> 83642 bytes .../HTML/images/kshark-list-graph-follow-1.png | Bin 0 -> 82268 bytes .../HTML/images/kshark-list-graph-follow-2.png | Bin 0 -> 81639 bytes .../HTML/images/kshark-list-info-area.png | Bin 0 -> 5083 bytes Documentation/HTML/images/kshark-open.png | Bin 0 -> 58572 bytes Documentation/HTML/images/kshark-plot-cpu-1.png | Bin 0 -> 8385 bytes Documentation/HTML/images/kshark-plot-cpu-2.png | Bin 0 -> 8453 bytes .../HTML/images/kshark-plot-cpu-result.png | Bin 0 -> 59326 bytes Documentation/HTML/images/kshark-plot-menu.png | Bin 0 -> 61670 bytes .../images/kshark-plot-task-measure-preempt.png | Bin 0 -> 65759 bytes .../HTML/images/kshark-plot-task-measure.png | Bin 0 -> 65673 bytes .../HTML/images/kshark-plot-task-result.png | Bin 0 -> 65607 bytes .../HTML/images/kshark-plot-task-select.png | Bin 0 -> 26263 bytes .../HTML/images/kshark-plot-task-zoom-1.png | Bin 0 -> 66467 bytes Documentation/HTML/images/kshark-select-a-1.png | Bin 0 -> 59254 bytes Documentation/HTML/images/kshark-select-b-1.png | Bin 0 -> 59400 bytes Documentation/HTML/images/kshark-zoom-in-2.png | Bin 0 -> 63059 bytes Documentation/HTML/images/kshark-zoom-in-3.png | Bin 0 -> 59020 bytes .../HTML/images/kshark-zoom-in-select.png | Bin 0 -> 60206 bytes .../HTML/images/kshark-zoom-out-select.png | Bin 0 -> 62821 bytes Documentation/HTML/index.html | 631 +++++++++++++++++++++ 35 files changed, 631 insertions(+) create mode 100644 Documentation/HTML/images/kshark-cursor-1.png create mode 100644 Documentation/HTML/images/kshark-filter-advance-1.png create mode 100644 Documentation/HTML/images/kshark-filter-del-adv.png create mode 100644 Documentation/HTML/images/kshark-filter-event-adv-list.png create mode 100644 Documentation/HTML/images/kshark-filter-events-sched.png create mode 100644 Documentation/HTML/images/kshark-filter-events.png create mode 100644 Documentation/HTML/images/kshark-filter-list-adv-irq.png create mode 100644 Documentation/HTML/images/kshark-filter-sync-graph-1.png create mode 100644 Documentation/HTML/images/kshark-filter-task-menu.png create mode 100644 Documentation/HTML/images/kshark-filter.png create mode 100644 Documentation/HTML/images/kshark-graph-info-line.png create mode 100644 Documentation/HTML/images/kshark-graph-plot-area.png create mode 100644 Documentation/HTML/images/kshark-graph-plot-title.png create mode 100644 Documentation/HTML/images/kshark-list-adjust.png create mode 100644 Documentation/HTML/images/kshark-list-enable-filter-1.png create mode 100644 Documentation/HTML/images/kshark-list-graph-follow-1.png create mode 100644 Documentation/HTML/images/kshark-list-graph-follow-2.png create mode 100644 Documentation/HTML/images/kshark-list-info-area.png create mode 100644 Documentation/HTML/images/kshark-open.png create mode 100644 Documentation/HTML/images/kshark-plot-cpu-1.png create mode 100644 Documentation/HTML/images/kshark-plot-cpu-2.png create mode 100644 Documentation/HTML/images/kshark-plot-cpu-result.png create mode 100644 Documentation/HTML/images/kshark-plot-menu.png create mode 100644 Documentation/HTML/images/kshark-plot-task-measure-preempt.png create mode 100644 Documentation/HTML/images/kshark-plot-task-measure.png create mode 100644 Documentation/HTML/images/kshark-plot-task-result.png create mode 100644 Documentation/HTML/images/kshark-plot-task-select.png create mode 100644 Documentation/HTML/images/kshark-plot-task-zoom-1.png create mode 100644 Documentation/HTML/images/kshark-select-a-1.png create mode 100644 Documentation/HTML/images/kshark-select-b-1.png create mode 100644 Documentation/HTML/images/kshark-zoom-in-2.png create mode 100644 Documentation/HTML/images/kshark-zoom-in-3.png create mode 100644 Documentation/HTML/images/kshark-zoom-in-select.png create mode 100644 Documentation/HTML/images/kshark-zoom-out-select.png create mode 100644 Documentation/HTML/index.html (limited to 'Documentation/HTML') diff --git a/Documentation/HTML/images/kshark-cursor-1.png b/Documentation/HTML/images/kshark-cursor-1.png new file mode 100644 index 0000000..64d19be Binary files /dev/null and b/Documentation/HTML/images/kshark-cursor-1.png differ diff --git a/Documentation/HTML/images/kshark-filter-advance-1.png b/Documentation/HTML/images/kshark-filter-advance-1.png new file mode 100644 index 0000000..23f6584 Binary files /dev/null and b/Documentation/HTML/images/kshark-filter-advance-1.png differ diff --git a/Documentation/HTML/images/kshark-filter-del-adv.png b/Documentation/HTML/images/kshark-filter-del-adv.png new file mode 100644 index 0000000..88e2376 Binary files /dev/null and b/Documentation/HTML/images/kshark-filter-del-adv.png differ diff --git a/Documentation/HTML/images/kshark-filter-event-adv-list.png b/Documentation/HTML/images/kshark-filter-event-adv-list.png new file mode 100644 index 0000000..c2f2d52 Binary files /dev/null and b/Documentation/HTML/images/kshark-filter-event-adv-list.png differ diff --git a/Documentation/HTML/images/kshark-filter-events-sched.png b/Documentation/HTML/images/kshark-filter-events-sched.png new file mode 100644 index 0000000..0941317 Binary files /dev/null and b/Documentation/HTML/images/kshark-filter-events-sched.png differ diff --git a/Documentation/HTML/images/kshark-filter-events.png b/Documentation/HTML/images/kshark-filter-events.png new file mode 100644 index 0000000..4732f8a Binary files /dev/null and b/Documentation/HTML/images/kshark-filter-events.png differ diff --git a/Documentation/HTML/images/kshark-filter-list-adv-irq.png b/Documentation/HTML/images/kshark-filter-list-adv-irq.png new file mode 100644 index 0000000..0b04031 Binary files /dev/null and b/Documentation/HTML/images/kshark-filter-list-adv-irq.png differ diff --git a/Documentation/HTML/images/kshark-filter-sync-graph-1.png b/Documentation/HTML/images/kshark-filter-sync-graph-1.png new file mode 100644 index 0000000..82e5849 Binary files /dev/null and b/Documentation/HTML/images/kshark-filter-sync-graph-1.png differ diff --git a/Documentation/HTML/images/kshark-filter-task-menu.png b/Documentation/HTML/images/kshark-filter-task-menu.png new file mode 100644 index 0000000..77fb98a Binary files /dev/null and b/Documentation/HTML/images/kshark-filter-task-menu.png differ diff --git a/Documentation/HTML/images/kshark-filter.png b/Documentation/HTML/images/kshark-filter.png new file mode 100644 index 0000000..0e9a380 Binary files /dev/null and b/Documentation/HTML/images/kshark-filter.png differ diff --git a/Documentation/HTML/images/kshark-graph-info-line.png b/Documentation/HTML/images/kshark-graph-info-line.png new file mode 100644 index 0000000..4f6be47 Binary files /dev/null and b/Documentation/HTML/images/kshark-graph-info-line.png differ diff --git a/Documentation/HTML/images/kshark-graph-plot-area.png b/Documentation/HTML/images/kshark-graph-plot-area.png new file mode 100644 index 0000000..84ed90e Binary files /dev/null and b/Documentation/HTML/images/kshark-graph-plot-area.png differ diff --git a/Documentation/HTML/images/kshark-graph-plot-title.png b/Documentation/HTML/images/kshark-graph-plot-title.png new file mode 100644 index 0000000..cbb8d2d Binary files /dev/null and b/Documentation/HTML/images/kshark-graph-plot-title.png differ diff --git a/Documentation/HTML/images/kshark-list-adjust.png b/Documentation/HTML/images/kshark-list-adjust.png new file mode 100644 index 0000000..aff15c1 Binary files /dev/null and b/Documentation/HTML/images/kshark-list-adjust.png differ diff --git a/Documentation/HTML/images/kshark-list-enable-filter-1.png b/Documentation/HTML/images/kshark-list-enable-filter-1.png new file mode 100644 index 0000000..8321c92 Binary files /dev/null and b/Documentation/HTML/images/kshark-list-enable-filter-1.png differ diff --git a/Documentation/HTML/images/kshark-list-graph-follow-1.png b/Documentation/HTML/images/kshark-list-graph-follow-1.png new file mode 100644 index 0000000..c4f8702 Binary files /dev/null and b/Documentation/HTML/images/kshark-list-graph-follow-1.png differ diff --git a/Documentation/HTML/images/kshark-list-graph-follow-2.png b/Documentation/HTML/images/kshark-list-graph-follow-2.png new file mode 100644 index 0000000..451de10 Binary files /dev/null and b/Documentation/HTML/images/kshark-list-graph-follow-2.png differ diff --git a/Documentation/HTML/images/kshark-list-info-area.png b/Documentation/HTML/images/kshark-list-info-area.png new file mode 100644 index 0000000..394dfdd Binary files /dev/null and b/Documentation/HTML/images/kshark-list-info-area.png differ diff --git a/Documentation/HTML/images/kshark-open.png b/Documentation/HTML/images/kshark-open.png new file mode 100644 index 0000000..1b201ce Binary files /dev/null and b/Documentation/HTML/images/kshark-open.png differ diff --git a/Documentation/HTML/images/kshark-plot-cpu-1.png b/Documentation/HTML/images/kshark-plot-cpu-1.png new file mode 100644 index 0000000..f49de93 Binary files /dev/null and b/Documentation/HTML/images/kshark-plot-cpu-1.png differ diff --git a/Documentation/HTML/images/kshark-plot-cpu-2.png b/Documentation/HTML/images/kshark-plot-cpu-2.png new file mode 100644 index 0000000..c1ea7d1 Binary files /dev/null and b/Documentation/HTML/images/kshark-plot-cpu-2.png differ diff --git a/Documentation/HTML/images/kshark-plot-cpu-result.png b/Documentation/HTML/images/kshark-plot-cpu-result.png new file mode 100644 index 0000000..635ddda Binary files /dev/null and b/Documentation/HTML/images/kshark-plot-cpu-result.png differ diff --git a/Documentation/HTML/images/kshark-plot-menu.png b/Documentation/HTML/images/kshark-plot-menu.png new file mode 100644 index 0000000..a26f052 Binary files /dev/null and b/Documentation/HTML/images/kshark-plot-menu.png differ diff --git a/Documentation/HTML/images/kshark-plot-task-measure-preempt.png b/Documentation/HTML/images/kshark-plot-task-measure-preempt.png new file mode 100644 index 0000000..243aef1 Binary files /dev/null and b/Documentation/HTML/images/kshark-plot-task-measure-preempt.png differ diff --git a/Documentation/HTML/images/kshark-plot-task-measure.png b/Documentation/HTML/images/kshark-plot-task-measure.png new file mode 100644 index 0000000..d4b7149 Binary files /dev/null and b/Documentation/HTML/images/kshark-plot-task-measure.png differ diff --git a/Documentation/HTML/images/kshark-plot-task-result.png b/Documentation/HTML/images/kshark-plot-task-result.png new file mode 100644 index 0000000..12bbf8b Binary files /dev/null and b/Documentation/HTML/images/kshark-plot-task-result.png differ diff --git a/Documentation/HTML/images/kshark-plot-task-select.png b/Documentation/HTML/images/kshark-plot-task-select.png new file mode 100644 index 0000000..be7f365 Binary files /dev/null and b/Documentation/HTML/images/kshark-plot-task-select.png differ diff --git a/Documentation/HTML/images/kshark-plot-task-zoom-1.png b/Documentation/HTML/images/kshark-plot-task-zoom-1.png new file mode 100644 index 0000000..716b5c6 Binary files /dev/null and b/Documentation/HTML/images/kshark-plot-task-zoom-1.png differ diff --git a/Documentation/HTML/images/kshark-select-a-1.png b/Documentation/HTML/images/kshark-select-a-1.png new file mode 100644 index 0000000..40a6cfa Binary files /dev/null and b/Documentation/HTML/images/kshark-select-a-1.png differ diff --git a/Documentation/HTML/images/kshark-select-b-1.png b/Documentation/HTML/images/kshark-select-b-1.png new file mode 100644 index 0000000..df4df41 Binary files /dev/null and b/Documentation/HTML/images/kshark-select-b-1.png differ diff --git a/Documentation/HTML/images/kshark-zoom-in-2.png b/Documentation/HTML/images/kshark-zoom-in-2.png new file mode 100644 index 0000000..25235e5 Binary files /dev/null and b/Documentation/HTML/images/kshark-zoom-in-2.png differ diff --git a/Documentation/HTML/images/kshark-zoom-in-3.png b/Documentation/HTML/images/kshark-zoom-in-3.png new file mode 100644 index 0000000..2c55319 Binary files /dev/null and b/Documentation/HTML/images/kshark-zoom-in-3.png differ diff --git a/Documentation/HTML/images/kshark-zoom-in-select.png b/Documentation/HTML/images/kshark-zoom-in-select.png new file mode 100644 index 0000000..12c2be7 Binary files /dev/null and b/Documentation/HTML/images/kshark-zoom-in-select.png differ diff --git a/Documentation/HTML/images/kshark-zoom-out-select.png b/Documentation/HTML/images/kshark-zoom-out-select.png new file mode 100644 index 0000000..25c7cfe Binary files /dev/null and b/Documentation/HTML/images/kshark-zoom-out-select.png differ diff --git a/Documentation/HTML/index.html b/Documentation/HTML/index.html new file mode 100644 index 0000000..9ab45a1 --- /dev/null +++ b/Documentation/HTML/index.html @@ -0,0 +1,631 @@ + + +KernelShark + + + +

KernelShark

+ +

Table of Contents

+

Introduction
+

The Graph View
+

+
  • Zooming In +
  • Zooming Out +
  • Graph Markers +
  • Graph Cursor +
  • Graph Plots + +
  • Process Plots +
  • CPU Plots +
    •  +
    •  +

    The List View
    +

    +
  • Selecting an event +
  • Graph follows toggle +
    •  +

    Filters
    +

    +
  • Task Filter (filtering processes) +
  • Event Filter + +
  • Advance Event Filter +
    •  +
    •  + + +

    Introduction

    + +

    +KernelShark is a front end reader of trace-cmd(1) output. "trace-cmd record" +and "trace-cmd extract" create a trace.dat (trace-cmd.dat(5)) file. +kernelshark can read this file and produce a graph and list view of its data. +

    + + + +

    +The application has two main viewing areas split by a paned divider. The top half +is a graphical display of the data and the bottom half is a list view of each +event. Underneath the menu bar is the graph information area: +

    + +

    Graph Info Area

    + + + +

    +The graph information line displays the timestamp of various locations. +The Pointer: shows the timestamp of where the mouse pointer is. The Cursor: is +the timestamp of the cursor location. To select a cursor location, double click +on the graph. Marker A is set with a left mouse click and Marker B is set +with a with a left mouse click while holding down the shift key. +

    + +

    +The graph is broken into two parts, the plot title section: +

    + +

    Plot Title

    + + + +

    +and the plot area: +

    + + + +

    +The plot area contains the data of the given plot, where plots can be per CPU or +per process. The top of the plot area shows a time line. The numbers in the time +line are seconds. The time in the time line is taken from the timestamps within +the trace.dat file which are architecture dependent. The time usually is the timestamp +from when the system started. +

    + +

    +Below the graph is the list area. +

    + +

    List Area

    + + + +

    +The list area contains the Page of the list. The list can hold a maximum of +1 million entries per page. If the trace data contains more than a million +entries, then the list will have more than one page. +

    + +

    +The list area also contains a search field to search for elements in the +list. +

    + +

    The Graph View

    + +

    +The graph view of kernelshark shows graphical plots of the data stored in +the trace.dat file. The data plots are per CPU or per process. +When there are too many events within the resolution of the graph, +the plots will appear as a rainbow colored bar. To make more sense out of +the graphs, you need to zoom into a given location to see the details of +that time frame more clearly. +

    + +

    Zooming In

    + +

    +To zoom in, left mouse click and hold and then drag the mouse right, release +to zoom. When you click the left mouse button a line will appear and stay +at that location. When you move the mouse to the right, another line appears +and will follow the mouse. When you release the mouse button, the area +between the two lines become the new width of the screen. That is, the graph +zooms in until the lines match the width of the screen. This allows you to +zoom into a specific location. +

    + + + +

    +The area that you selected will now become the new width of the viewable area. +The smaller the selection, the deeper the zoom. Note, that you must select 10 +pixels to zoom in. Less than 10 pixels will cancel the zoom. You can continue zooming +in until you get mor details. +

    + + + +

    +If a plot contains no events within the zoomed in raidus, then the line will be empty, +as CPU 1 is in the above image. CPU 0 shows two tasks that were running. One task +is given a pink/red color and the other a green color. The colored box represents +a task other than idle was running. The small lines that jet out of the box are +where events occur. +

    + +

    +If you zoom in enough such that a single event has enough room between itself +and other events, the type of event and the name and PID of the task that was running will appear +over the event. +

    + +

    Zooming Out

    + +

    +To zoom back out, left mouse click and hold and then drag the mouse left. +This time the width between the two lines will become a single pixel. +The farther apart the lines are, the farther the zoom out will be. +Zoom out will stop at the width of the full trace. +

    + + + +

    +When the mouse is over an event, a tool tip will appear showing the event name, +the latency data, the event info, the timestamp and the process +name and process ID. +

    + + + +

    Graph Markers

    + +

    +There are two markers that can be placed on the graph as well as a cursor. +Marker A is set by a left mouse click. When a marker is set, the + graph info area will be updated. +Marker A is represented by a green line: +

    + + + +

    +To set Marker B, press and hold the shift key and click the left mouse button. +Marker B will show up in red. +

    + + + +

    +When both the A and B markers are set, the graph info area +will show the timestamp of where the A and B markers are, as well as the difference +between the two. All timestamps are in seconds, with a resolution of microseconds. +

    + +

    Graph Cursor

    + +

    +Double clicking on the graph will set the cursor. The cursor is a blue line, and when +it is set, it will also select the event in the list view that is the closest event at the +timeline of where the cursor was selected at. +

    + + + +

    +The above shows that list item 217448 (sys_exit) was the closest event to where +the cursor was selected. +

    + +

    +Note that setting the cursor with double click will also set Marker A. +

    + +

    Graph Plots

    + +

    +The graph data is represented by plots. The data on the plots is either CPU specific or +process specific. If it is CPU specific, then the data is the time line of events that +happened on a given CPU (which CPU is shown in the plot title area). +If the plot is process specific, then the time line of events is for the given +process regardless of what CPU it was on at the time. The process name is also shown +in the plot title area. +

    + +

    +By default, all the CPUs within the loaded trace.dat file are plotted. +There's two ways to plot a process. One way is to right mouse click over a +displayed process in the graph and select the plot option. This will add the +process plot directly underneath the CPU plot that the process was on where +the right mouse click took place. The other way is to use the plot menu. +

    + + + +

    Process Plots

    + +

    +Selecting the "Task" menu will bring up a dialog with all the processes (also referred +to as tasks) that was found in the trace data. +

    + + + +

    +Selecting a process in this dialog will add the task plot to the bottom of the graph +area. Unselecting a process in this dialog will remove the plot. +

    + + + +

    +The colors in the process plots are different depending on what CPU the process +was on at the time. The CPU plots change colors as different processes run +on the CPU, and the process plots change color depending on what CPU the process +is running on at a time. This makes it easy to see how much a process +bounces around the CPUs. Zooming in on a process plot also shows some more +characteristics of the process. +

    + + + +

    +The hollow green box that is shown in front of some events in the process +plot represents when the task was woken up from a sleeping state to +when it actually ran. The hollow red box between some events shows that +the process was preempted by another process even though that process +was still runnable. +

    + +

    +Since the hollow green box shows the wake up latency of the task, the +A,B markers can be used to measure that time. +

    + + + +

    +The above shows that the epiphany-browser with PID 28072 had a 479 microsecond wake up +latency. The same can be done with the preemption latency. +

    + + + +

    CPU Plots

    + +

    +Selecting the CPU plot menu pops up a dialog that shows the available CPUs that +can be plotted. +

    + + + +

    +Removing a selected CPU and hitting "Apply" will remove that CPU plot. +

    + + + +

    + + + +

    The List View

    + +

    +The list view is in the bottom half paned window and can be expanded or shortened +with the paned handle. +

    + + + +

    +The top of the list view contains the list area which has the list page, list +search, and graph follow toggle button. If more than a million events are stored in the +list, then each set of million will be on a different page. +

    + +

    +The columns of the list are: +

    + + + +

    +The list search can find an event based on the contents in a row. Select a column, a +match criteria and the content to match will find the next row that matches the +search. The match criteria is one of the following: +

    + + + +

    +The search will find the next event that has the matching data within the column. +

    + +

    Selecting an event

    +

    +A single click on a row will select the row, but a double click on a row will select +that row as well as set the graph cursor to the location of that event. If the plot +that the event is on is not visible then the graph will adjust it vertical view area +to show the plot with the selected event. This has no effect on +graph markers. +

    + +

    Graph follows toggle

    + +

    +When the "graph follows" toggle is set, then even a single click on a row +will move the graph cursor. With the mouse focus on the list, using the keyboard +up and down arrow keys will move the selection of the list as well as the graph +cursor. +

    + + +

    + + +

    Filters

    + +

    +The amount of data that can be stored in a trace.dat file can be enourmous. +To make any sense out of some traces, it may be required to only display various +events. The same can be true about processes. +Kernelshark has filters for tasks as well as for events. The task filter +affects both the graph and the list, but the graph and list each have a separate +event filter. +

    + +

    Task Filter (filtering processes)

    + +

    +The task (process) filter is currently set by a right mouse click over +an event on either the graph or the list view, and by selecting the option to add or remove the +task to/from the task filter. The tasks within the task filter are the same for +both the graph and list, but each can be enabled separately. +

    + +

    +There are two types of task filters: +

    + + + +

    +If there are any tasks within the Task Filter then only those tasks will be displayed +when the filter is enabled. Any task within the Hide Tasks filter will not be +displayed, even if that same task is in the Task Filter. +

    + + + +

    +When either filter contains a task, the filter can be enabled. +

    + + + +

    The scheduling events

    + +

    +The events "sched_switch", "sched_wakeup", and "sched_wakeup_new" are treated +differently by the task filter. Because these events deal with two tasks +(previous and next, waker and wakee), if either of the tasks should be visible +then that event is visible regardless if the other task should be hidden. +This may seem confusing when an event that is hidden shows up in the Task column. +

    + +

    Event Filter

    + +

    +The graph and list view each have their own event filter. The event filters +are enabled through the Filter menu on the top menu-bar. +

    + + + +

    +Selecting either the "list events" or "graph events" will bring up the event +dialog with the events that are visible selected. +

    + +

    +Note: these do not mean that the events exist in the trace.dat file. They are +selected if the events are not to be hidden. Events that do not exist in the trace +and will not be displayed regardless of whether or not they are filtered. +

    + + + +

    +By clicking on "All" or any of the systems will either deselect all events underneath +or select all events underneath depending on the previous state of the box being +selected. By deselecting all events, it makes it easier to enable just a few individual events. +

    + + + +

    +If it is desired that the graph and list view have the same events filtered, then just +set up the desired filtering in one and then synchronize the other through +the filter menu. +

    + + + + + +

    Advance Event Filter

    + +

    +Filtering on events may not be enough. The ability to filter on the content +of individual events may be needed. In order to accomplish this, the advanced event +filtering is used. Selecting the "list advanced event" or "graph advanced event" +from the filter menu will pop up the advanced event filtering dialog. +The graph and list view each have their own advanced event filter. +

    + + + +

    +The "Filter:" entry at the bottom of the dialog is where the advanced filter is +written. Above that is helper buttons to pick events, operations and event fields. +The syntax of the filter is: +

    + +

    +   FILTER := EVENTS | EVENTS ':' EXPRESSION
+   EVENTS := EVENTS ',' EVENTS | SYSTEM '/' EVENT | SYSTEM | EVENT
+   SYSTEM := any system name
+   EVENT  := any event name
+   EXPRESSION := EXPRESSION BOOL EXPRESSION | '(' EXPRESSION ')' | OPERATION
+   BOOL   := '&&' | '||'
+   OPERATION := '!' EXPRESSION | LVALUE CMP RVALUE | LVALUE STRCMP STRVALUE
+   CMP    := '>' | '<' | '==' | '>=' | '<=' | '!='
+   STRCMP := '==' | '!=' | '=~' | '!~'
+   RVALUE := integer | FIELD
+   STRVALUE := string (double quoted value) | FIELD
+   LVALUE := FIELD | EXPR
+   EXPR   := FIELD OP RVALUE | '(' EXPR ')' | EXPR OP EXPR
+   FIELD  := a field name of an event
+   OP     := '+' | '-' | '*' | '/' | '<<' | '>>' | '&' | '!'
+
    + +

    +Spaces are ignored. The example used in the dialog figure: +

    + +
    +  sched/sched_switch : next_prio < 100 && (prev_prio > 100 && prev_pid != 0)
+
    + +

    +The sched/ is not necessary because without it, the filter will process all events +named sched_switch, and since there is only one event +that has that name, including the sched/ is redundant. +

    + +

    +The next_prio, prev_prio and prev_pid are all +event fields of the sched_swich event. +

    + +

    +If just sched was used and the /sched_switch was omitted, it would +still be a valid filter, but it would behave differently. By just specifying +a system, the filter will run on all events within that system. When a field +is encountered that does not belong to an event, then that compare will be set to false. +

    + +
    +   sched : prev_pid != 0
+   sched : !(prev_pid == 0)
+
    + +

    +The above two filters are not equivalent. They are for the sched_switch event, +but not for the other events. The first filter will return false for all events +that do not contain the prev_pid field, but the second filter would return +true for all events that do not contain that field. Again, if the event does +not contain a field, just that compare will be evaluated to false, not the entire +expression. This means for events that do not have the prev_pid field, +the above filters would be equivalent to: +

    + +
    +   sched : FALSE
+   sched : !(FALSE)
+
    + +

    +By letting the filters contain fields that do not belong to an event be valid, +allows for various tricks where two events can share the same +filter. +

    + +
    +   sched_switch, sched_wake.* : next_pid == 1 || pid == 1
+
    + +

    +The schedule events that have next_pid and not pid as a field +will just compare the first part of the || and those events with +pid but without next_pid will be compared against the second +part of the || +

    + +

    +Notice: that event names in the filter can be regular expressions. +

    + +

    +String fields can have regular expressions used in their comparing if +=~ or !~ are used. +

    + +
    +   sched_switch : next_comm =~ "^events/[23]$"
+
    + +

    +Note: When adding an advanced filter, all non advanced filters +(added by the event filter dialog box) will be removed, and only the advanced +filters will stay. But non advanced filters may be added after advanced +filters have been. The events that have advanced filters will be shadowed +in the event filter dialog: +

    + + + +

    +Just do not click on the adavanced filter box and hit "Apply" unless you want to remove +the adavanced filter. Non advanced filters can now be selected without affecting +the advanced filters. +

    + + + +

    +When adavanced filters already exist when the advanced filter dialog box pops up, +they will be listed in the area at the top of the dialog. Although +one filter may have been written, the list will be per event. A check box +is to the left of the filter, when checked, the filter will be deleted if +the "Apply" button is selected. +

    + + + + + -- cgit v1.2.2 From d2c42a8b5238abd33f33e6fe9ae8b48b8670f981 Mon Sep 17 00:00:00 2001 From: Randy Dunlap Date: Fri, 9 Apr 2010 13:24:54 -0400 Subject: doc: Fix typos and grammar in kernelshark help Signed-off-by: Randy Dunlap Signed-off-by: Steven Rostedt --- Documentation/HTML/index.html | 58 +++++++++++++++++++++---------------------- 1 file changed, 29 insertions(+), 29 deletions(-) (limited to 'Documentation/HTML') diff --git a/Documentation/HTML/index.html b/Documentation/HTML/index.html index 9ab45a1..8b3062d 100644 --- a/Documentation/HTML/index.html +++ b/Documentation/HTML/index.html @@ -133,13 +133,13 @@ zoom into a specific location. The area that you selected will now become the new width of the viewable area. The smaller the selection, the deeper the zoom. Note, that you must select 10 pixels to zoom in. Less than 10 pixels will cancel the zoom. You can continue zooming -in until you get mor details. +in until you get more details.

    -If a plot contains no events within the zoomed in raidus, then the line will be empty, +If a plot contains no events within the zoomed in radius, then the line will be empty, as CPU 1 is in the above image. CPU 0 shows two tasks that were running. One task is given a pink/red color and the other a green color. The colored box represents a task other than idle was running. The small lines that jet out of the box are @@ -200,7 +200,7 @@ between the two. All timestamps are in seconds, with a resolution of microsecond

    Double clicking on the graph will set the cursor. The cursor is a blue line, and when it is set, it will also select the event in the list view that is the closest event at the -timeline of where the cursor was selected at. +timeline of where the cursor was selected.

    @@ -227,10 +227,10 @@ in the plot title area.

    By default, all the CPUs within the loaded trace.dat file are plotted. -There's two ways to plot a process. One way is to right mouse click over a +There are two ways to plot a process. One way is to right mouse click over a displayed process in the graph and select the plot option. This will add the process plot directly underneath the CPU plot that the process was on where -the right mouse click took place. The other way is to use the plot menu. +the right mouse click took place. The other way is to use the Plots menu.

    @@ -238,8 +238,8 @@ the right mouse click took place. The other way is to use the plot menu.

    Process Plots

    -Selecting the "Task" menu will bring up a dialog with all the processes (also referred -to as tasks) that was found in the trace data. +Selecting the "Tasks" menu item will bring up a dialog with all the processes (also referred +to as tasks) that were found in the trace data.

    @@ -287,7 +287,7 @@ latency. The same can be done with the preemption latency.

    CPU Plots

    -Selecting the CPU plot menu pops up a dialog that shows the available CPUs that +Selecting the "CPUs" plot menu item pops up a dialog that shows the available CPUs that can be plotted.

    @@ -314,7 +314,7 @@ with the paned handle.

    The top of the list view contains the list area which has the list page, list -search, and graph follow toggle button. If more than a million events are stored in the +search, and "graph follows" toggle button. If more than a million events are stored in the list, then each set of million will be on a different page.

    @@ -330,10 +330,10 @@ resolution.
  • PID - The process ID of the task that was running when the event occurred.
  • Latency - The latency is broken into 5 fields:
      -
    1. Interrupts disabled - 'd' if interrupts are enabled, otherwise '.' +
    2. Interrupts disabled - 'd' if interrupts are disabled, otherwise '.'
    3. Need reschedule - 'N' if the kernel was notified that a schedule is needed, otherwise '.'
    4. In IRQ - 'h' if in a hard IRQ (hardware triggerred), 's' if in a soft IRQ - (context where the kernel initiated a the irq handler) or if soft IRQs + (context where the kernel initiated a the IRQ handler) or if soft IRQs are disabled, 'H' if in a hard IRQ and soft IRQs are disabled or the hard IRQ triggerred while processing a soft IRQ, otherwise '.'
    5. Preemption counter - The index of the preemption counter. If it is other @@ -341,7 +341,7 @@ resolution. if a schedule has been requested by some event. If the counter is zero, then '.' is shown.
    6. Lock depth - The depth of the big kernel lock being held. The big kernel - lock is recusive (same task may acquire it multiple times). On the first + lock is recursive (same task may acquire it multiple times). On the first acquisition, the depth is zero. This field will be zero or greater, or '.' if the big kernel lock is not held. When the big kernel lock is finally removed from the kernel, this field will go away as well. @@ -352,8 +352,8 @@ resolution.

      The list search can find an event based on the contents in a row. Select a column, a -match criteria and the content to match will find the next row that matches the -search. The match criteria is one of the following: +match criteria and the content to match to find the next row that matches the +search. The match criterion is one of the following:

        @@ -371,7 +371,7 @@ The search will find the next event that has the matching data within the column

        A single click on a row will select the row, but a double click on a row will select that row as well as set the graph cursor to the location of that event. If the plot -that the event is on is not visible then the graph will adjust it vertical view area +that the event is on is not visible then the graph will adjust its vertical view area to show the plot with the selected event. This has no effect on graph markers.

        @@ -392,7 +392,7 @@ cursor.

        Filters

        -The amount of data that can be stored in a trace.dat file can be enourmous. +The amount of data that can be stored in a trace.dat file can be enormous. To make any sense out of some traces, it may be required to only display various events. The same can be true about processes. Kernelshark has filters for tasks as well as for events. The task filter @@ -459,13 +459,13 @@ dialog with the events that are visible selected.

        Note: these do not mean that the events exist in the trace.dat file. They are selected if the events are not to be hidden. Events that do not exist in the trace -and will not be displayed regardless of whether or not they are filtered. +will not be displayed regardless of whether or not they are filtered.

        -By clicking on "All" or any of the systems will either deselect all events underneath +Clicking on "All" or any of the systems will either deselect all events underneath or select all events underneath depending on the previous state of the box being selected. By deselecting all events, it makes it easier to enable just a few individual events.

        @@ -487,13 +487,13 @@ as what is in the list filter. as what is in the graph filter.

      -

      Advance Event Filter

      +

      Advanced Event Filter

      Filtering on events may not be enough. The ability to filter on the content of individual events may be needed. In order to accomplish this, the advanced event filtering is used. Selecting the "list advanced event" or "graph advanced event" -from the filter menu will pop up the advanced event filtering dialog. +from the Filter menu will pop up the advanced event filtering dialog. The graph and list view each have their own advanced event filter.

      @@ -570,7 +570,7 @@ the above filters would be equivalent to:

      -By letting the filters contain fields that do not belong to an event be valid, +Letting filters contain fields that do not belong to an event be valid allows for various tricks where two events can share the same filter.

      @@ -587,7 +587,7 @@ part of the ||

      -Notice: that event names in the filter can be regular expressions. +Notice that event names in the filter can be regular expressions.

      @@ -600,28 +600,28 @@ String fields can have regular expressions used in their comparing if

      -Note: When adding an advanced filter, all non advanced filters +Note: When adding an advanced filter, all non-advanced filters (added by the event filter dialog box) will be removed, and only the advanced -filters will stay. But non advanced filters may be added after advanced -filters have been. The events that have advanced filters will be shadowed +filters will stay. But non-advanced filters may be added after advanced +filters have been. The events that have advanced filters will be shaded in the event filter dialog:

      -Just do not click on the adavanced filter box and hit "Apply" unless you want to remove -the adavanced filter. Non advanced filters can now be selected without affecting +Just do not click on the advanced filter box and hit "Apply" unless you want to remove +the advanced filter. Non-advanced filters can now be selected without affecting the advanced filters.

      -When adavanced filters already exist when the advanced filter dialog box pops up, +When advanced filters already exist when the advanced filter dialog box pops up, they will be listed in the area at the top of the dialog. Although one filter may have been written, the list will be per event. A check box -is to the left of the filter, when checked, the filter will be deleted if +is to the left of the filter. When checked, the filter will be deleted if the "Apply" button is selected.

      -- cgit v1.2.2 From 04b2e439a93677bc6ef5035729bf05e7427ac13e Mon Sep 17 00:00:00 2001 From: Steven Rostedt Date: Fri, 9 Apr 2010 14:40:25 -0400 Subject: doc: Fixed more types and cleared up some explanations Reported-by: Darren Hart Signed-off-by: Steven Rostedt --- Documentation/HTML/index.html | 100 ++++++++++++++++++++++++++---------------- 1 file changed, 61 insertions(+), 39 deletions(-) (limited to 'Documentation/HTML') diff --git a/Documentation/HTML/index.html b/Documentation/HTML/index.html index 8b3062d..331baf4 100644 --- a/Documentation/HTML/index.html +++ b/Documentation/HTML/index.html @@ -16,7 +16,7 @@
    7. Graph Cursor
    8. Graph Plots -
    9. Process Plots +
    10. Task Plots
    11. CPU Plots
      12. @@ -27,7 +27,7 @@

      Filters

      -
    12. Task Filter (filtering processes) +
    13. Task Filter
    14. Event Filter
    15. Advance Event Filter @@ -79,7 +79,7 @@ and the plot area:

      The plot area contains the data of the given plot, where plots can be per CPU or -per process. The top of the plot area shows a time line. The numbers in the time +per task. The top of the plot area shows a time line. The numbers in the time line are seconds. The time in the time line is taken from the timestamps within the trace.dat file which are architecture dependent. The time usually is the timestamp from when the system started. @@ -108,7 +108,7 @@ list.

      The graph view of kernelshark shows graphical plots of the data stored in -the trace.dat file. The data plots are per CPU or per process. +the trace.dat file. The data plots are per CPU or per task. When there are too many events within the resolution of the graph, the plots will appear as a rainbow colored bar. To make more sense out of the graphs, you need to zoom into a given location to see the details of @@ -139,11 +139,17 @@ in until you get more details.

      -If a plot contains no events within the zoomed in radius, then the line will be empty, -as CPU 1 is in the above image. CPU 0 shows two tasks that were running. One task -is given a pink/red color and the other a green color. The colored box represents -a task other than idle was running. The small lines that jet out of the box are -where events occur. +To save on resources, when zooming in, the beginning +and end of the full trace may not be reachable with the horizontal scroll bar. +If a plot contains no events within the reachable area, then the line will be empty, +as CPU 1 is in the above image. +

      + +

      +CPU 0 shows two tasks that were running. One task +is given a pink/red color and the other a green color. The think colored +horizontal bar represents a task other than idle was running. The small +lines that jet out of the bar are where events occur.

      @@ -165,8 +171,8 @@ Zoom out will stop at the width of the full trace.

      When the mouse is over an event, a tool tip will appear showing the event name, -the latency data, the event info, the timestamp and the process -name and process ID. +the latency data, the event info, the timestamp and the task +name and task process ID.

      @@ -218,60 +224,60 @@ Note that setting the cursor with double click will also set Marker A.

      The graph data is represented by plots. The data on the plots is either CPU specific or -process specific. If it is CPU specific, then the data is the time line of events that +task specific. If it is CPU specific, then the data is the time line of events that happened on a given CPU (which CPU is shown in the plot title area). -If the plot is process specific, then the time line of events is for the given -process regardless of what CPU it was on at the time. The process name is also shown +If the plot is task specific, then the time line of events is for the given +task regardless of what CPU it was on at the time. The task name is also shown in the plot title area.

      By default, all the CPUs within the loaded trace.dat file are plotted. -There are two ways to plot a process. One way is to right mouse click over a -displayed process in the graph and select the plot option. This will add the -process plot directly underneath the CPU plot that the process was on where +There are two ways to plot a task. One way is to right mouse click over a +displayed task in the graph and select the plot option. This will add the +task plot directly underneath the CPU plot that the task was on where the right mouse click took place. The other way is to use the Plots menu.

      -

      Process Plots

      +

      Task Plots

      -Selecting the "Tasks" menu item will bring up a dialog with all the processes (also referred -to as tasks) that were found in the trace data. +Selecting the "Tasks" menu item will bring up a dialog with all the tasks +that were found in the trace data.

      -Selecting a process in this dialog will add the task plot to the bottom of the graph -area. Unselecting a process in this dialog will remove the plot. +Selecting a task in this dialog will add the task plot to the bottom of the graph +area. Unselecting a task in this dialog will remove the plot.

      -The colors in the process plots are different depending on what CPU the process -was on at the time. The CPU plots change colors as different processes run -on the CPU, and the process plots change color depending on what CPU the process -is running on at a time. This makes it easy to see how much a process -bounces around the CPUs. Zooming in on a process plot also shows some more -characteristics of the process. +The colors in the task plots are different depending on which CPU the task +was on at the time. The CPU plots change colors as different tasks run +on the CPU, and the task plots change color depending on what CPU the task +is running on. This makes it easy to see how much a task +bounces around the CPUs. Zooming in on a task plot also shows some more +characteristics of the task.

      -The hollow green box that is shown in front of some events in the process +The hollow green bar that is shown in front of some events in the task plot represents when the task was woken up from a sleeping state to -when it actually ran. The hollow red box between some events shows that -the process was preempted by another process even though that process +when it actually ran. The hollow red bar between some events shows that +the task was preempted by another task even though that task was still runnable.

      -Since the hollow green box shows the wake up latency of the task, the +Since the hollow green bar shows the wake up latency of the task, the A,B markers can be used to measure that time.

      @@ -284,7 +290,7 @@ latency. The same can be done with the preemption latency. -

      CPU Plots

      +

      CPU Plots

      Selecting the "CPUs" plot menu item pops up a dialog that shows the available CPUs that @@ -332,12 +338,12 @@ resolution.

      1. Interrupts disabled - 'd' if interrupts are disabled, otherwise '.'
      2. Need reschedule - 'N' if the kernel was notified that a schedule is needed, otherwise '.' -
      3. In IRQ - 'h' if in a hard IRQ (hardware triggerred), 's' if in a soft IRQ +
      4. In IRQ - 'h' if in a hard IRQ (hardware triggered), 's' if in a soft IRQ (context where the kernel initiated a the IRQ handler) or if soft IRQs are disabled, 'H' if in a hard IRQ and soft IRQs are disabled or the hard IRQ - triggerred while processing a soft IRQ, otherwise '.' + triggered while processing a soft IRQ, otherwise '.'
      5. Preemption counter - The index of the preemption counter. If it is other - than zero, then the kernel will not preempt the running processes, even + than zero, then the kernel will not preempt the running tasks, even if a schedule has been requested by some event. If the counter is zero, then '.' is shown.
      6. Lock depth - The depth of the big kernel lock being held. The big kernel @@ -394,16 +400,16 @@ cursor.

        The amount of data that can be stored in a trace.dat file can be enormous. To make any sense out of some traces, it may be required to only display various -events. The same can be true about processes. +events. The same can be true about tasks. Kernelshark has filters for tasks as well as for events. The task filter affects both the graph and the list, but the graph and list each have a separate event filter.

        -

        Task Filter (filtering processes)

        +

        Task Filter

        -The task (process) filter is currently set by a right mouse click over +The task filter is currently set by a right mouse click over an event on either the graph or the list view, and by selecting the option to add or remove the task to/from the task filter. The tasks within the task filter are the same for both the graph and list, but each can be enabled separately. @@ -432,6 +438,18 @@ When either filter contains a task, the filter can be enabled. +

        +When a task is not in the "Task Filter", the pop up will show the +menu item "Add task". When a task is in the "Task Filter" the +pop up will show "Remove task". +

        + +

        +When a task is not in the "Hide Tasks", the pop up will show the +menu item "Hide task". When a task is in the "Hide Tasks", the +pop up will show "Show task". +

        +

        The scheduling events

        @@ -599,6 +617,10 @@ String fields can have regular expressions used in their comparing if sched_switch : next_comm =~ "^events/[23]$" +

        +The available regular expressions are described in regex(7). +

        +

        Note: When adding an advanced filter, all non-advanced filters (added by the event filter dialog box) will be removed, and only the advanced -- cgit v1.2.2 From 7f16dcb25f80f09978c762e23aca70882397ab05 Mon Sep 17 00:00:00 2001 From: Steven Rostedt Date: Fri, 9 Apr 2010 16:33:55 -0400 Subject: doc: Use timestamp and timeline instead of time stamp and time line The document is inconsistent with its use of time stamp and timestamp as well as time line and timeline. This patch changes them all to be single words, except when referencing the GUI labels which have the space. Reported-by: Randy Dunlap Signed-off-by: Steven Rostedt --- Documentation/HTML/index.html | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'Documentation/HTML') diff --git a/Documentation/HTML/index.html b/Documentation/HTML/index.html index 331baf4..12c9957 100644 --- a/Documentation/HTML/index.html +++ b/Documentation/HTML/index.html @@ -79,8 +79,8 @@ and the plot area:

        The plot area contains the data of the given plot, where plots can be per CPU or -per task. The top of the plot area shows a time line. The numbers in the time -line are seconds. The time in the time line is taken from the timestamps within +per task. The top of the plot area shows a timeline. The numbers in the timeline +are seconds. The time in the timeline is taken from the timestamps within the trace.dat file which are architecture dependent. The time usually is the timestamp from when the system started.

        @@ -224,9 +224,9 @@ Note that setting the cursor with double click will also set Marker A.

        The graph data is represented by plots. The data on the plots is either CPU specific or -task specific. If it is CPU specific, then the data is the time line of events that +task specific. If it is CPU specific, then the data is the timeline of events that happened on a given CPU (which CPU is shown in the plot title area). -If the plot is task specific, then the time line of events is for the given +If the plot is task specific, then the timeline of events is for the given task regardless of what CPU it was on at the time. The task name is also shown in the plot title area.

        @@ -331,7 +331,7 @@ The columns of the list are:
        • # - the index into the list.
        • CPU - the CPU that the event occurred on. -
        • Time Stamp - The time stamp of the event. This is in seconds with microsecond +
        • Time Stamp - The timestamp of the event. This is in seconds with microsecond resolution.
        • PID - The process ID of the task that was running when the event occurred.
        • Latency - The latency is broken into 5 fields: -- cgit v1.2.2