检测库

在开发应用程序时，您可能会使用第三方库和框架来加速您的工作。如果您随后使用 OpenTelemetry instrumentation 您的应用程序，您可能希望避免花费额外的时间手动为您使用的第三方库和框架添加 traces、logs 和 metrics。

许多库和框架已经支持 OpenTelemetry，或者通过 OpenTelemetry instrumentation 进行支持，因此它们可以生成您可以导出到可观测性后端的 telemetry。

如果您正在 instrumentation 使用第三方库或框架的应用程序或服务，请遵循以下说明，了解如何为您的依赖项使用原生 instrumented 库和 instrumentation 库。

使用原生 instrumented 库

如果一个库默认包含 OpenTelemetry 支持，您可以通过在您的应用程序中添加和设置 OpenTelemetry SDK 来获取该库发出的 traces、metrics 和 logs。

该库可能需要一些额外的配置来进行 instrumentation。请参阅该库的文档以了解更多信息。

使用插装库

OpenTelemetry-Swift 提供了多种仪器化库，当它们被安装和初始化时，会自动生成仪器化数据。

例如，NSURLSession 仪器化会自动为使用 NSURLSession 进行的所有网络请求创建span。

设置

所有仪器化库均在 OpenTelemetry Swift 中可用。要启用仪器化，请遵循其说明。

SDKResourceExtension

SDKResourceExtension 以 Resource 的形式提供有关设备的详细信息。

用法

使用 DefaultResource.get() 来生成一个一体化资源对象。此资源可以添加到 TracerProvider 或 MetricProvider。

OpenTelemetry.registerTracerProvider(tracerProvider: TracerProviderBuilder()
            .with(resource: DefaultResource.get())
            .build())

详情

SDKResourceExtension 在资源对象中提供有关 iOS 设备、操作系统详细信息和应用程序详细信息的属性。它将这些值应用于相应的语义属性。

应用信息

设备信息

操作系统信息

NSURLSession 仪器化

此仪器化会为所有使用 NSURLSessions 进行的网络请求创建 span。它还会将分布式跟踪标头注入到被仪器化的网络请求中。NetworkStatus 是此软件包的依赖项，它在网络 span 上提供网络状态属性。

注意：NSURLSession 仪器化依赖于 OpenTelemetry 对象中的全局跟踪器提供程序。必须在进行此仪器化之前配置自定义跟踪器提供程序并将其设置为全局提供程序。

用法

使用 URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration()) 初始化此类，以自动捕获所有网络调用。

可以使用 URLSessionInstrumentationConfiguration 中定义的可选回调来修改或增强此行为。

• shouldInstrument: ((URLRequest) -> (Bool)?)?

  过滤您要仪器化的请求，默认情况下全部仪器化。

• shouldRecordPayload: ((URLSession) -> (Bool)?)?

  如果您希望会话记录有效负载数据，请实现此项，默认值为 false。

• shouldInjectTracingHeaders: ((URLRequest) -> (Bool)?)?

  允许过滤您要注入标头的请求以跟踪，默认值为 true。如果您想注入自定义标头，也必须返回 true。

• injectCustomHeaders: ((inout URLRequest, Span?) -> Void)?

  实现此回调以注入自定义标头或以任何其他方式修改请求。

• nameSpan: ((URLRequest) -> (String)?)?

  修改给定请求的名称，而不是标准的 OpenTelemetry 名称。

• createdRequest: ((URLRequest, Span) -> Void)?

  在请求创建后调用，允许向 Span 添加额外信息。

• receivedResponse: ((URLResponse, DataOrFile?, Span) -> Void)?

  在响应接收后调用，允许向 Span 添加额外信息。

• receivedError: ((Error, DataOrFile?, HTTPStatus, Span) -> Void)?

  在接收到错误后调用，允许向 Span 添加额外信息。

以下是初始化示例。URLSessionInstrumentationConfiguration 的构造函数可以传递上面定义的参数，以满足应用程序的需求。

let sessionInstrumentation = URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration())

详情

NSURLSession 仪器化还提供其他属性，提供有关设备在网络请求时的网络状态的详细信息。

SignpostIntegration

当 span 开始或结束时，此软件包会创建 os_signpost 的 begin 和 end 调用。它允许与 OpenTelemetry 仪器化的应用程序自动集成，以便在 Instruments 等分析应用程序中显示其 span。它还导出用于发布 OSLog，以便用户可以添加额外的 signpost 事件。此功能在 Simple Exporter 示例中展示。

版本通知

• iOS 15+、macOS 12+、tvOS 15+、watchOS 8+：使用 OSSignposterIntegration，它利用现代的 OSSignposter API 以提高效率和兼容性。
• 旧系统：使用 SignPostIntegration，它依赖于传统的 os_signpost API。

用法

根据您的部署目标添加适当的 span processor（请参阅 手动仪器化）文档以获取有关配置您的提供程序的详细信息。

对于 iOS 15+、macOS 12+、tvOS 15+、watchOS 8+：

OpenTelemetry.instance.tracerProvider.addSpanProcessor(OSSignposterIntegration())

对于旧系统

OpenTelemetry.instance.tracerProvider.addSpanProcessor(SignPostIntegration())

或者，在运行时自动选择：

if #available(iOS 15, macOS 12, tvOS 15, watchOS 8, *) {
    OpenTelemetry.instance.tracerProvider.addSpanProcessor(OSSignposterIntegration())
} else {
    OpenTelemetry.instance.tracerProvider.addSpanProcessor(SignPostIntegration())
}

可用检测库

OpenTelemetry 生成的仪器化库的完整列表可在 opentelemetry-swift 存储库中找到。

您还可以在注册表中找到更多可用的仪器化。

下一步

设置好仪器化库后，您可能希望在代码中添加自己的仪器化，以收集自定义遥测数据。