通过OpenTelemetry接入iOS Trace数据

Swift项目

1. 导入opentelemetry-swift。

   1. 在Xcode中，选择File>Add Package。

   2. 在添加Package文本框中，输入如下链接。

      https://github.com/open-telemetry/opentelemetry-swift

   3. 选择Dependency Rule为Exact Version，设置版本号为1.4.0。

      更多信息，请参见OpenTelemetry iOS SDK Release。

2. 选择Swift Products。

   建议选择以下Products。

   • OpenTelemetryApi

   • OpenTelemetryProtocolExporter

   • OpenTelemetrySdk

   • URLSessionInstrumentation

   • StdoutExporter

   • ResourceExtension

   关于Swift Products的更多信息，请参见附录：OpenTelemetry Products说明。

Objc项目

opentelemetry-swift对Objc语言的兼容较差，日志服务基于opentelemetry-swift实现了一个Objc扩展。Objc项目除了需要完成Swift项目的配置外，还需要增加opentelemetry-objc-extension。

1. 完成Swift项目的配置。

2. 导入opentelemetry-objc-extension。

   1. 在Xcode中，选择File>Add Package。

   2. 在添加Package文本框中，输入如下链接。

      https://github.com/aliyun-sls/opentelemetry-objc-extension

   3. 选择Dependency Rule为Exact Version，输入版本号为1.0.0。

      更多信息，请参见OpenTelemetry iOS Objc Extension SDK Release。

3. 选择Objc Extension Products。

   建议选择以下Products。

   • OpenTelemetryApiObjc

   • OpenTelemetryProtocolExporterObjc

   • OpenTelemetrySdkObjc

   • ResourceExtensionObjc

   • URLSessionInstrumentationObjc

   • StdoutExporterObjc

关于Objc Extension Products的更多信息，请参见附录：OpenTelemetry Products说明。

Swift项目

// 导入如下模块。
import GRPC
import NIO
import OpenTelemetryApi
import OpenTelemetrySdk
import OpenTelemetryProtocolExporter
import StdoutExporter
import URLSessionInstrumentation

// 初始化Exporter。Exporter用于导出Trace数据到日志服务Logstore。
let client = ClientConnection.usingPlatformAppropriateTLS(for: MultiThreadedEventLoopGroup(numberOfThreads: 1))
.connect(host: "${endpoint}", port: ${port})	
let otlpTraceExporter = OtlpTraceExporter(
 channel: client,
 config: OtlpConfiguration(
 timeout: OtlpConfiguration.DefaultTimeoutInterval,
 headers:
 [
 ("x-sls-otel-project", "${project}"),
 ("x-sls-otel-instance-id", "${instanceId}"),
 ("x-sls-otel-ak-id", "${access-key-id}"),
 ("x-sls-otel-ak-secret", "${access-key-secret}")
 ]
 )
)

// 初始化tracer provider。tracer provider用于暴露主要的API，对Span进行预处理、自定义Clock，
// 自定义TraceId、SpanId生成规则，自定义采样器等。您可以根据实际的需要进行配置。
let spanExporters = MultiSpanExporter(spanExporters: [StdoutExporter(isDebug: true), otlpTraceExporter])
let spanProcessor = SimpleSpanProcessor(spanExporter: spanExporters)
OpenTelemetry.registerTracerProvider(
 tracerProvider: TracerProviderBuilder()
 .add(spanProcessor: spanProcessor)
 .with(resource: 
 Resource(attributes:
 [
 ResourceAttributes.serviceName.rawValue: AttributeValue.string("${service}"),
 ResourceAttributes.serviceNamespace.rawValue: AttributeValue.string("${service.namespace}"),
 ResourceAttributes.serviceVersion.rawValue: AttributeValue.string("${version}"),
 ResourceAttributes.hostName.rawValue: AttributeValue.string("${host}"),
 ResourceAttributes.deploymentEnvironment.rawValue: AttributeValue.string("${environment}"),
 ]
 )
 )
 .build()
)

// 配置其他的Instrumentation采集器。请根据实际业务需要进行配置。如下配置是开启采集NSUrlSession网络库的请求信息。
URLSessionInstrumentation(configuration: URLSessionInstrumentationConfiguration(
 shouldInstrument: { request in
 return true
 })
)
let tracer = OpenTelemetry.instance.tracerProvider.get(instrumentationName: "OTel Application", instrumentationVersion: "1.0.0")

Objc 项目

// 导入以下模块
@import OpenTelemetryApiObjc;
@import OpenTelemetrySdkObjc;
@import OpenTelemetryProtocolExporterObjc;
@import URLSessionInstrumentationObjc;
@import StdoutExporterObjc;

// 初始化Exporter。Exporter用于导出Trace数据到日志服务Logstore。
NSDictionary *headers = @{
 @"x-sls-otel-project": @"${project}",
 @"x-sls-otel-instance-id": @"${instanceId}",
 @"x-sls-otel-ak-id": @"${access-key-id}",
 @"x-sls-otel-ak-secret": @"${access-key-secret}"
};
OtlpConfigurationObjc *configuration = [OtlpConfigurationObjc configuration:OtlpConfigurationObjc.DefaultTimeoutInterval headers:headers];
OtlpTraceExporterObjc *exporter = [OtlpTraceExporterObjc exporter:@"https://${endpoint}"
 port:@"${port}"
 configuration:configuration
];

// 初始化tracer provider。tracer provider用于暴露主要的API，对Span进行预处理，自定义Clock。
// 自定义TraceId、SpanId生成规则，自定义采样器等。您可以根据实际的需要进行配置。
NSArray *exporters = @[
 [StdoutExporterObjc stdoutExporter:true], // 开发调试时，建议开启，实现在console中打印出Span的具体的内容。
 exporter
];
SpanProcessorObjc *spanProcessor = [BatchSpanProcessorObjc processor: [MultiSpanExporterObjc multiSpanExporter:exporters]];

TracerProviderBuilderObjc *providerBuilder = [TracerProviderBuilderObjc builder];
NSDictionary *resources = @{
 ResourceAttributesObjc.serviceName: [AttributeValueObjc string:@"${service}"], // 当前要追踪Trace的服务名称，建议取模块的名称，例如首页、会员中心。
 ResourceAttributesObjc.serviceNamespace: [AttributeValueObjc string:@"${service.namespace}"], // 建议固定为iOS/iPadOS/macOS/tvOS/watchOS。
 ResourceAttributesObjc.serviceVersion: [AttributeValueObjc string:@"${version}"], // 建议和App版本号保持一致。
 ResourceAttributesObjc.hostName: [AttributeValueObjc string:@"${host}"], // 建议固定为iOS。
 ResourceAttributesObjc.deploymentEnvironment: [AttributeValueObjc string:@"${environment}"] // 开发环境，一般开发阶段建议设置为dev，线上环境设置为prod。
};
providerBuilder = [providerBuilder withResource: [ResourceObjc resource:resources]];
providerBuilder = [providerBuilder addSpanProcessor: spanProcessor];

// 初始化OpenTelemetrySdk。
[OpenTelemetryObjc registerTracerProvider:[providerBuilder build]];

// 配置其他的Instrumentation采集器。请根据实际业务需要进行配置。如下配置是开启采集NSUrlSession网络库的请求信息。
[URLSessionInstrumentationObjc urlSessionInstrumentation:
 [URLSessionInstrumentationConfigurationObjc urlSessionInstrumentationConfiguration:[TestURLSessionInstrumentation instrumentation]]
];

Swift示例

let tracer: Tracer = OpenTelemetry.instance.tracerProvider.get(instrumentationName: "OTel Application", instrumentationVersion: "1.0.0")

ObjC示例

TracerObjc *tracer = [OpenTelemetryObjc.instance.tracerProvider getWithInstrumentationName:@"app" instrumentationVersion:@"1.0"];

Swift示例

let spanBuilder = tracer.spanBuilder(spanName: "operation name")
let span = spanBuilder .setSpanKind(spanKind: .client).startSpan()
// do stuff
// ...
span.end()

ObjC示例

SpanBuilderObjc *spanBuilder = [_tracer spanBuilder:@"operation name"];
SpanObjc *span = [[spanBuilder setSpanKind:SpanKindObjc.CLIENT] startSpan];
// do stuff
// ...
[span end];

Swift示例

func methodA() {
 let span = tracer.spanBuilder(spanName: "operation methodA").setSpanKind(spanKind: .client).startSpan()
	method(span)
 span.end()
}

func methodB(_ parent: Span) {
 let spanBuilder = tracer.spanBuilder(spanName: "operation methodB")
 spanBuilder.setParent(parent)
 let child = spanBuilder .setSpanKind(spanKind: .client).startSpan()
 // do stuff
 // ...
 child.end()
}

ObjC示例

- (void) methodA {
 SpanObjc *span = [[[_tracer spanBuilder:@"operation methodA"] setSpanKind:SpanKindObjc.CLIENT] startSpan];
 [self methodB: span];
 [span end];
}

- (void) methodB: (SpanObjc *)parent {
 SpanBuilderObjc *spanBuilder = [_tracer spanBuilder:@"operation name"];
 [spanBuilder setParent: parent];
 SpanObjc *span = [[spanBuilder setSpanKind:SpanKindObjc.CLIENT] startSpan];
 // do stuff
 // ...
 [span end];
}

Swift示例

func methodA() {
 let span = tracer.spanBuilder(spanName: "operation methodA").setSpanKind(spanKind: .client).startSpan()
 OpenTelemetry.instance.contextProvider.setActiveSpan(span)
 
 methodB(span)
 
 span.end()
}

func methodB(_ parent: Span) {
 let child = tracer.spanBuilder(spanName: "operation methodB").setSpanKind(spanKind: .client).startSpan()
 // do stuff
 // ...
 child.end()
}

ObjC示例

- (void) methodA {
 SpanObjc *span = [[[_tracer spanBuilder:@"operation methodA"] setSpanKind:SpanKindObjc.CLIENT] startSpan];
 [OpenTelemetryObjc.instance.contextProvider setActiveSpan:span];
 [self methodB];
 // do stuff
 // ...
 [span end];
}

- (void) methodB {
 SpanBuilderObjc *spanBuilder = [_tracer spanBuilder:@"operation name"];
 SpanObjc *span = [[spanBuilder setSpanKind:SpanKindObjc.CLIENT] startSpan];
 // do stuff
 // ...
 [span end];
}

Swift示例

let spanBuilder = tracer.spanBuilder(spanName: "GET /resource/catalog")
let span = spanBuilder .setSpanKind(spanKind: .client).startSpan()
span.setAttribute(key: "http.method", value: "GET")
span.setAttribute(key: "http.url", value: "http url")

ObjC示例

SpanBuilderObjc *spanBuilder = [_tracer spanBuilder:@"GET /resource/catalog"];
SpanObjc *span = [[spanBuilder setSpanKind:SpanKindObjc.CLIENT] startSpan];
[span setAttribute:@"http.method" stringValue:@"GET"];
[span setAttribute:@"http.url" stringValue:request.URL.baseURL];

Swift示例

span.addEvent(name: "start")
// do stuff
// ...
span.addEvent(name: "start")

// 也可以携带属性。
span.addEvent(name: "event with attributes",
 attributes: [ "key1": AttributeValue.string("value1"),
 "key2": AttributeValue.double(2.2)
 ]
)

ObjC示例

[chilsSpan addEvent:@"start"];
// do stuff
// ...
[chilsSpan addEvent:@"end"];

// 也可以携带属性。
[chilsSpan addEvent:@"event with attributes" attributes:@{
 @"key1": [AttributeValueObjc string:@"value1"],
 @"key2": [AttributeValueObjc double:1.1],
}];

Swift示例

spanBuilder.addLink(spanContext: parent.context)
let span = spanBuilder .setSpanKind(spanKind: .client).startSpan()

ObjC示例

SpanBuilderObjc *spanBuilder = [_tracer spanBuilder:@"Another"];
[spanBuilder addLink:parent.context];

SpanObjc *span = [[spanBuilder setSpanKind:SpanKindObjc.CLIENT] startSpan];

Swift示例

let span = tracer.spanBuilder(spanName: "operation name").startSpan()
do {
 try expression
 // do stuff
 // ...
} catch {
 span.status = .error(description: "\(error)")
}

ObjC示例

SpanObjc *span = [[_tracer spanBuilder:@"operation name"] startSpan];
@try {
 // do stuff
 // ...
} @catch (NSException *exception) {
 [span setStatus:[StatusObjc error: exception.description]];
} @finally {
 [span end];
}

Swift示例

// 在SDK初始化时，需要完成URLSessionInstrumentation的初始化。
// 按需传入对应的参数。
URLSessionInstrumentation(
 configuration: URLSessionInstrumentationConfiguration(
 shouldInstrument: { request in
 // 是否采集该request的数据。
 return true
 }
 )
)

ObjC示例

// 在SDK初始化时，需要完成URLSessionInstrumentationObjc的初始化。
// 初始化URLSessionInstrumentationObjc时，需要传入一个实现了URLSessionInstrumentationConfigurationImpl协议的类（可参见下面的TestURLSessionInstrumentation实现）
[URLSessionInstrumentationObjc urlSessionInstrumentation:
 [URLSessionInstrumentationConfigurationObjc urlSessionInstrumentationConfiguration:[TestURLSessionInstrumentation instrumentation]]
];

// TestURLSessionInstrumentation的实现示例。
#pragma mark - URLSessionInstrumentation
@interface TestURLSessionInstrumentation: NSObject<URLSessionInstrumentationConfigurationImpl>
+ (instancetype) instrumentation;
@end

@implementation TestURLSessionInstrumentation
+ (instancetype) instrumentation {
 return [[TestURLSessionInstrumentation alloc] init];
}
- (void)createdRequest:(NSURLRequest * _Nonnull)request span:(SpanObjc * _Nonnull)span {
 // request被创建时回调。
 [span setAttribute:@"createdRequest" stringValue:@"request created"];
}
- (void)injectCustomHeaders:(NSURLRequest * _Nonnull)request span:(SpanObjc * _Nullable)span {
 // 注入自定义请求头。
 [(NSMutableURLRequest *)request addValue:@"custom header" forHTTPHeaderField:@"injectCustomHeaders"];
}
- (NSString * _Nullable)nameSpan:(NSURLRequest * _Nonnull)request {
 // 重命名Span。
 if ([request.URL.host containsString:@"dns.alidns.com"]) {
 return @"请求解析DNS";
 }
 return nil;
}
- (void)receivedError:(NSError * _Nonnull)error dataOrFile:(NSObject * _Nullable)dataOrFile span:(SpanObjc * _Nonnull)span {
 // 接口失败时回调。
}
- (void)receivedResponse:(NSURLResponse * _Nonnull)response dataOrFile:(NSObject * _Nullable)dataOrFile span:(SpanObjc * _Nonnull)span {
 // 接口成功时回调。
 NSLog(@"receivedResponse: %@", dataOrFile);
}
- (BOOL)shouldInjectTracingHeaders:(NSURLRequest * _Nonnull)request {
 // 注入tracing headers。
 return YES;
}
- (BOOL)shouldInstrument:(NSURLRequest * _Nonnull)request {
 // 是否采集该request的数据。
 return YES;
}
- (BOOL)shouldRecordPayload:(NSURLSession * _Nonnull)session {
 // 是否采集请求体信息。
 return YES;
}
- (void)spanCustomization:(NSURLRequest * _Nonnull)request spanBuilder:(SpanBuilderObjc * _Nonnull)spanBuilder {
 // 自定义Span信息。
 [spanBuilder setAttribute:@"spanCustomization" stringValue:@"customize span"];
}
@end