https://source.android.com/ 
/*
 * Copyright (C) 2006 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.util;

import android.os.DeadSystemException;

import com.android.internal.os.RuntimeInit;
import com.android.internal.util.FastPrintWriter;
import com.android.internal.util.LineBreakBufferedWriter;

import java.io.PrintWriter;
import java.io.StringWriter;
import java.io.Writer;
import java.net.UnknownHostException;


API for sending log output.

Generally, you should use the Log.v(), Log.d(), Log.i(), Log.w(), and Log.e() methods to write logs. You can then view the logs in logcat.

The order in terms of verbosity, from least to most is
ERROR, WARN, INFO, DEBUG, VERBOSE.  Verbose should never be compiled
into an application except during development.  Debug logs are compiled
in but stripped at runtime.  Error, warning and info logs are always kept.

Tip: A good convention is to declare a TAG constant
in your class:

private static final String TAG = "MyActivity";

and use that in subsequent calls to the log methods.



Tip: Don't forget that when you make a call like

Log.v(TAG, "index=" + i);

that when you're building the string to pass into Log.d, the compiler uses a
StringBuilder and at least three allocations occur: the StringBuilder
itself, the buffer, and the String object.  Realistically, there is also
another buffer allocation and copy, and even more pressure on the gc.
That means that if your log message is filtered out, you might be doing
significant work and incurring significant overhead.

/**
 * API for sending log output.
 *
 * <p>Generally, you should use the {@link #v Log.v()}, {@link #d Log.d()},
 * {@link #i Log.i()}, {@link #w Log.w()}, and {@link #e Log.e()} methods to write logs.
 * You can then <a href="{@docRoot}studio/debug/am-logcat.html">view the logs in logcat</a>.
 *
 * <p>The order in terms of verbosity, from least to most is
 * ERROR, WARN, INFO, DEBUG, VERBOSE.  Verbose should never be compiled
 * into an application except during development.  Debug logs are compiled
 * in but stripped at runtime.  Error, warning and info logs are always kept.
 *
 * <p><b>Tip:</b> A good convention is to declare a <code>TAG</code> constant
 * in your class:
 *
 * <pre>private static final String TAG = "MyActivity";</pre>
 *
 * and use that in subsequent calls to the log methods.
 * </p>
 *
 * <p><b>Tip:</b> Don't forget that when you make a call like
 * <pre>Log.v(TAG, "index=" + i);</pre>
 * that when you're building the string to pass into Log.d, the compiler uses a
 * StringBuilder and at least three allocations occur: the StringBuilder
 * itself, the buffer, and the String object.  Realistically, there is also
 * another buffer allocation and copy, and even more pressure on the gc.
 * That means that if your log message is filtered out, you might be doing
 * significant work and incurring significant overhead.
 */
public final class Log {

    
Priority constant for the println method; use Log.v.

/**
     * Priority constant for the println method; use Log.v.
     */
    public static final int VERBOSE = 2;

    
Priority constant for the println method; use Log.d.

/**
     * Priority constant for the println method; use Log.d.
     */
    public static final int DEBUG = 3;

    
Priority constant for the println method; use Log.i.

/**
     * Priority constant for the println method; use Log.i.
     */
    public static final int INFO = 4;

    
Priority constant for the println method; use Log.w.

/**
     * Priority constant for the println method; use Log.w.
     */
    public static final int WARN = 5;

    
Priority constant for the println method; use Log.e.

/**
     * Priority constant for the println method; use Log.e.
     */
    public static final int ERROR = 6;

    
Priority constant for the println method.

/**
     * Priority constant for the println method.
     */
    public static final int ASSERT = 7;

    
Exception class used to capture a stack trace in wtf. 
@hide
/**
     * Exception class used to capture a stack trace in {@link #wtf}.
     * @hide
     */
    public static class TerribleFailure extends Exception {
        TerribleFailure(String msg, Throwable cause) { super(msg, cause); }
    }

    
Interface to handle terrible failures from wtf. 
@hide
/**
     * Interface to handle terrible failures from {@link #wtf}.
     *
     * @hide
     */
    public interface TerribleFailureHandler {
        void onTerribleFailure(String tag, TerribleFailure what, boolean system);
    }

    private static TerribleFailureHandler sWtfHandler = new TerribleFailureHandler() {
            public void onTerribleFailure(String tag, TerribleFailure what, boolean system) {
                RuntimeInit.wtf(tag, what, system);
            }
        };

    private Log() {
    }

    
Send a VERBOSE log message. 
Params:
  • tag – Used to identify the source of a log message.  It usually identifies
       the class or activity where the log call occurs.
  • msg – The message you would like logged.
/**
     * Send a {@link #VERBOSE} log message.
     * @param tag Used to identify the source of a log message.  It usually identifies
     *        the class or activity where the log call occurs.
     * @param msg The message you would like logged.
     */
    public static int v(String tag, String msg) {
        return println_native(LOG_ID_MAIN, VERBOSE, tag, msg);
    }

    
Send a VERBOSE log message and log the exception. 
Params:
  • tag – Used to identify the source of a log message.  It usually identifies
       the class or activity where the log call occurs.
  • msg – The message you would like logged.
  • tr – An exception to log
/**
     * Send a {@link #VERBOSE} log message and log the exception.
     * @param tag Used to identify the source of a log message.  It usually identifies
     *        the class or activity where the log call occurs.
     * @param msg The message you would like logged.
     * @param tr An exception to log
     */
    public static int v(String tag, String msg, Throwable tr) {
        return printlns(LOG_ID_MAIN, VERBOSE, tag, msg, tr);
    }

    
Send a DEBUG log message. 
Params:
  • tag – Used to identify the source of a log message.  It usually identifies
       the class or activity where the log call occurs.
  • msg – The message you would like logged.
/**
     * Send a {@link #DEBUG} log message.
     * @param tag Used to identify the source of a log message.  It usually identifies
     *        the class or activity where the log call occurs.
     * @param msg The message you would like logged.
     */
    public static int d(String tag, String msg) {
        return println_native(LOG_ID_MAIN, DEBUG, tag, msg);
    }

    
Send a DEBUG log message and log the exception. 
Params:
  • tag – Used to identify the source of a log message.  It usually identifies
       the class or activity where the log call occurs.
  • msg – The message you would like logged.
  • tr – An exception to log
/**
     * Send a {@link #DEBUG} log message and log the exception.
     * @param tag Used to identify the source of a log message.  It usually identifies
     *        the class or activity where the log call occurs.
     * @param msg The message you would like logged.
     * @param tr An exception to log
     */
    public static int d(String tag, String msg, Throwable tr) {
        return printlns(LOG_ID_MAIN, DEBUG, tag, msg, tr);
    }

    
Send an INFO log message. 
Params:
  • tag – Used to identify the source of a log message.  It usually identifies
       the class or activity where the log call occurs.
  • msg – The message you would like logged.
/**
     * Send an {@link #INFO} log message.
     * @param tag Used to identify the source of a log message.  It usually identifies
     *        the class or activity where the log call occurs.
     * @param msg The message you would like logged.
     */
    public static int i(String tag, String msg) {
        return println_native(LOG_ID_MAIN, INFO, tag, msg);
    }

    
Send a INFO log message and log the exception. 
Params:
  • tag – Used to identify the source of a log message.  It usually identifies
       the class or activity where the log call occurs.
  • msg – The message you would like logged.
  • tr – An exception to log
/**
     * Send a {@link #INFO} log message and log the exception.
     * @param tag Used to identify the source of a log message.  It usually identifies
     *        the class or activity where the log call occurs.
     * @param msg The message you would like logged.
     * @param tr An exception to log
     */
    public static int i(String tag, String msg, Throwable tr) {
        return printlns(LOG_ID_MAIN, INFO, tag, msg, tr);
    }

    
Send a WARN log message. 
Params:
  • tag – Used to identify the source of a log message.  It usually identifies
       the class or activity where the log call occurs.
  • msg – The message you would like logged.
/**
     * Send a {@link #WARN} log message.
     * @param tag Used to identify the source of a log message.  It usually identifies
     *        the class or activity where the log call occurs.
     * @param msg The message you would like logged.
     */
    public static int w(String tag, String msg) {
        return println_native(LOG_ID_MAIN, WARN, tag, msg);
    }

    
Send a WARN log message and log the exception. 
Params:
  • tag – Used to identify the source of a log message.  It usually identifies
       the class or activity where the log call occurs.
  • msg – The message you would like logged.
  • tr – An exception to log
/**
     * Send a {@link #WARN} log message and log the exception.
     * @param tag Used to identify the source of a log message.  It usually identifies
     *        the class or activity where the log call occurs.
     * @param msg The message you would like logged.
     * @param tr An exception to log
     */
    public static int w(String tag, String msg, Throwable tr) {
        return printlns(LOG_ID_MAIN, WARN, tag, msg, tr);
    }

    
Checks to see whether or not a log for the specified tag is loggable at the specified level.
 The default level of any tag is set to INFO. This means that any level above and including
 INFO will be logged. Before you make any calls to a logging method you should check to see
 if your tag should be logged. You can change the default level by setting a system property:
     'setprop log.tag.<YOUR_LOG_TAG> <LEVEL>'
 Where level is either VERBOSE, DEBUG, INFO, WARN, ERROR, ASSERT, or SUPPRESS. SUPPRESS will
 turn off all logging for your tag. You can also create a local.prop file that with the
 following in it:
     'log.tag.<YOUR_LOG_TAG>=<LEVEL>'
 and place that in /data/local.prop.

Params:
  • tag – The tag to check.
  • level – The level to check.
Throws:
  • IllegalArgumentException – is thrown if the tag.length() > 23
        for Nougat (7.0) releases (API <= 23) and prior, there is no
        tag limit of concern after this API level.
Returns:Whether or not that this is allowed to be logged.
/**
     * Checks to see whether or not a log for the specified tag is loggable at the specified level.
     *
     *  The default level of any tag is set to INFO. This means that any level above and including
     *  INFO will be logged. Before you make any calls to a logging method you should check to see
     *  if your tag should be logged. You can change the default level by setting a system property:
     *      'setprop log.tag.&lt;YOUR_LOG_TAG> &lt;LEVEL>'
     *  Where level is either VERBOSE, DEBUG, INFO, WARN, ERROR, ASSERT, or SUPPRESS. SUPPRESS will
     *  turn off all logging for your tag. You can also create a local.prop file that with the
     *  following in it:
     *      'log.tag.&lt;YOUR_LOG_TAG>=&lt;LEVEL>'
     *  and place that in /data/local.prop.
     *
     * @param tag The tag to check.
     * @param level The level to check.
     * @return Whether or not that this is allowed to be logged.
     * @throws IllegalArgumentException is thrown if the tag.length() > 23
     *         for Nougat (7.0) releases (API <= 23) and prior, there is no
     *         tag limit of concern after this API level.
     */
    public static native boolean isLoggable(String tag, int level);

    /*
     * Send a {@link #WARN} log message and log the exception.
     * @param tag Used to identify the source of a log message.  It usually identifies
     *        the class or activity where the log call occurs.
     * @param tr An exception to log
     */
    public static int w(String tag, Throwable tr) {
        return printlns(LOG_ID_MAIN, WARN, tag, "", tr);
    }

    
Send an ERROR log message. 
Params:
  • tag – Used to identify the source of a log message.  It usually identifies
       the class or activity where the log call occurs.
  • msg – The message you would like logged.
/**
     * Send an {@link #ERROR} log message.
     * @param tag Used to identify the source of a log message.  It usually identifies
     *        the class or activity where the log call occurs.
     * @param msg The message you would like logged.
     */
    public static int e(String tag, String msg) {
        return println_native(LOG_ID_MAIN, ERROR, tag, msg);
    }

    
Send a ERROR log message and log the exception. 
Params:
  • tag – Used to identify the source of a log message.  It usually identifies
       the class or activity where the log call occurs.
  • msg – The message you would like logged.
  • tr – An exception to log
/**
     * Send a {@link #ERROR} log message and log the exception.
     * @param tag Used to identify the source of a log message.  It usually identifies
     *        the class or activity where the log call occurs.
     * @param msg The message you would like logged.
     * @param tr An exception to log
     */
    public static int e(String tag, String msg, Throwable tr) {
        return printlns(LOG_ID_MAIN, ERROR, tag, msg, tr);
    }

    
What a Terrible Failure: Report a condition that should never happen. The error will always be logged at level ASSERT with the call stack. Depending on system configuration, a report may be added to the DropBoxManager and/or the process may be terminated immediately with an error dialog. 
Params:
  • tag – Used to identify the source of a log message.
  • msg – The message you would like logged.
/**
     * What a Terrible Failure: Report a condition that should never happen.
     * The error will always be logged at level ASSERT with the call stack.
     * Depending on system configuration, a report may be added to the
     * {@link android.os.DropBoxManager} and/or the process may be terminated
     * immediately with an error dialog.
     * @param tag Used to identify the source of a log message.
     * @param msg The message you would like logged.
     */
    public static int wtf(String tag, String msg) {
        return wtf(LOG_ID_MAIN, tag, msg, null, false, false);
    }

    
Like wtf(String, String), but also writes to the log the full call stack. 
@hide
/**
     * Like {@link #wtf(String, String)}, but also writes to the log the full
     * call stack.
     * @hide
     */
    public static int wtfStack(String tag, String msg) {
        return wtf(LOG_ID_MAIN, tag, msg, null, true, false);
    }

    
What a Terrible Failure: Report an exception that should never happen. Similar to wtf(String, String), with an exception to log. 
Params:
  • tag – Used to identify the source of a log message.
  • tr – An exception to log.
/**
     * What a Terrible Failure: Report an exception that should never happen.
     * Similar to {@link #wtf(String, String)}, with an exception to log.
     * @param tag Used to identify the source of a log message.
     * @param tr An exception to log.
     */
    public static int wtf(String tag, Throwable tr) {
        return wtf(LOG_ID_MAIN, tag, tr.getMessage(), tr, false, false);
    }

    
What a Terrible Failure: Report an exception that should never happen. Similar to wtf(String, Throwable), with a message as well. 
Params:
  • tag – Used to identify the source of a log message.
  • msg – The message you would like logged.
  • tr – An exception to log.  May be null.
/**
     * What a Terrible Failure: Report an exception that should never happen.
     * Similar to {@link #wtf(String, Throwable)}, with a message as well.
     * @param tag Used to identify the source of a log message.
     * @param msg The message you would like logged.
     * @param tr An exception to log.  May be null.
     */
    public static int wtf(String tag, String msg, Throwable tr) {
        return wtf(LOG_ID_MAIN, tag, msg, tr, false, false);
    }

    static int wtf(int logId, String tag, String msg, Throwable tr, boolean localStack,
            boolean system) {
        TerribleFailure what = new TerribleFailure(msg, tr);
        // Only mark this as ERROR, do not use ASSERT since that should be
        // reserved for cases where the system is guaranteed to abort.
        // The onTerribleFailure call does not always cause a crash.
        int bytes = printlns(logId, ERROR, tag, msg, localStack ? what : tr);
        sWtfHandler.onTerribleFailure(tag, what, system);
        return bytes;
    }

    static void wtfQuiet(int logId, String tag, String msg, boolean system) {
        TerribleFailure what = new TerribleFailure(msg, null);
        sWtfHandler.onTerribleFailure(tag, what, system);
    }

    
Sets the terrible failure handler, for testing.

Returns:the old handler
@hide
/**
     * Sets the terrible failure handler, for testing.
     *
     * @return the old handler
     *
     * @hide
     */
    public static TerribleFailureHandler setWtfHandler(TerribleFailureHandler handler) {
        if (handler == null) {
            throw new NullPointerException("handler == null");
        }
        TerribleFailureHandler oldHandler = sWtfHandler;
        sWtfHandler = handler;
        return oldHandler;
    }

    
Handy function to get a loggable stack trace from a Throwable

Params:
  • tr – An exception to log
/**
     * Handy function to get a loggable stack trace from a Throwable
     * @param tr An exception to log
     */
    public static String getStackTraceString(Throwable tr) {
        if (tr == null) {
            return "";
        }

        // This is to reduce the amount of log spew that apps do in the non-error
        // condition of the network being unavailable.
        Throwable t = tr;
        while (t != null) {
            if (t instanceof UnknownHostException) {
                return "";
            }
            t = t.getCause();
        }

        StringWriter sw = new StringWriter();
        PrintWriter pw = new FastPrintWriter(sw, false, 256);
        tr.printStackTrace(pw);
        pw.flush();
        return sw.toString();
    }

    
Low-level logging call.

Params:
  • priority – The priority/type of this log message
  • tag – Used to identify the source of a log message.  It usually identifies
       the class or activity where the log call occurs.
  • msg – The message you would like logged.
Returns:The number of bytes written.
/**
     * Low-level logging call.
     * @param priority The priority/type of this log message
     * @param tag Used to identify the source of a log message.  It usually identifies
     *        the class or activity where the log call occurs.
     * @param msg The message you would like logged.
     * @return The number of bytes written.
     */
    public static int println(int priority, String tag, String msg) {
        return println_native(LOG_ID_MAIN, priority, tag, msg);
    }

    
@hide
/** @hide */ public static final int LOG_ID_MAIN = 0;
    
@hide
/** @hide */ public static final int LOG_ID_RADIO = 1;
    
@hide
/** @hide */ public static final int LOG_ID_EVENTS = 2;
    
@hide
/** @hide */ public static final int LOG_ID_SYSTEM = 3;
    
@hide
/** @hide */ public static final int LOG_ID_CRASH = 4;

    
@hide
/** @hide */ public static native int println_native(int bufID,
            int priority, String tag, String msg);

    
Return the maximum payload the log daemon accepts without truncation.

Returns:LOGGER_ENTRY_MAX_PAYLOAD.
/**
     * Return the maximum payload the log daemon accepts without truncation.
     * @return LOGGER_ENTRY_MAX_PAYLOAD.
     */
    private static native int logger_entry_max_payload_native();

    
Helper function for long messages. Uses the LineBreakBufferedWriter to break
up long messages and stacktraces along newlines, but tries to write in large
chunks. This is to avoid truncation.

@hide
/**
     * Helper function for long messages. Uses the LineBreakBufferedWriter to break
     * up long messages and stacktraces along newlines, but tries to write in large
     * chunks. This is to avoid truncation.
     * @hide
     */
    public static int printlns(int bufID, int priority, String tag, String msg,
            Throwable tr) {
        ImmediateLogWriter logWriter = new ImmediateLogWriter(bufID, priority, tag);
        // Acceptable buffer size. Get the native buffer size, subtract two zero terminators,
        // and the length of the tag.
        // Note: we implicitly accept possible truncation for Modified-UTF8 differences. It
        //       is too expensive to compute that ahead of time.
        int bufferSize = PreloadHolder.LOGGER_ENTRY_MAX_PAYLOAD    // Base.
                - 2                                                // Two terminators.
                - (tag != null ? tag.length() : 0)                 // Tag length.
                - 32;                                              // Some slack.
        // At least assume you can print *some* characters (tag is not too large).
        bufferSize = Math.max(bufferSize, 100);

        LineBreakBufferedWriter lbbw = new LineBreakBufferedWriter(logWriter, bufferSize);

        lbbw.println(msg);

        if (tr != null) {
            // This is to reduce the amount of log spew that apps do in the non-error
            // condition of the network being unavailable.
            Throwable t = tr;
            while (t != null) {
                if (t instanceof UnknownHostException) {
                    break;
                }
                if (t instanceof DeadSystemException) {
                    lbbw.println("DeadSystemException: The system died; "
                            + "earlier logs will point to the root cause");
                    break;
                }
                t = t.getCause();
            }
            if (t == null) {
                tr.printStackTrace(lbbw);
            }
        }

        lbbw.flush();

        return logWriter.getWritten();
    }

    
PreloadHelper class. Caches the LOGGER_ENTRY_MAX_PAYLOAD value to avoid
a JNI call during logging.

/**
     * PreloadHelper class. Caches the LOGGER_ENTRY_MAX_PAYLOAD value to avoid
     * a JNI call during logging.
     */
    static class PreloadHolder {
        public final static int LOGGER_ENTRY_MAX_PAYLOAD =
                logger_entry_max_payload_native();
    }

    
Helper class to write to the logcat. Different from LogWriter, this writes
the whole given buffer and does not break along newlines.

/**
     * Helper class to write to the logcat. Different from LogWriter, this writes
     * the whole given buffer and does not break along newlines.
     */
    private static class ImmediateLogWriter extends Writer {

        private int bufID;
        private int priority;
        private String tag;

        private int written = 0;

        
Create a writer that immediately writes to the log, using the given
parameters.

/**
         * Create a writer that immediately writes to the log, using the given
         * parameters.
         */
        public ImmediateLogWriter(int bufID, int priority, String tag) {
            this.bufID = bufID;
            this.priority = priority;
            this.tag = tag;
        }

        public int getWritten() {
            return written;
        }

        @Override
        public void write(char[] cbuf, int off, int len) {
            // Note: using String here has a bit of overhead as a Java object is created,
            //       but using the char[] directly is not easier, as it needs to be translated
            //       to a C char[] for logging.
            written += println_native(bufID, priority, tag, new String(cbuf, off, len));
        }

        @Override
        public void flush() {
            // Ignored.
        }

        @Override
        public void close() {
            // Ignored.
        }
    }
}