PHP agent logs in context

With our PHP agent, you can get logs in context, which lets you see your app logs in the context of your other New Relic data. For general information on this feature, see APM logs in context.

Tip

Got lots of PHP logs? Check out our tutorial on how to optimize and manage them.

Automatic logs in context options

If you're using a supported framework, you can configure the APM agent to send your app's logs and linking metadata automatically to New Relic. Supported frameworks for automatic logs in context include:

Monolog (version 2 or 3)

This is the simplest approach, and it's a great choice for developers who may not have the access or interest in setting up a log forwarder, or for accounts that want to see the power of logs and other linking metadata in context of their apps, without a lot of overhead.

Using this option, the agent adds span.id, trace.id, hostname, entity.guid, and entity.name. Learn about log forwarding limitations.

Important

As of agent release 10.3.0 the logging metrics and agent log forwarding features are enabled by default.

All you need to do is install an agent version with log forwarding capabilities (PHP agent 10.1.0 or higher). If forwarding is disabled, you can use this configuration:

Configuration file (newrelic.ini):

newrelic.application_logging.enabled = true
newrelic.application_logging.metrics.enabled = true
newrelic.application_logging.forwarding.enabled = true

The PHP agent configuration docs explain in detail how to configure your agent, but here we'll review and link to some of the most important aspects of the PHP logs configuration.

There is a single option to control if the core logging feature is active:

newrelic.application_logging.enabled

If you're using a supported logging framework the agent can send metrics which measure the number of severity of log messages your application is generating. You can enable this features using the newrelic.config.application_logging.metrics.enabled config.

If you're using a supported logging framework and want to use the agent to send your application logs to New Relic, you can control that through settings newrelic.config.application_logging.forwarding prefixed INI settings. Options available are:

Important

If you have an existing log forwarding solution and are updating your agent to use automatic logs in context, be sure to disable your manual log forwarder. Otherwise, your app will be sending double the log data. Depending on your account, this could result in double billing. For more information, learn how to disable your specific log forwarder.

Did this doc help with your installation?

Secure your data

Your logs may include sensitive information protected by HIPAA or other compliance protocols. By default we obfuscate number patterns that appear to be for items such as credit cards or Social Security numbers, but you may need to hash or mask additional information.

For more information, see our documentation about obfuscation expressions and rules. You can hash or mask your log data by using the New Relic UI or by using NerdGraph, our GraphQL API.

Explore your data

To make the most of your logging data:

On the APM Summary page, click your Web transaction time chart to view logs associated with a specific point in time.
Check your app's Errors inbox to view the logs associated with your errors.
Use distributed tracing to see the logs associated with individual traces.
Explore more logging data across your platform with our logs UI.
Set up alerts based on log output and severity.
Query your data using our specialized UI for logs data, and create dashboards with the results.

Troubleshooting tips

Typically your logs will start to appear less than a minute after you enable logs in context. Check your app's Triage > Logs section. You will also start seeing log patterns related to the error there.

If you don't see any logs for errors or traces, there may not be any for your app. Try refreshing the UI page, or change the selected time period.

Disable automatic logging

APM logs in context automatically forwards agent log data when enabled. As of agent release 10.3.0, this feature is enabled by default for the PHP agent. This can have a negative impact on your security, compliance, billing, or system performance. For more information, or if you need to adjust the default setting, follow the procedures to disable automatic logging.

Manual logs in context option

Before language agents had the ability to forward and decorate logs, you could use our manual solutions to send linking metadata.

This option is still supported, but is no longer encouraged. Also, this method requires that you install a log forwarder before enabling logs in context. If you do not have a log forwarder, the New Relic UI will prompt you to use our infrastructure agent.

If you decide to use your existing log forwarding solution and later decide to update your agent to use automatic logs in context, be sure to disable your manual log forwarder. Otherwise, your app will be sending double log lines. Depending on your account, this could result in double billing. For more information, follow the procedures to disable your specific log forwarder.

Important

This option should not be used with in-agent forwarding. Using an external log forwarder to send logs to New Relic while in-agent forwarding is enabled will cause your logs to be sent up twice to New Relic. Depending on your account, this may result in double billing.

Update your agent's configuration to disable log forwarding, then restart the agent.

Configuration file (newrelic.ini):

newrelic.application_logging.forwarding.enabled = false

If you need to use the manual process to set up logs in context for PHP, first setup your PHP app.

Make sure you have already set up logging in New Relic. This includes configuring a supported log forwarder that collects your application logs and extends the metadata that is forwarded to New Relic.
Install or update to the latest PHP agent version, and enable distributed tracing. Use PHP agent version 9.13.0.270 or higher for logs in context.
Install Monolog version 1 or 2, or use a compatible log forwarding plugin if you are not using the built-in Monolog Handler for New Relic.
Configure logs in context for PHP using the Monolog extension, if used.

You must install the Monolog log enricher package before you can configure Monolog for logs in context. This is done by using Composer to install the newrelic/monolog-enricher package.

In most cases, use the Processor and Handler classes provided by the log enricher package in conjunction with Monolog's built-in BufferHandler.

The Processor adds the contextual metadata required for New Relic's logs in context capabilities to operate.
The Handler sends the log records to New Relic.
The BufferHandler ensures that the logs are delivered with as little overhead as possible.
At the point where you create the Monolog\Logger object, add the following pushProcessor and pushHandler calls to add the Processor and Handler:
```
<?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));
```
Tip
You can use the Processor and Handler in conjunction with any existing Monolog setup. You do not need to remove your existing processors and handlers.

If you use Monolog to send logs to a compatible log forwarder, and if you have already configured that tool to send logs to New Relic, you can use the Processor and Formatter solely for that tool. This option prevents additional overhead of sending logs directly to New Relic with the Handler.

You will need to be using a handler that supports the setFormatter() method, and your logging tool must be able to ingest JSON logs.

Here's an example of configuring Monolog to handle other log forwarders:

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

To verify that you have configured the log appender correctly, run your application, then check your logs data in New Relic using the query operator has:span.id has:trace.id.

If everything is configured correctly and your data is being forwarded to New Relic with the enriched metadata, your logs should now be emitted as JSON and contain trace.id and span.id fields. If you don't see log data in the UI, follow the troubleshooting procedures.

If the logs from your application do not include fields like trace.id and span.id, there may be a problem with the configuration of the Monolog log enricher. In this situation:

Check that the PHP agent for your app has been installed and is configured to enable distributed tracing.
Check that your application is using the Monolog logger object when sending log records, not syslog().
Check that another Monolog handler is not preventing the log record from bubbling.

Tip

Automatic logs in context options

Important

Important

Did this doc help with your installation?

Secure your data

Explore your data

Troubleshooting tips

Disable automatic logging

Manual logs in context option

Important

PHP configuration with Monolog

Tip

PHP configuration with other log forwarders