3. 核心概念：Span、Trace、Metric、Log 的基本概念及其在 Mock 中的映射

在可观测性领域，Span、Trace、Metric 和 Log 是四大核心数据支柱。理解它们在真实系统中的含义，以及它们在 OTelMock 隔离测试环境中的映射关系，是构建高质量 Mock 数据的基础。

3.1 四大核心概念定义

概念 英文 定义 典型用途
Span Span 表示一个单一操作或工作单元，包含操作名称、开始/结束时间、状态、属性及父子关系。 记录一次数据库查询、一次 HTTP 请求处理、一个函数调用。
Trace Trace 由一组具有相同 TraceID 的 Span 构成的有向无环图，代表一个端到端请求的完整路径。 追踪用户下单请求经过网关、订单服务、支付服务、库存服务的完整链路。
Metric Metric 可聚合的数值型测量数据，通常带有时间戳和标签（维度）。 统计请求延迟 P99、CPU 使用率、每秒请求数（RPS）、错误率。
Log Log 带时间戳的文本记录，描述系统在特定时刻发生的离散事件。 记录异常堆栈、审计日志、业务操作记录。
关键区别： Span 和 Trace 关注“发生了什么”以及“因果关系”；Metric 关注“聚合值是多少”；Log 关注“具体细节是什么”。在 OTelMock 中，Mock 数据需要分别模拟这三种语义。

3.2 核心概念在 OTelMock 中的映射

OTelMock 的核心职责是模拟真实 OTel Collector 或 SDK 的输出。因此，每个真实概念在 Mock 中都有对应的数据结构和生成策略。

真实概念 OTelMock 映射 Mock 数据关键字段 隔离测试中的意义
Span SpanData 对象 spanId, parentSpanId, traceId, name, kind, startTime, endTime, status, attributes 模拟单个服务操作的耗时、状态和标签，用于验证下游服务是否正确处理了该 Span。
Trace TraceData 集合 一组共享同一 traceId 的 SpanData 列表，包含完整的父子关系链 模拟一个完整的分布式请求路径，用于验证链路追踪系统的完整性。
Metric MetricData 对象 name, type (Gauge/Sum/Histogram), value, unit, attributes, timestamp 模拟特定时间点的指标值，用于验证告警规则或聚合计算逻辑。
Log LogData 对象 timestamp, severityText, body, attributes, traceId, spanId 模拟带有上下文关联的日志事件，用于验证日志关联分析功能。

3.3 概念关系与 Mock 数据生成流程

下图展示了真实系统中四大概念的关系，以及 OTelMock 如何从配置生成对应的 Mock 数据。

真实系统概念 → OTelMock 数据映射 真实系统 Span / Trace Metric Log OTelMock SpanData / TraceData MetricData LogData Mock 输出 OTLP Protobuf JSON / gRPC 文件 / 内存 Mock 配置 核心映射原则 • 每个真实概念对应一个 Mock 对象 • 字段结构遵循 OTel 规范 • 输出格式支持 OTLP/JSON

3.4 代码示例：Mock 数据定义

以下代码展示了在 OTelMock 中如何定义 Span、Metric 和 Log 的 Mock 数据对象。

// SpanData 示例
{
  "traceId": "0af7651916cd43dd8448eb211c80319c",
  "spanId": "b7ad6b7169203331",
  "parentSpanId": "",
  "name": "HTTP GET /api/users",
  "kind": "SERVER",
  "startTime": "2025-01-15T10:00:00.000Z",
  "endTime": "2025-01-15T10:00:00.250Z",
  "status": { "code": "OK" },
  "attributes": {
    "http.method": "GET",
    "http.url": "/api/users",
    "http.status_code": 200
  }
}

// MetricData 示例 (Gauge)
{
  "name": "cpu.usage",
  "type": "Gauge",
  "value": 78.5,
  "unit": "%",
  "attributes": { "host": "web-01", "region": "us-east" },
  "timestamp": "2025-01-15T10:00:00.000Z"
}

// LogData 示例
{
  "timestamp": "2025-01-15T10:00:00.123Z",
  "severityText": "ERROR",
  "body": "Connection timeout to database",
  "attributes": { "db.system": "postgresql", "db.operation": "select" },
  "traceId": "0af7651916cd43dd8448eb211c80319c",
  "spanId": "b7ad6b7169203331"
}

3.5 隔离测试中的 Mock 映射策略

  • Span 映射策略： 为每个被测服务接口定义一组标准 Span，包含正常、超时、异常三种状态。Mock 时通过 parentSpanId 构建父子关系，模拟真实调用链。
  • Trace 映射策略： 使用相同的 traceId 将多个 Span 串联成完整 Trace。在隔离测试中，通常只模拟当前服务上下游的 Span，避免全链路数据冗余。
  • Metric 映射策略： 根据测试场景生成固定值或序列值（如递增、波动）。对于 Histogram 类型，需要模拟多个桶的计数分布。
  • Log 映射策略： 确保 Log 的 traceId 和 spanId 与对应的 Span 关联，以验证日志与链路追踪的关联能力。
常见误区： 在 Mock 中直接复制生产环境的真实数据。这可能导致敏感信息泄露，且数据量过大影响测试性能。正确的做法是使用结构化模板生成最小化、脱敏的 Mock 数据。

3.6 概念对比：真实数据 vs Mock 数据

维度 真实数据 Mock 数据
数据来源 生产系统实时采集 根据配置模板生成
数据量 海量、持续增长 可控、按需生成
数据完整性 包含所有字段和关联 只包含测试所需字段
数据敏感性 可能包含 PII 或敏感信息 完全脱敏，无真实用户数据
可重复性 不可重复，每次不同 可重复，支持确定性测试
异常覆盖 依赖真实故障发生 可主动注入各种异常场景
实践要点： 在 OTelMock 中，Span、Trace、Metric、Log 的 Mock 数据应遵循 OpenTelemetry 协议（OTLP）的规范结构。使用统一的 Resource 和 InstrumentationScope 元数据，确保 Mock 数据能被标准 OTel Collector 或后端系统正确解析。
← 上一章 📖 返回目录 下一章 →