Ruby: Configure logs in context

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 (Ruby agent 8.6.0 or higher), and update your configuration to enable forwarding.

newrelic.yml:

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.

newrelic.yml:

application_logging:
  forwarding:
    max_samples_stored: 10_000

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.

1. If you want to use this option, make sure you have the in-agent forwarding configuration option disabled.

   newrelic.yml:

   application_logging:
      forwarding:
        enabled: false

   Copy

2. Enable log decorating in your configuration, then relaunch the agent to start decorating your logs.

   newrelic.yml:

   application_logging:
     local_decorating:
       enabled: true

   Copy

   Environment variable:

   NEW_RELIC_APPLICATION_LOGGING_LOCAL_DECORATING_ENABLED=true

   Copy

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

   Copy

   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 the manual decorating formatter, NewRelic::Agent::Logging::DecoratingFormatter.

Before language agents had the ability to forward and decorate logs, you could enable logs in context by updating your application to use the NewRelic::Agent::Logging::DecoratingFormatter to send linking metadata.

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.

Rails logging is controlled by two components:

• A logger you can customize by setting config.logger

• A log formatter you can customize by setting config.log_formatter)

  In most cases, you should configure logs in context by setting config.log_formatter to the DecoratingFormatter in your Rails application. For more information about Rails configuration, see the rubyonrails.org documentation.

  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

  Copy

  This configuration uses the New Relic formatter for log messages, but the remaining configuration is provided by the other Rails settings.

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

• logging
• semantic logger
• rails_stdout_logger
• rails_12factor

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

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.

To configure this extension with the lograge gem, follow standard procedures in this doc for Ruby on Rails configuration. No additional configuration is required for the lograge gem.

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

module ________
  class Application < Rails::Application

    ...

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