This package provides the components required to integrate a PHP application using Monolog with New Relic Logs.
Three components are provided:
-
A
Handler
, which delivers log records directly from Monolog to New Relic Logs. -
A
Processor
. This can be used in conjunction with the New Relic PHP agent to decorate log records with linking metadata, which allows you to use logs-in-context to correlate log records with related data across the New Relic platform. -
A
Formatter
, which extends theJsonFormatter
provided by Monolog to take the decorated log records from theProcessor
and output them with the simplified JSON body structure expected by New Relic Logs and its supported plugins.
Please see the examples section below for more detail on how to integrate these components with your application.
- Monolog, version 1 or 2.
- PHP 5.3.0 or later, although a currently supported version of PHP is strongly recommended.
To use the Handler
, you will also need the following:
- PHP's curl extension.
To enable logs-in-context functionality, you will also need:
- The New Relic PHP agent, version 9.3 or later.
This package is available on Packagist, and should be installed using Composer:
composer require newrelic/monolog-enricher
The simplest way to use this package is to use the Processor
and Handler
to
send data directly to New Relic Logs:
<?php
use Monolog\Logger;
use NewRelic\Monolog\Enricher\{Handler, Processor};
$log = new Logger('log');
$log->pushProcessor(new Processor);
$log->pushHandler(new Handler);
$log->info('Hello, world!');
If the New Relic PHP agent
is installed, then the Handler
should be able to detect the
license key
from the PHP agent, and the Processor
will automatically add linking metadata
to log records.
If you do not use New Relic APM, you can skip pushing the processor: the
Handler
can operate independently.
By default, using the Handler
means that each log record will cause a HTTP
request to occur to the New Relic Logs API. This may add overhead to your
application if a significant number of records are logged.
Like most built-in Monolog handlers, the Handler
class allows the
specification of a minimum
log level:
log records below the given level will not be sent to New Relic. Therefore, if
you don't want to see logs below WARNING
, you could change the instantiation
of Handler
as follows:
<?php
// ...
$log->pushHandler(new Handler(Logger::WARNING));
Another way of avoiding a HTTP request for each log message that is sent is to
use Monolog's built-in
BufferHandler
to batch log messages, and then send them in one message at the end of the
request:
<?php
use Monolog\Handler\BufferHandler;
use Monolog\Logger;
use NewRelic\Monolog\Enricher\{Handler, Processor};
$log = new Logger('log');
$log->pushProcessor(new Processor);
$log->pushHandler(new BufferHandler(new Handler));
$log->info('Hello, world!');
The Handler
class provides methods to set the license key or the New Relic
Log API host that will be used. This may be useful if the New Relic PHP agent
is not installed, or if you wish to log to a different account or region.
<?php
// ...
$handler = new Handler;
$handler->setHost('log-api.eu.newrelic.com');
$handler->setLicenseKey('0123456789abcdef0123456789abcdef01234567');
$log->pushHandler($handler);
If you have a logging tool already configured to send logs to New Relic Logs
(such as Fluentd, AWS CloudWatch, or
another logging tool supported by New Relic Logs),
then you may prefer to use the Processor
and Formatter
to send logs to that
tool, rather than sending logs directly to New Relic using the Handler
.
For example, if your logging tool is configured to pick up
NDJSON on stderr
, you could configure the logger as
follows:
<?php
use Monolog\Handler\StreamHandler;
use Monolog\Logger;
use NewRelic\Monolog\Enricher\{Formatter, Processor};
$log = new Logger('log');
$log->pushProcessor(new Processor);
$handler = new StreamHandler('php://stderr');
$handler->setFormatter(new Formatter);
$log->pushHandler($handler);
$log->info('Hello, world!');
More information on configuring your logging tool to send logs to New Relic Logs can be found within the New Relic documentation.
If you would like to contribute to this project, please read the CONTRIBUTING.md and code of conduct, along with the instructions below on our coding standards and running the test suites.
The development dependencies for this project are managed by Composer, and should be installed via Composer:
composer install
This project conforms to PSR-12, with a soft line length limit of 80 characters.
PHP_CodeSniffer is used to
ensure conformity. You can run phpcs
to check the current code via the
following Composer script:
composer coding-standard-check
Alternatively, you can use phpcbf
to automatically fix most errors:
composer coding-standard-fix
When submitting a fix, please also ensure a corresponding entry has been added to the changelog.
This project uses PHPUnit 4, which is the last PHPUnit version to support PHP 5.3.
You can run the test suite via Composer:
composer test
If phpdbg
is available, you can also generate a code coverage report while
running the test suite:
composer test-coverage
This will write a HTML coverage report to coverage/index.html
.
It's also possible to run a suite of integration tests against both Monolog 1 and 2 via Composer:
composer integration
More information on these tests is available in the
tests/integration
README.