simplecomplex / json-log
PSR-3 logger which files events as JSON.
Requires
- php: >=7.0
- psr/log: ^1.0
- simplecomplex/utils: ^1.8 || ^2.0 || dev-develop
Suggests
- simplecomplex/config: For better configuration management.
- simplecomplex/inspect: CLI features do NOT work without Inspect. And great for logging; better variable dumps and traces.
README
PSR-3 logger which files events as JSON.
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).
Several columns get skipped if their equivalent method returns empty string (that's the un-bold items).
Some column's must be set via the PSR-3 logger methods' $context
argument.
All column values are string, except the code column.
Event
- message
- @timestamp: ISO-8601
- message_id: fairly random ID, using site ID as salt
- correlation_id: set via
$context
- subtype: set via
$context
, defaultcomponent
- level:
emergency|alert|critical|error|warning|notice|info|debug
- code: integer, set via
$context
; default0
- exception: PHP throwable, via
$context
; becomes class name - trunc:
(original byte length/truncated length)
- user: set via
$context
, or overrideJsonLogEvent::user()
in extending class - session: set via
$context
, overrideJsonLogEvent::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
.
The simplest approach to that is to use environment variables, like
SetEnv lib_simplecomplex_jsonlog__threshold 7
.
JsonLog
constructor uses environment variables as fallback.
- (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; defaultYmd
- (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
.
Requirements
- PHP >=7.0
- PSR-3 Log
- SimpleComplex Utils