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

在 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) 自定义属性命名规范

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

1. 使用小写字母和下划线（如 custom.field_name）。
2. 避免特殊字符（如空格、点号 . 可能导致解析问题）。
3. 添加命名空间前缀（如 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. 验证字段是否生效

1. 在 Kibana 中检查：
   • 打开 Discover，搜索 span.attributes.* 查看所有属性。
   • 确认标准属性（如 enduser.id）是否出现在预定义字段列表中。
2. 在 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 验证字段映射，确保数据在搜索、可视化和告警中可用。