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