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 84 /** 85 * Exception class used to capture a stack trace in {@link #wtf()}. 86 */ 87 private static class TerribleFailure extends Exception { TerribleFailure(String msg, Throwable cause)88 TerribleFailure(String msg, Throwable cause) { super(msg, cause); } 89 } 90 91 /** 92 * Interface to handle terrible failures from {@link #wtf()}. 93 * 94 * @hide 95 */ 96 public interface TerribleFailureHandler { onTerribleFailure(String tag, TerribleFailure what)97 void onTerribleFailure(String tag, TerribleFailure what); 98 } 99 100 private static TerribleFailureHandler sWtfHandler = new TerribleFailureHandler() { 101 public void onTerribleFailure(String tag, TerribleFailure what) { 102 RuntimeInit.wtf(tag, what); 103 } 104 }; 105 Log()106 private Log() { 107 } 108 109 /** 110 * Send a {@link #VERBOSE} log message. 111 * @param tag Used to identify the source of a log message. It usually identifies 112 * the class or activity where the log call occurs. 113 * @param msg The message you would like logged. 114 */ v(String tag, String msg)115 public static int v(String tag, String msg) { 116 return println_native(LOG_ID_MAIN, VERBOSE, tag, msg); 117 } 118 119 /** 120 * Send a {@link #VERBOSE} log message and log the exception. 121 * @param tag Used to identify the source of a log message. It usually identifies 122 * the class or activity where the log call occurs. 123 * @param msg The message you would like logged. 124 * @param tr An exception to log 125 */ v(String tag, String msg, Throwable tr)126 public static int v(String tag, String msg, Throwable tr) { 127 return println_native(LOG_ID_MAIN, VERBOSE, tag, msg + '\n' + getStackTraceString(tr)); 128 } 129 130 /** 131 * Send a {@link #DEBUG} log message. 132 * @param tag Used to identify the source of a log message. It usually identifies 133 * the class or activity where the log call occurs. 134 * @param msg The message you would like logged. 135 */ d(String tag, String msg)136 public static int d(String tag, String msg) { 137 return println_native(LOG_ID_MAIN, DEBUG, tag, msg); 138 } 139 140 /** 141 * Send a {@link #DEBUG} log message and log the exception. 142 * @param tag Used to identify the source of a log message. It usually identifies 143 * the class or activity where the log call occurs. 144 * @param msg The message you would like logged. 145 * @param tr An exception to log 146 */ d(String tag, String msg, Throwable tr)147 public static int d(String tag, String msg, Throwable tr) { 148 return println_native(LOG_ID_MAIN, DEBUG, tag, msg + '\n' + getStackTraceString(tr)); 149 } 150 151 /** 152 * Send an {@link #INFO} log message. 153 * @param tag Used to identify the source of a log message. It usually identifies 154 * the class or activity where the log call occurs. 155 * @param msg The message you would like logged. 156 */ i(String tag, String msg)157 public static int i(String tag, String msg) { 158 return println_native(LOG_ID_MAIN, INFO, tag, msg); 159 } 160 161 /** 162 * Send a {@link #INFO} log message and log the exception. 163 * @param tag Used to identify the source of a log message. It usually identifies 164 * the class or activity where the log call occurs. 165 * @param msg The message you would like logged. 166 * @param tr An exception to log 167 */ i(String tag, String msg, Throwable tr)168 public static int i(String tag, String msg, Throwable tr) { 169 return println_native(LOG_ID_MAIN, INFO, tag, msg + '\n' + getStackTraceString(tr)); 170 } 171 172 /** 173 * Send a {@link #WARN} log message. 174 * @param tag Used to identify the source of a log message. It usually identifies 175 * the class or activity where the log call occurs. 176 * @param msg The message you would like logged. 177 */ w(String tag, String msg)178 public static int w(String tag, String msg) { 179 return println_native(LOG_ID_MAIN, WARN, tag, msg); 180 } 181 182 /** 183 * Send a {@link #WARN} log message and log the exception. 184 * @param tag Used to identify the source of a log message. It usually identifies 185 * the class or activity where the log call occurs. 186 * @param msg The message you would like logged. 187 * @param tr An exception to log 188 */ w(String tag, String msg, Throwable tr)189 public static int w(String tag, String msg, Throwable tr) { 190 return println_native(LOG_ID_MAIN, WARN, tag, msg + '\n' + getStackTraceString(tr)); 191 } 192 193 /** 194 * Checks to see whether or not a log for the specified tag is loggable at the specified level. 195 * 196 * The default level of any tag is set to INFO. This means that any level above and including 197 * INFO will be logged. Before you make any calls to a logging method you should check to see 198 * if your tag should be logged. You can change the default level by setting a system property: 199 * 'setprop log.tag.<YOUR_LOG_TAG> <LEVEL>' 200 * Where level is either VERBOSE, DEBUG, INFO, WARN, ERROR, ASSERT, or SUPPRESS. SUPPRESS will 201 * turn off all logging for your tag. You can also create a local.prop file that with the 202 * following in it: 203 * 'log.tag.<YOUR_LOG_TAG>=<LEVEL>' 204 * and place that in /data/local.prop. 205 * 206 * @param tag The tag to check. 207 * @param level The level to check. 208 * @return Whether or not that this is allowed to be logged. 209 * @throws IllegalArgumentException is thrown if the tag.length() > 23. 210 */ isLoggable(String tag, int level)211 public static native boolean isLoggable(String tag, int level); 212 213 /* 214 * Send a {@link #WARN} log message and log the exception. 215 * @param tag Used to identify the source of a log message. It usually identifies 216 * the class or activity where the log call occurs. 217 * @param tr An exception to log 218 */ w(String tag, Throwable tr)219 public static int w(String tag, Throwable tr) { 220 return println_native(LOG_ID_MAIN, WARN, tag, getStackTraceString(tr)); 221 } 222 223 /** 224 * Send an {@link #ERROR} log message. 225 * @param tag Used to identify the source of a log message. It usually identifies 226 * the class or activity where the log call occurs. 227 * @param msg The message you would like logged. 228 */ e(String tag, String msg)229 public static int e(String tag, String msg) { 230 return println_native(LOG_ID_MAIN, ERROR, tag, msg); 231 } 232 233 /** 234 * Send a {@link #ERROR} log message and log the exception. 235 * @param tag Used to identify the source of a log message. It usually identifies 236 * the class or activity where the log call occurs. 237 * @param msg The message you would like logged. 238 * @param tr An exception to log 239 */ e(String tag, String msg, Throwable tr)240 public static int e(String tag, String msg, Throwable tr) { 241 return println_native(LOG_ID_MAIN, ERROR, tag, msg + '\n' + getStackTraceString(tr)); 242 } 243 244 /** 245 * What a Terrible Failure: Report a condition that should never happen. 246 * The error will always be logged at level ASSERT with the call stack. 247 * Depending on system configuration, a report may be added to the 248 * {@link android.os.DropBoxManager} and/or the process may be terminated 249 * immediately with an error dialog. 250 * @param tag Used to identify the source of a log message. 251 * @param msg The message you would like logged. 252 */ wtf(String tag, String msg)253 public static int wtf(String tag, String msg) { 254 return wtf(tag, msg, null); 255 } 256 257 /** 258 * What a Terrible Failure: Report an exception that should never happen. 259 * Similar to {@link #wtf(String, String)}, with an exception to log. 260 * @param tag Used to identify the source of a log message. 261 * @param tr An exception to log. 262 */ wtf(String tag, Throwable tr)263 public static int wtf(String tag, Throwable tr) { 264 return wtf(tag, tr.getMessage(), tr); 265 } 266 267 /** 268 * What a Terrible Failure: Report an exception that should never happen. 269 * Similar to {@link #wtf(String, Throwable)}, with a message as well. 270 * @param tag Used to identify the source of a log message. 271 * @param msg The message you would like logged. 272 * @param tr An exception to log. May be null. 273 */ wtf(String tag, String msg, Throwable tr)274 public static int wtf(String tag, String msg, Throwable tr) { 275 TerribleFailure what = new TerribleFailure(msg, tr); 276 int bytes = println_native(LOG_ID_MAIN, ASSERT, tag, getStackTraceString(tr)); 277 sWtfHandler.onTerribleFailure(tag, what); 278 return bytes; 279 } 280 281 /** 282 * Sets the terrible failure handler, for testing. 283 * 284 * @return the old handler 285 * 286 * @hide 287 */ setWtfHandler(TerribleFailureHandler handler)288 public static TerribleFailureHandler setWtfHandler(TerribleFailureHandler handler) { 289 if (handler == null) { 290 throw new NullPointerException("handler == null"); 291 } 292 TerribleFailureHandler oldHandler = sWtfHandler; 293 sWtfHandler = handler; 294 return oldHandler; 295 } 296 297 /** 298 * Handy function to get a loggable stack trace from a Throwable 299 * @param tr An exception to log 300 */ getStackTraceString(Throwable tr)301 public static String getStackTraceString(Throwable tr) { 302 if (tr == null) { 303 return ""; 304 } 305 StringWriter sw = new StringWriter(); 306 PrintWriter pw = new PrintWriter(sw); 307 tr.printStackTrace(pw); 308 return sw.toString(); 309 } 310 311 /** 312 * Low-level logging call. 313 * @param priority The priority/type of this log message 314 * @param tag Used to identify the source of a log message. It usually identifies 315 * the class or activity where the log call occurs. 316 * @param msg The message you would like logged. 317 * @return The number of bytes written. 318 */ println(int priority, String tag, String msg)319 public static int println(int priority, String tag, String msg) { 320 return println_native(LOG_ID_MAIN, priority, tag, msg); 321 } 322 323 /** @hide */ public static final int LOG_ID_MAIN = 0; 324 /** @hide */ public static final int LOG_ID_RADIO = 1; 325 /** @hide */ public static final int LOG_ID_EVENTS = 2; 326 /** @hide */ public static final int LOG_ID_SYSTEM = 3; 327 println_native(int bufID, int priority, String tag, String msg)328 /** @hide */ public static native int println_native(int bufID, 329 int priority, String tag, String msg); 330 } 331