Package com.azure.core.util.logging

Class ClientLogger

java.lang.Object

com.azure.core.util.logging.ClientLogger

public class ClientLogger
extends Object

This is a fluent logger helper class that wraps a pluggable Logger.

This logger logs format-able messages that use {} as the placeholder. When a throwable is the last argument of the format varargs and the logger is enabled for verbose, the stack trace for the throwable is logged.

A minimum logging level threshold is determined by the AZURE_LOG_LEVEL environment configuration. By default logging is disabled.

Log level hierarchy

1. Error
2. Warning
3. Info
4. Verbose

The logger is capable of producing json-formatted messages enriched with key value pairs. Context can be provided in the constructor and populated on every message or added per each log record.

See Also:

• Configuration

Constructor Summary

Constructors

Constructor	Description
ClientLogger(Class<?> clazz)	Retrieves a logger for the passed class using the LoggerFactory.
ClientLogger(Class<?> clazz, Map<String,Object> context)	Retrieves a logger for the passed class using the LoggerFactory.
ClientLogger(String className)	Retrieves a logger for the passed class name using the LoggerFactory.
ClientLogger(String className, Map<String,Object> context)	Retrieves a logger for the passed class name using the LoggerFactory with context that will be populated on all log records produced with this logger.

Method Summary

Modifier and Type	Method	Description
LoggingEventBuilder	atError()	Creates LoggingEventBuilder for error log level that can be used to enrich log with additional context.
LoggingEventBuilder	atInfo()	Creates LoggingEventBuilder for info log level that can be used to enrich log with additional context.
LoggingEventBuilder	atLevel(LogLevel level)	Creates LoggingEventBuilder for log level that can be used to enrich log with additional context.
LoggingEventBuilder	atVerbose()	Creates LoggingEventBuilder for verbose log level that can be used to enrich log with additional context.
LoggingEventBuilder	atWarning()	Creates LoggingEventBuilder for warning log level that can be used to enrich log with additional context.
boolean	canLogAtLevel(LogLevel logLevel)	Determines if the app or environment logger support logging at the given log level.
void	error(String message)	Logs a message at error log level.
void	error(String format, Object... args)	Logs a format-able message that uses {} as the placeholder at error log level.
void	info(String message)	Logs a message at info log level.
void	info(String format, Object... args)	Logs a format-able message that uses {} as the placeholder at informational log level.
void	log(LogLevel logLevel, Supplier<String> message)	Logs a format-able message that uses {} as the placeholder at the given logLevel.
void	log(LogLevel logLevel, Supplier<String> message, Throwable throwable)	Logs a format-able message that uses {} as the placeholder at verbose log level.
RuntimeException	logExceptionAsError(RuntimeException runtimeException)	Logs the RuntimeException at the error level and returns it to be thrown.
RuntimeException	logExceptionAsWarning(RuntimeException runtimeException)	Logs the RuntimeException at the warning level and returns it to be thrown.
<T extends Throwable> T	logThowableAsWarning(T throwable)	Deprecated. Use logThrowableAsWarning(Throwable) instead.
<T extends Throwable> T	logThrowableAsError(T throwable)	Logs the Throwable at the error level and returns it to be thrown.
<T extends Throwable> T	logThrowableAsWarning(T throwable)	Logs the Throwable at the warning level and returns it to be thrown.
void	verbose(String message)	Logs a message at verbose log level.
void	verbose(String format, Object... args)	Logs a format-able message that uses {} as the placeholder at verbose log level.
void	warning(String message)	Logs a message at warning log level.
void	warning(String format, Object... args)	Logs a format-able message that uses {} as the placeholder at warning log level.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ClientLogger

public ClientLogger(Class<?> clazz)

Retrieves a logger for the passed class using the LoggerFactory.

Parameters:

clazz - Class creating the logger.

ClientLogger

public ClientLogger(String className)

Retrieves a logger for the passed class name using the LoggerFactory.

Parameters:

className - Class name creating the logger.

Throws:

RuntimeException - when logging configuration is invalid depending on SLF4J implementation.

ClientLogger

public ClientLogger(Class<?> clazz,
 Map<String,Object> context)

Retrieves a logger for the passed class using the LoggerFactory.

Parameters:

clazz - Class creating the logger.

context - Context to be populated on every log record written with this logger. Objects are serialized with toString() method.

Throws:

NullPointerException - If clazz is null.

ClientLogger

public ClientLogger(String className,
 Map<String,Object> context)

Retrieves a logger for the passed class name using the LoggerFactory with context that will be populated on all log records produced with this logger.

 Map<String, Object> context = new HashMap<>();
 context.put("connectionId", "95a47cf");

 ClientLogger loggerWithContext = new ClientLogger(ClientLoggerJavaDocCodeSnippets.class, context);
 loggerWithContext.info("A formattable message. Hello, {}", name);
 

Parameters:

className - Class name creating the logger.

context - Context to be populated on every log record written with this logger. Objects are serialized with toString() method.

Throws:

RuntimeException - when logging configuration is invalid depending on SLF4J implementation.

Method Details

log

public void log(LogLevel logLevel,
 Supplier<String> message)

Logs a format-able message that uses {} as the placeholder at the given logLevel.

Code samples

Logging with a specific log level

 logger.log(LogLevel.VERBOSE,
     () -> String.format("Param 1: %s, Param 2: %s, Param 3: %s", "param1", "param2", "param3"));
 

Parameters:

logLevel - Logging level for the log message.

message - The format-able message to log.

log

public void log(LogLevel logLevel,
 Supplier<String> message,
 Throwable throwable)

Logs a format-able message that uses {} as the placeholder at verbose log level.

Code samples

Logging with a specific log level and exception

 Throwable illegalArgumentException = new IllegalArgumentException("An invalid argument was encountered.");
 logger.log(LogLevel.VERBOSE,
     () -> String.format("Param 1: %s, Param 2: %s, Param 3: %s", "param1", "param2", "param3"),
     illegalArgumentException);
 

Parameters:

logLevel - Logging level for the log message.

message - The format-able message to log.

throwable - Throwable for the message. Throwable.

verbose

public void verbose(String message)

Logs a message at verbose log level.

Code samples

Logging a message at verbose log level.

 logger.verbose("A log message");
 

Parameters:

message - The message to log.

verbose

public void verbose(String format,
 Object... args)

Logs a format-able message that uses {} as the placeholder at verbose log level.

Code samples

Logging a message at verbose log level.

 logger.verbose("A formattable message. Hello, {}", name);
 

Parameters:

format - The formattable message to log.

args - Arguments for the message. If an exception is being logged, the last argument should be the Throwable.

info

public void info(String message)

Logs a message at info log level.

Code samples

Logging a message at verbose log level.

 logger.info("A log message");
 

Parameters:

message - The message to log.

info

public void info(String format,
 Object... args)

Logs a format-able message that uses {} as the placeholder at informational log level.

Code samples

Logging a message at informational log level.

 logger.info("A formattable message. Hello, {}", name);
 

Parameters:

format - The format-able message to log

args - Arguments for the message. If an exception is being logged, the last argument should be the Throwable.

warning

public void warning(String message)

Logs a message at warning log level.

Code samples

Logging a message at warning log level.

 Throwable detailedException = new IllegalArgumentException("A exception with a detailed message");
 logger.warning(detailedException.getMessage());
 

Parameters:

message - The message to log.

warning

public void warning(String format,
 Object... args)

Logs a format-able message that uses {} as the placeholder at warning log level.

Code samples

Logging a message at warning log level.

 Throwable exception = new IllegalArgumentException("An invalid argument was encountered.");
 logger.warning("A formattable message. Hello, {}", name, exception);
 

Parameters:

format - The format-able message to log.

args - Arguments for the message. If an exception is being logged, the last argument should be the Throwable.

error

public void error(String message)

Logs a message at error log level.

Code samples

Logging a message at error log level.

 try {
     upload(resource);
 } catch (IOException ex) {
     logger.error(ex.getMessage());
 }
 

Parameters:

message - The message to log.

error

public void error(String format,
 Object... args)

Logs a format-able message that uses {} as the placeholder at error log level.

Code samples

Logging an error with stack trace.

 try {
     upload(resource);
 } catch (IOException ex) {
     logger.error("A formattable message. Hello, {}", name, ex);
 }
 

Parameters:

format - The format-able message to log.

args - Arguments for the message. If an exception is being logged, the last argument should be the Throwable.

logExceptionAsWarning

public RuntimeException logExceptionAsWarning(RuntimeException runtimeException)

Logs the RuntimeException at the warning level and returns it to be thrown.

This API covers the cases where a runtime exception type needs to be thrown and logged. If a Throwable is being logged use logThrowableAsWarning(Throwable) instead.

Parameters:

runtimeException - RuntimeException to be logged and returned.

Returns:

The passed RuntimeException.

Throws:

NullPointerException - If runtimeException is null.

logThowableAsWarning

@Deprecated
public <T extends Throwable> T logThowableAsWarning(T throwable)

Deprecated.

Use logThrowableAsWarning(Throwable) instead.

Logs the Throwable at the warning level and returns it to be thrown.

This API covers the cases where a checked exception type needs to be thrown and logged. If a RuntimeException is being logged use logExceptionAsWarning(RuntimeException) instead.

Type Parameters:

T - Type of the Throwable being logged.

Parameters:

throwable - Throwable to be logged and returned.

Returns:

The passed Throwable.

Throws:

NullPointerException - If throwable is null.

logThrowableAsWarning

public <T extends Throwable> T logThrowableAsWarning(T throwable)

Logs the Throwable at the warning level and returns it to be thrown.

This API covers the cases where a checked exception type needs to be thrown and logged. If a RuntimeException is being logged use logExceptionAsWarning(RuntimeException) instead.

Type Parameters:

T - Type of the Throwable being logged.

Parameters:

throwable - Throwable to be logged and returned.

Returns:

The passed Throwable.

Throws:

NullPointerException - If throwable is null.

logExceptionAsError

public RuntimeException logExceptionAsError(RuntimeException runtimeException)

Logs the RuntimeException at the error level and returns it to be thrown.

This API covers the cases where a runtime exception type needs to be thrown and logged. If a Throwable is being logged use logThrowableAsError(Throwable) instead.

Parameters:

runtimeException - RuntimeException to be logged and returned.

Returns:

The passed RuntimeException.

Throws:

NullPointerException - If runtimeException is null.

logThrowableAsError

public <T extends Throwable> T logThrowableAsError(T throwable)

Logs the Throwable at the error level and returns it to be thrown.

This API covers the cases where a checked exception type needs to be thrown and logged. If a RuntimeException is being logged use logExceptionAsError(RuntimeException) instead.

Type Parameters:

T - Type of the Throwable being logged.

Parameters:

throwable - Throwable to be logged and returned.

Returns:

The passed Throwable.

Throws:

NullPointerException - If throwable is null.

canLogAtLevel

public boolean canLogAtLevel(LogLevel logLevel)

Determines if the app or environment logger support logging at the given log level.

Parameters:

logLevel - Logging level for the log message.

Returns:

Flag indicating if the environment and logger are configured to support logging at the given log level.

atError

public LoggingEventBuilder atError()

Creates LoggingEventBuilder for error log level that can be used to enrich log with additional context.

Code samples

Logging with context at error level.

 logger.atVerbose()
     .addKeyValue("key", 1L)
     .log(() -> String.format("Param 1: %s, Param 2: %s, Param 3: %s", "param1", "param2", "param3"));
 

Returns:

instance of LoggingEventBuilder or no-op if error logging is disabled.

atWarning

public LoggingEventBuilder atWarning()

Creates LoggingEventBuilder for warning log level that can be used to enrich log with additional context.

Code samples

Logging with context at warning level.

 logger.atWarning()
     .addKeyValue("key", "value")
     .log("A formattable message. Hello, {}", name, exception);
 

Returns:

instance of LoggingEventBuilder or no-op if warn logging is disabled.

atInfo

public LoggingEventBuilder atInfo()

Creates LoggingEventBuilder for info log level that can be used to enrich log with additional context.

Code samples

Logging with context at info level.

 logger.atInfo()
     .addKeyValue("key", "value")
     .log("A formattable message. Hello, {}", name);
 

Returns:

instance of LoggingEventBuilder or no-op if info logging is disabled.

atVerbose

public LoggingEventBuilder atVerbose()

Creates LoggingEventBuilder for verbose log level that can be used to enrich log with additional context.

Code samples

Logging with context at verbose level.

 logger.atVerbose()
     .addKeyValue("key", 1L)
     .log(() -> String.format("Param 1: %s, Param 2: %s, Param 3: %s", "param1", "param2", "param3"));
 

Returns:

instance of LoggingEventBuilder or no-op if verbose logging is disabled.

atLevel

public LoggingEventBuilder atLevel(LogLevel level)

Creates LoggingEventBuilder for log level that can be used to enrich log with additional context.

Code samples

Logging with context at provided level.

 LogLevel level = response.getStatusCode() == 200 ? LogLevel.INFORMATIONAL : LogLevel.WARNING;
 logger.atLevel(level)
     .addKeyValue("key", "value")
     .log("message");
 

Parameters:

level - log level.

Returns:

instance of LoggingEventBuilder or no-op if logging at provided level is disabled.