数据库语义约定稳定性迁移指南
由于修改数量巨大且受影响的用户基数广泛，OpenTelemetry 发行的现有数据库仪表化需要实施一个迁移计划，以协助用户过渡到稳定的数据库语义约定。
具体而言，当 OpenTelemetry 发行的现有数据库仪表化更新到稳定的数据库语义约定后，它们会
- SHOULD NOT 在其现有的主版本中更改其默认发出的数据库约定版本。约定包括（但不限于）属性、指标和 Span 名称，以及度量单位。
- 应在其现有主版本中引入一个名为
OTEL_SEMCONV_STABILITY_OPT_IN的环境变量，该变量接受database- 发射稳定的数据库约定，并停止发射该仪表化先前发射的旧数据库约定。database/dup- 同时发射旧的和稳定的数据库约定，允许分阶段推广稳定的语义约定。- 默认行为（在缺少其中一个值的情况下）是继续发射该仪表化先前发射的旧数据库约定版本。
- 需要维护（至少包括安全修补）其现有主版本，自开始同时发出两套约定之日起至少六个月。
- 可能会在下一个主版本中删除该环境变量，并且只发射稳定的数据库约定。
注意
OTEL_SEMCONV_STABILITY_OPT_IN 仅用于从实验性语义约定迁移到其初始稳定版本。
更改摘要
本节总结了 HTTP 语义约定自 v1.24.0 到 v1.33.0 的变更。
数据库客户端 span 属性
| 更改 | 注释 |
|---|---|
db.connection_string | 已移除 |
db.user | 已移除 |
network.transport | 已移除 |
network.type | 已移除 |
db.name | 已移除，整合到新的 db.namespace 中 |
db.redis.database_index | 已移除，整合到新的 db.namespace 中 |
db.mssql.instance_name | 已移除，整合到新的 db.namespace 中 |
db.instance.id | 已移除，替换为 server.address 或根据情况整合到 db.namespace 中 |
db.system → db.system.name | |
db.statement → db.query.text | 已澄清，默认情况下仅当存在排除敏感信息的清理时才应收集 |
db.operation → db.operation.name | |
db.sql.table → db.collection.name | 由于可能存在多个，如果不从 db.query.text 中提取值，则不应捕获 |
db.cassandra.table → db.collection.name | |
db.mongodb.collection → db.collection.name | |
db.cosmosdb.container → db.collection.name | |
新增：db.query.summary | |
新增：db.operation.batch.size | |
新增：db.response.status_code | |
新增：db.stored_procedure.name | |
新增：error.type | |
新增：db.operation.parameter.<key> | 尚未标记为稳定 |
新增：db.query.parameter.<key> | 尚未标记为稳定 |
新增：db.response.returned_rows | 尚未标记为稳定 |
参考
数据库客户端 span 名称
推荐的 span 名称已更改。有关新的 span 名称推荐的详细信息，请参阅 数据库客户端 span 名称 v1.33.0。
参考
数据库客户端操作持续时间指标
这是一个必需的指标。以前没有类似的指标。
请参阅 指标 db.client.operation.duration v1.33.0。
实验性连接指标
数据库连接指标尚未稳定，但最新版本中有几项更改。
数据库客户端连接数
指标变更
- 名称：
db.client.connections.usage→db.client.connection.count - 属性：见下表
| 属性变更 | 注释 |
|---|---|
pool.name → db.client.connection.pool.name | |
state → db.client.connection.state |
参考
数据库客户端连接最大空闲数
指标变更
- 名称：
db.client.connections.idle.max→db.client.connection.idle.max - 属性：见下表
| 属性变更 | 注释 |
|---|---|
pool.name → db.client.connection.pool.name |
参考
数据库客户端连接最小空闲数
指标变更
- 名称：
db.client.connections.idle.min→db.client.connection.idle.min - 属性：见下表
| 属性变更 | 注释 |
|---|---|
pool.name → db.client.connection.pool.name |
参考
数据库客户端最大连接数
指标变更
- 名称：
db.client.connections.max→db.client.connection.max - 属性：见下表
| 属性变更 | 注释 |
|---|---|
pool.name → db.client.connection.pool.name |
参考
数据库客户端待处理请求数
指标变更
- 名称：
db.client.connections.pending_requests→db.client.connection.pending_requests - 属性：见下表
| 属性变更 | 注释 |
|---|---|
pool.name → db.client.connection.pool.name |
参考
数据库客户端连接超时
指标变更
- 名称：
db.client.connections.timeouts→db.client.connection.timeouts - 属性：见下表
| 属性变更 | 注释 |
|---|---|
pool.name → db.client.connection.pool.name |
参考
数据库客户端连接创建时间
指标变更
- 名称：
db.client.connections.create_time→db.client.connection.create_time - 单位：
ms→s - 属性：见下表
| 属性变更 | 注释 |
|---|---|
pool.name → db.client.connection.pool.name |
参考
数据库客户端连接等待时间
指标变更
- 名称：
db.client.connections.wait_time→db.client.connection.wait_time - 单位：
ms→s - 属性：见下表
| 属性变更 | 注释 |
|---|---|
pool.name → db.client.connection.pool.name |
参考
数据库客户端连接使用时间
指标变更
- 名称：
db.client.connections.use_time→db.client.connection.use_time - 单位：
ms→s - 属性：见下表
| 属性变更 | 注释 |
|---|---|
pool.name → db.client.connection.pool.name |
参考