Module: Airbrake

Defined in:
lib/airbrake-ruby.rb,
lib/airbrake-ruby/stat.rb,
lib/airbrake-ruby/query.rb,
lib/airbrake-ruby/queue.rb,
lib/airbrake-ruby/config.rb,
lib/airbrake-ruby/notice.rb,
lib/airbrake-ruby/backlog.rb,
lib/airbrake-ruby/context.rb,
lib/airbrake-ruby/promise.rb,
lib/airbrake-ruby/request.rb,
lib/airbrake-ruby/tdigest.rb,
lib/airbrake-ruby/version.rb,
lib/airbrake-ruby/loggable.rb,
lib/airbrake-ruby/response.rb,
lib/airbrake-ruby/backtrace.rb,
lib/airbrake-ruby/benchmark.rb,
lib/airbrake-ruby/code_hunk.rb,
lib/airbrake-ruby/ignorable.rb,
lib/airbrake-ruby/mergeable.rb,
lib/airbrake-ruby/stashable.rb,
lib/airbrake-ruby/truncator.rb,
lib/airbrake-ruby/file_cache.rb,
lib/airbrake-ruby/grouppable.rb,
lib/airbrake-ruby/inspectable.rb,
lib/airbrake-ruby/sync_sender.rb,
lib/airbrake-ruby/thread_pool.rb,
lib/airbrake-ruby/timed_trace.rb,
lib/airbrake-ruby/async_sender.rb,
lib/airbrake-ruby/filter_chain.rb,
lib/airbrake-ruby/hash_keyable.rb,
lib/airbrake-ruby/time_truncate.rb,
lib/airbrake-ruby/monotonic_time.rb,
lib/airbrake-ruby/deploy_notifier.rb,
lib/airbrake-ruby/notice_notifier.rb,
lib/airbrake-ruby/remote_settings.rb,
lib/airbrake-ruby/config/processor.rb,
lib/airbrake-ruby/config/validator.rb,
lib/airbrake-ruby/nested_exception.rb,
lib/airbrake-ruby/filters/sql_filter.rb,
lib/airbrake-ruby/filters/keys_filter.rb,
lib/airbrake-ruby/performance_notifier.rb,
lib/airbrake-ruby/filters/thread_filter.rb,
lib/airbrake-ruby/performance_breakdown.rb,
lib/airbrake-ruby/filters/context_filter.rb,
lib/airbrake-ruby/filters/keys_allowlist.rb,
lib/airbrake-ruby/filters/keys_blocklist.rb,
lib/airbrake-ruby/filters/gem_root_filter.rb,
lib/airbrake-ruby/remote_settings/callback.rb,
lib/airbrake-ruby/filters/dependency_filter.rb,
lib/airbrake-ruby/filters/system_exit_filter.rb,
lib/airbrake-ruby/filters/git_revision_filter.rb,
lib/airbrake-ruby/filters/git_repository_filter.rb,
lib/airbrake-ruby/filters/root_directory_filter.rb,
lib/airbrake-ruby/remote_settings/settings_data.rb,
lib/airbrake-ruby/filters/git_last_checkout_filter.rb,
lib/airbrake-ruby/filters/exception_attributes_filter.rb

Overview

We use Semantic Versioning v2.0.0 More information: semver.org/

Defined Under Namespace

Modules: Backtrace, FileCache, Filters, Grouppable, HashKeyable, Ignorable, Inspectable, Loggable, Mergeable, MonotonicTime, Response, Stashable, TimeTruncate Classes: AsyncSender, Backlog, Benchmark, CodeHunk, Config, Context, DeployNotifier, FilterChain, NestedException, Notice, NoticeNotifier, PerformanceBreakdown, PerformanceNotifier, Promise, Query, Queue, RemoteSettings, Request, Stat, SyncSender, TDigest, ThreadPool, TimedTrace, Truncator

Constant Summary collapse

Error =

The general error that this library uses when it wants to raise.

Since:

  • v1.0.0

Class.new(StandardError)
LOG_LABEL =

Returns the label to be prepended to the log output.

Returns:

  • (String) —

    the label to be prepended to the log output

Since:

  • v1.0.0

'**Airbrake:'.freeze
JRUBY =

Returns true if current Ruby is JRuby. The result is used for special cases where we need to work around older implementations.

Returns:

  • (Boolean) —

    true if current Ruby is JRuby. The result is used for special cases where we need to work around older implementations

Since:

  • v1.0.0

(RUBY_ENGINE == 'jruby')
HAS_SAFE_LEVEL =

Returns true if this Ruby supports safe levels and tainting, to guard against using deprecated or unsupported features.

Returns:

  • (Boolean) —

    true if this Ruby supports safe levels and tainting, to guard against using deprecated or unsupported features.

Since:

  • v1.0.0

(
  RUBY_ENGINE == 'ruby' &&
  Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.7')
)
AIRBRAKE_RUBY_VERSION =

Returns the library version.

Returns:

  • (String) —

    the library version

'6.2.2'.freeze
NOTIFIER_INFO =

Returns the information about the notifier library.

Returns:

  • (Hash{Symbol=>String}) —

    the information about the notifier library

Since:

  • v5.0.0

{
  name: 'airbrake-ruby'.freeze,
  version: Airbrake::AIRBRAKE_RUBY_VERSION,
  url: 'https://github.com/airbrake/airbrake-ruby'.freeze,
}.freeze

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.deploy_notifier ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • v4.2.3



151
152
153
 
# File 'lib/airbrake-ruby.rb', line 151

def deploy_notifier
  @deploy_notifier ||= DeployNotifier.new
end

.notice_notifier ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • v4.2.3



145
146
147
 
# File 'lib/airbrake-ruby.rb', line 145

def notice_notifier
  @notice_notifier ||= NoticeNotifier.new
end

.performance_notifier ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Since:

  • v4.2.3



139
140
141
 
# File 'lib/airbrake-ruby.rb', line 139

def performance_notifier
  @performance_notifier ||= PerformanceNotifier.new
end

Class Method Details

.add_filter(filter = nil) {|notice| ... } ⇒ void

This method returns an undefined value.

Runs a callback before notify or notify_sync kicks in. This is useful if you want to ignore specific notices or filter the data the notice contains.

Examples:

Ignore all notices

Airbrake.add_filter(&:ignore!)

Ignore based on some condition

Airbrake.add_filter do |notice|
  notice.ignore! if notice[:error_class] == 'StandardError'
end

Ignore with help of a class

class MyFilter
  def call(notice)
    # ...
  end
end

Airbrake.add_filter(MyFilter.new)

Parameters:

  • filter (#call) (defaults to: nil) —

    The filter object

Yields:

  • (notice) —

    The notice to filter

Yield Parameters:

Yield Returns:

  • (void)

Since:

  • v1.0.0



230
231
232
 
# File 'lib/airbrake-ruby.rb', line 230

def add_filter(filter = nil, &block)
  notice_notifier.add_filter(filter, &block)
end

.add_performance_filter(filter = nil) {|metric| ... } ⇒ void

This method returns an undefined value.

Runs a callback before notify_request, notify_query, notify_queue or notify_performance_breakdown kicks in. This is useful if you want to ignore specific metrics or filter the data the metric contains.

Examples:

Ignore all metrics

Airbrake.add_performance_filter(&:ignore!)

Filter sensitive data

Airbrake.add_performance_filter do |metric|
  case metric
  when Airbrake::Query
    metric.route = '[Filtered]'
  when Airbrake::Request
    metric.query = '[Filtered]'
  end
end

Filter with help of a class

class MyFilter
  def call(metric)
    # ...
  end
end

Airbrake.add_performance_filter(MyFilter.new)

Parameters:

  • filter (#call) (defaults to: nil) —

    The filter object

Yields:

  • (metric) —

    The metric to filter

Yield Parameters:

Yield Returns:

  • (void)

See Also:

Since:

  • v3.2.0



558
559
560
 
# File 'lib/airbrake-ruby.rb', line 558

def add_performance_filter(filter = nil, &block)
  performance_notifier.add_filter(filter, &block)
end

.build_notice(exception, params = {}) ⇒ Airbrake::Notice

Builds an Airbrake notice. This is useful, if you want to add or modify a value only for a specific notice. When you’re done modifying the notice, send it with notify or notify_sync.

Examples:

notice = airbrake.build_notice('App crashed!')
notice[:params][:username] = user.name
airbrake.notify_sync(notice)

Parameters:

  • exception (Exception) —

    The exception on top of which the notice should be built

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

    The additional params attached to the notice

Returns:

Since:

  • v1.0.0



265
266
267
 
# File 'lib/airbrake-ruby.rb', line 265

def build_notice(exception, params = {})
  notice_notifier.build_notice(exception, params)
end

.close ⇒ nil

Makes the notice notifier a no-op, which means you cannot use the notify and notify_sync methods anymore. It also stops the notice notifier’s worker threads.

rubocop:disable Style/IfUnlessModifier

Examples:

Airbrake.close
Airbrake.notify('App crashed!') #=> raises Airbrake::Error

Returns:

  • (nil)

Since:

  • v1.0.0



279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
 
# File 'lib/airbrake-ruby.rb', line 279

def close
  if defined?(@notice_notifier) && @notice_notifier
    @notice_notifier.close
  end

  if defined?(@performance_notifier) && @performance_notifier
    @performance_notifier.close
  end

  if defined?(@remote_settings) && @remote_settings
    @remote_settings.stop_polling
  end

  nil
end

.configure {|config| ... } ⇒ void

This method returns an undefined value.

Configures the Airbrake notifier.

Examples:

Airbrake.configure do |c|
  c.project_id = 113743
  c.project_key = 'fd04e13d806a90f96614ad8e529b2822'
end

Yields:

  • (config)

Yield Parameters:

Since:

  • v1.0.0



123
124
125
126
127
128
129
130
131
132
133
134
135
 
# File 'lib/airbrake-ruby.rb', line 123

def configure
  yield config = Airbrake::Config.instance
  Airbrake::Loggable.instance = config.logger

  config_processor = Airbrake::Config::Processor.new(config)

  config_processor.process_blocklist(notice_notifier)
  config_processor.process_allowlist(notice_notifier)

  @remote_settings ||= config_processor.process_remote_configuration

  config_processor.add_filters(notice_notifier)
end

.configured? ⇒ Boolean

Returns true if the notifier was configured, false otherwise.

Returns:

  • (Boolean) —

    true if the notifier was configured, false otherwise

Since:

  • v2.3.0



157
158
159
 
# File 'lib/airbrake-ruby.rb', line 157

def configured?
  @notice_notifier && @notice_notifier.configured?
end

.delete_filter(filter_class) ⇒ void

Note:

This method cannot delete filters assigned via the Proc form.

This method returns an undefined value.

Deletes a filter added via add_filter.

Examples:

# Add a MyFilter filter (we pass an instance here).
Airbrake.add_filter(MyFilter.new)

# Delete the filter (we pass class name here).
Airbrake.delete_filter(MyFilter)

Parameters:

  • filter_class (Class) —

    The class of the filter you want to delete

Since:

  • v3.1.0



247
248
249
 
# File 'lib/airbrake-ruby.rb', line 247

def delete_filter(filter_class)
  notice_notifier.delete_filter(filter_class)
end

.delete_performance_filter(filter_class) ⇒ void

Note:

This method cannot delete filters assigned via the Proc form.

This method returns an undefined value.

Deletes a filter added via add_performance_filter.

Examples:

# Add a MyFilter filter (we pass an instance here).
Airbrake.add_performance_filter(MyFilter.new)

# Delete the filter (we pass class name here).
Airbrake.delete_performance_filter(MyFilter)

Parameters:

  • filter_class (Class) —

    The class of the filter you want to delete

See Also:

Since:

  • v3.2.0



576
577
578
 
# File 'lib/airbrake-ruby.rb', line 576

def delete_performance_filter(filter_class)
  performance_notifier.delete_filter(filter_class)
end

.merge_context(context) ⇒ void

This method returns an undefined value.

Merges context with the current context.

The context will be attached to the notice object upon a notify call and cleared after it’s attached. The context data is attached to the ‘params/airbrake_context` key.

Examples:

class MerryGrocer
  def load_fruits(fruits)
    Airbrake.merge_context(fruits: fruits)
  end

  def deliver_fruits
    Airbrake.notify('fruitception')
  end

  def load_veggies(veggies)
    Airbrake.merge_context(veggies: veggies)
  end

  def deliver_veggies
    Airbrake.notify('veggieboom!')
  end
end

grocer = MerryGrocer.new

# Load some fruits to the context.
grocer.load_fruits(%w(mango banana apple))

# Deliver the fruits. Note that we are not passing anything,
# `deliver_fruits` knows that we loaded something.
grocer.deliver_fruits

# Load some vegetables and deliver them to Airbrake. Note that the
# fruits have been delivered and therefore the grocer doesn't have them
# anymore. We merge veggies with the new context.
grocer.load_veggies(%w(cabbage carrot onion))
grocer.deliver_veggies

# The context is empty again, feel free to load more.

Parameters:

  • context (Hash{Symbol=>Object})

Since:

  • v1.0.0



353
354
355
 
# File 'lib/airbrake-ruby.rb', line 353

def merge_context(context)
  notice_notifier.merge_context(context)
end

.notify(exception, params = {}) {|notice| ... } ⇒ Airbrake::Promise

Sends an exception to Airbrake asynchronously.

Examples:

Sending an exception

Airbrake.notify(RuntimeError.new('Oops!'))

Sending a string

# Converted to RuntimeError.new('Oops!') internally
Airbrake.notify('Oops!')

Sending a Notice

notice = airbrake.build_notice(RuntimeError.new('Oops!'))
airbrake.notify(notice)

Parameters:

  • exception (Exception, String, Airbrake::Notice) —

    The exception to be sent to Airbrake

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

    The additional payload to be sent to Airbrake. Can contain any values. The provided values will be displayed in the Params tab in your project’s dashboard

Yields:

  • (notice) —

    The notice to filter

Yield Parameters:

Yield Returns:

  • (void)

Returns:

See Also:

Since:

  • v1.0.0



182
183
184
 
# File 'lib/airbrake-ruby.rb', line 182

def notify(exception, params = {}, &block)
  notice_notifier.notify(exception, params, &block)
end

.notify_deploy(deploy_info) ⇒ void

This method returns an undefined value.

Pings the Airbrake Deploy API endpoint about the occurred deploy.

Parameters:

  • deploy_info (Hash{Symbol=>String}) —

    The params for the API

Options Hash (deploy_info):

  • :environment (Symbol)
  • :username (Symbol)
  • :repository (Symbol)
  • :revision (Symbol)
  • :version (Symbol)

Since:

  • v1.0.0



305
306
307
 
# File 'lib/airbrake-ruby.rb', line 305

def notify_deploy(deploy_info)
  deploy_notifier.notify(deploy_info)
end

.notify_performance_breakdown(breakdown_info, stash = {}) ⇒ void

This method returns an undefined value.

Increments performance breakdown statistics of a certain route.

Examples:

Airbrake.notify_performance_breakdown(
  method: 'POST',
  route: '/thing/:id/create',
  response_type: 'json',
  groups: { db: 24.0, view: 0.4 }, # ms
  timing: 123.45 # ms
)

Parameters:

  • breakdown_info (Hash{Symbol=>Object})
  • stash (Hash) (defaults to: {}) —

    What needs to be appeneded to the stash, so it’s available in filters

Options Hash (breakdown_info):

  • :method (String) —

    HTTP method

  • :route (String)
  • :response_type (String)
  • :groups (Array<Hash{Symbol=>Float}>)
  • :timing (Float) —

    How much time it took to process the performance breakdown (in ms)

Since:

  • v4.2.0



474
475
476
477
478
 
# File 'lib/airbrake-ruby.rb', line 474

def notify_performance_breakdown(breakdown_info, stash = {})
  performance_breakdown = PerformanceBreakdown.new(**breakdown_info)
  performance_breakdown.stash.merge!(stash)
  performance_notifier.notify(performance_breakdown)
end

.notify_performance_breakdown_sync(breakdown_info, stash = {}) ⇒ Object

Increments performance breakdown statistics of a certain route synchronously.

See Also:

Since:

  • v4.10.0



484
485
486
487
488
 
# File 'lib/airbrake-ruby.rb', line 484

def notify_performance_breakdown_sync(breakdown_info, stash = {})
  performance_breakdown = PerformanceBreakdown.new(**breakdown_info)
  performance_breakdown.stash.merge!(stash)
  performance_notifier.notify_sync(performance_breakdown)
end

.notify_query(query_info, stash = {}) ⇒ void

This method returns an undefined value.

Increments SQL statistics of a certain query. When method and route are provided, the query is grouped by these parameters.

After a certain amount of time (n seconds) the aggregated query information will be sent to Airbrake.

Examples:

Airbrake.notify_query(
  method: 'GET',
  route: '/things',
  query: 'SELECT * FROM things',
  func: 'do_stuff',
  file: 'app/models/foo.rb',
  line: 452,
  timing: 123.45 # ms
)

Parameters:

  • query_info (Hash{Symbol=>Object})
  • stash (Hash) (defaults to: {}) —

    What needs to be appeneded to the stash, so it’s available in filters

  • request_info (Hash) —

    a customizable set of options

Options Hash (query_info):

  • :method (String) —

    The HTTP method that triggered this SQL query (optional)

  • :route (String) —

    The route that triggered this SQL query (optional)

  • :query (String) —

    The query that was executed

  • :timing (Float) —

    How much time it took to process the query (in ms)

See Also:

Since:

  • v3.2.0



435
436
437
438
439
 
# File 'lib/airbrake-ruby.rb', line 435

def notify_query(query_info, stash = {})
  query = Query.new(**query_info)
  query.stash.merge!(stash)
  performance_notifier.notify(query)
end

.notify_query_sync(query_info, stash = {}) ⇒ Object

Synchronously increments SQL statistics of a certain query. When method and route are provided, the query is grouped by these parameters.

See Also:

Since:

  • v4.10.0



446
447
448
449
450
 
# File 'lib/airbrake-ruby.rb', line 446

def notify_query_sync(query_info, stash = {})
  query = Query.new(**query_info)
  query.stash.merge!(stash)
  performance_notifier.notify_sync(query)
end

.notify_queue(queue_info, stash = {}) ⇒ void

This method returns an undefined value.

Increments statistics of a certain queue (worker).

Examples:

Airbrake.notify_queue(
  queue: 'emails',
  error_count: 1,
  groups: { redis: 24.0, sql: 0.4 } # ms
)

Parameters:

  • queue_info (Hash{Symbol=>Object})
  • stash (Hash) (defaults to: {}) —

    What needs to be appended to the stash, so it’s available in filters

  • breakdown_info (Hash) —

    a customizable set of options

Options Hash (queue_info):

  • :queue (String) —

    The name of the queue/worker

  • :error_count (Integer) —

    How many times this worker failed

  • :groups (Array<Hash{Symbol=>Float}>) —

    Where the job spent its time

See Also:

Since:

  • v4.9.0



512
513
514
515
516
 
# File 'lib/airbrake-ruby.rb', line 512

def notify_queue(queue_info, stash = {})
  queue = Queue.new(**queue_info)
  queue.stash.merge!(stash)
  performance_notifier.notify(queue)
end

.notify_queue_sync(queue_info, stash = {}) ⇒ Object

Increments statistics of a certain queue (worker) synchronously.

See Also:

Since:

  • v4.10.0



521
522
523
524
525
 
# File 'lib/airbrake-ruby.rb', line 521

def notify_queue_sync(queue_info, stash = {})
  queue = Queue.new(**queue_info)
  queue.stash.merge!(stash)
  performance_notifier.notify_sync(queue)
end

.notify_request(request_info, stash = {}) ⇒ void

This method returns an undefined value.

Increments request statistics of a certain route invoked with method, which returned status_code.

After a certain amount of time (n seconds) the aggregated route information will be sent to Airbrake.

Examples:

Airbrake.notify_request(
  method: 'POST',
  route: '/thing/:id/create',
  status_code: 200,
  timing: 123.45 # ms
)

Parameters:

  • request_info (Hash{Symbol=>Object})
  • stash (Hash) (defaults to: {}) —

    What needs to be appeneded to the stash, so it’s available in filters

Options Hash (request_info):

  • :method (String) —

    The HTTP method that was invoked

  • :route (String) —

    The route that was invoked

  • :status_code (Integer) —

    The response code that the route returned

  • :timing (Float) —

    How much time it took to process the request (in ms)

See Also:

Since:

  • v3.0.0



383
384
385
386
387
 
# File 'lib/airbrake-ruby.rb', line 383

def notify_request(request_info, stash = {})
  request = Request.new(**request_info)
  request.stash.merge!(stash)
  performance_notifier.notify(request)
end

.notify_request_sync(request_info, stash = {}) ⇒ Object

Synchronously increments request statistics of a certain route invoked with method, which returned status_code.

See Also:

Since:

  • v4.10.0



393
394
395
396
397
 
# File 'lib/airbrake-ruby.rb', line 393

def notify_request_sync(request_info, stash = {})
  request = Request.new(**request_info)
  request.stash.merge!(stash)
  performance_notifier.notify_sync(request)
end

.notify_sync(exception, params = {}) {|notice| ... } ⇒ Airbrake::Promise

Sends an exception to Airbrake synchronously.

Examples:

Airbrake.notify_sync('App crashed!')
#=> {"id"=>"123", "url"=>"https://airbrake.io/locate/321"}

Parameters:

  • exception (Exception, String, Airbrake::Notice) —

    The exception to be sent to Airbrake

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

    The additional payload to be sent to Airbrake. Can contain any values. The provided values will be displayed in the Params tab in your project’s dashboard

Yields:

  • (notice) —

    The notice to filter

Yield Parameters:

Yield Returns:

  • (void)

Returns:

See Also:

Since:

  • v1.0.0



202
203
204
 
# File 'lib/airbrake-ruby.rb', line 202

def notify_sync(exception, params = {}, &block)
  notice_notifier.notify_sync(exception, params, &block)
end

.reset ⇒ void

This method returns an undefined value.

Resets all notifiers, including its filters

Since:

  • v4.2.2



583
584
585
586
587
588
589
 
# File 'lib/airbrake-ruby.rb', line 583

def reset
  close

  self.performance_notifier = PerformanceNotifier.new
  self.notice_notifier = NoticeNotifier.new
  self.deploy_notifier = DeployNotifier.new
end