# zero-observer

**Repository Path**: xiaohua_gitee/zero-observer

## Basic Information

- **Project Name**: zero-observer
- **Description**: 一个开箱即用的一站式 Java 应用日志观测工具，无需各种复杂繁琐的配置，使用门槛低。
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 8
- **Created**: 2025-07-18
- **Last Updated**: 2025-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

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

zero-observer 依托于 [zero-log](https://gitee.com/kuafucv/zero-log) 的自动化日志采集插件，实现接收 Java 应用上报的日志数据，并提供开箱即用的日志可视化检索功能，极大降低了 Java 应用日志可视化检索的门槛。

# 软件架构
![img.png](images/img.png)

# 版本升级指南
请异步至 >>> [版本升级记录](VERSIONS.md) <<<

# 快速接入
## 安装教程
> zero-observer 数据存储使用的是 mysql 与 elasticsearch，mysql 存储的是系统数据，elasticsearch 存储的是日志数据。
> 所以需要自行安装 mysql 与 elasticsearch。

### Mysql 初始化脚本
创建数据库：zero_observer，执行下面建表语句。
```mysql
CREATE TABLE `app_log_growth_trend` (
  `id` bigint(20) NOT NULL,
  `create_time` datetime NOT NULL,
  `app` varchar(255) NOT NULL,
  `env` varchar(50) NOT NULL,
  `level` varchar(10) NOT NULL,
  `statistic_time` datetime NOT NULL,
  `log_count` int(11) NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `app_log_total_growth_trend` (
  `id` bigint(20) NOT NULL,
  `create_time` datetime NOT NULL,
  `statistic_time` datetime NOT NULL,
  `log_count` bigint(20) NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `app_env_instance` (
    `id` bigint(20) NOT NULL,
    `create_time` datetime NOT NULL,
    `app` varchar(255) NOT NULL,
    `env` varchar(50) NOT NULL,
    `ip` varchar(50) NOT NULL,
    `port` varchar(5) NOT NULL,
    `hostname` varchar(255) NOT NULL,
    PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### Docker 部署
```shell
# 拉取镜像
docker pull registry.cn-hangzhou.aliyuncs.com/kuafucv/zero-observer:0.0.3
# 启动容器
docker run -itd -p 8080:8080 --name zero-observer \
 -e TZ=Asia/Shanghai
 -e ES_IP=127.0.0.1 \
 -e ES_PORT=9200 \
 -e ES_USERNAME=es \
 -e ES_PASSWORD=es \
 -e MYSQL_IP=127.0.0.1 \
 -e MYSQL_PORT=3306 \
 -e MYSQL_USERNAME=root \
 -e MYSQL_PASSWORD=123456 \
 registry.cn-hangzhou.aliyuncs.com/kuafucv/zero-observer:0.0.3
```
> 参数解析：
> - TZ：时区，默认 Asia/Shanghai
> - ES_IP：elasticsearch 的 ip
> - ES_PORT：elasticsearch restapi 的端口
> - ES_USERNAME：elasticsearch 用户名，无则不填即可
> - ES_PASSWORD：elasticsearch 密码，无则不填即可
> - MYSQL_IP：mysql 的ip
> - MYSQL_PORT：mysql 端口
> - MYSQL_USERNAME 用户名
> - MYSQL_PASSWORD 密码

### Jar 包部署
下载 zero-observer.jar 与 start 启动器。
> 默认 server.port=9999

- linux 系统执行如下命令
```shell
./start java -jar zero-observer.jar 
```
- windows 系统双击 start.exe

启动成功后，浏览器访问：http://127.0.0.1:9999/zero-observer/
> 0.0.3 版本以前，访问路径是 http://ip:port 直接访问的，有小伙伴反馈自己公司的项目环境只能暴露一个端口出去，所以需要有 context-path 做代理配置.
> 故而从 0.0.4 版本及以后，访问路径统一改为 http://ip:port/zero-observer/，有需要的小伙伴通过 zero-observer 进行代理配置。
> 
> 如果有同学还是想要通过 http://ip:port 或者域名直接访问，不想后面再跟上 context-path 的，也可以通过 Nginx 进行一层代理。

## Java 应用日志接入
Java 应用引入 [zero-log](https://gitee.com/kuafucv/zero-log) 即可。
### 1. 引入 maven 依赖
```xml
<dependency>
    <groupId>io.github.kuafucv</groupId>
    <artifactId>zero-log</artifactId>
    <version>0.0.7</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 方式提交参数 -->
        <!-- Ip 和 端口替换为 zero-observer 部署的 ip 和端口 -->
        <endpointUrl>http://ip:port/log/report}</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. 日志观测
启动 Java 服务，等待日志自动上报至 zero-observer 即可。

## 系统功能
### 仪表盘
![img_1.png](images/img_1.png)
### 应用日志
![img_2.png](images/img_2.png)
### 应用控制台日志
![img_3.png](images/img_3.png)
### 应用日志查询
![img_4.png](images/img_4.png)
### 应用日志详情
![img_5.png](images/img_5.png)

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

如果你觉得 zero-observer 对你有帮助，请帮忙点个 star + fork。
如有使用问题或者建议，欢迎联系我，备注[zero-log]。

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

你的赞助是我坚持的最佳动力❤️❤️❤️。