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