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 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 ---