语义约定：标准化属性命名

本节将学习：为什么需要语义约定？常见的语义约定有哪些？如何选择和使用语义约定？

为什么需要语义约定

问题是什么？ 属性命名不一致。

举个例子：服务 A 使用 "user_id"，服务 B 使用 "userId"，服务 C 使用 "user.id"。命名不一致，导致无法统一查询，无法关联数据，无法自动化处理。

语义约定的价值是什么？ 通过语义约定，可以：

统一命名：所有服务使用相同的属性名
标准属性：使用标准的属性定义
可查询：可以统一查询所有服务的数据
可关联：可以关联不同服务的数据
可自动化：可以自动化处理数据

这就是语义约定的价值。它让数据变得标准化，可以统一处理。

常见的语义约定

语义约定有哪些？

第一个是 HTTP 语义约定。

```
http.method
```
：HTTP 方法（GET、POST 等）
```
http.url
```
：HTTP URL
```
http.status_code
```
：HTTP 状态码
```
http.request.size
```
：请求大小
```
http.response.size
```
：响应大小

第二个是数据库语义约定。

```
db.system
```
：数据库系统（mysql、postgresql 等）
```
db.name
```
：数据库名称
```
db.statement
```
：SQL 语句
```
db.operation
```
：数据库操作（select、insert 等）

第三个是消息队列语义约定。

```
messaging.system
```
：消息系统（kafka、rabbitmq 等）
```
messaging.destination
```
：消息目标
```
messaging.message_id
```
：消息 ID

第四个是业务语义约定。

```
user.id
```
：用户 ID
```
order.id
```
：订单 ID
```
payment.amount
```
：支付金额

这些是常见的语义约定。使用这些约定，可以保证数据的一致性。

如何选择和使用语义约定

选择原则是什么？

第一个原则：优先使用标准语义约定。 HTTP、数据库、消息队列等，使用 OpenTelemetry 官方定义。这样可以保证数据的一致性。

第二个原则：自定义业务语义约定。 业务相关的属性，遵循命名规范。例如，

user.id

、

order.id

、

payment.amount

。

第三个原则：统一团队使用。 团队内部统一，文档化约定。这样可以保证团队内部的一致性。

使用示例：在代码中，可以这样使用语义约定：

Span span = tracer.spanBuilder("http.request")
    .setAttribute("http.method", "GET")
    .setAttribute("http.url", "/api/orders")
    .setAttribute("http.status_code", 200)
    .startSpan();

这个代码使用标准语义约定。

http.method

、

http.url

、

http.status_code

都是标准的语义约定。

命名规范：使用小写字母和下划线，使用语义化的名称，遵循 OpenTelemetry 规范，保持一致性。

这就是如何选择和使用语义约定。

本节小结

在本节中，我们学习了语义约定：

第一个是语义约定的价值。 标准化属性命名，保证数据一致性，可以统一查询、关联、自动化处理。

第二个是常见的语义约定。 HTTP、数据库、消息队列、业务约定。这些是常见的语义约定。

第三个是选择原则。 优先使用标准约定，自定义业务约定，统一团队使用。

这就是语义约定。理解语义约定，是保证数据一致性的关键。

第 2 章总结

在第 2 章中，我们学习了 OpenTelemetry 的架构概览，包括：

OpenTelemetry 是什么：CNCF 毕业项目，供应商中立的可观察性框架
核心组件：API、SDK、Collector
数据流：从应用到可视化
插桩方式：自动 vs 手动
采样策略：控制成本和数据完整性
语义约定：标准化属性命名

这些都是 OpenTelemetry 的基础知识。理解这些知识，是掌握 OpenTelemetry 的关键。

在下一章，我们将开始学习 Prometheus 安装与配置。学习如何安装和配置 Prometheus，如何收集和查询指标。