1Tracing Skia Execution 2====================== 3 4Introduction 5------------ 6 7Skia is instrumented to provide execution traces in several ways. Within Chrome, Skia is traced 8with the standard [tracing interface](chrome://tracing), along with the rest of Chromium. In 9the Android framework, Skia's tracing is integrated into 10[atrace](https://source.android.com/devices/tech/debug/ftrace). 11 12For standalone builds, Skia's tools (DM, nanobench, and Viewer) are capable of tracing execution 13in three ways, controlled by the `--trace` command line argument. 14 15Standalone Tracing 16------------------ 17 18Most arguments to `--trace` will be interpreted as a filename (the two exceptions are described 19below), 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 27This creates a file `gl_bleed_gms.json` in the current directory. There are limitations in Chrome's 28tracing tool that prevent loading a file larger than 256 MB. To stay under that limit (and avoid 29clutter and slowdown in the interface), it's best to run a small number of tests/benchmarks when 30tracing. 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 36tracing tools. Tip: press '?' for a help screen explaining the available keyboard and mouse 37controls. 38 39 40 41Android ATrace 42-------------- 43 44Running any tool with `--trace atrace` on an Android device will cause the application to forward 45tracing information to [atrace](https://source.android.com/devices/tech/debug/ftrace). On other 46platforms, this has no effect. 47 48If you run `systrace` from the host command line, you will need to supply `-a <app_name>`, 49and the `<app_name>` argument will need to exactly match the command line used on the target 50device. For example, if you use `adb shell "cd /data/local/tmp; ./nanobench --trace atrace ..."` 51you must pass `-a ./nanobench` or systrace will ignore events from the application. 52 53Console Logging 54--------------- 55 56For 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 85Adding More Trace Events 86------------------------ 87 88Adding more trace events involves using a set of `TRACE_` macros. The simplest example, to record 89the time spent in a function or other scope, is: 90 91~~~ 92#include <SkTraceEvent.h> 93... 94void 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 107For more examples, including other kinds of trace events and attaching parameters to events, see 108the comments in 109[SkTraceEventCommon.h](https://cs.chromium.org/chromium/src/third_party/skia/src/core/SkTraceEventCommon.h).
