Jaeger数据模型：Span、Trace、Logs数据结构
项目地址: https://gitcode.com/GitHub_Trending/ja/jaeger 概述
Jaeger作为业界领先的分布式追踪系统，其核心数据模型设计直接影响着追踪数据的存储、查询和可视化效果。本文将深入解析Jaeger的三大核心数据结构：Span（跨度）、Trace（追踪）和Logs（日志），帮助开发者全面理解分布式追踪的数据组织方式。
核心数据结构解析
1. Span（跨度） - 分布式追踪的基本单元
Span代表分布式系统中的单个工作单元，是追踪数据的最小组成元素。每个Span包含以下关键字段：
type Span struct {
TraceID TraceID `json:"traceID"` // 追踪ID
SpanID SpanID `json:"spanID"` // 跨度ID
OperationName string `json:"operationName"` // 操作名称
References []Reference `json:"references"` // 引用关系
StartTime uint64 `json:"startTime"` // 开始时间（微秒）
Duration uint64 `json:"duration"` // 持续时间（微秒）
Tags []KeyValue `json:"tags"` // 标签键值对
Logs []Log `json:"logs"` // 日志记录
ProcessID ProcessID `json:"processID,omitempty"` // 进程ID
Process *Process `json:"process,omitempty"` // 进程信息
}
Span关键字段说明
| 字段名 | 类型 | 描述 | 示例值 |
|---|---|---|---|
| TraceID | string | 全局唯一的追踪标识符 | "5a2b3c4d5e6f7a8b" |
| SpanID | string | 当前Span的唯一标识符 | "9e8d7c6b5a4f3e2d" |
| OperationName | string | 操作/方法名称 | "HTTP GET /api/users" |
| StartTime | uint64 | 开始时间戳（微秒） | 1640995200000000 |
| Duration | uint64 | 持续时间（微秒） | 150000 |
2. Trace（追踪） - 完整的调用链
Trace代表一个完整的分布式事务调用链，由多个相关的Span组成：
type Trace struct {
TraceID TraceID `json:"traceID"` // 追踪ID
Spans []Span `json:"spans"` // 包含的所有Span
Processes map[ProcessID]Process `json:"processes"` // 进程信息映射
Warnings []string `json:"warnings"` // 警告信息
}
Trace结构特点
3. Logs（日志） - 详细的事件记录
Log结构用于记录Span执行过程中的具体事件：
type Log struct {
Timestamp uint64 `json:"timestamp"` // 时间戳（微秒）
Fields []KeyValue `json:"fields"` // 日志字段
}
type KeyValue struct {
Key string `json:"key"` // 键名
Type ValueType `json:"type,omitempty"` // 值类型
Value any `json:"value"` // 值内容
}
日志类型支持
Jaeger支持多种数据类型的日志记录：
| 类型常量 | 描述 | 示例 |
|---|---|---|
| StringType | 字符串类型 | "error message" |
| BoolType | 布尔类型 | true |
| Int64Type | 64位整数 | 42 |
| Float64Type | 64位浮点数 | 3.14159 |
| BinaryType | 二进制数据 | []byte{0x01, 0x02} |
4. 引用关系（References）
Span之间的依赖关系通过References字段定义：
type Reference struct {
RefType ReferenceType `json:"refType"` // 引用类型
TraceID TraceID `json:"traceID"` // 目标追踪ID
SpanID SpanID `json:"spanID"` // 目标跨度ID
}
const (
ChildOf ReferenceType = "CHILD_OF" // 父子关系
FollowsFrom ReferenceType = "FOLLOWS_FROM" // 跟随关系
)
数据模型关系图谱
实际应用示例
完整的Trace数据示例
{
"traceID": "5a2b3c4d5e6f7a8b",
"spans": [
{
"traceID": "5a2b3c4d5e6f7a8b",
"spanID": "9e8d7c6b5a4f3e2d",
"operationName": "HTTP GET /api/users",
"references": [],
"startTime": 1640995200000000,
"duration": 150000,
"tags": [
{
"key": "http.method",
"type": "string",
"value": "GET"
},
{
"key": "http.status_code",
"type": "int64",
"value": 200
}
],
"logs": [
{
"timestamp": 1640995200050000,
"fields": [
{
"key": "event",
"type": "string",
"value": "cache hit"
}
]
}
],
"processID": "p1"
}
],
"processes": {
"p1": {
"serviceName": "api-gateway",
"tags": [
{
"key": "ip",
"type": "string",
"value": "192.168.1.100"
}
]
}
}
}
最佳实践建议
1. Span命名规范
- 使用有意义的操作名称，如
HTTP GET /api/users - 避免使用泛化的名称，如
processRequest
2. Tags使用指南
// 推荐：使用标准语义标签
tags := []KeyValue{
{Key: "http.method", Type: "string", Value: "GET"},
{Key: "http.status_code", Type: "int64", Value: 200},
{Key: "db.system", Type: "string", Value: "mysql"},
}
// 避免：使用非标准标签
tags := []KeyValue{
{Key: "method", Type: "string", Value: "GET"}, // 不明确
}
3. Logs记录原则
- 记录关键业务事件和异常情况
- 保持日志内容简洁且有价值
- 避免记录敏感信息
性能优化考虑
数据序列化优化
由于Jaeger需要处理大量的追踪数据，数据模型的序列化性能至关重要：
- 使用二进制格式：在生产环境中优先使用Thrift或Protobuf格式
- 减少字段冗余：合理使用omitempty标签避免序列化空值
- 批量处理：合并多个Span的日志记录减少IO操作
总结
Jaeger的数据模型设计体现了分布式追踪系统的核心需求：
- Span 作为基本单元，完整记录单个操作的执行详情
- Trace 组织相关Span，构建完整的调用链视图
- Logs 提供详细的运行时信息，辅助问题诊断
通过深入理解这些数据结构，开发者可以更好地利用Jaeger进行系统监控、性能分析和故障排查，构建更加稳定可靠的分布式系统。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
