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_segment ⇒ Object

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

[View source] [View on GitHub]

207
208
209
210
211
 
# File 'lib/new_relic/agent/tracer.rb', line 207

def current_segment
  return unless txn = current_transaction

  txn.current_segment
end

.current_span_id ⇒ Object Also known as: span_id

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

[View source] [View on GitHub]

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

def current_span_id
  if span = current_segment
    span.guid
  end
end

.current_trace_id ⇒ Object Also known as: trace_id

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

[View source] [View on GitHub]

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

def current_trace_id
  if txn = current_transaction
    txn.trace_id
  end
end

.current_transaction ⇒ Object

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

[View source] [View on GitHub]

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

def current_transaction
  state.current_transaction
end

.in_transaction(name: nil, partial_name: nil, category:, 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) —

    :web for web transactions or :background for background transactions

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

    reserved for New Relic internal use

[View source] [View on GitHub]

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

def in_transaction(name: nil,
  partial_name: nil,
  category:,
  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 => exception
    current_transaction.notice_error(exception)
    raise
  ensure
    finishable&.finish
  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

[View source] [View on GitHub]

288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
 
# File 'lib/new_relic/agent/tracer.rb', line 288

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 => exception
  log_error('start_datastore_segment', exception)
end

.start_external_request_segment(library:, uri:, procedure:, 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) —

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

  • uri (String, URI) —

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

  • procedure (String) —

    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

[View source] [View on GitHub]

335
336
337
338
339
340
341
342
343
344
345
346
347
 
# File 'lib/new_relic/agent/tracer.rb', line 335

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

  segment = Transaction::ExternalRequestSegment.new(library, uri, procedure, start_time)
  start_and_add_segment(segment, parent)
rescue ArgumentError
  raise
rescue => exception
  log_error('start_external_request_segment', exception)
end

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

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

Parameters:

  • name (String) —

    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

[View source] [View on GitHub]

237
238
239
240
241
242
243
244
245
246
247
248
 
# File 'lib/new_relic/agent/tracer.rb', line 237

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

  segment = Transaction::Segment.new(name, unscoped_metrics, start_time)
  start_and_add_segment(segment, parent)
rescue ArgumentError
  raise
rescue => exception
  log_error('start_segment', exception)
end

.start_transaction_or_segment(name: nil, partial_name: nil, category:, 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) —

    :web for web transactions or :task 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

[View source] [View on GitHub]

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
 
# File 'lib/new_relic/agent/tracer.rb', line 134

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

  raise ArgumentError, 'missing required argument: name or partial_name' if name.nil? && partial_name.nil?

  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 => exception
  log_error('start_transaction_or_segment', exception)
end

.tracing_enabled? ⇒ Boolean

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

Returns:

  • (Boolean)
[View source] [View on GitHub]

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

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)
[View source] [View on GitHub]

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

def transaction_sampled?
  txn = current_transaction
  return false unless txn

  txn.sampled?
end