library json-log

simplecomplex/json-log

PSR-3 logger which files events as JSON.

JsonLog

PSR-3 logger which files events as JSON., _(*1)

Columns

Columns are configuration-wise split in groups of event-, request- and site-specific items.
For every column there's a JsonLogEvent method and a JSON bucket name (this lists the bucket names)., _(*2)

Several columns get skipped if their equivalent method returns empty string (that's the un-bold items)., _(*3)

Some column's must be set via the PSR-3 logger methods' $context argument., _(*4)

All column values are string, except the code column., _(*5)

Event

• message
• @timestamp: ISO-8601
• message_id: fairly random ID, using site ID as salt
• correlation_id: set via $context
• subtype: set via $context, default component
• level: emergency|alert|critical|error|warning|notice|info|debug
• code: integer, set via $context; default 0
• exception: PHP throwable, via $context; becomes class name
• trunc: (original byte length/truncated length)
• user: set via $context, or override JsonLogEvent::user() in extending class
• session: set via $context, override JsonLogEvent::session() in extending class

Request

• method: HTTP request method; cli if in CLI mode
• request_uri: HTTP request URI; console arguments if in CLI mode
• referer: HTTP referrer (sanitized)
• client_ip: remote address, filtered for reverse_proxy_addresses
• useragent: sanitized

Site

• type: type setting; default webapp
• host: $_SERVER['SERVER_NAME'] or empty
• site_id: siteid setting
• canonical: canonical setting
• tags: tags setting

Settings

Are set via 'global' SimpleComplex Config, section lib_simplecomplex_jsonlog., _(*6)

The simplest approach to that is to use environment variables, like
SetEnv lib_simplecomplex_jsonlog__threshold 7.
JsonLog constructor uses environment variables as fallback., _(*7)

• (int) threshold: less severe events are skipped (not logged); default 4 (~warning)
• (str) siteid: defaults to name of directory above document root
• (str) path: default /var/log/[apache2|httpd|nginx]/php-jsonlog
• (int) truncate (Kb): truncate message so that event JSON doesn't exceed that length; default 32
• (str) reverse_proxy_addresses: comma-separated list of IP addresses; default empty
• (str) type: default webapp
• (str) canonical: site identifier across multiple instances; default empty
• (str) tags: comma-separated list; default empty
• (str) reverse_proxy_header: default HTTP_X_FORWARDED_FOR
• (str) file_time: set to empty or none to write to the same log file forever; default Ymd
• (str) format: default|pretty|prettier; prettier is not valid JSON, but easier on the eyes

Recommended settings

All environments

• siteid: use something more meaningful than the default
• truncate: way higher, to like 256, if your system generates giant dumps or traces

Prod environment

• reverse_proxy_addresses: look out for proxy servers

Dev/test environment

• threshold: 7 (~debug)
• path: make it closer to home if no log extractor (like Kibana+ElasticSearch) running
• format: prettier if no log extractor running

CLI commands

# List all json-log commands and their help.
php cli.php json-log -h
# One command's help.
php cli.php json-log-xxx -h

# Check/enable JsonLog to write logs.
php cli.php json-log-committable

# Truncate current log file.
php cli.php json-log-truncate

Dependency injection container ID: logger

Recommendation: access (and thus instantiate) JsonLog via DI container ID 'logger'.
See SimpleComplex Utils Dependency., _(*8)

Requirements

• PHP >=7.0
• PSR-3 Log
• SimpleComplex Utils

Suggestions

• SimpleComplex Inspect
• SimpleComplex Config