本文介绍如何通过日志服务 Logback Appender 上传日志到日志服务。

背景信息

Logback 是由 Log4j 创始人所设计的一款开源日志组件。 借助 Logback，您可以控制日志信息输送的目的端，包括控制台、文件、GUI组件、套接口服务器、NT 的事件记录器、UNIX Syslog 守护进程等；您可以控制每一条日志的输出格式；您还可以定义每一条日志信息的级别，更加细致地控制日志的生成过程。您只需通过一个配置文件即可实现上述功能，无需修改应用的代码。
火山引擎日志服务 TLS Logback Appender 是一个基于 Logback 框架的 Appender，用于将日志上传到火山引擎日志服务中。上传的日志样式如下：

level: ERROR
location: com.volcengine.service.tls.logback.example.LogbackAppenderExample.main(LogbackAppenderExample.java:18)
message: this is an error log
throwable: java.lang.RuntimeException: xxx
thread: main
time: 2023-10-24T12:00+0000
log: 2023-10-24 12:00:00,000 ERROR [main] com.volcengine.service.tls.logback.example.LogbackAppenderExample: this is an error log
__source__: 192.168.1.100
__path__: sys.log

功能优势

• 日志不落盘：产生的日志通过网络发给服务端。
• 零代码改造成本：只需通过 XML 文件简单配置即可上报日志到日志服务。
• 高性能：基于日志服务 Java SDK Producer，具有异步发送、高性能、失败重试等特性，适用于高并发场景。

使用说明

1 在 Maven 工程中添加依赖

参考如下示例，在 Maven 工程中添加依赖。

<dependency>
    <groupId>com.volcengine</groupId>
    <artifactId>ve-tls-logback-appender</artifactId>
    <version>1.0.0</version>
</dependency>

2 修改配置文件

您可以参考如下示例在 logback.xml 文件中定义日志服务 Logback Appender，即在文件中绑定 com.volcengine.service.tls.logback.LogbackAppender 类。
如下示例代码注册了两个 Logback Appender，一个用于将日志输出到控制台，另一个用于将日志上报到日志服务。详细代码，请参考logback-example.xml。
示例代码中详细标注了日志服务 Logback Appender 必填和选填参数。其中，关于 TLS Java Producer 的自定义配置，请参考 LOG Java Producer。

<configuration>
    <!--为了防止进程退出时，内存中的数据丢失，请加上此选项-->
    <shutdownHook class="ch.qos.logback.core.hook.DelayingShutdownHook"/>

    <!-- 配置日志输出目的地为TLS日志服务的appender -->
    <appender name="TLSLogbackAppender" class="com.volcengine.service.tls.logback.LogbackAppender">
        <!-- 必选项：TLS日志服务基本配置 -->
        <endpoint></endpoint>
        <region></region>
        <accessKeyId></accessKeyId>
        <accessKeySecret></accessKeySecret>
        <!-- 必选项：TLS日志项目/主题配置 -->
        <projectID></projectID>
        <topicID></topicID>
        <!-- 可选项：日志数据源配置 -->
        <source></source>
        <filename></filename>

        <!-- 可选项：TLS Java Producer自定义配置 -->
        <totalSizeInBytes>104857600</totalSizeInBytes>
        <maxThreadCount>50</maxThreadCount>
        <maxBlockMs>60000</maxBlockMs>
        <maxBatchSizeBytes>524288</maxBatchSizeBytes>
        <maxBatchCount>4096</maxBatchCount>
        <lingerMs>2000</lingerMs>
        <retryCount>2</retryCount>
        <maxReservedAttempts>3</maxReservedAttempts>

        <!-- 可选项：通过配置encoder pattern自定义日志格式 -->
        <encoder>
            <pattern>%d %-5level [%thread] %logger{0}: %msg</pattern>
        </encoder>

        <!-- 可选项：设置时间格式 -->
        <timeFormat>yyyy-MM-dd'T'HH:mmZ</timeFormat>
        <!-- 可选项：设置时区 -->
        <timeZone>Asia/Shanghai</timeZone>

        <!-- 可选项：配置LevelFilter -->
        <filter class="ch.qos.logback.classic.filter.LevelFilter">
            <level>INFO</level>
            <onMatch>ACCEPT</onMatch>
            <onMismatch>DENY</onMismatch>
        </filter>
        <!-- 可选项：配置mdcFields -->
        <mdcFields>THREAD_ID,MDC_KEY</mdcFields>
    </appender>

    <!-- 配置日志输出目的地为Stdout的appender -->
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger - %msg %X{THREAD_ID} %n</pattern>
        </encoder>
    </appender>

    <!-- 可用来获取StatusManager中的状态 -->
    <statusListener class="ch.qos.logback.core.status.OnConsoleStatusListener"/>
    <!-- 解决debug模式下循环发送的问题 -->
    <logger name="org.apache.http.impl.conn.Wire" level="WARN" />

    <root>
        <level value="DEBUG"/>
        <appender-ref ref="TLSLogbackAppender"/>
        <appender-ref ref="STDOUT"/>
    </root>
</configuration>

3 使用原有 Logback 日志输出代码上报日志

LogbackAppenderExample 中的示例代码展示了通过 Logback 输出日志的基本配置。 当您实例化 Logger 对象后，通过 trace/debug/info/warn/error 方法即可将日志输出到您在 logback.xml 文件中所配置的目的端。

package com.volcengine.service.tls.logback.example;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.slf4j.MDC;

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

    public static void main(String[] args) {
        MDC.put("MDC_KEY","MDC_VALUE");
        MDC.put("THREAD_ID", String.valueOf(Thread.currentThread().getId()));

        LOGGER.trace("This is a trace log.");
        LOGGER.debug("This is a debug log.");
        LOGGER.info("This is a info log.");
        LOGGER.warn("This is a warn log.");
        LOGGER.error("This is an error log.");
    }
}