# zero-log

**Repository Path**: lucky_cube/zero-log

## Basic Information

- **Project Name**: zero-log
- **Description**: zero-log 旨在提供低门槛、轻量级、无侵入式的方式实现日志的采集与发送。
- **Primary Language**: Java
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 5
- **Created**: 2025-07-07
- **Last Updated**: 2025-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# zero-log
Java 应用开发时，服务器上的日志往往是以日志文件的形式存在。在日常维护时，通常需要将日志信息实现可视化查询。ELK、EFK 等是优秀的日志可视化查询解决方案。不过对于部分开发者来说，日志的采集配置是一个比较繁琐的过程。
为此我们希望通过一些低门槛的方式，实现日志的自动采集，无需复杂的规则配置就能将日志采集发送到远端服务器上。

zero-log 旨在提供低门槛、轻量级、无侵入式的方式实现日志的采集与发送。springboot 内置使用的是 logback，所以，zero-log 基于 logback 实现将代码中通过 log.error、log.warn、log.info、log.trace 等方式输出的日志自动采集并发送到远程服务器上。
业务代码的日志输出方式无需任何改动，只需要引入 zero-log 的依赖，同时在 logback-spring.xml 中添加 HttpBatchAppender，配置日志数据接收的接口即可实现日志的自动采集与传输。

## 使用说明
### 1. 引入 maven 依赖
```xml
<dependency>
    <groupId>io.github.kuafucv</groupId>
    <artifactId>zero-log</artifactId>
    <version>0.0.6</version>
</dependency>
```
### 2. 配置 logback-spring.xml
```xml
<configuration debug="false">
    
    <springProperty name="app_name" source="spring.application.name"/>
    <springProperty name="env" source="spring.profiles.active"/>
    <springProperty name="port" source="server.port"/>

    <conversionRule conversionWord="clr" converterClass="org.springframework.boot.logging.logback.ColorConverter" />
    <conversionRule conversionWord="wex" converterClass="org.springframework.boot.logging.logback.WhitespaceThrowableProxyConverter" />
    <conversionRule conversionWord="wEx" converterClass="org.springframework.boot.logging.logback.ExtendedWhitespaceThrowableProxyConverter" />

    <property name="FILE_LOG_PATTERN" value="${FILE_LOG_PATTERN:-[%X{TRACE_ID}] %d{${LOG_DATEFORMAT_PATTERN:-yyyy-MM-dd HH:mm:ss.SSS}} ${LOG_LEVEL_PATTERN:-%5p} ${PID:- } --- [%15.15t] %-40.40logger{39} : %m%n${LOG_EXCEPTION_CONVERSION_WORD:-%wEx}}"/>
    <property name="FILE_LOG_CHARSET" value="${FILE_LOG_CHARSET:-${file.encoding:-UTF-8}}"/>

    <appender name="BATCH_HTTP" class="io.github.kuafucv.zero.log.HttpBatchAppender">
        <!-- 必需：参照 logback 的 encoder 配置 -->
        <encoder>
            <pattern>${FILE_LOG_PATTERN}</pattern>
            <charset>${FILE_LOG_CHARSET}</charset>
        </encoder>
        <!--请求的地址-->
        <!-- 必需：日志接收接口URL，接口必须是 POST 方法，application/json 方式提交参数 -->
        <endpointUrl>${endpointUrl}</endpointUrl>
        <!-- 可选：是否包含MDC上下文 -->
        <includeMDC>true</includeMDC>
        <!-- 必填：应用名称 -->
        <appName>${app_name}</appName>
        <!-- 可选：环境，默认值：env -->
        <env>${env}</env>
        <!-- 可选：服务端口，默认值：0 -->
        <appServerPort>${port}</appServerPort>
        <!-- 可选：日志传输频率，单位秒，默认值：3 秒 -->
        <flushIntervalInSeconds>3</flushIntervalInSeconds>
        <!-- 可选：请求超时时间，默认值：1000 毫秒 -->
        <httpReadTimeoutInMillis>1000</httpReadTimeoutInMillis>
        <!-- 可选：请求超时时间，默认值：1000 毫秒 -->
        <httpConnectionTimeoutInMillis>1000</httpConnectionTimeoutInMillis>
        <!-- 可选：日志存储滚筒最大数量，默认值：8 -->
        <maxNumberOfBuckets>8</maxNumberOfBuckets>
        <!-- 可选：每个日志存储滚筒大小（KB），默认值：1024 -->
        <maxBucketSizeInKilobytes>1024</maxBucketSizeInKilobytes>
    </appender>

    <!-- 日志输出级别 -->
    <root level="INFO">
        <appender-ref ref="BATCH_HTTP" />
    </root>
</configuration>
```
### 3. 日志数据格式

```json
{
  "hostname":"hostname",
  "ip":"ip",
  "port": 0,
  "patternLog": "通过 encode 转换后的日志格式，通常 encode 的 pattern 配置与 日志文件的 patter 一致",
  "timestamp": "日志输出的时间戳，毫秒",
  "level": "level",
  "pid": "线程id",
  "thread": "线程名称",
  "logger": "logger",
  "message": "message",
  "mdc": {},
  "exception": {
    "className":"",
    "message": "",
    "stackTrace": []
  }
}
```
### 4. endpointUrl
endpointUrl 是远端接口日志信息的接口地址，http 协议，post 方法。
可以对接自研日志中心，也可以使用猿观测平台 [zero-observer](https://gitee.com/kuafucv/zero-observer) 进行对接

## 联系我们 
![img1.png](images/img1.png)

## 赞助支持
![1191831750864963_.pic.jpg](images/1191831750864963_.pic.jpg)
![1191821750864960_.pic.jpg](images/1191821750864960_.pic.jpg)