Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updating recommended email settings for monolog #6587

Closed
wants to merge 3 commits into from
Closed

Updating recommended email settings for monolog #6587

Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
7588af5
Updating recommended email settings for monolog
jorgelbg May 21, 2016
f300c8a
Changing explanation of the deduplicated/deduplication handlers and r…
jorgelbg May 23, 2016
4a0c00d
Adding a new line to improve readability
jorgelbg May 23, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 76 additions & 48 deletions cookbook/logging/monolog_email.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,18 +25,20 @@ it is broken down.
# action_level: error
# excluded_404s:
# - ^/
handler: buffered
buffered:
type: buffer
handler: deduplicated
deduplicated:
type: deduplication
handler: swift
swift:
type: swift_mailer
from_email: '[email protected]'
to_email: '[email protected]'
# or list of recipients
# to_email: ['[email protected]', '[email protected]', ...]
subject: An Error Occurred!
subject: 'An Error Occurred! %%message%%'
level: debug
formatter: monolog.formatter.html
content_type: text/html

.. code-block:: xml

Expand All @@ -49,8 +51,9 @@ it is broken down.
http://symfony.com/schema/dic/monolog http://symfony.com/schema/dic/monolog/monolog-1.0.xsd">

<monolog:config>
<!--
To also log 400 level errors (but not 404's):
<!--
500 errors are logged at the critical level,
to also log 400 level errors (but not 404's):
action-level="error"
And add this child inside this monolog:handler
<monolog:excluded-404>^/</monolog:excluded-404>
Expand All @@ -59,23 +62,25 @@ it is broken down.
name="mail"
type="fingers_crossed"
action-level="critical"
handler="buffered"
handler="deduplicated"
/>
<monolog:handler
name="buffered"
type="buffer"
name="deduplicated"
type="deduplication"
handler="swift"
/>
>
<monolog:handler
name="swift"
type="swift_mailer"
from-email="[email protected]"
subject="An Error Occurred!"
level="debug">
subject="An Error Occurred! %%message%%"
level="debug"
formatter="monolog.formatter.html"
content-type="text/html">

<monolog:to-email>[email protected]</monolog:to-email>

<!-- or multiple to-email elements -->
<!-- or list of recipients -->
<!--
<monolog:to-email>[email protected]</monolog:to-email>
<monolog:to-email>[email protected]</monolog:to-email>
Expand All @@ -92,26 +97,29 @@ it is broken down.
'handlers' => array(
'mail' => array(
'type' => 'fingers_crossed',
// 500 errors are logged at the critical level
'action_level' => 'critical',
// to also log 400 level errors (but not 404's):
// 'action_level' => 'error',
// 'excluded_404s' => array(
// '^/',
// ),
'handler' => 'buffered',
'handler' => 'deduplicated',
),
'buffered' => array(
'type' => 'buffer',
'deduplicated' => array(
'type' => 'deduplication',
'handler' => 'swift',
),
'swift' => array(
'type' => 'swift_mailer',
'from_email' => '[email protected]',
'to_email' => '[email protected]',
'type' => 'swift_mailer',
'from_email' => '[email protected]',
'to_email' => '[email protected]',
// or a list of recipients
// 'to_email' => array('[email protected]', '[email protected]', ...),
'subject' => 'An Error Occurred!',
'level' => 'debug',
'subject' => 'An Error Occurred! %%message%%',
'level' => 'debug',
'formatter' => 'monolog.formatter.html',
'content_type' => 'text/html',
),
),
));
Expand All @@ -121,20 +129,23 @@ it is only triggered when the action level, in this case ``critical`` is reached
The ``critical`` level is only triggered for 5xx HTTP code errors. If this level
is reached once, the ``fingers_crossed`` handler will log all messages
regardless of their level. The ``handler`` setting means that the output
is then passed onto the ``buffered`` handler.
is then passed onto the ``deduplicated`` handler.

.. tip::

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

The ``buffered`` handler simply keeps all the messages for a request and
then passes them onto the nested handler in one go. If you do not use this
handler then each message will be emailed separately. This is then passed
to the ``swift`` handler. This is the handler that actually deals with
emailing you the error. The settings for this are straightforward, the
to and from addresses and the subject.
The ``deduplicated`` handler simply keeps all the messages for a request and
then passes them onto the nested handler in one go, but only if the records are
unique over a given period of time (60 seconds by default). If the records are
duplicates they are simply discarded. Adding this handler reduces the amount of
notifications to a manageable level, specially in critical failure scenarios.
The messages are then passed to the ``swift`` handler. This is the handler that
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would add a blank line before this sentence to have it rendered as its own paragraph to improve readability.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

actually deals with emailing you the error. The settings for this are
straightforward, the to and from addresses, the formatter, the content type
and the subject.

You can combine these handlers with other handlers so that the errors still
get logged on the server as well as the emails being sent:
Expand All @@ -160,20 +171,22 @@ get logged on the server as well as the emails being sent:
handler: grouped
grouped:
type: group
members: [streamed, buffered]
members: [streamed, deduplicated]
streamed:
type: stream
path: '%kernel.logs_dir%/%kernel.environment%.log'
level: debug
buffered:
type: buffer
deduplicated:
type: deduplication
handler: swift
swift:
type: swift_mailer
from_email: '[email protected]'
to_email: '[email protected]'
subject: An Error Occurred!
subject: 'An Error Occurred! %%message%%'
level: debug
formatter: monolog.formatter.html
content_type: text/html

.. code-block:: xml

Expand All @@ -196,25 +209,36 @@ get logged on the server as well as the emails being sent:
type="group"
>
<member type="stream"/>
<member type="buffered"/>
<member type="deduplicated"/>
</monolog:handler>
<monolog:handler
name="stream"
path="%kernel.logs_dir%/%kernel.environment%.log"
level="debug"
/>
<monolog:handler
name="buffered"
type="buffer"
name="deduplicated"
type="deduplication"
handler="swift"
/>
<monolog:handler
name="swift"
type="swift_mailer"
from-email="[email protected]"
to-email="[email protected]"
subject="An Error Occurred!"
subject="An Error Occurred! %%message%%"
level="debug"
/>
formatter="monolog.formatter.html"
content-type="text/html">

<monolog:to-email>[email protected]</monolog:to-email>

<!-- or list of recipients -->
<!--
<monolog:to-email>[email protected]</monolog:to-email>
<monolog:to-email>[email protected]</monolog:to-email>
...
-->
</monolog:handler>
</monolog:config>
</container>

Expand All @@ -230,29 +254,33 @@ get logged on the server as well as the emails being sent:
),
'grouped' => array(
'type' => 'group',
'members' => array('streamed', 'buffered'),
'members' => array('streamed', 'deduplicated'),
),
'streamed' => array(
'type' => 'stream',
'path' => '%kernel.logs_dir%/%kernel.environment%.log',
'level' => 'debug',
),
'buffered' => array(
'type' => 'buffer',
'handler' => 'swift',
'deduplicated' => array(
'type' => 'deduplication',
'handler' => 'swift',
),
'swift' => array(
'type' => 'swift_mailer',
'from_email' => '[email protected]',
'to_email' => '[email protected]',
'subject' => 'An Error Occurred!',
'level' => 'debug',
'type' => 'swift_mailer',
'from_email' => '[email protected]',
'to_email' => '[email protected]',
// or a list of recipients
// 'to_email' => array('[email protected]', '[email protected]', ...),
'subject' => 'An Error Occurred! %%message%%',
'level' => 'debug',
'formatter' => 'monolog.formatter.html',
'content_type' => 'text/html',
),
),
));

This uses the ``group`` handler to send the messages to the two
group members, the ``buffered`` and the ``stream`` handlers. The messages will
group members, the ``deduplicated`` and the ``stream`` handlers. The messages will
now be both written to the log file and emailed.

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