云日志服務Log4j2 SDK
更新時間 2024-09-02 10:48:01
最近更新時間: 2024-09-02 10:48:01
分享文章
本文主要介紹云日志服務Log4j2 SDK的使用方法。
Ctyun Log4j2 Appender概述
Log4j2 是 log4j 的升級版本。它支持將日志輸出到各種目標，如文件、控制臺等，并允許通過簡單的配置文件自定義日志級別、格式和輸出目的地。
通過Ctyun Log4j Appender，您可以將生成的日志信息異步發送到ctyun云日志服務，其樣式如下：
__user_agent__ : log4j2
level : INFO
location : cn.ctyun.example.Log4j2AppenderExample.main(Log4j2AppenderExample.java:10)
message : log4j2 info log
thread : main
time : 2024-06-06T18:03:06+0800
__message__ : 2024-06-06T18:03:06+0800 [main] INFO cn.ctyun.example.Log4j2AppenderExample: log4j2 info log
其中：
- level：日志級別。
- location：日志打印語句的代碼位置 。
- message：日志內容。
- throwable：日志異常信息，只有當記錄了異常信息，這個字段才會出現。
- thread：線程名稱。
- time：日志打印時間（可以通過 timeFormat 或 timeZone 配置 time 字段呈現的格式和時區）。
- ts：日志生成時的時間。
- message ：日志信息。
- user_agent： 日志來源
功能優勢
日志實時傳輸：
- 實時性增強： 日志數據不再依賴傳統的磁盤寫入，而是實時通過網絡通道發送至服務端，確保數據的即時性。
無侵入性集成：
- 無縫對接： 對于已采用log4j2作為日志框架的應用，我們提供了簡潔的配置方案，無需對應用代碼進行大幅度修改，即可實現日志的采集與傳輸。
高效異步處理：
- 高并發設計： 系統采用高并發架構，后臺異步處理日志發送任務，即使在大量日志數據產生的情況下，也能保證系統的穩定運行和高效處理。
版本支持
- ctyun-lts-java-sdk 1.6.0
使用步驟
源碼使用
打開編寫好的log4j2源碼項目，只需簡單修改即可完成使用，方便用戶自行擴展修改。log4j2SDK 是依賴于ctyun-lts-java-sdk 的日志上傳功能，所以需要先導入ctyun-lts-java-sdk 1.6.0 jar包。
1、maven 工程中引入依賴
在jar包目錄執行以下命令，把ctyun-lts-java-sdk 1.6.0 jar包引入本地maven倉庫，或者通過其他方式手動導入。
mvn install:install-file -Dfile=ctyun-lts-java-sdk-1.6.0.jar -DgroupId=cn.ctyun.lts -DartifactId=ctyun-lts-java-sdk -Dversion=1.6.0 -Dpackaging=jar
在pom.xml 添加以下依賴
<dependency>
? <groupId>cn.ctyun.lts</groupId>
? <artifactId>ctyun-lts-java-sdk</artifactId>
? <version>1.6.0</version>
</dependency>
2、重命名resources 目錄下的log4j2-example.xml 為 log4j2.xml
3、項目中引入CustomerAppender.java
將appender目錄整個移動到您當前的項目中，（如果只單獨運行log4j2項目，則不需要移動）。
4、修改配置文件
以xml配置文件 log4j2.xml為例（若不存在則在項目根目錄創建，一般是src/resources/log4j2.xml），配置自定義的的appender與 Logger，例如：level="INFO",則會接受INFO,WARN,ERROR 級別的日志，DEBUG,TRACE不會被接收打印。
此處需要填入5個必填參數，相關參數獲取，詳情參考天翼云官網云日志服務-SDK接入概述。
<CustomerAppender name="AppenderCustomer"
endpoint="lts log service endpoint"
accessKey="your accessKey"
secretKey="your secretKey"
logProject="your log project code"
logUnit="your log unit code"
......
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" >
<Appenders>
<CustomerAppender name="AppenderCustomer"
endpoint="lts log service endpoint"
accessKey="your accessKey"
secretKey="your secretKey"
logProject="your log project code"
logUnit="your log unit code"
totalSizeInBytes="104857600"
maxBlockMs="0"
ioThreadCount="8"
batchSizeThresholdInBytes="524288"
batchCountThreshold="4096"
lingerMs="2000"
retries="10"
baseRetryBackoffMs="100"
maxRetryBackoffMs="100"
timeFormat="yyyy-MM-dd'T'HH:mm:ssZ"
timeZone="UTC"
ignoreExceptions="true">
<PatternLayout
pattern="%d{yyyy-MM-dd'T'HH:mm:ssZ} [%t] %-5level %class{36}: %msg%xEx"/>
</CustomerAppender>
</Appenders>
<Loggers>
<Root level="INFO">
<AppenderRef ref="AppenderCustomer" level="INFO"/>
</Root>
</Loggers>
</Configuration>
5、測試功能是否正常
運行example目錄中的Log4j2AppenderExample.java內的測試用例，查看發送響應是否返回success，以及日志控制臺是否成功上傳日志信息。
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;
public class Log4j2AppenderExample {
private static final Logger LOGGER = LogManager.getLogger(Log4j2AppenderExample.class);
public static void main(String[] args) throws InterruptedException {
LOGGER.trace("log4j2 trace log"); //不會被上傳, level低于xml中的INFO
LOGGER.debug("log4j2 debug log"); //不會被上傳, level低于xml中的INFO
LOGGER.info("log4j2 info log");
LOGGER.warn("log4j2 warn log");
LOGGER.error("log4j2 error log",new RuntimeException("error"));
}
}
反饋結果
18:03:06.055 [main] INFO cn.ctyun.example.Log4j2AppenderExample : log4j2 info log
18:03:06.093 [main] WARN cn.ctyun.example.Log4j2AppenderExample : log4j2 warn log
18:03:06.094 [main] ERROR cn.ctyun.example.Log4j2AppenderExample : log4j2 error log
java.lang.RuntimeException: error
at cn.ctyun.example.Log4j2AppenderExample.main(Log4j2AppenderExample.java:12) [classes/:?]
response: SUCCESS
response: SUCCESS
response: SUCCESS
jar包使用
直接引入ctyun-lts-java-log4j2-appender-1.6.0.jar包，只需要修改配置文件即可使用
1、maven 工程中引入依賴
在jar包目錄執行以下命令，把ctyun-lts-java-log4j2-appender-1.6.0.jar包引入本地maven倉庫，或者通過其他方式手動導入。
mvn install:install-file -Dfile=ctyun-lts-java-log4j2-appender-1.6.0.jar -DgroupId=cn.ctyun.appender -DartifactId=ctyun-lts-java-log4j2-appender -Dversion=1.6.0 -Dpackaging=jar
在pom.xml 添加以下依賴
<dependency>
<groupId>cn.ctyun.appender</groupId>
<artifactId>ctyun-lts-java-log4j2-appender</artifactId>
<version>1.6.0</version>
</dependency>
2、修改配置文件
以xml配置文件 log4j2.xml為例（若不存在則在項目根目錄創建，一般是src/resources/log4j2.xml），配置自定義的的appender與 Logger。例如：level="INFO",則會接受INFO,WARN,ERROR 級別的日志，DEBUG,TRACE不會被接收打印。
此處需要填入5個必填參數，相關參數獲取，詳情參考天翼云官網云日志服務-SDK接入概述。
<CustomerAppender name="AppenderCustomer"
endpoint="lts log service endpoint"
accessKey="your accessKey"
secretKey="your secretKey"
logProject="your log project code"
logUnit="your log unit code"
......
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" >
<Appenders>
<CustomerAppender name="AppenderCustomer"
endpoint="lts log service endpoint"
accessKey="your accessKey"
secretKey="your secretKey"
logProject="your log project code"
logUnit="your log unit code"
totalSizeInBytes="104857600"
maxBlockMs="0"
ioThreadCount="8"
batchSizeThresholdInBytes="524288"
batchCountThreshold="4096"
lingerMs="2000"
retries="3"
baseRetryBackoffMs="100"
maxRetryBackoffMs="100"
timeFormat="yyyy-MM-dd'T'HH:mm:ssZ"
timeZone="UTC"
ignoreExceptions="true">
<PatternLayout
pattern="%d{yyyy-MM-dd'T'HH:mm:ssZ} [%t] %-5level %class{36}: %msg%xEx"/>
</CustomerAppender>
<Console name="STDOUT" target="SYSTEM_OUT">
<PatternLayout pattern="%d{HH:mm:ss.SSS} [%t] %-5level %C %x: %msg%n"/>
</Console>
</Appenders>
<Loggers>
<Root level="INFO"> <!--全局默認level，會被下面level覆蓋-->
<AppenderRef ref="c" level="INFO"/> <!--只上傳INFO及以上級別日志-->
<AppenderRef ref="STDOUT"/>
</Root>
<!-- ignore package -->
<Logger name="cn.ctyun.lts" level="OFF" additivity="false">
</Logger>
</Loggers>
</Configuration>
3、測試功能是否正常
運行測試用例，查看發送響應是否返回success，以及日志控制臺是否成功上傳日志信息。
18:03:06.055 [main] INFO cn.ctyun.example.Log4j2AppenderExample : log4j2 info log
18:03:06.093 [main] WARN cn.ctyun.example.Log4j2AppenderExample : log4j2 warn log
18:03:06.094 [main] ERROR cn.ctyun.example.Log4j2AppenderExample : log4j2 error log
java.lang.RuntimeException: error
at cn.ctyun.example.Log4j2AppenderExample.main(Log4j2AppenderExample.java:12) [classes/:?]
response: SUCCESS
response: SUCCESS
response: SUCCESS
回調函數
日志發送成功后的回調函數為CustomerAppender.customCallback() ，該回調函數會返回日志上傳的結果，如果想配置其他格式的回調方法，或者使用Logger打印，可以自定義修改appender目錄下CustomerAppender.java 中的customCallback() 類。
private static Callback customCallback() {
Callback callback = new Callback() {
@Override
public void onCompletion(Result result) {
// 處理回調結果
if (result.isSuccessful()) {
System.out.println("response: "+result.getErrorMessage()+ result.getErrorCode());
} else {
System.out.println("response: "+result.getErrorMessage()+ result.getErrorCode());
}
}
};
return callback;
}
參數說明
Log4j2 Appender 可供配置的屬性（參數）如下，其中注釋為必選參數的是必須填寫的，可選參數在不填寫的情況下，使用默認值。
#日志服務的endpoint 地址，必填參數
endpoint="lts log service endpoint"
#用戶身份標識，必填參數
accessKey="your accessKey"
secretKey="your secretKey"
#日志服務的日志項目 project 標識，必填參數
logProject="your log project code"
#日志服務的日志單元 unit 標識，必填參數
logUnit="your log unit code"
#單個 producer 實例能緩存的日志大小上限，默認為 100MB。
totalSizeInBytes="104857600"
#如果 producer 可用空間不足，調用者在 send 方法上的最大阻塞時間，默認為 60 秒。為了不阻塞打印日志的線程，強烈建議將該值設置成 0。
maxBlockMs="0"
#執行日志發送任務的線程池大小，默認為可用處理器個數。
ioThreadCount="8"
#當一個 ProducerBatch 中緩存的日志大小大于等于 batchSizeThresholdInBytes 時，該 batch 將被發送，默認為 512 KB，最大可設置成 5MB。
batchSizeThresholdInBytes="524288"
#當一個 ProducerBatch 中緩存的日志條數大于等于 batchCountThreshold 時，該 batch 將被發送，默認為 4096，最大可設置成 40960。
batchCountThreshold="4096"
#一個 ProducerBatch 從創建到可發送的逗留時間，默認為 2 秒，最小可設置成 100 毫秒。
lingerMs="2000"
#如果某個 ProducerBatch 首次發送失敗，能夠對其重試的次數，默認為3次。
#如果 retries 小于等于 0，該 ProducerBatch 首次發送失敗后將直接進入失敗隊列。
retries="3"
#首次重試的退避時間，默認為 100 毫秒。
#Producer 采樣指數退避算法，第 N 次重試的計劃等待時間為 baseRetryBackoffMs * 2^(N-1)。
baseRetryBackoffMs="100"
#重試的最大退避時間，默認為 100 毫秒。
maxRetryBackoffMs="100"
#輸出到日志服務的時間的格式，默認是 yyyy-MM-dd'T'HH:mm:ssZ，可選參數
timeFormat ="yyyy-MM-dd'T'HH:mm:ssZ"
#輸出到日志服務的時間的時區，默認是 UTC，可選參數（如果希望 time 字段的時區為東八區，可將該值設定為 Asia/Shanghai）
timeZone ="UTC"
使用示例
項目中提供了一個名為 cn.ctyun.example.Log4j2AppenderExample的實例，它會加載resources目錄下的 log4j2.xml文件進行log4j2配置。
log4j2.xml樣例說明
- 配置了三個appender：AppenderWarnAbove、 AppenderInfoOnly、STDOUT。
- AppenderWarnAbove：將日志輸出到logProject=test-proj，logUnit=test-unit1。只輸出WARN及以上級別的日志。
- AppenderInfoOnly：將日志輸出到logProject=test-proj，logUnit=test-unit。只輸出INFO級別的日志。
- STDOUT：將日志輸出到控制臺。由于沒有對日志級別進行過濾，會輸出root中配置的日志級及以上的所有日志。
如果不需要AppenderInfoOnly配置項 ，可以在xml配置文件中將其刪除。
如果需要修改日志上傳的日志級別，比如上傳info級別及以上日志，可以在修改AppenderWarnAbove 的level，如下：
<Loggers>
<Root level="INFO"> <!--全局默認level-->
<AppenderRef ref="AppenderCustomer" level="WARN"/> <!--只上傳WARN及以上級別日志-->
<AppenderRef ref="STDOUT"/>
</Root>
</Loggers>
常見問題
Q：如何關閉某些類輸出的日志？
A：通過在 log4j2.xml 文件中添加 <Logger name="packname" level="OFF"/> 可屏蔽相應包下日志的輸出。例如，當您在 log4j2.xml 文件中添加如下內容會屏蔽 package 名為 cn.ctyun.lts 下所有類的日志輸出。
<Loggers>
...
<!-- ignore package -->
<Logger name="cn.ctyun.lts" level="OFF" additivity="false">
</Logger>
</Loggers>n.example" level="OFF"/>
</Loggers>
