3. OpenTelemetry 核心概念：Signal、Span、Trace、Metric、Log、Context Propagation、Resource

在构建发布工程自助门户的可观测性时，OpenTelemetry 提供了一套标准化的数据模型与协议。理解其核心概念是设计有效观测方案的前提。本章将逐一拆解这些概念，并阐明它们如何在发布流水线中协同工作。

3.1 三大信号（Signal）

OpenTelemetry 将可观测性数据抽象为三种核心信号（Signal），分别对应传统监控的三大支柱，但通过统一的 SDK 和导出协议实现了数据关联。

3.2 Span 与 Trace：请求的旅程

Span 是链路追踪的基本工作单元。它代表一个具有开始时间和结束时间的操作，例如“拉取代码”、“执行构建”、“运行单元测试”。每个 Span 包含操作名称、时间戳、属性（Attributes）和事件（Events）。

Trace 是由一系列 Span 组成的树状结构，代表一个端到端的请求流。Trace 通过一个全局唯一的 Trace ID 标识，其内部的 Span 通过 Parent Span ID 形成父子关系。

Trace ID: abc123
├── Span: "用户触发发布" (Root Span)
│   ├── Span: "代码检出" (Child of Root)
│   │   └── Span: "Git Clone" (Child of 代码检出)
│   ├── Span: "单元测试" (Child of Root)
│   ├── Span: "构建镜像" (Child of Root)
│   │   └── Span: "Docker Build" (Child of 构建镜像)
│   └── Span: "部署到预发环境" (Child of Root)
│       └── Span: "K8s Apply" (Child of 部署到预发环境)

3.3 Metric：聚合的量化视图

Metrics 用于聚合测量系统在时间维度上的状态。OpenTelemetry 支持三种主要的 Metric 工具：

• Counter（计数器）： 只增不减的值，如“构建总次数”、“部署失败次数”。
• Histogram（直方图）： 记录值的分布，如“构建耗时分布”、“部署延迟分布”。
• Gauge（仪表盘）： 可上下波动的瞬时值，如“当前排队构建数”、“环境 CPU 使用率”。

3.4 Log：带上下文的事件记录

OpenTelemetry 的 Logs 并非取代传统日志框架，而是通过标准化的日志记录 API 和关联机制，使日志成为可观测性的一部分。关键改进在于：

• 结构化日志： 日志不再是纯文本字符串，而是包含键值对的结构化数据。
• Trace 关联： 日志记录自动携带当前上下文的 Trace ID 和 Span ID，实现“日志即 Span 事件”。

// 结构化日志示例（伪代码）
logger.info("构建任务完成", {
  "trace_id": "abc123",
  "span_id": "def456",
  "build_id": "build-789",
  "duration_ms": 45230,
  "status": "success"
});

3.5 Context Propagation：跨服务传递状态

Context Propagation 是 OpenTelemetry 的“神经系统”。它负责将 Trace ID、Span ID 以及 Baggage（用户自定义上下文）在微服务、线程、消息队列之间透明传递。没有它，分布式链路就会断裂。

传播机制分为两部分：

3.6 Resource：描述数据来源

Resource 是关联到所有信号（Traces、Metrics、Logs）的元数据，用于描述生成数据的实体。它通常包含基础设施信息、服务名称、版本号、环境标签等。Resource 是数据聚合与过滤的基础。

Resource Attributes:
  service.name: "发布引擎"
  service.version: "2.1.0"
  deployment.environment: "production"
  host.name: "jenkins-master-01"
  cloud.provider: "aws"
  cloud.region: "us-east-1"

3.7 概念总结与发布工程映射

下表总结了所有核心概念在发布工程自助门户中的具体映射，帮助你快速建立认知关联：