当前位置：首页 > news >正文

OpenTelemetry学习笔记(四)：OpenTelemetry 语义约定，即字段映射（1）

news 2025/7/19 10:32:43

在 OpenTelemetry 中，span.setAttribute(key, value) 的 key 命名不是完全随意的，而是需要遵循一定的规范，以确保数据在 Elastic Observability（或其它后端系统）中能够正确解析、展示和分析。以下是关键规则和最佳实践：

1. 关键命名规则

(1) 优先使用 OpenTelemetry 语义约定（Semantic Conventions）

OpenTelemetry 定义了一套标准的属性命名规范（官方文档），用于统一不同场景下的字段命名。推荐优先使用这些标准属性，以便与 Elastic Observability 的内置功能无缝集成。

常见标准属性示例

场景	标准属性名	说明
用户信息	`enduser.id`	用户 ID（替代旧版 `user.id`）
HTTP 请求	`http.method`, `http.status_code`	HTTP 方法、状态码
数据库操作	`db.statement`, `db.system`	SQL 语句、数据库类型
系统指标	`system.cpu.utilization`	CPU 使用率

为什么重要？

Elastic Observability 原生支持 OpenTelemetry 语义约定，例如：
- enduser.id 会自动关联到用户相关的分析（如用户行为追踪）。
- http.method 会在 APM 服务的 HTTP 请求分布图中展示。
使用非标准属性可能导致数据无法被 Elastic 的预定义仪表盘识别。

**(2) 避免使用 `user.*` 前缀（已弃用）**

在旧版 OpenTelemetry 中，user.id 是常见用法，但新版语义约定已将其替换为 enduser.id（参考）。
✅ 推荐：span.setAttribute("enduser.id", "123456")
❌ 避免：span.setAttribute("user.id", "123456")

(3) 自定义属性命名规范

如果标准属性无法满足需求，可以自定义属性，但需遵循以下原则：

使用小写字母和下划线（如 custom.field_name）。
避免特殊字符（如空格、点号 . 可能导致解析问题）。
添加命名空间前缀（如 app.、business.）以区分自定义字段。

示例

span.setAttribute("app.login.method", "oauth2");       // 自定义应用属性
span.setAttribute("business.order_id", "ord_123");     // 业务相关属性

2. Elastic Observability 中的展示效果

(1) 标准属性的自动映射

enduser.id：在 Elastic APM 的“用户会话”分析中自动展示。
http.method：在 HTTP 服务概览图中显示请求方法分布。
db.statement：在数据库查询分析中显示 SQL 语句。

(2) 自定义属性的处理

自动索引：自定义属性会被存储到 Elasticsearch 的 span 索引中，但默认不会出现在预定义仪表盘。
手动搜索/分析：
- 在 Kibana 的 Discover 中直接搜索字段名（如 span.attributes.app.login.method: "oauth2"）。
- 在 Metrics/Logs 应用中创建自定义可视化图表。

3. 最佳实践总结

场景	推荐做法
用户 ID	`span.setAttribute("enduser.id", "123456")`
HTTP 请求	`span.setAttribute("http.method", "GET")`
数据库操作	`span.setAttribute("db.statement", "SELECT * FROM users")`
自定义业务属性	`span.setAttribute("business.order_id", "ord_123")`
自定义技术属性	`span.setAttribute("app.cache.hit", true)`

4. 验证字段是否生效

在 Kibana 中检查：
- 打开 Discover，搜索 span.attributes.* 查看所有属性。
- 确认标准属性（如 enduser.id）是否出现在预定义字段列表中。
在 APM 服务地图中验证：
- 如果属性关联到用户或 HTTP 请求，检查是否在对应分析模块中生效。

5. 常见问题

Q1: 为什么 `user.id` 在 Elastic 中不显示？

新版 OpenTelemetry 已弃用 user.*，改用 enduser.*。需更新代码：

// 错误（旧版）
span.setAttribute("user.id", "123456"); 
// 正确（新版）
span.setAttribute("enduser.id", "123456");

Q2: 自定义属性如何用于告警？

在 Elastic 中，可以通过 Kibana Alerting 基于自定义属性（如 app.error_count）创建规则。

Q3: 属性值支持哪些数据类型？

OpenTelemetry 支持 string、boolean、number、array（部分后端可能限制类型）。

结论

优先使用 OpenTelemetry 语义约定（如 enduser.id、http.method），确保与 Elastic Observability 无缝集成。
自定义属性需规范命名（小写、下划线、命名空间前缀），避免冲突。
通过 Kibana 验证字段映射，确保数据在搜索、可视化和告警中可用。

查看全文

http://www.xdnf.cn/news/1142893.html