1 /* 2 * Copyright (C) 2006 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.util; 18 19 import com.android.internal.os.RuntimeInit; 20 21 import java.io.PrintWriter; 22 import java.io.StringWriter; 23 24 /** 25 * API for sending log output. 26 * 27 * <p>Generally, use the Log.v() Log.d() Log.i() Log.w() and Log.e() 28 * methods. 29 * 30 * <p>The order in terms of verbosity, from least to most is 31 * ERROR, WARN, INFO, DEBUG, VERBOSE. Verbose should never be compiled 32 * into an application except during development. Debug logs are compiled 33 * in but stripped at runtime. Error, warning and info logs are always kept. 34 * 35 * <p><b>Tip:</b> A good convention is to declare a <code>TAG</code> constant 36 * in your class: 37 * 38 * <pre>private static final String TAG = "MyActivity";</pre> 39 * 40 * and use that in subsequent calls to the log methods. 41 * </p> 42 * 43 * <p><b>Tip:</b> Don't forget that when you make a call like 44 * <pre>Log.v(TAG, "index=" + i);</pre> 45 * that when you're building the string to pass into Log.d, the compiler uses a 46 * StringBuilder and at least three allocations occur: the StringBuilder 47 * itself, the buffer, and the String object. Realistically, there is also 48 * another buffer allocation and copy, and even more pressure on the gc. 49 * That means that if your log message is filtered out, you might be doing 50 * significant work and incurring significant overhead. 51 */ 52 public final class Log { 53 54 /** 55 * Priority constant for the println method; use Log.v. 56 */ 57 public static final int VERBOSE = 2; 58 59 /** 60 * Priority constant for the println method; use Log.d. 61 */ 62 public static final int DEBUG = 3; 63 64 /** 65 * Priority constant for the println method; use Log.i. 66 */ 67 public static final int INFO = 4; 68 69 /** 70 * Priority constant for the println method; use Log.w. 71 */ 72 public static final int WARN = 5; 73 74 /** 75 * Priority constant for the println method; use Log.e. 76 */ 77 public static final int ERROR = 6; 78 79 /** 80 * Priority constant for the println method. 81 */ 82 public static final int ASSERT = 7; 83 Log()84 private Log() { 85 } 86 87 /** 88 * Send a {@link #VERBOSE} log message. 89 * @param tag Used to identify the source of a log message. It usually identifies 90 * the class or activity where the log call occurs. 91 * @param msg The message you would like logged. 92 */ v(String tag, String msg)93 public static int v(String tag, String msg) { 94 return println(VERBOSE, tag, msg); 95 } 96 97 /** 98 * Send a {@link #VERBOSE} log message and log the exception. 99 * @param tag Used to identify the source of a log message. It usually identifies 100 * the class or activity where the log call occurs. 101 * @param msg The message you would like logged. 102 * @param tr An exception to log 103 */ v(String tag, String msg, Throwable tr)104 public static int v(String tag, String msg, Throwable tr) { 105 return println(VERBOSE, tag, msg + '\n' + getStackTraceString(tr)); 106 } 107 108 /** 109 * Send a {@link #DEBUG} log message. 110 * @param tag Used to identify the source of a log message. It usually identifies 111 * the class or activity where the log call occurs. 112 * @param msg The message you would like logged. 113 */ d(String tag, String msg)114 public static int d(String tag, String msg) { 115 return println(DEBUG, tag, msg); 116 } 117 118 /** 119 * Send a {@link #DEBUG} log message and log the exception. 120 * @param tag Used to identify the source of a log message. It usually identifies 121 * the class or activity where the log call occurs. 122 * @param msg The message you would like logged. 123 * @param tr An exception to log 124 */ d(String tag, String msg, Throwable tr)125 public static int d(String tag, String msg, Throwable tr) { 126 return println(DEBUG, tag, msg + '\n' + getStackTraceString(tr)); 127 } 128 129 /** 130 * Send an {@link #INFO} log message. 131 * @param tag Used to identify the source of a log message. It usually identifies 132 * the class or activity where the log call occurs. 133 * @param msg The message you would like logged. 134 */ i(String tag, String msg)135 public static int i(String tag, String msg) { 136 return println(INFO, tag, msg); 137 } 138 139 /** 140 * Send a {@link #INFO} log message and log the exception. 141 * @param tag Used to identify the source of a log message. It usually identifies 142 * the class or activity where the log call occurs. 143 * @param msg The message you would like logged. 144 * @param tr An exception to log 145 */ i(String tag, String msg, Throwable tr)146 public static int i(String tag, String msg, Throwable tr) { 147 return println(INFO, tag, msg + '\n' + getStackTraceString(tr)); 148 } 149 150 /** 151 * Send a {@link #WARN} log message. 152 * @param tag Used to identify the source of a log message. It usually identifies 153 * the class or activity where the log call occurs. 154 * @param msg The message you would like logged. 155 */ w(String tag, String msg)156 public static int w(String tag, String msg) { 157 return println(WARN, tag, msg); 158 } 159 160 /** 161 * Send a {@link #WARN} log message and log the exception. 162 * @param tag Used to identify the source of a log message. It usually identifies 163 * the class or activity where the log call occurs. 164 * @param msg The message you would like logged. 165 * @param tr An exception to log 166 */ w(String tag, String msg, Throwable tr)167 public static int w(String tag, String msg, Throwable tr) { 168 return println(WARN, tag, msg + '\n' + getStackTraceString(tr)); 169 } 170 171 /** 172 * Checks to see whether or not a log for the specified tag is loggable at the specified level. 173 * 174 * The default level of any tag is set to INFO. This means that any level above and including 175 * INFO will be logged. Before you make any calls to a logging method you should check to see 176 * if your tag should be logged. You can change the default level by setting a system property: 177 * 'setprop log.tag.<YOUR_LOG_TAG> <LEVEL>' 178 * Where level is either VERBOSE, DEBUG, INFO, WARN, ERROR, ASSERT, or SUPPRESS. SUPRESS will 179 * turn off all logging for your tag. You can also create a local.prop file that with the 180 * following in it: 181 * 'log.tag.<YOUR_LOG_TAG>=<LEVEL>' 182 * and place that in /data/local.prop. 183 * 184 * @param tag The tag to check. 185 * @param level The level to check. 186 * @return Whether or not that this is allowed to be logged. 187 * @throws IllegalArgumentException is thrown if the tag.length() > 23. 188 */ isLoggable(String tag, int level)189 public static native boolean isLoggable(String tag, int level); 190 191 /* 192 * Send a {@link #WARN} log message and log the exception. 193 * @param tag Used to identify the source of a log message. It usually identifies 194 * the class or activity where the log call occurs. 195 * @param tr An exception to log 196 */ w(String tag, Throwable tr)197 public static int w(String tag, Throwable tr) { 198 return println(WARN, tag, getStackTraceString(tr)); 199 } 200 201 /** 202 * Send an {@link #ERROR} log message. 203 * @param tag Used to identify the source of a log message. It usually identifies 204 * the class or activity where the log call occurs. 205 * @param msg The message you would like logged. 206 */ e(String tag, String msg)207 public static int e(String tag, String msg) { 208 return println(ERROR, tag, msg); 209 } 210 211 /** 212 * Send a {@link #ERROR} log message and log the exception. 213 * @param tag Used to identify the source of a log message. It usually identifies 214 * the class or activity where the log call occurs. 215 * @param msg The message you would like logged. 216 * @param tr An exception to log 217 */ e(String tag, String msg, Throwable tr)218 public static int e(String tag, String msg, Throwable tr) { 219 int r = println(ERROR, tag, msg + '\n' + getStackTraceString(tr)); 220 RuntimeInit.reportException(tag, tr, false); // asynchronous 221 return r; 222 } 223 224 /** 225 * Handy function to get a loggable stack trace from a Throwable 226 * @param tr An exception to log 227 */ getStackTraceString(Throwable tr)228 public static String getStackTraceString(Throwable tr) { 229 if (tr == null) { 230 return ""; 231 } 232 StringWriter sw = new StringWriter(); 233 PrintWriter pw = new PrintWriter(sw); 234 tr.printStackTrace(pw); 235 return sw.toString(); 236 } 237 238 /** 239 * Low-level logging call. 240 * @param priority The priority/type of this log message 241 * @param tag Used to identify the source of a log message. It usually identifies 242 * the class or activity where the log call occurs. 243 * @param msg The message you would like logged. 244 * @return The number of bytes written. 245 */ println(int priority, String tag, String msg)246 public static native int println(int priority, String tag, String msg); 247 } 248