Module: NewRelic::Agent

Extended by:
Forwardable, Agent, SupportabilityHelper
Included in:
Agent
Defined in:
lib/new_relic/agent.rb,
lib/new_relic/agent/method_tracer.rb,
lib/new_relic/agent/distributed_tracing.rb,
lib/new_relic/agent/distributed_trace_payload.rb,
lib/new_relic/agent/external.rb,
lib/new_relic/agent/instrumentation/controller_instrumentation.rb,
lib/new_relic/agent/instrumentation/rack.rb,
lib/new_relic/agent/datastores.rb,
lib/new_relic/agent/messaging.rb,
lib/new_relic/agent/sql_sampler.rb,
lib/new_relic/agent/tracer.rb,
lib/new_relic/agent/transaction.rb,
lib/new_relic/agent/transaction_sampler.rb,
lib/new_relic/agent/transaction/external_request_segment.rb

Overview

This module contains most of the public API methods for the Ruby Agent.

For adding custom instrumentation to method invocations, see the docs for MethodTracer and MethodTracer::ClassMethods.

For information on how to trace transactions in non-Rack contexts, see Instrumentation::ControllerInstrumentation.

For general documentation about the Ruby agent, see: docs.newrelic.com/docs/agents/ruby-agent

Defined Under Namespace

Modules: Datastores, DistributedTracing, External, Instrumentation, Messaging, MethodTracer Classes: DistributedTracePayload, SqlSampler, Tracer, Transaction, TransactionSampler

Recording custom metrics collapse

SUPPORTABILITY_INCREMENT_METRIC =

Increment a simple counter metric.

metric_name should follow a slash separated path convention. Application specific metrics should begin with “Custom/”.

This method is safe to use from any thread.

'Supportability/API/increment_metric'.freeze

Recording custom metrics collapse

Recording custom errors collapse

Recording custom Insights events collapse

Manual agent configuration and startup/shutdown collapse

Ignoring or excluding data collapse

Adding custom attributes to traces collapse

Transaction naming collapse

Trace and Entity metadata collapse

Manual browser monitoring configuration collapse

Instance Method Details

#add_custom_attributes(params) ⇒ Object

Add attributes to the transaction trace, Insights Transaction event, and any traced errors recorded for the current transaction.

If Browser Monitoring is enabled, and the browser_monitoring.attributes.enabled configuration setting is true, these custom attributes will also be present in the script injected into the response body, making them available on Insights PageView events.


573
574
575
576
577
578
579
580
581
582
# File 'lib/new_relic/agent.rb', line 573

def add_custom_attributes(params) #THREAD_LOCAL_ACCESS
  record_api_supportability_metric(:add_custom_attributes)

  if params.is_a? Hash
    txn = Transaction.tl_current
    txn.add_custom_attributes(params) if txn
  else
    ::NewRelic::Agent.logger.warn("Bad argument passed to #add_custom_attributes. Expected Hash but got #{params.class}")
  end
end

#add_instrumentation(file_pattern) ⇒ Object

Add instrumentation files to the agent. The argument should be a glob matching ruby scripts which will be executed at the time instrumentation is loaded. Since instrumentation is not loaded when the agent is not running it's better to use this method to register instrumentation than just loading the files directly, although that probably also works.


420
421
422
423
# File 'lib/new_relic/agent.rb', line 420

def add_instrumentation(file_pattern)
  record_api_supportability_metric(:add_instrumentation)
  NewRelic::Control.instance.add_instrumentation file_pattern
end

#after_fork(options = {}) ⇒ Object

Register this method as a callback for processes that fork jobs.

If the master/parent connects to the agent prior to forking the agent in the forked process will use that agent_run. Otherwise the forked process will establish a new connection with the server.

Use this especially when you fork the process to run background jobs or other work. If you are doing this with a web dispatcher that forks worker processes then you will need to force the agent to reconnect, which it won't do by default. Passenger and Rainbows and Unicorn are already handled, nothing special needed for them.

Options:

  • :force_reconnect => true to force the spawned process to establish a new connection, such as when forking a long running process. The default is false–it will only connect to the server if the parent had not connected.

  • :keep_retrying => false if we try to initiate a new connection, this tells me to only try it once so this method returns quickly if there is some kind of latency with the server.


385
386
387
388
# File 'lib/new_relic/agent.rb', line 385

def after_fork(options={})
  record_api_supportability_metric(:after_fork)
  agent.after_fork(options) if agent
end

#browser_timing_headerObject

This method returns a string suitable for inclusion in a page - known as 'manual instrumentation' for Real User Monitoring. Can return either a script tag with associated javascript, or in the case of disabled Real User Monitoring, an empty string

This is the header string - it should be placed as high in the page as is reasonably possible - that is, before any style or javascript inclusions, but after any header-related meta tags

In previous agents there was a corresponding footer required, but all the work is now done by this single method.


728
729
730
731
732
733
# File 'lib/new_relic/agent.rb', line 728

def browser_timing_header
  record_api_supportability_metric(:browser_timing_header)

  return "" unless agent
  agent.javascript_instrumentor.browser_timing_header
end

#disable_all_tracingObject

Yield to the block without collecting any metrics or traces in any of the subsequent calls. If executed recursively, will keep track of the first entry point and turn on tracing again after leaving that block. This uses the thread local Tracer::State.


499
500
501
502
503
504
505
506
507
508
509
510
# File 'lib/new_relic/agent.rb', line 499

def disable_all_tracing
  record_api_supportability_metric(:disable_all_tracing)

  return yield unless agent

  begin
    agent.push_trace_execution_flag(false)
    yield
  ensure
    agent.pop_trace_execution_flag
  end
end

#disable_sql_recordingObject

This method sets the state of sql recording in the transaction sampler feature. Within the given block, no sql will be recorded

usage:

NewRelic::Agent.disable_sql_recording do
  ...
end

535
536
537
538
539
540
541
542
543
544
545
546
# File 'lib/new_relic/agent.rb', line 535

def disable_sql_recording
  record_api_supportability_metric(:disable_sql_recording)

  return yield unless agent

  state = agent.set_record_sql(false)
  begin
    yield
  ensure
    agent.set_record_sql(state)
  end
end

#disable_transaction_tracingObject

This method disables the recording of transaction traces in the given block. See also #disable_all_tracing


517
518
519
520
521
522
# File 'lib/new_relic/agent.rb', line 517

def disable_transaction_tracing
  Deprecator.deprecate :disable_transaction_tracing,
                       'disable_all_tracing or ignore_transaction'
  record_api_supportability_metric(:disable_transaction_tracing)
  yield
end

#drop_buffered_dataObject

Clear out any data the agent has buffered but has not yet transmitted to the collector.


406
407
408
409
# File 'lib/new_relic/agent.rb', line 406

def drop_buffered_data
  agent.drop_buffered_data if agent
  record_api_supportability_metric(:drop_buffered_data)
end

#get_transaction_nameObject

Get the name of the current running transaction. This is useful if you want to modify the default name.


621
622
623
624
625
626
627
628
629
# File 'lib/new_relic/agent.rb', line 621

def get_transaction_name #THREAD_LOCAL_ACCESS
  record_api_supportability_metric(:get_transaction_name)

  txn = Transaction.tl_current
  if txn
    namer = Instrumentation::ControllerInstrumentation::TransactionNamer
    txn.best_name.sub(Regexp.new("\\A#{Regexp.escape(namer.prefix_for_category(txn))}"), '')
  end
end

#ignore_apdexObject

This method disables the recording of Apdex metrics in the current transaction.


475
476
477
478
479
# File 'lib/new_relic/agent.rb', line 475

def ignore_apdex
  record_api_supportability_metric(:ignore_apdex)
  txn = NewRelic::Agent::Transaction.tl_current
  txn.ignore_apdex! if txn
end

#ignore_enduserObject

This method disables browser monitoring javascript injection in the current transaction.


486
487
488
489
490
# File 'lib/new_relic/agent.rb', line 486

def ignore_enduser
  record_api_supportability_metric(:ignore_enduser)
  txn = NewRelic::Agent::Transaction.tl_current
  txn.ignore_enduser! if txn
end

#ignore_error_filter(&block) ⇒ Object

Set a filter to be applied to errors that the Ruby Agent will track. The block should evalute to the exception to track (which could be different from the original exception) or nil to ignore this exception.

The block is yielded to with the exception to filter.

Return the new block or the existing filter Proc if no block is passed.


243
244
245
246
247
248
249
250
251
# File 'lib/new_relic/agent.rb', line 243

def ignore_error_filter(&block)
  record_api_supportability_metric(:ignore_error_filter)

  if block
    NewRelic::Agent::ErrorCollector.ignore_error_filter = block
  else
    NewRelic::Agent::ErrorCollector.ignore_error_filter
  end
end

#ignore_transactionObject

This method disables the recording of the current transaction. No metrics, traced errors, transaction traces, Insights events, slow SQL traces, or RUM injection will happen for this transaction.


464
465
466
467
468
# File 'lib/new_relic/agent.rb', line 464

def ignore_transaction
  record_api_supportability_metric(:ignore_transaction)
  txn = NewRelic::Agent::Transaction.tl_current
  txn.ignore! if txn
end

#linking_metadataObject

Returns a new hash containing trace and entity metadata that can be used to relate data to a trace or to an entity in APM.

This hash includes:

  • trace.id - The current trace id, if there is a current trace id. This value may be omitted.

  • span.id - The current span id, if there is a current span. This value may be omitted.

  • entity.name - The name of the current application. This is read from the app_name key in your config. If there are multiple application names, the first one is used.

  • entity.type - The entity type is hardcoded to the string 'SERVICE'.

  • entity.guid - The guid of the current entity.

  • hostname - The fully qualified hostname.


691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
# File 'lib/new_relic/agent.rb', line 691

def 
   = Hash.new
  [ENTITY_NAME_KEY] = config[:app_name][0]
  [ENTITY_TYPE_KEY] = ENTITY_TYPE
  [HOSTNAME_KEY] = Hostname.get

  if entity_guid = config[:entity_guid]
    [ENTITY_GUID_KEY] = entity_guid
  end

  if trace_id = Tracer.current_trace_id
    [TRACE_ID_KEY] = trace_id
  end
  if span_id = Tracer.current_span_id
    [SPAN_ID_KEY] = span_id
  end
  
end

#manual_start(options = {}) ⇒ Object

Call this to manually start the Agent in situations where the Agent does not auto-start.

When the app environment loads, so does the Agent. However, the Agent will only connect to the service if a web front-end is found. If you want to selectively monitor ruby processes that don't use web plugins, then call this method in your code and the Agent will fire up and start reporting to the service.

Options are passed in as overrides for values in the newrelic.yml, such as app_name. In addition, the option log will take a logger that will be used instead of the standard file logger. The setting for the newrelic.yml section to use (ie, RAILS_ENV) can be overridden with an :env argument.


353
354
355
356
357
358
# File 'lib/new_relic/agent.rb', line 353

def manual_start(options={})
  record_api_supportability_metric(:manual_start)

  raise "Options must be a hash" unless Hash === options
  NewRelic::Control.instance.init_plugin({ :agent_enabled => true, :sync_startup => true }.merge(options))
end

#notice_error(exception, options = {}) ⇒ Object

Send an error to New Relic.

Any option keys other than the ones listed here are treated as :custom_params.

Note: Previous versions of the agent allowed passing :request_params, but those are now ignored. If you need to record the request parameters, call this method inside a transaction or pass the information in :custom_params.

Most of the time, you do not need to specify the :uri or :metric options; only pass them if you are calling notice_error outside a transaction.

Options Hash (options):

  • :custom_params (Hash)

    Custom parameters to attach to the trace

  • :expected (Boolean)

    Only record the error trace (do not affect error rate or Apdex status)

  • :uri (String)

    Request path, minus request params or query string (usually not needed)

  • :metric (String)

    Metric name associated with the transaction (usually not needed)


281
282
283
284
285
286
287
288
289
290
291
292
# File 'lib/new_relic/agent.rb', line 281

def notice_error(exception, options={})
  record_api_supportability_metric(:notice_error)

  if options.has_key?(:trace_only)
    NewRelic::Agent.logger.log_once(:warn, :trace_only_deprecated,
      'Passing the :trace_only option to NewRelic::Agent.notice_error is deprecated. Please use :expected instead.')
    options[:expected] = options.delete(:trace_only)
  end

  Transaction.notice_error(exception, options)
  nil # don't return a noticed error datastructure. it can only hurt.
end

#record_custom_event(event_type, event_attrs) ⇒ Object

Record a custom event to be sent to New Relic Insights. The recorded event will be buffered in memory until the next time the agent sends data to New Relic's servers.

If you want to be able to tie the information recorded via this call back to the web request or background job that it happened in, you may want to instead use the add_custom_attributes API call to attach attributes to the Transaction event that will automatically be generated for the request.

A timestamp will be automatically added to the recorded event when this method is called.


322
323
324
325
326
327
328
329
330
# File 'lib/new_relic/agent.rb', line 322

def record_custom_event(event_type, event_attrs)
  record_api_supportability_metric(:record_custom_event)

  if agent && NewRelic::Agent.config[:'custom_insights_events.enabled']
    agent.custom_event_aggregator.record(event_type, event_attrs)
  end

  nil
end

#record_metric(metric_name, value) ⇒ Object

Record a value for the given metric name.

This method should be used to record event-based metrics such as method calls that are associated with a specific duration or magnitude.

metric_name should follow a slash separated path convention. Application specific metrics should begin with “Custom/”.

value should be either a single Numeric value representing the duration/ magnitude of the event being recorded, or a Hash containing :count, :total, :min, :max, and :sum_of_squares keys. The latter form is useful for recording pre-aggregated metrics collected externally.

This method is safe to use from any thread.


187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
# File 'lib/new_relic/agent.rb', line 187

def record_metric(metric_name, value) #THREAD_LOCAL_ACCESS
  record_api_supportability_metric(:record_metric)

  return unless agent

  if value.is_a?(Hash)
    stats = NewRelic::Agent::Stats.new

    stats.call_count = value[:count] if value[:count]
    stats.total_call_time = value[:total] if value[:total]
    stats.total_exclusive_time = value[:total] if value[:total]
    stats.min_call_time = value[:min] if value[:min]
    stats.max_call_time = value[:max] if value[:max]
    stats.sum_of_squares = value[:sum_of_squares] if value[:sum_of_squares]
    value = stats
  end
  agent.stats_engine.tl_record_unscoped_metrics(metric_name, value)
end

#require_test_helperObject

Require agent testing helper methods


428
429
430
431
# File 'lib/new_relic/agent.rb', line 428

def require_test_helper
  record_api_supportability_metric(:require_test_helper)
  require File.expand_path('../../../test/agent_helper', __FILE__)
end

#set_sql_obfuscator(type = :replace, &block) ⇒ Object

This method sets the block sent to this method as a sql obfuscator. The block will be called with a single String SQL statement to obfuscate. The method must return the obfuscated String SQL. If chaining of obfuscators is required, use type = :before or :after

type = :before, :replace, :after

Example:

NewRelic::Agent.set_sql_obfuscator(:replace) do |sql|
   my_obfuscator(sql)
end

449
450
451
452
# File 'lib/new_relic/agent.rb', line 449

def set_sql_obfuscator(type = :replace, &block)
  record_api_supportability_metric(:set_sql_obfuscator)
  NewRelic::Agent::Database.set_sql_obfuscator(type, &block)
end

#set_transaction_name(name, options = {}) ⇒ Object

Set the name of the current running transaction. The agent will apply a reasonable default based on framework routing, but in cases where this is insufficient, this can be used to manually control the name of the transaction. The category of transaction can be specified via the :category option:

  • :category => :controller indicates that this is a controller action and will appear with all the other actions.

  • :category => :task indicates that this is a background task and will show up in New Relic with other background tasks instead of in the controllers list

  • :category => :middleware if you are instrumenting a rack middleware call. The :name is optional, useful if you have more than one potential transaction in the #call.

  • :category => :uri indicates that this is a web transaction whose name is a normalized URI, where 'normalized' means the URI does not have any elements with data in them such as in many REST URIs.

The default category is the same as the running transaction.


611
612
613
614
# File 'lib/new_relic/agent.rb', line 611

def set_transaction_name(name, options={})
  record_api_supportability_metric(:set_transaction_name)
  Transaction.set_overriding_transaction_name(name, options[:category])
end

#shutdown(options = {}) ⇒ Object

Shutdown the agent. Call this before exiting. Sends any queued data and kills the background thread.


397
398
399
400
# File 'lib/new_relic/agent.rb', line 397

def shutdown(options={})
  record_api_supportability_metric(:shutdown)
  agent.shutdown if agent
end