快速开始

本文介绍如何快速使用日志服务 iOS SDK 实现基础的日志采集流程，包括创建日志项目、创建日志主题、写入日志等操作。

前提条件

在使用 TLS iOS SDK 前，请确保您已完成以下事项：

• 已安装日志服务 iOS SDK。详细步骤请参考安装 iOS SDK。
• 已创建并获取火山引擎 API 访问密钥。访问密钥 AccessKey 拥有所有 API 的全部权限。建议您通过 IAM 用户进行 API 相关操作和日常运维。使用 IAM 用户前，主账号需要为 IAM 用户授予日志服务相关资源和操作的权限。
• 已添加 VOLCENGINE_ACCESS_KEY_ID 等环境变量。环境变量的配置方式请参考配置身份认证信息。

创建相关资源

1. 初始化 Client 实例。
   您可以参考以下示例代码，引入 TLS iOS SDK 并创建 TLS Client。初始化时推荐通过环境变量动态获取火山引擎密钥等身份认证信息，以免 AccessKey 硬编码引发数据安全风险。

   #import <Foundation/Foundation.h>
   #import <VeTLSiOSSDK/VeTLSiOSSDK.h>
   
   // 初始化客户端，推荐通过环境变量动态获取火山引擎密钥等身份认证信息，以免 AccessKey 硬编码引发数据安全风险。详细说明请参考https://www.volcengine.com/docs/6470/1166455
   int main(int argc, char *argv[]) {
       NSProcessInfo *processInfo = [NSProcessInfo processInfo];
       NSDictionary *environment = [processInfo environment];
       TLSClientConfig *config = [TLSClientConfig alloc]; {
           config.endpoint = [environment objectForKey:@"VOLCENGINE_ENDPOINT"];
           config.region = [environment objectForKey:@"VOLCENGINE_REGION"];
           config.accessKeyId = [environment objectForKey:@"VOLCENGINE_ACCESS_KEY_ID"];
           config.accessKeySecret = [environment objectForKey:@"VOLCENGINE_ACCESS_KEY_SECRET"];
       }
       // Make client
       TLSClient *client = [[TLSClient alloc] initWithConfig:config];
       return 0;
   }
   

2. 创建日志项目。
   您可以通过 TLS Client 进行日志项目的管理，例如创建和删除日志项目。对应的参数设置请参考 API 文档。

   #import <VeTLSiOSSDK/VeTLSiOSSDK.h>
   
   int main(int argc, char *argv[]) {
       ......
       {
           CreateProjectRequest *request = [CreateProjectRequest alloc];
           request.description = @"my project";
           request.region = @"cn-guilin-boe";
           request.projectName = @"ios-sdk-test-project";
           CreateProjectResponse *response = [CreateProjectResponse alloc];
           NSLog(@"CreateProjectResponse: %@", [response toJSONString]);
       }
       ......
   }
   

   您将得到类似如下的响应：

   CreateProjectResponse: {"StatusCode":200,"ProjectId":"XXXX","RequestId":"XXX"}
   

3. 创建日志主题。
   您可以通过 TLS Client 进行日志主题的管理，例如创建和删除日志主题。对应的参数设置请参考 API 文档。

   #import <VeTLSiOSSDK/VeTLSiOSSDK.h>
   
   int main(int argc, char *argv[]) {
       ......
       {
           CreateTopicRequest *request = [CreateTopicRequest alloc]; {
               request.projectId = @"XXXX";
               request.topicName = @"ios-sdk-test-topic";
               request.ttl = [[NSNumber alloc] initWithInt:1];
               request.shardCount = [[NSNumber alloc] initWithInt:1];
           }
           [client CreateTopic:request];
       }
       ......
   }
   

   您将得到类似如下的响应：

   CreateTopicResponse: {"RequestId":"XXXX","StatusCode":200,"TopicId":"XXXX"}
   

通过 TLS Client 上传日志

您可以通过 TLS Client 向指定日志主题上传日志，相关示例代码如下。上传日志的参数设置请参考 API 文档。
成功上传日志后，稍后您可以在控制台中查看实时采集到服务端的日志数据，或通过 SearchLogs 接口检索已上传的日志数据。

#import <VeTLSiOSSDK/VeTLSiOSSDK.h>

int main(int argc, char *argv[]) {
    ......
    // PutLogs
    {
        LogContent *logContent = [[LogContent alloc] init]; {
            logContent.key = @"testKey";
            logContent.value = @"testValue";
        }
        Log *log = [[Log alloc] init]; {
            log.time = (int64_t)([[NSDate date] timeIntervalSince1970]);
            [log.contentsArray addObject:logContent];
        }
        LogGroup *logGroup = [[LogGroup alloc] init]; {
            logGroup.source = @"ios-sdk-test";
            logGroup.fileName = @"ios-sdk-test";
            [logGroup.logsArray addObject:log];
        }
        PutLogsRequest *request = [[PutLogsRequest alloc] init]; {
            request.topicId = @"XXX"; // ios-sdk-test-topic
            request.logGroupList = [[LogGroupList alloc] init];
            [request.logGroupList.logGroupsArray addObject:logGroup];
        }
        PutLogsResponse *response = [client PutLogs:request];
        NSLog(@"PutLogsResponse: %@", [response toJSONString]);
    }
    ......
}

使用 PutLogs V2接口上传日志

定义 Protobuf 上传日志的方式较为繁琐，在对日志上传服务的性能要求不高的场景下，可以使用 TLS iOS SDK 提供的 PutLogs V2 接口，无需组装复杂的日志结构，使用语言原生内置的数据结构即可完成日志上传。示例代码如下：

#import <VeTLSiOSSDK/VeTLSiOSSDK.h>

int main(int argc, char *argv[]) {
    ......
    PutLogsV2Request *request = [[PutLogsV2Request alloc] init]; {
        request.source = @"Your log source";
        request.fileName = @"Your filename";
        request.topicId = @"Your topicId";
        request.logs = @[
            [[PutLogsV2LogItem alloc] initWithKeyValueAndTime:@{@"TestKey": @"TestValue"} timeStamp:0]
        ];
    }
    NSLog(@"Response: %@", [[client PutLogsV2:request] toJSONString]);
    ......
}

使用异步接口上传日志

如果您希望 PutLogs 不阻塞当前线程，您可以使用 TLS iOS SDK 里提供的 PutLogsAsync 和 PutLogsV2Async 接口。

PutLogsAsync 示例代码

#import <VeTLSiOSSDK/VeTLSiOSSDK.h>

int main(int argc, char *argv[]) {
    ......
    LogContent *logContent = [[LogContent alloc] init]; {
        logContent.key = @"testKey";
        logContent.value = @"testValue";
    }
    Log *log = [[Log alloc] init]; {
        log.time = (int64_t)([[NSDate date] timeIntervalSince1970] * 1000);
        [log.contentsArray addObject:logContent];
    }
    LogGroup * logGroup = [[LogGroup alloc] init]; {
        logGroup.source = @"ios-sdk-test";
        logGroup.fileName = @"ios-sdk-test";
        [logGroup.logsArray addObject:log];
    }
    PutLogsRequest *request = [[PutLogsRequest alloc] init]; {
        request.topicId = @"XXX"; // ios-sdk-test-topic
        request.logGroupList = [[LogGroupList alloc] init];
        [request.logGroupList.logGroupsArray addObject:logGroup];
    }
    VeTask* task = [client PutLogsAsync:request];
    // 如果您不关注调用结果，可忽略下面的回调。
    [task continueWithBlock:^id _Nullable(VeTask * _Nonnull t) {
        if (t.error == nil) {
            if (t.result != nil) {
                GeneralHttpResponse* response = t.result;
                NSLog(@"RequestId: %@, HttpStatus: %@, ResponseBody: %@", response.requestId, response.httpStatusCode, [[NSString alloc] initWithData:response.responseBody encoding:NSUTF8StringEncoding]);
            }
        } else NSLog(@"Encountered error: %@", t.error);
        return nil;
    }];
    ......
}

PutLogsV2Async 示例代码

#import <VeTLSiOSSDK/VeTLSiOSSDK.h>

int main(int argc, char *argv[]) {
    ......
    PutLogsV2Request *request = [[PutLogsV2Request alloc] init]; {
        request.source = @"My source";
        request.fileName = @"My filename";
        request.topicId = @"XXX";
        request.logs = @[
            [[PutLogsV2LogItem alloc] initWithKeyValueAndTime:@{@"TestKey": @"TestValue"} timeStamp:0]
        ];
    }
    VeTask* task = [client PutLogsV2Async:request];
    // 如果您不关注调用结果，可忽略下面的回调。
    [task continueWithBlock:^id _Nullable(VeTask * _Nonnull t) {
        if (t.error == nil) {
            if (t.result != nil) {
                GeneralHttpResponse* response = t.result;
                NSLog(@"RequestId: %@, HttpStatus: %@, ResponseBody: %@", response.requestId, response.httpStatusCode, [[NSString alloc] initWithData:response.responseBody encoding:NSUTF8StringEncoding]);
            }
        } else NSLog(@"Encountered error: %@", t.error);
        return nil;
    }];
    ......
}