Sign in Subscribe
Bug

Debug｜使用 Sentry SDK 主动捕获并上报事件

了解如何在 iOS 应用中使用 Sentry SDK 主动上报错误，补充默认崩溃和问题收集之外的场景。

廖林

• 2 min read

在 iOS SDK 中，完成 Sentry 初始化之后，就会默认开启一些自动化的事件和 issue 收集功能，主要包括：

  1. 崩溃捕获：未捕获的异常、Objective-C 异常、Swift fatal error、信号崩溃等。
  2. ANR（App Not Responding）检测：主线程长时间阻塞时，会被记录为一个 issue。
  3. 启动性能数据：应用启动时的冷启动、热启动的耗时。
  4. 面包屑（breadcrumbs）：比如 app 进入后台/前台、网络请求、UIViewController 生命周期等。
  5. 设备信息和上下文：包括 iOS 版本、设备型号、App 版本号等。

Sentry 默认不收集的问题

始化后虽然会自动捕获一些常见的 crash 和错误，但有很多类型是不会自动收集的，需要开发者显式上报或启用额外功能。

  1. 业务逻辑错误

比如接口返回的数据格式错误、登录失败、权限不足等。这类错误不会被自动收集。

  1. 非致命异常

try/catch 捕获到的异常、NSError、Swift Result.failure 等，如果你自己处理了，Sentry不会自动上报。

  1. 自定义断言 / 逻辑判断失败

例如 assert(someCondition) 或内部校验不通过，不会默认上报。

  1. UI 逻辑问题

如按钮点击无响应、页面显示错误等不会被捕获。

  1. 业务埋点数据

例如订单提交失败、支付超时、用户行为等，需要你主动打点。

  1. 日志 / 警告

普通的 print、NSLog、os_log 信息不会被默认上传。

Sentry 主动上传问题的 API

SentrySDK.capture

Sentry SDK 提供了 SentrySDK.capture(...) 系列方法，用于手动捕获并上报事件。

支持直接传入不同类型的对象：

  • SentrySDK.capture(error: Error) → 上报 Swift/Objective-C 错误对象
  • SentrySDK.capture(exception: NSException) → 上报异常
  • SentrySDK.capture(message: String) → 上报一条消息（类似日志）
  • SentrySDK.capture(event: Event) → 上报一个你手动构造好的事件

capture 就是把某个错误/消息/事件提交到 Sentry 的通用方法。

Sentry.Event

sentry.Event 是事件对象模型（数据结构），不是一个方法。它专门用于构造更定制化的上报内容。

let event = Sentry.Event(level: .error)
event.message = SentryMessage(formatted: "User profile data invalid")
event.extra = ["userId": "12345", "field": "email"]
SentrySDK.capture(event: event)

通过这个模型对象，我们可以完全控制事件内容（level、tags、user、extra 等）