{"id":13441015,"url":"https://github.com/cunctator/traceshark","last_synced_at":"2026-01-11T01:03:25.520Z","repository":{"id":19333235,"uuid":"22571940","full_name":"cunctator/traceshark","owner":"cunctator","description":"This is a tool for Linux kernel ftrace and perf events visualization","archived":false,"fork":false,"pushed_at":"2024-11-03T21:53:30.000Z","size":11704,"stargazers_count":169,"open_issues_count":0,"forks_count":21,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-03-20T11:40:12.173Z","etag":null,"topics":["cpu-frequency","cpu-profiling","flame-charts","flamegraph","ftrace","kernel","linux-kernel","perf","perf-events","performance","performance-analysis","profiler","profiling","real-time","scheduling","trace","traces","viewer","visualization","visualizer"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cunctator.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-08-03T09:28:28.000Z","updated_at":"2025-02-20T06:31:07.000Z","dependencies_parsed_at":"2023-02-10T07:00:38.791Z","dependency_job_id":"9ecc259e-003a-40f6-bdc8-665053d53927","html_url":"https://github.com/cunctator/traceshark","commit_stats":null,"previous_names":[],"tags_count":47,"template":false,"template_full_name":null,"purl":"pkg:github/cunctator/traceshark","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cunctator%2Ftraceshark","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cunctator%2Ftraceshark/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cunctator%2Ftraceshark/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cunctator%2Ftraceshark/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cunctator","download_url":"https://codeload.github.com/cunctator/traceshark/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cunctator%2Ftraceshark/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28264088,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-11T00:36:07.053Z","status":"ssl_error","status_checked_at":"2026-01-11T00:35:52.154Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpu-frequency","cpu-profiling","flame-charts","flamegraph","ftrace","kernel","linux-kernel","perf","perf-events","performance","performance-analysis","profiler","profiling","real-time","scheduling","trace","traces","viewer","visualization","visualizer"],"created_at":"2024-07-31T03:01:28.911Z","updated_at":"2026-01-11T01:03:25.460Z","avatar_url":"https://github.com/cunctator.png","language":"C++","readme":"![traceshark logo](https://raw.githubusercontent.com/cunctator/traceshark/882584f48e9c03b85e6a5a6b96725040ef1739f5/images/shark-penguin.png)\n\n# 1. Introduction to Traceshark\n\nThis is a graphical viewer for the Ftrace and Perf events that can be captured by the Linux kernel. It visualizes the following events:\n\n```\ncpu_frequency\ncpu_idle\nsched_migrate_task\nsched_process_exit\nsched_process_fork\nsched_switch\nsched_wakeup\nsched_wakeup_new\nsched_waking\n```\n\nThe `sched_waking` events are not really visualized but there is a button to find the `sched_waking` event that has instigated a particular `sched_wakeup` event.\n\n![traceshark screenshot](https://raw.githubusercontent.com/cunctator/traceshark/4d2083d6df569c3bd59a6b64ef210a5c61714cbe/doc/ts-screenshot5.png)\n\nAbove is a screenshot of traceshark. The eight uppermost graphs are for displaying CPU idle and frequency states. They are eight because the measurement was made on a system with eight virtual CPUs. The green graphs with red circles ![idle graph](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/doc/idle-graph.png) show the CPU idle states while the thicker blue graphs ![idle graph](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/doc/freq-graph.png) show the CPU frequency changes.\n\nBelow these eight graphs are the per CPU scheduling graphs, the different colors of these graphs are for different tasks. The small vertical bars that are shown just above the per CPU graphs indicates the waiting time between a task becoming runnable and being scheduled, the highest height is equal to 20 ms, i.e. a full length means that the waiting time was at least 20 ms, possibly more.\n\n Furthermore, in the scheduling graphs, there are the following subtle markers:\n* ![still running example](https://raw.githubusercontent.com/cunctator/traceshark/b552614ebc40656a6cbaef77e21ee95eb4eb32cd/doc/running60x54.png) The blue triangle indicates that the task was still running when it was scheduled out.\n* ![preempted example](https://raw.githubusercontent.com/cunctator/traceshark/b552614ebc40656a6cbaef77e21ee95eb4eb32cd/doc/preempted60x54.png) The red triangle indicates that the task was preempted when it was scheduled out.\n* ![uninterruptible example](https://raw.githubusercontent.com/cunctator/traceshark/b552614ebc40656a6cbaef77e21ee95eb4eb32cd/doc/unint60x54.png) The magenta colored plus sign indicates that the task went into uninterruptible sleep when it was scheduled out. Note that in practice, only the lower line of the plus sign is visible.\n\nBelow the scheduling graphs are the migration graphs. Task migrations between CPUs are shown with arrows. Fork/exit is shown with an arrow from/to `fork/exit`.\n\nBelow the migration arrows are the unified task graphs, where tasks are shown without caring about which CPU it is running on. Here the time between becoming runnable and being scheduled in shown by horizontal bars.\n\nThese graphs will only be shown if requested by the user. It is necessary to select a task and click the ![Add task graph button](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/addtask30x30.png) button or the `Add a unified graph` button in the task select dialog.\n\nThe task select dialog can be shown by clicking `View -\u003e Show task list`, or by clicking the dedicated ![show task dialog button](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/taskselector30x30.png) button for it on the left panel.\n\n## 1.1 Brief summary of the functionality of the GUI\n\n### 1.1.1 How to zoom and scroll vertically\n\nThe graphs are by default zoomed and scrolled horizontally, i.e. time wise. You can scroll by grabbing the graph with your mouse pointer and zoom with the mouse wheel.\n\nIf you instead want to zoom or scroll vertically, you need to toggle the ![Toggle vertical zoom](https://raw.githubusercontent.com/cunctator/traceshark/67651b9c424d938a1cef99e60e81e948486439fa/images/verticalzoom30x30.png) button.\n\nAnother option is to select the vertical axis by left clicking on it with your mouse pointer. N.B, you should click directly on the line representing the axis, not on the labels, such as \"cpu0\", \"cpu1\", etc. As long as the vertical axis is selected, all scrolling and zooming will be vertical. If you want to switch back to horizontal, then you just need to deselect the axis by clicking on it again. Vertical zooming and scrolling may be particularly useful if you are looking at a trace of a system with a large number of CPUs or if you are short of vertical screen space.\n\n### 1.1.2 Functionality of the menus\n\nThe items in the menus are in general duplicated as buttons. However, there is one exception, those that are in the ```Event``` menu.\n\n![traceshark screenshot](https://raw.githubusercontent.com/cunctator/traceshark/d31d91d0dcd39eea830de1fd9172bf9d309b2bc9/doc/menu_event.png)\n\nAbove is a screenshot of the ```Event``` menu. For these items, there are no push buttons in the GUI. However, these actions can also be triggered by double clicking on the corresponding column of the currently selected event in the events view. Below is a brief explanation of these menu items:\n\n* ![backtrace button](https://raw.githubusercontent.com/cunctator/traceshark/d31d91d0dcd39eea830de1fd9172bf9d309b2bc9/images/eventbacktrace30x30.png)```Show backtrace```: Shows a dialog window containing the backtrace of the currently selected event. The backtrace dialog window will look somewhat like this:\n![close button](https://raw.githubusercontent.com/cunctator/traceshark/d31d91d0dcd39eea830de1fd9172bf9d309b2bc9/doc/backtrace.png)\n* ![moveblue button](https://raw.githubusercontent.com/cunctator/traceshark/d31d91d0dcd39eea830de1fd9172bf9d309b2bc9/images/eventmoveblue30x30.png)```Move blue cursor```: Move the blue cursor to the time of the selected event.\n* ![movered button](https://raw.githubusercontent.com/cunctator/traceshark/d31d91d0dcd39eea830de1fd9172bf9d309b2bc9/images/eventmovered30x30.png)```Move red cursor```: Move the red cursor to the time of the selected event.\n* ![filterpid button](https://raw.githubusercontent.com/cunctator/traceshark/d31d91d0dcd39eea830de1fd9172bf9d309b2bc9/images/eventfilterpid30x30.png)```Filter on event PID```: Filter the events view on the PID of the selected event.\n* ![filtercpu button](https://raw.githubusercontent.com/cunctator/traceshark/d31d91d0dcd39eea830de1fd9172bf9d309b2bc9/images/eventfiltercpu30x30.png)```Filter on event CPU```: Filter the events view on the CPU of the selected event.\n* ![filtertype button](https://raw.githubusercontent.com/cunctator/traceshark/d31d91d0dcd39eea830de1fd9172bf9d309b2bc9/images/eventfiltertype30x30.png)```Filter on event type```: Filter the events view on the type of the selected event.\n\n### 1.1.3 Functionality of the buttons\n\nThere are a number of buttons in the GUI. These buttons are also duplicated in the menus.  Here is a description of the buttons in the left panel:\n\n* ![open button](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/open30x30.png) This button is used to open a trace file.\n* ![close button](https://raw.githubusercontent.com/cunctator/traceshark/b2d0b868ea4947d89240dd627f05bb77bd51ce03/images/close30x30.png) Closes the currently open trace.\n* ![screenshot button](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/screenshot30x30.png) Take a screenshot of the plot and save it to a file.\n* ![task select button](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/taskselector30x30.png) Show the task select dialog. This makes it possible to filter the events view by task, to show a task in the legend, or to show a unified graph. This button is very useful when the user knows the name of a task of interest but cannot find it easily among the scheduling graphs.\n* ![cpu filter button](https://raw.githubusercontent.com/cunctator/traceshark/5fbe59adad7cfa603337ef9ec1999e026851066f/images/cpufilter30x30.png) Show a list of CPUs and it's possible to filter the events view by CPU.\n* ![Event list](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/eventfilter30x30.png) Show a list of the different event types and it's possible to filter the events view by event type.\n* ![Regex dialog](https://raw.githubusercontent.com/cunctator/traceshark/76fe91ec9155f5d67fb4d9663720a05c3a1f6e9b/images/argfilter30x30.png) Show a dialog that lets the user input one or several regular expressions and it is possible to filter the events view with these. The filtering only applies to what is in the Info field. The filtering is separately applied to the different words, which are delimited by spaces. The filtering will by default try with all words but it is also possible to select a certain position. The position may be from the start or from the match of the previous regular expression.\n* ![Time filter](https://raw.githubusercontent.com/cunctator/traceshark/76fe91ec9155f5d67fb4d9663720a05c3a1f6e9b/images/timefilter30x30.png) This will filter the events view so that only events in the interval between the cursors are displayed.\n* ![Reset all filters](https://raw.githubusercontent.com/cunctator/traceshark/76fe91ec9155f5d67fb4d9663720a05c3a1f6e9b/images/resetfilters30x30.png) This button resets all filters.\n* ![Export filtered events](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/exportevents30x30.png) Opens a dialog that allows the filtered events to be saved to a file. The output format is more or less the same as from perf, so that if one has filtered on the `cycles` events, it's possible to generate a CPU Flame Graph with the tools [here](https://github.com/brendangregg/FlameGraph), or [here](https://github.com/cunctator/FlameGraph). A typical way to use this would be something like this:\n  1. Move the blue and red cursors so that they define a time interval that is of interest.\n  2. Click on the ![Time filter](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/timefilter30x30.png) button to limit the events to this interval.\n  3. Click on the ![Event list](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/eventfilter30x30.png) button. Select the `cycles` event and click on the `Create events filter` button.\n  4. Click on the ![task select button](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/taskselector30x30.png) button and select a task or a set of tasks that is of interest. Click on the `Create events filter` button.\n  5. Click on the ![Export filtered events](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/exportevents30x30.png) button and type in the filename `filtered.asc`. Click on the `Save` button.\n  6. Download the flamegraph software by giving one of the following commands in your home directory:\n  ```\n  git clone https://github.com/cunctator/FlameGraph.git\n  ```\n  or\n  ```\n  git clone https://github.com/brendangregg/FlameGraph.git\n  ```\n  7. Create the flamegraph of the filtered events:\n  ```\n  ~/FlameGraph/stackcollapse-perf.pl --kernel  filtered.asc \u003e filtered.folded\n  ~/FlameGraph/flamegraph.pl --hash --color=java filtered.folded \u003e filtered.svg\n  ```\n  8. If all went well, your file `filtered.svg` should now contain an image, that can be displayed by a web browser such as Chromium or Firefox. For an example, check the file doc/filtered.svg in this repository, it can be zoomed, unlike the png representation below:\n  [![filtered.png](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/doc/filtered.png)](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/doc/filtered.png)\n  You can read more about flame graphs [here](http://www.brendangregg.com/flamegraphs.html).\n* ![Export filtered CPU events](https://raw.githubusercontent.com/cunctator/traceshark/c7168ab2ffffd65f3b87ae6b65c2f9c6a7daed6b/images/exportcpuevents30x30.png) This functions exactly as the previously mentioned ![Export filtered events](https://raw.githubusercontent.com/cunctator/traceshark/c7168ab2ffffd65f3b87ae6b65c2f9c6a7daed6b/images/exportevents30x30.png) button, except that it only exports cycles events. The benefit is that the user doesn't need to separately filter on cycles events. The downside is that if the events of interest have a slightly different name, nothing will be exported. This could be the case with certain kernel versions, particularly heavily patched vendor kernels.\n* ![Cursor zoom](https://raw.githubusercontent.com/cunctator/traceshark/c7168ab2ffffd65f3b87ae6b65c2f9c6a7daed6b/images/cursorzoom30x30.png) Pressing this button will zoom the plot to the time interval that is defined by the cursors. This feature may be especially useful when a very large file has been opened and the response to mouse zooming is sluggish.\n* ![Full zoom](https://raw.githubusercontent.com/cunctator/traceshark/d83b961645e038f55b39d78f2cc9768c8b6a0c2c/images/fullzoom30x30.png) Pressing this button will zoom the plot to the full time interval, that is from the beginning to the end of the trace. The height will also be adjusted so that everything is shown vertically too.\n* ![Default zoom](https://raw.githubusercontent.com/cunctator/traceshark/d83b961645e038f55b39d78f2cc9768c8b6a0c2c/images/defaultzoom30x30.png) Pressing this button will zoom the plot to the default zoom. This is the same as the full zoom, except that if there is not enough vertical screen space for displaying the trace without cluttering, then vertically only a part  of the trace will be displayed and a vertical scroll bar will be displayed.\n* ![Toggle vertical zoom](https://raw.githubusercontent.com/cunctator/traceshark/67651b9c424d938a1cef99e60e81e948486439fa/images/verticalzoom30x30.png) Pressing this button will toggle the vertical zooming and scrolling. The effect is the same as toggling the selection of the vertical axis.\n* ![Show scheduling latencies](https://raw.githubusercontent.com/cunctator/traceshark/758009355ebe32897aa5b1854e5033da1dd3d27d/images/latency30x30.png) Pressing this button will show a list of scheduling latencies. If a latency in the list is double clicked, then the task in question will be selected and the cursors will be moved to show the latency. The latencies are sorted so that the biggest latencies are displayed first. A scheduling latency is the delay between a task becoming runnable and being scheduled.\n* ![Show wakeup latencies](https://raw.githubusercontent.com/cunctator/traceshark/758009355ebe32897aa5b1854e5033da1dd3d27d/images/latency-wakeup30x30.png) Pressing this button will show a list of wakeup latencies. It works in the same way as the scheduling latencies button but shows wakeup latencies instead. Wakeup latencies only include the delay between a wakeup event and a task being scheduled. If a task is being scheduled out in a runnable state, then the delay until it being scheduled again is not included. If you want these latencies included, then you should use the previously mentioned ![Show scheduling latencies](https://raw.githubusercontent.com/cunctator/traceshark/758009355ebe32897aa5b1854e5033da1dd3d27d/images/latency30x30.png) button instead.\n* ![Select which types of graphs should be enabled](https://raw.githubusercontent.com/cunctator/traceshark/643bd5cfb6222da00231317750d4b97900fac9fc/images/settings30x30.png) Pressing this button will open a dialog that allows the user to select which types of graphs will be displayed. Here it is possible to disable certain graphs, for example CPU idle graphs that frequently may be of little interest. It is also possible to enable horizontal latency graphs for the per CPU task graphs that are disabled by default, because they will frequently overlap each other. If OpenGL is enabled at compile time, then it is possible to select the desired line width of the scheduling graphs. Otherwise, the line width will always be set to 1. The dialog has an `Apply \u0026 Save` button that allows the user to save the settings to `$HOME/.traceshark`, so that they will be remembered the next time traceshark is started.\n* ![Show global statistics](https://github.com/cunctator/traceshark/raw/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/getstats30x30.png) Pressing this button will show a dialog with global statistics on the left side of the plot. The statistics show how many % of the CPU time each task has consumed as well as the time consumed. The percentages are percentage of a core. This means that the maximum for a normal task is 100% and for the idle task, swapper with pid 0, the maximum is `N * 100`, where N is the number of CPUs. The tasks are sorted so that those tasks that consume more CPU time are shown earlier. The dialog has buttons for adding selected tasks to the legend, to add them as task graphs, to filter the events view on them, or to reset the filtering. There is even a button to close the dialog.\n* ![Show statistics limited by cursors](https://github.com/cunctator/traceshark/raw/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/getstatstimelimit30x30.png) Pressing this button will show a dialog with the same statistics as the previous button but the scope will not be the whole trace but the time between cursors and the statistics will be shown on the right side of the plot. If the cursors are moved while the dialog is shown, then the statistics will be updated accordingly.\n\nThe top widget has some buttons as well:\n\n* ![Move the red cursor](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/movered30x30.png) Move the red cursor to the time specified in the time text box.\n* ![Add the blue cursor](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/moveblue30x30.png) Move the blue cursor to the time specified in the time text box.\n* ![Add to legend](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/addtolegend30x30.png) Adds the currently selected task, from the scheduling graphs, to the legend. A task can be removed from the legend by double clicking on it in the legend.\n* ![Clear legend](https://raw.githubusercontent.com/cunctator/traceshark/b2d0b868ea4947d89240dd627f05bb77bd51ce03/images/clearlegend30x30.png) Removes all tasks from the legend.\n* ![Find Wakeup](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/wakeup30x30.png) This moves the non-active cursor to the immediately preceding scheduling of the currently selected task. The active cursor is moved to the wakeup event. The selected task is unselected and instead the task of the wakeup event is selected. The events view is scrolled to the wakeup event. This makes it convenient to easily check which task is waiting for which. It is a good idea to double click on the info field of the wakeup event, in order to see the backtrace so that one can determine whether the wakeup was caused by an interrupt or not. If all IRQs are traced it may also be possible to form a conclusion by looking at the surrounding IRQ related events. A typical way to use this button would be something like this:\n  1. Choose a task whose wakeup sequence is of interest\n  2. Double click to move the cursor to just after the scheduling of interest\n  3. Make sure that the task is selected.\n  4. Click on the ![Wakeup](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/wakeup30x30.png) button.\n  5. Locate the wakeup event in the events view. It should be selected.\n  6. Double click on the `Info` field to display the backtrace. Alternatively, you can use the ```Event-\u003eShow backtrace``` menu item.\n  7. If the backtrace leads to an interrupt (including software interrupts), then the wakeup source has been found.\n  8. If the `sched_wakeup` event is executed as pid 0, that is no new task has been auto-selected, and/or, the backtrace leads to something like this:\n     ```\n     2863f8 ttwu_do_wakeup\n     286522 ttwu_do_activate\n     2878a7 sched_ttwu_pending\n     29fec6 do_idle\n     2a00ff cpu_startup_entry\n     237418 start_secondary\n     2000d5 [unknown]\n     ```\n     Then it's necessary to find the preceding `sched_waking` event and study its backtrace instead. Click on the ![Find Waking](https://github.com/cunctator/traceshark/raw/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/waking30x30.png) button and go back to VI.\n  9. If none of the above is true, then go back to IV.\n* ![Find Waking](https://github.com/cunctator/traceshark/raw/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/waking30x30.png) This is used to find the `sched_waking` event that is associated with and precedes a particular `sched_wakeup` event. A `sched_wakeup` event must be selected in the events view for this button to be enabled.\n* ![Find Waking Direct](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/wakingdirect30x30.png) This is used to find the `sched_waking` event directly, without first finding the `sched_wakeup` event. It operates in the same way as the ![Find Wakeup](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/wakeup30x30.png) button, based on the currently selected task and the position of the currently active cursor. If you use this button, you should remember that tasks might sometimes wake up without a `sched_waking` event. One example is when new tasks are woken up by the `sched_wakeup_new` event; in that case there is no corresponding `sched_waking` event.\n* ![Find next sched_switch sleep event](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/findsleep30x30.png) This is used to find the next sched_switch event that puts the currently selected task to sleep. It is sometimes desirable to see what kind of code makes a task go to sleep; this is particularly useful together with the feature that the backtrace can be displayed by double clicking on the event's info field in the events view.\n* ![Add unified task graph](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/addtask30x30.png) Adds a unified scheduling graph for the currently selected task.\n* ![Remove unified task graph](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/removetask30x30.png) Removes the currently selected unified graph.\n* ![Remove all unified task graphs](https://raw.githubusercontent.com/cunctator/traceshark/dbf92937590e3987632d60c0ccc4119f7b06284a/images/cleartasksgraphs30x30.png) This button removes all unified graphs that have been added to the plot.\n* ![Filter on the current task](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/filtercurrent30x30.png) This will filter the events view so that only events involving the currently selected task will be displayed.\n* ![Filter on the current task time limited](https://raw.githubusercontent.com/cunctator/traceshark/608fdb55d78e7beebecf3a5e036cace07842f2c6/images/filtercurrentlimited30x30.png) This will do the same as the previous, except that in addition it will exclude those events that are outside the interval defined by the positions of the cursors.\n\n### 1.1.4 The Events view\n\nAt the bottom of the screen is the events view. The events view will be automatically scrolled when a cursor is moved. It is also possible to move the currently active cursor by double clicking on a time in the events view. Another very important feature is that by double clicking on the info field, a dialog will open that displays the backtrace of that particular event. In general, it is  possible to trigger the actions in the ```Event``` menu by double clicking on the corresponding column of the currently selected event.\n\n# 2. Building traceshark\n\n## 2.1 How to set up your build environment\n\nIn order to build traceshark, you will need three things:\n* A C++ compiler\n* make\n* The development packages for Qt\n\nOn Ubuntu 16.04, Ubuntu 18.04, Ubuntu 20.04, Debian 9, and Debian 10, you can install these like this:\n\n```\nsudo apt-get install qt5-default g++ make\n```\n\nOn Ubuntu 22.04 and Debian 11, you can install these like this:\n\n```\nsudo apt install qtbase5-dev g++ make\n```\n\nOn Fedora (tested with Fedora 32), you can do the following:\n\n```\nsudo dnf install qt5-qtbase-devel g++ make\n```\n\nIt is not recommended but if you plan to configure your build to use the QCustomPlot library on your distro instead of the patched built-in version, then you will need to install the relevant development package. On Ubuntu 20.04 and Debian 10:\n\n```\nsudo apt-get install libqcustomplot-dev\n```\n\nThe QCustomPlot library on Debian 9 and Ubuntu 18.04 is too old for traceshark.\n\nOn Fedora 32:\n```\nsudo dnf install qcustomplot-qt5-devel\n```\n\nOn macOS, you will need to:\n* Install Xcode and Homebrew as described at [brew.sh](https://brew.sh)\n* Install Qt version 6.x:\n```\nbrew install qt\n```\n\nNB: It seems like on macOS you need to make sure that the currently used screen resolution matches the screen's native resolution. Otherwise, the graphs will be rendered in a very strange way; at least this has been seen on a Mac Studio with Ventura.\n\n\n## 2.2 How to compile and install\n\nThe program can be compiled and installed by doing something like this:\n\n```\nqmake (on some distros you should use qmake6, or qmake-qt5 instead of qmake)\nmake -j5\nsudo make install\n```\n\nOn macOS, the ```sudo make install``` doesn't work. You can find the executable in ```traceshark.app/Contents/MacOS/traceshark```. Running traceshark on macOS is currently in a quite experimental state.\n\n## 2.3 How to configure your build\n\nIt is not necessary but you can tweak your build by editing traceshark.pro. One of the most important options is that you can disable OpenGL support. If and only if OpenGL support is enabled, then it is possible for the user to select the line width of the scheduling graphs, otherwise the line width will always be set to 1. OpenGL is enabled at compile time by default. If it has been enabled at compile time, then it will be enabled by default when running the application but only if the screen is deemed to be a high resolution screen.  The user can enable or disable OpenGL at runtime by opening the dialog with the ![Select which types of graphs should be enabled](https://raw.githubusercontent.com/cunctator/traceshark/643bd5cfb6222da00231317750d4b97900fac9fc/images/settings30x30.png) button. If you run into rendering problems, including problems with very slow rendering, then disabling OpenGL might be worth trying. OpenGL can be disabled at compile time by uncommenting the following line in traceshark.pro:\n\n```\n# DISABLE_OPENGL = yes\n```\n\nYou can uncomment the following if you want the try to detect and optimize for your build machine:\n\n```\n# MARCH_FLAG = -march=native\n# MTUNE_FLAG = -mtune=native\n```\n\n, or you can uncomment some specific flags to build for a certain machine, e.g.\nuncomment this to build for Broadwell:\n\n```\n# MARCH_FLAG = -march=broadwell\n# MTUNE_FLAG = -mtune=broadwell\n```\n\nThe recommended default compiler is g++ but you can compile with clang, or another version of g++, if you like, by uncommenting and possibly editing one of the following in traceshark.pro:\n\n```\n# USE_ALTERNATIVE_COMPILER = clang++-14\n# USE_ALTERNATIVE_COMPILER = g++-12\n```\n\nIf you want to build a debug build, uncomment one of the following two lines:\n\n```\n# Uncomment this for debug build:\n# USE_DEBUG_FLAG = -g\n\n# Uncomment this for debug symbols and optmized for debug:\n# USE_DEBUG_FLAG = -g -Og\n```\n\nIf you want to enable the Qt debug features, then you need to uncomment this line:\n\n```\n# Uncomment this for debug build. This affects Qt.\n# QT_DEBUG_BUILD = yes\n```\n\nThis is not recommended because it will very likely result in worse performance but if you absolutely want to use the QCustomPlot library on your system, then you need to uncomment the following line:\n\n```\n# USE_SYSTEM_QCUSTOMPLOT = yes\n```\n\nPlease note that the software will compile for Qt 4 but that it has not been as\ntested with Qt 4. For that reason you might want to build with Qt 5, unless\nyou happen to prefer Qt 4.\n\n# 3. Obtaining a trace\n\nThere are two ways to capture a trace: Ftrace and perf. Perf is the recommended method because it is able to generate backtraces that are understood by traceshark. However, Ftrace has the benefit that it almost always works right out of the box on many distros. Nowadays, perf usually works right out of the box too but it was not always the case in the past.\n\nFor both Ftrace and perf it is very desirable to avoid lost events because traceshark cannot visualize correctly with lost events, nor can it find a wakeup event that has been lost.\n\nWhen tracing, particularly when capturing many kilobytes of the stack with each event, the impact of the filesystem may easily become non-negligible. In particular, if when tracing some hot event that may be triggered by the file system, then if the storing of one event on average generates one or more additional events then there will of course be an explosion of events, and the tracing will end in a non-desirable way in one way or another.\n\nIf the system has enough RAM, one thing that can be done to ameliorate the situation is to store the trace to tmpfs. You can create a tmpfs by doing something like this:\n\n```\n sudo mkdir -p /mnt/tmp\n sudo mount -t tmpfs -o size=8192M tmpfs /mnt/tmp\n```\n\n...or you can add a line to your /etc/fstab:\n\n```\ntmpfs      /mnt/tmp        tmpfs   size=8192M      0        2\n```\n\nThe above is only provided as an example; you will probably need to adjust the size and path according to your needs. The benefit with tmpfs is that it is very fast and generally doesn't generate a lot of events. The downside is of course that it will easily consume a lot of RAM.\n\n\n## 3.1 Sample traces\n\nIf you are not anxious to trace anything in particular but only want to play around with traceshark, then you can find sample traces [here](https://github.com/cunctator/traceshark-resources), or just clone the repo with the samples:\n```\ngit clone https://github.com/cunctator/traceshark-resources.git\n```\n\n## 3.2 Capturing a trace with Ftrace\n\nYou can get an Ftrace trace to view by doing the following:\n\n```\ntrace-cmd record -e cpu_frequency -e cpu_idle -e sched_kthread_stop -e sched_kthread_stop_ret -e sched_migrate_task -e sched_move_numa -e sched_pi_setprio -e sched_process_exec -e sched_process_exit -e sched_process_fork -e sched_process_free -e sched_process_wait -e sched_stick_numa -e sched_swap_numa -e sched_switch -e sched_wait_task -e sched_wake_idle_without_ipi -e sched_wakeup -e sched_wakeup_new -e sched_waking\n```\n\nIf you get problem with lost events, then you may want to try the `-r` and `-b` options. For example:\n```\ntrace-cmd record -e cpu_frequency -e cpu_idle -e sched_kthread_stop -e sched_kthread_stop_ret -e sched_migrate_task -e sched_move_numa -e sched_pi_setprio -e sched_process_exec -e sched_process_exit -e sched_process_fork -e sched_process_free -e sched_process_wait -e sched_stick_numa -e sched_swap_numa -e sched_switch -e sched_wait_task -e sched_wake_idle_without_ipi -e sched_wakeup -e sched_wakeup_new -e sched_waking -b 32768 -r 99\n```\n\nThe above will use kernel buffers that are a whopping 32 MB per cpu and run the capture threads with a real time priority of 99. You may want to adjust these values to suit your system.\n\nYou may also want to add additional events to the above command that are of interest to your software. You can get a list of available events by running the following command as root:\n```\ntrace-cmd list\n```\nIn order to open the trace with traceshark, it must first be converted to ASCII:\n```\ntrace-cmd report trace.dat \u003e file_to_open_with_traceshark.asc\n```\n\n## 3.3 Capturing a trace with perf\n\nWith perf you may also want to consider additional events. A list of all events can be obtained by running the following command as root:\n```\nperf list\n```\n\nA perf trace can be obtained by doing something like this:\n\n```\nperf record -e power:cpu_frequency -e power:cpu_idle -e sched:sched_kthread_stop -e sched:sched_kthread_stop_ret -e sched:sched_migrate_task -e sched:sched_move_numa -e sched:sched_pi_setprio -e sched:sched_process_exec -e sched:sched_process_exit -e sched:sched_process_fork -e sched:sched_process_free -e sched:sched_process_wait -e sched:sched_stick_numa -e sched:sched_swap_numa -e sched:sched_switch -e sched:sched_wait_task -e sched:sched_wake_idle_without_ipi -e sched:sched_wakeup -e sched:sched_wakeup_new -e sched:sched_waking -e cycles -a --call-graph=dwarf,20480 -m 128M\n```\n\nThe `--call-graph=dwarf,20480` option is needed, if you want to get stack traces for your events. You might need to adjust the size 20480, the maximum is 65528. The benefit with larger sizes is that you can capture bigger stacks, the downside is that the traces will be larger, tracing will have more overhead, and the probability that perf will lose some events is higher. I believe that you can use the `-g` option instead if your software is compiled with frame pointers.\n\nThe option `-m 128M` is needed to increase the memory used by perf for buffering in order to avoid lost events, especially when using the `--call-graph` option. This is necessary because traceshark doesn't cope well with lost events.\n\nThe stack trace of an event will be displayed by traceshark if you double click on the event's info field in the events view.\n\nTyping the above commands every time may be error prone and tedious, for this reason, there is the [perf-record.sh](https://raw.githubusercontent.com/cunctator/traceshark/de71cc2f7982f3fe11f20da8c44c0ecaae16453f/scripts/perf-record.sh) script in the [scripts](https://github.com/cunctator/traceshark/tree/de71cc2f7982f3fe11f20da8c44c0ecaae16453f/scripts) directory.\n\nIn order to get an ASCII representation that can be parsed by traceshark:\n```\nperf script -f \u003e file_to_open_with_traceshark.asc\n```\n\nNB: Your perf program need to be recent enough to work with traceshark, it may\nmean that you need to compile perf from the kernel sources of a recent kernel,\nrather than the perf that is supplied with your Linux distro.\n\nIt seems that some distros provide a perf program that is older than the kernel\nin the distro, or somehow a modified perf. This results in a trace being\ncaptured with some events in a different format than expected by traceshark, so\nthat for example scheduling is not correctly shown.\n\nOne approach if the perf provided by your distro doesn't work with traceshark,\nis to check the kernel version with \"uname -r\", then go to kernel.org and\ndownload the corresponding mainline kernel and compile perf from the tools/perf\ndirectory in that kernel source tree. If it still doesn't work and you have a\nvery old kernel, it might work to use perf from a newer kernel, although you\nwould probably be better off if you upgraded both the kernel and perf but\nupgrading the kernel isn't always possible.\n\nI am not exactly sure how recent perf/kernel is necessary but basically I\nbelieve that late 3.X and all 4.X and 5.x kernels to date should work as long\nas the perf program has not been patched.\n\nIf you use the '-g' flag, you might also want to compile your own perf because\nin some distros perf is compiled without support for backtraces and it starts\nworking when you compile perf with those bits enabled. Fortunately, nowadays\nit's common that the perf utility shipped with the distro support backtraces.\n\nWhen you compile perf, you get a report like this:\n\n```\nAuto-detecting system features:\n...                         dwarf: [ on  ]\n...            dwarf_getlocations: [ on  ]\n...                         glibc: [ on  ]\n...                          gtk2: [ OFF ]\n...                      libaudit: [ on  ]\n...                        libbfd: [ on  ]\n...                        libelf: [ on  ]\n...                       libnuma: [ on  ]\n...        numa_num_possible_cpus: [ on  ]\n...                       libperl: [ on  ]\n...                     libpython: [ on  ]\n...                      libslang: [ on  ]\n...                     libcrypto: [ on  ]\n...                     libunwind: [ OFF ]\n...            libdw-dwarf-unwind: [ on  ]\n...                          zlib: [ on  ]\n...                          lzma: [ on  ]\n...                     get_cpuid: [ on  ]\n...                           bpf: [ on  ]\n```\n\nI believe that for backtraces to work, it's desirable that as many as possible\nof those dwarf, bfd, elf, and unwind related options are enabled. They tend to\nget automatically enabled if you have the necessary development packages\ninstalled on your machine.\n\nOn Ubuntu Bionic and Debian Buster/Bullseye the following might work:\n```\nsudo apt-get install binutils-dev binutils-multiarch-dev bison elfutils flex libaudit-dev libbfd-dev libdw-dev libelf-dev libelf1 libgtk2.0-dev libiberty-dev liblzma-dev libnuma-dev libperl-dev libslang2-dev libslang2 'libunwind*' libunwind8 python-dev libzstd-dev libcap-dev\n```\n\nOn Ubuntu Jammy, the following might work:\n\n```\nsudo apt-get install binutils-dev binutils-multiarch-dev bison elfutils flex libaudit-dev libbfd-dev libdw-dev libelf-dev libelf1 libgtk2.0-dev libiberty-dev liblzma-dev libnuma-dev libperl-dev libslang2-dev libslang2 libunwind-dev libunwind8 python3-dev libzstd-dev libcap-dev libtraceevent-dev libssl-dev libbabeltrace-dev  python3-setuptools libpfm4-dev systemtap-sdt-dev java-common openjdk-8-jdk\n```\n\nThe two examples above may need to be adjusted based on what kernel version you have.\n","funding_links":[],"categories":["C++","\u003ca name=\"cpp\"\u003e\u003c/a\u003eC++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcunctator%2Ftraceshark","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcunctator%2Ftraceshark","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcunctator%2Ftraceshark/lists"}