2. 核心概念：OpenTelemetry协议(OTLP)、信号(Signals)、资源(Resource)、属性(Attribute)与语义约定

在构建可靠性驱动的可观测性目录之前，必须深入理解 OpenTelemetry 的五大核心概念。它们是整个自助目录的数据基础与通信契约。本章将逐一拆解 OTLP 协议、信号类型、资源标识、属性机制以及语义约定，并阐明它们在目录架构中的具体作用。

2.1 OTLP：统一的可观测性传输协议

OTLP（OpenTelemetry Protocol）是 OpenTelemetry 的原生数据交换协议，定义了客户端（SDK/Collector）与服务端（Collector/Backend）之间的数据序列化与传输标准。它使用 Protobuf 作为序列化格式，支持 gRPC 和 HTTP/JSON 两种传输方式。

OTLP 的核心优势在于其统一性：无论信号类型（Trace、Metric、Log），都使用相同的传输层、认证机制和压缩策略。这大幅降低了目录架构的运维复杂度。

2.2 信号（Signals）：可观测性的三大支柱

OpenTelemetry 将可观测性数据抽象为三种标准信号：Traces、Metrics 和 Logs。每种信号都有独立的数据模型和语义，但在目录架构中必须关联起来。

• Traces（链路）：记录请求在分布式系统中的完整路径。核心数据结构是 Span，包含 TraceId、SpanId、ParentSpanId、StartTime、EndTime、Attributes 和 Events。
• Metrics（指标）：聚合后的数值测量数据。支持 Counter、Histogram、Gauge、UpDownCounter 等 Instrument 类型。每个 Metric 包含一系列 DataPoint。
• Logs（日志）：带时间戳的结构化文本记录。OpenTelemetry 使用 LogRecord 模型，包含 Severity、Body、Attributes 和 TraceContext 关联字段。

2.3 资源（Resource）：数据的来源标识

Resource 描述了产生数据的实体（如服务、容器、主机、集群）。它是所有信号的公共元数据，在 OTLP 中作为独立的消息体存在，与信号载荷一起传输。

// Resource 示例（Protobuf 表示）
message Resource {
  repeated KeyValue attributes = 1;
  string dropped_attributes_count = 2;
}

// 典型资源属性
resource.attributes = {
  "service.name": "payment-service",
  "service.version": "1.4.2",
  "host.name": "ip-10-0-1-42",
  "k8s.pod.uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "deployment.environment": "production"
}

在可靠性评审中，资源是数据关联的关键纽带。目录架构必须强制要求每个信号携带完整的 Resource 信息，否则无法进行跨信号关联分析。

2.4 属性（Attribute）：可观测性的维度键值对

Attribute 是 OpenTelemetry 中最灵活的元数据载体，以键值对（Key-Value）形式附加在 Span、DataPoint、LogRecord 和 Resource 上。属性支持多种值类型：字符串、布尔、整数、浮点数、数组。

2.5 语义约定（Semantic Conventions）：标准化的属性命名规范

语义约定是 OpenTelemetry 社区定义的属性命名与取值标准。它确保不同服务、不同语言 SDK 上报的数据使用一致的属性名，从而实现跨团队、跨工具的可观测性互操作性。

语义约定按领域组织，主要包含以下类别：

• 通用约定：service.name、service.version、telemetry.sdk.name
• HTTP 约定：http.method、http.url、http.status_code、http.route
• 数据库约定：db.system、db.name、db.statement、db.operation
• 消息队列约定：messaging.system、messaging.destination、messaging.operation
• 基础设施约定：host.name、k8s.pod.name、cloud.provider

2.6 核心概念在自助目录中的协同关系

在可靠性评审驱动的自助目录中，这五个概念形成以下数据流：

1. OTLP 作为统一传输管道，承载所有信号。
2. 每个信号（Trace/Metric/Log）携带 Resource 标识来源实体。
3. 信号内部通过 Attribute 描述具体操作的维度信息。
4. 语义约定 确保 Attribute 的命名和取值在目录中可被统一解析和查询。
5. 目录架构基于 Resource 和 Attribute 建立索引，实现跨信号的关联检索。