Update DB-API instrumentor readthedocs with sqlcommenter guide

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
 

instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py

@@ -20,19 +20,168 @@
 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
     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
+************
+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, 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,
+    )
+
+
+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.
+
+.. _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
+
+    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
+****************************
+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
 ---
 """