QT应用中集成 Sentry

Sentry 是一个开源的错误监控和日志记录平台，旨在帮助开发团队实时捕获、跟踪和解决软件应用程序中的错误和异常。它提供了强大的错误监控和日志记录工具，使开发团队能够快速定位并解决生产环境中的问题。

在现代软件开发中，错误和异常是不可避免的。良好的错误监控和日志记录系统可以帮助开发团队快速响应和解决问题，提高软件的可靠性和稳定性。通过及时发现和修复问题，可以降低用户遭遇错误的概率，提升用户体验，同时也有助于保护品牌声誉。

本文将介绍如何集成 Sentry 到 QT应用程序，实现一个完善的错误监控和日志记录功能，解决 C 端产品因为用户环境等原因导致的难于定位、难于收集有效信息的痛点。

Sentry SDK for C/C++

第一步，前往 https://github.com/getsentry/sentry-native 下载 Sentry Native SDK。Sentry Native SDK 是一个针对本机应用程序的错误和崩溃报告客户端，针对 C 和 C++ 进行了优化，支持Sentry 20.6.0及更高版本。截止本文撰写的时间，最新版本是 0.7.0，直接下载 sentry-native.zip 这个包。

解压 sentry-native.zip 压缩包：

unzip sentry-native.zip -d sentry-native

第二步，编译 Sentry Native SDK。

$ cd sentry-native/
$ cmake -B build -D SENTRY_BACKEND=crashpad -D SENTRY_INTEGRATION_QT=YES
$ cmake --build build --parallel
# 将头文件和库文件等安装到 install 目录
$ cmake --install build --prefix install --config RelWithDebInfo
# 查看 install 下的目录结构，如果系统没有 tree 命令，使用 sudo apt install tree 安装
$ tree install
install
├── bin
│   └── crashpad_handler
├── include
│   └── sentry.h
└── lib
    ├── cmake
    │   └── sentry
    │       ├── sentry-config.cmake
    │       ├── sentry-config-version.cmake
    │       ├── sentry_crashpad-targets.cmake
    │       ├── sentry_crashpad-targets-relwithdebinfo.cmake
    │       ├── sentry-targets.cmake
    │       └── sentry-targets-relwithdebinfo.cmake
    └── libsentry.so

如果出现如下错误：

CMake Error at /home/alex/.local/lib/python3.8/site-packages/cmake/data/share/cmake-3.27/Modules/FindCURL.cmake:176 (message):
  CURL: Required feature AsynchDNS is not found
Call Stack (most recent call first):
  CMakeLists.txt:278 (find_package)

解决方法：

$ sudo apt install libcurl4-openssl-dev

可以看到，编译出来的 Sentry Native SDK 包含头文件、库文件，还有一个 crashpad_handler，需要注意的是，crashpad_handler 这个文件需要放到应用程序所在的目录下。

注册 Sentry 账号

Sentry 服务可以本地部署，也可以直接使用 Sentry 提供的免费服务。对于个人开发者来说，Sentry 提供的免费服务够用，没有必要自行去折腾。

访问 https://sentry.io 网站，首先注册一个账号，这个过程和大多数注册过程相同，按照提示进行即可，这里就不赘述。

注册完成后，出现如下界面：

点击上面的那个Start按钮，会一步步直到你配置项目。

先点上面的 Desktop，就会出现桌面项目，然后点 QT，最后点击右下角的 Configure SDK。出现针对 QT 的集成代码示例，参照代码示例就可以完成在 QT 项目中集成 Sentry SDK。

点击右下角的 View Sample Error，系统会生成一个 Error 示例，在 Sentry 控制台可以看到：

上图展现了一个 Sentry 上报事件的详细信息。

QT 应用中集成 Sentry

借助于 Sentry native SDK，我们很容易集成 Sentry。下面用一个简单的示例程序进行说明，为了简单起见，我们创建一个控制台程序，项目起名为 SentryDemo。

按照前面 Qt SDK 配置提示的那样，在 main.cpp 中加入 sentry 初始化代码：

    sentry_options_t *options = sentry_options_new();
    sentry_options_set_dsn(options, "https://47e01ddf9ed4e2ce58914c67cd315d07@o4506677667561472.ingest.sentry.io/4506683131428864");
    // This is also the default-path. For further information and recommendations:
    // https://docs.sentry.io/platforms/native/configuration/options/#database-path
    sentry_options_set_database_path(options, ".sentry-native");
    sentry_options_set_release(options, "my-project-name@2.3.12");
    sentry_options_set_debug(options, 1);
    sentry_init(options);

其中第二行代码要换成你的 Sentry 项目的 DSN，这个值可以在 sentry.io 的项目设置中查到。

接下来加入一个简单的事件捕获代码：

    sentry_capture_event(sentry_value_new_message_event(
      /*   level */ SENTRY_LEVEL_INFO,
      /*  logger */ "custom",
      /* message */ "It works!"
    ));

为了使得代码编译通过，还得修改项目工程 pro 文件，加入：

INCLUDEPATH += $${PWD}/../thirdparty/sentry-native/install/include
LIBS += -L$${PWD}/../thirdparty/sentry-native/install/lib -lsentry

这样就得到了 SentryDemo 可执行程序，需要注意的是，在运行 SentryDemo 前，需要将前一步编译 Sentry Native SDK 得到的 libsentry.so 和 crashpad_handler 复制到和可执行程序相同的目录。执行结果如下：

$ ./SentryDemo 
[sentry] INFO using database path "/work/mywork/qt-in-action/source/build-SentryDemo-Desktop_Qt_5_15_2_GCC_64bit-Debug/.sentry-native"
[sentry] DEBUG starting transport
[sentry] DEBUG starting background worker thread
[sentry] DEBUG starting backend
[sentry] DEBUG starting crashpad backend with handler "/work/mywork/qt-in-action/source/build-SentryDemo-Desktop_Qt_5_15_2_GCC_64bit-Debug/crashpad_handler"
[sentry] DEBUG background worker thread started
[sentry] DEBUG using minidump URL "https://o4506677667561472.ingest.sentry.io:443/api/4506683131428864/minidump/?sentry_client=sentry.native/0.7.0&sentry_key=47e01ddf9ed4e2ce58914c67cd315d07"
[sentry] INFO started crashpad client handler
[sentry] DEBUG setting up Qt integration
[sentry] DEBUG processing and pruning old runs
[sentry] DEBUG merging scope into event
[sentry] DEBUG trying to read modules from /proc/self/maps
[sentry] DEBUG read 57 modules from /proc/self/maps
[sentry] DEBUG adding attachments to envelope
[sentry] DEBUG sending envelope
[sentry] DEBUG submitting task to background worker thread
[sentry] DEBUG executing task on worker thread
*   Trying 34.120.195.249:443...
* TCP_NODELAY set
* Connected to o4506677667561472.ingest.sentry.io (34.120.195.249) port 443 (#0)
* ALPN, offering h2
* ALPN, offering http/1.1
* successfully set certificate verify locations:
*   CAfile: /etc/ssl/certs/ca-certificates.crt
  CApath: /etc/ssl/certs
* SSL connection using TLSv1.3 / TLS_AES_256_GCM_SHA384
* ALPN, server accepted to use h2
* Server certificate:
*  subject: C=US; ST=California; L=San Francisco; O=Sentry; CN=ingest.sentry.io
*  start date: Nov  2 00:00:00 2023 GMT
*  expire date: Dec  2 23:59:59 2024 GMT
*  subjectAltName: host "o4506677667561472.ingest.sentry.io" matched cert's "*.ingest.sentry.io"
*  issuer: C=US; O=DigiCert Inc; CN=DigiCert Global G2 TLS RSA SHA256 2020 CA1
*  SSL certificate verify ok.
* Using HTTP2, server supports multi-use
* Connection state changed (HTTP/2 confirmed)
* Copying HTTP/2 data in stream buffer to connection buffer after upgrade: len=0
* Using Stream ID: 1 (easy handle 0x55ad8d179b20)
> POST /api/4506683131428864/envelope/ HTTP/2
Host: o4506677667561472.ingest.sentry.io
user-agent: sentry.native/0.7.0
accept: */*
x-sentry-auth:Sentry sentry_key=47e01ddf9ed4e2ce58914c67cd315d07, sentry_version=7, sentry_client=sentry.native/0.7.0
content-type:application/x-sentry-envelope
content-length:13896

* We are completely uploaded and fine
* old SSL session ID is stale, removing
* Connection state changed (MAX_CONCURRENT_STREAMS == 100)!
< HTTP/2 200 
< server: nginx
< date: Sat, 03 Feb 2024 13:54:11 GMT
< content-type: application/json
< content-length: 41
< access-control-allow-origin: *
< vary: origin,access-control-request-method,access-control-request-headers
< access-control-expose-headers: x-sentry-error,x-sentry-rate-limits,retry-after
< cross-origin-resource-policy: cross-origin
< x-envoy-upstream-service-time: 0
< strict-transport-security: max-age=31536000; includeSubDomains; preload
< via: 1.1 google
< alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000
< 
{"id":"8a84cd16adab42f49611bb32adfe72f0"}* Connection #0 to host o4506677667561472.ingest.sentry.io left intact

前往 sentry.io，可以看到我们收到如下消息上报：

点开，可以查看事件的详细信息。

可以看到，详细信息中包含操作系统版本、程序发布版本等等。

看到这里，你可能觉得，这不就是一个日志系统吗？

当然，你的确可以把 Sentry 当做一个在线日志系统，还是加强版本的。事件消息可以分级（level），还可以自定义类别（logger），还可以分版本（release）。

不过这样做，就有点暴殄天物了，因为 Sentry 还可以收集 crash 日志。

触发 Crash 上报

在程序中加入一段能引发内存访问错误的代码，模拟程序崩溃，看看会发生什么。

static void *invalid_mem = (void *)1;

static void
trigger_crash()
{
    memset((char *)invalid_mem, 1, 100);
}

在 main 函数中调用 trigger_crash，运行之后，在 sentry.io 管理端就可以看到有新的 crash 报告上来：

点开可以查看详情：

这样，我们在程序崩溃时，就得到了错误上报，还包含了 crash 堆栈，通过调试符号，我们可以根据偏移地址，找到对应的源码行。

Sentry 的强大在于，我们可以上传调试符号文件，Sentry 自动分析符号文件，直接定位到源代码行，省去了我们使用 addr2line 之类的工具。

如何生成调试符号文件，如何上传调试符号文件，咱们在下一章再见。