module ElasticAPM

ElasticAPM

rubocop:disable Style/AccessorGrouping

Licensed to Elasticsearch B.V. under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. Elasticsearch B.V. licenses this file to you under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.apache.org/licenses/LICENSE-2.0

Constants

VERSION

Public Class Methods

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 400
def add_filter(key, callback = nil, &block)
  if callback.nil? && !block
    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 84
def agent
  Agent.instance
end

build_context( 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 315
def build_context(
  rack_env: nil,
  for_type: :transaction
)
  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 100
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 93
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 247
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 153
def end_transaction(result = nil)
  agent&.end_transaction(result)
end

log_ids() { |current_transaction&.id, current_span&.id, trace_id| ... } click to toggle source

Get a formatted string containing transaction, span, and trace ids. If a block is provided, the ids are yielded.

@yield [String|nil, String|nil, String|nil] The transaction, span, and trace ids. @return [String] Unless block given rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity

# File lib/elastic_apm.rb, line 111
def log_ids
  trace_id = (current_transaction || current_span)&.trace_id
  if block_given?
    return yield(current_transaction&.id, current_span&.id, trace_id)
  end

  ids = []
  ids << "transaction.id=#{current_transaction.id}" if current_transaction
  ids << "span.id=#{current_span.id}" if current_span
  ids << "trace.id=#{trace_id}" if trace_id
  ids.join(' ')
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 [String] ID of the generated [Error]

# File lib/elastic_apm.rb, line 330
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 [String] ID of the generated [Error]

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

restart(config = nil) click to toggle source

Restarts the ElasticAPM Agent using the same config or a new one, if it is provided. Starts the agent if it is not running. Stops and starts the agent if it is running.

# File lib/elastic_apm.rb, line 72
def restart(config = nil)
  config ||= agent&.config
  stop if running?
  start(config)
end

running?() click to toggle source

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

# File lib/elastic_apm.rb, line 79
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 372
def set_custom_context(custom)
  agent&.set_custom_context(custom)
end

set_destination(address: nil, port: nil, service: nil, cloud: nil) click to toggle source

Set destination fields on the current span

@param address [String] Destination address @param address [String] Destination address @param address [Hash] Destination service @param address [Hash] Destination cloud

# File lib/elastic_apm.rb, line 390
def set_destination(address: nil, port: nil, service: nil, cloud: nil)
  agent&.set_destination(address: address, port: port, service: service, cloud: cloud)
end

set_label(key, value) click to toggle source

Set a label value for the current transaction

@param key [String,Symbol] A key @param value [Object] A value @return [Object] The given value

# File lib/elastic_apm.rb, line 355
def set_label(key, value)
  case value
  when TrueClass,
       FalseClass,
       Numeric,
       NilClass,
       String
    agent&.set_label(key, value)
  else
    agent&.set_label(key, value.to_s)
  end
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 380
def set_user(user)
  agent&.set_user(user)
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 59
def start(config = {})
  Agent.start config
end

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

rubocop:disable Metrics/ParameterLists Start a new span

@param name [String] A description of the span, eq `SELECT FROM “users”` @param type [String] The span type, eq `db` @param subtype [String] The span subtype, eq `postgresql` @param action [String] The span action type, eq `connect` or `query` @param context [Span::Context] Context information about the span @param include_stacktrace [Boolean] Whether or not to capture a stacktrace @param trace_context [TraceContext] An optional [TraceContext] object for

Distributed Tracing.

@param parent [Transaction,Span] The parent transaction or span.

Relevant when the span is created in another thread.

@param sync [Boolean] Whether the span is created synchronously or not. @return [Span]

# File lib/elastic_apm.rb, line 215
def start_span(
  name,
  type = nil,
  subtype: nil,
  action: nil,
  context: nil,
  include_stacktrace: true,
  trace_context: nil,
  parent: nil,
  sync: nil
)
  agent&.start_span(
    name,
    type,
    subtype: subtype,
    action: action,
    context: context,
    trace_context: trace_context,
    parent: parent,
    sync: sync
  ).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 ) click to toggle source

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] @param trace_context [TraceContext] An optional [TraceContext] object for

Distributed Tracing.

@return [Transaction]

# File lib/elastic_apm.rb, line 135
def start_transaction(
  name = nil,
  type = nil,
  context: nil,
  trace_context: nil
)
  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 64
def stop
  Agent.stop
end

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

rubocop:disable Metrics/ParameterLists 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` @param subtype [String] The subtype of span eg. `postgresql`. @param action [String] The action type of span eg. `connect` or `query`. @param context [Span::Context] Context information about the span @param include_stacktrace [Boolean] Whether or not to capture a stacktrace @param trace_context [TraceContext] An optional [TraceContext] object for

Distributed Tracing.

@param parent [Transaction,Span] The parent transaction or span.

Relevant when the span is created in another thread.

@param sync [Boolean] Whether the span is created synchronously or not. @yield [Span] @return Result of block

# File lib/elastic_apm.rb, line 267
def with_span(
  name,
  type = nil,
  subtype: nil,
  action: nil,
  context: nil,
  include_stacktrace: true,
  trace_context: nil,
  parent: nil,
  sync: 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,
        subtype: subtype,
        action: action,
        context: context,
        include_stacktrace: include_stacktrace,
        trace_context: trace_context,
        parent: parent,
        sync: sync
      )
    result = yield span
    span&.outcome ||= Span::Outcome::SUCCESS
    result
  rescue
    span&.outcome ||= Span::Outcome::FAILURE
    raise
  ensure
    end_span
  end
end

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

Wrap a block in a Transaction, ending it after the block

Distributed Tracing.

@yield [Transaction] @return result of block

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

  return yield(nil) unless agent

  begin
    transaction =
      start_transaction(
        name,
        type,
        context: context,
        trace_context: trace_context
      )
    result = yield transaction
    transaction&.outcome ||= Transaction::Outcome::SUCCESS
    result
  rescue
    transaction&.outcome ||= Transaction::Outcome::FAILURE
    raise
  ensure
    end_transaction
  end
end