Skip to content

Latest commit

 

History

History
79 lines (62 loc) · 6.08 KB

migration-guide.md

File metadata and controls

79 lines (62 loc) · 6.08 KB

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. to v1.TODO (stable).

Database client span attributes

Change Comments
db.connection_string Removed
db.user Removed
network.transport Removed
network.type Removed
db.name → db.namespace
db.redis.database_index → 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 → db.query.text Clarified, SHOULD be collected by default only if there is sanitization that excludes sensitive information
db.operation → 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

References:

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 operation duration metric

This is a required metric. There was no similar metric previously.

See Metric db.client.operation.duration v1.TODO.