Database semconv stability migration guide

docs/database/migration-guide.md

@@ -0,0 +1,79 @@
+# Database semantic convention stability migration guide
+
+Due to the significant number of modifications and the extensive user base
+affected by them, existing database instrumentations published by
+OpenTelemetry are required to implement a migration plan that will assist users in
+transitioning to the stable database semantic conventions.
+
+Specifically, when existing database instrumentations published by OpenTelemetry are
+updated to the stable database semantic conventions, they:
+
+- SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN` in
+  their existing major version, which accepts:
+  - `database` - emit the stable database conventions, and stop emitting
+    the old database conventions that the instrumentation emitted previously.
+  - `database/dup` - emit both the old and the stable database conventions,
+    allowing for a phased rollout of the stable semantic conventions.
+  - The default behavior (in the absence of one of these values) is to continue
+    emitting whatever version of the old database conventions the
+    instrumentation was emitting previously.
+- Need to maintain (security patching at a minimum) their existing major version
+  for at least six months after it starts emitting both sets of conventions.
+- May drop the environment variable in their next major version and emit only
+  the stable database conventions.
+
+## Summary of changes
+
+This section summarizes the changes made to the HTTP semantic conventions
+from
+[v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/README.md).
+to
+[v1.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/README.md).
+
+### Database client span attributes
+
+<!-- prettier-ignore-start -->
+| Change                                          | Comments                                                                                                    |
+|-------------------------------------------------|-------------------------------------------------------------------------------------------------------------|
+| `db.connection_string`                          | Removed                                                                                                     |
+| `db.user`                                       | Removed                                                                                                     |
+| `network.transport`                             | Removed                                                                                                     |
+| `network.type`                                  | Removed                                                                                                     |
+| `db.name` &rarr; `db.namespace`                 |                                                                                                             |
+| `db.redis.database_index` &rarr; `db.namespace` |                                                                                                             |
+| `db.mssql.instance_name`                        | Incorporated into the new `db.namespace`                                                                    |
+| `db.instance.id`                                | Removed, replaced by `server.address` or `db.namespace` as appropriate                                      |
+| `db.statement` &rarr; `db.query.text`           | Clarified, SHOULD be collected by default only if there is sanitization that excludes sensitive information |
+| `db.operation` &rarr; `db.operation.name`       |                                                                                                             |
+| `db.sql.table` -> `db.collection.name`          |                                                                                                             |
+| `db.cassandra.table` -> `db.collection.name`    |                                                                                                             |
+| `db.mongodb.collection` -> `db.collection.name` |                                                                                                             |
+| `db.cosmosdb.container` -> `db.collection.name` |                                                                                                             |
+| New: `db.query.parameter.<key>`                 | Opt-In                                                                                                      |
+| New: `error.type`                               |                                                                                                             |
+<!-- prettier-ignore-end -->
+
+References:
+
+- [Database client span attributes v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md)
+- [Database client span attributes v1.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-spans.md)
+
+### Database client span names
+
+The recommended span name has changed to `{db.operation.name} {target}`, where the `{target}` SHOULD describe the entity
+that the operation is performed against and SHOULD adhere to one of the following values, provided they are accessible:
+
+- `db.collection.name` SHOULD be used for data manipulation operations or operations on database collections.
+- `db.namespace` SHOULD be used for operations on a specific database namespace.
+- `server.address:server.port` SHOULD be used for other operations not targeting any specific database(s) or collection(s)
+
+References:
+
+- [Database client span names v1.24.0](https://github.com/open-telemetry/semantic-conventions/blob/v1.24.0/docs/database/database-spans.md)
+- [Database client span names v1.TODO (stable)](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-spans.md#name)
+
+### Database client operation duration metric
+
+This is a required metric. There was no similar metric previously.
+
+See [Metric `db.client.operation.duration` v1.TODO](https://github.com/open-telemetry/semantic-conventions/blob/v1.TODO/docs/database/database-metrics.md#metric-dbclientoperationduration).