README

This package provides the components required to integrate a PHP application using Monolog with New Relic Logs.

Note

This is a fork of the original newrelic/newrelic-monolog-logenricher-php package, updated to support Monolog 3 and PHP 8.1+.

Installation

Components

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 the JsonFormatter provided by Monolog to take the decorated log records from the Processor and output them with the simplified JSON body structure expected by New Relic Logs and its supported plugins.

Please see Getting Started below for more detail on how to integrate these components with your application.

Requirements

Monolog, version 3.
PHP 8.1 or later.

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.

Install

This package is available on Packagist, and should be installed using Composer:

composer require giovanne-oliveira/newrelic-monolog-enricher

Getting Started

Sending logs directly to New Relic Logs

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.

Selectively sending log records

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));

Buffering log records to improve performance

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!');

Manually specifying the license key and/or host

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);

Integrating with an existing logging tool

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.

Contribute

Setting up a development environment

The development dependencies for this project are managed by Composer, and should be installed via Composer:

composer install

Coding standards

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

Testing

This project uses Pest for testing.

You can run the test suite via Composer:

composer test

License

newrelic-monolog-logenricher-php is licensed under the Apache 2.0 License.

giovanne-oliveira / newrelic-monolog-enricher

Maintainers

Details