Merge branch 'main' into feature/genai-genai-spec-updates

nagkumar91 · web-flow · commit b82dd71ec63f · 2025-10-10T07:06:51.000-07:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,12 +20,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
-- `opentelemetry-instrumentation`: botocore: Add support for AWS Secrets Manager semantic convention attribute
+- `opentelemetry-instrumentation-botocore`: Add support for AWS Secrets Manager semantic convention attribute
   ([#3765](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3765))
+- `opentelemetry-instrumentation-dbapi`: Add support for `commenter_options` in `trace_integration` function to control SQLCommenter behavior
+  ([#3743](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3743))
 - Add `rstcheck` to pre-commit to stop introducing invalid RST
   ([#3777](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3777))
 - `opentelemetry-exporter-credential-provider-gcp`: create this package which provides support for supplying your machine's Application Default 
   Credentials (https://cloud.google.com/docs/authentication/application-default-credentials) to the OTLP Exporters created automatically by OpenTelemetry Python's auto instrumentation. These credentials authorize OTLP traces to be sent to `telemetry.googleapis.com`. [#3766](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3766).
+- `opentelemetry-instrumentation-psycopg`: Add missing parameter `capture_parameters` to instrumentor.
+  ([#3676](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3676))
+- `opentelemetry-instrumentation-dbapi`: Adds sqlcommenter to documentation.
+  ([#3720](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3720))
 
 ## Version 1.37.0/0.58b0 (2025-09-11)
 
diff --git a/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py b/instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py
@@ -20,19 +20,148 @@
 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. 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
+
+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
     import pyodbc
 
-    from opentelemetry.instrumentation.dbapi import trace_integration
-
+    from opentelemetry.instrumentation.dbapi import (
+        trace_integration,
+        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.
+    wrap_connect(__name__, mysql.connector, "connect", "mysql")
+    wrap_connect(__name__, pyodbc, "Connection", "odbc")
+
+
+Configuration
+-------------
+
+SQLCommenter
+************
+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:
+
+* `Semantic Conventions - Database Spans <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md#sql-commenter>`_
+* `sqlcommenter <https://google.github.io/sqlcommenter/>`_
+
+.. code:: python
+
+    import mysql.connector
+
+    from opentelemetry.instrumentation.dbapi import wrap_connect
+
+
+    # Opts into sqlcomment for MySQL trace integration.
+    wrap_connect(
+        __name__,
+        mysql.connector,
+        "connect",
+        "mysql",
+        enable_commenter=True,
+    )
+
+
+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
+
+    import mysql.connector
+
+    from opentelemetry.instrumentation.dbapi import wrap_connect
+
+
+    # Opts into sqlcomment for MySQL trace integration.
+    # Opts out of tags for libpq_version, db_driver.
+    wrap_connect(
+        __name__,
+        mysql.connector,
+        "connect",
+        "mysql",
+        enable_commenter=True,
+        commenter_options={
+            "libpq_version": False,
+            "db_driver": False,
+        }
+    )
+
+Available commenter_options
+###########################
+
+The following sqlcomment key-values can be opted out of through ``commenter_options``:
+
++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| Commenter Option          | Description                                               | Example                                                                   |
++===========================+===========================================================+===========================================================================+
+| ``db_driver``             | Database driver name with version.                        | ``mysql.connector=2.2.9``                                                 |
++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``dbapi_threadsafety``    | DB-API threadsafety value: 0-3 or unknown.                | ``dbapi_threadsafety=2``                                                  |
++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``dbapi_level``           | DB-API API level: 1.0, 2.0, or unknown.                   | ``dbapi_level=2.0``                                                       |
++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``driver_paramstyle``     | DB-API paramstyle for SQL statement parameter.            | ``driver_paramstyle='pyformat'``                                          |
++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``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'``                                            |
++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``opentelemetry_values``  | OpenTelemetry context as traceparent at time of query.    | ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` |
++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+
+SQLComment in span attribute
+****************************
+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
+
+    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
 ---
 """
@@ -79,6 +208,7 @@ def trace_integration(
     enable_commenter: bool = False,
     db_api_integration_factory: type[DatabaseApiIntegration] | None = None,
     enable_attribute_commenter: bool = False,
+    commenter_options: dict[str, Any] | None = None,
 ):
     """Integrate with DB API library.
     https://www.python.org/dev/peps/pep-0249/
@@ -97,6 +227,7 @@ def trace_integration(
         db_api_integration_factory: The `DatabaseApiIntegration` to use. If none is passed the
             default one is used.
         enable_attribute_commenter: Flag to enable/disable sqlcomment inclusion in `db.statement` span attribute. Only available if enable_commenter=True.
+        commenter_options: Configurations for tags to be appended at the sql query.
     """
     wrap_connect(
         __name__,
@@ -110,6 +241,7 @@ def trace_integration(
         enable_commenter=enable_commenter,
         db_api_integration_factory=db_api_integration_factory,
         enable_attribute_commenter=enable_attribute_commenter,
+        commenter_options=commenter_options,
     )
 
 
diff --git a/instrumentation/opentelemetry-instrumentation-dbapi/tests/test_dbapi_integration.py b/instrumentation/opentelemetry-instrumentation-dbapi/tests/test_dbapi_integration.py
@@ -259,6 +259,45 @@ def test_suppress_instrumentation(self):
         spans_list = self.memory_exporter.get_finished_spans()
         self.assertEqual(len(spans_list), 0)
 
+    def test_commenter_options_propagation(self):
+        db_integration = dbapi.DatabaseApiIntegration(
+            "instrumenting_module_test_name",
+            "testcomponent",
+            commenter_options={"opentelemetry_values": False},
+        )
+        mock_connection = db_integration.wrapped_connection(
+            mock_connect, {}, {}
+        )
+        cursor = mock_connection.cursor()
+        with self.assertRaises(Exception):
+            cursor.execute("SELECT 1", throw_exception=True)
+        spans_list = self.memory_exporter.get_finished_spans()
+        self.assertEqual(len(spans_list), 1)
+        span = spans_list[0]
+        self.assertEqual(span.attributes.get("db.system"), "testcomponent")
+        self.assertIn("opentelemetry_values", db_integration.commenter_options)
+        self.assertFalse(
+            db_integration.commenter_options["opentelemetry_values"]
+        )
+
+    @mock.patch("opentelemetry.instrumentation.dbapi.wrap_connect")
+    def test_trace_integration_passes_commenter_options(
+        self, mock_wrap_connect
+    ):
+        fake_connect_module = mock.Mock()
+        fake_options = {"opentelemetry_values": False, "foo": "bar"}
+        dbapi.trace_integration(
+            connect_module=fake_connect_module,
+            connect_method_name="connect",
+            database_system="testdb",
+            commenter_options=fake_options,
+        )
+        mock_wrap_connect.assert_called_once()
+        _, _, kwargs = mock_wrap_connect.mock_calls[0]
+
+        self.assertIn("commenter_options", kwargs)
+        self.assertEqual(kwargs["commenter_options"], fake_options)
+
     def test_executemany(self):
         db_integration = dbapi.DatabaseApiIntegration(
             "instrumenting_module_test_name", "testcomponent"
diff --git a/instrumentation/opentelemetry-instrumentation-psycopg/src/opentelemetry/instrumentation/psycopg/__init__.py b/instrumentation/opentelemetry-instrumentation-psycopg/src/opentelemetry/instrumentation/psycopg/__init__.py
@@ -184,6 +184,7 @@ def _instrument(self, **kwargs: Any):
         enable_attribute_commenter = kwargs.get(
             "enable_attribute_commenter", False
         )
+        capture_parameters = kwargs.get("capture_parameters", False)
         dbapi.wrap_connect(
             __name__,
             psycopg,
@@ -196,6 +197,7 @@ def _instrument(self, **kwargs: Any):
             enable_commenter=enable_sqlcommenter,
             commenter_options=commenter_options,
             enable_attribute_commenter=enable_attribute_commenter,
+            capture_parameters=capture_parameters,
         )
 
         dbapi.wrap_connect(
@@ -210,6 +212,7 @@ def _instrument(self, **kwargs: Any):
             enable_commenter=enable_sqlcommenter,
             commenter_options=commenter_options,
             enable_attribute_commenter=enable_attribute_commenter,
+            capture_parameters=capture_parameters,
         )
         dbapi.wrap_connect(
             __name__,
@@ -223,6 +226,7 @@ def _instrument(self, **kwargs: Any):
             enable_commenter=enable_sqlcommenter,
             commenter_options=commenter_options,
             enable_attribute_commenter=enable_attribute_commenter,
+            capture_parameters=capture_parameters,
         )
 
     def _uninstrument(self, **kwargs: Any):
diff --git a/instrumentation/opentelemetry-instrumentation-psycopg/tests/test_psycopg_integration.py b/instrumentation/opentelemetry-instrumentation-psycopg/tests/test_psycopg_integration.py
@@ -264,6 +264,24 @@ def test_span_name(self):
         self.assertEqual(spans_list[6].name, "postgresql")
         self.assertEqual(spans_list[7].name, "--")
 
+    def test_span_params_attribute(self):
+        PsycopgInstrumentor().instrument(capture_parameters=True)
+        cnx = psycopg.connect(database="test")
+        query = "SELECT * FROM mytable WHERE myparam1 = %s AND myparam2 = %s"
+        params = ("test", 42)
+
+        cursor = cnx.cursor()
+
+        cursor.execute(query, params)
+        spans_list = self.memory_exporter.get_finished_spans()
+        self.assertEqual(len(spans_list), 1)
+        self.assertEqual(spans_list[0].name, "SELECT")
+        assert spans_list[0].attributes is not None
+        self.assertEqual(spans_list[0].attributes["db.statement"], query)
+        self.assertEqual(
+            spans_list[0].attributes["db.statement.parameters"], str(params)
+        )
+
     # pylint: disable=unused-argument
     def test_not_recording(self):
         mock_tracer = mock.Mock()
@@ -479,6 +497,23 @@ async def test_span_name_async(self):
         self.assertEqual(spans_list[4].name, "query")
         self.assertEqual(spans_list[5].name, "query")
 
+    async def test_span_params_attribute(self):
+        PsycopgInstrumentor().instrument(capture_parameters=True)
+        cnx = await psycopg.AsyncConnection.connect("test")
+        query = "SELECT * FROM mytable WHERE myparam1 = %s AND myparam2 = %s"
+        params = ("test", 42)
+        async with cnx.cursor() as cursor:
+            await cursor.execute(query, params)
+
+        spans_list = self.memory_exporter.get_finished_spans()
+        self.assertEqual(len(spans_list), 1)
+        self.assertEqual(spans_list[0].name, "SELECT")
+        assert spans_list[0].attributes is not None
+        self.assertEqual(spans_list[0].attributes["db.statement"], query)
+        self.assertEqual(
+            spans_list[0].attributes["db.statement.parameters"], str(params)
+        )
+
     # pylint: disable=unused-argument
     async def test_not_recording_async(self):
         mock_tracer = mock.Mock()
