# LightTrace

**Repository Path**: Mrg_gitee/light-trace

## Basic Information

- **Project Name**: LightTrace
- **Description**: 轻量级分布式链路追踪系统
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-29
- **Last Updated**: 2026-04-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LightTrace - 轻量级分布式链路追踪系统

> 参考 TLog 设计理念，构建无侵入式 Java 链路追踪解决方案

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Java](https://img.shields.io/badge/Java-1.8%2B-green.svg)](https://www.java.com)
[![Maven](https://img.shields.io/badge/Maven-3.6%2B-orange.svg)](https://maven.apache.org)

## 🎯 项目简介

LightTrace 是一个轻量级的分布式链路追踪系统，专为 Java 微服务架构设计。基于 **ByteBuddy 字节码增强** 技术，实现**无侵入式**埋点，对业务代码零修改。

### 核心特性

| 特性 | 说明 |
|------|------|
| 🚀 **无侵入** | 通过 Java Agent 自动埋点，业务代码零修改 |
| ⚡ **高性能** | overhead < 5%，单机每秒处理 10万+ Span |
| 🔌 **易扩展** | SPI 插件机制，支持自定义组件 |
| 📊 **可视化** | 完整的链路查询和拓扑展示 |
| 🏗️ **轻量级** | 部署简单，依赖少，易维护 |

## 📦 项目结构

```
light-trace/
├── lighttrace-core/              # 核心模块（共享）
│   ├── context/                  # 上下文管理
│   ├── idgen/                    # ID 生成器
│   ├── model/                    # 数据模型（Span、LogEvent）
│   ├── config/                   # 配置管理
│   └── exporter/                 # 数据导出（HTTP）
├── lighttrace-plugin-api/        # 插件 API
├── lighttrace-plugins/           # 组件插件集
│   ├── lighttrace-spring-mvc-plugin/  # Spring MVC 支持
│   ├── lighttrace-feign-plugin/       # Feign 支持
│   ├── lighttrace-mybatis-plugin/     # MyBatis 支持
│   ├── lighttrace-dubbo-plugin/       # Dubbo 支持
│   └── lighttrace-redis-plugin/       # Redis 支持
├── lighttrace-bootstrap/         # Agent 启动入口
└── lighttrace-collector/         # Collector 服务端
    ├── controller/               # REST API
    ├── service/                  # 业务逻辑
    └── resources/static/         # Dashboard 前端
```

## 🚀 快速开始

### 方式一：一键启动（推荐）

```bash
git clone https://gitee.com/Mrg_gitee/light-trace.git
cd light-trace
./quick-start.sh
```

### 方式二：手动启动

#### 1. 编译项目

```bash
# 编译 Agent
mvn clean package -DskipTests -pl lighttrace-bootstrap -am

# 编译 Collector
mvn install -DskipTests -pl lighttrace-core -am
cd lighttrace-collector && mvn clean package -DskipTests
```

#### 2. 启动 Collector

```bash
java -jar lighttrace-collector/target/lighttrace-collector-1.0.0-SNAPSHOT.jar
```

#### 3. 启动被监控应用（带 Agent）

```bash
java -javaagent:lighttrace-bootstrap/target/lighttrace-bootstrap-1.0.0-SNAPSHOT.jar \
     -Dlighttrace.serviceName=order-service \
     -Dlighttrace.collectorUrl=http://localhost:8080 \
     -jar your-application.jar
```

#### 4. 查看链路

访问 Dashboard：`http://localhost:8080`

| 功能 | 地址 |
|------|------|
| Dashboard | http://localhost:8080 |
| 健康检查 | http://localhost:8080/api/health |
| 查询链路 | http://localhost:8080/api/traces/{traceId} |
| 服务列表 | http://localhost:8080/api/services |

## 📋 核心组件

### TraceID 生成器

```java
TraceIdGenerator generator = new TraceIdGenerator(1);
String traceId = generator.generate(); // "18f4e2c8a9b0c1d2"
```

### 上下文管理

```java
// 设置上下文
SpanContext context = SpanContext.builder()
    .traceId(traceId)
    .spanId(spanId)
    .build();
TraceContext.set(context);

// 获取上下文
SpanContext ctx = TraceContext.get();

// 清理上下文（重要！）
TraceContext.clear();
```

## 📚 文档

| 文档 | 链接 |
|------|------|
| 系统设计 | [查看](https://feishu.cn/docx/T3L0d4aHOohsnGxfaF7clkAonQL) |
| 开发规范 | [查看](https://feishu.cn/docx/C9qDdrgbHoXC6pxZCtscgeRZnWe) |
| 部署运维 | [查看](https://feishu.cn/docx/HTiydyyEUoJVhMxgR1PcVKUDnAe) |
| 数据库设计 | [查看](https://feishu.cn/docx/EMSUdP5PYoq3odxUxEcciAzsnac) |

## 🛠️ 技术栈

### Agent 端

| 组件 | 技术 | 版本 |
|------|------|------|
| 字节码增强 | ByteBuddy | 1.14.x |
| JSON 处理 | FastJSON | 1.2.83_noneautotype |
| 日志框架 | SLF4J + Logback | 1.7.x |
| 插件机制 | SPI | Java 标准 |

### Collector 端

| 组件 | 技术 | 版本 |
|------|------|------|
| Web 框架 | Spring Boot | 2.7.x |
| 数据存储 | 内存（可扩展 ClickHouse）| - |
| 前端 | HTML + JavaScript | 原生 |

### 支持的组件

| 组件 | 状态 | 说明 |
|------|------|------|
| Spring MVC | ✅ | Web 请求追踪 |
| Feign | ✅ | HTTP 调用追踪 |
| MyBatis | ✅ | 数据库操作追踪 |
| Dubbo | ✅ | RPC 调用追踪 |
| Redis | ✅ | 缓存操作追踪 |

## 🤝 贡献

欢迎提交 Issue 和 PR！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/xxx`)
3. 提交更改 (`git commit -am 'feat: add xxx'`)
4. 推送分支 (`git push origin feature/xxx`)
5. 创建 Pull Request

## ✅ 功能清单

### Agent 端（已完成）

- [x] TraceId / SpanId 生成器
- [x] Span 上下文管理（ThreadLocal）
- [x] 字节码增强框架
- [x] HTTP Span 导出器
- [x] Spring MVC 插件
- [x] Feign 插件
- [x] MyBatis 插件
- [x] Dubbo 插件
- [x] Redis 插件

### Collector 端（已完成）

- [x] Span 接收 API (/api/spans)
- [x] 链路查询 API (/api/traces/{traceId})
- [x] 服务列表 API (/api/services)
- [x] 拓扑查询 API (/api/topology)
- [x] Dashboard 前端页面
- [x] 内存存储（可扩展 ClickHouse）

### 待完善（后续迭代）

- [ ] ClickHouse 数据持久化
- [ ] 采样策略配置
- [ ] 链路告警
- [ ] 更多插件（Kafka、RocketMQ、Elasticsearch 等）

## 📄 License

Apache License 2.0

---

**LightTrace Team** © 2026