001/* 002 * SonarQube 003 * Copyright (C) 2009-2018 SonarSource SA 004 * mailto:info AT sonarsource DOT com 005 * 006 * This program is free software; you can redistribute it and/or 007 * modify it under the terms of the GNU Lesser General Public 008 * License as published by the Free Software Foundation; either 009 * version 3 of the License, or (at your option) any later version. 010 * 011 * This program is distributed in the hope that it will be useful, 012 * but WITHOUT ANY WARRANTY; without even the implied warranty of 013 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 * Lesser General Public License for more details. 015 * 016 * You should have received a copy of the GNU Lesser General Public License 017 * along with this program; if not, write to the Free Software Foundation, 018 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. 019 */ 020package org.sonar.api.utils.log; 021 022import java.util.function.Supplier; 023import javax.annotation.Nullable; 024 025/** 026 * SonarQube plugins are not coupled with external logging libraries like SLF4J or Logback. 027 * <p> 028 * Example: 029 * <pre> 030 * public class MyClass { 031 * private static final Logger LOGGER = Loggers.get("logger_name"); 032 * 033 * public void doSomething() { 034 * LOGGER.info("something valuable for production environment"); 035 * LOGGER.warn("message with arguments {} and {}", "foo", 42); 036 * } 037 * } 038 * </pre> 039 * <p> 040 * Message arguments are defined with <code>{}</code>, but not with {@link java.util.Formatter} syntax. 041 * 042 * <p> 043 * INFO, WARN and ERROR levels are always enabled. They can't be disabled by users. 044 * DEBUG and TRACE levels are enabled on demand with the property <code>sonar.log.level</code>. 045 * <p> 046 * See {@link org.sonar.api.utils.log.LogTester} for testing facilities. 047 * @since 5.1 048 */ 049public interface Logger { 050 051 boolean isTraceEnabled(); 052 053 /** 054 * Logs a TRACE message. 055 * <p> 056 * TRACE messages must 057 * be valuable for diagnosing production problems. They must not be used for development debugging. 058 * They can significantly slow down performances. The standard use-case is logging of 059 * SQL and Elasticsearch requests. 060 */ 061 void trace(String msg); 062 063 /** 064 * Logs a TRACE message, which is only to be constructed if the logging level 065 * is such that the message will actually be logged. 066 * <p> 067 * TRACE messages must 068 * be valuable for diagnosing production problems. They must not be used for development debugging. 069 * They can significantly slow down performances. The standard use-case is logging of 070 * SQL and Elasticsearch requests. 071 * @param msgSupplier A function, which when called, produces the desired log message 072 * @since 6.3 073 */ 074 default void trace(Supplier<String> msgSupplier) { 075 if (isTraceEnabled()) { 076 trace(msgSupplier.get()); 077 } 078 } 079 080 /** 081 * Logs an TRACE parameterized message according to the specified format and argument. Example: 082 * <code>trace("Value is {}", value)</code> 083 * <p> 084 * TRACE messages must 085 * be valuable for diagnosing production problems. They must not be used for development debugging. 086 * They can significantly slow down performances. The standard use-case is logging of 087 * SQL and Elasticsearch requests. 088 */ 089 void trace(String pattern, @Nullable Object arg); 090 091 /** 092 * Logs an TRACE parameterized message according to the specified format and arguments. Example: 093 * <code>trace("Values are {} and {}", value1, value2)</code> 094 * <p> 095 * TRACE messages must 096 * be valuable for diagnosing production problems. They must not be used for development debugging. 097 * They can significantly slow down performances. The standard use-case is logging of 098 * SQL and Elasticsearch requests. 099 */ 100 void trace(String msg, @Nullable Object arg1, @Nullable Object arg2); 101 102 /** 103 * Logs an TRACE parameterized message according to the specified format and arguments. Example: 104 * <code>trace("Values are {} and {}", value1, value2)</code> 105 * <p> 106 * TRACE messages must 107 * be valuable for diagnosing production problems. They must not be used for development debugging. 108 * They can significantly slow down performances. The standard use-case is logging of 109 * SQL and Elasticsearch requests. 110 * <p> 111 * This variant incurs the hidden cost of creating an Object[] before invoking the method. 112 * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See 113 * {@link #trace(String, Object)} and {@link #trace(String, Object, Object)} 114 */ 115 void trace(String msg, Object... args); 116 117 boolean isDebugEnabled(); 118 119 /** 120 * Logs a DEBUG message. 121 * <p> 122 * DEBUG messages must 123 * be valuable for diagnosing production problems. They must not be used for development debugging. 124 */ 125 void debug(String msg); 126 127 /** 128 * Logs a DEBUG message which is only to be constructed if the logging level 129 * is such that the message will actually be logged. 130 * <p> 131 * DEBUG messages must 132 * be valuable for diagnosing production problems. They must not be used for development debugging. 133 * @param msgSupplier A function, which when called, produces the desired log message 134 * @since 6.3 135 */ 136 default void debug(Supplier<String> msgSupplier) { 137 if (isDebugEnabled()) { 138 debug(msgSupplier.get()); 139 } 140 } 141 142 /** 143 * Logs an DEBUG parameterized message according to the specified format and argument. Example: 144 * <code>debug("Value is {}", value)</code> 145 * <p> 146 * Debug messages must 147 * be valuable for diagnosing production problems. They must not be used for development debugging. 148 */ 149 void debug(String pattern, @Nullable Object arg); 150 151 /** 152 * Logs an DEBUG parameterized message according to the specified format and arguments. Example: 153 * <code>debug("Values are {} and {}", value1, value2)</code> 154 * <p> 155 * Debug messages must 156 * be valuable for diagnosing production problems. They must not be used for development debugging. 157 */ 158 void debug(String msg, @Nullable Object arg1, @Nullable Object arg2); 159 160 /** 161 * Logs an DEBUG parameterized message according to the specified format and arguments. Example: 162 * <code>debug("Values are {}, {} and {}", value1, value2, value3)</code> 163 * <p> 164 * Debug messages must 165 * be valuable for diagnosing production problems. They must not be used for development debugging. 166 * * <p> 167 * This variant incurs the hidden cost of creating an Object[] before invoking the method. 168 * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See 169 * {@link #debug(String, Object)} and {@link #debug(String, Object, Object)} 170 */ 171 void debug(String msg, Object... args); 172 173 /** 174 * Logs an INFO level message. 175 */ 176 void info(String msg); 177 178 /** 179 * Logs an INFO parameterized message according to the specified format and argument. Example: 180 * <code>info("Value is {}", value)</code> 181 */ 182 void info(String msg, @Nullable Object arg); 183 184 /** 185 * Logs an INFO parameterized message according to the specified format and arguments. Example: 186 * <code>info("Values are {} and {}", value1, value2)</code> 187 */ 188 void info(String msg, @Nullable Object arg1, @Nullable Object arg2); 189 190 /** 191 * Logs an INFO parameterized message according to the specified format and arguments. Example: 192 * <code>info("Values are {}, {} and {}", value1, value2, value3)</code> 193 * <p> 194 * This variant incurs the hidden cost of creating an Object[] before invoking the method. 195 * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See 196 * {@link #info(String, Object)} and {@link #info(String, Object, Object)} 197 */ 198 void info(String msg, Object... args); 199 200 /** 201 * Logs a WARN level message. 202 */ 203 void warn(String msg); 204 205 /** 206 * Logs an exception at the WARN level with an accompanying message. 207 */ 208 void warn(String msg, Throwable throwable); 209 210 /** 211 * Logs a WARN parameterized message according to the specified format and argument. Example: 212 * <code>warn("Value is {}", value)</code> 213 */ 214 void warn(String msg, @Nullable Object arg); 215 216 /** 217 * Logs a WARN parameterized message according to the specified format and arguments. Example: 218 * <code>warn("Values are {} and {}", value1, value2)</code> 219 */ 220 void warn(String msg, @Nullable Object arg1, @Nullable Object arg2); 221 222 /** 223 * Logs a WARN parameterized message according to the specified format and arguments. Example: 224 * <code>warn("Values are {}, {} and {}", value1, value2, value3)</code> 225 * <p> 226 * This variant incurs the hidden cost of creating an Object[] before invoking the method. 227 * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See 228 * {@link #warn(String, Object)} and {@link #warn(String, Object, Object)} 229 */ 230 void warn(String msg, Object... args); 231 232 /** 233 * Logs an ERROR level message. 234 */ 235 void error(String msg); 236 237 /** 238 * Logs an ERROR parameterized message according to the specified format and argument. Example: 239 * <code>error("Value is {}", value)</code> 240 */ 241 void error(String msg, @Nullable Object arg); 242 243 /** 244 * Logs a ERROR parameterized message according to the specified format and arguments. Example: 245 * <code>error("Values are {} and {}", value1, value2)</code> 246 */ 247 void error(String msg, @Nullable Object arg1, @Nullable Object arg2); 248 249 /** 250 * Logs a ERROR parameterized message according to the specified format and arguments. Example: 251 * <code>error("Values are {}, {} and {}", value1, value2, value3)</code> 252 * <p> 253 * This variant incurs the hidden cost of creating an Object[] before invoking the method. 254 * The variants taking one and two arguments exist solely in order to avoid this hidden cost. See 255 * {@link #error(String, Object)} and {@link #error(String, Object, Object)} 256 */ 257 void error(String msg, Object... args); 258 259 /** 260 * Logs an exception at the ERROR level with an accompanying message. 261 */ 262 void error(String msg, Throwable thrown); 263 264 /** 265 * Attempt to change logger level. Return true if it succeeded, false if 266 * the underlying logging facility does not allow to change level at 267 * runtime. 268 * <p> 269 * This method must not be used to enable DEBUG or TRACE logs in tests. Use 270 * {@link org.sonar.api.utils.log.LogTester#setLevel(LoggerLevel)} instead. 271 * <p> 272 * The standard use-case is to customize logging of embedded 3rd-party 273 * libraries. 274 */ 275 boolean setLevel(LoggerLevel level); 276 277 LoggerLevel getLevel(); 278}