Enable logs-in-context for Ruby

BETA

Combined with New Relic Logs, logs-in-context for the Ruby agent connects your Logs and APM data in New Relic, giving full context to high-level events and providing high value data to specific log lines. This document explains how to enable this feature and get started using it.

New Relic's logs-in-context (linking logs directly to Applications, APM errors, and APM traces and spans) for New Relic Logs is currently available as a beta feature. Your use of the early access service is at your own risk. New Relic disclaims all warranties, express or implied, regarding the beta services.

Compatibility and requirements

To use New Relic Logs with the Ruby agent, ensure your configuration meets the following requirements:

New Relic Logs must be enabled and a compatible logging plugin must be installed prior to enabling logs-in-context. For more information, see Introduction to New Relic Logs.

Enable logs-in-context with New Relic Logs

To enable New Relic logs-in-context with Ruby:

  1. Install or update the Ruby agent.
  2. Enable and configure logging.
  3. Optional: Advanced configuration.
  4. Check for logging data.

Install or update the Ruby agent

Install or update to the most recent Ruby agent version, and enable distributed tracing.

Enable logs-in-context for Ruby

Enable for Rails

In most cases, the DecoratingFormatter should be used in your Rails application. For more guidance regarding Rails configuration, see Configuring Rails Applications.

In your application's config, require 'newrelic_rpm', then add the following line:

module ________
  class Application < Rails::Application

    ...

    config.log_formatter = ::NewRelic::Agent::Logging::DecoratingFormatter.new
  end
end

This will use the New Relic formatter to format log messages, but the rest of the logging configuration will be provided by the other Rails config settings.

Rails advanced configuration

If setting the log_formatter option doesn't meet your needs, replace the entire Rails logger with an instance of the New Relic logger. Provide the parameters to the logger's constructor, like this:

module ________
  class Application < Rails::Application

    ...

    config.logger = ::NewRelic::Agent::Logging::DecoratingLogger.new(
      "log/application.log", #etc...
    )
  end
end

Enable for Ruby without Rails

For non-Rails applications, use the DecoratingLogger in place of the Ruby standard ::Logger, like this:

logger = ::NewRelic::Agent::Logging::DecoratingLogger.new(
	'log/application.log', #etc...
)
...
  
logger.info(...)

The DecoratingLogger is a drop-in replacement for the Ruby standard ::Logger. Their constructors accept the same parameters.

Advanced configuration

Custom logger configuration

To use our logging extension with a different logging implementation, or your own custom logger, use the DecoratingFormatter.

Example:

module ________
  class Application < Rails::Application

    ...

    config.logger = ::YourCustomLoggerImplementation.new(
      $stdout,
      formatter: ::NewRelic::Agent::Logging::DecoratingFormatter.new
    )
  end
end

Lograge configuration

To enable this extension with the lograge gem, there is no additional configuration required.

Check for logging data

If you have configured your logging in /config/application.rb, or in /config/environments/development.rb, run your application locally and check its logging output. You should see some output like this:

{"entity.name":"your_app_name","entity.type":"SERVICE","hostname":"79bcbf8d","trace.id":"79bcbf8d","span.id":"00fc7d46","timestamp":1567701375543,"message":"example log message one","log.level":"DEBUG"}
{"entity.name":"your_app_name","entity.type":"SERVICE","hostname":"79bcbf8d","trace.id":"79bcbf8d","span.id":"6754870b","timestamp":1567702843604,"message":"example log message two","log.level":"DEBUG"}

If you have deployed this application to an environment with a log forwarder, your application's logs will appear in the New Relic Logs UI with metadata linking them to a trace and a span. You can find them using a query like this:

service.name:"your_app_name" has:trace.id

If you see JSON logs in your application's output, but no logs returned by a query like the above, check your log forwarder.

Troubleshooting

If the logs from your application are not formatted in JSON with fields like trace.id and span.id, there may be a problem with the configuration of the New Relic Logging Extension.

Check that:

  • the application is using a supported logging framework.
  • the configuration has been applied to all the environments where you would like to use the New Relic Logging Extension.
  • there is not another logger configured later in the configuration of the application.

Incompatibilities

The New Relic decorating logger is known to be incompatible with the following gems:

What's next?

Once you've enabled logs-in-context, here are some potential next steps:

For more help

Recommendations for learning more: