Improve FlaskInstrumentor readthedocs on sqlcommenter (open-telemetry#3883)

* Clean up FlaskInstrumentor readthedocs sqlcommenter

* Fix quotes

* Changelog

* Update instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py

Co-authored-by: Emídio Neto <[email protected]>

---------

Co-authored-by: Riccardo Magliocchetti <[email protected]>
Co-authored-by: Emídio Neto <[email protected]>

Author: 3 people

CHANGELOG.md

@@ -17,6 +17,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   ([#3850](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3850))
 - `opentelemetry-instrumentation-httpx`: add support for url exclusions via `OTEL_PYTHON_EXCLUDED_URLS` / `OTEL_PYTHON_HTTPX_EXCLUDED_URLS`
   ([#3837](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3837))
+- `opentelemetry-instrumentation-flask`: improve readthedocs for sqlcommenter configuration.
+  ([#3883](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3883))
 
 ### Fixed
 

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

@@ -189,54 +189,66 @@ def response_hook(span: Span, status: str, response_headers: List):
 Note:
     The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change.
 
-SQLCOMMENTER
-*****************************************
-You can optionally configure Flask instrumentation to enable sqlcommenter which enriches
-the query with contextual information.
+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; /*framework=flask%%3A2.9.3*/"``. 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.flask import FlaskInstrumentor
 
-    FlaskInstrumentor().instrument(enable_commenter=True, commenter_options={})
-
-For example, FlaskInstrumentor when used with SQLAlchemyInstrumentor or Psycopg2Instrumentor,
-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:
-
-.. code::
-
-    select * from auth_users /*metrics=value*/;"
+    FlaskInstrumentor().instrument(enable_commenter=True)
 
-Inorder for the commenter to append flask related tags to sql queries, the commenter needs
-to enabled on the respective SQLAlchemyInstrumentor or Psycopg2Instrumentor framework too.
-
-SQLCommenter Configurations
-***************************
-We can configure the tags to be appended to the sqlquery log by adding configuration
-inside ``commenter_options={}`` dict.
-
-For example, enabling this flag will add flask and it's version which
-is ``/*flask%%3A2.9.3*/`` to the SQL query as a comment (default is True):
+Note:
+    FlaskInstrumentor sqlcommenter requires that sqlcommenter is also
+    enabled for an active instrumentation of a database driver or object-relational
+    mapper (ORM) in the same database client stack. The latter, such as
+    Psycopg2Instrumentor of SQLAlchemyInstrumentor, will create a base sqlcomment
+    that is enhanced by FlaskInstrumentor with additional values from context
+    before appending to the query statement.
+
+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
 
-    framework = True
-
-For example, enabling this flag will add route uri ``/*route='/home'*/``
-to the SQL query as a comment (default is True):
-
-.. code:: python
+    from opentelemetry.instrumentation.flask import FlaskInstrumentor
 
-    route = True
+    # Opts into sqlcomment for Flask trace integration.
+    # Opts out of tags for controller.
+    FlaskInstrumentor().instrument(
+        enable_commenter=True,
+        commenter_options={
+            "controller": False,
+        }
+    )
 
-For example, enabling this flag will add controller name ``/*controller='home_view'*/``
-to the SQL query as a comment (default is True):
+Available commenter_options
+###########################
 
-.. code:: python
+The following sqlcomment key-values can be opted out of through ``commenter_options``:
 
-    controller = True
++-------------------+----------------------------------------------------+----------------------------------------+
+| Commenter Option  | Description                                        | Example                                |
++===================+====================================================+========================================+
+| ``framework``     | Flask framework name with version (URL encoded).   | ``framework='flask%%%%3A2.9.3'``       |
++-------------------+----------------------------------------------------+----------------------------------------+
+| ``route``         | Flask route URI pattern.                           | ``route='/home'``                      |
++-------------------+----------------------------------------------------+----------------------------------------+
+| ``controller``    | Flask controller/endpoint name.                    | ``controller='home_view'``             |
++-------------------+----------------------------------------------------+----------------------------------------+
 
 API
 ---