Ruby Agent Configuration

The New Relic Agent can be configured with settings in a configuration file as well as programmatically. This article summarizes the configuration options available for the Ruby Agent.

The agent by default loads its configuration from the file newrelic.yml located in either the config subdirectory or working directory itself. This file is installed automatically when the plugin is installed but you should also receive a version via e-mail pre-configured with your license key.

The newrelic.yml file is a standard yaml configuration file. There is a defaults section at the top, and sections below for each environment (e.g. Development, Testing and Production).

This documentation applies to the latest release of the agent. For details on earlier versions, refer to the comments in the newrelic.yml itself.

General Configuration

• license_key - This is where the key from your RPM account goes. The key is used to locate the correct account to store data into when the agent connects to RPM

• agent_enabled - Use this setting to force the agent to run or not run. Default is 'auto' which means the agent will install and run only if a valid dispatcher such as Mongrel is running. This prevents it from running with Rake or the console. Set to false to completely turn the agent off regardless of the other settings. Set to true when it seems like the agent is not starting up because it is not detecting your dispatcher.
  

• app_name - This is the name of your application. The name is used to create an automatic "application definition" in RPM.
  

• monitor_mode - Whether or not the agent will send data to the server. When "true", the agent collects performance data about your application and reports this data to the NewRelic RPM service at newrelic.com. Set to false when you don't want the agent to connect to the server (using up a host license).
  

• developer_mode - In Rails applications, having developer mode set to true installs the New Relic Developer Mode. This should generally be false in all environments except development mode since it introduces high overhead that would be intolerable in production.

• apdex_t - Sets the 'T' value, the response time threshold for a satisfying transaction, for this application's apdex score. The default is 0.5 seconds. Read more about Apdex.

• log_level - This sets the log level for messages appearing in newrelic_agent.log.

• ssl - This sets whether or not to use SSL when communicating with RPM. Default is false.

• verify_certificate - (Experimental) When SSL is enabled, this setting enable verification of the SSL certificate sent by the server. Only enable it if the data you send us needs end-to-end verified certificates. Setting it to true may cause the agent to block your application during the time it is looking up the host name.

• capture_params - This determines whether transaction tracer and error collector should capture HTTP parameters and transmit them to RPM. Default is false.

Proxy Configuration

The following settings are used when a proxy host exists between your application and collector.newrelic.com.

• proxy_host
• proxy_port
• proxy_user
• proxy_pass

Transaction Tracer (Silver level and above)

Transaction Tracing is a feature in the agent which collects detailed information on a selection of transactions including a summary of the calling sequence, a breakdown of time spent, and a list of SQL queries and their query plans (on mysql and postgresql).

Transaction Tracing can be customized in the newrelic.yml and tuned programmatically to collect important extra detail.

In the newrelic.yml these options are indented under the key transaction_tracer:

• enabled - This sets whether transaction tracer is enabled or not. This only works for silver or gold subscription levels

• transaction_threshold - Threshold in seconds for when to collect a transaction trace. When the response time of a controller action exceeds this threshold, a transaction trace will be recorded and sent to RPM. Valid values are any float value, or (default) apdex_f, which will use the threshold for an dissatisfying Apdex controller action - four times the Apdex T value.

• record_sql - Chooses which SQL recording policy to use. Options are off, which records nothing, obfuscated, which records an obfuscated version of the SQL, or raw, which records the SQL exactly as it is issued to the database. Default is obfuscated.

• stack_trace_threshold - Sets the threshold (in seconds) for which slow queries collect a stack trace of the calling code.

• explain_enabled - Determines whether the agent will capture query plans for slow SQL queries. Only supported in mysql and postgres. Should be set to false when using other adapters.

• explain_threshold - Threshold in seconds for query execution time below which query plans will not not be captured. Relevant only when explain_enabled is true. Default is 0.5 seconds.

By default, transaction traces and error snapshots both record the http request parameters. These are displayed in RPM when viewing transaction traces and error snapshots. They are helpful to have because they provide context about the request that may be pertinent in analyzing what happened.

Transaction traces and error snapshots can also be annotated with custom key/value pairs. This is helpful because even more context can be provided. For example, annotating an account name could be helpful in knowing which customer was having a problem.

At New Relic, we annotate every request with a user's email address, account name, and which shard their data lives on. Notice in this screen shot that these fields show up in the "Custom" section of the transaction trace:

To annotate key/value pairs into transaction traces and error snapshots, make the following call from within your application:

NewRelic::Agent.add_custom_parameters(:key => value)

Note: There is no way to only add this data for requests which will trigger a transaction trace or error snapshot. Always add the custom parameters and they will be picked up by slow transactions or transactions with errors.

If your transaction traces have long periods of time where the New Relic Agent probes have zero visibility, you can add visibility with custom method instrumentation. To instrument a method in your application so that it shows up in Transaction Traces, add the following code to the class to instrument:

add_method_tracer :some_method, 'Custom/<class>/<method>', :metric => false

The :metric => false option tells the Agent to have this probe only participate in transaction traces and not produce streams of metric data, which would not be visible except in Custom Dashboards.

CAUTION - adding probes to your code adds overhead. Each probe burns about 20 microseconds of CPU. Be careful not to probe a method that's called frequently in a loop.

Error Collector (Silver level and above)

The agent will collect and report all uncaught exceptions. Several configuration options allow you to customize the error collection.

These options are indented under the key error_collector:

• enabled - sets whether or not error collector is enabled

• capture_source - sets whether or not to capture source code with ActionView errors

• ignore_errors - A comma separated list of Exception classes which will be ignored

In addition, the error collector can be customized programmatically for more control over filtering. In your application initialization, you can register a block with the Agent to be called when an error is detected. The block should return the error to record, or nil if the error is to be ignored. For example:

  config.after_initialize do
    NewRelic::Agent.ignore_error_filter do |error|
      if error.message =~ /gateway down/
        nil
      elsif
        error.class.name == "InvalidLicenseException"
        StandardError.new "We should never see this..."
      else
        error
      end
    end
  end

Updating the newrelic.yml file after new releases

A template for the newrelic.yml file can always be found in the base directory of the agent plugin or gem.

When you update to new versions of the plugin, it's a good idea to examine or diff config/newrelic.yml and newrelic.yml in the installation directory to take advantage of new configuration options.

Updating the plugin does not automatically update config/newrelic.yml.