日志服务：接入iOS Trace数据

步骤一：集成SDK

（推荐）通过CocoaPods集成

1. 在Xcode工程的Podfile中添加如下内容。

   // 添加aliyun-specs source。
   source 'https://github.com/aliyun/aliyun-specs.git'
   // 添加CocoaPods source。
   source 'https://github.com/CocoaPods/Specs.git'
   
   pod 'AliyunLogProducer', '~> 3.1.14', :subspecs => ['Trace']

2. 保存并执行pod install --repo-update命令。
3. 使用后缀为.xcworkspace的文件打开工程。

通过SDK文件方式集成

1. 下载SDK文件。
2. 解压SDK文件后，将如下framework添加到项目中。
   AliyunLogProducer.framework、AliyunLogCore.framework、AliyunLogOT.framework和AliyunLogTrace.framework。

步骤二：配置接入服务

1. 在工程的AppDelegate.m文件导入头文件。

   #import <AliyunLogProducer/AliyunLogProducer.h>

2. 在AppDelegate.m文件的application:(UIApplication *)application didFinishLaunchingWithOptions方法中初始化SDK。

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
       // Override point for customization after application launch.
   
   
       SLSCredentials *credentials = [SLSCredentials credentials];
       credentials.accessKeyId = @"your access key id";
       credentials.accessKeySecret = @"your access key secret";
       // 上述AccessKey是通过STS方式获取时，需配置securityToken。
       credentials.securityToken = @"your access security token";
   
       SLSTraceCredentials *tracerCredentials = [credentials createTraceCredentials];
       tracerCredentials.endpoint = @"your trace endpoint";
       tracerCredentials.project = @"your trace project";
       tracerCredentials.logstore = @"your trace logstore";
   
   
       [[SLSCocoa sharedInstance] initialize:credentials configuration:^(SLSConfiguration * _Nonnull configuration) {
           // 开启Trace功能。
           configuration.enableTrace = YES;
           // 开启Trace NSURLSession instrumentation功能。
           // 如果需要打通移动端与服务端Trace链路，则必须设置configuration.enableInstrumentNSURLSession为YES。
           configuration.enableInstrumentNSURLSession = YES;
       }];
   
       return YES;
   }

   • SLSCredentials
     SLSCredentials类定义了鉴权字段。

     字段	示例值	说明
     accessKeyId	LTAI****eYDw	日志服务Project的AccessKey ID。如何获取，请参见访问密钥。
     accessKeySecret	lrRq****GOVM	日志服务Project的AccessKey Secret。如何获取，请参见访问密钥。
     securityToken	124f****a369	日志服务Project的访问密钥Token。使用STS方式接入时，需要配置。如何获取，请参见AssumeRole。

   • SLSTraceCredentials

     SLSTraceCredentials定义了关键的配置字段。

     字段	示例值	说明
     endpoint	https://cn-hangzhou.log.aliyuncs.com	您在创建Trace实例时所绑定的Project的访问域名，此处必须添加https://前缀。如何获取，请参见公网服务入口。 重要 只支持公网服务入口。
     project	sls-ayasls-demo	您在创建Trace实例时所绑定的Project。更多信息，请参见创建Trace实例。
     logstore	ayasls-traces	创建Trace实例后，日志服务会自动生成一个名为{instance}-traces的Logstore。其中{instance}为Trace实例ID。更多信息，请参见创建Trace实例。 此处需配置为该Logstore。

   • SLSConfiguration
     SLSConfiguration类提供了SDK初始化额外参数配置的接口。

     类型	字段/方法	说明
     配置方法	enableTrace	是否启用Trace功能。
     	enableInstrumentNSURLSession	是否启用NSURLSession instrumentation功能。如果要打通移动端与服务端Trace链路，必须开启。
     	spanProvider	自定义Span的Resource和Attribute信息。
     环境配置	env	App的环境信息，默认为default。 建议开发环境配置为dev；线上环境配置为prod。

   • SLSCocoa
     SLSCocoa类提供了SDK初始化相关的全部参数配置、用户信息配置等接口。

     类型	字段/方法	说明
     单例	sharedInstance	获取SLSCocoa单例。
     初始化	initialize	初始化SLSCocoa。
     	setCredentials	更新Credentials凭证信息，支持热更新。
     配置方法	setUserInfo	更新用户信息。
     全局扩展参数配置	setExtra	新增全局扩展参数。
     	removeExtra	移除全局扩展参数，全局生效。
     	clearExtras	清空全局扩展参数，全局生效。

3. 可选：通过STS方式配置credentials.accessKeyId、credentials.accessKeySecret和credentials.securityToken信息。

   // 可以在请求AccessKey信息后，发起调用。
   - (void) updateSLS {
       SLSCredentials *credentials = [SLSCredentials credentials];
       // （可选）更新AccessKey。
       credentials.accessKeyId = @"your access key id";
       credentials.accessKeySecret = @"your access key secret";
       credentials.securityToken = @"your access security token";
   
       // （可选）更新Project等信息。
       SLSTraceCredentials *tracerCredentials = [credentials createTraceCredentials];
       tracerCredentials.endpoint = @"your trace endpoint";
       tracerCredentials.project = @"your trace project";
       tracerCredentials.logstore = @"your trace logstore";
   
       [[SLSCocoa sharedInstance] setCredentials:credentials];
   }

步骤三：构造Trace数据

构造单个Span

SDK提供多种方式构造单个Span。

• 通过SpanBuilder构造

  SLSSpan *span = [[[[[[[[SLSTracer spanBuilder:@"span with spanbuilder"]
                     setParent:span] // 设置父Span。
                     setStart:start] // 设置起始时间。
                     setActive:YES/NO] // 是否保持Span活跃。
                     setService: @"service name"] // 设置服务名称，默认为iOS，一般无需设置。
                     addAttribute:[SLSAttribute of:@"attr_key" value:@"attr_value"], nil] // 增加属性信息。
                     addResource:[SLSResource of:@"res_key" value:@"res_value"]] // 增加资源信息。
                  build]; // 构造并开启一个Span。
  [span end]; // 结束当前Span。

• 通过startSpan构造

  SLSSpan *span = [SLSTracer startSpan:@"span name"]; // 调用startSpan方法后，Span处于开始状态。
  [span setName: @"span name"]; // 设置Span名称。
  [span setParentSpanID:parent.spanID]; // 设置父Span ID。
  [span setStart:start]; // 设置起始时间，一般无需设置。
  [span setService:@"service name"]; // 设置服务名称，默认为iOS，一般无需设置。
  [span setStatusCode:ERROR/UNSET/OK]; // 设置Span状态，默认是UNSET。
  [span setStatusMessage:@"status message"]; // 设置Span状态的描述信息。
  [span setKind:SLSINTERNAL/SLSSERVER/SLSCLIENT/SLSPRODUCER/SLSCONSUMER];
  [span addAttribute:[SLSAttribute of:@"attr_key" value:@"attr_value"], nil]; // 增加属性信息。
  [span addResource:[SLSResource of:@"res_key" value:@"res_value"]]; // 增加资源信息。
  [span end]; // 结束当前span。

• 通过withinSpan构造

  通过withinSpan方式构造Span，无需关注Span的start和end设置。一般情况下，需要把业务代码放入到Runnable中，并且构造的 span无法设置额外信息。

  [SLSTracer withinSpan:@"span with func block" block:^{
      // 代码块。
  }];

构造一条包含多个Span的Trace数据

一条Trace数据会关联1个或多个Span。SDK提供多种方式，关联不同Span。

• 通过SpanBuilder构造

   SLSSpan *span = [[[[[SLSTracer spanBuilder:@"span with spanbuilder"]
                     setActive:YES] // 必须设置为YES。
                     addAttribute:[SLSAttribute of:@"attr_key" value:@"attr_value"], nil]
                     addResource:[SLSResource of:@"res_key" value:@"res_value"]]
                  build];
  
  [[Tracer startSpan: @"child span 1"] end];
  [[Tracer startSpan: @"child span 2"] end];
  
  [span end]; // 结束Trace。

• 通过startSpan构造

  SLSSpan *span = [SLSTracer startSpan:@"span with children" active:YES]; // 第二个参数必须设置为YES。
  [[SLSTracer startSpan:@"child span 1"] end];
  [[SLSTracer startSpan:@"child span 2"] end];
  [span end]; // 结束Trace。

• 通过withinSpan构造

  [SLSTracer withinSpan:@"span with func block" block:^{
      [[SLSTracer startSpan:@"span within block 1"] end];
      // 子Trace。
      [SLSTracer withinSpan:@"nested span with func block" block:^{
          [[SLSTracer startSpan:@"nested span 1"] end];
          [[SLSTracer startSpan:@"nested span 2"] end];
      }];
      [[SLSTracer startSpan:@"span within block 2"] end];
  }];

自定义Attribute和Resource

SDK支持通过SpanProvider添加自定义信息。通过SpanProvider创建的Resource和Attribute将添加到所有Span中。您可以根据这个特性为所有Span添加业务关联的Resource和Attribute信息。

// 实现SLSSpanProviderProtocol。
@interface SpanProvider : NSObject<SLSSpanProviderProtocol>
+ (instancetype) provider;
@end

@implementation SpanProvider
+ (instancetype) provider {
    return [[SpanProvider alloc] init];
}

- (nonnull NSArray<SLSAttribute *> *)provideAttribute {
    NSMutableArray<SLSAttribute *> *array = [NSMutableArray array];
    [array addObject:[SLSAttribute of:@"attr_key" value:@"attr_value"]];
    return array;
}

- (nonnull SLSResource *)provideResource {
    return [SLSResource of:@"res_key" value:@"res_value"];
}
@end


// 此处省略Credentials的初始化过程。
// ...

[[SLSCocoa sharedInstance] initialize:credentials configuration:^(SLSConfiguration * _Nonnull configuration) {
    // 此处省略configuration的其他配置。
    // ...
    configuration.spanProvider = [SpanProvider provider];
}];
// 此处省略其他配置过程。
// ...

参数说明

• SLSTracer

  字段/方法	说明
  spanBuilder:	构造一个SLSSpanBuilder对象。
  startSpan:	构造一个SLSSpan对象。
  startSpan: active:	构造一个SLSSpan对象，根据active的值决定是否设置为活跃Span。
  withinSpan: block:	构造一个SLSSpan对象，并设置为活跃Span，自动执行block代码块。
  withinSpan: active: block:	构造一个SLSSpan对象，根据active的值决定是否设置为活跃Span，自动执行block代码块。
  withinSpan: active: parent: block:	构造一个SLSSpan对象，根据active的值决定是否设置为活跃Span，并设置该Span对象的父Span为parent，自动执行block代码块。

• SLSSpanBuilder

  字段/方法	说明
  builder	构造一个SLSSpanBuilder对象。
  initWithName: provider: processor:	初始化SLSSpanBuilder对象，并指定Span名称、SpanProcessor和SpanProvider。
  setParent:	设置父Span。
  setActive:	设置是否为活跃Span。
  setKind:	设置Span类型，支持设置为SLSINTERNAL、SLSSERVER、SLSCLIENT、SLSPRODUCER或SLSCONSUMER。默认为SLSCLIENT。
  setStart:	设置Span的开始时间。
  addAttribute: , ...	增加Attribute属性信息。
  addAttributes:	增加一组Attribute属性信息。
  addResource:	增加Resource资源信息。
  setService:	设置服务名称，默认为iOS。

• SLSSpan

  字段/方法	说明
  setName:	设置Span名称。
  setKind:	设置Span类型，支持设置为INTERNAL、SERVER、CLIENT、PRODUCER或CONSUMER。默认为CLIENT。
  setTraceId:	设置Trace ID，不建议手动设置。
  setSpanId:	设置Span ID，不建议手动设置。
  setParentSpanId:	设置父Span ID。
  setStart:	设置Span开始时间，不建议手动设置。
  setEnd:	设置Span结束时间。
  setDuration:	设置Span持续时间，不建议手动设置。
  setStatus:	设置Span状态，支持设置为ERROR、UNSET或OK。默认为UNSET。
  setStatusMessage:	设置Span状态的描述信息。
  setHost:	设置Host。
  setService:	设置服务名称，默认为iOS。
  addAttribute: , ...	增加Attribute属性信息。
  addAttributes:	增加Attribute属性信息。
  addResource(resource)	增加Resource资源信息。
  end	结束当前Span。
  isEnd	判断当前Span是否结束。
  toDict	转换Span数据结构为Map对象。

• SLSResource

  字段/方法	说明
  resource	返回SLSResource对象。
  of: value:	基于传入的key和value，返回一个Resource对象。
  of: , ...	根据传入的SLSKeyValue键值对，返回一个Resource对象。
  ofAttributes:	根据传入的Attribute Array，返回一个Resource对象。
  add: value:	添加key和value信息到当前Resource对象。
  add:	添加一组SLSAttribute信息到当前Resource对象。
  merge:	将传入的Resource对象信息合并到当前Resource中实现。

• Attribute

  字段/方法	说明
  of: value:	返回一个Attribute对象。
  of: , ...	返回一个Attribute Array对象。

其他说明