Ruby agent configuration

If true, allows the Ruby agent to run.

Specify the application name used to aggregate data in the New Relic UI. To report data to multiple apps at the same time, specify a list of names separated by a semicolon ;. For example, MyApp or MyStagingApp;Instance1.

Your New Relic license key.

Sets the level of detail of log messages. Possible log levels, in increasing verbosity, are: error, warn, info or debug.

An array of ActiveSupport custom event names to subscribe to and instrument. For example,

• one.custom.event
• another.event
• a.third.event

Your New Relic user key. Required when using the New Relic REST API v2 to record deployments using the newrelic deployments command.

Backports the faster ActiveRecord connection lookup introduced in Rails 6, which improves agent performance when instrumenting ActiveRecord. Note that this setting may not be compatible with other gems that patch ActiveRecord.

Manual override for the path to your local CA bundle. This CA bundle will be used to validate the SSL certificate presented by New Relic's data collection service.

Enable or disable the capture of memcache keys from transaction traces.

When true, the agent captures HTTP request parameters and attaches them to transaction traces, traced errors, and TransactionError events.

If true, the agent will clear Tracer::State in Agent.drop_buffered_data.

Path to newrelic.yml. If undefined, the agent checks the following directories (in order):

• config/newrelic.yml
• newrelic.yml
• $HOME/.newrelic/newrelic.yml
• $HOME/newrelic.yml

Allows newrelic distributed tracing headers to be suppressed on outbound requests.

The exit handler that sends all cached data to the collector before shutting down is forcibly installed. This is true even when it detects scenarios where it generally should not be. The known use case for this option is when Sinatra runs as an embedded service within another framework. The agent detects the Sinatra app and skips the at_exit handler as a result. Sinatra classically runs the entire application in an at_exit block and would otherwise misbehave if the agent's at_exit handler was also installed in those circumstances. Note: send_data_on_exit should also be set to true in tandem with this setting.

If true, enables high security mode. Ensure you understand the implications of high security mode before enabling this setting.

A dictionary of label names and values that will be applied to the data sent from this agent. May also be expressed as a semicolon-delimited ; string of colon-separated : pairs. For example, Server:One;Data Center:Primary.

Defines a name for the log file.

Defines a path to the agent log file, excluding the filename.

Specifies a marshaller for transmitting data to the New Relic collector. Currently json is the only valid value for this setting.

When true, the agent transmits data about your app to the New Relic collector.

If true, uses Module#prepend rather than alias_method for ActiveRecord instrumentation.

Defines a host for communicating with the New Relic collector via a proxy server.

Defines a password for communicating with the New Relic collector via a proxy server.

Defines a port for communicating with the New Relic collector via a proxy server.

Defines a user for communicating with the New Relic collector via a proxy server.

Applies Language Agent Security Policy settings.

If true, enables the exit handler that sends data to the New Relic collector before shutting down.

When set to true, forces a synchronous connection to the New Relic collector during application startup. For very short-lived processes, this helps ensure the New Relic agent has time to report.

If true, tracer state storage is thread-local, otherwise, fiber-local

Defines the maximum number of seconds the agent should spend attempting to connect to the collector.

If true, enables capture of all HTTP request headers for all destinations.

An array of CLASS#METHOD (for instance methods) and/or CLASS.METHOD (for class methods) strings representing Ruby methods that the agent can automatically add custom instrumentation to. This doesn't require any modifications of the source code that defines the methods.

Use fully qualified class names (using the :: delimiter) that include any module or class namespacing.

Here is some Ruby source code that defines a render_png instance method for an Image class and a notify class method for a User class, both within a MyCompany module namespace:

module MyCompany
  class Image
    def render_png
      # code to render a PNG
    end
  end

  class User
    def self.notify
      # code to notify users
    end
  end
end

Given that source code, the newrelic.yml config file might request instrumentation for both of these methods like so:

automatic_custom_instrumentation_method_list:
  - MyCompany::Image#render_png
  - MyCompany::User.notify

That configuration example uses YAML array syntax to specify both methods. Alternatively, you can use a comma-delimited string:

automatic_custom_instrumentation_method_list: 'MyCompany::Image#render_png, MyCompany::User.notify'

Whitespace around the comma(s) in the list is optional. When configuring the agent with a list of methods via the NEW_RELIC_AUTOMATIC_CUSTOM_INSTRUMENTATION_METHOD_LIST environment variable, use this comma-delimited string format:

$
export NEW_RELIC_AUTOMATIC_CUSTOM_INSTRUMENTATION_METHOD_LIST='MyCompany::Image#render_png, MyCompany::User.notify'

If true, when the agent is in an application using Ruby on Rails, it will start after config/initializers run.

If true, enables collection of transaction traces.

If true, enables the collection of explain plans in transaction traces. This setting will also apply to explain plans in slow SQL traces if slow_sql.explain_enabled is not set separately.

Threshold (in seconds) above which the agent will collect explain plans. Relevant only when explain_enabled is true.

Maximum number of transaction trace nodes to record in a single transaction trace.

If true, the agent records Redis command arguments in transaction traces.

Obfuscation level for SQL queries reported in transaction trace nodes.

By default, this is set to obfuscated, which strips out the numeric and string literals.

• If you do not want the agent to capture query information, set this to none.
• If you want the agent to capture all query information in its original form, set this to raw.
• When you enable high security mode, this is automatically set to obfuscated.

Specify a threshold in seconds. The agent includes stack traces in transaction trace nodes when the stack trace duration exceeds this threshold.

Specify a threshold in seconds. Transactions with a duration longer than this threshold are eligible for transaction traces. Specify a float value or the string apdex_f.

A list of error classes that the agent should ignore.

If true, the agent collects TransactionError events.

If true, the agent captures traced errors and error count metrics.

A list of error classes that the agent should treat as expected.

A map of error classes to a list of messages. When an error of one of the classes specified here occurs, if its error message contains one of the strings corresponding to it here, that error will be treated as expected.

A comma separated list of status codes, possibly including ranges. Errors associated with these status codes, where applicable, will be treated as expected.

A map of error classes to a list of messages. When an error of one of the classes specified here occurs, if its error message contains one of the strings corresponding to it here, that error will be ignored.

A comma separated list of status codes, possibly including ranges. Errors associated with these status codes, where applicable, will be ignored.

Defines the maximum number of frames in an error backtrace. Backtraces over this amount are truncated in the middle, preserving the beginning and the end of the stack trace.

Defines the maximum number of TransactionError events reported per harvest cycle.

If true, enables auto-injection of the JavaScript header for page load timing (sometimes referred to as real user monitoring or RUM).

If true, enables auto-injection of Content Security Policy Nonce in browser monitoring scripts. For now, auto-injection only works with Rails 5.2+.

If true, enables transaction event sampling.

Defines the maximum number of transaction events reported from a single harvest.

If true, enables log decoration and the collection of log events and metrics.

If true, the agent captures log records emitted by your application.

Sets the minimum level a log event must have to be forwarded to New Relic.

This is based on the integer values of Ruby's Logger::Severity constants: https://github.com/ruby/ruby/blob/master/lib/logger/severity.rb

The intention is to forward logs with the level given to the configuration, as well as any logs with a higher level of severity.

For example, setting this value to "debug" will forward all log events to New Relic. Setting this value to "error" will only forward log events with the levels "error", "fatal", and "unknown".

Valid values (ordered lowest to highest):

• "debug"
• "info"
• "warn"
• "error"
• "fatal"
• "unknown"

A hash with key/value pairs to add as custom attributes to all log events forwarded to New Relic. If sending using an environment variable, the value must be formatted like: "key1=value1,key2=value2"

Defines the maximum number of log records to buffer in memory at a time.

If true, the agent decorates logs with metadata to link to entities, hosts, traces, and spans.

If true, the agent captures metrics related to logging for your application.

If false, all LLM instrumentation (OpenAI only for now) will be disabled and no metrics, events, or spans will be sent. AI Monitoring is automatically disabled if high_security mode is enabled.

If false, LLM instrumentation (OpenAI only for now) will not capture input and output content on specific LLM events.

The excluded attributes include:

• content from LlmChatCompletionMessage events

• input from LlmEmbedding events

  This is an optional security setting to prevent recording sensitive data sent to and received from your LLMs.

If true, enables capture of attributes for all destinations.

Prefix of attributes to exclude from all destinations. Allows * as wildcard at end.

Prefix of attributes to include in all destinations. Allows * as wildcard at end.

If true, the agent captures attributes from browser monitoring.

Prefix of attributes to exclude from browser monitoring. Allows * as wildcard at end.

Prefix of attributes to include in browser monitoring. Allows * as wildcard at end.

If true, the agent captures attributes from error collection.

Prefix of attributes to exclude from error collection. Allows * as wildcard at end.

Prefix of attributes to include in error collection. Allows * as wildcard at end.

If true, the agent captures attributes on span events.

Prefix of attributes to exclude from span events. Allows * as wildcard at end.

Prefix of attributes to include on span events. Allows * as wildcard at end.

If true, the agent captures attributes from transaction events.

Prefix of attributes to exclude from transaction events. Allows * as wildcard at end.

Prefix of attributes to include in transaction events. Allows * as wildcard at end.

If true, the agent captures attributes on transaction segments.

Prefix of attributes to exclude from transaction segments. Allows * as wildcard at end.

Prefix of attributes to include on transaction segments. Allows * as wildcard at end.

If true, the agent captures attributes from transaction traces.

Prefix of attributes to exclude from transaction traces. Allows * as wildcard at end.

Prefix of attributes to include in transaction traces. Allows * as wildcard at end.

If true, enables an audit log which logs communications with the New Relic collector.

List of allowed endpoints to include in audit log.

Specifies a path to the audit log file (including the filename).

Specify a list of constants that should prevent the agent from starting automatically. Separate individual constants with a comma ,. For example, "Rails::Console,UninstrumentedBackgroundJob".

Defines a comma-delimited list of executables that the agent should not instrument. For example, "rake,my_ruby_script.rb".

Defines a comma-delimited list of Rake tasks that the agent should not instrument. For example, "assets:precompile,db:migrate".

The AWS account ID for the AWS account associated with this app

If true, the agent will report source code level metrics for traced methods. See: https://docs.newrelic.com/docs/apm/agents/ruby-agent/features/ruby-codestream-integration/

DEPRECATED Please see: distributed_tracing.enabled.

If true, enables cross-application tracing when distributed_tracing.enabled is set to false.

If false, custom attributes will not be sent on events.

If true, the agent captures custom events.

• Specify a maximum number of custom events to buffer in memory at a time.
• When configuring the agent for AI monitoring, set to max value 100000. This ensures the agent captures the maximum amount of LLM events.

If false, the agent will not add database_name parameter to transaction or slow sql traces.

If false, the agent will not report datastore instance metrics, nor add host or port_path_or_id parameters to transaction or slow SQL traces.

If true, disables Action Cable instrumentation.

If true, disables Action Controller instrumentation.

If true, disables Action Mailbox instrumentation.

If true, disables Action Mailer instrumentation.

If true, disables Active Job instrumentation.

If true, disables Active Storage instrumentation.

If true, disables Active Support instrumentation.

If true, disables Active Record instrumentation.

If true, disables instrumentation for Active Record 4+

If true, the agent won't sample the CPU usage of the host process.

If true, the agent won't measure the depth of Delayed Job queues.

If true, disables the use of GC::Profiler to measure time spent in garbage collection

If true, the agent won't sample the memory usage of the host process.

If true, the agent won't wrap third-party middlewares in instrumentation (regardless of whether they are installed via Rack::Builder or Rails).

If true, disables the collection of sampler metrics. Sampler metrics are metrics that are not event-based (such as CPU time or memory usage).

If true, disables Sequel instrumentation.

If true, disables Sidekiq instrumentation.

If true, disables agent middleware for Roda. This middleware is responsible for advanced feature support such as page load timing and error collection.

If true, disables agent middleware for Sinatra. This middleware is responsible for advanced feature support such as cross application tracing, page load timing, and error collection.

# newrelic.yml

  cross_application_tracer:
    enabled: true
  distributed_tracing:
    enabled: false

If true, disables view instrumentation.

If true, the agent won't sample performance measurements from the Ruby VM.

Distributed tracing lets you see the path that a request takes through your distributed system. Enabling distributed tracing changes the behavior of some New Relic features, so carefully consult the transition guide before you enable this feature.

If true, the agent captures Elasticsearch queries in transaction traces.

If true, the agent obfuscates Elasticsearch queries in transaction traces.

If true, the agent uses Heroku dyno names as the hostname.

Ordinarily the agent reports dyno names with a trailing dot and process ID (for example, worker.3). You can remove this trailing data by specifying the prefixes you want to report without trailing data (for example, worker).

Configures the hostname for the trace observer Host. When configured, enables tail-based sampling by sending all recorded spans to a trace observer for further sampling decisions, irrespective of any usual agent sampling decision.

Configures the TCP/IP port for the trace observer Host

If true (the default), data sent to the trace observer is batched instead of sending each span individually.

Configure the compression level for data sent to the trace observer.

May be one of: :none, :low, :medium, :high.

Set the level to :none to disable compression.

Controls auto-instrumentation of ActiveSupport::BroadcastLogger at start up. May be one of: auto, prepend, chain, disabled. Used in Rails versions >= 7.1.

Controls auto-instrumentation of ActiveSupport::Logger at start up. May be one of: auto, prepend, chain, disabled. Used in Rails versions below 7.1.

Controls auto-instrumentation of Async::HTTP at start up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of bunny at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of the ruby-kafka library at start-up. May be one of auto, prepend, chain, disabled.

Controls auto-instrumentation of the opensearch-ruby library at start-up. May be one of auto, prepend, chain, disabled.

Controls auto-instrumentation of the rdkafka library at start-up. May be one of auto, prepend, chain, disabled.

Controls auto-instrumentation of the aws-sdk-sqs library at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of the aws-sdk-dynamodb library at start-up. May be one of auto, prepend, chain, disabled.

Controls auto-instrumentation of the Fiber class at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of the concurrent-ruby library at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of Curb at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of Delayed Job at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of the elasticsearch library at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of ethon at start up. May be one of auto, prepend, chain, disabled

Controls auto-instrumentation of Excon at start-up. May be one of: enabled, disabled.

Controls auto-instrumentation of Grape at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of gRPC clients at start-up. May be one of: auto, prepend, chain, disabled.

Specifies a list of hostname patterns separated by commas that will match gRPC hostnames that traffic is to be ignored by New Relic for. New Relic's gRPC client instrumentation will ignore traffic streamed to a host matching any of these patterns, and New Relic's gRPC server instrumentation will ignore traffic for a server running on a host whose hostname matches any of these patterns. By default, no traffic is ignored when gRPC instrumentation is itself enabled. For example, "private.com$,exception.*"

Controls auto-instrumentation of gRPC servers at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of HTTPClient at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of http.rb gem at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of httpx at start up. May be one of auto, prepend, chain, disabled

Controls auto-instrumentation of Ruby standard library Logger at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of the LogStasher library at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of dalli gem for Memcache at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of memcached gem for Memcache at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of memcache-client gem for Memcache at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of Mongo at start-up. May be one of: enabled, disabled.

Controls auto-instrumentation of Net::HTTP at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of the ruby-openai gem at start-up. May be one of: auto, prepend, chain, disabled. Defaults to disabled in high security mode.

Controls auto-instrumentation of Puma::Rack. When enabled, the agent hooks into the to_app method in Puma::Rack::Builder to find gems to instrument during application startup. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of Puma::Rack::URLMap at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of Rack. When enabled, the agent hooks into the to_app method in Rack::Builder to find gems to instrument during application startup. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of Rack::URLMap at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of rake at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of Redis at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of resque at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of Roda at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of Sinatra at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of Stripe at startup. May be one of: enabled, disabled.

Controls auto-instrumentation of ViewComponent at startup. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of the Thread class at start-up to allow the agent to correctly nest spans inside of an asynchronous transaction. This does not enable the agent to automatically trace all threads created (see instrumentation.thread.tracing). May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of the Thread class at start-up to automatically add tracing to all Threads created in the application.

Controls auto-instrumentation of the Tilt template rendering library at start-up. May be one of: auto, prepend, chain, disabled.

Controls auto-instrumentation of Typhoeus at start-up. May be one of: auto, prepend, chain, disabled.

If true, the agent will collect metadata about messages and attach them as segment parameters.

If true, the agent captures Mongo queries in transaction traces.

If true, the agent obfuscates Mongo queries in transaction traces.

If true, the agent captures OpenSearch queries in transaction traces.

If true, the agent obfuscates OpenSearch queries in transaction traces.

Specify a custom host name for display in the New Relic UI.

Specify an Array of Rake tasks to automatically instrument. This configuration option converts the Array to a RegEx list. If you'd like to allow all tasks by default, use rake.tasks: [.+]. No rake tasks will be instrumented unless they're added to this list. For more information, visit the New Relic Rake Instrumentation docs.

Timeout for waiting on connect to complete before a rake task

Define transactions you want the agent to ignore, by specifying a list of patterns matching the URI you want to ignore. For more detail, see the docs on ignoring specific transactions.

If true, the security agent is loaded (a Ruby 'require' is performed)

If true, the security agent is started (the agent runs in its event loop)

Defines the mode for the security agent to operate in. Currently only IAST is supported

Defines the endpoint URL for posting security-related data

If true, enables RCI (remote code injection) detection

If true, enables RXSS (reflected cross-site scripting) detection

If true, enables deserialization detection

The port the application is listening on. This setting is mandatory for Passenger servers. Other servers should be detected by default.

Defines the request body limit to process in security events (in KB). The default value is 300, for 300KB.

If true, the agent will operate in a streamlined mode suitable for use with short-lived serverless functions. NOTE: Only AWS Lambda functions are supported currently and this option is not intended for use without New Relic's Ruby Lambda layer offering.

An array of strings that will collectively serve as an allowlist for filtering which Sidekiq job arguments get reported to New Relic. To capture any Sidekiq arguments, 'job.sidekiq.args.*' must be added to the separate :'attributes.include' configuration option. Each string in this array will be turned into a regular expression via Regexp.new to permit advanced matching. For job argument hashes, if either a key or value matches the pair will be included. All matching job argument array elements and job argument scalars will be included.

An array of strings that will collectively serve as a denylist for filtering which Sidekiq job arguments get reported to New Relic. To capture any Sidekiq arguments, 'job.sidekiq.args.*' must be added to the separate :'attributes.include' configuration option. Each string in this array will be turned into a regular expression via Regexp.new to permit advanced matching. For job argument hashes, if either a key or value matches the pair will be excluded. All matching job argument array elements and job argument scalars will be excluded.

If true, the agent collects slow SQL queries.

Specify a threshold in seconds. The agent collects slow SQL queries and explain plans that exceed this threshold.

If true, the agent collects explain plans in slow SQL queries. If this setting is omitted, the transaction_tracer.explain_enabled setting will be applied as the default setting for explain plans in slow SQL as well.

Defines an obfuscation level for slow SQL queries. Valid options are obfuscated, raw, or none.

Generate a longer sql_id for slow SQL traces. sql_id is used for aggregation of similar queries.

If true, enables span event sampling.

Sets the maximum number of span events to buffer when streaming to the trace observer.

• Defines the maximum number of span events reported from a single harvest. Any Integer between 1 and 10000 is valid.'
• When configuring the agent for AI monitoring, set to max value 10000.This ensures the agent captures the maximum amount of distributed traces.

If true, the agent strips messages from all exceptions except those in the allowlist. Enabled automatically in high security mode.

Specify a list of exceptions you do not want the agent to strip when strip_exception_messages is true. Separate exceptions with a comma. For example, "ImportantException,PreserveMessageException".

An array of strings to specify which keys inside a Stripe event's user_data hash should be reported to New Relic. Each string in this array will be turned into a regular expression via Regexp.new to permit advanced matching. Setting the value to ["."] will report all user_data.