module ElasticAPM

add_filter(key, callback = nil, &block) click to toggle source

Provide a filter to transform payloads before sending them off

@param key [Symbol] Unique filter key @param callback [Object, Proc] A filter that responds to call(payload) @yield [Hash] A filter. Used if provided. Otherwise using `callback` @return [Bool] true

# File lib/elastic_apm.rb, line 360
def add_filter(key, callback = nil, &block)
  if callback.nil? && !block_given?
    raise ArgumentError, '#add_filter needs either `callback\' or a block'
  end

  agent&.add_filter(key, block || callback)
end

agent() click to toggle source

@return [Agent] Currently running [Agent] if any

# File lib/elastic_apm.rb, line 45
def agent
  Agent.instance
end

build_context( deprecated_env = nil, rack_env: nil, for_type: :transaction ) click to toggle source

Build a [Context] from a Rack `env`. The context may include information about the request, response, current user and more

@param rack_env [Rack::Env] A Rack env @return [Context] The built context

# File lib/elastic_apm.rb, line 288
def build_context(
  deprecated_env = nil,
  rack_env: nil,
  for_type: :transaction
)
  if !rack_env && (rack_env = deprecated_env)
    warn "[ElasticAPM] [DEPRECATED] `build_context' expects two keyword" \
      "arguments, `rack_env:' and `for_type:'"
  end

  agent&.build_context(rack_env: rack_env, for_type: for_type)
end

current_span() click to toggle source

Returns the currently active span (if any)

@return [Span] or `nil`

# File lib/elastic_apm.rb, line 61
def current_span
  agent&.current_span
end

current_transaction() click to toggle source

Returns the currently active transaction (if any)

@return [Transaction] or `nil`

# File lib/elastic_apm.rb, line 54
def current_transaction
  agent&.current_transaction
end

end_span() click to toggle source

Ends the current span

@return [Span]

# File lib/elastic_apm.rb, line 240
def end_span
  agent&.end_span
end

end_transaction(result = nil) click to toggle source

Ends the current transaction with `result`

@param result [String] The result of the transaction @return [Transaction]

# File lib/elastic_apm.rb, line 122
def end_transaction(result = nil)
  agent&.end_transaction(result)
end

report(exception, context: nil, handled: true) click to toggle source

Report and exception to APM

@param exception [Exception] The exception @param context [Context] An optional [Context] @param handled [Boolean] Whether the exception was rescued @return [Error] The generated [Error]

# File lib/elastic_apm.rb, line 309
def report(exception, context: nil, handled: true)
  agent&.report(exception, context: context, handled: handled)
end

report_message(message, context: nil, **attrs) click to toggle source

Report a custom string error message to APM

@param message [String] The message @param context [Context] An optional [Context] @return [Error] The generated [Error]

# File lib/elastic_apm.rb, line 318
def report_message(message, context: nil, **attrs)
  agent&.report_message(
    message,
    context: context,
    backtrace: caller,
    **attrs
  )
end

running?() click to toggle source

@return [Boolean] Whether there's an [Agent] running

# File lib/elastic_apm.rb, line 40
def running?
  Agent.running?
end

set_custom_context(custom) click to toggle source

Provide further context for the current transaction

@param custom [Hash] A hash with custom information. Can be nested. @return [Hash] The current custom context

# File lib/elastic_apm.rb, line 342
def set_custom_context(custom)
  agent&.set_custom_context(custom)
end

set_tag(key, value) click to toggle source

Set a tag value for the current transaction

@param key [String,Symbol] A key @param value [Object] A value (will be converted to string) @return [Object] The given value

# File lib/elastic_apm.rb, line 334
def set_tag(key, value)
  agent&.set_tag(key, value)
end

set_user(user) click to toggle source

Provide a user to the current transaction

@param user [Object] An object representing a user @return [Object] Given user

# File lib/elastic_apm.rb, line 350
def set_user(user)
  agent&.set_user(user)
end

span( name, type = nil, context: nil, include_stacktrace: true ) { |: nil)| ... } click to toggle source

rubocop:disable Metrics/MethodLength Start a new span

@param name [String] A description of the span, eq `SELECT FROM “users”` @param type [String] The kind of span, eq `db.mysql2.query` @param context [Span::Context] Context information about the span @yield [Span] Optional block encapsulating span @return [Span] Unless block given @deprecated See `with_span` or `start_span`

# File lib/elastic_apm.rb, line 180
def span(
  name,
  type = nil,
  context: nil,
  include_stacktrace: true,
  &block
)
  return (block_given? ? yield : nil) unless agent

  if block_given?
    with_span(
      name,
      type,
      context: context,
      include_stacktrace: include_stacktrace,
      &block
    )
  else
    start_span(
      name,
      type,
      context: context,
      include_stacktrace: include_stacktrace
    )
  end
end

start(config = {}) click to toggle source

Starts the ElasticAPM Agent

@param config [Config] An instance of Config @return [Agent] The resulting [Agent]

# File lib/elastic_apm.rb, line 30
def start(config = {})
  Agent.start config
end

start_span( name, type = nil, context: nil, include_stacktrace: true, trace_context: nil ) click to toggle source

Start a new span

@param name [String] A description of the span, eq `SELECT FROM “users”` @param type [String] The kind of span, eq `db.mysql2.query` @param context [Span::Context] Context information about the span @param include_stacktrace [Boolean] Whether or not to capture a stacktrace @return [Span]

# File lib/elastic_apm.rb, line 217
def start_span(
  name,
  type = nil,
  context: nil,
  include_stacktrace: true,
  trace_context: nil
)
  agent&.start_span(
    name,
    type,
    context: context,
    trace_context: trace_context
  ).tap do |span|
    break unless span && include_stacktrace
    break unless agent.config.span_frames_min_duration?

    span.original_backtrace ||= caller
  end
end

start_transaction( name = nil, type = nil, context: nil, trace_context: nil, traceparent: nil ) click to toggle source

rubocop:disable Metrics/MethodLength Start a new transaction

@param name [String] A description of the transaction, eg `ExamplesController#index` @param type [String] The kind of the transaction, eg `app.request.get` or `db.mysql2.query` @param context [Context] An optional [Context] @return [Transaction]

# File lib/elastic_apm.rb, line 96
def start_transaction(
  name = nil,
  type = nil,
  context: nil,
  trace_context: nil,
  traceparent: nil
)
  if traceparent
    trace_context ||= traceparent
    warn "[ElasticAPM] [DEPRECATED] `start_transaction' with" \
      "`traceparent:' has been renamed. Use `trace_context:' instead."
  end

  agent&.start_transaction(
    name,
    type,
    context: context,
    trace_context: trace_context
  )
end

stop() click to toggle source

Stops the ElasticAPM Agent

# File lib/elastic_apm.rb, line 35
def stop
  Agent.stop
end

transaction(name = nil, type = nil, context: nil) { |: nil)| ... } click to toggle source

Start a new transaction or return the currently running

@param name [String] A description of the transaction, eg `ExamplesController#index` @param type [String] The kind of the transaction, eg `app.request.get` or `db.mysql2.query` @param context [Context] An optional [Context] @yield [Transaction] Optional block encapsulating transaction @return [Transaction] Unless block given @deprecated See `with_transaction` or `start_transaction`

# File lib/elastic_apm.rb, line 75
def transaction(name = nil, type = nil, context: nil, &block)
  return (block_given? ? yield : nil) unless agent

  if block_given?
    with_transaction(name, type, context: context, &block)
  else
    start_transaction(name, type, context: context)
  end
end

with_span( name, type = nil, context: nil, include_stacktrace: true, trace_context: nil ) { |nil| ... } click to toggle source

rubocop:disable Metrics/MethodLength Wrap a block in a Span, ending it after the block

@param name [String] A description of the span, eq `SELECT FROM “users”` @param type [String] The kind of span, eq `db.mysql2.query` @param context [Span::Context] Context information about the span @param include_stacktrace [Boolean] Whether or not to capture a stacktrace @yield [Span] @return Result of block

# File lib/elastic_apm.rb, line 253
def with_span(
  name,
  type = nil,
  context: nil,
  include_stacktrace: true,
  trace_context: nil
)
  unless block_given?
    raise ArgumentError,
      'expected a block. Do you want `start_span\' instead?'
  end

  return yield nil unless agent

  begin
    span =
      start_span(
        name,
        type,
        context: context,
        include_stacktrace: include_stacktrace,
        trace_context: trace_context
      )
    yield span
  ensure
    end_span
  end
end

with_transaction( name = nil, type = nil, context: nil, trace_context: nil, traceparent: nil ) { |nil| ... } click to toggle source

rubocop:disable Metrics/MethodLength Wrap a block in a Transaction, ending it after the block

@param name [String] A description of the transaction, eg `ExamplesController#index` @param type [String] The kind of the transaction, eg `app.request.get` or `db.mysql2.query` @param context [Context] An optional [Context] @yield [Transaction] @return result of block

# File lib/elastic_apm.rb, line 136
def with_transaction(
  name = nil,
  type = nil,
  context: nil,
  trace_context: nil,
  traceparent: nil
)
  unless block_given?
    raise ArgumentError,
      'expected a block. Do you want `start_transaction\' instead?'
  end

  if traceparent
    trace_context ||= traceparent
    warn "[ElasticAPM] [DEPRECATED] `with_transaction' with " \
      "`traceparent:' has been renamed. Use `trace_context:' instead."
  end

  return yield(nil) unless agent

  begin
    transaction =
      start_transaction(
        name,
        type,
        context: context,
        trace_context: trace_context
      )
    yield transaction
  ensure
    end_transaction
  end
end

Constants

Public Class Methods