云日志服务Java SDK(标准插件)
云日志服务SDK提供了Java语言上报未结构化日志的一系列方法,方便用户直接使用编码方式上报未结构化日志到云日志服务后台。
传输协议
HTTPS
使用前提
- 参考注册华为账号并开通华为云中操作,完成注册。
- 确认云日志服务的区域,请用户根据所在区域,选择RegionName。
- 获取华为账号的AK/SK。
- 获取华为云账号的项目ID(project id),详细步骤请参见“我的凭证 > API凭证”。
- 获取需要上报到LTS的日志组ID和日志流ID。
- 已安装Java开发环境。云日志服务Java SDK支持JDK1.8及以上,您可以执行java –version命令检查您已安装的Java版本。如未安装,可以从Java官方网站下载安装包进行安装。
使用说明
- 当用户修改权限后,权限信息在一天后生效。
- SDK支持跨云/本地上报日志,当前仅支持华北-北京四、华东-上海一、华南-广州、西南-贵阳一。使用详情见Appender配置参数说明表中的“enableLocalTest”参数,当该参数为true时,上报日志规格为单个机器200次/秒(即每秒只能发送200次,每次批量发送数量/大小详情见参数“batchSizeThresholdInBytes、batchCountThreshold、lingerMs”)。
- 通过SDK上报日志到LTS的时间相距当前时间不超过2天,否则上报日志会被LTS删除。
注意事项
由于Java-SDK默认对SK明文存储,不符合某些对于安全有更高要求的用户,LTS提供了一种用户自定义的加解密方式,建议用户优先使用加解密方式。
加密过程如下:
- 用户编写一个java类,比如com.demo.DecryptDemo类,在该类中增加一个解密方法,比如decrypt方法,输入和输出均为字符串。
- 编写decrypt的方法内容,客户自行实现SK加解密算法,返回解密后的值。
- 当用户调用Java-SDK初始化时,会需要传入SK,这时使用DecryptDemo.decrypt方法即可。
安装SDK
您可以通过以下两种方式安装云日志服务Java SDK。
方式一:在Maven项目中加入依赖项(推荐方式)。
- maven构建时,settings.xml文件的mirrors节点需要增加华为外部开源仓。如下:
<mirror> <id>huaweicloud</id> <mirrorOf>*</mirrorOf> <url>https://repo.huaweicloud.com/repository/maven/</url> </mirror>
- 您可以在华为外部开源仓中获取日志服务Java SDK依赖的最新版本。
- 在Maven工程中使用日志服务Java SDK,只需在pom.xml中加入相应依赖即可,Maven项目管理工具会自动下载相关JAR包。以1.0.1版本为例,在<dependencies>中加入如下内容:
<dependency> <groupId>io.github.huaweicloud</groupId> <artifactId>lts-sdk-common</artifactId> <version>1.0.1</version> </dependency> <dependency> <groupId>io.github.huaweicloud</groupId> <artifactId>lts-sdk-java</artifactId> <version>1.0.1</version> </dependency>
方式二:在项目中直接依赖Java SDK的jar包。
- 下载lts-sdk-common和lts-sdk-java包。(建议使用最新版本的jar包。)
- 请确保您的项目中有以下依赖,因为SDK的jar包中需要该依赖。
<dependency> <groupId>com.alibaba</groupId> <artifactId>fastjson</artifactId> <version>1.2.83</version> </dependency> <dependency> <groupId>joda-time</groupId> <artifactId>joda-time</artifactId> <version>2.10.14</version> </dependency> <dependency> <groupId>org.apache.commons</groupId> <artifactId>commons-lang3</artifactId> <version>3.11</version> </dependency> <dependency> <groupId>org.apache.httpcomponents</groupId> <artifactId>httpclient</artifactId> <version>4.5.13</version> </dependency> <dependency> <groupId>com.google.guava</groupId> <artifactId>guava</artifactId> <version>30.1.1-jre</version> </dependency> <dependency> <groupId>commons-io</groupId> <artifactId>commons-io</artifactId> <version>2.11.0</version> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-api</artifactId> <version>2.0.7</version> </dependency> <dependency> <groupId>org.slf4j</groupId> <artifactId>slf4j-simple</artifactId> <version>2.0.7</version> </dependency>
- 以0.6.75版本的IntelliJ IDEA为例:项目中导入JAR包
- 在IntelliJ IDEA中选择您的工程,选择“File > Project Structure”。
- 在Project Structure对话框,左侧单击“Modules”。
- 在Dependencies页签,选择“+ > JARs or directories”。
- 在Attach Files or Directories对话框中,选中已下载的JAR文件,单击“OK”。
示例代码
package com.huawei.log; import java.util.ArrayList; import java.util.HashMap; import java.util.List; import java.util.Map; import com.alibaba.fastjson.JSONObject; import com.huaweicloud.lts.appender.JavaSDKAppender; import com.huaweicloud.lts.producer.Producer; import com.huaweicloud.lts.producer.exception.ProducerException; import com.huaweicloud.lts.producer.model.log.LogContent; import com.huaweicloud.lts.producer.model.log.LogItem; public class LtsLogJavaSdkTest1 implements Runnable { @Override public void run() { /* 认证用的ak和sk硬编码到代码中或者明文存储都有很大的安全风险, 建议在配置文件或者环境变量中密文存放, 使用时解密, 确保安全; 本示例以ak和sk保存在环境变量中为例, 运行本示例前请先在本地环境中设置环境变量HUAWEICLOUD_SDK_AK和HUAWEICLOUD_SDK_SK. */ String ak = System.getenv("HUAWEICLOUD_SDK_AK"); String sk = System.getenv("HUAWEICLOUD_SDK_SK"); // 构建appender JavaSDKAppender appender = JavaSDKAppender.custom() // 华为云账号的项目ID(project id) .setProjectId("xxx") // 华为云账号的AK .setAccessKeyId(ak) // 华为云账号的SK .setAccessKeySecret(sk) // 云日志服务的区域 .setRegionName("xxxxxx") // 单个Appender能缓存的日志大小上限 .setTotalSizeInBytes(104857600) // producer发送日志时阻塞时间 .setMaxBlockMs(0L) // 执行日志发送任务的线程池大小 .setIoThreadCount(8) // producer发送单批日志量上限 .setBatchSizeThresholdInBytes(524288) // producer发送单批日志条数上限 .setBatchCountThreshold(4096) // producer发送单批日志等待时间 .setLingerMs(2000) // producer发送日志失败后重试次数 .setRetries(5) // 首次重试的退避时间 .setBaseRetryBackoffMs(500L) // 重试的最大退避时间 .setMaxRetryBackoffMs(500L) // 默认false, true: 可以跨云上报日志, false: 仅能在华为云ecs主机上报日志 // .setEnableLocalTest(false) // 超过1M的日志, 拆分后丢弃大于1M的数据 // .setGiveUpExtraLongSingleLog(true) .builder(); // 获取发送producer Producer producer = appender.getProducer(); // 创建日志发送的结构体 while (true) { List<LogItem> logItemList = new ArrayList<>(); try { Thread.sleep(500); // 构建日志 LogItem logItem = getLogItem(); logItemList.add(logItem); // 发送日志(日志组ID,日志流ID,日志) producer.send("xxxxxx", "xxxxxx", logItemList); } catch (InterruptedException | ProducerException e) { e.printStackTrace(); } } } private LogItem getLogItem() { LogItem logItem = new LogItem(); // 华为云账号的项目ID(project id) logItem.setTenantProjectId("xxxxxx"); // 客户可以自行定义日志标签, 如果不需要请传入一个空Map Map<String, String> labels = new HashMap<>(); labels.put("javaSdk1", "value1"); labels.put("javaSdk2", "value2"); logItem.setLabels(JSONObject.toJSONString(labels)); List<LogContent> contents = new ArrayList<>(); for (int k = 0; k < 100; k++) { LogContent logContent = new LogContent(); // 日志产生时间, 建议为当前时间Ns long logTimeNs = System.currentTimeMillis() * 1000000L + System.nanoTime() % 1000000L; logContent.setLogTimeNs(logTimeNs); // 日志内容 logContent.setLog("test~~javaSdk~~~test1 " + k); contents.add(logContent); } logItem.setContents(contents); return logItem; } }
单个producer性能基线
上报日志时,请参考如下参数的测试性能基线,若超出基线值,可能会导致日志上报异常。
- totalSizeInBytes:524288000
- ioThreadCount:8
- maxBlockMs:0
- batchSizeThresholdInBytes:524288
- batchCountThreshold:4096
- lingerMs:2000
按照参数基线值设置后,使用8U16GB的机器规格测试,上报单条日志大小为1KB。
测试结果:SDK上报日志的数据量为10MB/s,速率为1.2w条/s。
当日志上报量超过单个producer时:
- 建议拆分日志流,使用多个producer上报日志,分摊流量,以保障SDK处于正常上报状态。
- 如果maxBlockMs为0时,SDK处于非阻塞状态,会触发保护机制自动降级,可能会对部分日志做丢弃处理。
- 如果maxBlockMs大于0时,SDK处于阻塞状态,阻塞时间为maxBlockMs,可能会造成prodcuer.send()发送日志方法处于阻塞状态。
配置参数说明
- Appender中配置参数说明。
表1 Appender配置参数说明表 参数名称
描述
类型
是否需要填写
默认值
projectId
华为云账号的项目ID(project id)。
String
必填
-
accessKeyId
华为云账号的AK。认证用的AK硬编码到代码中或者明文存储都有很大的安全风险,建议密文存放,使用时解密,确保安全。
String
必填
-
accessKeySecret
华为云账号的SK。认证用的SK硬编码到代码中或者明文存储都有很大的安全风险,建议密文存放,使用时解密,确保安全。
String
必填
-
regionName
云日志服务的区域。
String
必填
-
logGroupId
LTS的日志组ID。
String
必填
-
logStreamId
LTS的日志流ID。
String
必填
-
totalSizeInBytes
单个producer实例能缓存的日志大小上限。
int
选填
100M(100 * 1024 * 1024)
maxBlockMs
如果 producer 可用空间不足,调用者在 send 方法上的最大阻塞时间,单位为毫秒。默认为 60 秒(60000毫秒),建议为0秒。
- 当maxBlockMs值>=0时,则阻塞到设置的时间,如果到达阻塞时间,还是不能获取到内存,即报错且丢弃日志。
- 当maxBlockMs值=-1时,则一直阻塞到发送成功,且不会丢弃日志。
long
选填
60秒(60000毫秒)
ioThreadCount
执行日志发送任务的线程池大小。
int
选填
客户机器空闲CPU数量,但一定大于1
batchSizeThresholdInBytes
当一个 ProducerBatch 中缓存的日志大小大于等于 batchSizeThresholdInBytes 时,该 batch 将被发送。
int
选填
0.5M(512 * 1024)
batchCountThreshold
当一个 ProducerBatch 中缓存的日志条数大于等于 batchCountThreshold 时,该 batch 将被发送。
int
选填
4096
lingerMs
一个 ProducerBatch 从创建到可发送的逗留时间。
int
选填
2S
retries
如果某个 ProducerBatch 首次发送失败,能够对其重试的次数,建议为 5 次。如果 retries 小于等于 0,该 ProducerBatch 首次发送失败后将直接进入失败队列。
int
选填
10
baseRetryBackoffMs
首次重试的退避时间。
long
选填
0.1S
maxRetryBackoffMs
重试的最大退避时间。
long
选填
50S
giveUpExtraLongSingleLog
超过1M的日志, 拆分后丢弃大于1M的数据。
boolean
选填
false
enableLocalTest
是否开启跨云上报日志。
- 选true时,开启跨云后用户能通过公网(仅支持华北-北京四、华东-上海一、华南-广州、西南-贵阳一)访问(建议调测使用)。
- 选false时,关闭跨云后用户是通过华为云当前区域主机访问。
boolean
选填
false
- 日志上报LogItem类参数说明。
单次上报条数小于4096条,且小于5M。
表2 日志上报LogItem类参数说明表 参数名称
描述
类型
是否需要填写
tenantProjectId
华为云账号的项目ID(project id)。
String
是
contents
批量日志内容。
Array< LogContent>
是
labels
日志标签,JSON格式。
支持的Key值有:projectId,clusterId,clusterName,nameSpace,appGroup,appName,serviceID,podName,pid,group,containerName,hostId,hostIP,hostName,hostIPv6,serverlessFunc,serverlessPkg,functionVersion,pailId,pathFile,kind
例如:
{ "clusterName" : "k8s", "appGroup" : "group1" }
String
是
- 日志上报LogConten类参数说明。
通过SDK上报日志到LTS的时间相距当前时间不超过2天,否则上报日志会被LTS删除。
表3 LogConten类参数说明 参数名称
描述
类型
是否需要填写
logTimeNs
日志时间(单位:纳秒)
long
是
log
日志内容
String
是