airbrake：实践指南

真正理解airbrake，要从它处理的任务开始：用于 Ruby 应用程序的官方 Airbrake 库。对日常自动化任务来说，输入边界、依赖和失败处理如果不清楚就很难稳定复用往往决定它能否落地，不能只用安装成功来判断。与其反复读介绍，不如用一项范围明确的真实任务完成最小试跑，再依据配置时间、输出质量、异常信息和维护痕迹做取舍。编辑判断上，愿意先做小范围验证并复查原始文档的团队可以优先研究它；其他团队不必为了热门标签勉强接入。

气闸

• 气闸 README
• 气闸红宝石 README
• YARD API 文档

简介

Airbrake是一个提供健壮异常的在线工具 在任何 Ruby 应用程序中进行跟踪。这样做，您可以轻松地 检查错误，将错误与单独的代码片段联系起来，并追踪原因 回到最近的变化。 Airbrake 仪表板提供简单的分类， 搜索并确定异常的优先级，以便在发生错误时，您的团队 可以快速确定根本原因。

主要特点

此库构建在 Airbrake Ruby 之上。Airbrake 与 Airbrake Ruby 的区别 在于，airbrake gem 只是一个 与框架或其他库集成的集合，而 airbrake-ruby gem 才是负责发送异常并 执行其他核心工作的 基础库。

通常只需依赖此 gem，选择需要的集成并 按照对应说明操作。如果开发不使用框架的纯 Ruby 应用， 或嵌入 Ruby 且不需要列出的任何集成， 则可以仅依赖 airbrake-ruby gem，完全忽略此 gem。

此 gem 提供的集成包括：

• Heroku support (as an add-on)
• Web frameworks
  • Rails
  • 西纳特拉
  • 机架应用
• 作业处理库
  • ActiveJob
  • 回复
  • Sidekiq
  • DelayedJob
  • 升龙拳
  • 运动鞋
• 其他图书馆
  • ActionCable
  • 耙子
  • 记录仪
• 纯 Ruby 脚本

部署跟踪：

• 使用 Capistrano
• 使用 Rake 任务

安装

捆绑器

将 Airbrake gem 添加到您的 Gemfile 中：

gem 'airbrake'

手册

从终端调用以下命令：

gem install airbrake

配置

导轨

整合

要将 Airbrake 与您的 Rails 应用程序集成，您需要了解您的 [项目 ID 和项目密钥][项目 ID 密钥]。设置 AIRBRAKE_PROJECT_ID & AIRBRAKE_PROJECT_KEY 环境变量与您的项目的值和 生成 Airbrake 配置：

export AIRBRAKE_PROJECT_ID=<PROJECT ID>
export AIRBRAKE_PROJECT_KEY=<PROJECT KEY>

rails g airbrake

Heroku addon 用户可以省略指定密钥和 ID。将使用 Heroku 附加组件的环境变量（[Heroku 附加组件 文档][heroku-文档]）：

rails g airbrake

该命令将在下面生成Airbrake配置文件 config/initializers/airbrake.rb。确保该文件已签入您的 版本控制系统。这足以启动空气制动。

为了根据您的需要配置库，打开文件并 编辑它。 支持的配置选项的完整列表 可用 在线。

要测试集成，请调用我们提供的特殊 Rake 任务：

rake airbrake:test

如果成功，测试异常应该出现在您的仪表板中。

notify_airbrake 控制器助手

Airbrake gem 定义了 Rails 控制器中可用的两个辅助方法： #notify_airbrake 和 #notify_airbrake_sync。如果您想通知 Airbrake 从您的控制器手动，通常最好选择它们 Airbrake.notify，因为它们会自动添加 从机架环境到通知的信息。 #notify_airbrake 是 异步，而 #notify_airbrake_sync 是同步（等待响应 从服务器并返回它们）。接受的参数列表是相同的 至 Airbrake.notify。

附加功能：用户报告，精密API

库自动发送所有未捕获的异常，并附加最大的异常 可以帮助您调试错误的可能数量的信息。空气制动宝石 能够报告当前登录用户的信息（id、 电子邮件、用户名等），如果您使用 Devise 等身份验证库。的 库还提供了一个特殊的API用于手动错误 报告。 API的描述可在线获取。

与 Rake 任务和 Rails 运行程序自动集成

此外，Rails 集成还可以在任何情况下提供自动异常报告。 Rake tasks^[链接] 和 Rails runner。

与filter_parameters集成

如果你想在Airbrake中重用Rails.application.config.filter_parameters 您可以通过以下方式配置通知程序：

# config/initializers/airbrake.rb
Airbrake.configure do |c|
  c.blocklist_keys = Rails.application.config.filter_parameters
end

有几个重要的细节：

1. 您必须在 Airbrake 配置之前加载 filter_parameter_logging.rb
2. 如果使用Lambdas配置filter_parameters，则需要转换它们 到过程。否则你会得到 ArgumentError
3. 如果使用 Procs 配置 filter_parameters，则 procs 必须返回 与 Airbrake allowlist/blocklist 选项兼容的按键阵列 （字符串、符号、正则表达式）

咨询 示例应用程序，其中 创建是为了展示如何配置 filter_parameters。

filter_parameters 点符号警告

rails/pull/13897 中引入的点表示法 不支持 filter_parameters（e.g。像 credit_card.code 这样的密钥） 性能原因。相反，只需指定 code 密钥即可。如果你有一个 对此有强烈意见，请发表评论 专用问题。

记录

在新的 Rails 应用程序中，默认情况下，所有 Airbrake 日志都会写入 log/airbrake.log。在旧版本中，我们曾经写到任何地方 Rails.logger 写入。如果您希望将应用程序升级到新行为， 请按以下方式配置您的记录器：

c.logger = Airbrake::Rails.logger

西纳特拉

要将 Airbrake 与 Sinatra 一起使用，只需 require gem，configure 即可 和 use 我们的 Rack 中间件。

# myapp.rb
require 'sinatra/base'
require 'airbrake'

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

  # Display debug output.
  c.logger.level = Logger::DEBUG
end

class MyApp < Sinatra::Base
  use Airbrake::Rack::Middleware

  get('/') { 1/0 }
end

run MyApp.run!

要运行该应用程序，请将名为 config.ru 的文件添加到同一目录并调用 来自控制台的 rackup。

# config.ru
require_relative 'myapp'

就这样！现在您可以向 localhost:9292 发送测试请求并检查您的 项目的仪表板出现新错误。

curl localhost:9292

机架

要从任何 Rack 应用程序向 Airbrake 发送异常，只需 use 我们的 Rack 中间件，以及[配置][配置]通知程序。

require 'airbrake'
require 'airbrake/rack'

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

use Airbrake::Rack::Middleware

注意：请注意，默认情况下库不会过滤任何参数， 包括用户密码。过滤掉密码 添加过滤器。

附加来自机架请求的信息

如果您想附加来自 Web 请求的附加信息（例如 HTTP headers），定义一个特殊的过滤器，例如：

Airbrake.add_filter do |notice|
  next unless (request = notice.stash[:rack_request])
  notice[:params][:remoteIp] = request.env['REMOTE_IP']
end

notice 对象携带真实的 Rack::Request 对象 它的 藏品。 机架请求始终可以通过 :rack_request 存储密钥进行访问。

可选的机架请求过滤器

该库附带了下面列出的可选预定义构建器。

RequestBodyFilter

RequestBodyFilter 将 Rack 请求正文附加到通知中。它接受一个 length 参数，告诉过滤器从正文中读取多少字节。

默认情况下，最多读取 4096 字节：

Airbrake.add_filter(Airbrake::Rack::RequestBodyFilter.new)

您可以通过将 Integer 参数传递给 过滤器。例如，读取最多 512 字节：

Airbrake.add_filter(Airbrake::Rack::RequestBodyFilter.new(512))

发送自定义路由故障性能

任意代码性能检测

对于应用程序中的每条路线，Airbrake 都会收集性能细分 统计数据。如果您需要坚控特定操作，您可以捕获您的 自己的细分：

def index
  Airbrake::Rack.capture_timing('operation name') do
    call_operation(...)
  end

  call_other_operation
end

这将对 call_operation 进行基准测试并将性能信息发送至 Airbrake，到相应的路线（在“操作名称”标签下）。

方法性能仪器

或者，您可以衡量特定方法的性能：

class UsersController
  extend Airbrake::Rack::Instrumentable

  def index
    call_operation(...)
  end
  airbrake_capture_timing :index
end

与上例类似，index方法的性能信息 将被发送到 Airbrake。

西德克

我们支持 Sidekiq v2+。它们的配置步骤是相同的。简单地说 require 我们的集成，您就完成了：

require 'airbrake/sidekiq'

如果您在 Airbrake 之前需要 Sidekiq，那么您甚至不必 require 手动进行任何操作，它应该开箱即用。

空气制动板::Sidekiq::RetryableJobsFilter

默认情况下，Airbrake 会通知所有错误，包括在 重试尝试。过滤掉这些错误并仅在 Sidekiq 时收到通知 已用尽重试，您可以添加 RetryableJobsFilter：

Airbrake.add_filter(Airbrake::Sidekiq::RetryableJobsFilter.new)

该过滤器接受可选的 max_retries 参数。设置后，它会配置 允许的不会触发 Airbrake 通知的作业重试次数。 通常，该参数由作业本身配置，但此设置需要 最高优先级并将该值强加于所有作业，因此在以下情况下要小心 你用它。默认情况下，未设置。

Airbrake.add_filter(
  Airbrake::Sidekiq::RetryableJobsFilter.new(max_retries: 10)
)

ActiveJob

无需额外配置。只需确保您已配置 带有队列适配器的 Airbrake 通知器。

雷斯克

简单地 require Resque 集成：

require 'airbrake/resque'

与 Rails 应用程序集成

如果您在 Rails 应用程序的上下文中使用 Resque，请创建一个 config/initializers/resque.rb 中的新初始化程序包含以下内容：

# config/initializers/resque.rb
require 'airbrake/resque'
Resque::Failure.backend = Resque::Failure::Airbrake

现在一切都准备好了。

一般整合

任何使用 Resque 的 Ruby 应用程序都可以与 Airbrake 集成。如果您可以要求 Airbrake gem after Resque，那么就没有必要要求 airbrake/resque 不再：

require 'resque'
require 'airbrake'

Resque::Failure.backend = Resque::Failure::Airbrake

如果您不确定，只需按照与 Rails 方法类似的方式进行配置即可。如果你使用 多个后端，然后继续阅读所需的配置步骤 Resque wiki（相当简单）。

DelayedJob

只需 require 我们的集成即可完成：

require 'airbrake/delayed_job'

如果您在 Airbrake 之前需要 DelayedJob，那么您甚至不必 require 手动进行任何操作，它应该开箱即用。

升龙轩

只需 require 我们的集成即可完成：

require 'airbrake/shoryuken'

如果您在 Airbrake 之前需要 Shoryuken，那么您甚至不必 require 手动进行任何操作，它应该开箱即用。

运动鞋

只需 require 我们的集成即可完成：

require 'airbrake/sneakers'

如果您在 Airbrake 之前需要运动鞋，那么您甚至不必 require 手动进行任何操作，它应该开箱即用。

ActionCable

ActionCable 集成发送 ActionCable 操作中发生的错误并 subscribed/unsubscribed 事件。如果您将 Rails 与 ActionCable 一起使用，则有 没什么可做的，它已经加载了。如果您在 Rails 之外使用 ActionCable，只需 要求它：

require 'airbrake/rails/action_cable'

耙子

Airbrake 提供 Rake 任务集成，我们的 Rails 使用它 integration^[链接]。要将 Airbrake 集成到任何项目中， 只是 require 你的 Rakefile 中的宝石，如果它没有被要求的话 [配置][配置]通知程序。

# Rakefile
require 'airbrake'

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

task :foo do
  1/0
end

记录器

如果您想将日志消息转换为 Airbrake 错误，您可以使用我们的 与 stdlib 中的 Ruby Logger 类集成。您需要做的就是 将您的记录器包装在 Airbrake 的装饰器类中：

require 'airbrake/logger'

# Create a normal logger
logger = Logger.new($stdout)

# Wrap it
logger = Airbrake::AirbrakeLogger.new(logger)

现在您可以按照与使用 logger 对象完全相同的方式使用它。对于 例如，调用 fatal 将会记录您的消息并将其发送到 空气制动板仪表板：

logger.fatal('oops')

Logger 类将尝试利用默认的 Airbrake 通知程序 传递消息。可以通过 #airbrake_notifier 重新定义它：

# Assign your own notifier.
logger.airbrake_notifier = Airbrake::NoticeNotifier.new

空气制动严重程度

为了减少记录器集成的噪音，可以 配置 Airbrake 严重级别。例如，如果您只想发送 fatal 来自 Logger 的消息，然后按如下方式配置：

# Send only fatal messages to Airbrake, ignore anything below this level.
logger.airbrake_level = Logger::FATAL

默认情况下，airbrake_level 设置为 Logger::WARN，这意味着 向 Airbrake 发送警告、错误和致命错误消息。

配置 Airbrake 记录器与 Rails 应用程序的集成

为了配置具有 Airbrake 集成的生产记录器，只需 使用 after_initialize 中的包装记录器覆盖 Rails.logger 回调：

# config/environments/production.rb
config.after_initialize do
  # Standard logger with Airbrake integration:
  # https://github.com/airbrake/airbrake#logger
  Rails.logger = Airbrake::AirbrakeLogger.new(Rails.logger)
end

使用 Rails 引擎时配置 Rails APM SQL 查询统计信息

默认情况下，该库收集 Rails SQL 性能统计数据。适用于标准导轨 应用程序无需额外配置。但是，如果您的应用程序使用 Rails engines，您需要采取 附加步骤以确保文件和行信息存在 在引擎代码中执行的查询。

具体来说，您需要确保您的 Rails.backtrace_cleaner 有一个消音器，不会使引擎代码静音（将被静音） 默认）。例如，如果您的引擎名为 blorgh 及其主目录 位于项目的根目录中，您需要扩展提供的默认消音器 使用 Rails 并将路径添加到您的引擎：

# config/initializers/backtrace_silencers.rb

# Delete default silencer(s).
Rails.backtrace_cleaner.remove_silencers!

# Define custom silencer, which adds support for the "blorgh" engine
Rails.backtrace_cleaner.add_silencer do |line|
  app_dirs_pattern = %r{A/?(app|config|lib|test|blorgh|(w*))}
  !app_dirs_pattern.match?(line)
end

纯 Ruby 脚本

Airbrake 支持任何类型的 Ruby 应用程序，包括纯 Ruby 脚本。 如果你想将你的脚本与 Airbrake 集成，你不必使用这个 宝石。 Airbrake Ruby gem 提供了所有需要的工具。

部署跟踪

通过通知 Airbrake 您的应用程序部署，所有错误都得到解决 当部署发生时，以便您会再次收到有关任何错误的通知 部署后再次发生。此外，还可以检查以下错误 部署前后发生的空气制动。

有多种方法可以将部署跟踪与您的应用程序集成， 如下所述。

卡皮斯特拉诺

该库支持 Capistrano v2 和 Capistrano v3。为了配置 使用 Capistrano 部署跟踪只需 require 我们从您的集成 上限文件：

# Capfile
require 'airbrake/capistrano'

如果您使用 Capistrano 3，请定义 after :finished 挂钩，该挂钩执行 部署通知任务（Capistrano 2 不需要此步骤）。

# config/deploy.rb
namespace :deploy do
  after :finished, 'airbrake:deploy'
end

如果您对应用程序进行版本控制，则可以在中设置 :app_version 变量 config/deploy.rb，以便该信息将附加到您的部署中。

# config/deploy.rb
set :app_version, '1.2.3'

耙子任务

Rake 任务可以接受下表所示的多个参数：

钥匙	必填	默认	示例
ENVIRONMENT	否	Rails.env	生产
USERNAME	否	无	约翰
REPOSITORY	否	无	https://github.com/airbrake/airbrake
REVISION	否	无	38748467ea579e7ae64f7815452307c9d05e05c5
VERSION	否	无	v2.0

在轨道中

只需调用 rake airbrake:deploy 并传递所需的参数：

rake airbrake:deploy USERNAME=john ENVIRONMENT=production REVISION=38748467 REPOSITORY=https://github.com/airbrake/airbrake

任何地方

确保将 require 库 Rake 集成到您的 Rakefile 中。

# Rakefile
require 'airbrake/rake/tasks'

然后，像 Rails 示例中所示那样调用它。

支持的红宝石

• CRuby >= 2.6.0
• JRuby >= 9k

联系方式

如果您有问题、疑问或错误报告，请随时：

• [提出问题][问题]
• 给我们发送电子邮件
• [向我们发推文][X]
• 与我们聊天（访问airbrake.io并点击圆形橙色 右下角按钮）

许可证

该项目使用MIT许可证。详情请参见LICENSE.md。

开发与测试

为了运行测试套件，首先，克隆存储库并安装 与 Bundler 的依赖关系。

git clone https://github.com/airbrake/airbrake.git
cd airbrake
bundle

接下来，运行单元测试。

bundle exec rake

为了测试与框架和其他库的集成，请安装它们 借助以下命令的依赖关系：

bundle exec appraisal install

要运行特定框架的集成测试，请使用 appraisal 命令。

bundle exec appraisal rails-4.2 rake spec:integration:rails
bundle exec appraisal sinatra rake spec:integration:sinatra

专业提示：GitHub 操作配置 具有以下列表 所有集成测试和调用它们的命令。