README.md 7.02 KB
Newer Older
1
Monolog for Drupal 8
2
====================
3
4

Overview
5
--------
6
7
8
This module integrates Drupal with the fantastic [Monolog library by Seldaek](https://github.com/Seldaek/monolog) to provide a better logging solution. Some of the benefits of using this module are as follows:

- Configurable logging levels
9
- A multitude of handlers, formatters and processors
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
- All the power and flexibility of Monolog

The Drupal Monolog module also has full watchdog integration, so it works with core and contributed modules out of the box.

Monolog sends your logs to files, sockets, inboxes, databases and various web services.
This module is a thin wrapper to integrate the Monolog library with the Drupal logging
system. For more information on how the Monolog library itself works, take a look to the
[documentation](https://github.com/Seldaek/monolog/blob/master/doc/01-usage.md).


Install
-------
The Monolog module needs to be installed via Composer, which will also download the required library.
Look at [Using Composer with Drupal](https://www.drupal.org/node/2404989) for further information.


Quick start
===========

Monolog module does not have an UI, all the configuration is done in services files.

You should create a site specific services.yml (monolog.services.yml for example) in the same
folder of your settings.php and then add this line to settings.php itself:

```
$settings['container_yamls'][] = 'sites/default/monolog.services.yml';
```

The simplest configuration that allows Monolog to log to a rotating file might be:

```
parameters:
  monolog.channel_handlers:
    default: ['rotating_file']

services:
  monolog.handler.rotating_file:
    class: Monolog\Handler\RotatingFileHandler
48
    arguments: ['private://logs/debug.log', 10, '%monolog.level.debug%']
49
50
51
52
53
54
55
56
57
58
59
60
61
62
```

This configuration will log every message with a log level greater (or equal) than *debug* to a file called
*debug.log* located into the *logs* folder in your private filesystem.
Files will be rotated every day and the maximum number of files to keep will be *10*.

How it works
============

Handlers
--------

Handlers are registered as services in the [Drupal Service Container](https://www.drupal.org/docs/8/api/services-and-dependency-injection/services-and-dependency-injection-in-drupal-8).
You can define as many handlers as you need.
63
Each handler has a name (that must be under the *monolog.handler.* namespace), an implementing class and a list of arguments.
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

Mapping among logger channels and Monolog handlers is done defining parameters.
Under the *monolog.channel_handlers* parameter it is possible to define where to send logs from a specific channel.
The *default* mapping should exist as the fallback one.
In the previous example all logs will be sent to the *monolog.handler.rotating_file* handler (note that only the handler name is used, not the full service name).

The following example will send all PHP specific logs to a separate file:

```
parameters:
  monolog.channel_handlers:
    php: ['rotating_file_php']
    default: ['rotating_file_all']

services:
  monolog.handler.rotating_file_php:
    class: Monolog\Handler\RotatingFileHandler
81
    arguments: ['private://logs/php.log', 10, '%monolog.level.debug%']
82
83
  monolog.handler.rotating_file_all:
    class: Monolog\Handler\RotatingFileHandler
84
    arguments: ['private://logs/debug.log', 10, '%monolog.level.debug%']
85
86
```

87
The following code:
88
89
90
91
92

```
\Drupal::logger('php')->debug('debug message');
```

93
will write a message to the *private://logs/php.log* file.
94
95
96
97
98
99
100
101
102
103

Processors
----------

Monolog can alter the messages being written to a logging facility using *processors*. The module provides a set
of already defined processors to add information like the current user, the request uri, the client IP and so on.

Processors are defined as services under the *monolog.processor.* namespace.
We suggest you to use the [Devel module](https://www.drupal.org/project/devel) or [Drupal Console](https://drupalconsole.com) to find all of them.

104
105
106
107
108
109
110
111
To edit the list of used processors you need to override the *monolog.processors* parameter in
`sites/default/monolog.services.yml` and set the ones you need:

```
parameters:
  monolog.processors: ['message_placeholder', 'current_user', 'request_uri', 'ip', 'referer', 'filter_backtrace']
```

112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
Formatters
----------

Monolog can alter the format of the message using *formatters*. A formatter needs to be registered as services in the
[Drupal Service Container](https://www.drupal.org/docs/8/api/services-and-dependency-injection/services-and-dependency-injection-in-drupal-8).
The module provides a set of already defined formatters like line formatter and json formatter. We suggest you to use the [Devel module](https://www.drupal.org/project/devel) or [Drupal Console](https://drupalconsole.com) to find all of them.

The following example will send all PHP specific logs to a separate file in the logstash format:

```
parameters:
  monolog.channel_handlers:
    php:
      handlers: ['rotating_file_php']
      formatter: 'logstash'
    default: ['rotating_file_all']
  monolog.processors: ['message_placeholder', 'current_user', 'request_uri', 'ip', 'referer']

services:
  monolog.handler.rotating_file_php:
    class: Monolog\Handler\RotatingFileHandler
    arguments: ['private://logs/php.log', 10, 'monolog.level.debug']
  monolog.handler.rotating_file_all:
    class: Monolog\Handler\RotatingFileHandler
    arguments: ['private://logs/debug.log', 10, 'monolog.level.debug']
```

If no formatter is specified the module will fallback to line formatter.
140

141
Log to database
142
---------------
143
144

The Monolog module automatically register an handler for every enabled Drupal logger. To log to the standard
145
146
147
148
149
150
151
watchdog table it is possible to enable the Database Logging module and use *drupal.dblog* as handler:

```
parameters:
  monolog.channel_handlers:
    default: ['drupal.dblog']
```
152
153
154
155
156
157
158
159

Examples
--------

* RotatingFileHandler: logs to filesystem
```
  monolog.handler.rotating_file_debug:
    class: Monolog\Handler\RotatingFileHandler
160
    arguments: ['public://logs/debug.log', 10, '%monolog.level.debug%']
161
162
163
164
165
166
```

* SlackHandler: logs to a Slack channel
```
  monolog.handler.slack:
    class: Monolog\Handler\SlackHandler
167
    arguments: ['slack-token', 'monolog', 'Drupal', true, null, '%monolog.level.error%']
168
169
```

170
171
172
173
174
175
176
177
* DrupalMailHandler: sends log by mail (use this instead of the Monolog SwiftMailerHandler)
```
  monolog.handler.mail:
    class: Drupal\monolog\Logger\Handler\DrupalMailHandler
    arguments: ['mail@example.com', 'monolog.level.debug']

```

178
179
180
181
182
183
184
* [FingersCrossedHandler](https://github.com/Seldaek/monolog/blob/master/doc/02-handlers-formatters-processors.md#wrappers--special-handlers)
```
  monolog.handler.fg:
    class: Monolog\Handler\FingersCrossedHandler
    arguments: ['@monolog.handler.slack', null, 100]
```

185
You can find the complete list of Processors/Handlers/Formatters [here](https://github.com/Seldaek/monolog/blob/master/doc/02-handlers-formatters-processors.md#handlers).
186
187
188
189
190
191

Extending Monolog
--------

Handlers and Processors are Drupal/Symfony Services.
It is possible to define new ones or alter the existing ones just using Drupal 8 OOP standard approaches.