Class: NewRelic::Agent::Tracer

Inherits:
Object
  • Object
show all
Defined in:
lib/new_relic/agent/tracer.rb

Overview

This class helps you interact with the current transaction (if it exists), start new transactions/segments, etc.

Class Method Summary collapse

Class Method Details

.current_segmentObject

Returns the currently active segment in the transaction in progress for this thread, or nil if no segment or transaction exists.


212
213
214
215
# File 'lib/new_relic/agent/tracer.rb', line 212

def current_segment
  return unless txn = current_transaction
  txn.current_segment
end

.current_span_idObject Also known as: span_id

Returns the id of the current span, or nil if none exists.


56
57
58
59
60
# File 'lib/new_relic/agent/tracer.rb', line 56

def current_span_id
  if span = current_segment
    span.guid
  end
end

.current_trace_idObject Also known as: trace_id

Returns the trace_id of the current_transaction, or nil if none exists.


46
47
48
49
50
# File 'lib/new_relic/agent/tracer.rb', line 46

def current_trace_id
  if txn = current_transaction
    txn.trace_id
  end
end

.current_transactionObject

Returns the transaction in progress for this thread, or nil if none exists.


38
39
40
# File 'lib/new_relic/agent/tracer.rb', line 38

def current_transaction
  state.current_transaction
end

.in_transaction(name: nil, partial_name: nil, category: nil, options: {}) ⇒ Object

Runs the given block of code in a transaction.

Parameters:

  • name (String) (defaults to: nil)

    reserved for New Relic internal use

  • partial_name (String) (defaults to: nil)

    a meaningful name for this transaction (e.g., blogs/index); the Ruby agent will add a New-Relic-specific prefix

  • category (Symbol) (defaults to: nil)

    :web for web transactions or :background for background transactions

  • options (Hash) (defaults to: {})

    reserved for New Relic internal use


88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
# File 'lib/new_relic/agent/tracer.rb', line 88

def in_transaction(name: nil,
                   partial_name: nil,
                   category: nil,
                   options: {})

  finishable = start_transaction_or_segment(
    name: name,
    partial_name: partial_name,
    category: category,
    options: options
  )

  begin
    # We shouldn't raise from Tracer.start_transaction_or_segment, but
    # only wrap the yield to be absolutely sure we don't report agent
    # problems as app errors
    yield
  rescue => e
    current_transaction.notice_error(e)
    raise e
  ensure
    finishable.finish if finishable
  end
end

.start_datastore_segment(product: nil, operation: nil, collection: nil, host: nil, port_path_or_id: nil, database_name: nil, start_time: nil, parent: nil) ⇒ DatastoreSegment

Creates and starts a datastore segment used to time datastore operations.

Parameters:

  • product (String) (defaults to: nil)

    the datastore name for use in metric naming, e.g. “FauxDB”

  • operation (String) (defaults to: nil)

    the name of the operation (e.g. “select”), often named after the method that's being instrumented.

  • collection (optional, String) (defaults to: nil)

    the collection name for use in statement-level metrics (i.e. table or model name)

  • host (optional, String) (defaults to: nil)

    the host this database instance is running on

  • port_path_or_id (optional, String) (defaults to: nil)

    TCP port, file path, UNIX domain socket, or other connection-related info

  • database_name (optional, String) (defaults to: nil)

    the name of this database

  • start_time (optional, Time) (defaults to: nil)

    a Time instance denoting the start time of the segment. Value is set by AbstractSegment#start if not given.

  • parent (optional, Segment) (defaults to: nil)

    Use for the rare cases (such as async) where the parent segment should be something other than the current segment

Returns:

  • (DatastoreSegment)

    the newly created segment; you must call finish on it at the end of the code you're tracing


296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
# File 'lib/new_relic/agent/tracer.rb', line 296

def start_datastore_segment(product: nil,
                            operation: nil,
                            collection: nil,
                            host: nil,
                            port_path_or_id: nil,
                            database_name: nil,
                            start_time: nil,
                            parent: nil)

  product ||= UNKNOWN
  operation ||= OTHER

  segment = Transaction::DatastoreSegment.new product, operation, collection, host, port_path_or_id, database_name
  start_and_add_segment segment, parent

rescue ArgumentError
  raise
rescue => e
  log_error('start_datastore_segment', e)
end

.start_external_request_segment(library: nil, uri: nil, procedure: nil, start_time: nil, parent: nil) ⇒ ExternalRequestSegment

Creates and starts an external request segment using the given library, URI, and procedure. This is used to time external calls made over HTTP.

Parameters:

  • library (String) (defaults to: nil)

    a string of the class name of the library used to make the external call, for example, 'Net::HTTP'.

  • uri (String, URI) (defaults to: nil)

    indicates the URI to which the external request is being made. The URI should begin with the protocol, for example, 'github.com'.

  • procedure (String) (defaults to: nil)

    the HTTP method being used for the external request as a string, for example, 'GET'.

  • start_time (optional, Time) (defaults to: nil)

    a Time instance denoting the start time of the segment. Value is set by AbstractSegment#start if not given.

  • parent (optional, Segment) (defaults to: nil)

    Use for the rare cases (such as async) where the parent segment should be something other than the current segment

Returns:

  • (ExternalRequestSegment)

    the newly created segment; you must call finish on it at the end of the code you're tracing


344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
# File 'lib/new_relic/agent/tracer.rb', line 344

def start_external_request_segment(library: nil,
                                   uri: nil,
                                   procedure: nil,
                                   start_time: nil,
                                   parent: nil)

  # ruby 2.0.0 does not support required kwargs
  raise ArgumentError, 'missing required argument: library' if library.nil?
  raise ArgumentError, 'missing required argument: uri' if uri.nil?
  raise ArgumentError, 'missing required argument: procedure' if procedure.nil?

  segment = Transaction::ExternalRequestSegment.new library, uri, procedure, start_time
  start_and_add_segment segment, parent

rescue ArgumentError
  raise
rescue => e
  log_error('start_external_request_segment', e)
end

.start_segment(name: nil, unscoped_metrics: nil, start_time: nil, parent: nil) ⇒ Segment

Creates and starts a general-purpose segment used to time arbitrary code.

Parameters:

  • name (String) (defaults to: nil)

    full name of the segment; the agent will not add a prefix. Third-party users should begin the name with Custom/; e.g., Custom/UserMailer/send_welcome_email

  • unscoped_metrics (optional, String, Array) (defaults to: nil)

    additional unscoped metrics to record using this segment's timing information

  • start_time (optional, Time) (defaults to: nil)

    a Time instance denoting the start time of the segment. Value is set by AbstractSegment#start if not given.

  • parent (optional, Segment) (defaults to: nil)

    Use for the rare cases (such as async) where the parent segment should be something other than the current segment

Returns:

  • (Segment)

    the newly created segment; you must call finish on it at the end of the code you're tracing


241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
# File 'lib/new_relic/agent/tracer.rb', line 241

def start_segment(name:nil,
                  unscoped_metrics:nil,
                  start_time: nil,
                  parent: nil)

  # ruby 2.0.0 does not support required kwargs
  raise ArgumentError, 'missing required argument: name' if name.nil?

  segment = Transaction::Segment.new name, unscoped_metrics, start_time
  start_and_add_segment segment, parent

rescue ArgumentError
  raise
rescue => e
  log_error('start_segment', e)
end

.start_transaction_or_segment(name: nil, partial_name: nil, category: nil, options: {}) ⇒ Object, #finish

Starts a segment on the current transaction (if one exists) or starts a new transaction otherwise.

Parameters:

  • name (String) (defaults to: nil)

    reserved for New Relic internal use

  • partial_name (String) (defaults to: nil)

    a meaningful name for this transaction (e.g., blogs/index); the Ruby agent will add a New-Relic-specific prefix

  • category (Symbol) (defaults to: nil)

    :web for web transactions or :background for background transactions

  • options (Hash) (defaults to: {})

    reserved for New Relic internal use

Returns:

  • (Object, #finish)

    an object that responds to finish; you must call finish on it at the end of the code you're tracing


132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
# File 'lib/new_relic/agent/tracer.rb', line 132

def start_transaction_or_segment(name: nil,
                                 partial_name: nil,
                                 category: nil,
                                 options: {})
  if name.nil? && partial_name.nil?
    raise ArgumentError, 'missing required argument: name or partial_name'
  end
  if category.nil?
    raise ArgumentError, 'missing required argument: category'
  end

  if name
    options[:transaction_name] = name
  else
    options[:transaction_name] = Transaction.name_from_partial(
      partial_name,
      category
    )
  end

  if (txn = current_transaction)
    txn.create_nested_segment(category, options)
  else
    Transaction.start_new_transaction(state, category, options)
  end

rescue ArgumentError
  raise
rescue => e
  log_error('start_transaction_or_segment', e)
end

.tracing_enabled?Boolean

Returns true unless called from within an NewRelic::Agent.disable_all_tracing block.

Returns:

  • (Boolean)

30
31
32
# File 'lib/new_relic/agent/tracer.rb', line 30

def tracing_enabled?
  state.tracing_enabled?
end

.transaction_sampled?Boolean Also known as: sampled?

Returns a boolean indicating whether the current_transaction is sampled, or nil if there is no current transaction.

Returns:

  • (Boolean)

67
68
69
70
71
# File 'lib/new_relic/agent/tracer.rb', line 67

def transaction_sampled?
  if txn = current_transaction
    txn.sampled?
  end
end