From 7ffbe30a41361a2d172132f28f866afdcdf375b0 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 17 Oct 2025 19:00:53 -0700 Subject: [PATCH 1/4] Improve Django sqlcomment readthedocs --- .../instrumentation/django/__init__.py | 99 +++++++++---------- 1 file changed, 48 insertions(+), 51 deletions(-) diff --git a/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py b/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py index ebc3e08f4d..96284990a9 100644 --- a/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py @@ -170,10 +170,18 @@ def response_hook(span, request, response): Note: The environment variable names used to capture HTTP headers are still experimental, and thus are subject to change. -SQLCOMMENTER -***************************************** -You can optionally configure Django 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. +``Users().objects.all()`` will result in +``"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 `_ +* `sqlcommenter `_ .. code:: python @@ -181,53 +189,42 @@ def response_hook(span, request, response): DjangoInstrumentor().instrument(is_sql_commentor_enabled=True) - -For example, -:: - - Invoking Users().objects.all() 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 /*metrics=value*/;" - - -SQLCommenter Configurations -*************************** -We can configure the tags to be appended to the sqlquery log by adding below variables to the settings.py - -SQLCOMMENTER_WITH_FRAMEWORK = True(Default) or False - -For example, -:: -Enabling this flag will add django framework and it's version which is /*framework='django%3A2.2.3*/ - -SQLCOMMENTER_WITH_CONTROLLER = True(Default) or False - -For example, -:: -Enabling this flag will add controller name that handles the request /*controller='index'*/ - -SQLCOMMENTER_WITH_ROUTE = True(Default) or False - -For example, -:: -Enabling this flag will add url path that handles the request /*route='polls/'*/ - -SQLCOMMENTER_WITH_APP_NAME = True(Default) or False - -For example, -:: -Enabling this flag will add app name that handles the request /*app_name='polls'*/ - -SQLCOMMENTER_WITH_OPENTELEMETRY = True(Default) or False - -For example, -:: -Enabling this flag will add opentelemetry traceparent /*traceparent='00-fd720cffceba94bbf75940ff3caaf3cc-4fd1a2bdacf56388-01'*/ - -SQLCOMMENTER_WITH_DB_DRIVER = True(Default) or False - -For example, -:: -Enabling this flag will add name of the db driver /*db_driver='django.db.backends.postgresql'*/ +Warning: + Duplicate sqlcomments may be appended to the sqlquery log if DjangoInstrumentor + sqlcommenter is enabled in addition to sqlcommenter for an active instrumention + of a database driver or object relation mapper (ORM) in the same database client + stack. For example, if psycopg2 driver is used and Psycopg2Instrumentor has + sqlcommenter enabled, then both DjangoInstrumentor and Psycopg2Instrumentor will + append comments to the query statement. + +SQLCommenter with commenter_options +*********************************** +The key-value pairs appended to the query can be configured using +variables in Django ``settings.py``. When sqlcommenter is enabled, all +available KVs/tags are calculated by default, i.e. ``True`` for each. The +``settings.py`` values support *opting out* of specific KVs. + +Available settings.py commenter options +####################################### + +We can configure the tags to be appended to the sqlquery log by adding below variables to +``settings.py``, e.g. ``SQLCOMMENTER_WITH_FRAMEWORK = False`` + ++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``settings.py`` variable | Description | Example | ++=====================================+===========================================================+===========================================================================+ +| ``SQLCOMMENTER_WITH_FRAMEWORK`` | Django framework name with version (URL encoded). | ``framework='django%%%%3A4.2.0'`` | ++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``SQLCOMMENTER_WITH_CONTROLLER`` | Django controller/view name that handles the request. | ``controller='index'`` | ++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``SQLCOMMENTER_WITH_ROUTE`` | URL path pattern that handles the request. | ``route='polls/'`` | ++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``SQLCOMMENTER_WITH_APP_NAME`` | Django app name that handles the request. | ``app_name='polls'`` | ++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``SQLCOMMENTER_WITH_OPENTELEMETRY`` | OpenTelemetry context as traceparent at time of query. | ``traceparent='00-fd720cffceba94bbf75940ff3caaf3cc-4fd1a2bdacf56388-01'`` | ++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``SQLCOMMENTER_WITH_DB_DRIVER`` | Database driver name used by Django. | ``db_driver='django.db.backends.postgresql'`` | ++-------------------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ API --- From 064f7c05bc55e7f23fe19b9d12d050f397b56c89 Mon Sep 17 00:00:00 2001 From: tammy-baylis-swi Date: Fri, 17 Oct 2025 19:02:20 -0700 Subject: [PATCH 2/4] Changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 024990c91d..71f86abac5 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-django`: improve readthedocs for sqlcommenter configuration. + ([#3884](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3884)) + ## Version 1.38.0/0.59b0 (2025-10-16) ### Fixed From fb94d2f0b8ff373e367127482372918475c1627c Mon Sep 17 00:00:00 2001 From: Tammy Baylis <96076570+tammy-baylis-swi@users.noreply.github.com> Date: Thu, 30 Oct 2025 09:03:29 -0700 Subject: [PATCH 3/4] Update instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__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/django/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py b/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py index 96284990a9..f5fa985494 100644 --- a/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py @@ -192,7 +192,7 @@ def response_hook(span, request, response): Warning: Duplicate sqlcomments may be appended to the sqlquery log if DjangoInstrumentor sqlcommenter is enabled in addition to sqlcommenter for an active instrumention - of a database driver or object relation mapper (ORM) in the same database client + of a database driver or object-relational mapper (ORM) in the same database client stack. For example, if psycopg2 driver is used and Psycopg2Instrumentor has sqlcommenter enabled, then both DjangoInstrumentor and Psycopg2Instrumentor will append comments to the query statement. From 9f84955b2ca95bac0703155ce97feb0b3617ba54 Mon Sep 17 00:00:00 2001 From: Tammy Baylis <96076570+tammy-baylis-swi@users.noreply.github.com> Date: Thu, 30 Oct 2025 09:03:38 -0700 Subject: [PATCH 4/4] Update instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__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/django/__init__.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py b/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py index f5fa985494..054036defd 100644 --- a/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-django/src/opentelemetry/instrumentation/django/__init__.py @@ -191,7 +191,7 @@ def response_hook(span, request, response): Warning: Duplicate sqlcomments may be appended to the sqlquery log if DjangoInstrumentor - sqlcommenter is enabled in addition to sqlcommenter for an active instrumention + sqlcommenter is enabled in addition to sqlcommenter for an active instrumentation of a database driver or object-relational mapper (ORM) in the same database client stack. For example, if psycopg2 driver is used and Psycopg2Instrumentor has sqlcommenter enabled, then both DjangoInstrumentor and Psycopg2Instrumentor will