この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/semconv/non-normative/db-migration/

翻訳元: open-telemetry/semantic-conventions v1.44.0（コミット e10a930）

データベースのセマンティック規約の安定性に関する移行ガイド

変更点の量が多く、影響を受けるユーザー基盤も広範であることから、OpenTelemetryが公開している既存のデータベース計装は、安定版のデータベースセマンティック規約への移行をユーザーが行いやすくする移行計画を実装する必要があります。

具体的には、OpenTelemetryが公開している既存のデータベース計装が安定版のデータベースセマンティック規約に更新される際には、次のようにします。

既存のメジャーバージョンにおいて、デフォルトで発行するデータベース規約のバージョンを変更してはなりません（SHOULD NOT）。規約には、属性、メトリクス名、スパン名、計測単位などが含まれますが、これらに限定されません。
既存のメジャーバージョンにおいて、環境変数OTEL_SEMCONV_STABILITY_OPT_INを導入すべきです（SHOULD）。この変数は次の値を受け付けます。
- database - 安定版のデータベース規約を発行し、それまで計装が発行していた古いデータベース規約の発行を停止します。
- database/dup - 古い規約と安定版の規約の両方を発行し、安定版セマンティック規約への段階的な移行を可能にします。
- これらの値がいずれも指定されていない場合のデフォルトの動作は、その計装がそれまで発行していた古いデータベース規約のバージョンをそのまま発行し続けることです。
両方の規約セットを発行し始めてから少なくとも6か月間は、既存のメジャーバージョンを（少なくともセキュリティパッチの適用という形で）維持する必要があります。
次のメジャーバージョンでは、この環境変数を削除し、安定版のデータベース規約のみを発行してもかまいません（MAY）。

[!NOTE] OTEL_SEMCONV_STABILITY_OPT_INは、実験的なセマンティック規約から最初の安定版への移行時にのみ使用することを意図しています。

変更点のまとめ

この節では、HTTPセマンティック規約について、v1.24.0からv1.33.0への変更をまとめます。

データベースクライアントのスパン属性

Change	Comments
`db.connection_string`	削除
`db.user`	削除
`network.transport`	削除
`network.type`	削除
`db.name`	削除。新しい`db.namespace`に統合。値は、大文字小文字の正規化を試みずにアプリケーションから提供されたとおりに取得することが推奨される（RECOMMENDED）と明確化
`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`	デフォルトでの収集は、機密情報を除外するサニタイズが行われている場合に限るべき（SHOULD）と明確化
`db.operation` → `db.operation.name`	値は、大文字小文字の正規化を試みずにアプリケーションから提供されたとおりに取得することが推奨される（RECOMMENDED）と明確化
`db.sql.table` → `db.collection.name`	複数存在する可能性があるため、`db.query.text`から値を抽出して取得すべきではない。値は、大文字小文字の正規化を試みずにアプリケーションから提供されたとおりに取得することが推奨される（RECOMMENDED）と明確化
`db.cassandra.table` → `db.collection.name`	値は、大文字小文字の正規化を試みずにアプリケーションから提供されたとおりに取得することが推奨される（RECOMMENDED）と明確化
`db.mongodb.collection` → `db.collection.name`	値は、大文字小文字の正規化を試みずにアプリケーションから提供されたとおりに取得することが推奨される（RECOMMENDED）と明確化
`db.cosmosdb.container` → `db.collection.name`	値は、大文字小文字の正規化を試みずにアプリケーションから提供されたとおりに取得することが推奨される（RECOMMENDED）と明確化
新規: `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`	まだ安定版としてマークされていない

参考:

データベースクライアントのスパン名

推奨されるスパン名が変更されました。新しいスパン名の推奨事項の詳細は、データベースクライアントのスパン名 v1.33.0を参照してください。

参考:

データベースシステム名

属性db.systemはdb.system.nameに改名されました。この改名にあわせて、多くのenum値も更新されており、とくに<vendor>.<product>という命名パターンに従うことでベンダーとの関係を明示するようになった点が目立ちます。

以下の表には、db.system.nameへの改名または削除が行われたdb.systemの値のみを、新しい値の安定性とともに列挙しています。変更のない値は掲載していません。

[!NOTE] db.system.name属性自体はstableです。個々のenumメンバーは、以下に示すとおりそれぞれ独自の安定性レベル（stableまたはdevelopment）を持ちます。

Description	Old `db.system` value	New `db.system.name` value
Adabas (Adaptable Database System)	`adabas`	`softwareag.adabas`
InterSystems Caché (古いエイリアス)	`cache`	削除
InterSystems Caché	`intersystems_cache`	`intersystems.cache`
Cloudscape	`cloudscape`	削除
ColdFusion	`coldfusion`	削除
Azure Cosmos DB	`cosmosdb`	`azure.cosmosdb`
IBM Db2	`db2`	`ibm.db2`
Amazon DynamoDB	`dynamodb`	`aws.dynamodb`
EnterpriseDB	`edb`	削除
FileMaker	`filemaker`	削除
Firebird	`firebird`	`firebirdsql`
FirstSQL	`firstsql`	削除
H2 Database	`h2`	`h2database`
SAP HANA	`hanadb`	`sap.hana`
IBM Informix	`informix`	`ibm.informix`
Actian Ingres	`ingres`	`actian.ingres`
InterBase	`interbase`	削除
SAP MaxDB	`maxdb`	`sap.maxdb`
Microsoft SQL Server	`mssql`	`microsoft.sql_server`
Microsoft SQL Server Compact	`mssqlcompact`	削除
IBM Netezza	`netezza`	`ibm.netezza`
Oracle Database	`oracle`	`oracle.db`
Pervasive PSQL	`pervasive`	削除
PointBase	`pointbase`	削除
Progress Database	`progress`	削除
Amazon Redshift	`redshift`	`aws.redshift`
Google Cloud Spanner	`spanner`	`gcp.spanner`
Sybase	`sybase`	削除
Vertica	`vertica`	削除

参考:

データベースクライアントの操作時間メトリクス

これは必須のメトリクスです。以前は類似のメトリクスはありませんでした。

詳細はメトリクスdb.client.operation.duration v1.33.0を参照してください。

実験的なコネクションメトリクス

データベースのコネクションメトリクスはまだ安定版ではありませんが、最新リリースでいくつかの変更がありました。

データベースクライアントのコネクション数

メトリクスの変更点:

名前: db.client.connections.usage → db.client.connection.count
属性: 以下の表を参照

Attribute change	Comments
`pool.name` → `db.client.connection.pool.name`
`state` → `db.client.connection.state`

参考:

データベースクライアントのアイドルコネクション最大数

メトリクスの変更点:

名前: db.client.connections.idle.max → db.client.connection.idle.max
属性: 以下の表を参照

Attribute change	Comments
`pool.name` → `db.client.connection.pool.name`

参考:

データベースクライアントのアイドルコネクション最小数

メトリクスの変更点:

名前: db.client.connections.idle.min → db.client.connection.idle.min
属性: 以下の表を参照

Attribute change	Comments
`pool.name` → `db.client.connection.pool.name`

参考:

データベースクライアントのコネクション最大数

メトリクスの変更点:

名前: db.client.connections.max → db.client.connection.max
属性: 以下の表を参照

Attribute change	Comments
`pool.name` → `db.client.connection.pool.name`

参考:

データベースクライアントの保留中リクエスト数

メトリクスの変更点:

名前: db.client.connections.pending_requests → db.client.connection.pending_requests
属性: 以下の表を参照

Attribute change	Comments
`pool.name` → `db.client.connection.pool.name`

参考:

データベースクライアントのコネクションタイムアウト数

メトリクスの変更点:

名前: db.client.connections.timeouts → db.client.connection.timeouts
属性: 以下の表を参照

Attribute change	Comments
`pool.name` → `db.client.connection.pool.name`

参考:

データベースクライアントのコネクション作成時間

メトリクスの変更点:

名前: db.client.connections.create_time → db.client.connection.create_time
単位: ms → s
属性: 以下の表を参照

Attribute change	Comments
`pool.name` → `db.client.connection.pool.name`

参考:

データベースクライアントのコネクション待機時間

メトリクスの変更点:

名前: db.client.connections.wait_time → db.client.connection.wait_time
単位: ms → s
属性: 以下の表を参照

Attribute change	Comments
`pool.name` → `db.client.connection.pool.name`

参考:

データベースクライアントのコネクション使用時間

メトリクスの変更点:

名前: db.client.connections.use_time → db.client.connection.use_time
単位: ms → s
属性: 以下の表を参照

Attribute change	Comments
`pool.name` → `db.client.connection.pool.name`

参考: