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 /** 20 * Writes trace events to the system trace buffer. These trace events can be 21 * collected and visualized using the Systrace tool. 22 * 23 * <p>This tracing mechanism is independent of the method tracing mechanism 24 * offered by {@link Debug#startMethodTracing}. In particular, it enables 25 * tracing of events that occur across multiple processes. 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>. 29 */ 30 public final class Trace { 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 36 private static final String TAG = "Trace"; 37 38 // These tags must be kept in sync with system/core/include/cutils/trace.h. 39 // They should also be added to frameworks/native/cmds/atrace/atrace.cpp. 40 /** @hide */ 41 public static final long TRACE_TAG_NEVER = 0; 42 /** @hide */ 43 public static final long TRACE_TAG_ALWAYS = 1L << 0; 44 /** @hide */ 45 public static final long TRACE_TAG_GRAPHICS = 1L << 1; 46 /** @hide */ 47 public static final long TRACE_TAG_INPUT = 1L << 2; 48 /** @hide */ 49 public static final long TRACE_TAG_VIEW = 1L << 3; 50 /** @hide */ 51 public static final long TRACE_TAG_WEBVIEW = 1L << 4; 52 /** @hide */ 53 public static final long TRACE_TAG_WINDOW_MANAGER = 1L << 5; 54 /** @hide */ 55 public static final long TRACE_TAG_ACTIVITY_MANAGER = 1L << 6; 56 /** @hide */ 57 public static final long TRACE_TAG_SYNC_MANAGER = 1L << 7; 58 /** @hide */ 59 public static final long TRACE_TAG_AUDIO = 1L << 8; 60 /** @hide */ 61 public static final long TRACE_TAG_VIDEO = 1L << 9; 62 /** @hide */ 63 public static final long TRACE_TAG_CAMERA = 1L << 10; 64 /** @hide */ 65 public static final long TRACE_TAG_HAL = 1L << 11; 66 /** @hide */ 67 public static final long TRACE_TAG_APP = 1L << 12; 68 /** @hide */ 69 public static final long TRACE_TAG_RESOURCES = 1L << 13; 70 /** @hide */ 71 public static final long TRACE_TAG_DALVIK = 1L << 14; 72 /** @hide */ 73 public static final long TRACE_TAG_RS = 1L << 15; 74 /** @hide */ 75 public static final long TRACE_TAG_BIONIC = 1L << 16; 76 /** @hide */ 77 public static final long TRACE_TAG_POWER = 1L << 17; 78 /** @hide */ 79 public static final long TRACE_TAG_PACKAGE_MANAGER = 1L << 18; 80 /** @hide */ 81 public static final long TRACE_TAG_SYSTEM_SERVER = 1L << 19; 82 /** @hide */ 83 public static final long TRACE_TAG_DATABASE = 1L << 20; 84 85 private static final long TRACE_TAG_NOT_READY = 1L << 63; 86 private static final int MAX_SECTION_NAME_LEN = 127; 87 88 // Must be volatile to avoid word tearing. 89 private static volatile long sEnabledTags = TRACE_TAG_NOT_READY; 90 nativeGetEnabledTags()91 private static native long nativeGetEnabledTags(); nativeTraceCounter(long tag, String name, int value)92 private static native void nativeTraceCounter(long tag, String name, int value); nativeTraceBegin(long tag, String name)93 private static native void nativeTraceBegin(long tag, String name); nativeTraceEnd(long tag)94 private static native void nativeTraceEnd(long tag); nativeAsyncTraceBegin(long tag, String name, int cookie)95 private static native void nativeAsyncTraceBegin(long tag, String name, int cookie); nativeAsyncTraceEnd(long tag, String name, int cookie)96 private static native void nativeAsyncTraceEnd(long tag, String name, int cookie); nativeSetAppTracingAllowed(boolean allowed)97 private static native void nativeSetAppTracingAllowed(boolean allowed); nativeSetTracingEnabled(boolean allowed)98 private static native void nativeSetTracingEnabled(boolean allowed); 99 100 static { 101 // We configure two separate change callbacks, one in Trace.cpp and one here. The 102 // native callback reads the tags from the system property, and this callback 103 // reads the value that the native code retrieved. It's essential that the native 104 // callback executes first. 105 // 106 // The system provides ordering through a priority level. Callbacks made through 107 // SystemProperties.addChangeCallback currently have a negative priority, while 108 // our native code is using a priority of zero. SystemProperties.addChangeCallback(new Runnable() { @Override public void run() { cacheEnabledTags(); } })109 SystemProperties.addChangeCallback(new Runnable() { 110 @Override public void run() { 111 cacheEnabledTags(); 112 } 113 }); 114 } 115 Trace()116 private Trace() { 117 } 118 119 /** 120 * Caches a copy of the enabled-tag bits. The "master" copy is held by the native code, 121 * and comes from the PROPERTY_TRACE_TAG_ENABLEFLAGS property. 122 * <p> 123 * If the native code hasn't yet read the property, we will cause it to do one-time 124 * initialization. We don't want to do this during class init, because this class is 125 * preloaded, so all apps would be stuck with whatever the zygote saw. (The zygote 126 * doesn't see the system-property update broadcasts.) 127 * <p> 128 * We want to defer initialization until the first use by an app, post-zygote. 129 * <p> 130 * We're okay if multiple threads call here simultaneously -- the native state is 131 * synchronized, and sEnabledTags is volatile (prevents word tearing). 132 */ cacheEnabledTags()133 private static long cacheEnabledTags() { 134 long tags = nativeGetEnabledTags(); 135 sEnabledTags = tags; 136 return tags; 137 } 138 139 /** 140 * Returns true if a trace tag is enabled. 141 * 142 * @param traceTag The trace tag to check. 143 * @return True if the trace tag is valid. 144 * 145 * @hide 146 */ isTagEnabled(long traceTag)147 public static boolean isTagEnabled(long traceTag) { 148 long tags = sEnabledTags; 149 if (tags == TRACE_TAG_NOT_READY) { 150 tags = cacheEnabledTags(); 151 } 152 return (tags & traceTag) != 0; 153 } 154 155 /** 156 * Writes trace message to indicate the value of a given counter. 157 * 158 * @param traceTag The trace tag. 159 * @param counterName The counter name to appear in the trace. 160 * @param counterValue The counter value. 161 * 162 * @hide 163 */ traceCounter(long traceTag, String counterName, int counterValue)164 public static void traceCounter(long traceTag, String counterName, int counterValue) { 165 if (isTagEnabled(traceTag)) { 166 nativeTraceCounter(traceTag, counterName, counterValue); 167 } 168 } 169 170 /** 171 * Set whether application tracing is allowed for this process. This is intended to be set 172 * once at application start-up time based on whether the application is debuggable. 173 * 174 * @hide 175 */ setAppTracingAllowed(boolean allowed)176 public static void setAppTracingAllowed(boolean allowed) { 177 nativeSetAppTracingAllowed(allowed); 178 179 // Setting whether app tracing is allowed may change the tags, so we update the cached 180 // tags here. 181 cacheEnabledTags(); 182 } 183 184 /** 185 * Set whether tracing is enabled in this process. Tracing is disabled shortly after Zygote 186 * initializes and re-enabled after processes fork from Zygote. This is done because Zygote 187 * has no way to be notified about changes to the tracing tags, and if Zygote ever reads and 188 * caches the tracing tags, forked processes will inherit those stale tags. 189 * 190 * @hide 191 */ setTracingEnabled(boolean enabled)192 public static void setTracingEnabled(boolean enabled) { 193 nativeSetTracingEnabled(enabled); 194 195 // Setting whether tracing is enabled may change the tags, so we update the cached tags 196 // here. 197 cacheEnabledTags(); 198 } 199 200 /** 201 * Writes a trace message to indicate that a given section of code has 202 * begun. Must be followed by a call to {@link #traceEnd} using the same 203 * tag. 204 * 205 * @param traceTag The trace tag. 206 * @param methodName The method name to appear in the trace. 207 * 208 * @hide 209 */ traceBegin(long traceTag, String methodName)210 public static void traceBegin(long traceTag, String methodName) { 211 if (isTagEnabled(traceTag)) { 212 nativeTraceBegin(traceTag, methodName); 213 } 214 } 215 216 /** 217 * Writes a trace message to indicate that the current method has ended. 218 * Must be called exactly once for each call to {@link #traceBegin} using the same tag. 219 * 220 * @param traceTag The trace tag. 221 * 222 * @hide 223 */ traceEnd(long traceTag)224 public static void traceEnd(long traceTag) { 225 if (isTagEnabled(traceTag)) { 226 nativeTraceEnd(traceTag); 227 } 228 } 229 230 /** 231 * Writes a trace message to indicate that a given section of code has 232 * begun. Must be followed by a call to {@link #asyncTraceEnd} using the same 233 * tag. Unlike {@link #traceBegin(long, String)} and {@link #traceEnd(long)}, 234 * asynchronous events do not need to be nested. The name and cookie used to 235 * begin an event must be used to end it. 236 * 237 * @param traceTag The trace tag. 238 * @param methodName The method name to appear in the trace. 239 * @param cookie Unique identifier for distinguishing simultaneous events 240 * 241 * @hide 242 */ asyncTraceBegin(long traceTag, String methodName, int cookie)243 public static void asyncTraceBegin(long traceTag, String methodName, int cookie) { 244 if (isTagEnabled(traceTag)) { 245 nativeAsyncTraceBegin(traceTag, methodName, cookie); 246 } 247 } 248 249 /** 250 * Writes a trace message to indicate that the current method has ended. 251 * Must be called exactly once for each call to {@link #asyncTraceBegin(long, String, int)} 252 * using the same tag, name and cookie. 253 * 254 * @param traceTag The trace tag. 255 * @param methodName The method name to appear in the trace. 256 * @param cookie Unique identifier for distinguishing simultaneous events 257 * 258 * @hide 259 */ asyncTraceEnd(long traceTag, String methodName, int cookie)260 public static void asyncTraceEnd(long traceTag, String methodName, int cookie) { 261 if (isTagEnabled(traceTag)) { 262 nativeAsyncTraceEnd(traceTag, methodName, cookie); 263 } 264 } 265 266 /** 267 * Writes a trace message to indicate that a given section of code has begun. This call must 268 * be followed by a corresponding call to {@link #endSection()} on the same thread. 269 * 270 * <p class="note"> At this time the vertical bar character '|', newline character '\n', and 271 * null character '\0' are used internally by the tracing mechanism. If sectionName contains 272 * these characters they will be replaced with a space character in the trace. 273 * 274 * @param sectionName The name of the code section to appear in the trace. This may be at 275 * most 127 Unicode code units long. 276 */ beginSection(String sectionName)277 public static void beginSection(String sectionName) { 278 if (isTagEnabled(TRACE_TAG_APP)) { 279 if (sectionName.length() > MAX_SECTION_NAME_LEN) { 280 throw new IllegalArgumentException("sectionName is too long"); 281 } 282 nativeTraceBegin(TRACE_TAG_APP, sectionName); 283 } 284 } 285 286 /** 287 * Writes a trace message to indicate that a given section of code has ended. This call must 288 * be preceeded by a corresponding call to {@link #beginSection(String)}. Calling this method 289 * will mark the end of the most recently begun section of code, so care must be taken to 290 * ensure that beginSection / endSection pairs are properly nested and called from the same 291 * thread. 292 */ endSection()293 public static void endSection() { 294 if (isTagEnabled(TRACE_TAG_APP)) { 295 nativeTraceEnd(TRACE_TAG_APP); 296 } 297 } 298 } 299