Skip to content

Commit 133d36b

Browse files
jorgelbgxabbuh
jorgelbg
authored and
xabbuh
committed
Updating recommended email settings for monolog
1 parent 918e842 commit 133d36b

File tree

1 file changed

+77
-48
lines changed

1 file changed

+77
-48
lines changed

‎cookbook/logging/monolog_email.rst‎

Lines changed: 77 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -25,18 +25,20 @@ it is broken down.
2525
# action_level: error
2626
# excluded_404s:
2727
# - ^/
28-
handler: buffered
29-
buffered:
30-
type: buffer
28+
handler: deduplicated
29+
deduplicated:
30+
type: deduplication
3131
handler: swift
3232
swift:
3333
type: swift_mailer
3434
from_email: 'error@example.com'
3535
to_email: 'error@example.com'
3636
# or list of recipients
3737
# to_email: ['dev1@example.com', 'dev2@example.com', ...]
38-
subject: An Error Occurred!
38+
subject: 'An Error Occurred! %%message%%'
3939
level: debug
40+
formatter: monolog.formatter.html
41+
content_type: text/html
4042
4143
.. code-block:: xml
4244
@@ -49,8 +51,9 @@ it is broken down.
4951
http://symfony.com/schema/dic/monolog http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">
5052
5153
<monolog:config>
52-
<!--
53-
To also log 400 level errors (but not 404's):
54+
<!--
55+
500 errors are logged at the critical level,
56+
to also log 400 level errors (but not 404's):
5457
action-level="error"
5558
And add this child inside this monolog:handler
5659
<monolog:excluded-404>^/</monolog:excluded-404>
@@ -59,23 +62,25 @@ it is broken down.
5962
name="mail"
6063
type="fingers_crossed"
6164
action-level="critical"
62-
handler="buffered"
65+
handler="deduplicated"
6366
/>
6467
<monolog:handler
65-
name="buffered"
66-
type="buffer"
68+
name="deduplicated"
69+
type="deduplication"
6770
handler="swift"
68-
/>
71+
>
6972
<monolog:handler
7073
name="swift"
7174
type="swift_mailer"
7275
from-email="error@example.com"
73-
subject="An Error Occurred!"
74-
level="debug">
76+
subject="An Error Occurred! %%message%%"
77+
level="debug"
78+
formatter="monolog.formatter.html"
79+
content-type="text/html">
7580
7681
<monolog:to-email>error@example.com</monolog:to-email>
7782
78-
<!-- or multiple to-email elements -->
83+
<!-- or list of recipients -->
7984
<!--
8085
<monolog:to-email>dev1@example.com</monolog:to-email>
8186
<monolog:to-email>dev2@example.com</monolog:to-email>
@@ -92,26 +97,29 @@ it is broken down.
9297
'handlers' => array(
9398
'mail' => array(
9499
'type' => 'fingers_crossed',
100+
// 500 errors are logged at the critical level
95101
'action_level' => 'critical',
96102
// to also log 400 level errors (but not 404's):
97103
// 'action_level' => 'error',
98104
// 'excluded_404s' => array(
99105
// '^/',
100106
// ),
101-
'handler' => 'buffered',
107+
'handler' => 'deduplicated',
102108
),
103-
'buffered' => array(
104-
'type' => 'buffer',
109+
'deduplicated' => array(
110+
'type' => 'deduplication',
105111
'handler' => 'swift',
106112
),
107113
'swift' => array(
108-
'type' => 'swift_mailer',
109-
'from_email' => 'error@example.com',
110-
'to_email' => 'error@example.com',
114+
'type' => 'swift_mailer',
115+
'from_email' => 'error@example.com',
116+
'to_email' => 'error@example.com',
111117
// or a list of recipients
112118
// 'to_email' => array('dev1@example.com', 'dev2@example.com', ...),
113-
'subject' => 'An Error Occurred!',
114-
'level' => 'debug',
119+
'subject' => 'An Error Occurred! %%message%%',
120+
'level' => 'debug',
121+
'formatter' => 'monolog.formatter.html',
122+
'content_type' => 'text/html',
115123
),
116124
),
117125
));
@@ -121,20 +129,24 @@ it is only triggered when the action level, in this case ``critical`` is reached
121129
The ``critical`` level is only triggered for 5xx HTTP code errors. If this level
122130
is reached once, the ``fingers_crossed`` handler will log all messages
123131
regardless of their level. The ``handler`` setting means that the output
124-
is then passed onto the ``buffered`` handler.
132+
is then passed onto the ``deduplicated`` handler.
125133

126134
.. tip::
127135

128136
If you want both 400 level and 500 level errors to trigger an email,
129137
set the ``action_level`` to ``error`` instead of ``critical``. See the
130138
code above for an example.
131139

132-
The ``buffered`` handler simply keeps all the messages for a request and
133-
then passes them onto the nested handler in one go. If you do not use this
134-
handler then each message will be emailed separately. This is then passed
135-
to the ``swift`` handler. This is the handler that actually deals with
136-
emailing you the error. The settings for this are straightforward, the
137-
to and from addresses and the subject.
140+
The ``deduplicated`` handler simply keeps all the messages for a request and
141+
then passes them onto the nested handler in one go, but only if the records are
142+
unique over a given period of time (60 seconds by default). If the records are
143+
duplicates they are simply discarded. Adding this handler reduces the amount of
144+
notifications to a manageable level, specially in critical failure scenarios.
145+
146+
The messages are then passed to the ``swift`` handler. This is the handler that
147+
actually deals with emailing you the error. The settings for this are
148+
straightforward, the to and from addresses, the formatter, the content type
149+
and the subject.
138150

139151
You can combine these handlers with other handlers so that the errors still
140152
get logged on the server as well as the emails being sent:
@@ -152,20 +164,22 @@ get logged on the server as well as the emails being sent:
152164
handler: grouped
153165
grouped:
154166
type: group
155-
members: [streamed, buffered]
167+
members: [streamed, deduplicated]
156168
streamed:
157169
type: stream
158170
path: '%kernel.logs_dir%/%kernel.environment%.log'
159171
level: debug
160-
buffered:
161-
type: buffer
172+
deduplicated:
173+
type: deduplication
162174
handler: swift
163175
swift:
164176
type: swift_mailer
165177
from_email: 'error@example.com'
166178
to_email: 'error@example.com'
167-
subject: An Error Occurred!
179+
subject: 'An Error Occurred! %%message%%'
168180
level: debug
181+
formatter: monolog.formatter.html
182+
content_type: text/html
169183
170184
.. code-block:: xml
171185
@@ -188,25 +202,36 @@ get logged on the server as well as the emails being sent:
188202
type="group"
189203
>
190204
<member type="stream"/>
191-
<member type="buffered"/>
205+
<member type="deduplicated"/>
192206
</monolog:handler>
193207
<monolog:handler
194208
name="stream"
195209
path="%kernel.logs_dir%/%kernel.environment%.log"
196210
level="debug"
197211
/>
198212
<monolog:handler
199-
name="buffered"
200-
type="buffer"
213+
name="deduplicated"
214+
type="deduplication"
201215
handler="swift"
202216
/>
203217
<monolog:handler
204218
name="swift"
219+
type="swift_mailer"
205220
from-email="error@example.com"
206-
to-email="error@example.com"
207-
subject="An Error Occurred!"
221+
subject="An Error Occurred! %%message%%"
208222
level="debug"
209-
/>
223+
formatter="monolog.formatter.html"
224+
content-type="text/html">
225+
226+
<monolog:to-email>error@example.com</monolog:to-email>
227+
228+
<!-- or list of recipients -->
229+
<!--
230+
<monolog:to-email>dev1@example.com</monolog:to-email>
231+
<monolog:to-email>dev2@example.com</monolog:to-email>
232+
...
233+
-->
234+
</monolog:handler>
210235
</monolog:config>
211236
</container>
212237
@@ -222,29 +247,33 @@ get logged on the server as well as the emails being sent:
222247
),
223248
'grouped' => array(
224249
'type' => 'group',
225-
'members' => array('streamed', 'buffered'),
250+
'members' => array('streamed', 'deduplicated'),
226251
),
227252
'streamed' => array(
228253
'type' => 'stream',
229254
'path' => '%kernel.logs_dir%/%kernel.environment%.log',
230255
'level' => 'debug',
231256
),
232-
'buffered' => array(
233-
'type' => 'buffer',
234-
'handler' => 'swift',
257+
'deduplicated' => array(
258+
'type' => 'deduplication',
259+
'handler' => 'swift',
235260
),
236261
'swift' => array(
237-
'type' => 'swift_mailer',
238-
'from_email' => 'error@example.com',
239-
'to_email' => 'error@example.com',
240-
'subject' => 'An Error Occurred!',
241-
'level' => 'debug',
262+
'type' => 'swift_mailer',
263+
'from_email' => 'error@example.com',
264+
'to_email' => 'error@example.com',
265+
// or a list of recipients
266+
// 'to_email' => array('dev1@example.com', 'dev2@example.com', ...),
267+
'subject' => 'An Error Occurred! %%message%%',
268+
'level' => 'debug',
269+
'formatter' => 'monolog.formatter.html',
270+
'content_type' => 'text/html',
242271
),
243272
),
244273
));
245274
246275
This uses the ``group`` handler to send the messages to the two
247-
group members, the ``buffered`` and the ``stream`` handlers. The messages will
276+
group members, the ``deduplicated`` and the ``stream`` handlers. The messages will
248277
now be both written to the log file and emailed.
249278

250279
.. _Monolog: https://github.com/Seldaek/monolog

0 commit comments

Comments
 (0)