Loggers

+ +

A logger is a component which will take your logging request and log it. Each class in a project can + have an individual logger, or they can all use a common logger. Loggers are named entities; it is + common to name them after the class which will use it for logging.

+ +

Creating a logger is done by calling the static getLogger() method on the Logger object + and providing the name of the logger. For example, to create a logger named foo:

+ +

$logger = Logger::getLogger('foo');

+ +

Logging requests are made by invoking one of the printing methods of a Logger instance. These logging + methods are: trace, debug, info, warn, error and fatal. The printing method determines the level of a + logging request. For example, calling the method info() creates a logging request of level + INFO. For example:

+ +

$logger->info("This is the message to be logged.");

+ +

Loggers by themselves do not define where these messages will be logged. For that you need to assign + one or more appenders to the logger.

+ + +

A logger can be assigned a threshold level. All logging requests with level lower than this threshold + will be ignored.

+ +

For example, setting logger threshold to INFO means that logging requests with levels + TRACE and DEBUG will not be logged by this logger.

+ +

An example of setting the root logger threshold to DEBUG:

+ +


+    
+    
+        
+        
+    
+
+]]>

+ +

By default loggers do not have a threshold set, which means they will log all events, regardless of the + level.

+ + + +

Loggers can be individually configured in the configuration file.

+ +

The simplest example is to configure the root logger, since all other loggers will inherit its + settings, as explained in the next section.

+ +


+    
+    
+        
+        
+    
+
+]]>

This configuration adds the default appender to the root logger, and sets it's + threshold level to DEBUG.

+ +

It is also possible to configure individual named loggers. For example, let's configure the + foo logger, used in the example above, and set it's threshold to WARN:

+ +


+    
+    
+        
+        
+    
+
+]]>

+ + + +

Loggers follow a parent-child relationship pattern which is implemented by using a naming pattern. + A logger is said to be an ancestor of another logger if its name followed by a dot is a + prefix of the descendant logger name. A logger is said to be a parent of a + child logger if there are no ancestors between itself and the descendant logger.

+ +

For example, the logger named foo is a parent of the logger named foo.bar. + Similarly, org is a parent of org.apache and an ancestor of + org.apache.logging. This naming scheme should be familiar to most developers.

+ +

The root logger resides at the top of the logger hierarchy. It is exceptional in two ways:

it always exists,
it cannot be retrieved by name.

+ +

Invoking the class static Logger::getRootLogger() method retrieves the root logger. + All other loggers are instantiated and retrieved with the Logger::getLogger($name) + method. This method takes the name of the desired logger as a parameter. If the logger does not exist + at the time of the call, it will be created.

+ + + +

The threshold level and appenders are inherited from the parent to the child loggers.

+ +

For example examine the following configuration:

+ +


+    
+    
+        
+        
+    
+
+]]>

+ +

The threshold level of the root logger is set to debug. Also, the root logger is linked to a console + appender. Any named logger that is created will inherit these root settings.

+ +

trace('This will not be logged.');
+$main->info('This will be logged.');
+]]>

A logger named main is created. Since there is no logger-specific configuration, it + will inherit all of it's settings from the root logger: a console appender, and threshold set to DEBUG. + Therefore, this code will produce the following output:

+ +

INFO - This will be logged.

+ + + +

Appender additivity is a property of loggers to inherit their parent's appenders. By default all + loggers have appender additivity enabled.

+ +

Let's take the following example:

+ +


+    
+    
+    
+        
+    
+     
+        
+    
+
+]]>

Since additivity is enabled by default, the logger foo will have two linked appenders: + A1 which it will inherit from the root logger, and A2 which is defined for it specifically.

+ +

Therefore, by executing the following code:

+ +

info('This will be logged twice.');
+]]>

The message will be logged twice - once by A1 and once by A2, producing:

+ +

+INFO - This will be logged twice.
+INFO - This will be logged twice.
+

+ +

Disabling appender additivity

+ +

Logger's appender additivity can also be disabled if needed.

+ +

If the foo logger in the previous example was configured like this:

+ +

 
+    
+
+]]>

Then the logger would not have inherited the A1 appender from the root logger, and the message + would have been logged only once.

+ +

A more complex example

+ +

In this example we will look at multiple loggers making a hierarchy.

+ +

Not to make the example too complex, all appenders will log to the console. Of course, this doesn't + always have to be the case.

+ +

Let's take the following configuration file:

+ +

The table below shows how the configuration is interpreted, and which appenders are inherited:

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Logger name	Linked appenders	Additivity flag	Output targets	Comment
root	A1	N/A	A1	One appender, named A1, is added to root logger. Any logging requests to root logger + will be forwarded only to that one appender.
foo	A2, A3	true	A1, A2, A3	A logger named `foo` is created and two appenders, named A2 and A3, are + added to it. Additionally, because of logger additivity, `foo` inherits the + appender A1 from the root logger which is it's parent in the logger hierarchy. Therefore + logging requests to this logger will be forwarded to appenders A1, A2 and A3.
foo.bar	none	true	A1, A2, A3	A logger named `foo.bar` is created. Because it's name starts with + `foo`, it will be created as a child of the `foo` logger. + No appenders are added to `foo.bar` but it will inherit it's ancestor's + appenders: appenders A2 and A3 from `foo` and A1 from `root`. + Logging requests to this logger will be forwarded to appenders A1, A2 and A3.
foo.bar.baz	A4	false	A4	Finally, logger `foo.bar.baz` is created, and because of it's name it is + created as child to `foo.bar`. One appender, A4 is added to it. However, since + it's additivity flag is set to false, it will not inherit any appenders from it's + ancestors. Logging requests to this logger will be forwarded only to appender A4.

+ +