云日志服务Java SDK（log4j2）
云日志服务Java SDK提供了与log4j2适配的扩展插件，可以直接在log4j2中配置华为云appender，将通过log4j2产生的日志直接上报至云日志服务。
传输协议
HTTPS
使用前提
- 使用云日志SDK前，您需要注册华为账号并开通华为云。
- 确认云日志服务的区域，请用户根据所在区域，选择region name。
- 获取华为云账号的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删除。
安装SDK
您可以通过以下两种方式安装日志服务log4j2 SDK
方式一：在Maven项目中加入依赖项（推荐方式）。
- maven构建时，settings.xml文件的mirrors节点需要增加华为外部开源仓。如下：
<mirror> <id>huaweicloud</id> <mirrorOf>*</mirrorOf> <url>https://repo.huaweicloud.com/repository/maven/</url> </mirror> - 您可以在华为外部开源仓中获取日志服务log4j2 SDK依赖的最新版本。
- 在Maven工程中使用日志服务log4j2 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-log4j2</artifactId> <version>1.0.1</version> </dependency>
方式二：在项目中直接依赖Log4j2 SDK的jar包。
- 下载lts-sdk-common和lts-sdk-log4j2包。
- 请确保您的项目中有以下依赖，因为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> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-core</artifactId> <version>2.19.0</version> </dependency> <dependency> <groupId>org.apache.logging.log4j</groupId> <artifactId>log4j-api</artifactId> <version>2.19.0</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。
示例代码
- log4j2.xml示例如下：
<?xml version="1.0" encoding="UTF-8"?> <Configuration status="WARN"> <Appenders> <!-- projectId：华为云账号的项目ID--> <!-- logGroupId：华为云日志服务日志组ID--> <!-- logStreamId：华为云日志服务日志流ID--> <!-- accessKeyId：华为云账号的AK, 认证用的AK硬编码到代码中或者明文存储都有很大的安全风险, 建议密文存放, 使用时解密, 确保安全--> <!-- accessKeySecret：华为云账号的SK, 认证用的SK硬编码到代码中或者明文存储都有很大的安全风险, 建议密文存放, 使用时解密, 确保安全--> <!-- regionName：云日志服务的区域：单个Appender能缓存的日志大小上限--> <!-- maxBlockMs：producer发送日志时阻塞时间--> <!-- ioThreadCount：执行日志发送任务的线程池大小--> <!-- batchSizeThresholdInBytes：producer发送单批日志量上限--> <!-- batchCountThreshold：producer发送单批日志条数上限--> <!-- lingerMs：producer发送单批日志等待时间--> <!-- retries：producer发送日志失败后重试次数--> <!-- baseRetryBackoffMs：首次重试的退避时间--> <!-- maxRetryBackoffMs：重试的最大退避时间--> <!-- giveUpExtraLongSingleLog：过1M的日志, 拆分后放弃1M以外的--> <!-- enableLocalTest：默认false, true: 可以跨云上报日志, false: 仅能在华为云ecs主机上报日志--> <ltsLog name="log4j2sdkappender" projectId="xxx" logGroupId="xxx" logStreamId="xxx" accessKeyId="xxx" accessKeySecret="xxx" regionName="xxx" totalSizeInBytes="104857600" maxBlockMs="0" ioThreadCount="8" batchSizeThresholdInBytes="524288" batchCountThreshold="4096" lingerMs="2000" retries="5" baseRetryBackoffMs="500" maxRetryBackoffMs="500" giveUpExtraLongSingleLog="true" enableLocalTest="false"> <PatternLayout pattern="%d %-5level [%thread] %logger{0}: %msg"/> </ltsLog> </Appenders> <Loggers> <Root level="WARN"> <AppenderRef ref="log4j2sdkappender"/> </Root> </Loggers> </Configuration> - 编写代码产生的日志如下：
package com.huawei.log; import org.apache.logging.log4j.LogManager; import org.apache.logging.log4j.Logger; public class TestLog4j2AppenderInfo { private static final Logger LOGGER = LogManager.getLogger(TestLog4j2AppenderInfo.class); public static void main(String[] args) { LOGGER.info("test~log4j2~~~info"); } }
配置参数说明
- 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
