JSONlog

Logs watchdog events JSON-formatted

to log files.
Provides a Logstash/ElasticSearch-ready log source.

Drupal 7 and 11 compatible.

All Core versions have a stable release and work in a similar way using the same configurable settings as listed below.

Settings overridable by server environment vars

to secure simple and safe centralized configuration of multiple sites/hosts.
Just SetEnv drupal_[Drupal conf var] '[value]'.

• jsonlog_severity_threshold: defaults to warning
• jsonlog_truncate: defaults to 64 (Kb), logger uses file locking
• jsonlog_site_id: defaults to server's hostname + database name + database prefix (if any))
• jsonlog_canonical: name; for site identification across multiple instances
• jsonlog_dir: defaults to PHP:ini error_log (unless that is 'syslog', then checks the usual suspects /var/log/...) + /drupal-jsonlog
• jsonlog_file_time: none | Ymd (default) | YW | Ym
• jsonlog_newline_prepend: bool|null (version >=8.x-1.3 only)
• jsonlog_tags: comma-separated list; server env var + Drupal conf var

Beware that versions >=8.x-2.* defaults to append newline to log entry instead of prepending.

JSON log fields

• @timestamp: ISO-8601 milliseconds timestamp instead of watchdog's native seconds timestamp
• @version: (always) 1
• message_id: jsonlog site ID + unique padding
• site_id: (default) server's hostname + database name + database prefix (if any)
• canonical: name; for site identification across multiple instances (default empty)
• tags: comma-separated list; becomes array
• type: always 'drupal'
• subtype: drupal watchdog type
• severity: (string) error is 'error', not 3
• method: HTTP request method, or 'cli' (if drush)
• request_uri
• referer
• uid
• username: name of current user, or empty (deprecated >=8.x-2.*)
• client_ip: equivalent to watchdog standard 'ip' field
• link
• code: integer if watchdog 'link' is N or 'N'
• variables: always null, watchdog variables gets parsed into message
• trunc: null if the log entry as a whole doesn't exceed the json_truncate setting; otherwise array of original length, truncated length

Pros & cons versus dblog and syslog

• + JSONlog provides Logstash/ElasticSearch-ready and -tailor-made sources; all Logstash has to do is trace files located in standardized directories across multiple servers
• + dblog may be a performance issue in high traffic environments, due to database operations
• - but dblog might - due to database writing - be better at handling concurrency
• + syslog logs all sorts of stuff, not only Drupal site related events
• + syslog will in most cases truncate at maximally 1Kb; and that size will be unsufficient when logging error traces (for instance via Inspect)

Original concept

and continued source of inspiration: Klavs Klavsen (klavs).

Sponsorship

JSONlog D7 is sponsored by Københavns Kommune, Koncernservice (Copenhagen Municipality, Corporate Services). Recent major versions are sponsored by Cegeka and VDAB.

Documentation (D7)

• phpdoc Doxygen dialect

Requirements

• D7: PHP 5.3+
• D9: PHP 7+
• D10+: PHP 8.1
• no module dependencies