Skip to content

feat: Trilogy semantic convention stability#2095

Open
hannahramadan wants to merge 9 commits intoopen-telemetry:mainfrom
hannahramadan:trilogy_semantic_stability
Open

feat: Trilogy semantic convention stability#2095
hannahramadan wants to merge 9 commits intoopen-telemetry:mainfrom
hannahramadan:trilogy_semantic_stability

Conversation

@hannahramadan
Copy link
Member

@hannahramadan hannahramadan commented Mar 18, 2026

This PR is intended to assist in the transition from the old to new database semantic conventions. Per the database semantic convention stability migration spec, users should be able to set the environment variable OTEL_SEMCONV_STABILITY_OPT_IN to:

  • database to emit stable conventions only
  • database/dup to emit both old and the stable conventions
  • a blank env var will emit old conventions only

The agent is required to maintain this bridge for 6 months and may drop the environment variable in the next major version and emit only the stable database and networking conventions.

This approach was approved for HTTP migration in #1547

Changes (Old -> Stable):

  • db.system → db.system.name
  • net.peer.name → server.address
  • db.name → db.namespace
  • db.statement → db.query.text

Removed in stable:

  • db.user
  • db.instance.id

Added in stable:

  • server.port
  • error.type
  • db.response.status_code

Span Naming Changes for Stable Semantic Conventions
The stable database semantic conventions spec defines a specific span naming convention:

  1. {db.query.summary} if available
  2. {db.operation.name} {target} if operation is available
  3. {target} alone (e.g., db.namespace)
  4. {db.system.name} as fallback (e.g., mysql)

Additionally, the spec states:

"The operation name SHOULD NOT be extracted from db.query.text"

Stable/Dup semconv (new behavior):

  • Span name follows the spec, ignoring config[:span_name]
  • Operation is not extracted from SQL
  • Operation is only used if explicitly provided via with_attributes
  • Fallback chain: {operation} {db.namespace} → {db.namespace} → mysql

record_exception: config[:record_exception]
) do |span|
super
rescue StandardError => e
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is new, to capture error.type and db.status.status_code. The same pattern exists in the ping and query methods.

'server.address' => mysql_host
}

attributes['server.port'] = mysql_port if mysql_port
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

server.port is a new attribute. I debated always adding this as it is only required when different from the default, and originally first checked if it was different from the default before adding. I am happy to add this condition back in.

[10] server.port: When observed from the client side, and when communicating through an intermediary, server.port SHOULD represent the server port behind any intermediaries, for example proxies, if it's available.

[11] server.port: If using a port other than the default port for this DBMS and if server.address is set.

# @param database_name [String] The name of the database (db.namespace).
# @return [String] The span name.
# @api private
def stable_database_span_name(operation, database_name)
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would love to hear opinions on the span name change. I believe this as-is follows the spec, but want to make sure users are okay with this change. Note: it removes config[:span_name], so users wouldn't be able to set it anymore. I'm happy to revert this - just trying to follow spec to get started.

Span Naming Changes for Stable Semantic Conventions
The stable database semantic conventions spec defines a specific span naming convention:

  1. {db.query.summary} if available
  2. {db.operation.name} {target} if operation is available
  3. {target} alone (e.g., db.namespace)
  4. {db.system.name} as fallback (e.g., mysql)

Additionally, the spec states:

"The operation name SHOULD NOT be extracted from db.query.text"

Stable/Dup semconv (new behavior):

  • Span name follows the spec, ignoring config[:span_name]
  • Operation is not extracted from SQL
  • Operation is only used if explicitly provided via with_attributes
  • Fallback chain: {operation} {db.namespace} → {db.namespace} → mysql

We have a PR to generate a summary query, which I believe it was discussed to put that behind a config because of potential overhead. This could be added later as an option for span name.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant