Improve psycopg2, psycopg readthedocs on sqlcommenter

CHANGELOG.md

@@ -28,14 +28,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-- `opentelemetry-instrumentation-botocore`: Handle dict input in _decode_tool_use for Bedrock streaming
+- `opentelemetry-instrumentation-botocore`: bedrock: only decode JSON input buffer in Anthropic Claude streaming
   ([#3875](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3875))
 - `opentelemetry-instrumentation-aiohttp-client`, `opentelemetry-instrumentation-aiohttp-server`: Fix readme links and text
   ([#3902](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3902))
 - `opentelemetry-instrumentation-aws-lambda`: Fix ImportError with slash-delimited handler paths
   ([#3894](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3894))
 - `opentelemetry-exporter-richconsole`: Prevent deadlock when parent span is not part of the batch
   ([#3900](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3900))
+- `opentelemetry-instrumentation-psycopg2`, `opentelemetry-instrumentation-psycopg`: improve readthedocs for sqlcommenter configuration.
+  ([#3882](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3882))
 - `opentelemetry-instrumentation-aiohttp-server`: delay initialization of tracer, meter and excluded urls to instrumentation for testability
   ([#3836](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3836))
 

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

@@ -13,10 +13,10 @@
 # limitations under the License.
 
 """
-The integration with PostgreSQL supports the `Psycopg`_ library, it can be enabled by
+The integration with PostgreSQL supports the `Psycopg`_ library. It can be enabled by
 using ``PsycopgInstrumentor``.
 
-.. _Psycopg: http://initd.org/psycopg/
+.. _Psycopg: https://www.psycopg.org/psycopg3/docs/
 
 Usage
 -----
@@ -55,84 +55,87 @@
 Configuration
 -------------
 
-SQLCOMMENTER
-*****************************************
+SQLCommenter
+************
 You can optionally configure Psycopg instrumentation to enable sqlcommenter which enriches
-the query with contextual information.
+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
 
     from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor
 
-    PsycopgInstrumentor().instrument(enable_commenter=True, commenter_options={})
-
-
-For example,
-::
-
-   Invoking cursor.execute("select * from auth_users") will lead to sql query "select * from auth_users" but when SQLCommenter is enabled
-   the query will get appended with some configurable tags like "select * from auth_users /*tag=value*/;"
-
-
-SQLCommenter Configurations
-***************************
-We can configure the tags to be appended to the sqlquery log by adding configuration inside commenter_options(default:{}) keyword
-
-db_driver = True(Default) or False
-
-For example,
-::
-Enabling this flag will add psycopg and it's version which is /*psycopg%%3A2.9.3*/
-
-dbapi_threadsafety = True(Default) or False
-
-For example,
-::
-Enabling this flag will add threadsafety /*dbapi_threadsafety=2*/
+    PsycopgInstrumentor().instrument(enable_commenter=True)
 
-dbapi_level = True(Default) or False
 
-For example,
-::
-Enabling this flag will add dbapi_level /*dbapi_level='2.0'*/
+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.
 
-libpq_version = True(Default) or False
-
-For example,
-::
-Enabling this flag will add libpq_version /*libpq_version=140001*/
-
-driver_paramstyle = True(Default) or False
+.. code:: python
 
-For example,
-::
-Enabling this flag will add driver_paramstyle /*driver_paramstyle='pyformat'*/
+    from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor
 
-opentelemetry_values = True(Default) or False
+    # Opts into sqlcomment for Psycopg trace integration.
+    # Opts out of tags for libpq_version, db_driver.
+    PsycopgInstrumentor().instrument(
+        enable_commenter=True,
+        commenter_options={
+            "libpq_version": False,
+            "db_driver": False,
+        }
+    )
 
-For example,
-::
-Enabling this flag will add traceparent values /*traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'*/
+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.                        | ``psycopg='3.1.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                                  | ``libpq_version=140001``                                                  |
++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``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 optionally configure psycopg instrumentation to append sqlcomment to query span attribute for convenience of your platform.
+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
 
     from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor
 
+    # Opts into sqlcomment for Psycopg trace integration.
+    # Opts into sqlcomment for `db.statement` span attribute.
     PsycopgInstrumentor().instrument(
         enable_commenter=True,
         enable_attribute_commenter=True,
     )
 
-For example,
-::
-
-    Invoking cursor.execute("select * from auth_users") will lead to postgresql query "select * from auth_users" but when SQLCommenter and attribute_commenter are enabled
-    the query will get appended with some configurable tags like "select * from auth_users /*tag=value*/;" for both server query and `db.statement` span attribute.
-
+Warning:
+    Capture of sqlcomment in ``db.statement`` may have high cardinality without platform normalization. See `Semantic Conventions for database spans <https://opentelemetry.io/docs/specs/semconv/database/database-spans/#generating-a-summary-of-the-query-text>`_ for more information.
 
 API
 ---

instrumentation/opentelemetry-instrumentation-psycopg2/README.rst

@@ -1,5 +1,5 @@
-OpenTelemetry Psycopg Instrumentation
-=====================================
+OpenTelemetry Psycopg2 Instrumentation
+======================================
 
 |pypi|
 
@@ -16,6 +16,6 @@ Installation
 
 References
 ----------
-* `OpenTelemetry Psycopg Instrumentation <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/psycopg2/psycopg2.html>`_
+* `OpenTelemetry Psycopg2 Instrumentation <https://opentelemetry-python-contrib.readthedocs.io/en/latest/instrumentation/psycopg2/psycopg2.html>`_
 * `OpenTelemetry Project <https://opentelemetry.io/>`_
 * `OpenTelemetry Python Examples <https://github.com/open-telemetry/opentelemetry-python/tree/main/docs/examples>`_

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

@@ -13,10 +13,10 @@
 # limitations under the License.
 
 """
-The integration with PostgreSQL supports the `Psycopg`_ library, it can be enabled by
+The integration with PostgreSQL supports the `psycopg2`_ library. It can be enabled by
 using ``Psycopg2Instrumentor``.
 
-.. _Psycopg: http://initd.org/psycopg/
+.. _Psycopg2: https://www.psycopg.org/docs/
 
 Usage
 -----
@@ -54,85 +54,87 @@
 Configuration
 -------------
 
-SQLCOMMENTER
-*****************************************
+SQLCommenter
+************
 You can optionally configure Psycopg2 instrumentation to enable sqlcommenter which enriches
-the query with contextual information.
+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
 
     from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
 
-    Psycopg2Instrumentor().instrument(enable_commenter=True, commenter_options={})
+    Psycopg2Instrumentor().instrument(enable_commenter=True)
 
 
-For example,
-::
+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.
 
-   Invoking cursor.execute("select * from auth_users") will lead to sql query "select * from auth_users" but when SQLCommenter is enabled
-   the query will get appended with some configurable tags like "select * from auth_users /*tag=value*/;"
-
-
-SQLCommenter Configurations
-***************************
-We can configure the tags to be appended to the sqlquery log by adding configuration inside commenter_options(default:{}) keyword
-
-db_driver = True(Default) or False
-
-For example,
-::
-Enabling this flag will add psycopg2 and it's version which is /*psycopg2%%3A2.9.3*/
-
-dbapi_threadsafety = True(Default) or False
-
-For example,
-::
-Enabling this flag will add threadsafety /*dbapi_threadsafety=2*/
-
-dbapi_level = True(Default) or False
-
-For example,
-::
-Enabling this flag will add dbapi_level /*dbapi_level='2.0'*/
-
-libpq_version = True(Default) or False
-
-For example,
-::
-Enabling this flag will add libpq_version /*libpq_version=140001*/
-
-driver_paramstyle = True(Default) or False
+.. code:: python
 
-For example,
-::
-Enabling this flag will add driver_paramstyle /*driver_paramstyle='pyformat'*/
+    from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
 
-opentelemetry_values = True(Default) or False
+    # Opts into sqlcomment for Psycopg2 trace integration.
+    # Opts out of tags for libpq_version, db_driver.
+    Psycopg2Instrumentor().instrument(
+        enable_commenter=True,
+        commenter_options={
+            "libpq_version": False,
+            "db_driver": False,
+        }
+    )
 
-For example,
-::
-Enabling this flag will add traceparent values /*traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'*/
+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.                        | ``psycopg2='2.9.3'``                                                      |
++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``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                                  | ``libpq_version=140001``                                                  |
++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
+| ``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 optionally configure psycopg2 instrumentation to append sqlcomment to query span attribute for convenience of your platform.
+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
 
     from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
 
+    # Opts into sqlcomment for Psycopg2 trace integration.
+    # Opts into sqlcomment for `db.statement` span attribute.
     Psycopg2Instrumentor().instrument(
         enable_commenter=True,
         enable_attribute_commenter=True,
     )
 
-
-For example,
-::
-
-    Invoking cursor.execute("select * from auth_users") will lead to postgresql query "select * from auth_users" but when SQLCommenter and attribute_commenter are enabled
-    the query will get appended with some configurable tags like "select * from auth_users /*tag=value*/;" for both server query and `db.statement` span attribute.
+Warning:
+    Capture of sqlcomment in ``db.statement`` may have high cardinality without platform normalization. See `Semantic Conventions for database spans <https://opentelemetry.io/docs/specs/semconv/database/database-spans/#generating-a-summary-of-the-query-text>`_ for more information.
 
 API
 ---