# access_agent

**Repository Path**: gilbertwang/access_agent

## Basic Information

- **Project Name**: access_agent
- **Description**: 实时解析行文本文件，利用inotify和IO多路复用技术，提取字段信息，可以通过自定义的connector发送到服务端，最多同时支持32个connector，自定义connector以so动态连接库的形式提供，支持多文件/目录监控，采样，字段内容过滤等功能。详细介绍：https://blog.csdn.net/tq02h2a/article/details/103394791
- **Primary Language**: C
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2021-12-27
- **Last Updated**: 2026-06-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# access_agent

`access_agent` 是一个基于 Linux `inotify` 机制的轻量级文件访问日志实时监控与分析 Agent，采用 C 语言编写。它能够实时监控指定日志文件的变化，按配置提取关键字段，经过过滤和采样后，通过可插拔的 Connector 将数据输出到不同的目标端（如标准输出、UDP 等）。

## 特性

- **实时文件监控**：基于 Linux `inotify` 机制，使用 `select` I/O 多路复用监听多个文件的变化事件（修改、创建、删除、移动）。
- **灵活字段提取**：通过配置文件指定分隔符、字段位置及长度，从日志行中精准提取所需字段。
- **内容过滤**：支持按字段值进行精确匹配过滤，仅上报满足条件的数据。
- **采样控制**：支持配置采样率（如 5%），降低数据上报量。
- **可插拔 Connector**：Connector 以动态链接库（`.so`）形式提供，最多可同时加载 32 个，便于扩展不同的输出目标。
- **守护进程模式**：支持以前台或守护进程方式运行。
- **偏移量续读**：默认从文件末尾开始读取，也支持从头读取；文件被移动后会重置偏移量。

## 项目结构

```
access_agent/
├── config/
│   └── fs_monitor.cfg          # 示例配置文件
├── src/
│   ├── framework/               # 核心框架
│   │   ├── main.c               # 程序入口
│   │   ├── fs_monitor.c         # inotify 事件循环与 select 多路复用
│   │   ├── fs_monitor_callback.c # 文件变化回调：读取、解析、过滤、推送
│   │   ├── fs_file_analysis.c   # 文件操作与日志行解析
│   │   ├── fs_monitor_worker.c  # Worker 创建与 inotify 绑定
│   │   ├── fs_monitor_worker_pool.c # Worker 池管理与 Connector 动态加载
│   │   ├── fs_monitor_cfg.c     # 配置文件解析
│   │   ├── fs_monitor_sys_cfg.c # 系统配置转换
│   │   ├── fs_monitor_dir_file_cfg.c  # 目录文件配置
│   │   ├── fs_monitor_field_cfg.c     # 字段配置
│   │   ├── fs_monitor_filter_cfg.c    # 过滤配置
│   │   ├── fs_monitor_connector_cfg.c # Connector 配置
│   │   └── ...
│   ├── connector/               # 输出连接器（动态库）
│   │   ├── stdout_connector/    # 标准输出 Connector
│   │   │   ├── stdout_connector.c
│   │   │   └── Makefile
│   │   └── udp_connector/       # UDP Connector
│   │       ├── udp_connector.c
│   │       └── Makefile
│   └── Makefile
└── README.md
```

## 编译构建

确保系统已安装 `gcc` 和 `make`，然后在项目根目录执行：

```bash
cd src
make
```

编译完成后：
- 核心可执行文件：`src/framework/access_agent`
- stdout Connector：`src/connector/stdout_connector/stdout_connector.so`
- UDP Connector：`src/connector/udp_connector/udp_connector.so`

清理构建产物：

```bash
cd src
make clean
```

## 使用方式

```bash
./access_agent <配置文件路径>
```

示例：

```bash
./access_agent /root/access_agent/config/fs_monitor.cfg
```

## 配置文件说明

配置文件采用分段式键值对格式，参考 `config/fs_monitor.cfg`：

### 1. 监听目录与文件（`dir_file`，数组类型）

可配置多组目录和文件，Agent 会监控目录并追踪对应文件的变化。

```ini
[dir_file,array]
dir[0]=/root/test
file[0]=/root/test/access_log.txt

dir[1]=/root/test
file[1]=/root/test/access_log.txt.1
```

### 2. 字段提取（`field`）

格式：`字段名=字段位置(从0开始):字段大小(字节)`

```ini
[field]
client_ip=12:16
host=13:32
method=16:8
resp_time=21:8
time=23:32
url=28:64
```

### 3. 系统配置（`system`）

```ini
[system]
# 文本分隔符，0x09 表示制表符(Tab)
separator=0x09
# 是否以守护进程方式启动：true / false
is_daemon=false
# 是否从文件开头开始读取：true / false（默认从末尾开始）
is_from_begin=false
# 采样率，如 5 代表 5%
sampling_rate=5
```

### 4. 字段过滤（`filter`）

精确匹配过滤：仅当字段值与配置值一致时才会上报。不配则表示不过滤。

```ini
[filter]
url=/customLayout/home/top
```

### 5. 连接器配置（`connectors`，数组类型）

指定要加载的 Connector 动态库路径，最多支持 32 个。

```ini
[connectors,array]
connector_so_path[0]=/root/access_agent/src/connector/stdout_connector/stdout_connector.so
connector_so_path[1]=/root/access_agent/src/connector/udp_connector/udp_connector.so
```

## Connector 开发

如需自定义输出目标，可参照 `stdout_connector` 或 `udp_connector` 实现：

1. 实现以下接口函数：

```c
int connnect_to_source(char * snd_buffer, int buffer_size, char * logbuffer);
```

- `snd_buffer`：按字段配置拼接的二进制数据缓冲区
- `buffer_size`：`snd_buffer` 的有效长度
- `logbuffer`：以 `|` 分隔的明文日志字符串，便于调试或输出

2. 编写 `Makefile`，编译为共享库（`.so`）。

3. 将 `.so` 路径添加到配置文件的 `[connectors,array]` 段中即可。

## 注意事项

- 本工具仅适用于 Linux 系统，依赖内核的 `inotify` 支持。
- 确保 Agent 对监控目录和文件具有足够的读取权限。
- UDP Connector 默认向 `127.0.0.1:10012` 发送数据，如需修改目标地址，请编辑 `udp_connector.c` 并重新编译。
- 日志输出通过宏 `INFO_LOG` / `ERROR_LOG` 打印到标准输出，可在 `fs_monitor_log.h` 中查看或调整。

## 作者

- **Author**: gilbert
- **Created**: Nov 2019