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
15Android ATrace
16--------------
17
18Running any tool with `--trace atrace` on an Android device will cause the application to forward
19tracing information to [atrace](https://source.android.com/devices/tech/debug/ftrace). On other
20platforms, this has no effect.
21
22If you run `systrace` from the host command line, you will need to supply `-a <app_name>`,
23and the `<app_name>` argument will need to exactly match the command line used on the target
24device. For example, if you use `adb shell "cd /data/local/tmp; ./nanobench --trace atrace ..."`
25you must pass `-a ./nanobench` or systrace will ignore events from the application.
26
27Console Logging
28---------------
29
30For simple situations, all tracing events can be directed to the console with `--trace debugf`:
31
32<!--?prettify lang=sh?-->
33
34    # Run DM on a single GM with SkDebugf tracing
35    out/Release/dm --config gl --match ^gamma$ --trace debugf
36
37~~~
38[ 0] <skia.gpu> GrDrawingManager::internalFlush id=1 #0 {
39[ 0] } GrDrawingManager::internalFlush
40[ 0] <skia.gpu> GrGpu::createTexture id=1 #1 {
41[ 0] } GrGpu::createTexture
42[ 0] <skia.gpu> GrRenderTargetContext::discard id=1 #2 {
43[ 0] } GrRenderTargetContext::discard
44[ 0] <skia.gpu> SkGpuDevice::clearAll id=1 #3 {
45[ 1]  <skia.gpu> GrRenderTargetContext::clear id=1 #4 {
46[ 1]  } GrRenderTargetContext::clear
47[ 0] } SkGpuDevice::clearAll
48[ 0] <skia> SkCanvas::drawRect() #5 {
49[ 1]  <skia.gpu> SkGpuDevice::drawRect id=1 #6 {
50[ 2]   <skia.gpu> GrRenderTargetContext::drawRect id=1 #7 {
51[ 3]    <skia.gpu> GrRenderTargetContext::addDrawOp id=1 #8 {
52[ 3]    } GrRenderTargetContext::addDrawOp
53[ 2]   } GrRenderTargetContext::drawRect
54[ 1]  } SkGpuDevice::drawRect
55[ 0] } SkCanvas::drawRect()
56...
57~~~
58
59Chrome Tracing
60--------------
61
62Any other argument to `--trace` will be interpreted as a filename, and trace events will be written
63to that file in JSON format, suitable for viewing with [chrome://tracing](chrome://tracing).
64
65<!--?prettify lang=sh?-->
66
67    # Run DM on several GMs to get tracing data
68    out/Release/dm --config gl --match bleed --trace gl_bleed_gms.json
69
70This creates a file `gl_bleed_gms.json` in the current directory. Go to
71[chrome://tracing](chrome://tracing), click Load:
72
73![Load Button](tracing_load.png)
74
75... then select the JSON file. The data will be loaded and can be navigated/inspected using the
76tracing tools. Tip: press '?' for a help screen explaining the available keyboard and mouse
77controls.
78
79![Tracing interface](tracing.png)
80