From eaa05bc55089fe3cd2ecf48f7f5afd66628cc8e2 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Thu, 28 Aug 2025 17:09:34 -0700 Subject: [PATCH 01/11] Update DB-API integration docs --- .../instrumentation/dbapi/__init__.py | 43 +++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py index a2d63c20e3..6c441ebf18 100644 --- a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py @@ -20,6 +20,18 @@ Usage ----- +The DB-API instrumentor and its utilities provide common, core functionality for +database framework or object relation mapper (ORM) instrumentations. Users will +typically instrument database client code with those framework/ORM-specific +instrumentations, instead of directly using this DB-API integration. See full list +at `instrumentation`_. + +.. _instrumentation: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation + +If an instrumentation for your needs does not exist, then DB-API integration can +be used directly as follows. + + .. code-block:: python import mysql.connector @@ -33,6 +45,37 @@ # Ex: pyodbc trace_integration(pyodbc, "Connection", "odbc") + +Configuration +------------- + +SQLCOMMENTER +************ +You can optionally configure DB-API instrumentation to enable sqlcommenter which +enriches the query with contextual information. Queries made after setting up +trace integration with sqlcommenter enabled will have configurable key-value pairs +appended to them, e.g. ``"select * from auth_users; /*metrics=value*/"``. For +more information, see: + +* `Semantic Conventions - Database Spans `_ +* `sqlcommenter `_ + +.. code:: python + + import mysql.connector + import pyodbc + + from opentelemetry.instrumentation.dbapi import trace_integration + + + # Ex: mysql.connector + trace_integration( + mysql.connector, + "connect", + "mysql", + enable_commenter=True, + ) + API --- """ From bf1c21170db80b591961a09975151d2fd7556f32 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 29 Aug 2025 09:38:11 -0700 Subject: [PATCH 02/11] Add more wrap_connect info --- .../instrumentation/dbapi/__init__.py | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py index 6c441ebf18..2274deecdf 100644 --- a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py @@ -37,14 +37,20 @@ import mysql.connector import pyodbc - from opentelemetry.instrumentation.dbapi import trace_integration - + from opentelemetry.instrumentation.dbapi import ( + trace_integration, + wrap_connect, + ) # Ex: mysql.connector trace_integration(mysql.connector, "connect", "mysql") # Ex: pyodbc trace_integration(pyodbc, "Connection", "odbc") + # Or, directly call wrap_connect for more configurability + wrap_connect(__name__, mysql.connector, "connect", "mysql") + wrap_connect(__name__, pyodbc, "Connection", "odbc") + Configuration ------------- @@ -65,11 +71,12 @@ import mysql.connector import pyodbc - from opentelemetry.instrumentation.dbapi import trace_integration + from opentelemetry.instrumentation.dbapi import wrap_connect # Ex: mysql.connector - trace_integration( + wrap_connect( + __name__, mysql.connector, "connect", "mysql", From d042691b799dbd50d2cf7f210f884c7341696b28 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 29 Aug 2025 10:49:06 -0700 Subject: [PATCH 03/11] Add DB-API docs SQLCommenter Configurations --- .../instrumentation/dbapi/__init__.py | 64 +++++++++++++++++-- 1 file changed, 58 insertions(+), 6 deletions(-) diff --git a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py index 2274deecdf..112f18c44c 100644 --- a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py @@ -42,9 +42,9 @@ wrap_connect, ) - # Ex: mysql.connector + # Example: mysql.connector trace_integration(mysql.connector, "connect", "mysql") - # Ex: pyodbc + # Example: pyodbc trace_integration(pyodbc, "Connection", "odbc") # Or, directly call wrap_connect for more configurability @@ -60,8 +60,9 @@ You can optionally configure DB-API instrumentation to enable sqlcommenter which enriches the query with contextual information. Queries made after setting up trace integration with sqlcommenter enabled will have configurable key-value pairs -appended to them, e.g. ``"select * from auth_users; /*metrics=value*/"``. For -more information, see: +appended to them, e.g. ``"select * from auth_users; /*metrics=value*/"``. This +supports context propagation between database client and server when database log +records are enabled. For more information, see: * `Semantic Conventions - Database Spans `_ * `sqlcommenter `_ @@ -69,20 +70,71 @@ .. code:: python import mysql.connector - import pyodbc from opentelemetry.instrumentation.dbapi import wrap_connect - # Ex: mysql.connector + # Opts into sqlcomment for MySQL trace integration + wrap_connect( + __name__, + mysql.connector, + "connect", + "mysql", + enable_commenter=True, + ) + + +SQLCommenter Configurations +*************************** +When using ``wrap_connect`` for DB-API trace integration, the key-value pairs appended to the query can be configured using ``commenter_options``. When sqlcommenter is enabled, all available KVs/tags calculated by default. ``commenter_options`` supports opting out of specific KVs. + +.. code:: python + + import mysql.connector + + from opentelemetry.instrumentation.dbapi import wrap_connect + + + # Opts into sqlcomment for MySQL trace integration + # Opts out of tags for libpq_version wrap_connect( __name__, mysql.connector, "connect", "mysql", enable_commenter=True, + commenter_options={ + "libpq_version": False, + "db_driver": False, + } ) +Available commenter options +########################### + +The following options can be configured through ``commenter_options``: + +#. ``db_driver`` - Database driver name with version. + Example: ``mysql.connector=2.2.9`` + +#. ``dbapi_threadsafety`` - DB-API's threadsafety value. + Example: ``dbapi_threadsafety=2`` + +#. ``dbapi_level`` - DB-API's API level. + Example: ``dbapi_level=2.0`` + +#. ``driver_paramstyle`` - DB-API's paramstyle for SQL statement parameters. + Example: ``driver_paramstyle='pyformat'`` + +#. ``libpq_version`` - PostgreSQL's libpq version (checked for PostgreSQL only). + Example: ``libpq_version=140001`` + +#. ``mysql_client_version`` - MySQL client version (checked for MySQL only). + Example: ``mysql_client_version='123'`` + +#. ``opentelemetry_values`` - OpenTelemetry context values. + Example: ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` + API --- """ From 61600903ed08a113be4daadaa150c87e3381d9bb Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 29 Aug 2025 11:22:17 -0700 Subject: [PATCH 04/11] Emphasize framework/orm-specific instrumentors first --- .../instrumentation/dbapi/__init__.py | 29 +++++++++++++++---- 1 file changed, 23 insertions(+), 6 deletions(-) diff --git a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py index 112f18c44c..da560d94a4 100644 --- a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py @@ -47,7 +47,7 @@ # Example: pyodbc trace_integration(pyodbc, "Connection", "odbc") - # Or, directly call wrap_connect for more configurability + # Or, directly call wrap_connect for more configurability. wrap_connect(__name__, mysql.connector, "connect", "mysql") wrap_connect(__name__, pyodbc, "Connection", "odbc") @@ -57,7 +57,14 @@ SQLCOMMENTER ************ -You can optionally configure DB-API instrumentation to enable sqlcommenter which +sqlcommenter is supported by several database client framework/ORM-specific +instrumentors. See their respective docs for how to opt into this feature at +`instrumentation`_. There is no need to opt in at the DB-API level unless setting up +its integration directly. + +.. _instrumentation: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation + +If using DB-API instrumentation directly, you can optionally enable sqlcommenter which enriches the query with contextual information. Queries made after setting up trace integration with sqlcommenter enabled will have configurable key-value pairs appended to them, e.g. ``"select * from auth_users; /*metrics=value*/"``. This @@ -74,7 +81,7 @@ from opentelemetry.instrumentation.dbapi import wrap_connect - # Opts into sqlcomment for MySQL trace integration + # Opts into sqlcomment for MySQL trace integration. wrap_connect( __name__, mysql.connector, @@ -86,7 +93,17 @@ SQLCommenter Configurations *************************** -When using ``wrap_connect`` for DB-API trace integration, the key-value pairs appended to the query can be configured using ``commenter_options``. When sqlcommenter is enabled, all available KVs/tags calculated by default. ``commenter_options`` supports opting out of specific KVs. +sqlcommenter is supported by several database client framework/ORM-specific +instrumentors. See their respective docs for how to configure this feature at +`instrumentation`_. There is no need to configure at the DB-API level unless setting up +its integration directly. + +.. _instrumentation: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation + +If using DB-API instrumentation directly, the key-value pairs appended to the query +can be configured using ``commenter_options``. When sqlcommenter is enabled, all +available KVs/tags are calculated by default. ``commenter_options`` supports *opting out* +of specific KVs. .. code:: python @@ -95,8 +112,8 @@ from opentelemetry.instrumentation.dbapi import wrap_connect - # Opts into sqlcomment for MySQL trace integration - # Opts out of tags for libpq_version + # Opts into sqlcomment for MySQL trace integration. + # Opts out of tags for libpq_version, db_driver. wrap_connect( __name__, mysql.connector, From 1a7e2a4dcc90b39213c57ad81bd7027f6ab30b57 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 29 Aug 2025 11:48:39 -0700 Subject: [PATCH 05/11] Table instead of numbered list commenter options --- .../instrumentation/dbapi/__init__.py | 37 +++++++++---------- 1 file changed, 17 insertions(+), 20 deletions(-) diff --git a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py index da560d94a4..a07b195088 100644 --- a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py @@ -131,26 +131,23 @@ The following options can be configured through ``commenter_options``: -#. ``db_driver`` - Database driver name with version. - Example: ``mysql.connector=2.2.9`` - -#. ``dbapi_threadsafety`` - DB-API's threadsafety value. - Example: ``dbapi_threadsafety=2`` - -#. ``dbapi_level`` - DB-API's API level. - Example: ``dbapi_level=2.0`` - -#. ``driver_paramstyle`` - DB-API's paramstyle for SQL statement parameters. - Example: ``driver_paramstyle='pyformat'`` - -#. ``libpq_version`` - PostgreSQL's libpq version (checked for PostgreSQL only). - Example: ``libpq_version=140001`` - -#. ``mysql_client_version`` - MySQL client version (checked for MySQL only). - Example: ``mysql_client_version='123'`` - -#. ``opentelemetry_values`` - OpenTelemetry context values. - Example: ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| Commenter Option | Description | Example | ++===========================+===========================================================+===========================================================================+ +| ``db_driver`` | Database driver name with version. | ``mysql.connector=2.2.9`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``dbapi_threadsafety`` | DB-API's threadsafety value. | ``dbapi_threadsafety=2`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``dbapi_level`` | DB-API's API level. | ``dbapi_level=2.0`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``driver_paramstyle`` | DB-API's paramstyle for SQL statement parameters. | ``driver_paramstyle='pyformat'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``libpq_version`` | PostgreSQL's libpq version (checked for PostgreSQL only). | ``libpq_version=140001`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``mysql_client_version`` | MySQL client version (checked for MySQL only). | ``mysql_client_version='123'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``opentelemetry_values`` | OpenTelemetry context as traceparent at time of query. | ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ API --- From 709efbf8b804aa155ed7d6144954fbfa36810fdf Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 29 Aug 2025 11:52:43 -0700 Subject: [PATCH 06/11] Update wording --- .../src/opentelemetry/instrumentation/dbapi/__init__.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py index a07b195088..d448525c51 100644 --- a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py @@ -136,13 +136,13 @@ +===========================+===========================================================+===========================================================================+ | ``db_driver`` | Database driver name with version. | ``mysql.connector=2.2.9`` | +---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ -| ``dbapi_threadsafety`` | DB-API's threadsafety value. | ``dbapi_threadsafety=2`` | +| ``dbapi_threadsafety`` | DB-API threadsafety value: 0-3 or unknown. | ``dbapi_threadsafety=2`` | +---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ -| ``dbapi_level`` | DB-API's API level. | ``dbapi_level=2.0`` | +| ``dbapi_level`` | DB-API API level: 1.0, 2.0, or unknown. | ``dbapi_level=2.0`` | +---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ -| ``driver_paramstyle`` | DB-API's paramstyle for SQL statement parameters. | ``driver_paramstyle='pyformat'`` | +| ``driver_paramstyle`` | DB-API paramstyle for SQL statement parameter. | ``driver_paramstyle='pyformat'`` | +---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ -| ``libpq_version`` | PostgreSQL's libpq version (checked for PostgreSQL only). | ``libpq_version=140001`` | +| ``libpq_version`` | PostgreSQL libpq version (checked for PostgreSQL only). | ``libpq_version=140001`` | +---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ | ``mysql_client_version`` | MySQL client version (checked for MySQL only). | ``mysql_client_version='123'`` | +---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ From 893ed454275e09580009ef64ff9a7c48573b2423 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 29 Aug 2025 12:12:09 -0700 Subject: [PATCH 07/11] Add docs SQLComment in span attribute --- .../instrumentation/dbapi/__init__.py | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py index d448525c51..931d058191 100644 --- a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py @@ -149,6 +149,39 @@ | ``opentelemetry_values`` | OpenTelemetry context as traceparent at time of query. | ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` | +---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +SQLComment in span attribute +**************************** +sqlcommenter is supported by several Python database client framework/ORM-specific +instrumentors. See their respective docs for how to opt into this feature at +`instrumentation`_. There is no need to opt in at the DB-API level unless setting up +its integration directly. + +.. _instrumentation: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation + +If using DB-API instrumentation directly and sqlcommenter is enabled, you can opt into +the inclusion of sqlcomment in the query span ``db.statement`` attribute for your needs. +If ``commenter_options`` have been set, the span attribute comment will also be configured +by this setting. + +.. code:: python + + import mysql.connector + + from opentelemetry.instrumentation.dbapi import wrap_connect + + + # Opts into sqlcomment for MySQL trace integration. + # Opts into sqlcomment for `db.statement` span attribute. + wrap_connect( + __name__, + mysql.connector, + "connect", + "mysql", + enable_commenter=True, + enable_attribute_commenter=True, + ) + + API --- """ From 772495b8481124f5a7cc965c8897cb5e081c9384 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 29 Aug 2025 12:12:24 -0700 Subject: [PATCH 08/11] Adjust wording --- .../instrumentation/dbapi/__init__.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py index 931d058191..3898e0d619 100644 --- a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py @@ -55,9 +55,9 @@ Configuration ------------- -SQLCOMMENTER +SQLCommenter ************ -sqlcommenter is supported by several database client framework/ORM-specific +sqlcommenter is supported by several Python database client framework/ORM-specific instrumentors. See their respective docs for how to opt into this feature at `instrumentation`_. There is no need to opt in at the DB-API level unless setting up its integration directly. @@ -67,7 +67,7 @@ If using DB-API instrumentation directly, you can optionally enable sqlcommenter which enriches the query with contextual information. Queries made after setting up trace integration with sqlcommenter enabled will have configurable key-value pairs -appended to them, e.g. ``"select * from auth_users; /*metrics=value*/"``. This +appended to them, e.g. ``"select * from auth_users; /*traceparent=00-01234567-abcd-01*/"``. This supports context propagation between database client and server when database log records are enabled. For more information, see: @@ -91,9 +91,9 @@ ) -SQLCommenter Configurations -*************************** -sqlcommenter is supported by several database client framework/ORM-specific +SQLComment customization +************************ +sqlcommenter is supported by several Python database client framework/ORM-specific instrumentors. See their respective docs for how to configure this feature at `instrumentation`_. There is no need to configure at the DB-API level unless setting up its integration directly. @@ -129,7 +129,7 @@ Available commenter options ########################### -The following options can be configured through ``commenter_options``: +The following sqlcomment key-values can be opted out of through ``commenter_options``: +---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ | Commenter Option | Description | Example | From 5675b82d832cea2d9de55353a2363aecc5f69166 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 29 Aug 2025 12:18:35 -0700 Subject: [PATCH 09/11] Changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0b2102a591..722139a174 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ([#3679](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3679)) - `opentelemetry-instrumentation`: Avoid calls to `context.detach` with `None` token. ([#3673](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3673)) +- `opentelemetry-instrumentation-dbapi`: Adds sqlcommenter to documentation. + ([#3720](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3720)) ### Added From 7ae40b078eac49091c5b692ce8180d148ca54167 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Tue, 2 Sep 2025 10:14:01 -0700 Subject: [PATCH 10/11] Rm repeated link defs --- .../src/opentelemetry/instrumentation/dbapi/__init__.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py index 3898e0d619..ccc546c7d0 100644 --- a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py @@ -62,8 +62,6 @@ `instrumentation`_. There is no need to opt in at the DB-API level unless setting up its integration directly. -.. _instrumentation: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation - If using DB-API instrumentation directly, you can optionally enable sqlcommenter which enriches the query with contextual information. Queries made after setting up trace integration with sqlcommenter enabled will have configurable key-value pairs @@ -98,8 +96,6 @@ `instrumentation`_. There is no need to configure at the DB-API level unless setting up its integration directly. -.. _instrumentation: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation - If using DB-API instrumentation directly, the key-value pairs appended to the query can be configured using ``commenter_options``. When sqlcommenter is enabled, all available KVs/tags are calculated by default. ``commenter_options`` supports *opting out* @@ -156,8 +152,6 @@ `instrumentation`_. There is no need to opt in at the DB-API level unless setting up its integration directly. -.. _instrumentation: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation - If using DB-API instrumentation directly and sqlcommenter is enabled, you can opt into the inclusion of sqlcomment in the query span ``db.statement`` attribute for your needs. If ``commenter_options`` have been set, the span attribute comment will also be configured From c0da153899c541e41b8012319602bd9b90dbff81 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 12 Sep 2025 12:34:04 -0700 Subject: [PATCH 11/11] Reduce duplicate text, update doc header --- .../instrumentation/dbapi/__init__.py | 48 +++++++------------ 1 file changed, 17 insertions(+), 31 deletions(-) diff --git a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py index ccc546c7d0..c7eb7a20a4 100644 --- a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py @@ -23,8 +23,9 @@ The DB-API instrumentor and its utilities provide common, core functionality for database framework or object relation mapper (ORM) instrumentations. Users will typically instrument database client code with those framework/ORM-specific -instrumentations, instead of directly using this DB-API integration. See full list -at `instrumentation`_. +instrumentations, instead of directly using this DB-API integration. Features +such as sqlcommenter can be configured at framework/ORM level as well. See full +list at `instrumentation`_. .. _instrumentation: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation @@ -57,15 +58,10 @@ SQLCommenter ************ -sqlcommenter is supported by several Python database client framework/ORM-specific -instrumentors. See their respective docs for how to opt into this feature at -`instrumentation`_. There is no need to opt in at the DB-API level unless setting up -its integration directly. - -If using DB-API instrumentation directly, you can optionally enable sqlcommenter which -enriches the query with contextual information. Queries made after setting up -trace integration with sqlcommenter enabled will have configurable key-value pairs -appended to them, e.g. ``"select * from auth_users; /*traceparent=00-01234567-abcd-01*/"``. This +You can optionally enable sqlcommenter which enriches the query with contextual +information. Queries made after setting up trace integration with sqlcommenter +enabled will have configurable key-value pairs appended to them, e.g. +``"select * from auth_users; /*traceparent=00-01234567-abcd-01*/"``. This supports context propagation between database client and server when database log records are enabled. For more information, see: @@ -89,16 +85,11 @@ ) -SQLComment customization -************************ -sqlcommenter is supported by several Python database client framework/ORM-specific -instrumentors. See their respective docs for how to configure this feature at -`instrumentation`_. There is no need to configure at the DB-API level unless setting up -its integration directly. - -If using DB-API instrumentation directly, the key-value pairs appended to the query -can be configured using ``commenter_options``. When sqlcommenter is enabled, all -available KVs/tags are calculated by default. ``commenter_options`` supports *opting out* +SQLCommenter with commenter_options +*********************************** +The key-value pairs appended to the query can be configured using +``commenter_options``. When sqlcommenter is enabled, all available KVs/tags +are calculated by default. ``commenter_options`` supports *opting out* of specific KVs. .. code:: python @@ -122,7 +113,7 @@ } ) -Available commenter options +Available commenter_options ########################### The following sqlcomment key-values can be opted out of through ``commenter_options``: @@ -147,15 +138,10 @@ SQLComment in span attribute **************************** -sqlcommenter is supported by several Python database client framework/ORM-specific -instrumentors. See their respective docs for how to opt into this feature at -`instrumentation`_. There is no need to opt in at the DB-API level unless setting up -its integration directly. - -If using DB-API instrumentation directly and sqlcommenter is enabled, you can opt into -the inclusion of sqlcomment in the query span ``db.statement`` attribute for your needs. -If ``commenter_options`` have been set, the span attribute comment will also be configured -by this setting. +If sqlcommenter is enabled, you can opt into the inclusion of sqlcomment in +the query span ``db.statement`` attribute for your needs. If ``commenter_options`` +have been set, the span attribute comment will also be configured by this +setting. .. code:: python