Scala应用中OpenTelemetry Java Agent告警：同一属性存在多值记录

告警核心原因解析 #

这个警告来自OpenTelemetry异步度量存储组件，本质是在同一个度量收集周期内，db.client.connections.usage这个异步Instrument的同一属性组合被多次调用记录方法。具体诱因拆解：

• 违反异步Instrument使用规范：db.client.connections.usage属于异步度量（通常是ObservableGauge），这类Instrument要求单次收集周期内，每个唯一属性集合只能被记录一次。若回调逻辑中对同一属性（比如state="idle"）多次执行record操作，就会触发警告。
• 回调聚合逻辑错误：统计连接池状态时，未先计算某类连接的总数，而是遍历每个连接都调用一次record(1, attributes)，导致同一属性被重复记录。
• 重复注册回调：若代码中重复注册了针对db.client.connections.usage的异步回调，多个回调会在同一周期内各自记录同一属性，引发告警。
• 并发状态干扰：虽然OpenTelemetry异步回调默认由MetricReader单线程执行，但如果回调执行期间连接池状态被其他线程修改，可能导致回调多次读取不同值并重复记录同一属性（该场景概率较低）。

解决建议 #

1. 修正回调聚合逻辑 #

先一次性计算每种属性对应的总数值，再调用一次record完成记录，避免重复操作：

// 错误示例：遍历单个连接重复记录
connectionPool.forEach(conn => {
  val attributes = Attributes.of(AttributeKey.stringKey("state"), conn.state())
  gauge.record(1, attributes)
})

// 正确示例：先聚合总数再记录
val stateCounts = connectionPool.groupBy(_.state()).view.mapValues(_.size)
stateCounts.foreach { case (state, count) =>
  val attributes = Attributes.of(AttributeKey.stringKey("state"), state)
  gauge.record(count, attributes)
}

2. 检查Instrument注册唯一性 #

确保代码中仅注册一次针对db.client.connections.usage的异步回调，避免重复注册导致的多次记录。

3. 快照化状态读取 #

在回调内先获取连接池状态的快照（比如复制当前连接列表），基于快照完成统计和记录，避免回调执行期间连接状态变化带来的干扰。

4. 升级OpenTelemetry版本 #

你使用的1.25.1版本较旧，后续稳定版本（如1.30+）对异步度量的处理逻辑有优化，也修复了部分潜在bug，升级前需验证Scala应用的兼容性。

5. 确认Instrument类型正确性 #

db.client.connections.usage确实适合用ObservableGauge（异步）记录连接池实时状态，无需更换Instrument类型，但要避免错误使用同步Instrument（如普通Gauge）实现异步逻辑。

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