# apm

**Repository Path**: willdas/apm

## Basic Information

- **Project Name**: apm
- **Description**: 轻量级分布式链路追踪与 APM 系统（含 AI 日志分析），采用 Java Agent + gRPC 上报 + Web UI 的整体架构，对标 SkyWalking 简化实现。
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-10
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# APM

轻量级分布式链路追踪与 APM 系统（含 AI 日志分析），采用 Java Agent + gRPC 上报 + Web UI 的整体架构，对标 SkyWalking 简化实现。

## 特性

- **链路追踪**：Java Agent 通过 ByteBuddy 无侵入埋点，采集 ENTRY / EXIT / LOCAL 三类 Span，支持跨服务传播（`X-APM-TraceId` / `X-APM-SpanId` / `X-APM-Service`）
- **服务拓扑**：基于 ExitSpan 的 `peer` 与服务端 Entry 关联自动推导拓扑关系，ECharts 力导向图可视化展示节点与调用关系、CPM/延迟/错误率
- **日志采集**：log4j2 插件将日志按 TraceId 关联上报，支持级别过滤查询
- **存储可插拔**：H2（默认，内嵌零配置）与 MySQL 双实现，通过配置一键切换
- **内置 Web UI**：Vue 3 + ant-design-vue + ECharts，Trace 查询/详情、拓扑图、日志查询
- **AI 日志分析**：异常日志自动聚合分析（详见 `Java日志AI分析_调研与APM规划.md`）

## 架构

```
┌─────────────────────────────────────────────────────────┐
│                        业务应用                           │
│  ┌──────────────────────────────────────────────────┐   │
│  │  apm-agent-all（-javaagent 挂载）                 │   │
│  │  │ springmvc / service / jdbc / beetlsql / log4j2 │   │
│  │  └───────────┬──────────────────────────────────┘   │
└─────────┬───────────────┬───────────────────────────────┘
          │ gRPC 5299     │ 上报（批量，默认 2s）
          ▼               ▼
┌─────────────────────────────────────────────────────────┐
│                     apm-server                           │
│  TraceReceiver  LogReceiver          TopologyAnalyzer    │
│      │               │                     │             │
│      ▼               ▼                     ▼             │
│  TraceStorage ◄─── LogStorage ◄──── 拓扑查询              │
│   (H2 / MySQL 可切换)                                  │
│      │                                                  │
│      ▼                                                  │
│  REST API :52599（/api/traces /api/topology /api/logs） │
│  Web UI（Vue 3，静态资源内嵌）                            │
└─────────────────────────────────────────────────────────┘
```

## 模块结构

| 模块 | 说明 |
| --- | --- |
| `apm-protocol` | Protobuf 协议定义（trace / log / metric） |
| `apm-common` | 公共模型与常量：Span、TraceContext、DTO（含 Topology/Node/Edge） |
| `apm-agent/apm-agent-core` | Agent 启动引导、ByteBuddy 插桩、gRPC 上报、配置加载 |
| `apm-agent/apm-agent-plugins` | 插件：`plugin-springmvc`、`plugin-service`、`plugin-jdbc`、`plugin-beetlsql`、`plugin-log4j2` |
| `apm-agent/apm-agent-all` | Agent 聚合产物（shade 打包，含 ByteBuddy/gRPC 等依赖） |
| `apm-server/apm-server-core` | Spring Boot 服务：接收器、分析器、REST API、Web UI 静态资源 |
| `apm-server/apm-server-storage` | 存储 SPI 及 H2 / MySQL 实现 |
| `apm-server/apm-server-ui` | 前端源码（Vue 3 + Vite + ECharts），构建产物拷入 server-core 静态目录 |
| `apm-all-in-one` | 单体可执行 jar（内嵌 H2 + gRPC + 静态 UI），开发模式一键启动 |
| `demo-app` | 示例应用（Spring Boot + H2 + BeetlSQL），用于演示埋点与链路 |

## 快速开始

### 1. 构建

要求：JDK 8、Maven 3.6+。

```bash
mvn clean package -DskipTests
```

产物：
- Agent：`apm-agent/apm-agent-all/target/apm-agent-all-1.0.0-SNAPSHOT.jar`
- 服务端：`apm-all-in-one/target/apm-all-in-one-1.0.0-SNAPSHOT.jar`

### 2. 启动服务端（默认 H2，零配置）

```bash
java -jar apm-all-in-one/target/apm-all-in-one-1.0.0-SNAPSHOT.jar
```

- gRPC 接收端口：`5299`
- Web 端口：`52599`，浏览器打开 http://localhost:52599
- H2 控制台：http://localhost:52599/h2-console

### 3. 启动示例应用（挂载 Agent）

```bash
java -javaagent:apm-agent/apm-agent-all/target/apm-agent-all-1.0.0-SNAPSHOT.jar \
     -Dapm.agent.service.name=demo-app \
     -Dapm.agent.reporter.grpc-endpoint=localhost:5299 \
     -jar demo-app/target/demo-app-1.0.0.jar
```

访问 `http://localhost:8080/api/orders/1001` 产生调用链，然后在 UI 中查看 Trace 与拓扑图。

## Agent 配置

配置优先级：**JVM `-D` 参数 > `apm-config.properties` 文件 > 默认值**。配置文件需位于应用的 classpath 下。

| 配置项 | 默认值 | 说明 |
| --- | --- | --- |
| `apm.agent.service.name` | `unknown-service` | 服务名 |
| `apm.backend_url` | `localhost:5299` | 服务端地址（别名 `apm.agent.server.address`） |
| `apm.sample_rate` | `1.0` | 采样率（0~1） |
| `apm.max_span_count` | `300` | 单 Trace 最大 Span 数 |
| `apm.report_batch_size` | `50` | 批量上报条数 |
| `apm.report_interval_ms` | `2000` | 上报间隔（毫秒） |
| `apm.ignore_suffix` | `.jpg,.css,.js,.png,.gif,.ico` | 忽略的请求后缀 |
| `apm.plugins_disabled` | （空） | 禁用的插件，逗号分隔（如 `springmvc,service`） |
| `apm.agent.scan.packages` | （空） | ServicePlugin 扫描的业务包前缀（逗号分隔） |

示例 `apm-config.properties`：

```properties
apm.service_name=demo-app
apm.backend_url=localhost:5299
apm.report_batch_size=10
apm.report_interval_ms=1000
```

## 插件列表

| 插件 | 拦截目标 | 采集内容 |
| --- | --- | --- |
| `springmvc` | `DispatcherServlet#doDispatch` | HTTP 入口 Span（ENTRY） |
| `service` | `@Service` / `@Controller` 方法（按 `apm.agent.scan.packages`） | 本地方法 Span（LOCAL） |
| `jdbc` | JDBC `Driver#connect`、`Connection#prepareStatement` 执行 | 数据库 Span（EXIT），自动解析 JDBC URL 得到真实 peer（mysql/postgresql/oracle/sqlserver/h2/sqlite），打 `db.type` / `db.peer` tag |
| `beetlsql` | BeetlSQL 拦截器 | SQL 执行上下文 |
| `log4j2` | log4j2 日志事件 | 日志上报并与当前 TraceId 关联 |

## REST API

| 接口 | 说明 |
| --- | --- |
| `GET /api/traces?service=&start=&end=&traceId=&endpoint=&status=error\|ok&minDuration=&maxDuration=&sort=startTime\|duration&order=desc\|asc&limit=20&offset=0` | Trace 列表（多条件过滤） |
| `GET /api/traces/{traceId}` | 单条 Trace 详情（含全部 Span） |
| `GET /api/topology?duration=3600000` | 服务拓扑（`duration` 时间窗口，毫秒，默认 1 小时） |
| `GET /api/logs?start=&end=&level=&traceId=&limit=100&offset=0` | 日志查询 |

## 存储切换

默认使用内嵌 H2，零配置可直接运行。切换 MySQL：修改 `apm-server/apm-server-core/src/main/resources/application.yml`：

```yaml
apm:
  storage:
    type: mysql        # h2 | mysql
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/apm?useSSL=false&allowPublicKeyRetrieval=true&serverTimezone=Asia/Shanghai
    driver-class-name: com.mysql.cj.jdbc.Driver
    username: root
    password: your-password
```

## 前端开发

```bash
cd apm-server/apm-server-ui
npm install
npm run dev      # 开发模式，Vite 代理 API 到 :52599
npm run build    # 构建产物拷贝至 apm-server-core/src/main/resources/static
```

## 技术栈

- Java 8、Maven 多模块
- Spring Boot 2.7.18、gRPC 1.58、Protobuf 3.24
- ByteBuddy 1.10（Agent 无侵入插桩）
- H2 / MySQL 8.0
- Vue 3、ant-design-vue、ECharts 5、Vite