📚 课程目录第2章 OpenTelemetry基础概念

2. OpenTelemetry 基础概念：Signal、Resource、Instrumentation Scope 与 Context Propagation

在构建自动化告警规则之前，必须理解 OpenTelemetry 的核心数据模型。OpenTelemetry 将可观测性数据抽象为四个基础概念：Signal（信号）、Resource（资源）、Instrumentation Scope（检测范围） 和 Context Propagation（上下文传播）。这四个概念共同构成了告警规则的数据来源与关联基础。

2.1 Signal：可观测性的三大支柱

Signal 是 OpenTelemetry 对可观测性数据的统称，包含三种核心类型：Trace（链路）、Metric（指标） 和 Log（日志）。告警规则通常基于 Metric 触发，但 Trace 和 Log 提供了根因分析的上下文。

Signal 类型	核心作用	告警关联场景
Trace	记录请求在分布式系统中的完整路径，包含 Span（跨度）和 Span 之间的父子关系。	当告警触发时，通过 Trace ID 快速定位到具体的请求链路，判断是哪个服务或操作导致延迟或错误。
Metric	聚合后的数值型数据，如请求延迟 P99、错误率、CPU 使用率。支持 Counter、Histogram、Gauge 等类型。	直接作为告警规则的输入源，例如“当错误率 > 5% 时触发告警”。
Log	带时间戳的结构化或非结构化文本记录，通常包含严重级别、服务名、Trace ID 等属性。	作为告警的补充信息，在告警通知中附带相关日志片段，帮助运维人员快速排查。

SRE 实践提示： 在告警规则自动化中，Metric 是“触发器”，Trace 是“地图”，Log 是“细节”。三者缺一不可，但自动化模板应优先标准化 Metric 的采集与聚合规则。

2.2 Resource：数据的归属与来源

Resource 描述了产生可观测性数据的实体，例如主机、容器、Kubernetes Pod、服务实例等。每个 Signal 都必须关联一个 Resource，用于标识数据来源。Resource 以键值对（Key-Value）形式存在，常见的属性包括：

service.name：服务名称，如 payment-service。
service.instance.id：服务实例唯一标识。
host.name：主机名或 Pod 名称。
cloud.region：云区域，如 us-east-1。
deployment.environment：部署环境，如 production、staging。

在告警规则中，Resource 属性常用于分组和过滤。例如，只对 deployment.environment=production 的服务实例计算错误率告警，或按 service.name 分组展示不同服务的延迟 P99。

2.3 Instrumentation Scope：检测的边界与粒度

Instrumentation Scope 表示产生 Signal 的检测库或检测模块。它通常对应一个具体的库名称和版本，例如 io.opentelemetry.contrib.mongodb 或 @opentelemetry/instrumentation-express。Scope 的作用是：

隔离：不同检测库产生的数据可以通过 Scope 区分，避免命名冲突。
版本管理：当检测库升级时，Scope 中的版本信息帮助运维人员判断数据格式是否变化。
告警过滤：可以针对特定 Scope 的 Metric 设置告警，例如只关注来自 http-server 检测库的请求延迟。

  关键区别： Resource 描述“谁产生的数据”（物理或逻辑实体），Instrumentation Scope 描述“用什么产生的数据”（检测库）。两者共同构成 Signal 的元数据。

2.4 Context Propagation：跨服务的关联纽带

Context Propagation 是 OpenTelemetry 实现分布式追踪的核心机制。它通过将上下文信息（如 Trace ID、Span ID）在服务调用之间传递，将分散的 Span 串联成完整的 Trace。上下文传播通常通过 HTTP 头（如 traceparent）或 gRPC 元数据实现。

在告警场景中，Context Propagation 的价值体现在：

关联分析：当告警触发时，运维人员可以通过 Trace ID 快速关联到所有相关服务的 Span，无需手动拼接日志。
根因定位：通过 Span 的父子关系和时序，可以快速定位是哪个服务调用链路的哪个环节出现异常。
自动化诊断：告警规则可以配置为自动提取 Trace ID，并在告警通知中附带链路快照链接。

2.5 四个概念在告警规则中的协作

在自动化告警规则模板中，这四个概念以如下方式协作：

Metric Signal 作为告警规则的输入数据源，例如 http.server.duration 指标。
Resource 属性 用于告警规则的过滤条件，例如只监控 service.name="checkout-service" 的实例。
Instrumentation Scope 用于区分不同检测库产生的同名指标，避免告警规则误匹配。
Context Propagation 在告警触发后，帮助运维人员从 Metric 跳转到 Trace 和 Log，实现端到端诊断。

常见误区： 很多团队在定义告警规则时只关注 Metric 的阈值，忽略了 Resource 和 Scope 的过滤作用。这会导致告警规则在混合环境中（如多服务、多环境）产生大量误报。建议在模板中强制要求填写 Resource 过滤条件。

2.6 代码示例：在告警规则中使用 Resource 和 Scope

以下是一个基于 OpenTelemetry 语义约定的告警规则配置片段（以 Prometheus 风格的告警规则为例），展示了如何利用 Resource 和 Scope 进行精确过滤：

groups:
  - name: otel-service-alerts
    rules:
      - alert: HighErrorRate
        expr: |
          sum by (service.name, service.instance.id) (
            rate(http.server.duration_count{
              otel.scope.name="io.opentelemetry.instrumentation-http",
              deployment.environment="production"
            }[5m])
          ) > 0.05
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "服务 {{ $labels.service.name }} 错误率超过 5%"
          description: "实例 {{ $labels.service.instance.id }} 在 5 分钟内错误率达到 {{ $value | humanizePercentage }}"

在这个例子中：

otel.scope.name 过滤了来自特定检测库的指标。
deployment.environment 确保只对生产环境生效。
service.name 和 service.instance.id 用于告警通知中的精确定位。