拥抱 Apple SDK

Embrace Apple SDK 能够检测您的 iOS、iPadOS、tvOS、visionOS 和 watchOS* 应用，从而收集可观测性数据。此项目代表着从之前的 Embrace SDK 的转变，它采用了一种更模块化的方法，支持 OpenTelemetry 标准。我们还添加了一些功能来扩展 OpenTelemetry，以便更好地支持移动应用。

通过此 SDK 记录的遥测数据可供 Embrace 平台的 Embrace 客户使用，但非 Embrace 客户也可以使用它，将收集的数据直接导出到任何 OTel Collector，无论是他们自己托管的，还是由其他供应商托管的。实际上，对于希望利用 OpenTelemetry 生态系统进行可观测性，但同时也希望拥有 Embrace 以其而闻名的所有高级遥测捕获功能的 iOS 应用来说，此 SDK 是直接使用 OpenTelemetry Swift SDK 的替代方案。

目前，仅支持 Spans 和 Logs，但将来会添加其他信号。

更多文档和示例可以在 https://embrace.io/docs/ 中找到。

• 会话捕获
• 崩溃捕获
• 网络捕获
• OTel 追踪捕获
• 自定义面包屑
• 自定义日志
• OpenTelemetry 导出
• 会话属性
• 自动视图追踪
• 网络负载捕获

• Metrickit 捕获

有关更详细的演练，请查看 GETTING_STARTED 文档。您也可以打开 Examples/BrandGame 下的 BrandGame 项目，查看一个已经设置并使用 EmbraceIO 包的应用。

以下是开始使用 Embrace SDK 的快速概述。 您需要：

1. 导入 EmbraceIO 模块
2. 通过将 Embrace.Options 传递给 setup 方法来创建 Embrace 客户端的实例。
3. 在该实例上调用 start 方法

这应该在应用程序运行时尽早完成，例如，UIApplicationDelegate.applicationDidFinishLaunching(_:) 可能是一个好地方。

这是一个代码片段

import EmbraceIO
// ...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    do {
      try Embrace.setup(options: .init(appId: "myApp"))
      try Embrace.client?.start()
    } catch {
      // Unable to start Embrace
    }

    return true
}

也可以链式调用这些方法，因为 setup 将返回 Embrace.client 实例

import EmbraceIO
// ...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    do {
      try Embrace
        .setup( .init(appId: "myApp") )
        .start()

    } catch {
      // Unable to start Embrace
    }

    return true
}

SDK 在启动过程中不太可能失败，但也有可能。 最明显的原因是磁盘上没有剩余空间来创建我们的数据存储，或者这些数据存储可能已损坏。 该接口考虑了这些边缘情况，如果它们发生，将抛出一个错误。

如果从未调用过 setup 或者 setup 抛出错误，则 Embrace.client 实例将返回 nil。 可以使用 Swift 的“Optional try”来使此入口点尽可能简洁

import EmbraceIO
// ...

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    try? Embrace
        .setup(options: .init(appId: "myApp"))
        .start()

    // Can leverage optional behavior if desired
    let span = Embrace.client?.buildSpan("app-did-finish-launching", type: .performance)
    // ...
    span?.end()

    return true
}

现在您的 Embrace 实例已设置并启动，是时候添加一些自定义检测了！ 请在下面的文档中查看完整的功能列表，但这里有一些快速示例

创建一个 span

let span = Embrace.client?
  .buildSpan(name: "my-custom-operation", type: .performance)
  .startSpan()

// perform `my-custom-operation`

span?.end()

添加用户数据

Embrace.client?.metadata.userEmail = "testing.email@my-org.com"
Embrace.client?.metadata.userIdentifier = "827B02FE-D868-461D-8B4A-FE7371818369"
Embrace.client?.metadata.userName = "tony.the.tester"

我们正在使用我们自己的 KSCrash 分支，因此我们需要在 Xcode 中设置 Github 凭据以提供所需的访问权限。

• 转到“设置”中的“帐户”选项卡 (cmd+,)
• 验证您是否已保存 Github 凭据，或者单击 + 符号以添加 Github 凭据。

通过选择目录或 Package.swift 文件本身在 Xcode 中打开项目。 如果是第一次打开，Xcode 可能需要一些时间来解析 Package Dependencies 并索引项目。

要构建项目，请选择 EmbraceIO-Package 方案，然后在菜单中选择 Product -> Build (⌘+B)。

要在 Xcode 中运行测试，请选择 EmbraceIO-Package 方案，然后在菜单中选择 Product -> Test (⌘+U)。 您还可以打开 Test Navigator (⌘+6) 并使用 Xcode 的 UI 运行单个测试。

还有一个 bin/test 命令可用于从命令行运行测试。 建议通过 xcpretty 管道传输此命令。

bin/test | xcpretty

我们使用 SwiftLint 来强制执行一致性，并且每个 pull request 都必须通过 lint 检查才能合并。

您可以按照他们的 README 中的说明安装 SwiftLint。 我们推荐使用 homebrew

brew install swiftlint

一旦 swiftlint 在您的 PATH 中，您可以运行 linter

swiftlint --fix

除了直接在 Xcode 中出现的警告和错误之外，您还可以使用 SwiftLint 自动更正某些问题。 为此，您首先需要在本地环境中安装 SwiftLint。 请按照 SwiftLint 的 GitHub 页面 了解所有可用选项。

• 使用 swiftlint lint --strict 获取所有问题的报告。
• 尽可能使用 swiftlint --fix 自动修复问题。

我们强烈建议使用 pre-commit 钩子，以确保所有修改的文件在推送之前都符合指南。 我们在 .githooks/pre-commit 中提供了一个 pre-commit 钩子的示例。 请注意，根据您的本地环境，您可能需要编辑 pre-commit 文件以设置 swiftlint 的路径。

cp .githooks/pre-commit .git/hooks/pre-commit

关于如何设置钩子的其他方案

• 使用 core.hooksPath 设置来更改钩子路径 (git config core.hooksPath .githooks)

如果您无法获取 KSCrash 依赖项，则您很可能在 Xcode 中遇到 Github 授权问题。

1. 验证您是否已在“设置”中的“帐户”选项卡上设置 Github 凭据
2. 如果系统提示您这样做，请在该页面上输入 SSH 密钥的密码。
3. 如果您在 .gitconfig 中有以下内容，请将其删除，因为 Xcode 显然无法处理此问题

[url "ssh://git@github.com/"]
  insteadOf = https://github.com/

要测试您的更改是否修复了授权问题，请尝试使用“File”->“Packages”->“Reset package caches”获取依赖项。

我们感谢您对 SDK 及其提供的 API 的任何反馈。

要为该项目做出贡献，请参阅我们的 贡献指南。 完成个人贡献者许可协议 (CLA) 后，您将能够提交功能请求、创建错误报告或提交 pull request。

对于紧急事项（例如中断）或与 Embrace 服务或 UI 相关的问题，请在我们的 Community Slack 中联系，以获得直接、更快速的帮助。

Embrace Apple SDK 在 Apache-2.0 许可证下发布。