Module: AppOpticsAPM::SDK::Tracing

Included in:
AppOpticsAPM::SDK
Defined in:
lib/appoptics_apm/sdk/tracing.rb

Overview

Traces are best created with an AppOpticsAPM::SDK.start_trace block and AppOpticsAPM::SDK.trace blocks around calls to be traced. These two methods guarantee proper nesting of traces, handling of the tracing context, as well as avoiding broken traces in case of exceptions.

Some optional keys that can be used in the opts hash:

  • :Controller

  • :Action

  • :HTTP-Host

  • :URL

  • :Method

as well as custom keys. The information will show up in the raw data view of a span.

Invalid keys: :Label, :Layer, :Edge, :Timestamp, :Timestamp_u, :TransactionName (allowed in start_trace)

The methods are exposed as singleton methods for AppOpticsAPM::SDK.

Usage:

  • AppOpticsAPM::SDK.appoptics_ready?

  • AppOpticsAPM::SDK.get_transaction_name

  • AppOpticsAPM::SDK.set_transaction_name

  • AppOpticsAPM::SDK.start_trace

  • AppOpticsAPM::SDK.start_trace_with_target

  • AppOpticsAPM::SDK.trace

  • AppOpticsAPM::SDK.tracing?

Example:

class MonthlyCouponEmailJob
  def perform(*args)

    # KVs to report to the dashboard
    report_kvs = {}
    report_kvs[:Spec] = :job
    report_kvs[:Controller] = :MonthlyEmailJob
    report_kvs[:Action] = :CouponEmailer

    # Start tracing this job with start_trace
    AppOpticsAPM::SDK.start_trace('starling', nil, report_kvs) do
      monthly = MonthlyEmail.new(:CouponEmailer)

      # Trace a sub-component of this trace
      AppOpticsAPM::SDK.trace(self.class.name) do

        # The work to be done
        users = User.all
        users.each do |u|
          monthly.send(u.email)
        end

      end
    end
  end
end

Instance Method Summary collapse

Instance Method Details

#appoptics_ready?(wait_milliseconds = 3000) ⇒ Boolean

Wait for AppOptics to be ready to send traces.

This may be useful in short lived background processes when it is important to capture information during the whole time the process is running. Usually AppOptics doesn't block an application while it is starting up.

Argument:

  • wait_milliseconds (int, default 3000) the maximum time to wait in milliseconds

Example:

unless AppopticsAPM::SDK.appoptics_ready?(10_000)
  Logger.info "AppOptics not ready after 10 seconds, no metrics will be sent"
end

Returns:

  • (Boolean)

300
301
302
303
304
305
306
307
308
309
310
# File 'lib/appoptics_apm/sdk/tracing.rb', line 300

def appoptics_ready?(wait_milliseconds = 3000)
  return false unless AppOpticsAPM.loaded
  # These codes are returned by isReady:
  # OBOE_SERVER_RESPONSE_UNKNOWN 0
  # OBOE_SERVER_RESPONSE_OK 1
  # OBOE_SERVER_RESPONSE_TRY_LATER 2
  # OBOE_SERVER_RESPONSE_LIMIT_EXCEEDED 3
  # OBOE_SERVER_RESPONSE_INVALID_API_KEY 4
  # OBOE_SERVER_RESPONSE_CONNECT_ERROR 5
  AppopticsAPM::Context.isReady(wait_milliseconds) == 1
end

#get_transaction_nameObject

Get the currently set custom transaction name.

This is provided for testing

Returns:

  • (String or nil) the current transaction name (without domain prepended)


263
264
265
# File 'lib/appoptics_apm/sdk/tracing.rb', line 263

def get_transaction_name
  AppOpticsAPM.transaction_name
end

#set_transaction_name(name) ⇒ Object

Provide a custom transaction name

The AppOpticsAPM gem tries to create meaningful transaction names from controller+action or something similar depending on the framework used. However, you may want to override the transaction name to better describe your instrumented operation.

Take note that on the dashboard the transaction name is converted to lowercase, and might be truncated with invalid characters replaced. Method calls with an empty string or a non-string argument won't change the current transaction name.

The configuration AppOpticsAPM.Config['transaction_name']['prepend_domain'] can be set to true to have the domain name prepended to the transaction name when an event or a metric are logged. This is a global setting.

Argument:

  • name - A non-empty string with the custom transaction name

Example:

class DogfoodsController < ApplicationController

  def create
    @dogfood = Dogfood.new(params.permit(:brand, :name))
    @dogfood.save

    AppOpticsAPM::SDK.set_transaction_name("dogfoodscontroller.create_for_#{params[:brand]}")

    redirect_to @dogfood
  end

end

Returns:

  • (String or nil) the current transaction name


246
247
248
249
250
251
252
253
# File 'lib/appoptics_apm/sdk/tracing.rb', line 246

def set_transaction_name(name)
  if name.is_a?(String) && name.strip != ''
    AppOpticsAPM.transaction_name = name
  else
    AppOpticsAPM.logger.debug "[appoptics_apm/api] Could not set transaction name, provided name is empty or not a String."
  end
  AppOpticsAPM.transaction_name
end

#start_trace(span, xtrace = nil, opts = {}) ⇒ Object

Collect metrics and start tracing a given block of code.

This will start a trace depending on configuration and probability, detect any exceptions thrown by the block, and report errors.

When start_trace returns control to the calling context, the trace will be completed and the tracing context will be cleared.

Arguments:

  • span - Name for the span to be used as label in the trace view.

  • xtrace - (optional) incoming X-Trace identifier to be continued.

  • opts - (optional) hash containing key/value pairs that will be reported with this span. The value of :TransactionName will set the transaction_name.

Example:

def handle_request(request, response)
  # ... code that processes request and response ...
end

def handle_request_with_appoptics(request, response)
  AppOpticsAPM::SDK.start_trace('custom_trace', nil, :TransactionName => 'handle_request') do
    handle_request(request, response)
  end
end

Returns:

  • The result of the block.


139
140
141
# File 'lib/appoptics_apm/sdk/tracing.rb', line 139

def start_trace(span, xtrace = nil, opts = {})
  start_trace_with_target(span, xtrace, {}, opts) { yield }
end

#start_trace_with_target(span, xtrace, target, opts = {}) ⇒ Object

Collect metrics, trace a given block of code, and assign trace info to target.

This will start a trace depending on configuration and probability, detect any exceptions thrown by the block, report errors, and assign an X-Trace to the target.

The motivating use case for this is HTTP streaming in rails3. We need access to the exit event's trace id so we can set the header before any work is done, and before any headers are sent back to the client.

Arguments:

  • span - The span the block of code belongs to.

  • xtrace - (optional) incoming X-Trace identifier to be continued.

  • target - (optional) has to respond to #[]=, The target object in which to place the trace information.

  • opts - (optional) hash containing key/value pairs that will be reported with this span.

Example:

def handle_request(request, response)
  # ... code that processes request and response ...
end

def handle_request_with_appoptics(request, response)
  AppOpticsAPM::SDK.start_trace_with_target('rails', request['X-Trace'], response) do
    handle_request(request, response)
  end
end

Returns:

  • The result of the block.


173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
# File 'lib/appoptics_apm/sdk/tracing.rb', line 173

def start_trace_with_target(span, xtrace, target, opts = {})
  return yield unless AppOpticsAPM.loaded

  if AppOpticsAPM::Context.isValid # not an entry span!
    result = trace(span, opts) { yield }
    target['X-Trace'] = AppOpticsAPM::Context.toString
    return result
  end

  # :TransactionName and 'TransactionName' need to be removed from opts
  AppOpticsAPM.transaction_name = opts.delete('TransactionName') || opts.delete(:TransactionName)

  AppOpticsAPM::API.log_start(span, xtrace, opts)
  opts[:Backtrace] && opts.delete(:Backtrace) # to avoid sending backtrace twice (faster to check presence here)

  # AppOpticsAPM::Event.startTrace creates an Event without an Edge
  exit_evt = AppOpticsAPM::Event.startTrace(AppOpticsAPM::Context.get)

  result = begin
    AppOpticsAPM::API.send_metrics(span, opts) do
      target['X-Trace'] = AppOpticsAPM::EventUtil.metadataString(exit_evt)
      yield
    end
  rescue Exception => e
    AppOpticsAPM::API.log_exception(span, e)
    exit_evt.addEdge(AppOpticsAPM::Context.get)
    xtrace = AppOpticsAPM::API.log_end(span, opts, exit_evt)
    e.instance_variable_set(:@xtrace, xtrace)
    raise
  end

  exit_evt.addEdge(AppOpticsAPM::Context.get)
  AppOpticsAPM::API.log_end(span, opts, exit_evt)

  result
end

#trace(span, opts = {}, protect_op = nil) ⇒ Object

Trace a given block of code.

Also detects any exceptions thrown by the block and report errors.

Arguments:

  • :span - The span the block of code belongs to.

  • :opts - (optional) A hash containing key/value pairs that will be reported along with the first event of this span.

  • :protect_op - (optional) The operation being traced. Used to avoid double tracing operations that call each other.

Example:

def computation_with_appoptics(n)
  AppOpticsAPM::SDK.trace('computation', { :number => n }, :computation) do
    return n if n == 0
    n + computation_with_appoptics(n-1)
  end
end

result = computation_with_appoptics(100)

Returns:

  • The result of the block.


90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
# File 'lib/appoptics_apm/sdk/tracing.rb', line 90

def trace(span, opts = {}, protect_op = nil)
  return yield if !AppOpticsAPM.loaded || !AppOpticsAPM.tracing? || AppOpticsAPM.tracing_layer_op?(protect_op)

  opts.delete(:TransactionName)
  opts.delete('TransactionName')

  AppOpticsAPM::API.log_entry(span, opts, protect_op)
  opts[:Backtrace] && opts.delete(:Backtrace) # to avoid sending backtrace twice (faster to check presence here)
  begin
    yield
  rescue Exception => e
    AppOpticsAPM::API.log_exception(span, e)
    raise
  ensure
    AppOpticsAPM::API.log_exit(span, opts, protect_op)
  end
end

#tracing?Boolean

Determine if this transaction is being traced.

Tracing puts some extra load on a system, therefor not all transaction are traced. The tracing? method helps to determine this so that extra work can be avoided when not tracing.

Example:

kvs = expensive_info_gathering_method  if AppOpticsAPM::SDK.tracing?
AppOpticsAPM::SDK.trace('some_span', kvs) do
  # this may not create a trace every time it runs
  db_request
end

Returns:

  • (Boolean)

280
281
282
# File 'lib/appoptics_apm/sdk/tracing.rb', line 280

def tracing?
  AppOpticsAPM.tracing?
end