| title | tags | metaDescription | redirects | freshnessValidatedDate | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
PHP agent logs in context |
|
For apps monitored by the PHP agent, learn how to link log data with related data across the rest of the New Relic platform. |
|
never |
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.
Got lots of PHP logs? Check out our [tutorial on how to optimize and manage them](/docs/tutorial-large-logs/get-started-managing-large-logs/).You have two options to configure logs in context to send your app's logs and linking metadata automatically to New Relic. Supported frameworks for automatic logs in context using in agent forwarding include:
- Monolog 2 or 3. Requires PHP Agent v10.1.0+.
The other option is to have the agent decorate log records with a token containing linking metadata and use an external log forwarder to send logs to New Relic. Supported frameworks for log decoration include:
- Monolog 2 or 3. Requires PHP Agent v10.13.0+.
* 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](/docs/logs/logs-context/get-started-logs-context#forwarding-details).
<Callout variant="important">
As of agent release 10.3.0 the logging metrics and agent log forwarding features are enabled by default.
</Callout>
All you need to do is install an agent version with log forwarding capabilities ([PHP agent 10.1.0 or higher](/docs/release-notes/agent-release-notes/php-release-notes/)). If forwarding is disabled, you can use this configuration:
Configuration file (`newrelic.ini`):
```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`](/docs/apm/agents/php-agent/configuration/php-agent-configuration/#cfg-application_logging_forwarding-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.application_logging.metrics.enabled`](/docs/apm/agents/php-agent/configuration/php-agent-configuration/#cfg-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.application_logging.forwarding` prefixed INI settings. Options available are:
* [`enabled`](/docs/apm/agents/php-agent/configuration/php-agent-configuration/#cfg-application_logging_forwarding-enabled)
* [`max_samples_stored`](/docs/apm/agents/php-agent/configuration/php-agent-configuration/#cfg-application_logging_forwarding-max_samples_stored)
* [`log_level`](/docs/apm/agents/php-agent/configuration/php-agent-configuration/#cfg-application_logging_forwarding-log-level)
If you are using the Monolog logging library (version 2 or 3) then you may also enable log context attributes. This converts logging context data
passed to Monolog into New Relic attributes. You can control this feature through settings `newrelic.application_logging.forwarding.context_data`
prefixed INI settings. Options available are:
* [`enabled`](/docs/apm/agents/php-agent/configuration/php-agent-configuration/#cfg-application_logging_forwarding_context_data-enabled)
* [`include`](/docs/apm/agents/php-agent/configuration/php-agent-configuration/#cfg-application_logging_forwarding_context_data-include)
* [`exclude`](/docs/apm/agents/php-agent/configuration/php-agent-configuration/#cfg-application_logging_forwarding_context_data-exclude)
<Callout variant="important">
If you have an existing log forwarding solution and are updating your agent to use automatic logs in context, be sure to <DNT>**disable your manual log forwarder**</DNT>. 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](/docs/logs/forward-logs/enable-log-management-new-relic#log-forwarding).
</Callout>
<Collapser id="2-decorate" title="Option 2: Let the agent decorate your logs."
Already have a log forwarder you like? We've got you covered! Language agents can decorate your logs with the linking metadata needed to provide access to automatic logs-in-context features.
This method requires that you install an [external log forwarder](/docs/logs/forward-logs/enable-log-management-new-relic#log-forwarding) 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](/docs/logs/forward-logs/forward-your-logs-using-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 <DNT>**disable your manual log forwarder**</DNT>. 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](/docs/logs/forward-logs/enable-log-management-new-relic#log-forwarding).
<Callout variant="important">
Local log decoration for the PHP agent does not directly alter log messages. Your logging framework configuration will need to be updated to write out the `NR-LINKING` token in messages.
</Callout>
If you choose to use log decoration to activate logs in context for PHP, first setup your PHP app.
1. Make sure you have already [set up logging in New Relic](/docs/logs/enable-log-management-new-relic/enable-log-monitoring-new-relic/enable-log-management-new-relic/). This includes configuring a supported log forwarder that collects your application logs and forwards these to New Relic.
2. [Install](/docs/agents/php-agent/installation/php-agent-installation-overview/) or [update](/docs/agents/php-agent/installation/update-php-agent/) to the latest PHP agent version, and [enable distributed tracing](/docs/distributed-tracing/enable-configure/quick-start/). Use [PHP agent version 10.13.0.1 or higher](/docs/release-notes/agent-release-notes/php-release-notes/) for logs decoration support.
3. Install [Monolog](https://github.com/Seldaek/monolog) version 2 or 3.
4. Configure logs decoration for PHP using the Monolog extension.
To enable local log decoration:
1. Disable automatic log forwarding:
```ini
newrelic.application_logging.forwarding.enabled = false
```
2. Enable local log decoration by the PHP agent:
```ini
newrelic.application_logging.local_decorating.enabled = true
```
3. The PHP agent will now add linking metadata to each Monolog log record. For this information to appear in the actual log messages it is necessary to set a Monolog Formatter for each Monolog Handler that includes the `%extra.NR-LINKING%` format specification at the end of the message. This is the necessary linking data for logs in context to work.
For example:
```php
<?php
use Monolog\Logger;
use Monolog\Formatter\LineFormatter;
use Monolog\Handler\StreamHandler;
$logger = new Logger('log');
$handler = new StreamHandler('php://stderr');
$logfmt = "%channel%.%level_name%: %message% %extra.NR-LINKING%\n";
$formatter = new LineFormatter($logfmt);
$handler->setFormatter($formatter);
$logger->pushHandler($handler);
```
Our decorator adds five attributes to every log `message` (plain text): `entity.guid`, `entity.name`, `hostname`, `trace.id`, and `span.id`. Example:
```
This is my log message. NR-LINKING|{entity.guid}|{hostname}|{trace.id}|{span.id}|{entity.name}|
```
5. To verify that you have configured the log appender correctly, run your application, then check your [logs data in New Relic](/docs/logs/log-management/ui-data/use-logs-ui/) 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](/docs/logs/log-management/troubleshooting/no-log-data-appears-ui/).
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.
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.
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.
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.