Electron 接入 Sentry 及 crash 处理

Electron 的 Sentry SDK 可以捕获主进程(main)和渲染进程(renderer)中的 JavaScript 异常、主进程事件以及收集本机崩溃报告(Minidumps)。

接入非常简单,本文主要说说怎样处理 crash。

安装

详见文档 👉🏻 https://docs.sentry.io/platforms/javascript/guides/electron/

# Using yarn
yarn add @sentry/electron

# Using npm
npm install @sentry/electron

配置

详见文档 👉🏻 https://docs.sentry.io/platforms/javascript/guides/electron/configuration/

import * as Sentry from '@sentry/electron'

Sentry.init({
  // 上报的地址
  dsn: 'dsn url',
  // 设置产品版本号
  release: 'project@v1.0.1',
  // 设置环境 development || test || production
  // 不手动设置的话,默认使用打包(production)和非打包(development)
  environment: process.env.SENTRY_ENV,
  tracesSampleRate: 1.0
})

// 设置用户标识 - 邮箱
Sentry.setUser({ id: '30000319373628' })
// 添加标签 - 应用版本号
Sentry.setTag('version', process.env.VUE_APP_VERSION)

默认的 release 使用的是服务版本号,即 package.json 的 appName@version
你可以手动设置成产品名机产品版本号,但需要注意格式是 [产品名]@[产品版本号],例如 wechat@v1.0.0

其他的例如,添加用户标识、添加标签、添加上下文甚至添加附件都可以在官方文档里找到详细的说明,这里不再赘述

解析 Crash

Sentry 虽然可以在崩溃时将本机崩溃报告(Minidumps)上传上来,但上传的 minidump 是汇编级别的代码,所以还需要上传 Electron 对应版本的调试 symbol 文件用来解析报告

模拟 crash

Electron 应用启动后,打开控制台,在控制台输入 window.process.crash() 模拟进程崩溃
可以在 Sentry 平台上看到上报的异常信息,但都是 unknown

sentry-cli

官方提供的命令行工具(https://docs.sentry.io/product/cli/),使用它上传文件到 Sentry
它提供了各种各样的安装方式:npm、homebrew、手动等等,选择你自己熟悉的方式即可

安装

以 npm 为例

// 全局安装
sudo npm install -g @sentry/cli --unsafe-perm

配置

首先利用 sentry-cli 登录,url 默认是 http://sentry.io,如果是自建 sentry,则需要设置 url ,例如 http://xxx.xx.xxx.xxx:9000/

# 默认登录
sentry-cli login

# 登录自建的 sentry
sentry-cli --url [your sentry url] login

登录成功后会自动在浏览器中打开 Auth Tokens 页面

自行创建 token 后输入到控制台中即完成配置,cli 会在系统根目录下创建 .sentryclirc 配置文件

虽然创建了 .sentryclirc 文件但里面只保存了刚才输入的 token, 所以如果 sentry 是自建的,还需要手动添加 sentry 的地址

vi $HOME/.sentryclirc

注意: 默认配置放到前面避免授权失败

[defaults]
url = [your sentry url]

查看配置

sentry-cli info

sentry-wizard

官方提供的设置引导工具,用它来下载 Electron 的 symbol 文件

安装

sudo npm install -g @sentry/wizard --unsafe-perm

配置

在 Electron 应用项目下运行

sentry-wizard --integration electron --url [your sentry url]

根据向导选择项目后会在项目根目录创建一个 sentry-symbols.js 文件

下载&上传

# Using yarn
yarn add -D @sentry/cli electron-download

# Using npm
npm install --save-dev @sentry/cli electron-download

运行成功后项目根目录下会自动生成一个 sentry-symbols.js 文件

自动

// 下载 symbol文件 并自动上传
node sentry-symbols.js

然后就是漫长的下载过程,根据当前使用的 Electron 版本下载各系统下的 symbol 文件( 需要 🪜 )

手动

如果因为网络问题一直下载失败,可以在 sentry-symbols.js 中查看需要下载的版本,自行在官方 GitHub 找到对应版本的文件进行下载
官网地址: https://github.com/electron/electron/releases

比如 现在正在使用的版本是 v12.0.0
https://github.com/electron/electron/releases/tag/v12.0.0 找到对应 tag

sentry-symbols.js 中显示要下载 4 个文件,

  • electron-v12.0.0-darwin-x64-dsym.zip
  • electron-v12.0.0-win32-ia32-symbols.zip
  • electron-v12.0.0-win32-x64-symbols.zip
  • electron-v12.0.0-linux-x64-symbols.zip

可根据应用部署环境选择性下载

sentry-cli upload-dif -t breakpad -o [组织名] -p [项目名]  [symbols 文件路径]

验证文件

在项目设置里的调试文件中可以查看 symbols 是否上传成功

异常解析对比

解析前

解析后

目录