2. OpenTelemetry 基础概念：Signal、Span、Attributes、Resource、Instrumentation Scope
在构建标准模板驱动的可观测性管线之前，必须深入理解 OpenTelemetry 的五大核心概念。它们是整个数据模型与采集管线的基石，决定了“采集什么”、“如何关联”以及“如何路由”。
2.1 三大信号（Signals）
OpenTelemetry 将可观测性数据抽象为三种标准信号（Signal），分别对应系统运行的不同侧面：
| 信号类型 | 英文 | 核心作用 | 典型数据点 |
|---|---|---|---|
| 链路 | Traces | 追踪请求在分布式系统中的完整路径与耗时 | Span ID、Parent Span ID、开始/结束时间戳 |
| 指标 | Metrics | 聚合统计系统状态与性能趋势 | Counter、Gauge、Histogram 的数值与标签 |
| 日志 | Logs | 记录离散的事件文本与上下文 | 时间戳、严重级别、消息体、结构化属性 |
设计要点： 在服务目录中，每个服务必须声明其产生的信号类型。标准模板将根据信号类型自动匹配对应的采集器、处理器和导出器配置。
三种信号并非孤立存在。OpenTelemetry 通过 Trace Context 和 Resource 将日志、指标与链路关联起来，形成“关联可观测性”。
2.2 Span：链路追踪的基本单元
Span 是 Trace 的构建块。每个 Span 代表一个命名、有时间范围的操作，是分布式追踪中最核心的数据结构。
- Span 名称：描述操作，如
HTTP GET /api/users。 - Span 上下文：包含 Trace ID、Span ID、Trace Flags，用于跨进程传播。
- 父子关系：通过 Parent Span ID 构建 Span 树，反映调用层级。
- 时间戳：Start Time 和 End Time，精确到纳秒。
- 状态：Unset / Ok / Error，标识操作结果。
- 事件：在 Span 生命周期内发生的带时间戳的注解。
管线设计影响： 标准模板必须为每个服务定义 Span 的采样策略、最大属性数、事件上限。过度采集 Span 属性会显著增加网络与存储开销。
2.3 Attributes：键值对元数据
Attributes 是附着在 Span、Metric 或 Log 上的键值对，用于提供上下文信息。OpenTelemetry 定义了语义约定（Semantic Conventions），确保跨服务的一致性。
| 类别 | 示例 Key | 示例 Value | 说明 |
|---|---|---|---|
| HTTP | http.method |
GET |
请求方法 |
| HTTP | http.status_code |
200 |
响应状态码 |
| 数据库 | db.system |
postgresql |
数据库类型 |
| 通用 | service.name |
user-service |
服务标识 |
避坑指南： 不要在 Attributes 中存储敏感信息（密码、、PII）。标准模板应内置属性过滤规则，在采集侧自动脱敏或丢弃敏感键。
2.4 Resource：资源描述
Resource 描述产生可观测性数据的实体（如进程、容器、主机）。它是全局元数据，附加到该资源产生的所有信号上。
- 资源属性：
service.name、service.version、host.name、cloud.provider。 - 资源检测器：自动从环境（K8s、ECS、本地）提取资源信息。
- 资源合并：SDK 会自动合并用户自定义资源与检测器发现的资源。
在服务目录中，Resource 是服务实例的唯一标识。标准模板必须强制每个服务实例携带 service.name 和 service.instance.id。
2.5 Instrumentation Scope：检测范围
Instrumentation Scope 标识产生信号的库或模块。它通常对应一个 instrumentation 库（如 io.opentelemetry.contrib.mongodb）或业务代码中的检测模块。
| 概念 | 作用 | 示例 |
|---|---|---|
| Scope Name | 标识 instrumentation 的来源 | @opentelemetry/instrumentation-http |
| Scope Version | 标识 instrumentation 的版本 | 0.52.0 |
| Schema URL | 指向语义约定的版本定义 | https://opentelemetry.io/schemas/1.26.0 |
模板策略： 在服务目录中，每个服务应列出其使用的 Instrumentation Scope 列表。标准模板将根据 Scope 自动启用对应的处理器（如 HTTP 属性提取器、DB 语句 sanitizer）。
2.6 核心概念在管线中的映射
在标准模板驱动的服务目录中，每个概念都对应具体的配置项：
| 概念 | 模板配置项 | 作用 |
|---|---|---|
| Signal | signals.enabled |
开启/关闭特定信号的采集 |
| Span | span.processor.* |
配置 Span 的批处理、采样、属性修改 |
| Attributes | attributes.include / exclude |
白名单/黑名单过滤属性 |
| Resource | resource.attributes |
静态定义资源属性，覆盖自动检测 |
| Scope | instrumentation.scopes |
按 Scope 粒度控制采样率与处理器 |
最佳实践： 在服务目录模板中，将 Resource 和 Scope 作为“路由键”。采集管线根据
service.name（Resource）和 instrumentation.scope.name（Scope）将数据路由到不同的后端或存储策略。