监测库

如何使用 Swift 监测库

OpenTelemetry-Swift 提供了几个监测库，安装和初始化后可以自动生成监测代码。

`SDKResourceExtension`

SDKResourceExtension 提供有关设备的细节作为资源。

用法

使用 DefaultResource.get() 生成一个完整的资源对象。该资源对象可以添加到 TracerProvider 或 MetricProvider 中。

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

详情

SDKResourceExtension 提供了一个包含了 iOS 设备、操作系统和应用详细信息的资源对象。它将这些值应用到相应的语义属性。

应用信息

属性	示例值	描述
`service.name`	`MyApplication`	`CFBundleName`；在 App 的 info.plist 中定义的应用名称。
`service.version`	`1.0 (1234)`	`CFBundleShortVersion` 和 (`CFBundleVersion`)；在 App 的 info.plist 中定义的应用版本。
`service.namespace`	`com.myCompany.myApplication`	`CFBundleIdentifier`

设备信息

属性	示例值	描述
`device.model.identifier`	`iphone13,3`	根据设备类型从 `sysctl` 获取
`device.id`	`00000000-0000-0000000`	`identifierForVendor` 的 UUID 字符串

操作系统信息

属性	示例值	描述
`os.type`	`darwin`	在 `ResourceAttributes` 中预定义
`os.name`	`iOS`、`watchOS`、`macOS`	`UIDevice.current.systemName` 或依赖于平台
`os.version`	`15.4.0`	`ProcessInfo.processInfo.operatingSystemVersion`
`os.description`	`iOS Version 15.4 (Build 19E240)`	包含操作系统名称、版本和构建信息的组合

`NSURLSession` 监测

该监测库会为所有使用 NSURLSessions 进行的网络请求生成跨度 (span)。它还会在被监测的网络请求中注入分布式追踪头信息。NetworkStatus 是此包的依赖项，它提供了网络状态属性。

注意：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 监测还提供了其他属性，提供了在进行网络请求时设备的网络状态的详细信息。

属性	示例值	描述
`net.host.connection.type`	`wifi`、`cell`、`unavailable`	在请求时设备所使用的连接类型。
`net.host.connection.subtype`	`EDGE` `LTE` 等	蜂窝网络连接的类型。仅在连接类型为 `cell` 时填充。
`net.host.carrier.name`	`T-Mobile`、`Verizon` 等	移动网络运营商的名称。仅对蜂窝连接类型填充。
`net.host.carrier.icc`	`DE`	与移动通信网络关联的 ISO 3166-1 alpha-2 2 字符国家代码。
`net.host.carrier.mcc`	`310`	移动国家代码。
`net.host.carrier.mnc`	`001`	移动网络代码。

`SignpostIntegration`

该包在开始或结束跨度时会创建 os_signpost 的 begin 和 end 调用。它允许自动集成使用 OpenTelemetry 进行监测的应用程序，在类似于 Instruments 的性能分析应用中显示它们的跨度。它还会导出它用于发布的 OSLog，以便用户可以添加额外的 signpost 事件。该功能在 Simple Exporter 示例中展示。

用法

只需像其他跨度处理器一样添加 SignpostIntegration（参见手动监测文档了解如何配置提供者）：

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

最后修改 December 10, 2023: translate (a4350d6e)

监测库

SDKResourceExtension

用法

详情