Node.js: Configure logs in context

APM logs in context connects your logs with all of your telemetry data for your apps, hosts, and other entities. Bringing all of this data together in a single tool helps you quickly:

Cut through the noise of thousands of logs when troubleshooting time-critical issues, so you automatically see only the most relevant logs.
Navigate within multiple types of telemetry data, and have the data correlate back to the original issue.
Easily drill down into more detailed information from the same place in the UI.
Find the log lines that you need to identify and resolve a problem.

For more information, including examples, learn how to get started with APM logs in context.

Automatic logs in context options

With application logging, your APM agent automatically collects and contextualizes your logs.

You have three options to configure APM logs in context to send your app's logs and linking metadata automatically to New Relic.

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, your logs will include span.id, trace.id, hostname, entity.guid, and entity.name. These attributes automatically link your logs to spans, traces, and other telemetry, making it easier to troubleshoot.

All you need to do is install an agent version with log forwarding capabilities (Node.js agent 8.11.0 or higher), and update your configuration to enable forwarding.

newrelic.js:

application_logging: {
  forwarding: {
    enabled: true
  }
}

Environment variable:

NEW_RELIC_APPLICATION_LOGGING_FORWARDING_ENABLED=true

This option may be on by default in a future agent version.

Optional adjustments:

Once this is enabled, you also have control over the maximum number of logs sent to New Relic every minute. The default value is 10,000. If more than 10,000 logs are received in a 60-second window, your logs will begin to be sampled.

Set it to a higher number to receive more logs. Set it to a lower number to receive fewer logs. Any integer up to 100,000 is valid. Increasing this value may increase the agent's utilization of CPU and RAM.

newrelic.js:

application_logging: {
  forwarding: {
    max_samples_stored: 10000
  }
}

Environment variable:

NEW_RELIC_APPLICATION_LOGGING_FORWARDING_MAX_SAMPLES_STORED: 10000

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 log lines. Depending on your account, this could result in double billing. For more information, follow the procedures to disable your specific log forwarder.

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 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.

This option should also not be used with the manual log decorating formatter. If you have references to the manual formatter in your codebase, please remove them before enabling this option.

If you want to use this option, make sure you have the in-agent forwarding configuration option disabled.
newrelic.js:
```
application_logging: {
  forwarding: {
    enabled: false
  }
}
```
Enable log decorating in your configuration, then relaunch the agent to start decorating your logs.
newrelic.js:
```
application_logging: {
  local_decorating: {
    enabled: true
  }
}
```
Environment variable:
```
NEW_RELIC_APPLICATION_LOGGING_LOCAL_DECORATING_ENABLED=true
```
Our decorator adds five attributes to every log message: 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}|
```
Some attributes may be empty if the log occurred outside a transaction or if they are not applicable to your application's context.
We recommend this option over manually using one of our log enrichers.

Before language agents had the ability to forward and decorate logs, you could enable logs in context by updating your application to use a framework-specific log enricher. This option is still supported, but is no longer encouraged. For instructions to use this approach, see Manual logs in context option.

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.

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 APM 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 APM agent log data but is not enabled by default. If you do enable application logging, it 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

To enable logs in context for APM apps monitored by Node.js, you can use our manual installation option.

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 Node.js agent version, and enable distributed tracing. Use Node.js agent version 6.2.0 or higher for logs in context.
Install Winston 3.0.0 or higher or Pino 7.0.0 or higher to enrich your log data.
In your agent configuration, set application_config.enabled to false. (Otherwise, the agent will automatically instrument your logger and calling these enrichers yourself will do nothing.)
Configure logs in context for Node.js using the appropriate log extension.

To install the Winston log enricher, enter the following command into your terminal or command line interface:
bash
```
$npm install @newrelic/winston-enricher
```

In your application code, update your logging configuration to add the newrelicFormatter:

// index.js
require('newrelic')
const winston = require('winston')
const newrelicFormatter = require('@newrelic/winston-enricher')(winston)

The New Relic formatter can be used individually or combined with other formatters as the final format.

format: winston.format.combine(
  winston.format.label({label: 'test'}),
  newrelicFormatter()
)

To install the Pino log enricher, enter the following command into your terminal or command line interface:
bash
```
$npm install @newrelic/pino-enricher
```
In your application code, update your logging configuration to add the New Relic Pino plugin:
```
// index.js
require('newrelic')
const nrPino = require('@newrelic/pino-enricher')
const pino = require('pino')
const logger = pino(nrPino())
```
The New Relic formatter can be used individually or combined with other formatters as the final format.

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 you'd like to see a working example of logs in context, take a look at our example application.

What's next?

After you set up APM logs in context, make the most of your logging data:

Explore the logging data across your platform with our Logs UI.
See your logs in context of your app's performance in the APM UI. Troubleshoot errors with distributed tracing, stack traces, application logs, and more.
Get deeper visibility into both your application and your platform performance data by forwarding your logs with our infrastructure monitoring agent. Review your infrastructure logs in the UI.
Set up alerts.
Query your data and create dashboards.

Automatic logs in context options

Option 1 (simplest): Let the agent decorate and forward your logs.

Option 2: Let the agent decorate your logs.

Option 3: Use the manual process to forward and decorate logs.