Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2012 The Android Open Source Project |
| 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | package android.os; |
| 18 | |
| 19 | /** |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 20 | * Writes trace events to the system trace buffer. These trace events can be |
| 21 | * collected and visualized using the Systrace tool. |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 22 | * |
Scott Main | c468240 | 2013-06-13 12:38:55 -0700 | [diff] [blame] | 23 | * <p>This tracing mechanism is independent of the method tracing mechanism |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 24 | * offered by {@link Debug#startMethodTracing}. In particular, it enables |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 25 | * tracing of events that occur across multiple processes. |
Scott Main | c468240 | 2013-06-13 12:38:55 -0700 | [diff] [blame] | 26 | * <p>For information about using the Systrace tool, read <a |
| 27 | * href="{@docRoot}tools/debugging/systrace.html">Analyzing Display and Performance |
| 28 | * with Systrace</a>. |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 29 | */ |
| 30 | public final class Trace { |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 31 | /* |
| 32 | * Writes trace events to the kernel trace buffer. These trace events can be |
| 33 | * collected using the "atrace" program for offline analysis. |
| 34 | */ |
| 35 | |
Andy McFadden | d11ca4d | 2012-10-22 16:16:06 -0700 | [diff] [blame] | 36 | private static final String TAG = "Trace"; |
| 37 | |
Alex Ray | 8a6787b | 2012-11-14 18:08:49 -0800 | [diff] [blame] | 38 | // These tags must be kept in sync with system/core/include/cutils/trace.h. |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 39 | /** @hide */ |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 40 | public static final long TRACE_TAG_NEVER = 0; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 41 | /** @hide */ |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 42 | public static final long TRACE_TAG_ALWAYS = 1L << 0; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 43 | /** @hide */ |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 44 | public static final long TRACE_TAG_GRAPHICS = 1L << 1; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 45 | /** @hide */ |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 46 | public static final long TRACE_TAG_INPUT = 1L << 2; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 47 | /** @hide */ |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 48 | public static final long TRACE_TAG_VIEW = 1L << 3; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 49 | /** @hide */ |
Chris Craik | 192a65e | 2012-04-16 16:08:40 -0700 | [diff] [blame] | 50 | public static final long TRACE_TAG_WEBVIEW = 1L << 4; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 51 | /** @hide */ |
Dianne Hackborn | 1ded0b1 | 2012-04-26 14:14:50 -0700 | [diff] [blame] | 52 | public static final long TRACE_TAG_WINDOW_MANAGER = 1L << 5; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 53 | /** @hide */ |
Dianne Hackborn | 1ded0b1 | 2012-04-26 14:14:50 -0700 | [diff] [blame] | 54 | public static final long TRACE_TAG_ACTIVITY_MANAGER = 1L << 6; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 55 | /** @hide */ |
Andy Stadler | 09b45a3 | 2012-05-03 15:00:49 -0700 | [diff] [blame] | 56 | public static final long TRACE_TAG_SYNC_MANAGER = 1L << 7; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 57 | /** @hide */ |
Glenn Kasten | ed853fc | 2012-05-07 11:05:55 -0700 | [diff] [blame] | 58 | public static final long TRACE_TAG_AUDIO = 1L << 8; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 59 | /** @hide */ |
Jamie Gennis | 24dae6c | 2012-05-11 04:43:35 -0700 | [diff] [blame] | 60 | public static final long TRACE_TAG_VIDEO = 1L << 9; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 61 | /** @hide */ |
Eino-Ville Talvala | 9c0d9cf | 2012-05-31 15:49:31 -0700 | [diff] [blame] | 62 | public static final long TRACE_TAG_CAMERA = 1L << 10; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 63 | /** @hide */ |
Alex Ray | 8a6787b | 2012-11-14 18:08:49 -0800 | [diff] [blame] | 64 | public static final long TRACE_TAG_HAL = 1L << 11; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 65 | /** @hide */ |
| 66 | public static final long TRACE_TAG_APP = 1L << 12; |
Dianne Hackborn | f7be480 | 2013-04-12 14:52:58 -0700 | [diff] [blame] | 67 | /** @hide */ |
| 68 | public static final long TRACE_TAG_RESOURCES = 1L << 13; |
Jamie Gennis | 0cc84ce | 2013-05-07 15:22:31 -0700 | [diff] [blame] | 69 | /** @hide */ |
| 70 | public static final long TRACE_TAG_DALVIK = 1L << 14; |
Tim Murray | 6d7a53c | 2013-05-23 16:59:23 -0700 | [diff] [blame] | 71 | /** @hide */ |
| 72 | public static final long TRACE_TAG_RS = 1L << 15; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 73 | |
Andy McFadden | 325be8a | 2012-10-29 16:42:41 -0700 | [diff] [blame] | 74 | private static final long TRACE_TAG_NOT_READY = 1L << 63; |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 75 | private static final int MAX_SECTION_NAME_LEN = 127; |
Dianne Hackborn | 83e6eb1 | 2012-05-08 14:53:24 -0700 | [diff] [blame] | 76 | |
Andy McFadden | d11ca4d | 2012-10-22 16:16:06 -0700 | [diff] [blame] | 77 | // Must be volatile to avoid word tearing. |
Andy McFadden | 325be8a | 2012-10-29 16:42:41 -0700 | [diff] [blame] | 78 | private static volatile long sEnabledTags = TRACE_TAG_NOT_READY; |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 79 | |
| 80 | private static native long nativeGetEnabledTags(); |
| 81 | private static native void nativeTraceCounter(long tag, String name, int value); |
| 82 | private static native void nativeTraceBegin(long tag, String name); |
| 83 | private static native void nativeTraceEnd(long tag); |
Romain Guy | 9425f92 | 2013-04-10 16:35:48 -0700 | [diff] [blame] | 84 | private static native void nativeAsyncTraceBegin(long tag, String name, int cookie); |
| 85 | private static native void nativeAsyncTraceEnd(long tag, String name, int cookie); |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 86 | private static native void nativeSetAppTracingAllowed(boolean allowed); |
Jamie Gennis | 6ad0452 | 2013-04-15 18:53:24 -0700 | [diff] [blame] | 87 | private static native void nativeSetTracingEnabled(boolean allowed); |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 88 | |
Dianne Hackborn | a53de06 | 2012-05-08 18:53:51 -0700 | [diff] [blame] | 89 | static { |
Andy McFadden | d11ca4d | 2012-10-22 16:16:06 -0700 | [diff] [blame] | 90 | // We configure two separate change callbacks, one in Trace.cpp and one here. The |
| 91 | // native callback reads the tags from the system property, and this callback |
| 92 | // reads the value that the native code retrieved. It's essential that the native |
| 93 | // callback executes first. |
| 94 | // |
| 95 | // The system provides ordering through a priority level. Callbacks made through |
| 96 | // SystemProperties.addChangeCallback currently have a negative priority, while |
| 97 | // our native code is using a priority of zero. |
Dianne Hackborn | a53de06 | 2012-05-08 18:53:51 -0700 | [diff] [blame] | 98 | SystemProperties.addChangeCallback(new Runnable() { |
| 99 | @Override public void run() { |
Andy McFadden | d11ca4d | 2012-10-22 16:16:06 -0700 | [diff] [blame] | 100 | cacheEnabledTags(); |
Dianne Hackborn | a53de06 | 2012-05-08 18:53:51 -0700 | [diff] [blame] | 101 | } |
| 102 | }); |
| 103 | } |
| 104 | |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 105 | private Trace() { |
| 106 | } |
| 107 | |
| 108 | /** |
Andy McFadden | d11ca4d | 2012-10-22 16:16:06 -0700 | [diff] [blame] | 109 | * Caches a copy of the enabled-tag bits. The "master" copy is held by the native code, |
| 110 | * and comes from the PROPERTY_TRACE_TAG_ENABLEFLAGS property. |
| 111 | * <p> |
| 112 | * If the native code hasn't yet read the property, we will cause it to do one-time |
| 113 | * initialization. We don't want to do this during class init, because this class is |
| 114 | * preloaded, so all apps would be stuck with whatever the zygote saw. (The zygote |
| 115 | * doesn't see the system-property update broadcasts.) |
| 116 | * <p> |
| 117 | * We want to defer initialization until the first use by an app, post-zygote. |
| 118 | * <p> |
| 119 | * We're okay if multiple threads call here simultaneously -- the native state is |
| 120 | * synchronized, and sEnabledTags is volatile (prevents word tearing). |
| 121 | */ |
| 122 | private static long cacheEnabledTags() { |
| 123 | long tags = nativeGetEnabledTags(); |
Andy McFadden | d11ca4d | 2012-10-22 16:16:06 -0700 | [diff] [blame] | 124 | sEnabledTags = tags; |
| 125 | return tags; |
| 126 | } |
| 127 | |
| 128 | /** |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 129 | * Returns true if a trace tag is enabled. |
| 130 | * |
| 131 | * @param traceTag The trace tag to check. |
| 132 | * @return True if the trace tag is valid. |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 133 | * |
| 134 | * @hide |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 135 | */ |
| 136 | public static boolean isTagEnabled(long traceTag) { |
Andy McFadden | d11ca4d | 2012-10-22 16:16:06 -0700 | [diff] [blame] | 137 | long tags = sEnabledTags; |
Andy McFadden | 325be8a | 2012-10-29 16:42:41 -0700 | [diff] [blame] | 138 | if (tags == TRACE_TAG_NOT_READY) { |
Andy McFadden | d11ca4d | 2012-10-22 16:16:06 -0700 | [diff] [blame] | 139 | tags = cacheEnabledTags(); |
| 140 | } |
| 141 | return (tags & traceTag) != 0; |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 142 | } |
| 143 | |
| 144 | /** |
| 145 | * Writes trace message to indicate the value of a given counter. |
| 146 | * |
| 147 | * @param traceTag The trace tag. |
| 148 | * @param counterName The counter name to appear in the trace. |
| 149 | * @param counterValue The counter value. |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 150 | * |
| 151 | * @hide |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 152 | */ |
| 153 | public static void traceCounter(long traceTag, String counterName, int counterValue) { |
Andy McFadden | d11ca4d | 2012-10-22 16:16:06 -0700 | [diff] [blame] | 154 | if (isTagEnabled(traceTag)) { |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 155 | nativeTraceCounter(traceTag, counterName, counterValue); |
| 156 | } |
| 157 | } |
| 158 | |
| 159 | /** |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 160 | * Set whether application tracing is allowed for this process. This is intended to be set |
| 161 | * once at application start-up time based on whether the application is debuggable. |
| 162 | * |
| 163 | * @hide |
| 164 | */ |
| 165 | public static void setAppTracingAllowed(boolean allowed) { |
| 166 | nativeSetAppTracingAllowed(allowed); |
| 167 | |
| 168 | // Setting whether app tracing is allowed may change the tags, so we update the cached |
| 169 | // tags here. |
| 170 | cacheEnabledTags(); |
| 171 | } |
| 172 | |
| 173 | /** |
Jamie Gennis | 6ad0452 | 2013-04-15 18:53:24 -0700 | [diff] [blame] | 174 | * Set whether tracing is enabled in this process. Tracing is disabled shortly after Zygote |
| 175 | * initializes and re-enabled after processes fork from Zygote. This is done because Zygote |
| 176 | * has no way to be notified about changes to the tracing tags, and if Zygote ever reads and |
| 177 | * caches the tracing tags, forked processes will inherit those stale tags. |
| 178 | * |
| 179 | * @hide |
| 180 | */ |
| 181 | public static void setTracingEnabled(boolean enabled) { |
| 182 | nativeSetTracingEnabled(enabled); |
| 183 | |
| 184 | // Setting whether tracing is enabled may change the tags, so we update the cached tags |
| 185 | // here. |
| 186 | cacheEnabledTags(); |
| 187 | } |
| 188 | |
| 189 | /** |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 190 | * Writes a trace message to indicate that a given section of code has |
| 191 | * begun. Must be followed by a call to {@link #traceEnd} using the same |
| 192 | * tag. |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 193 | * |
| 194 | * @param traceTag The trace tag. |
| 195 | * @param methodName The method name to appear in the trace. |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 196 | * |
| 197 | * @hide |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 198 | */ |
| 199 | public static void traceBegin(long traceTag, String methodName) { |
Andy McFadden | d11ca4d | 2012-10-22 16:16:06 -0700 | [diff] [blame] | 200 | if (isTagEnabled(traceTag)) { |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 201 | nativeTraceBegin(traceTag, methodName); |
| 202 | } |
| 203 | } |
| 204 | |
| 205 | /** |
| 206 | * Writes a trace message to indicate that the current method has ended. |
| 207 | * Must be called exactly once for each call to {@link #traceBegin} using the same tag. |
| 208 | * |
| 209 | * @param traceTag The trace tag. |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 210 | * |
| 211 | * @hide |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 212 | */ |
| 213 | public static void traceEnd(long traceTag) { |
Andy McFadden | d11ca4d | 2012-10-22 16:16:06 -0700 | [diff] [blame] | 214 | if (isTagEnabled(traceTag)) { |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 215 | nativeTraceEnd(traceTag); |
| 216 | } |
| 217 | } |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 218 | |
| 219 | /** |
Romain Guy | 9425f92 | 2013-04-10 16:35:48 -0700 | [diff] [blame] | 220 | * Writes a trace message to indicate that a given section of code has |
| 221 | * begun. Must be followed by a call to {@link #asyncTraceEnd} using the same |
| 222 | * tag. Unlike {@link #traceBegin(long, String)} and {@link #traceEnd(long)}, |
| 223 | * asynchronous events do not need to be nested. The name and cookie used to |
| 224 | * begin an event must be used to end it. |
| 225 | * |
| 226 | * @param traceTag The trace tag. |
| 227 | * @param methodName The method name to appear in the trace. |
| 228 | * @param cookie Unique identifier for distinguishing simultaneous events |
| 229 | * |
| 230 | * @hide |
| 231 | */ |
| 232 | public static void asyncTraceBegin(long traceTag, String methodName, int cookie) { |
| 233 | if (isTagEnabled(traceTag)) { |
| 234 | nativeAsyncTraceBegin(traceTag, methodName, cookie); |
| 235 | } |
| 236 | } |
| 237 | |
| 238 | /** |
| 239 | * Writes a trace message to indicate that the current method has ended. |
| 240 | * Must be called exactly once for each call to {@link #asyncTraceBegin(long, String, int)} |
| 241 | * using the same tag, name and cookie. |
| 242 | * |
| 243 | * @param traceTag The trace tag. |
| 244 | * @param methodName The method name to appear in the trace. |
| 245 | * @param cookie Unique identifier for distinguishing simultaneous events |
| 246 | * |
| 247 | * @hide |
| 248 | */ |
| 249 | public static void asyncTraceEnd(long traceTag, String methodName, int cookie) { |
| 250 | if (isTagEnabled(traceTag)) { |
| 251 | nativeAsyncTraceEnd(traceTag, methodName, cookie); |
| 252 | } |
| 253 | } |
| 254 | |
| 255 | /** |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 256 | * Writes a trace message to indicate that a given section of code has begun. This call must |
Jamie Gennis | 5800fc8 | 2013-04-09 18:37:22 -0700 | [diff] [blame] | 257 | * be followed by a corresponding call to {@link #endSection()} on the same thread. |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 258 | * |
| 259 | * <p class="note"> At this time the vertical bar character '|', newline character '\n', and |
| 260 | * null character '\0' are used internally by the tracing mechanism. If sectionName contains |
| 261 | * these characters they will be replaced with a space character in the trace. |
| 262 | * |
| 263 | * @param sectionName The name of the code section to appear in the trace. This may be at |
| 264 | * most 127 Unicode code units long. |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 265 | */ |
Jamie Gennis | 5800fc8 | 2013-04-09 18:37:22 -0700 | [diff] [blame] | 266 | public static void beginSection(String sectionName) { |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 267 | if (isTagEnabled(TRACE_TAG_APP)) { |
| 268 | if (sectionName.length() > MAX_SECTION_NAME_LEN) { |
| 269 | throw new IllegalArgumentException("sectionName is too long"); |
| 270 | } |
| 271 | nativeTraceBegin(TRACE_TAG_APP, sectionName); |
| 272 | } |
| 273 | } |
| 274 | |
| 275 | /** |
| 276 | * Writes a trace message to indicate that a given section of code has ended. This call must |
Jamie Gennis | 5800fc8 | 2013-04-09 18:37:22 -0700 | [diff] [blame] | 277 | * be preceeded by a corresponding call to {@link #beginSection(String)}. Calling this method |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 278 | * will mark the end of the most recently begun section of code, so care must be taken to |
Jamie Gennis | 5800fc8 | 2013-04-09 18:37:22 -0700 | [diff] [blame] | 279 | * ensure that beginSection / endSection pairs are properly nested and called from the same |
| 280 | * thread. |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 281 | */ |
Jamie Gennis | 5800fc8 | 2013-04-09 18:37:22 -0700 | [diff] [blame] | 282 | public static void endSection() { |
Jamie Gennis | f9c7d6b | 2013-03-25 14:18:25 -0700 | [diff] [blame] | 283 | if (isTagEnabled(TRACE_TAG_APP)) { |
| 284 | nativeTraceEnd(TRACE_TAG_APP); |
| 285 | } |
| 286 | } |
Jeff Brown | 481c157 | 2012-03-09 14:41:15 -0800 | [diff] [blame] | 287 | } |