OpenTelemetry如何避免AttributeKey键重复及明确重复键语义？

键命名规范与官方指导 #

• 建议为自定义键添加所属包/类名前缀，比如com.myapp.user_id，这是避免不同库键名冲突最直接的方式。OpenTelemetry官方语义规范中的预定义属性键（如http.method、db.system）都采用了领域前缀的命名方式，这可以作为自定义键的参考范式。
• 官方核心规范明确要求属性键需保证唯一性，语义规范文档定义了各场景下的标准键，自定义键需避免与这些标准键重复，同时推荐使用具有业务或模块辨识度的命名。

键字符串的语法限制 #

• 禁止包含换行符、控制字符等特殊符号；
• 允许使用.、_、/作为分隔符，官方预定义键大量使用.做层级分隔；
• 推荐使用小写字母命名，避免大小写敏感引发的隐性冲突。

重复键的精确语义解释 #

你观察到的默认实现行为是符合OpenTelemetry设计逻辑的：

• AttributeKey的唯一性由键字符串+数据类型共同决定，equals()方法会同时校验这两个维度；
• 但AttributesBuilder的去重逻辑仅依据键字符串：当添加相同键字符串但不同类型的AttributeKey时，后添加的会覆盖前一个的存储位置。由于get()方法需要完整匹配AttributeKey的键字符串和类型，导致原类型的AttributeKey无法找到对应值，只有新类型的AttributeKey能获取到值。

比如你提供的代码示例：

AttributeKey<String> strKey = AttributeKey.stringKey("foo");
AttributeKey<Boolean> boolKey = AttributeKey.booleanKey("foo");

Attributes attr = Attributes.builder()
    .put(strKey, "String")
    .put(boolKey, true)
    .build();

System.out.println("value=" + attr.get(strKey)); // 输出 value=null

最终存储的是boolKey对应的true，但用strKey获取时因类型不匹配返回null，而非预期的覆盖后的值。

共享库的最佳实践 #

• 强制添加唯一前缀：为库中所有自定义属性键添加专属标识前缀（如com.mylibrary.user_id），从根源避免跨库键名冲突；
• 统一管理键实例：在库内部定义并暴露预定义的AttributeKey常量，不允许外部调用方自行创建属性键；
• 明确文档声明：在库的文档中清晰列出所有暴露的属性键及其对应类型，方便集成方了解和规避冲突；
• 避免类型混用：在构建Attributes时，确保同一键字符串下仅使用一种数据类型的AttributeKey，避免依赖默认去重逻辑带来的非预期行为。

内容的提问来源于stack exchange，提问作者David