core/java/android/os/Trace.java

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