Skip to content

Commit 02fedf3

Browse files
tammy-baylis-swixrmx
tammy-baylis-swi
and
xrmx
authored
Update DB-API instrumentor readthedocs with sqlcommenter guide (open-telemetry#3720)
* Update DB-API integration docs * Add more wrap_connect info * Add DB-API docs SQLCommenter Configurations * Emphasize framework/orm-specific instrumentors first * Table instead of numbered list commenter options * Update wording * Add docs SQLComment in span attribute * Adjust wording * Changelog * Rm repeated link defs * Reduce duplicate text, update doc header * Update CHANGELOG.md --------- Co-authored-by: Riccardo Magliocchetti <[email protected]>
1 parent 302ffe2 commit 02fedf3

File tree

2 files changed

+137
-6
lines changed

2 files changed

+137
-6
lines changed

‎CHANGELOG.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,14 +20,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2020

2121
### Added
2222

23-
- `opentelemetry-instrumentation`: botocore: Add support for AWS Secrets Manager semantic convention attribute
23+
- `opentelemetry-instrumentation-botocore`: Add support for AWS Secrets Manager semantic convention attribute
2424
([#3765](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3765))
2525
- Add `rstcheck` to pre-commit to stop introducing invalid RST
2626
([#3777](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3777))
2727
- `opentelemetry-exporter-credential-provider-gcp`: create this package which provides support for supplying your machine's Application Default
2828
Credentials (https://cloud.google.com/docs/authentication/application-default-credentials) to the OTLP Exporters created automatically by OpenTelemetry Python's auto instrumentation. These credentials authorize OTLP traces to be sent to `telemetry.googleapis.com`. [#3766](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3766).
29-
- `opentelemetry-instrumentation-psycopg` Add missing parameter `capture_parameters` to instrumentor.
29+
- `opentelemetry-instrumentation-psycopg`: Add missing parameter `capture_parameters` to instrumentor.
3030
([#3676](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3676))
31+
- `opentelemetry-instrumentation-dbapi`: Adds sqlcommenter to documentation.
32+
([#3720](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3720))
3133

3234
## Version 1.37.0/0.58b0 (2025-09-11)
3335

‎instrumentation/opentelemetry-instrumentation-dbapi/src/opentelemetry/instrumentation/dbapi/__init__.py‎

Lines changed: 133 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,19 +20,148 @@
2020
Usage
2121
-----
2222
23+
The DB-API instrumentor and its utilities provide common, core functionality for
24+
database framework or object relation mapper (ORM) instrumentations. Users will
25+
typically instrument database client code with those framework/ORM-specific
26+
instrumentations, instead of directly using this DB-API integration. Features
27+
such as sqlcommenter can be configured at framework/ORM level as well. See full
28+
list at `instrumentation`_.
29+
30+
.. _instrumentation: https://github.com/open-telemetry/opentelemetry-python-contrib/tree/main/instrumentation
31+
32+
If an instrumentation for your needs does not exist, then DB-API integration can
33+
be used directly as follows.
34+
35+
2336
.. code-block:: python
2437
2538
import mysql.connector
2639
import pyodbc
2740
28-
from opentelemetry.instrumentation.dbapi import trace_integration
29-
41+
from opentelemetry.instrumentation.dbapi import (
42+
trace_integration,
43+
wrap_connect,
44+
)
3045
31-
# Ex: mysql.connector
46+
# Example: mysql.connector
3247
trace_integration(mysql.connector, "connect", "mysql")
33-
# Ex: pyodbc
48+
# Example: pyodbc
3449
trace_integration(pyodbc, "Connection", "odbc")
3550
51+
# Or, directly call wrap_connect for more configurability.
52+
wrap_connect(__name__, mysql.connector, "connect", "mysql")
53+
wrap_connect(__name__, pyodbc, "Connection", "odbc")
54+
55+
56+
Configuration
57+
-------------
58+
59+
SQLCommenter
60+
************
61+
You can optionally enable sqlcommenter which enriches the query with contextual
62+
information. Queries made after setting up trace integration with sqlcommenter
63+
enabled will have configurable key-value pairs appended to them, e.g.
64+
``"select * from auth_users; /*traceparent=00-01234567-abcd-01*/"``. This
65+
supports context propagation between database client and server when database log
66+
records are enabled. For more information, see:
67+
68+
* `Semantic Conventions - Database Spans <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md#sql-commenter>`_
69+
* `sqlcommenter <https://google.github.io/sqlcommenter/>`_
70+
71+
.. code:: python
72+
73+
import mysql.connector
74+
75+
from opentelemetry.instrumentation.dbapi import wrap_connect
76+
77+
78+
# Opts into sqlcomment for MySQL trace integration.
79+
wrap_connect(
80+
__name__,
81+
mysql.connector,
82+
"connect",
83+
"mysql",
84+
enable_commenter=True,
85+
)
86+
87+
88+
SQLCommenter with commenter_options
89+
***********************************
90+
The key-value pairs appended to the query can be configured using
91+
``commenter_options``. When sqlcommenter is enabled, all available KVs/tags
92+
are calculated by default. ``commenter_options`` supports *opting out*
93+
of specific KVs.
94+
95+
.. code:: python
96+
97+
import mysql.connector
98+
99+
from opentelemetry.instrumentation.dbapi import wrap_connect
100+
101+
102+
# Opts into sqlcomment for MySQL trace integration.
103+
# Opts out of tags for libpq_version, db_driver.
104+
wrap_connect(
105+
__name__,
106+
mysql.connector,
107+
"connect",
108+
"mysql",
109+
enable_commenter=True,
110+
commenter_options={
111+
"libpq_version": False,
112+
"db_driver": False,
113+
}
114+
)
115+
116+
Available commenter_options
117+
###########################
118+
119+
The following sqlcomment key-values can be opted out of through ``commenter_options``:
120+
121+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
122+
| Commenter Option | Description | Example |
123+
+===========================+===========================================================+===========================================================================+
124+
| ``db_driver`` | Database driver name with version. | ``mysql.connector=2.2.9`` |
125+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
126+
| ``dbapi_threadsafety`` | DB-API threadsafety value: 0-3 or unknown. | ``dbapi_threadsafety=2`` |
127+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
128+
| ``dbapi_level`` | DB-API API level: 1.0, 2.0, or unknown. | ``dbapi_level=2.0`` |
129+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
130+
| ``driver_paramstyle`` | DB-API paramstyle for SQL statement parameter. | ``driver_paramstyle='pyformat'`` |
131+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
132+
| ``libpq_version`` | PostgreSQL libpq version (checked for PostgreSQL only). | ``libpq_version=140001`` |
133+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
134+
| ``mysql_client_version`` | MySQL client version (checked for MySQL only). | ``mysql_client_version='123'`` |
135+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
136+
| ``opentelemetry_values`` | OpenTelemetry context as traceparent at time of query. | ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` |
137+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
138+
139+
SQLComment in span attribute
140+
****************************
141+
If sqlcommenter is enabled, you can opt into the inclusion of sqlcomment in
142+
the query span ``db.statement`` attribute for your needs. If ``commenter_options``
143+
have been set, the span attribute comment will also be configured by this
144+
setting.
145+
146+
.. code:: python
147+
148+
import mysql.connector
149+
150+
from opentelemetry.instrumentation.dbapi import wrap_connect
151+
152+
153+
# Opts into sqlcomment for MySQL trace integration.
154+
# Opts into sqlcomment for `db.statement` span attribute.
155+
wrap_connect(
156+
__name__,
157+
mysql.connector,
158+
"connect",
159+
"mysql",
160+
enable_commenter=True,
161+
enable_attribute_commenter=True,
162+
)
163+
164+
36165
API
37166
---
38167
"""

0 commit comments

Comments
 (0)