feat: Trilogy semantic convention stability#2095
feat: Trilogy semantic convention stability#2095hannahramadan wants to merge 9 commits intoopen-telemetry:mainfrom
Conversation
Use double quotes in rubocop.yml
| record_exception: config[:record_exception] | ||
| ) do |span| | ||
| super | ||
| rescue StandardError => e |
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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) |
There was a problem hiding this comment.
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:
- {db.query.summary} if available
- {db.operation.name} {target} if operation is available
- {target} alone (e.g., db.namespace)
- {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.
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_INto:databaseto emit stable conventions onlydatabase/dupto emit both old and the stable conventionsThe 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):
Removed in stable:
Added in stable:
Span Naming Changes for Stable Semantic Conventions
The stable database semantic conventions spec defines a specific span naming convention:
Additionally, the spec states:
Stable/Dup semconv (new behavior):