iOS SDK快速入门

快速使用

您可以按照以下方式对SDK进行初始化，并同调用addLog方法上报日志。

@interface ProducerExampleController ()
// 建议您全局保存LogProducerConfig实例和LogProducerClient实例。
@property(nonatomic, strong) LogProducerConfig *config;
@property(nonatomic, strong) LogProducerClient *client;
@end

@implementation ProducerExampleController


// callback为可选配置，如果您不需要关注日志的发送成功或失败状态，可以不注册callback。
// 如果需要动态化配置AccessKey，建议设置callback，并在callback被调用时更新AccessKey。
static void _on_log_send_done(const char * config_name, log_producer_result result, size_t log_bytes, size_t compressed_bytes, const char * req_id, const char * message, const unsigned char * raw_buffer, void * userparams) {
    if (result == LOG_PRODUCER_OK) {
        NSString *success = [NSString stringWithFormat:@"send success, config : %s, result : %d, log bytes : %d, compressed bytes : %d, request id : %s", config_name, (result), (int)log_bytes, (int)compressed_bytes, req_id];
        SLSLogV("%@", success);
    } else {
        NSString *fail = [NSString stringWithFormat:@"send fail   , config : %s, result : %d, log bytes : %d, compressed bytes : %d, request id : %s, error message : %s", config_name, (result), (int)log_bytes, (int)compressed_bytes, req_id, message];
        SLSLogV("%@", fail);
    }
}

- (void) initLogProducer {
    // 日志服务的服务接入点。此处必须是以https://或http://开头。
    NSString *endpoint = @"your endpoint";
    NSString *project = @"your project";
    NSString *logstore = @"your logstore";

    _config = [[LogProducerConfig alloc] initWithEndpoint:endpoint
                                                  project:project
                                                 logstore:logstore
    ];

    // 设置日志主题。
    [_config SetTopic:@"example_topic"];
    // 设置tag信息，此tag信息将被附加在每条日志上。
    [_config AddTag:@"example" value:@"example_tag"];
    //是否丢弃过期日志。0表示不丢弃，把日志时间修改为当前时间; 1表示丢弃。默认值为1。
    [_config SetDropDelayLog:1];
    // 是否丢弃鉴权失败的日志，0表示不丢弃，1表示丢弃。默认值为0。
    [_config SetDropUnauthorizedLog:0];    

    // 需要关注日志的发送成功或失败状态时, 第二个参数需要传入一个callback。
    _client = [[LogProducerClient alloc] initWithLogProducerConfig:_config callback:_on_log_send_done];
}

// 请求AccessKey信息。
- (void) requestAccessKey {
    // 推荐您先使用移动端日志直传服务配置AccessKey信息。
    // ...

    //  获取到AccessKey信息后，完成更新。
    [self updateAccessKey:accessKeyId accessKeySecret:accessKeySecret securityToken:securityToken];
}

// 更新AccessKey信息。
- (void) updateAccessKey:(NSString *)accessKeyId accessKeySecret:(NSString *)accessKeySecret securityToken:(NSString *)securityToken {
    
    // 通过STS服务获取的AccessKey会包含securitToken，需要使用以下方式更新。
    if (securityToken.length > 0) {
        if (accessKeyId.length > 0 && accessKeySecret.length > 0) {
            [_config ResetSecurityToken:accessKeyId
                        accessKeySecret:accessKeySecret
                          securityToken:securityToken
            ];
        }
    } else {
        // 不是通过STS服务获取的AccessKey，使用以下方式更新。
        if (accessKeyId.length > 0 && accessKeySecret.length > 0) {
            [_config setAccessKeyId: accessKeyId];
            [_config setAccessKeySecret: accessKeySecret];
        }
    }
}
// 上报日志。
- (void) addLog {
    Log *log = [Log log];
    // 您可以根据实际业务需要调整需上报的字段。
    [log putContent:@"content_key_1" intValue:123456];
    [log putContent:@"content_key_2" floatValue:23.34f];
    [log putContent:@"content_key_3" value:@"中文"];
    
    [_client AddLog:log];
}
@end

高级用法

动态配置参数

iOS SDK支持动态化配置Endpoint、ProjectName、Logstore、AccessKey等参数。

• 动态化配置Endpoint、ProjectName、Logstore。

  // 支持独立配置或一起配置Endpoint、ProjectName、Logstore。
  // 更新Endpoint。
  [_config setEndpoint:@"your new-endpoint"];
  // 更新ProjectName。
  [_config setProject:@"your new-project"];
  // 更新Logstore。
  [_config setLogstore:@"your new-logstore"];

• 动态配置AccessKey。

  动态配置AccessKey时，一般建议与callback结合使用。

  // 如果您在初始化LogProducerClient时已经完成了callback的初始化，以下代码可忽略。
  static void _on_log_send_done(const char * config_name, log_producer_result result, size_t log_bytes, size_t compressed_bytes, const char * req_id, const char * message, const unsigned char * raw_buffer, void * userparams) {
      if (LOG_PRODUCER_SEND_UNAUTHORIZED == result || LOG_PRODUCER_PARAMETERS_INVALID) {
          [selfClzz requestAccessKey]; // selfClzz为对当前类的持有。
      }
  }
  
  // 需要关注日志的发送成功或失败状态时, 第二个参数需要传入一个callback。
  _client = [[LogProducerClient alloc] initWithLogProducerConfig:_config callback:_on_log_send_done];
  
  // 请求AccessKey信息。
  - (void) requestAccessKey {
      // 推荐您先使用移动端日志直传服务配置AccessKey信息。
      // ...
  
      //  获取到AccessKey信息后，完成更新。
      [self updateAccessKey:accessKeyId accessKeySecret:accessKeySecret securityToken:securityToken];
  }
  
  // 更新AccessKey信息。
  - (void) updateAccessKey:(NSString *)accessKeyId accessKeySecret:(NSString *)accessKeySecret securityToken:(NSString *)securityToken {
      
      // 通过STS服务获取的AccessKey会包含securitToken，需要使用以下方式更新。
      if (securityToken.length > 0) {
          if (accessKeyId.length > 0 && accessKeySecret.length > 0) {
              [_config ResetSecurityToken:accessKeyId
                          accessKeySecret:accessKeySecret
                            securityToken:securityToken
              ];
          }
      } else {
          // 不是通过STS服务获取的AccessKey，使用以下方式更新。
          if (accessKeyId.length > 0 && accessKeySecret.length > 0) {
              [_config setAccessKeyId: accessKeyId];
              [_config setAccessKeySecret: accessKeySecret];
          }
      }
  }

• 动态化配置 source、topic、tag。

  重要

  source、topic、tag无法针对某类日志进行设置。一旦设置后，所有未成功发送到日志服务的日志，都可能会更新。如果您需要通过source、topic、tag来跟踪具体类别的日志，可能会导致与您的业务预期不相符合。建议您在生成Log时新增字段来标识对应的类别信息。

  // 设置日志主题。
  [_config SetTopic:@"your new-topic"];
  // 设置日志来源。
  [_config SetSource:@"your new-source"];
  // 设置tag信息，此tag信息会附加在每条日志上。
  [_config AddTag:@"test" value:@"your new-tag"];

断点续传

iOS SDK支持断点续传。开启断点续传后，每次通过addLog方法上传成功的日志都会先保存在本地binlog文件中，只有日志发送成功后才会删除本地数据，确保日志上传实现At Least Once。

您可以在SDK初始化时加入以下代码，实现断点续传。

- (void) initLogProducer {
    //  1表示开启断点续传功能，0表示关闭。默认值为0。
    [_config SetPersistent:1];
    
    // 持久化的文件名，需要保证文件所在的文件夹已创建。
    NSArray  *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
    NSString *Path = [[paths lastObject] stringByAppendingString:@"/log.dat"];
    [_config SetPersistentFilePath:Path];
    // 持久化文件滚动个数，建议设置成10。
    [_config SetPersistentMaxFileCount:10];
    // 每个持久化文件的大小，单位为Byte，格式为N*1024*1024。建议N的取值范围为1~10。
    [_config SetPersistentMaxFileSize:N*1024*1024];
    // 本地最多缓存的日志数量，不建议超过1048576，默认为65536。
    [_config SetPersistentMaxLogCount:65536];
}

配置参数说明

所有的配置参数由LogProducerConfig类提供，详见下表：

错误码

全部的错误码说明如下表所示。

常见问题

为什么会存在重复日志？

iOS SDK发送日志的过程是异步的，受网络状态影响，日志可能会发送失败并重新发送。由于SDK只在接口返回200状态码时才认为发送成功，因此日志会存在一定的重复率。建议您通过SQL查询分析语句对数据进行去重。

如果日志重复率较高，您需要先排查下SDK初始化是否存在问题。主要原因和解决方案如下：

• 断点续传配置错误

  针对断点续传配置错误，您需要确认下SetPersistentFilePath方法传入的文件路径是否全局唯一。

• SDK重复初始化

  • 造成SDK重复初始化的常见原因是单个实例写法错误，或者没有使用单例模式封装SDK的初始化，建议您参考以下方式完成SDK初始化。

    // AliyunLogHelper.h
    @interface AliyunLogHelper : NSObject
    + (instancetype)sharedInstance;
    - (void) addLog:(Log *)log;
    @end
    
    
    // AliyunLogHelper.m
    @interface AliyunLogHelper ()
    @property(nonatomic, strong) LogProducerConfig *config;
    @property(nonatomic, strong) LogProducerClient *client;
    @end
    
    @implementation AliyunLogHelper
    
    + (instancetype)sharedInstance {
        static AliyunLogHelper *sharedInstance = nil;
        static dispatch_once_t onceToken;
        dispatch_once(&onceToken, ^{
            sharedInstance = [[self alloc] init];
        });
        return sharedInstance;
    }
    
    - (instancetype)init {
        self = [super init];
        if (self) {
            [self initLogProducer];
        }
        return self;
    }
    
    - (void) initLogProducer {
        // 以下代码替换为您的初始化代码。
        _config = [[LogProducerConfig alloc] initWithEndpoint:@""
                                                      project:@""
                                                     logstore:@""
                                                  accessKeyID:@""
                                              accessKeySecret:@""
                                                securityToken:@""
        ];
    
        _client = [[LogProducerClient alloc] initWithLogProducerConfig:_config callback:_on_log_send_done];
    }
    
    - (void) addLog:(Log *)log {
        if (nil == log) {
            return;
        }
    
        [_client AddLog:log];
    }
    
    @end

  • 另外一个造成SDK重复初始化的原因是多进程。建议您只在主进程中初始化SDK，或者在不同进程中初始化SDK时，设置SetPersistentFilePath为不同的值，确保唯一性。

• 弱网环境配置优化

  如果您的应用是在弱网环境下使用，建议您参考如下示例优化SDK配置参数。

  // 初始化SDK。
  - (void) initProducer() {
      // 调整HTTP链接和发送超时时间，有利于减少日志重复率。
      // 您可以根据实际情况调整具体的超时时间。
      [_config SetConnectTimeoutSec:20];
      [_config SetSendTimeoutSec:20];
    
      // 其他初始化参数。
      // ...
  }

日志缺失，如何处理？

日志上报的过程是异步的，如果在上报日志前App被关闭，则日志有可能无法被上报，造成日志丢失。建议您开启断点续传功能。具体操作，请参见断点续传。

日志上报延时，如何处理？

SDK发送日志的过程是异步的，受网络环境以及应用使用场景的影响，日志可能不会立即上报。如果只有个别设备出现日志上报延时，这种情况是正常的，否则请您根据如下错误码进行排查。