Logger: mongodb_watchdog
The mongodb_watchdog
module stores the log entries for your Drupal site
in MongoDB collections as mentioned in
Settings Configuration
It also exposes a logs browsing UI on admin/reports/mongodb/watchdog/
,
with additional features in comparison with the built-in database logging:
- location of error log, with source file and line number
- integrated display of the Top404 and Top403
- grouping of logs by message
- optional: grouping of logs by HTTP request, when the
mongodb_watchdog.request_tracking
configuration is enabled
This module uses a separate database, defined by the logger
database alias in
settings. Do NOT point that alias to the same database as default
, because the
module Drops the logger
database when uninstalling, which would drop all your
other data with it.
Configuration
Below are the configurable items available in mongodb_watchdog.settings
mongodb.watchdog.items
- the maximum item limit on the capped collection used by the module.
- if not defined, it defaults to 10000.
- the actual (size-based) limit is derived from this value, assuming 1 kiB per watchdog entry.
mongodb.watchdog.limit
- the maximum severity level (0 to 7, per RFC 5424) to save into the logger storage.
- events below this level (with a higher numerical level) will be ignored by the module.
- if not defined, all events will saved.
mongodb.watchdog.items_per_page
- the maximum number of events displayed on the event details page.
mongodb_watchdog.request_tracking
- if true, enable the per-request event tracking.
- if not defined, it defaults to false because its cost is not entirely negligible.
- this feature requires the use of
mod_unique_id
in Apache 2.x
mongodb_watchdog.requests
- if request tracking is enabled, this setting defines the maximum requests limit on the capped collection used by the module.
- if not defined, it defaults to 100000.
- the actual (size-based) limit is derived from this variable, assuming 1 kiB per tracker entry.
See Drupal\Core\Logger\RfcLogLevel
and Psr\Log\LogLevel
for further
information about severity levels.
Troubleshooting command
The module provides one single command designed to help troubleshoot issues with logging when this module is enabled. It is available for Drush and Drupal Console indifferently.
The command takes no arguments and returns an analysis of the logger collections which needs to be interpreted.
$ drush mongodb:watchdog:sanitycheck
0: 0
1: 2
1000: 1
2000: 0
3000: 0
4000: 0
5000: 0
6000: 0
7000: 0
8000: 0
9000: 0
9999: 0
10000: 0
$
What the output of this command represents is the number of watchdog_event_*
collections with a document count in the range specified as the key.
In the results, the first and last two entries are specific: they match exact
counts, while the others are intervals, so the actual buckets are: 0
, 1
,
2..1000
, 1001..2000
, ..., 9001..9998
, 9999
, 10000
. The specific
value 10000 is the number of entries allowed in event collections, as these are
MongoDB capped collections: whatever its value n
, the command will report
0
, 1
, n-1
, n
, and 9 ranges in between.
Interpreting the results
As a general rule, on a high-load site, all buckets should have comparable
numbers, and the number of events logged grouped by pattern is pseudo-random,
except for the 0
bucket, which should be empty.
0
bucket non-empty: unless there was specific manipulation performed by hand, this is a bug, and should be reported: event collections are created when an event is created, by the first insertion, and dropped as needed, but never truncated or created without an insert.1
bucket has a high value, possibly orders of magnitude higher than other buckets. This denotes an incorrect use of the Drupal logger system, for which the PSR-3message
parameter is a message template, and the variant part of the message is expressed as placeholder values in the options. Look for calls to log operations passing a variable as the message and replace them by a template containing placeholders for the variable content in the message.n-1
bucket has a high value: suspicious situation with the logger, especially if the "n" value is low or 0: please report a possible bug, with accompanying datan
bucket has a high valuen-1
has a high value too: this is a mostly normal situation, especially if the value in the previous bucket is also high, although it means the data rotation in your site is possibly a bit high and you should increase the size of the capped collections to ensure longer retention of data.n-1
has a low or 0 value: your logs are saturated by the site, and you are losing information, as all the capped collections in that situation are rolling over constantly. Ensure you have enough storage and raise the value capped collection size.- The config value to change in these cases is
mongodb.watchdog.items
.