> Source: https://www.ymotongpoo.com/works/otel-specs-ja/semconv/non-normative/db-migration/


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

変更点の量が多く、影響を受けるユーザー基盤も広範であることから、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](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/README.md)から[v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/README.md)への変更をまとめます。

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

<!-- markdownlint-disable-file MD060 -->
| 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` &rarr; `db.system.name`                 |                                                                                                             |
| `db.statement` &rarr; `db.query.text`               | デフォルトでの収集は、機密情報を除外するサニタイズが行われている場合に限るべき（SHOULD）と明確化 |
| `db.operation` &rarr; `db.operation.name`           | 値は、大文字小文字の正規化を試みずにアプリケーションから提供されたとおりに取得することが推奨される（RECOMMENDED）と明確化 |
| `db.sql.table` &rarr; `db.collection.name`          | 複数存在する可能性があるため、`db.query.text`から値を抽出して取得すべきではない。値は、大文字小文字の正規化を試みずにアプリケーションから提供されたとおりに取得することが推奨される（RECOMMENDED）と明確化 |
| `db.cassandra.table` &rarr; `db.collection.name`    | 値は、大文字小文字の正規化を試みずにアプリケーションから提供されたとおりに取得することが推奨される（RECOMMENDED）と明確化 |
| `db.mongodb.collection` &rarr; `db.collection.name` | 値は、大文字小文字の正規化を試みずにアプリケーションから提供されたとおりに取得することが推奨される（RECOMMENDED）と明確化 |
| `db.cosmosdb.container` &rarr; `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.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md)
- [データベースクライアントのスパン属性 v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-spans.md)

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

推奨されるスパン名が変更されました。
新しいスパン名の推奨事項の詳細は、[データベースクライアントのスパン名 v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-spans.md#name)を参照してください。

参考:

- [データベースクライアントのスパン名 v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md)
- [データベースクライアントのスパン名 v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-spans.md#name)

### データベースシステム名

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

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

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

<!-- prettier-ignore-start -->
| 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`             | 削除                    |
<!-- prettier-ignore-end -->

参考:

- [`db.system`のenum値 v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md#notes-and-well-known-identifiers-for-dbsystem)
- [`db.system.name`のenum値 v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-spans.md#notes-and-well-known-identifiers-for-dbsystemname)

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

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

詳細は[メトリクス`db.client.operation.duration` v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md#metric-dbclientoperationduration)を参照してください。

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

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

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

メトリクスの変更点:

- **名前**: `db.client.connections.usage` &rarr; `db.client.connection.count`
- **属性**: 以下の表を参照

<!-- prettier-ignore-start -->
| Attribute change                                    | Comments |
|-----------------------------------------------------|----------|
| `pool.name` &rarr; `db.client.connection.pool.name` |          |
| `state` &rarr; `db.client.connection.state`         |          |
<!-- prettier-ignore-end -->

参考:

- [メトリクス`db.client.connections.usage` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsusage)
- [メトリクス`db.client.connection.count` v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md#metric-dbclientconnectioncount)

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

メトリクスの変更点:

- **名前**: `db.client.connections.idle.max` &rarr; `db.client.connection.idle.max`
- **属性**: 以下の表を参照

<!-- prettier-ignore-start -->
| Attribute change                                    | Comments |
|-----------------------------------------------------|----------|
| `pool.name` &rarr; `db.client.connection.pool.name` |          |
<!-- prettier-ignore-end -->

参考:

- [メトリクス`db.client.connections.idle.max` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsidlemax)
- [メトリクス`db.client.connection.idle.max` v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md#metric-dbclientconnectionidlemax)

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

メトリクスの変更点:

- **名前**: `db.client.connections.idle.min` &rarr; `db.client.connection.idle.min`
- **属性**: 以下の表を参照

<!-- prettier-ignore-start -->
| Attribute change                                    | Comments |
|-----------------------------------------------------|----------|
| `pool.name` &rarr; `db.client.connection.pool.name` |          |
<!-- prettier-ignore-end -->

参考:

- [メトリクス`db.client.connections.idle.min` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsidlemin)
- [メトリクス`db.client.connection.idle.min` v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md#metric-dbclientconnectionidlemin)

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

メトリクスの変更点:

- **名前**: `db.client.connections.max` &rarr; `db.client.connection.max`
- **属性**: 以下の表を参照

<!-- prettier-ignore-start -->
| Attribute change                                    | Comments |
|-----------------------------------------------------|----------|
| `pool.name` &rarr; `db.client.connection.pool.name` |          |
<!-- prettier-ignore-end -->

参考:

- [メトリクス`db.client.connections.max` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsmax)
- [メトリクス`db.client.connection.max` v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md#metric-dbclientconnectionmax)

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

メトリクスの変更点:

- **名前**: `db.client.connections.pending_requests` &rarr; `db.client.connection.pending_requests`
- **属性**: 以下の表を参照

<!-- prettier-ignore-start -->
| Attribute change                                    | Comments |
|-----------------------------------------------------|----------|
| `pool.name` &rarr; `db.client.connection.pool.name` |          |
<!-- prettier-ignore-end -->

参考:

- [メトリクス`db.client.connections.pending_requests` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionspending_requests)
- [メトリクス`db.client.connection.pending_requests` v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md#metric-dbclientconnectionpending_requests)

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

メトリクスの変更点:

- **名前**: `db.client.connections.timeouts` &rarr; `db.client.connection.timeouts`
- **属性**: 以下の表を参照

<!-- prettier-ignore-start -->
| Attribute change                                    | Comments |
|-----------------------------------------------------|----------|
| `pool.name` &rarr; `db.client.connection.pool.name` |          |
<!-- prettier-ignore-end -->

参考:

- [メトリクス`db.client.connections.timeouts` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionstimeouts)
- [メトリクス`db.client.connection.timeouts` v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md#metric-dbclientconnectiontimeouts)

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

メトリクスの変更点:

- **名前**: `db.client.connections.create_time` &rarr; `db.client.connection.create_time`
- **単位**: `ms` &rarr; `s`
- **属性**: 以下の表を参照

<!-- prettier-ignore-start -->
| Attribute change                                    | Comments |
|-----------------------------------------------------|----------|
| `pool.name` &rarr; `db.client.connection.pool.name` |          |
<!-- prettier-ignore-end -->

参考:

- [メトリクス`db.client.connections.create_time` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionscreate_time)
- [メトリクス`db.client.connection.create_time` v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md#metric-dbclientconnectioncreate_time)

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

メトリクスの変更点:

- **名前**: `db.client.connections.wait_time` &rarr; `db.client.connection.wait_time`
- **単位**: `ms` &rarr; `s`
- **属性**: 以下の表を参照

<!-- prettier-ignore-start -->
| Attribute change                                    | Comments |
|-----------------------------------------------------|----------|
| `pool.name` &rarr; `db.client.connection.pool.name` |          |
<!-- prettier-ignore-end -->

参考:

- [メトリクス`db.client.connections.wait_time` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionswait_time)
- [メトリクス`db.client.connection.wait_time` v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md#metric-dbclientconnectionwait_time)

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

メトリクスの変更点:

- **名前**: `db.client.connections.use_time` &rarr; `db.client.connection.use_time`
- **単位**: `ms` &rarr; `s`
- **属性**: 以下の表を参照

<!-- prettier-ignore-start -->
| Attribute change                                    | Comments |
|-----------------------------------------------------|----------|
| `pool.name` &rarr; `db.client.connection.pool.name` |          |
<!-- prettier-ignore-end -->

参考:

- [メトリクス`db.client.connections.use_time` v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-metrics.md#metric-dbclientconnectionsuse_time)
- [メトリクス`db.client.connection.use_time` v1.33.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.33.0/docs/database/database-metrics.md#metric-dbclientconnectionuse_time)