# logmon

**Repository Path**: lambdang/logmon

## Basic Information

- **Project Name**: logmon
- **Description**: 简洁日志采集工具，采集json日志，发送给openobser，同时采集目前程序的/debug/vars go 运行时指标，解析转发到openobserve。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-14
- **Last Updated**: 2026-06-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# logmon

轻量级日志和指标采集转发工具，专为 OpenObserve 设计。

## 功能特性

### 1. 日志采集转发

- **实时采集**：监控指定日志文件，实时读取新日志
- **直接转发**：日志不落地、不缓存，直接发送到 OpenObserve
- **高稳定性**：牺牲日志完整性换取系统稳定性和简单性
- **适用场景**：适合对日志完整性要求不高的监控场景

### 2. Go 运行时指标采集

- **简单采集**：直接通过 `/debug/vars` 接口获取指标
- **无需 OTel**：不依赖 OpenTelemetry，降低学习成本和系统复杂度
- **日志方式发送**：将指标数据作为日志发送到 OpenObserve 的日志系统
- **定时采集**：按照配置周期采集

### 3. 自定义 KV 指标解析

- **灵活配置**：通过 YAML 配置文件自定义解析 expvar 中的任意字段
- **多类型支持**：支持 int、int64、uint、uint64、float64、string、bool 等数据类型
- **多 kind 支持**：支持配置多个不同类型的自定义指标

### 4. 配置管理 API

- **配置查询**：通过 API 获取当前运行配置
- **动态更新**：支持运行时动态修改配置参数
- **原子操作**：配置更新使用 atomic 变量，线程安全

## 设计理念

> **日志设计哲学**：在大多数场景下，日志丢失率极低，且日志采集的核心价值在于监控和问题排查。我们选择牺牲极少的日志完整性，换取系统的极大简化和稳定性提升。

> **指标设计哲学**：指标采集不必复杂。OTel 和 Prometheus 虽然强大，但学习成本高、引入复杂、增加内存占用。对于大多数服务监控场景，通过 `expvar` 暴露的 Go 运行时指标（如 GC 次数、内存分配等）已经足够。将指标作为日志发送到 OpenObserve，即可实现数据可视化。当发现异常时，再使用 pprof 进行深入调试。

> **核心价值**：以最小的复杂度实现有效的服务监控。

### 方案对比

| 维度 | 传统方案（OTel/Prometheus） | logmon 方案 |
|------|----------------------------|-------------|
| **学习成本** | 高（需学习完整的指标体系） | 低（只需了解 expvar） |
| **系统复杂度** | 高（需部署独立服务） | 低（无额外依赖） |
| **内存占用** | 高（大量运行时组件） | 低（轻量级设计） |
| **部署难度** | 高（需配置多种组件） | 低（单二进制文件） |
| **适用场景** | 大规模分布式系统 | 中小规模服务监控 |
| **调试方式** | 内置指标分析 | expvar + pprof |

## 快速开始

### 配置文件

```yaml
# config.yaml

# 基础配置
root: "./"
user: "root"
password: "a123456"
appHost: ":8081"
appPprofHost: ":6060"

# 日志采集配置
logFile: "./cmd/tailtest/demo.log"
remoteHost: "http://localhost:5080"
remoteUser: "root@root.com"
remotePassword: "1JrgmQZxihCdzbkM"
org: "default"
logStream: "default"
logMaxSize: 10  # MB，达到此大小触发发送

# 指标采集配置（通过 /debug/vars 获取）
metricHost: "http://localhost:8886/debug/vars"
metricUser: "admin"
metricPassword: "ab12346"
metricDurationS: 5  # 采集周期（秒）

# 自定义指标配置
metricConfigs:
  - kind: logmon
    fields:
      - key: send_errnum
        type: int
      - key: send_num
        type: int
      - key: tail_errnum
        type: int
      - key: tail_num
        type: int

# 应用日志配置
appLog:
  logName: ./log/monapp.log
  outType: all
  formatter: json
  level: debug
```

### 运行

```bash
go run main.go -f ./config.yaml -e ./.env
```

## 技术特点

| 特性 | 说明 |
|------|------|
| 无缓存 | 日志不落地，内存占用低 |
| 异步发送 | 日志采集和发送解耦 |
| 连接池 | 使用 fasthttp 连接池复用 |
| 优雅退出 | 支持 context 优雅关闭 |
| **无 OTel** | 指标通过 HTTP 获取，无需 OTel |
| **sync.Pool** | 复用对象，减少内存分配 |
| **atomic 变量** | 配置更新线程安全 |

## API 接口

### 1. 查询配置

**GET** `/manage/info`

响应示例：
```json
{
  "logMaxSize": 10,
  "metricDurationS": 5,
  "appLogLevel": "debug"
}
```

### 2. 更新配置

**PUT** `/manage/config`

请求示例：
```json
{
  "cmd": "setLogMaxSize",
  "value": 20
}
```

支持的命令：
| 命令 | 说明 | 值类型 |
|------|------|--------|
| `setLogMaxSize` | 设置采集日志大小（MB） | int |
| `setMetricDurationS` | 设置指标采集间隔（秒） | int |
| `setAppLogLevel` | 设置日志级别 | string（debug/info/warn/error） |

响应示例：
```json
{
  "success": true,
  "message": "config updated successfully",
  "data": 20
}
```

## 指标说明

### 采集的 Go 运行时指标

通过 `/debug/vars` 接口获取以下指标，以日志形式发送：

| 指标 | 说明 |
|------|------|
| `kind` | 指标类型标识（固定为 `go_runtime`） |
| `timestamp` | 采集时间戳 |
| `start_time` | 程序启动时间 |
| `go_goroutines` | 当前 Goroutine 数量 |
| `go_threads` | 当前线程数量 |
| `go_memstats_alloc_bytes` | 当前堆内存占用 |
| `go_memstats_total_alloc_bytes` | 累计堆内存分配总量 |
| `go_memstats_sys_bytes` | 程序从 OS 申请的总内存 |
| `go_memstats_heap_objects` | 当前堆对象数量 |
| `go_memstats_heap_inuse_bytes` | 正在使用的堆内存 |
| `go_memstats_stack_inuse_bytes` | 栈内存使用 |
| `go_memstats_num_gc` | GC 总次数 |
| `go_memstats_pause_total_ns` | GC 暂停总时间 |
| `go_memstats_gc_cpu_fraction` | GC 占用 CPU 比例 |
| `go_memstats_next_gc_bytes` | 下一个 GC 阈值 |

### 自定义 KV 指标

#### 配置方式

```yaml
metricConfigs:
  - kind: logmon
    fields:
      - key: send_errnum
        type: int
      - key: send_num
        type: int
```

#### 配置说明

| 配置项 | 说明 |
|--------|------|
| `kind` | 指标类型标识 |
| `fields` | 字段配置列表 |
| `fields[].key` | expvar JSON 中的字段名 |
| `fields[].type` | 字段数据类型 |

#### 支持的数据类型

| 类型 | 说明 |
|------|------|
| `int` | 整数 |
| `int64` | 64 位整数 |
| `uint` | 无符号整数 |
| `uint64` | 64 位无符号整数 |
| `float64` | 浮点数 |
| `string` | 字符串 |
| `bool` | 布尔值 |

#### 输出格式

```json
{
  "kind": "logmon",
  "timestamp": 1782031073,
  "send_errnum": 5,
  "send_num": 100
}
```

#### 多 kind 配置

```yaml
metricConfigs:
  - kind: log_stats
    fields:
      - key: log_send
        type: int
      - key: log_error
        type: int
  - kind: http_stats
    fields:
      - key: http_requests
        type: int
      - key: http_errors
        type: int
```

## 性能优化

- **sync.Pool**：复用字节切片和 map 对象，减少内存分配
- **fasthttp**：高性能 HTTP 客户端，比标准库更快
- **HostClient**：针对单一主机优化的连接管理
- **atomic 变量**：无锁操作，提高并发性能

## 注意事项

1. **日志完整性**：由于不缓存机制，程序异常退出时可能丢失极少量日志
2. **网络依赖**：依赖网络稳定性，网络中断期间日志会丢失
3. **指标发送方式**：指标以日志形式发送，而非专用指标系统
4. **配置更新**：动态更新的配置在程序重启后会恢复为配置文件中的值

## 许可证

MIT License