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