Module: NewRelic::Agent

Extended by:
Agent
Included in:
Agent
Defined in:
lib/new_relic/agent.rb,
lib/new_relic/agent/agent.rb,
lib/new_relic/agent/worker_loop.rb,
lib/new_relic/agent/stats_engine.rb,
lib/new_relic/agent/method_tracer.rb,
lib/new_relic/agent/error_collector.rb,
lib/new_relic/agent/transaction_sampler.rb,
lib/new_relic/agent/instrumentation/rack.rb,
lib/new_relic/agent/stats_engine/samplers.rb,
lib/new_relic/agent/samplers/object_sampler.rb,
lib/new_relic/agent/stats_engine/metric_stats.rb,
lib/new_relic/agent/stats_engine/transactions.rb,
lib/new_relic/agent/instrumentation/active_record_instrumentation.rb

Overview

The NewRelic Agent collects performance data from ruby applications in realtime as the application runs, and periodically sends that data to the NewRelic server.

Defined Under Namespace

Modules: BusyCalculator, CollectionHelper, Instrumentation, MethodTracer, Samplers Classes: Agent, BackgroundLoadingError, ErrorCollector, ForceDisconnectException, ForceRestartException, IgnoreSilentlyException, LicenseException, PostTooBigException, Sampler, ServerError, ShimAgent, StatsEngine, TransactionSampleBuilder, TransactionSampler, WorkerLoop

Instance Method Summary collapse

Instance Method Details

#abort_transaction!Object

Cancel the collection of the current transaction in progress, if any. Only affects the transaction started on this thread once it has started and before it has completed.



248
249
250
251
252
253
# File 'lib/new_relic/agent.rb', line 248

def abort_transaction!
  # The class may not be loaded if the agent is disabled
  if defined? NewRelic::Agent::Instrumentation::MetricFrame
    NewRelic::Agent::Instrumentation::MetricFrame.abort_transaction!
  end
end

#add_custom_parameters(params) ⇒ Object Also known as: add_request_parameters

Add parameters to the current transaction trace on the call stack.



294
295
296
# File 'lib/new_relic/agent.rb', line 294

def add_custom_parameters(params)
  agent.add_custom_parameters(params)
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.



194
195
196
# File 'lib/new_relic/agent.rb', line 194

def add_instrumentation file_pattern
  NewRelic::Control.instance.add_instrumentation file_pattern
end

#agentObject Also known as: instance

The singleton Agent instance. Used internally.



137
138
139
140
# File 'lib/new_relic/agent.rb', line 137

def agent #:nodoc:
  raise "Plugin not initialized!" if @agent.nil?
  @agent
end

#agent=(new_instance) ⇒ Object

:nodoc:



142
143
144
# File 'lib/new_relic/agent.rb', line 142

def agent= new_instance #:nodoc:
  @agent = new_instance
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 newrelic_untrace



259
260
261
262
263
264
# File 'lib/new_relic/agent.rb', line 259

def disable_all_tracing
  agent.push_trace_execution_flag(false)
  yield
ensure
  agent.pop_trace_execution_flag
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


225
226
227
228
229
230
231
232
# File 'lib/new_relic/agent.rb', line 225

def disable_sql_recording
  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



236
237
238
239
240
241
242
243
# File 'lib/new_relic/agent.rb', line 236

def disable_transaction_tracing
  state = agent.set_record_tt(false)
  begin
    yield
  ensure
    agent.set_record_tt(state)
  end
end

#get_stats(metric_name, use_scope = false) ⇒ Object Also known as: get_stats_no_scope

Get or create a statistics gatherer that will aggregate numerical data under a metric name.

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

Return a NewRelic::Stats that accepts data via calls to add_data_point(value).



156
157
158
# File 'lib/new_relic/agent.rb', line 156

def get_stats(metric_name, use_scope=false)
  @agent.stats_engine.get_stats(metric_name, use_scope)
end

#ignore_error_filter(&block) ⇒ Object

Set a filter to be applied to errors that RPM will track. The block should return 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.



277
278
279
# File 'lib/new_relic/agent.rb', line 277

def ignore_error_filter(&block)
  agent.error_collector.ignore_error_filter(&block)
end

#is_execution_traced?Boolean

Check to see if we are capturing metrics currently on this thread.

Returns:

  • (Boolean)


267
268
269
# File 'lib/new_relic/agent.rb', line 267

def is_execution_traced?
  Thread.current[:newrelic_untraced].nil? || Thread.current[:newrelic_untraced].last != false      
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 RPM 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 RPM.

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.



176
177
178
179
180
181
# File 'lib/new_relic/agent.rb', line 176

def manual_start(options={})
  raise unless Hash === options
  # Ignore all args but hash options
  options.merge! :agent_enabled => true 
  NewRelic::Control.instance.init_plugin options
end

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

Record the given error in RPM. It will be passed through the #ignore_error_filter if there is one.

  • exception is the exception which will be recorded

  • extra_params is a hash of name value pairs to appear alongside the exception in RPM.



288
289
290
# File 'lib/new_relic/agent.rb', line 288

def notice_error(exception, extra_params = {})
  NewRelic::Agent::Instrumentation::MetricFrame.notice_error(exception, extra_params)
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


211
212
213
# File 'lib/new_relic/agent.rb', line 211

def set_sql_obfuscator(type = :replace, &block)
  agent.set_sql_obfuscator type, &block
end

#shutdownObject

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



185
186
187
# File 'lib/new_relic/agent.rb', line 185

def shutdown
  @agent.shutdown
end

#with_database_metric_name(model, method, &block) ⇒ Object

Yield to a block that is run with a database metric name context. This means the Database instrumentation will use this for the metric name if it does not otherwise know about a model. This is re-entrant.

  • model is the DB model class

  • method is the name of the finder method or other method to identify the operation with.



307
308
309
310
311
312
313
# File 'lib/new_relic/agent.rb', line 307

def with_database_metric_name(model, method, &block)
  if frame = NewRelic::Agent::Instrumentation::MetricFrame.current
    frame.with_database_metric_name(model, method, &block)
  else
    yield
  end
end