module Atatus

Atatus

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

Constants

AGENT_NAME
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/atatus.rb, line 377
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/atatus.rb, line 83
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/atatus.rb, line 302
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/atatus.rb, line 99
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/atatus.rb, line 92
def current_transaction
  agent&.current_transaction
end

end_span() click to toggle source

Ends the current span

@return [Span]

# File lib/atatus.rb, line 239
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/atatus.rb, line 150
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

# File lib/atatus.rb, line 109
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/atatus.rb, line 317
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/atatus.rb, line 326
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 Atatus 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/atatus.rb, line 71
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/atatus.rb, line 78
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/atatus.rb, line 359
def set_custom_context(custom)
  agent&.set_custom_context(custom)
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/atatus.rb, line 342
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/atatus.rb, line 367
def set_user(user)
  agent&.set_user(user)
end

start(config = {}) click to toggle source

Starts the Atatus Agent

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

# File lib/atatus.rb, line 58
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/atatus.rb, line 207
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/atatus.rb, line 132
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 Atatus Agent

# File lib/atatus.rb, line 63
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/atatus.rb, line 259
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
      )
    yield span
  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/atatus.rb, line 165
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
      )
    yield transaction
  ensure
    end_transaction
  end
end