DB and HTTP semantic convention stability migration for SQLAlchemy #4110

tammy-baylis-swi · 2026-01-21T00:17:03Z

Description

Add SQLAlchemy instrumentor support for when OTEL_SEMCONV_STABILITY_OPT_IN includes

"database" or "database/dup"
"http" or "http/dup"

This changes the SQLComment in span attribute feature if opted in. Inclusion of sqlcomment on query span would be on db.statement and/or db.query.text attribute if default, "database", or "database/dup".

Fixes #2679

Type of change

Please delete options that are not relevant.

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
This change requires a documentation update

How Has This Been Tested?

Added unit tests

Does This PR Require a Core Repo Change?

Yes. - Link to PR:
No.

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

Followed the style guidelines of this project
Changelogs have been updated
Unit tests have been added
Documentation has been updated

tammy-baylis-swi · 2026-01-22T23:45:31Z

...ntelemetry-instrumentation-sqlalchemy/src/opentelemetry/instrumentation/sqlalchemy/engine.py

+        # Extract db_name for operation name
+        # Prefer old semconv (db.name) over new semconv (db.namespace) for backwards compatibility
+        db_name = attrs.get(DB_NAME) or attrs.get(DB_NAMESPACE) or ""


This was a small design choice; lmk if should be another way.

It seems like the db_name should be the same regardless, right? We should be able to simply pull the DB name from the cursor, since pulling it back from the attributes seems like a very roundabout way to do this.

My preference would be to create a separate function to pull the DB name from the cursor. This can be used in _get_attributes_from_cursor and here for the Span name.

Added _get_db_name_from_cursor in 66e0dbd. It looks a little odd for a few reasons:

From existing _normalize_vendor and _get_attributes_from_cursor methods, it seems this instrumentor only "supports" postgresql and sqlite connection. So I followed this to keep scope to semconv migration.

The new helper gets postgres cursor connection the same way _get_attributes_from_cursor does.

We use conn.engine.url.database if sqlite, instead of from-cursor, else we'd have to create a new cursor (execute) and do PRAGMA database_list and that's not ideal.

...ntelemetry-instrumentation-sqlalchemy/src/opentelemetry/instrumentation/sqlalchemy/engine.py

herin049 · 2026-02-09T02:41:12Z

...elemetry-instrumentation-sqlalchemy/src/opentelemetry/instrumentation/sqlalchemy/__init__.py

            __version__,
            tracer_provider,
-            schema_url="https://opentelemetry.io/schemas/1.11.0",
+            schema_url=_get_schema_url(sem_conv_opt_in_mode),


Not sure if we need to worry about this scenario, and if it is even possible to define a schema URL for it, but what is the expected behavior if only of of DB or HTTP is opt in?

Good point. Initial expected behaviour would have only been DB opt-in, but now both HTTP and DB are (and should be) considered in 653a1e3. Right now, DB opt-in dictates whether schema url is default or new. This is ok if mode is http,database or dup or both default, but a mix (http,default or default,database) will mix network and db attributes from the same instrumentor.

But I think this is ok. If users/vendors are knowledgeable enough to be migrating before the breaking change to opt-in-by-default, then it can be dup for both anyway. THoughts?

This doesn't fix things but it's more consistent now in b9ef17a for doing the same for meter.

My concern is more that once we start emitting stable HTTP attributes by default, the schema URL should be using 1.21 (since this is the version HTTP became made stable), now if DB opt is is enabled then we should be using 1.25. If we only check the DB opt in, then it could fallback on 1.11.

Of course, this is assuming we're using version 1.25 of DB semconv and not 1.21. Do we know which one we plan on targeting?

Yes I think 1.11 (old hardcode), 1.21, and 1.25 make sense. How about this:

opt-in semconv

default 1.11.0

http,default 1.21.0

http/dup,default 1.21.0

*,database 1.25.0

*,database/dup 1.25.0

"default" case would not exist anymore if stable HTTP is new default and no option to opt out (iirc from last sig). DB would dictate highest and HTTP takes lower precedence.

Yes, exactly what I had in mind! I understand that this adds some scope, but figured we should do this correctly. Perhaps, we can add either a function directly in _OpenTelemetrySemanticConventionStability to get the schema URL to be used or expose a way to return the Semcov stability mapping in _OpenTelemetrySemanticConventionStability (e.g. with a function _get_stability_signal_type_mapping), and make a backwards compatible change to _get_schema_url to have the ability to accept this mapping and return the highest semconv version found. I also agree that we should simply use the highest associated semconv version based on the opted in semconv types. For example, if we add rpc that uses semconv 1.38, if this is set then it will take precedence over everything else.

As a step in that direction, in 5477ff8 I've added a separate _get_schema_url_for_signal_types to choose the highest version if default, http, database, or gen_ai. In that commit, SQLAlchemy instrumentor is the only one that uses it while all other instrumentors are using the classic _get_schema_url.

Lmk what you think!

herin049 · 2026-02-09T02:45:47Z

...ntelemetry-instrumentation-sqlalchemy/src/opentelemetry/instrumentation/sqlalchemy/engine.py

+        # Extract db_name for operation name
+        # Prefer old semconv (db.name) over new semconv (db.namespace) for backwards compatibility
+        db_name = attrs.get(DB_NAME) or attrs.get(DB_NAMESPACE) or ""


It seems like the db_name should be the same regardless, right? We should be able to simply pull the DB name from the cursor, since pulling it back from the attributes seems like a very roundabout way to do this.

My preference would be to create a separate function to pull the DB name from the cursor. This can be used in _get_attributes_from_cursor and here for the Span name.

…sage

tammy-baylis-swi · 2026-02-11T18:31:12Z

opentelemetry-instrumentation/src/opentelemetry/instrumentation/_semconv.py

 from enum import Enum
 from typing import Container, Mapping, MutableMapping

+from packaging import version as package_version


packaging is already a dep of opentelemetry-instrumentation so might as well use its built-in equality checks.

tammy-baylis-swi · 2026-02-11T18:31:29Z

opentelemetry-instrumentation/tests/test_semconv.py



+class TestOpenTelemetrySemConvSchemaUrl(TestCase):
+    @stability_mode("")


These decorators are needed for clean env at each test

tammy-baylis-swi and others added 9 commits January 20, 2026 13:26

Add _semconv set_db fns

df17c09

lint

c41c5b2

Changelog

d067840

semconv opt-in for sqlalchemy instr

8b78135

Merge branch 'main' into sqlalchemy-semconv-opt-in

7e4c458

use imports not hardcode

2a6c066

Update comment on comment-in-attr

3598cfc

Add tests

f830a0f

Changelog

575772a

tammy-baylis-swi commented Jan 22, 2026

View reviewed changes

tammy-baylis-swi marked this pull request as ready for review January 22, 2026 23:47

tammy-baylis-swi requested a review from a team as a code owner January 22, 2026 23:47

tammy-baylis-swi and others added 2 commits January 22, 2026 16:11

Add migration status

b03fb67

Merge branch 'main' into sqlalchemy-semconv-opt-in

1340532

tammy-baylis-swi mentioned this pull request Jan 23, 2026

feat(redis): support semantic convention opt-in and emit stable Redis attributes #3826

Open

6 tasks

herin049 reviewed Jan 24, 2026

View reviewed changes

...ntelemetry-instrumentation-sqlalchemy/src/opentelemetry/instrumentation/sqlalchemy/engine.py Outdated Show resolved Hide resolved

...ntelemetry-instrumentation-sqlalchemy/src/opentelemetry/instrumentation/sqlalchemy/engine.py Outdated Show resolved Hide resolved

tammy-baylis-swi and others added 2 commits January 26, 2026 13:53

Merge branch 'main' into sqlalchemy-semconv-opt-in

7d46aea

Sqlalchemy http,database opt-in

653a1e3

tammy-baylis-swi changed the title ~~DB semantic convention stability migration for SQLAlchemy~~ DB and HTTP semantic convention stability migration for SQLAlchemy Jan 26, 2026

tammy-baylis-swi requested a review from herin049 January 26, 2026 22:36

tammy-baylis-swi added this to @xrmx's Python PR digest Jan 26, 2026

tammy-baylis-swi moved this to Ready for review in @xrmx's Python PR digest Jan 26, 2026

Merge branch 'main' into sqlalchemy-semconv-opt-in

50eb085

herin049 reviewed Feb 9, 2026

View reviewed changes

herin049 approved these changes Feb 9, 2026

View reviewed changes

tammy-baylis-swi and others added 4 commits February 9, 2026 13:21

Merge branch 'main' into sqlalchemy-semconv-opt-in

36e487a

meter schema_url

b9ef17a

Add sqlalchemy _get_db_name_from_cursor

66e0dbd

Add per-signal semconv opt-in schema url precedence; add sqlalchemy u…

5477ff8

…sage

tammy-baylis-swi commented Feb 11, 2026

View reviewed changes

opt-in	semconv
default	1.11.0
http,default	1.21.0
http/dup,default	1.21.0
*,database	1.25.0
*,database/dup	1.25.0



		class TestOpenTelemetrySemConvSchemaUrl(TestCase):
		@stability_mode("")

DB and HTTP semantic convention stability migration for SQLAlchemy #4110

Are you sure you want to change the base?

DB and HTTP semantic convention stability migration for SQLAlchemy #4110

Uh oh!

Conversation

tammy-baylis-swi commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Type of change

How Has This Been Tested?

Does This PR Require a Core Repo Change?

Checklist:

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tammy-baylis-swi commented Jan 21, 2026 •

edited

Loading