content: /*
   * Copyright (C) 2012 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package android.os;
  
  import android.annotation.NonNull;
  import android.annotation.UnsupportedAppUsage;
  
  import com.android.internal.os.Zygote;
  
  import dalvik.annotation.optimization.FastNative;
  
  /**
   * Writes trace events to the system trace buffer.  These trace events can be
   * collected and visualized using the Systrace tool.
   *
   * <p>This tracing mechanism is independent of the method tracing mechanism
   * offered by {@link Debug#startMethodTracing}.  In particular, it enables
   * tracing of events that occur across multiple processes.
   * <p>For information about using the Systrace tool, read <a
   * href="{@docRoot}tools/debugging/systrace.html">Analyzing Display and Performance
   * with Systrace</a>.
   */
  public final class Trace {
      /*
       * Writes trace events to the kernel trace buffer.  These trace events can be
       * collected using the "atrace" program for offline analysis.
       */
  
      private static final String TAG = "Trace";
  
      // These tags must be kept in sync with system/core/include/cutils/trace.h.
      // They should also be added to frameworks/native/cmds/atrace/atrace.cpp.
      /** @hide */
      public static final long TRACE_TAG_NEVER = 0;
      /** @hide */
      public static final long TRACE_TAG_ALWAYS = 1L << 0;
      /** @hide */
      public static final long TRACE_TAG_GRAPHICS = 1L << 1;
      /** @hide */
      public static final long TRACE_TAG_INPUT = 1L << 2;
      /** @hide */
      @UnsupportedAppUsage
      public static final long TRACE_TAG_VIEW = 1L << 3;
      /** @hide */
      public static final long TRACE_TAG_WEBVIEW = 1L << 4;
      /** @hide */
      public static final long TRACE_TAG_WINDOW_MANAGER = 1L << 5;
      /** @hide */
      public static final long TRACE_TAG_ACTIVITY_MANAGER = 1L << 6;
      /** @hide */
      public static final long TRACE_TAG_SYNC_MANAGER = 1L << 7;
      /** @hide */
      public static final long TRACE_TAG_AUDIO = 1L << 8;
      /** @hide */
      public static final long TRACE_TAG_VIDEO = 1L << 9;
      /** @hide */
      public static final long TRACE_TAG_CAMERA = 1L << 10;
      /** @hide */
      public static final long TRACE_TAG_HAL = 1L << 11;
      /** @hide */
      @UnsupportedAppUsage
      public static final long TRACE_TAG_APP = 1L << 12;
      /** @hide */
      public static final long TRACE_TAG_RESOURCES = 1L << 13;
      /** @hide */
      public static final long TRACE_TAG_DALVIK = 1L << 14;
      /** @hide */
      public static final long TRACE_TAG_RS = 1L << 15;
      /** @hide */
      public static final long TRACE_TAG_BIONIC = 1L << 16;
      /** @hide */
      public static final long TRACE_TAG_POWER = 1L << 17;
      /** @hide */
      public static final long TRACE_TAG_PACKAGE_MANAGER = 1L << 18;
      /** @hide */
      public static final long TRACE_TAG_SYSTEM_SERVER = 1L << 19;
      /** @hide */
      public static final long TRACE_TAG_DATABASE = 1L << 20;
      /** @hide */
      public static final long TRACE_TAG_NETWORK = 1L << 21;
      /** @hide */
      public static final long TRACE_TAG_ADB = 1L << 22;
      /** @hide */
      public static final long TRACE_TAG_VIBRATOR = 1L << 23;
      /** @hide */
      public static final long TRACE_TAG_AIDL = 1L << 24;
      /** @hide */
      public static final long TRACE_TAG_NNAPI = 1L << 25;
      /** @hide */
      public static final long TRACE_TAG_RRO = 1L << 26;
  
      private static final long TRACE_TAG_NOT_READY = 1L << 63;
      private static final int MAX_SECTION_NAME_LEN = 127;
  
      // Must be volatile to avoid word tearing.
      @UnsupportedAppUsage
      private static volatile long sEnabledTags = TRACE_TAG_NOT_READY;
  
      private static int sZygoteDebugFlags = 0;
  
      @UnsupportedAppUsage
      private static native long nativeGetEnabledTags();
      private static native void nativeSetAppTracingAllowed(boolean allowed);
      private static native void nativeSetTracingEnabled(boolean allowed);
  
      @FastNative
      private static native void nativeTraceCounter(long tag, String name, long value);
      @FastNative
      private static native void nativeTraceBegin(long tag, String name);
      @FastNative
      private static native void nativeTraceEnd(long tag);
      @FastNative
      private static native void nativeAsyncTraceBegin(long tag, String name, int cookie);
      @FastNative
      private static native void nativeAsyncTraceEnd(long tag, String name, int cookie);
  
      static {
          // We configure two separate change callbacks, one in Trace.cpp and one here.  The
          // native callback reads the tags from the system property, and this callback
          // reads the value that the native code retrieved.  It's essential that the native
          // callback executes first.
          //
          // The system provides ordering through a priority level.  Callbacks made through
          // SystemProperties.addChangeCallback currently have a negative priority, while
          // our native code is using a priority of zero.
          SystemProperties.addChangeCallback(() -> {
              cacheEnabledTags();
              if ((sZygoteDebugFlags & Zygote.DEBUG_JAVA_DEBUGGABLE) != 0) {
                  traceCounter(TRACE_TAG_ALWAYS, "java_debuggable", 1);
              }
          });
      }
  
      private Trace() {
      }
  
      /**
       * Caches a copy of the enabled-tag bits.  The "master" copy is held by the native code,
       * and comes from the PROPERTY_TRACE_TAG_ENABLEFLAGS property.
       * <p>
       * If the native code hasn't yet read the property, we will cause it to do one-time
       * initialization.  We don't want to do this during class init, because this class is
       * preloaded, so all apps would be stuck with whatever the zygote saw.  (The zygote
       * doesn't see the system-property update broadcasts.)
       * <p>
       * We want to defer initialization until the first use by an app, post-zygote.
       * <p>
       * We're okay if multiple threads call here simultaneously -- the native state is
       * synchronized, and sEnabledTags is volatile (prevents word tearing).
       */
      private static long cacheEnabledTags() {
          long tags = nativeGetEnabledTags();
          sEnabledTags = tags;
          return tags;
      }
  
      /**
       * Returns true if a trace tag is enabled.
       *
       * @param traceTag The trace tag to check.
       * @return True if the trace tag is valid.
       *
       * @hide
       */
      @UnsupportedAppUsage
      public static boolean isTagEnabled(long traceTag) {
          long tags = sEnabledTags;
          if (tags == TRACE_TAG_NOT_READY) {
              tags = cacheEnabledTags();
          }
          return (tags & traceTag) != 0;
      }
  
      /**
       * Writes trace message to indicate the value of a given counter.
       *
       * @param traceTag The trace tag.
       * @param counterName The counter name to appear in the trace.
       * @param counterValue The counter value.
       *
       * @hide
       */
      @UnsupportedAppUsage
      public static void traceCounter(long traceTag, String counterName, int counterValue) {
          if (isTagEnabled(traceTag)) {
              nativeTraceCounter(traceTag, counterName, counterValue);
          }
      }
  
      /**
       * Set whether application tracing is allowed for this process.  This is intended to be set
       * once at application start-up time based on whether the application is debuggable.
       *
       * @hide
       */
      @UnsupportedAppUsage
      public static void setAppTracingAllowed(boolean allowed) {
          nativeSetAppTracingAllowed(allowed);
  
          // Setting whether app tracing is allowed may change the tags, so we update the cached
          // tags here.
          cacheEnabledTags();
      }
  
      /**
       * Set whether tracing is enabled in this process.  Tracing is disabled shortly after Zygote
       * initializes and re-enabled after processes fork from Zygote.  This is done because Zygote
       * has no way to be notified about changes to the tracing tags, and if Zygote ever reads and
       * caches the tracing tags, forked processes will inherit those stale tags.
       *
       * @hide
       */
      public static void setTracingEnabled(boolean enabled, int debugFlags) {
          nativeSetTracingEnabled(enabled);
          sZygoteDebugFlags = debugFlags;
  
          // Setting whether tracing is enabled may change the tags, so we update the cached tags
          // here.
          cacheEnabledTags();
      }
  
      /**
       * Writes a trace message to indicate that a given section of code has
       * begun. Must be followed by a call to {@link #traceEnd} using the same
       * tag.
       *
       * @param traceTag The trace tag.
       * @param methodName The method name to appear in the trace.
       *
       * @hide
       */
      @UnsupportedAppUsage
      public static void traceBegin(long traceTag, String methodName) {
          if (isTagEnabled(traceTag)) {
              nativeTraceBegin(traceTag, methodName);
          }
      }
  
      /**
       * Writes a trace message to indicate that the current method has ended.
       * Must be called exactly once for each call to {@link #traceBegin} using the same tag.
       *
       * @param traceTag The trace tag.
       *
       * @hide
       */
      @UnsupportedAppUsage
      public static void traceEnd(long traceTag) {
          if (isTagEnabled(traceTag)) {
              nativeTraceEnd(traceTag);
          }
      }
  
      /**
       * Writes a trace message to indicate that a given section of code has
       * begun. Must be followed by a call to {@link #asyncTraceEnd} using the same
       * tag. Unlike {@link #traceBegin(long, String)} and {@link #traceEnd(long)},
       * asynchronous events do not need to be nested. The name and cookie used to
       * begin an event must be used to end it.
       *
       * @param traceTag The trace tag.
       * @param methodName The method name to appear in the trace.
       * @param cookie Unique identifier for distinguishing simultaneous events
       *
       * @hide
       */
      @UnsupportedAppUsage
      public static void asyncTraceBegin(long traceTag, String methodName, int cookie) {
          if (isTagEnabled(traceTag)) {
              nativeAsyncTraceBegin(traceTag, methodName, cookie);
          }
      }
  
      /**
       * Writes a trace message to indicate that the current method has ended.
       * Must be called exactly once for each call to {@link #asyncTraceBegin(long, String, int)}
       * using the same tag, name and cookie.
       *
       * @param traceTag The trace tag.
       * @param methodName The method name to appear in the trace.
       * @param cookie Unique identifier for distinguishing simultaneous events
       *
       * @hide
       */
      @UnsupportedAppUsage
      public static void asyncTraceEnd(long traceTag, String methodName, int cookie) {
          if (isTagEnabled(traceTag)) {
              nativeAsyncTraceEnd(traceTag, methodName, cookie);
          }
      }
  
      /**
       * Checks whether or not tracing is currently enabled. This is useful to avoid intermediate
       * string creation for trace sections that require formatting. It is not necessary
       * to guard all Trace method calls as they internally already check this. However it is
       * recommended to use this to prevent creating any temporary objects that would then be
       * passed to those methods to reduce runtime cost when tracing isn't enabled.
       *
       * @return true if tracing is currently enabled, false otherwise
       */
      public static boolean isEnabled() {
          return isTagEnabled(TRACE_TAG_APP);
      }
  
      /**
       * Writes a trace message to indicate that a given section of code has begun. This call must
       * be followed by a corresponding call to {@link #endSection()} on the same thread.
       *
       * <p class="note"> At this time the vertical bar character '|', newline character '\n', and
       * null character '\0' are used internally by the tracing mechanism.  If sectionName contains
       * these characters they will be replaced with a space character in the trace.
       *
       * @param sectionName The name of the code section to appear in the trace.  This may be at
       * most 127 Unicode code units long.
       */
      public static void beginSection(@NonNull String sectionName) {
          if (isTagEnabled(TRACE_TAG_APP)) {
              if (sectionName.length() > MAX_SECTION_NAME_LEN) {
                  throw new IllegalArgumentException("sectionName is too long");
              }
              nativeTraceBegin(TRACE_TAG_APP, sectionName);
          }
      }
  
      /**
       * Writes a trace message to indicate that a given section of code has ended. This call must
       * be preceeded by a corresponding call to {@link #beginSection(String)}. Calling this method
       * will mark the end of the most recently begun section of code, so care must be taken to
       * ensure that beginSection / endSection pairs are properly nested and called from the same
       * thread.
       */
      public static void endSection() {
          if (isTagEnabled(TRACE_TAG_APP)) {
              nativeTraceEnd(TRACE_TAG_APP);
          }
      }
  
      /**
       * Writes a trace message to indicate that a given section of code has
       * begun. Must be followed by a call to {@link #endAsyncSection(String, int)} with the same
       * methodName and cookie. Unlike {@link #beginSection(String)} and {@link #endSection()},
       * asynchronous events do not need to be nested. The name and cookie used to
       * begin an event must be used to end it.
       *
       * @param methodName The method name to appear in the trace.
       * @param cookie Unique identifier for distinguishing simultaneous events
       */
      public static void beginAsyncSection(@NonNull String methodName, int cookie) {
          asyncTraceBegin(TRACE_TAG_APP, methodName, cookie);
      }
  
      /**
       * Writes a trace message to indicate that the current method has ended.
       * Must be called exactly once for each call to {@link #beginAsyncSection(String, int)}
       * using the same name and cookie.
       *
       * @param methodName The method name to appear in the trace.
       * @param cookie Unique identifier for distinguishing simultaneous events
       */
      public static void endAsyncSection(@NonNull String methodName, int cookie) {
          asyncTraceEnd(TRACE_TAG_APP, methodName, cookie);
      }
  
      /**
       * Writes trace message to indicate the value of a given counter.
       *
       * @param counterName The counter name to appear in the trace.
       * @param counterValue The counter value.
       */
      public static void setCounter(@NonNull String counterName, long counterValue) {
          if (isTagEnabled(TRACE_TAG_APP)) {
              nativeTraceCounter(TRACE_TAG_APP, counterName, counterValue);
          }
      }
  }
  