通过OpenTelemetry为Swift应用埋点并上报链路数据 - 可观测链路 OpenTelemetry 版

通过OpenTelemetry为应用埋点并上报链路数据至可观测链路 OpenTelemetry 版后，可观测链路 OpenTelemetry 版即可开始监控应用，您可以查看应用拓扑、调用链路、异常事务、慢事务和SQL分析等一系列监控数据。本文介绍如何使用OpenTelemetry为Swift应用埋点并上报数据。

前提条件

获取接入点信息

新版控制台

登录可观测链路 OpenTelemetry 版控制台，在左侧导航栏单击接入中心。
在开源框架区域单击OpenTelemetry卡片。
在弹出的OpenTelemetry面板中选择数据需要上报的地域。
说明
初次接入的地域将会自动进行资源初始化。
选择连接方式和上报方式，然后复制接入点信息。
- 连接方式：若您的服务部署在阿里云上，且所属地域与选择的接入地域一致，推荐使用阿里云内网方式，否则选择公网方式。
- 上报方式：根据客户端支持的协议类型选择HTTP或gRPC协议上报数据。

旧版控制台

登录可观测链路 OpenTelemetry 版控制台。
在左侧导航栏单击集群配置，然后在右侧页面单击接入点信息页签。
在页面顶部选择需要接入的地域，然后在集群信息区域打开显示Token开关。
在客户端采集工具区域单击OpenTelemetry。
在相关信息列中，获取接入点信息。
说明
如果应用部署于阿里云生产环境，则选择阿里云VPC网络接入点，否则选择公网接入点。

示例Demo

本文将通过具体示例介绍如何通过OpenTelemetry上报Swift语言编写的macOS命令行应用数据，该方法同样适用于iOS应用。

示例代码仓库地址：opentelemetry-swift-demo

步骤一：创建应用并添加依赖

选择要创建的应用，例如macOS的Command Line Tool。
在XCode中选择File > Add Packages...，然后在搜索框中输入https://github.com/open-telemetry/opentelemetry-swift，选择1.4.1版本。
说明
更多版本信息，请参考opentelemetry-swift releases信息。
选中所需的Package Products。
本文中使用到的Package Products如下：

步骤二：OpenTelemetry初始化

创建用于导出观测数据的组件。

从以下3种方法中选择1种上报Trace数据。

方法一：通过gRPC协议上报Trace数据

请分别将<gRPC-endpoint>和<gRPC-port>替换为从前提条件中获取的接入点信息，例如：host: "http://tracing-analysis-dc-hz.aliyuncs.com", port:8090。
请将<your-token>替换为从前提条件中获取的鉴权Token。

let grpcChannel = ClientConnection(
    configuration: ClientConnection.Configuration.default(
        target: .hostAndPort("<gRPC-endpoint>", 8090), // 接入点填写示例：tracing-analysis-dc-hz.aliyuncs.com，不需要添加"http://"
        eventLoopGroup: MultiThreadedEventLoopGroup(numberOfThreads: 1)
    )
)

let otlpGrpcConfiguration = OtlpConfiguration(
    timeout: OtlpConfiguration.DefaultTimeoutInterval,
    headers: [
        ("Authentication","xxxxxx")
    ]

)
let otlpGrpcTraceExporter = OtlpTraceExporter(channel: grpcChannel, config: otlpGrpcConfiguration)

方法二：通过HTTP协议上报Trace数据
请将<HTTP-endpoint>替换为从前提条件中获取的接入点信息，例如：http://tracing-analysis-dc-hz.aliyuncs.com/adapt_xxxx@xxxx_xxxx@xxxx/api/otlp/traces。
```
let url = URL(string: "<HTTP-endpoint>")
let otlpHttpTraceExporter = OtlpHttpTraceExporter(endpoint: url!)
```

方法三：在命令行输出Trace数据

let consoleTraceExporter = StdoutExporter(isDebug: true)

获取用于创建Span的Tracer。

请将<your-service-name>替换为要上报的应用名，<your-host-name>替换为主机名。
替换<trace-exporter>，根据步骤1上报Trace方法不同替换为不同值。
- 方式一：<trace-exporter>替换为otlpGrpcTraceExporter。
- 方式二：<trace-exporter>替换为otlpHttpTraceExporter。
- 方式三：<trace-exporter>替换为consoleTraceExporter。

// 设置应用名与主机名
let resource = Resource(attributes: [
    ResourceAttributes.serviceName.rawValue: AttributeValue.string("<your-service-name>"),
    ResourceAttributes.hostName.rawValue: AttributeValue.string("<your-host-name>")
])

// 配置TracerProvider
OpenTelemetry.registerTracerProvider(tracerProvider: TracerProviderBuilder()
                                     .add(spanProcessor: BatchSpanProcessor(spanExporter: <trace-exporter>)) // 上报至可观测链路 OpenTelemetry 版
                                     .with(resource: resource)
                                     .build())

// 获取tracer，用来创建Span
let tracer = OpenTelemetry.instance.tracerProvider.get(instrumentationName: "instrumentation-library-name", instrumentationVersion: "1.0.0")

步骤三：创建Span追踪链路数据

创建Span，为Span添加属性（Attribute）和事件（Event），并输出当前Span的TraceId。

let span = tracer.spanBuilder(spanName: "first span").startSpan()
// 设置属性
span.setAttribute(key: "http.method", value: "GET")
span.setAttribute(key: "http.url", value: "www.aliyun.com")
let attributes = [
    "key": AttributeValue.string("value"),
    "result": AttributeValue.int(100)
]

// your code...

// 设置Event
span.addEvent(name: "computation complete", attributes: attributes)

// 打印TraceId
print(span.context.traceId.hexString)

// your code...

// 结束当前span
span.end()

创建嵌套的Span。

let parentSpan = tracer.spanBuilder(spanName: "parent span").startSpan()

// your code...

let childSpan = tracer.spanBuilder(spanName: "child span").setParent(parentSpan).startSpan()

// your code...

childSpan.end()

// your code...

parentSpan.end()

启动应用。
在可观测链路 OpenTelemetry 版控制台的应用列表页面选择目标应用，查看链路数据。

步骤四：打通客户端与服务端应用链路

修改Header中的Trace透传格式。
- 不同协议使用不同的HTTP Header向下游传递Trace上下文，如OpenTelemtry默认使用W3C Trace Context格式（也支持修改为其他格式），而Zipkin使用B3或B3 Multi格式。关于透传格式的更多信息，请参见OpenTelemetry指定透传Header格式。
- 根据服务端使用的协议类型，在客户端中设置对应的透传格式（textPropagators和baggagePropagator），以实现iOS客户端应用与服务端应用链路打通：
  - 如果服务端使用OpenTelemetry默认的W3C Trace Context格式，客户端无需设置textPropagators和baggagePropagator。
  - 如果服务端使用Zipkin的B3/B3 Multi格式，客户端的textPropagators需设置为B3Propagator，baggagePropagator设置为ZipkinBaggagePropagator。
```
// 设置B3透传格式。
OpenTelemetry.registerPropagators(textPropagators: [B3Propagator()],
                                  baggagePropagator: ZipkinBaggagePropagator())
```
  - 如果服务端使用Jaeger协议，客户端的textPropagators需设置为JaegerPropagator，baggagePropagator设置为JaegerBaggagePropagator。
```
// 设置Jaeger透传格式。
OpenTelemetry.registerPropagators(textPropagators: [JaegerPropagator()],
                                  baggagePropagator: JaegerBaggagePropagator())
```
  - 也可以同时设置多种Trace透传格式。
```
// 同时使用W3C Trace Context、B3、Jaeger三种Trace透传格式。
OpenTelemetry.registerPropagators(textPropagators: [W3CTraceContextPropagator(), 
                                                    B3Propagator(), 
                                                    JaegerPropagator()],
                                  baggagePropagator: W3CBaggagePropagator())
```
导入URLSessionInstrumentation。
URLSessionInstrumentation是OpenTelemetry提供的针对URLSession的自动埋点插件，可以自动拦截所有通过URLSession发出的网络请求并创建调用链。
```
import URLSessionInstrumentation

...
let networkInstrumentation = URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration())
```

使用URLSession进行网络请求，访问服务端。

let url = URL(string: "<服务端地址>")!
let request = URLRequest(url: url)
let semaphore = DispatchSemaphore(value: 0)

let task = URLSession.shared.dataTask(with: request) { data, _, _ in
    if let data = data {
        let string = String(decoding: data, as: UTF8.self)
        print(string)
    }
    semaphore.signal()
}
task.resume()

semaphore.wait()

展开查看完整示例代码

OpenTelemetryUtil.swift

import Foundation

import GRPC
import NIO
import OpenTelemetryApi
import OpenTelemetrySdk
import OpenTelemetryProtocolExporter
import StdoutExporter

class OpenTelemetryUtil {
    
    private static let tracerProvider: TracerProvider = {
        // 通过gRPC协议上报
        let grpcChannel = ClientConnection(
            configuration: ClientConnection.Configuration.default(
                target: .hostAndPort("tracing-analysis-dc-hz.aliyuncs.com", 8090),
                eventLoopGroup: MultiThreadedEventLoopGroup(numberOfThreads: 1)
            )
        )
        

        let otlpGrpcConfiguration = OtlpConfiguration(
            timeout: OtlpConfiguration.DefaultTimeoutInterval,
            headers: [
                ("Authentication","${鉴权Token}")
            ]

        )
        let otlpGrpcTraceExporter = OtlpTraceExporter(channel: grpcChannel, config: otlpGrpcConfiguration)
        let consoleTraceExporter = StdoutExporter(isDebug: true)
        
        // 设置应用名与主机名
        let resource = Resource(attributes: [
            ResourceAttributes.serviceName.rawValue: AttributeValue.string("otel-swift-demo-grpc"),
            ResourceAttributes.hostName.rawValue: AttributeValue.string("adam.mac")
        ])

        let tracerProvider = TracerProviderBuilder()
            .add(spanProcessor: BatchSpanProcessor(spanExporter: otlpGrpcTraceExporter))
//            .add(spanProcessor: BatchSpanProcessor(spanExporter: consoleTraceExporter)) // 控制台打印 Trace，调试时使用
            .with(resource: resource)
            .build()
        
        
        // 配置TracerProvider
        OpenTelemetry.registerTracerProvider(tracerProvider: tracerProvider)
        // 修改透传格式
        OpenTelemetry.registerPropagators(textPropagators: [W3CTraceContextPropagator(),
                                                            B3Propagator(),
                                                            JaegerPropagator()],
                                          baggagePropagator: W3CBaggagePropagator())
        
        return tracerProvider
        
    }()
    
    
    // 获取tracer，用来创建Span
    static func getTracer(name: String, version: String) -> Tracer {
        return tracerProvider.get(instrumentationName: name, instrumentationVersion: version)
    }

}

main.swift

import Foundation


import OpenTelemetryApi
import OpenTelemetrySdk
// 对网络请求进行自动埋点
import URLSessionInstrumentation

let tracer = OpenTelemetryUtil.getTracer(name: "ios-demo", version: "1.0.0")

// 创建嵌套的Span
let parentSpan = tracer.spanBuilder(spanName: "parent span").startSpan()

let childSpan = tracer.spanBuilder(spanName: "child span").setParent(parentSpan).startSpan()

// 设置属性
childSpan.setAttribute(key: "http.method", value: "GET")
childSpan.setAttribute(key: "http.url", value: "www.aliyun.com")
let attributes = [
    "stringKey": AttributeValue.string("value"),
    "intKey": AttributeValue.int(100)
]
// 设置Event
childSpan.addEvent(name: "event", attributes: attributes)
// 打印TraceId
print(childSpan.context.traceId.hexString)

// 发送网络请求访问服务端
let networkInstrumentation = URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration())

let url = URL(string: "${服务端地址}")!
let request = URLRequest(url: url)
let semaphore = DispatchSemaphore(value: 0)

let task = URLSession.shared.dataTask(with: request) { data, _, _ in
    if let data = data {
        let string = String(decoding: data, as: UTF8.self)
        print(string)
    }
    semaphore.signal()
}
task.resume()

semaphore.wait()


// 手动结束手动创建的 Span
childSpan.end()
parentSpan.end()

sleep(60)

print("end")

启动应用，在调用链分析页面查看客户端与服务端打通的调用链。
如下图所示，HTTP GET为iOS应用，zipkin-demo-server为服务端应用。