Instrumentation Libraries

当你开发应用时，可能会使用第三方库和框架来加快开发进度。如果你随后使用 OpenTelemetry 对应用进行插桩，你可能希望避免额外花时间为所用的第三方库和框架手动添加链路、日志和指标。

许多库和框架已经原生支持 OpenTelemetry，或者通过 OpenTelemetry 的插桩获得支持， 因此它们能够生成可导出到可观测性后端的遥测数据。

如果你正在为使用第三方库或框架的应用或服务进行插桩， 请按照以下说明学习如何为你的依赖项使用原生插桩库和插桩库。

使用原生插桩库

如果某个库默认就支持 OpenTelemetry，你只需在应用中添加并配置 OpenTelemetry SDK， 就可以获取该库发出的链路、指标和日志。

该库可能需要一些额外的插桩配置。请查阅该库的文档以了解更多信息。

Use instrumentation libraries

OpenTelemetry-Swift provides several instrumentation libraries that generate instrumentation for you when they’re installed and initialized.

For example, the NSURLSession instrumentation automatically creates spans for all network requests made with NSURLSessions.

Setup

All instrumentation libraries are available in OpenTelemetry Swift. To turn on an instrumentation, follow its instructions.

SDKResourceExtension

SDKResourceExtension provides details about the device as a Resource.

Usage

Use DefaultResource.get() to generate an all-in-one resource object. This resource can be added to a TracerProvider or MetricProvider.

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

Details

SDKResourceExtension provides attributes in a resource object with details about the iOS device, OS details, and application details. It applies these values to the appropriate semantic attributes.

Application Info

Device Info

Operating System Info

NSURLSession instrumentation

This instrumentation creates spans for all network requests made with NSURLSessions. It also injects distributed tracing headers in instrumented network requests. NetworkStatus is a dependency of this package, which provides network status attributes on network spans.

Note: The NSURLSession instrumentation relies on the global tracer provider in the OpenTelemetry object. Custom tracer providers must be configured and set as the global provider prior to this instrumentation.

Usage

Initialize the class with URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration()) to automatically capture all network calls.

This behavior can be modified or augmented by using the optional callbacks defined in URLSessionInstrumentationConfiguration:

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

  Filter which requests you want to instrument, all by default.

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

  Implement if you want the session to record payload data, false by default.

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

  Allow filtering which requests you want to inject headers to follow the trace, true by default. You must also return true if you want to inject custom headers.

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

  Implement this callback to inject custom headers or modify the request in any other way.

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

  Modify the name for the given request instead of standard OpenTelemetry name.

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

  Called after request is created, it allows to add extra information to the Span.

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

  Called after response is received, it allows to add extra information to the Span.

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

  Called after an error is received, it allows to add extra information to the Span.

Below is an example of initialization. URLSessionInstrumentationConfiguration’s construction can be passed the parameters defined above to suit the needs of the application.

let sessionInstrumentation = URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration())

Details

NSURLSession instrumentation also provides additional attributes providing details about the network state of the device at the time of network requests.

SignpostIntegration

This package creates os_signpost begin and end calls when spans are started or ended. It allows automatic integration of applications instrumented with OpenTelemetry to show their spans in a profiling app like Instruments. It also exports the OSLog it uses for posting so the user can add extra signpost events. This functionality is shown in Simple Exporter example.

Version Notice

• iOS 15+, macOS 12+, tvOS 15+, watchOS 8+: Use OSSignposterIntegration, which utilizes the modern OSSignposter API for improved efficiency and compatibility.
• Older systems: Use SignPostIntegration, which relies on the traditional os_signpost API.

Usage

Add the appropriate span processor based on your deployment target (see the manual instrumentation) docs for details on configuring your providers:

For iOS 15+, macOS 12+, tvOS 15+, watchOS 8+:

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

For older systems

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

Or, to select automatically at runtime:

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

Available instrumentation libraries

A full list of instrumentation libraries produced by OpenTelemetry is available from the opentelemetry-swift repository.

You can also find more instrumentations available in the registry.

Next steps

After you have set up instrumentation libraries, you might want to add your own instrumentation to your code, to collect custom telemetry data.