1 Tracing Skia Execution 2 ====================== 3 4 Introduction 5 ------------ 6 7 Skia is instrumented to provide execution traces in several ways. Within Chrome, Skia is traced 8 with the standard [tracing interface](chrome://tracing), along with the rest of Chromium. In 9 the Android framework, Skia's tracing is integrated into 10 [atrace](https://source.android.com/devices/tech/debug/ftrace). 11 12 For standalone builds, Skia's tools (DM, nanobench, and Viewer) are capable of tracing execution 13 in three ways, controlled by the `--trace` command line argument. 14 15 Standalone Tracing 16 ------------------ 17 18 Most arguments to `--trace` will be interpreted as a filename (the two exceptions are described 19 below), and trace events will be written to that file in JSON format, suitable for viewing with 20 [chrome://tracing](chrome://tracing). 21 22 <!--?prettify lang=sh?--> 23 24 # Run DM on several GMs to get tracing data 25 out/Release/dm --config gl --match bleed --trace gl_bleed_gms.json 26 27 This creates a file `gl_bleed_gms.json` in the current directory. There are limitations in Chrome's 28 tracing tool that prevent loading a file larger than 256 MB. To stay under that limit (and avoid 29 clutter and slowdown in the interface), it's best to run a small number of tests/benchmarks when 30 tracing. Once you have generated a file in this way, go to 31 [chrome://tracing](chrome://tracing), click Load: 32 33  34 35 ... then select the JSON file. The data will be loaded and can be navigated/inspected using the 36 tracing tools. Tip: press '?' for a help screen explaining the available keyboard and mouse 37 controls. 38 39  40 41 Android ATrace 42 -------------- 43 44 Running any tool with `--trace atrace` on an Android device will cause the application to forward 45 tracing information to [atrace](https://source.android.com/devices/tech/debug/ftrace). On other 46 platforms, this has no effect. 47 48 If you run `systrace` from the host command line, you will need to supply `-a <app_name>`, 49 and the `<app_name>` argument will need to exactly match the command line used on the target 50 device. For example, if you use `adb shell "cd /data/local/tmp; ./nanobench --trace atrace ..."` 51 you must pass `-a ./nanobench` or systrace will ignore events from the application. 52 53 Console Logging 54 --------------- 55 56 For simple situations, all tracing events can be directed to the console with `--trace debugf`: 57 58 <!--?prettify lang=sh?--> 59 60 # Run DM on a single GM with SkDebugf tracing 61 out/Release/dm --config gl --match ^gamma$ --trace debugf 62 63 ~~~ 64 [ 0] <skia.gpu> GrDrawingManager::internalFlush id=1 #0 { 65 [ 0] } GrDrawingManager::internalFlush 66 [ 0] <skia.gpu> GrGpu::createTexture id=1 #1 { 67 [ 0] } GrGpu::createTexture 68 [ 0] <skia.gpu> GrRenderTargetContext::discard id=1 #2 { 69 [ 0] } GrRenderTargetContext::discard 70 [ 0] <skia.gpu> SkGpuDevice::clearAll id=1 #3 { 71 [ 1] <skia.gpu> GrRenderTargetContext::clear id=1 #4 { 72 [ 1] } GrRenderTargetContext::clear 73 [ 0] } SkGpuDevice::clearAll 74 [ 0] <skia> SkCanvas::drawRect() #5 { 75 [ 1] <skia.gpu> SkGpuDevice::drawRect id=1 #6 { 76 [ 2] <skia.gpu> GrRenderTargetContext::drawRect id=1 #7 { 77 [ 3] <skia.gpu> GrRenderTargetContext::addDrawOp id=1 #8 { 78 [ 3] } GrRenderTargetContext::addDrawOp 79 [ 2] } GrRenderTargetContext::drawRect 80 [ 1] } SkGpuDevice::drawRect 81 [ 0] } SkCanvas::drawRect() 82 ... 83 ~~~ 84 85 Adding More Trace Events 86 ------------------------ 87 88 Adding more trace events involves using a set of `TRACE_` macros. The simplest example, to record 89 the time spent in a function or other scope, is: 90 91 ~~~ 92 #include <SkTraceEvent.h> 93 ... 94 void doSomething() { 95 // Add an event for the duration of the current function (or other scope) 96 // "skia" is a category name, for filtering events while recording 97 // TRACE_FUNC is the event name, and expands to the name of the current function 98 TRACE_EVENT0("skia", TRACE_FUNC); 99 100 if (doExtraWork) { 101 TRACE_EVENT0("skia", "ExtraWorkBeingDone"); 102 ... 103 } 104 } 105 ~~~ 106 107 For more examples, including other kinds of trace events and attaching parameters to events, see 108 the comments in 109 [SkTraceEventCommon.h](https://cs.chromium.org/chromium/src/third_party/skia/src/core/SkTraceEventCommon.h).
