Ctyun Logback Appender概述

Logback是由log4j的創始人設計的一款高性能、靈活配置的Java日志框架。它支持將日志輸出到各種目標，如文件、控制臺等，并允許通過簡單的配置文件自定義日志級別、格式和輸出目的地。Logback的特點在于其高效的日志處理能力和強大的配置靈活性，使得開發者能夠輕松控制和管理日志，從而更好地監控和調試應用程序。同時，Logback也提供了與多種系統組件的集成支持，為Java應用提供了全面的日志解決方案。

通過Ctyun Logback Appender，您可以將生成的日志信息異步發送到ctyun云日志服務，其樣式如下：

__user_agent__  : logback
level  : INFO
location  : cn.ctyun.example.LogbackAppenderExample.main(LogbackAppenderExample.java:22)
message  : info log logback
thread  : main
time  : 2024-06-06T14:33+0800
__message__  : 2024-06-06 14:33:15,203 INFO [main] LogbackAppenderExample: info log logback

其中：

• level：日志級別。
• location：日志打印語句的代碼位置 。
• message：日志內容。
• throwable：日志異常信息，只有當記錄了異常信息，這個字段才會出現。
• thread：線程名稱。
• time：日志打印時間（可以通過 timeFormat 或 timeZone 配置 time 字段呈現的格式和時區）。ts ：日志生成時的時間。
• __ message __：日志信息。
• __ user_agent __： 日志來源

功能優勢

日志實時傳輸：

• 實時性增強： 日志數據不再依賴傳統的磁盤寫入，而是實時通過網絡通道發送至服務端，確保數據的即時性。

無侵入性集成：

• 無縫對接： 對于已采用logback作為日志框架的應用，我們提供了簡潔的配置方案，無需對應用代碼進行大幅度修改，即可實現日志的采集與傳輸。

高效異步處理：

• 高并發設計： 系統采用高并發架構，后臺異步處理日志發送任務，即使在大量日志數據產生的情況下，也能保證系統的穩定運行和高效處理。

版本支持

• logback 1.2.3
• ctyun-lts-java-sdk 1.6.0

使用方式

源碼使用

打開編寫好的logback源碼項目，只需簡單修改即可完成使用，方便用戶自行擴展修改。

1、maven 工程中引入依賴

在jar包目錄執行以下命令，把生成的jar包引入本地maven倉庫，或者通過其他方式手動導入。logback SDK 是依賴于ctyun-lts-java-sdk 的日志上傳功能，所以需要先導入ctyun-lts-java-sdk 1.6.0 jar包。

mvn install:install-file -Dfile=ctyun-lts-java-sdk-1.6.0.jar -DgroupId=cn.ctyun.lts -DartifactId=ctyun-lts-java-sdk-appender -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 目錄下的logback-example.xml 為 logback.xml

3、項目中引入CustomerAppender.java

將appender目錄整個移動到您當前的項目中，（如果只單獨運行logback項目，則不需要移動），然后logback.xml的appender字段中的 class 指向appednder目錄下的CustomerAppender.java類所在位置。

<appender name="AppenderCustomer" class="cn.ctyun.appender.CustomerAppender">

4、 修改配置文件

以xml配置文件 logback.xml為例（若不存在則在項目根目錄創建，一般是src/resources/logback.xml），配置自定義的的appender與 Logger，如果您的目錄發送改變，class也需改變，指向CustomerAppende.java 類所在位置。此處需要填入5個必填參數，相關參數獲取，詳情參考天翼云官網云日志服務-SDK接入概述。

  <!-- 此處需要進行用戶填寫相關配置信息 -->
 ?  <endpoint>your endpoint</endpoint>
 ?  <accessKey>your accessKey</accessKey>
 ?  <secretKey>your secretKey</secretKey>
 ?  <logProject>your log project code</logProject>
 ?  <logUnit>your log unit code</logUnit>

<appender name="AppenderCustomer" class="cn.ctyun.appender.CustomerAppender">
        <!--必填項-->
        <!-- 此處需要進行用戶填寫相關配置信息 -->
        <endpoint>your endpoint</endpoint>
        <accessKey>your accessKey</accessKey>
        <secretKey>your secretKey</secretKey>
        <logProject>your log project code</logProject>
        <logUnit>your log unit code</logUnit>
        <!-- 可選項 詳見 '參數說明'-->
        <totalSizeInBytes>104857600</totalSizeInBytes>
        <maxBlockMs>0</maxBlockMs>
        <ioThreadCount>8</ioThreadCount>
        <batchSizeThresholdInBytes>524288</batchSizeThresholdInBytes>
        <batchCountThreshold>4096</batchCountThreshold>
        <lingerMs>2000</lingerMs>
        <retries>10</retries>
        <baseRetryBackoffMs>100</baseRetryBackoffMs>
        <maxRetryBackoffMs>50000</maxRetryBackoffMs>
        <!-- 可選項 設置時區 -->
        <timeFormat>yyyy-MM-dd'T'HH:mmZ</timeFormat>
        <timeZone>Asia/Shanghai</timeZone>
        <!-- 可選項 通過配置 encoder 的 pattern 自定義 log 的格式 -->
        <encoder>
            <pattern>%d{yyyy-MM-dd'T'HH:mm:ssZ} [%thread] %-5level  %class{36} %x: %msg%n</pattern>
        </encoder>
        <!-- 打印INFO,WARN,ERROR級別的日志,過濾掉INFO 級別以下的日志 -->
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>INFO</level>
        </filter>
        <mdcFields>THREAD_ID,MDC_KEY</mdcFields>
    </appender>

5、測試功能是否正常

運行example目錄中的LogbackAppenderExample.java內的測試用例，查看控制臺是否返回success，以及日志控制臺是否成功上傳日志信息

jar包使用

直接引入ctyun-lts-java-logback-appender-1.6.0.jar包，只需要修改配置文件即可使用

1、maven 工程中引入依賴

在jar包目錄執行以下命令，把ctyun-lts-java-logback-appender-1.6.0.jar包引入本地maven倉庫，或者通過其他方式手動導入。

mvn install:install-file -Dfile=ctyun-lts-java-logback-appender-1.6.0.jar -DgroupId=cn.ctyun.appender -DartifactId=ctyun-lts-java-logback-appender -Dversion=1.6.0 -Dpackaging=jar

在pom.xml 添加以下依賴

<dependency>
 ?  <groupId>cn.ctyun.appender</groupId>
 ?  <artifactId>ctyun-lts-java-logback-appender</artifactId>
 ?  <version>1.6.0</version>
</dependency>

2、修改配置文件

以xml型配置文件 logback.xml為例（若不存在則在項目根目錄創建，一般是src/resources/logback.xml），配置自定義的的appender與 Logger。此處需要填入5個必填參數，相關參數獲取，詳情參考天翼云官網云日志服務-SDK接入概述。

    <!-- 此處需要進行用戶填寫相關配置信息 -->
    <endpoint>your endpoint</endpoint>
    <accessKey>your accessKey</accessKey>
    <secretKey>your secretKey</secretKey>
    <logProject>your log project code</logProject>
    <logUnit>your log unit code</logUnit>

   <!--為了防止進程退出時，內存中的數據丟失，請加上此選項-->
    <shutdownHook class="ch.qos.logback.core.hook.DelayingShutdownHook"/>
	 
	<!--自定義的 AppenderCustomer 用于采集 info及以上級別的日志-->
    <appender name="AppenderCustomer" class="cn.ctyun.appender.CustomerAppender">
        <!--必選項-->
        <!-- 此處需要進行用戶填寫相關配置信息 -->
        <endpoint>your endpoint</endpoint>
        <accessKey>your accessKey</accessKey>
        <secretKey>your secretKey</secretKey>
        <logProject>your log project code</logProject>
        <logUnit>your log unit code</logUnit>
        <!-- 可選項 詳見 '參數說明'-->
        <totalSizeInBytes>104857600</totalSizeInBytes>
        <maxBlockMs>0</maxBlockMs>
        <ioThreadCount>8</ioThreadCount>
        <batchSizeThresholdInBytes>524288</batchSizeThresholdInBytes>
        <batchCountThreshold>4096</batchCountThreshold>
        <lingerMs>2000</lingerMs>
        <retries>10</retries>
        <baseRetryBackoffMs>100</baseRetryBackoffMs>
        <maxRetryBackoffMs>50000</maxRetryBackoffMs>
        <!-- 可選項 設置時區 -->
        <timeFormat>yyyy-MM-dd'T'HH:mmZ</timeFormat>
        <timeZone>Asia/Shanghai</timeZone>
        <!-- 可選項 通過配置 encoder 的 pattern 自定義 log 的格式 -->
        <encoder>
            <pattern>%d{yyyy-MM-dd'T'HH:mm:ssZ} [%thread] %-5level  %class{36} %x: %msg%n</pattern>
        </encoder>
        <!-- 打印INFO,WARN,ERROR級別的日志,過濾掉INFO級別以下的日志 -->
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>INFO</level>
        </filter>

3、測試功能是否正常

運行您的測試用例，查看控制臺是否有日志發送信息的反饋

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
 
public class LogbackAppenderExample {

    private static final Logger LOGGER = LoggerFactory.getLogger(LogbackAppenderExample.class);

    public static void main(String[] args) {
        LOGGER.trace("trace log logback");   //level 低于info,不會被上傳
        LOGGER.debug("debug log logback");   //level 低于info,不會被上傳
        LOGGER.info("info log logback");
        LOGGER.warn("warn log logback");
        LOGGER.error("error log logback");
    }
}

反饋結果

15:56:33.813 [main] INFO  org.example.Logback - info log logback
15:56:33.858 [main] WARN  org.example.Logback - warn log logback 
15:56:33.858 [main] ERROR org.example.Logback - error log logback
response: SUCCESS  
response: SUCCESS  
response: SUCCESS  

參數說明

Logback Appender 可供配置的屬性（參數）如下，其中注釋為必選參數的是必須填寫的，可選參數在不填寫的情況下，使用默認值。

#日志服務的 HTTPS 地址，必選參數
<endpoint>your endpoint</endpoint>
#用戶身份標識，必選參數
<accessKey>your accessKey</accessKey>
<secretKey>your secretKey</secretKey>
#日志服務的日志項目 project 標識，必選參數
<logProject>your log project code</logProject>
#日志服務的日志單元 unit 標識，必選參數
<logUnit>your log unit code</logUnit>

#單個 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 首次發送失敗，能夠對其重試的次數，默認為 10 次。
#如果 retries 小于等于 0，該 ProducerBatch 首次發送失敗后將直接進入失敗隊列。
retries=10
#該參數越大能讓您追溯更多的信息，但同時也會消耗更多的內存。
maxReservedAttempts=11
#首次重試的退避時間，默認為 100 毫秒。
#Producer 采樣指數退避算法，第 N 次重試的計劃等待時間為 baseRetryBackoffMs * 2^(N-1)。
baseRetryBackoffMs=100
#重試的最大退避時間，默認為 50 秒。
maxRetryBackoffMs=50000

#輸出到日志服務的時間的格式，默認是 yyyy-MM-dd'T'HH:mm:ssZ，可選參數
timeFormat = yyyy-MM-dd'T'HH:mm:ssZ

#輸出到日志服務的時間的時區，默認是 UTC，可選參數（如果希望 time 字段的時區為東八區，可將該值設定為 Asia/Shanghai）
timeZone = UTC
#是否要記錄 Location 字段（日志打印位置），默認為 true，如果希望減少該選項對性能的影響，可以設為 false
includeLocation = true
#當 encoder 不為空時，是否要包含 message 字段，默認為 true
includeMessage = true

注意：

• CustomerAppender在運行過程中產生的異常會被捕獲并放入logback的 BasicStatusManager類中，您可以通過配置 OnConsoleStatusListener或其他方式查看出錯信息。如果不想打印這些信息，可以配置NopStatusListener。

回調函數

日志發送成功后的回調函數為CustomerAppender.customCallback() ，該回調函數會返回日志上傳的結果，如果想配置其他格式的回調方法，或者使用Logger打印，可以自定義修改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;
}

使用示例

項目中提供了一個名為 cn.ctyun.example.LogbackAppenderExample的實例，它會加載resources目錄下的 logback.xml文件進行logback配置。

logback.xml樣例說明

• 配置了兩個appender：AppenderCustomer、STDOUT。
• AppenderCustomer：將日志輸出到云日志服務中，只上傳INFO WARN、ERROR等級別的日志。
• STDOUT：將日志輸出到控制臺。由于沒有對日志級別進行過濾，會輸出root中配置的日志級（默認INFO）及以上的所有日志。

如果只想要上傳WARN級別以上的日志，可以將AppenderCustomer日志級別設置為WARN即可。

        <!-- 打印WARN,ERROR級別的日志,過濾掉warn 級別以下的日志 -->
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>WARN</level>    <!--INFO 改為 WARN-->
        </filter>

常見問題

Q：為何在Spring Boot 啟動異常退出？

A：將logback.xml 改成 logback-spring.xml

Q：如何關閉某些類輸出的日志？

A：通過在 logback.xml 文件中添加 <logger name="packname" level="OFF"/> 可屏蔽相應包下日志的輸出。
例如，當您在 logback.xml 文件中添加如下內容會屏蔽 package 名為 cn.ctyun.appender 下所有類的日志輸出。

<logger name="cn.ctyun.appender" level="OFF"/>

Q：應用初始化時出現這樣的信息 A number (N) of logging calls during the initialization phase have been intercepted and are now being replayed. These are subject to the filtering rules of the underlying logging system.

A：該信息只會在日志系統初始化階段產生，并不影響后續日志記錄的功能。

當應用首次調用 LoggerFactory.getLogger()方法時，日志系統進入初始化流程。初始化流程還未結束，再次調用 LoggerFactory.getLogger()方法便會出現上述信息。這時，slf4j 會創建替代記錄器（substitute loggers）并返回。在完成初始化后，替代記錄器（substitute loggers）會將日志記錄請求委托給合適的 logger。