Configure logs in context for Ruby

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. Read on to learn how to configure logs in context and start getting log data.

Compatibility and requirements

To use log management with the Ruby agent, ensure your configuration meets the following requirements:

Configure logs in context with log management

To configure logs in context with Ruby:

  1. Enable log management with a compatible log forwarding plugin.
  2. Install or update the Ruby agent.
  3. Configure logs in context for Ruby.
  4. Optional: Advanced configuration.
  5. Check for logging data.

Enable log management

Confirm that you have log management enabled, with a compatible log forwarding plugin installed to send your application logs to New Relic.

Install or update the Ruby agent

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

Configure logs in context for Ruby

Configure for Rails

Rails logging is controlled by two components: a logger (customizable by setting config.logger) and a log formatter (customizable by setting config.log_formatter). In most cases, logs in context should be configured by setting config.log_formatter to the DecoratingFormatter 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.

Please note that Logs in Context for Ruby does not currently support tagged logging; if you are initializing your logger with a log_tags argument, your custom tags may not appear on the final version of your logs.

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

Configure 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 configure 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:

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

Incompatible gems

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

What's next?

Now that you've set up APM logs in context, here are some potential next steps:

For more help