From 0735f240d3c1780cdf35a31ee333315d457929d7 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 17 Oct 2025 18:10:51 -0700 Subject: [PATCH 1/4] Clean up FlaskInstrumentor readthedocs sqlcommenter --- .../instrumentation/flask/__init__.py | 82 +++++++++++-------- 1 file changed, 47 insertions(+), 35 deletions(-) diff --git a/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py b/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py index 57f0f75ca3..fbed9b16cd 100644 --- a/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py +++ b/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 `_ +* `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 instrumention of a database driver or object relation + 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). | ``flask%%%%3A2.9.3`` | ++-------------------+----------------------------------------------------+----------------------------+ +| ``route`` | Flask route URI pattern. | ``route='/home'`` | ++-------------------+----------------------------------------------------+----------------------------+ +| ``controller`` | Flask controller/endpoint name. | ``controller='home_view'`` | ++-------------------+----------------------------------------------------+----------------------------+ API --- From 563f28541838dfbf7d84d778d6f0a025edd0cc29 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 17 Oct 2025 18:13:33 -0700 Subject: [PATCH 2/4] Fix quotes --- .../instrumentation/flask/__init__.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py b/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py index fbed9b16cd..756af87aca 100644 --- a/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py @@ -240,15 +240,15 @@ def response_hook(span: Span, status: str, response_headers: List): The following sqlcomment key-values can be opted out of through ``commenter_options``: -+-------------------+----------------------------------------------------+----------------------------+ -| Commenter Option | Description | Example | -+===================+====================================================+============================+ -| ``framework`` | Flask framework name with version (URL encoded). | ``flask%%%%3A2.9.3`` | -+-------------------+----------------------------------------------------+----------------------------+ -| ``route`` | Flask route URI pattern. | ``route='/home'`` | -+-------------------+----------------------------------------------------+----------------------------+ -| ``controller`` | Flask controller/endpoint name. | ``controller='home_view'`` | -+-------------------+----------------------------------------------------+----------------------------+ ++-------------------+----------------------------------------------------+----------------------------------------+ +| 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 --- From 8c070e6ea719f35a512da9f9943ba25d4ca72453 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 17 Oct 2025 18:15:12 -0700 Subject: [PATCH 3/4] Changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 024990c91d..70a568b963 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## Unreleased +- `opentelemetry-instrumentation-flask`: improve readthedocs for sqlcommenter configuration. + ([#3883](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3883)) + ## Version 1.38.0/0.59b0 (2025-10-16) ### Fixed From a976e85800ed48fb24cd08ef6ce14f830868ea42 Mon Sep 17 00:00:00 2001 From: Riccardo Magliocchetti Date: Thu, 30 Oct 2025 12:04:13 +0100 Subject: [PATCH 4/4] Update instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Emídio Neto <9735060+emdneto@users.noreply.github.com> --- .../src/opentelemetry/instrumentation/flask/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py b/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py index 756af87aca..5c4ec91bc5 100644 --- a/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-flask/src/opentelemetry/instrumentation/flask/__init__.py @@ -209,7 +209,7 @@ def response_hook(span: Span, status: str, response_headers: List): Note: FlaskInstrumentor sqlcommenter requires that sqlcommenter is also - enabled for an active instrumention of a database driver or object relation + 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