1. 前言

安装使用Java SDK可以帮助开发者快速接入并使用天翼云的日志服务相关功能，目前支持同步上传，异步批量上传等功能。

2. 使用条件

2.1. 先决条件

用户需要具备以下条件才能够使用LTS SDK Java版本：

1、购买并订阅了天翼云的云日志服务，并创建了日志项目和日志单元，获取到相应编码（logProject、logUnit）。

2、已获取AccessKey 和 SecretKey。

3、已安装JDK1.8及以上环境。

2.2. 下载及安装

下载压缩包，放到相应位置后并解压，把包放在本地目录：<base_path>。如果您想直接使用SDK，可以不做修改，直接使用SDK源码，示例代码为example/SamplePutlogs.java。。

1. 把SDK源码构建成jar包，可通过构建工具构建。或者直接使用已有jar包（target目录下）：”ctyun-lts-java-sdk-1.6.0.jar”。

2. 把生成的jar包引入本地maven仓库。可以通过例如idea的maven工具install 到maven仓库。或者通过命令构建安装（在jar包所在目录执行下面命令）。

mvn install:install-file -Dfile=ctyun-lts-java-sdk-1.10.0.jar -DgroupId=cn.ctyun.lts -DartifactId=ctyun-lts-java-sdk -Dversion=1.10.0 -Dpackaging=jar

3. 在您的maven工程的pom.xml文件中增加配置

<dependency>
    <groupid>cn.ctyun.lts</groupid>
    <artifactid>ctyun-lts-java-sdk</artifactid>
    <version>1.10.0</version>
</dependency>

4. 引入第三方依赖包

<dependency>
            <groupid>com.alibaba</groupid>
            <artifactid>fastjson</artifactid>
            <version>1.2.83_noneautotype</version>
        </dependency>
        <dependency>
            <groupid>net.jpountz.lz4</groupid>
            <artifactid>lz4</artifactid>
            <version>1.3.0</version>
        </dependency>
        <dependency>
            <groupid>org.apache.httpcomponents</groupid>
            <artifactid>httpclient</artifactid>
            <version>4.5.1</version>
        </dependency>
        <dependency>
            <groupid>io.opentelemetry.proto</groupid>
            <artifactid>opentelemetry-proto</artifactid>
            <version>1.1.0-alpha</version>
        </dependency>
        <dependency>
            <groupid>org.apache.httpcomponents</groupid>
            <artifactid>httpmime</artifactid>
            <version>4.5.1</version>
        </dependency>
        <dependency>
            <groupid>com.google.protobuf</groupid>
            <artifactid>protobuf-java</artifactid>
            <version>3.23.4</version>
        </dependency>

3. SDK基本使用

3.1. 基本使用

使用 SDK访问 LTS 的服务，需要设置正确的 AccessKey、SecretKey 和服务端 Endpoint，所有的服务可以使用同一 key 凭证来进行访问，但不同的服务需要使用不同的 endpoint 进行访问，详情参考天翼云官网-SDK接入概述。在调用前SDK，需要已知以下参数：

1、云日志服务访问地址。详情请查看访问地址（Endpoint）。

2、key凭证：accessKey和secretKey 。详情请查看如何获取访问密钥（AK/SK）。

3、日志项目编码：logProject，在使用SDK前，需要确保您有至少一个已经存在的日志项目，日志项目就是您要将日志上传到的地方。

4、日志单元编码：logUnit，在使用SDK前，需要确保日志项目中有至少一个已经存在的日志单元。

目前通过SDK将日志上传到云日志服务有两种上传形式：同步上传和异步上传，详细文档参考代码内README文件。

1、同步上传：当调用日志上传接口时，sdk会立即进行http请求调用，并返回发送结果。这种方式结构简单，可用于发送频率不高的场景。

2、异步上传：当调用日志上传接口时，后台线程会将日志进行累积，当达到发送条件时，会进行一次合并发送。对于需要频繁调用发送接口的场景，这种方式性能更卓越，更高效。

示例代码：同步上传

public static void main(String args[]) throws LogException, InterruptedException {
    String accessKey = "your accessKey";
    String secretKey = "your secretKey";
    String logProject = "log project Code";//日志项目ID
    String logUnit = "log unit Code";//日志单元ID
    String endpoint = "endpoint";

    Client client = new Client(endpoint, accessKey,secretKey);
    //构建日志
    LogItem logItem = new LogItem(System.currentTimeMillis());
    logItem.setOrigin_msg("info: sync ,java, test message!");  //日志原文
    logItem.PushBackContent("level", "info");             //日志分词
    logItem.PushBackContent("double_number", 3.1415);

    LogItems logItems = new LogItems();
    logItems.add(logItem); //添加日志，可添加多条

    try {
        for (int i = 0; i < 100; i++) {        //发送100次
            PutLogsResponse response = client.PutLogs(logProject, logUnit, logItems);
            PutLogsResponseBody res = response.getBody();
            System.out.println("response: statusCode:"+res.getStatusCode()+" ,message:"+res.getMessage()+" ,error:"+res.getError());
        }
    } catch (LogException e) {
        System.out.println("error :" + e.getErrorCode() + " , " + e.getMessage() + " , " + e.getHttpCode());
        e.printStackTrace();
    } catch (Exception ex) {
        ex.printStackTrace();
    }
}

示例代码：异步批量上传

public static void main(String[] args) throws Exception {
    String accessKey = "your accessKey";
    String secretKey = "your secretKey";
    String logProject = "log project Code";//日志项目ID
    String logUnit = "log unit Code";//日志单元ID
    String endpoint = "endpoint";

    // 初始化日志生产者
    try {
        Producer producer = new LogProducer(new ProducerConfig());
        producer.buildClient(logProject, endpoint, accessKey, secretKey);

        //发送日志，后台自动异步批量发送
        for (int i = 0; i < 1000; i++) {
            LogItem logItem = Utils.generateLogItem(1);
            producer.sendLogs(logProject, logUnit, logItem);
        }

        // 稍作等待后关闭生产者
        Thread.sleep(10000);

        producer.close();
    } catch (InterruptedException e) {
        LOGGER.warn("关闭生产者时线程被中断");
    } catch (ProducerException e) {
        LOGGER.info("关闭生产者失败: ", e);
    } catch (Exception e) {
        LOGGER.info("发生异常: ", e);
    }
}

4. 服务代码示例-同步上传

4.1. 关于Client的操作

此操作是初始化Client。用户需要配置至少3个关键的参数才够初始化Client。

示例代码：初始化Client配置

Client client = new Client(endpoint, accessKey,secretKey);

4.2. 关于Log的操作

此操作用于生成待上传的日志，日志上传只能上传LogItem格式的日志，logData包含了一个ArrayList类型，里面包含若干条LogItem日志。

LogItem类型的日志格式如下：

其中LogContent 和Labels是包含了两个成员变量的类，成员变量为key：string，value：T。

示例代码：组装生成1条日志

LogData logData = new LogData();
LogItem logItem = new LogItem(System.currentTimeMillis());
logItem.setOrigin_msg("java, test message!");
logItem.PushBackContent("level", "info");
logItem.PushBackContent("unit_id", "12345678");
logItem.PushBackContent("area", 1.3145);
logData.add(logItem);

注意：单条日志长度最大限制为1MB，其中content和labels的key的长度不超过64字符，仅支持数字、字母、下划线、连字符(-)、点(.),且必须以字母开头。value类型最好使用字符串（String）和数字类型（int,double），其他类型建议先转为字符串类型，并且value值不能为空或空字符串。

4.3. 关于日志上传的操作

此操作用于日志上传服务，需要传入的参数有四个，分别是logProject(日志项目编码)，logUnit(日志单元编码)，logData（要上传的日志），source（日志来源）。

示例代码：上传日志

PutLogsResponse response = client.PutLogs(logProject, logUnit, logItems);
PutLogsResponseBody res = response.getBody();     
System.out.println("response: statusCode:"+res.getStatusCode()+",message"+res.getMessage()+" ,error:"+res.getError());	                           

PutLogsResponse 里面包含了请求的响应头header和响应体body，其中接收响应数据的响应体body格式如下：

日志服务相关错误编码(部分):