Skip to content

Commit 447aac2

Browse files
tammy-baylis-swixrmx
tammy-baylis-swi
and
xrmx
authored
Improve PyMySQL, mysqlclient, mysql-connector instrumentor docs' sqlcommenter info (#3885)
* Update PyMySQL docs * Update mysql-connector, mysqlclient docs around sqlcommenter * Changelog * Add warning about db.statement cardinality * whitespace --------- Co-authored-by: Riccardo Magliocchetti <[email protected]>
1 parent 425da56 commit 447aac2

File tree

4 files changed

+172
-177
lines changed
  • CHANGELOG.md
  • instrumentation
    • opentelemetry-instrumentation-mysqlclient/src/opentelemetry/instrumentation/mysqlclient
    • opentelemetry-instrumentation-mysql/src/opentelemetry/instrumentation/mysql
    • opentelemetry-instrumentation-pymysql/src/opentelemetry/instrumentation/pymysql

4 files changed

+172
-177
lines changed

‎CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
2121
([#3883](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3883))
2222
- `opentelemetry-instrumentation-sqlalchemy`: improve readthedocs for sqlcommenter configuration.
2323
([#3886](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3886))
24+
- `opentelemetry-instrumentation-mysql`, `opentelemetry-instrumentation-mysqlclient`, `opentelemetry-instrumentation-pymysql`: improve readthedocs for sqlcommenter configuration.
25+
([#3885](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3885))
2426

2527
### Fixed
2628

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

Lines changed: 60 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -53,90 +53,97 @@
5353
Configuration
5454
-------------
5555
56-
SQLCOMMENTER
57-
*****************************************
58-
You can optionally configure mysql-connector instrumentation to enable sqlcommenter which enriches the query with contextual information.
56+
SQLCommenter
57+
************
58+
You can optionally enable sqlcommenter which enriches the query with contextual
59+
information. Queries made after setting up trace integration with sqlcommenter
60+
enabled will have configurable key-value pairs appended to them, e.g.
61+
``"select * from auth_users; /*traceparent=00-01234567-abcd-01*/"``. This
62+
supports context propagation between database client and server when database log
63+
records are enabled. For more information, see:
64+
65+
* `Semantic Conventions - Database Spans <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md#sql-commenter>`_
66+
* `sqlcommenter <https://google.github.io/sqlcommenter/>`_
5967
6068
.. code:: python
6169
6270
import mysql.connector
6371
from opentelemetry.instrumentation.mysql import MySQLInstrumentor
6472
65-
MySQLInstrumentor().instrument(enable_commenter=True, commenter_options={})
73+
MySQLInstrumentor().instrument(enable_commenter=True)
6674
6775
cnx = mysql.connector.connect(database="MySQL_Database")
6876
cursor = cnx.cursor()
6977
cursor.execute("INSERT INTO test (testField) VALUES (123)")
7078
cursor.close()
7179
cnx.close()
7280
73-
For example,
74-
::
81+
Warning:
82+
sqlcommenter for mysql-connector instrumentation should NOT be used if your application initializes cursors with ``prepared=True``, which will natively prepare and execute MySQL statements. Adding sqlcommenting will introduce a severe performance penalty by repeating ``Prepare`` of statements by mysql-connector that are made unique by traceparent in sqlcomment. The penalty does not happen if cursor ``prepared=False`` (default) and instrumentor ``enable_commenter=True``.
7583
76-
Invoking cursor.execute("INSERT INTO test (testField) VALUES (123)") will lead to sql query "INSERT INTO test (testField) VALUES (123)" but when SQLCommenter is enabled
77-
the query will get appended with some configurable tags like "INSERT INTO test (testField) VALUES (123) /*tag=value*/;"
84+
SQLCommenter with commenter_options
85+
***********************************
86+
The key-value pairs appended to the query can be configured using
87+
``commenter_options``. When sqlcommenter is enabled, all available KVs/tags
88+
are calculated by default. ``commenter_options`` supports *opting out*
89+
of specific KVs.
7890
79-
**WARNING:** sqlcommenter for mysql-connector instrumentation should NOT be used if your application initializes cursors with ``prepared=True``, which will natively prepare and execute MySQL statements. Adding sqlcommenting will introduce a severe performance penalty by repeating ``Prepare`` of statements by mysql-connector that are made unique by traceparent in sqlcomment. The penalty does not happen if cursor ``prepared=False`` (default) and instrumentor ``enable_commenter=True``.
80-
81-
SQLCommenter Configurations
82-
***************************
83-
We can configure the tags to be appended to the sqlquery log by adding configuration inside commenter_options(default:{}) keyword
84-
85-
db_driver = True(Default) or False
86-
87-
For example,
88-
::
89-
Enabling this flag will add mysql.connector and its version, e.g. /*mysql.connector%%3A1.2.3*/
90-
91-
dbapi_threadsafety = True(Default) or False
92-
93-
For example,
94-
::
95-
Enabling this flag will add threadsafety /*dbapi_threadsafety=2*/
96-
97-
dbapi_level = True(Default) or False
98-
99-
For example,
100-
::
101-
Enabling this flag will add dbapi_level /*dbapi_level='2.0'*/
102-
103-
mysql_client_version = True(Default) or False
104-
105-
For example,
106-
::
107-
Enabling this flag will add mysql_client_version /*mysql_client_version='123'*/
108-
109-
driver_paramstyle = True(Default) or False
91+
.. code:: python
11092
111-
For example,
112-
::
113-
Enabling this flag will add driver_paramstyle /*driver_paramstyle='pyformat'*/
93+
import mysql.connector
94+
from opentelemetry.instrumentation.mysql import MySQLInstrumentor
11495
115-
opentelemetry_values = True(Default) or False
96+
# Opts into sqlcomment for mysql-connector trace integration.
97+
# Opts out of tags for mysql_client_version, db_driver.
98+
MySQLInstrumentor().instrument(
99+
enable_commenter=True,
100+
commenter_options={
101+
"mysql_client_version": False,
102+
"db_driver": False,
103+
}
104+
)
116105
117-
For example,
118-
::
119-
Enabling this flag will add traceparent values /*traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'*/
106+
Available commenter_options
107+
###########################
108+
109+
The following sqlcomment key-values can be opted out of through ``commenter_options``:
110+
111+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
112+
| Commenter Option | Description | Example |
113+
+===========================+===========================================================+===========================================================================+
114+
| ``db_driver`` | Database driver name with version (URL encoded). | ``mysql.connector%%%%3A2.2.9`` |
115+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
116+
| ``dbapi_threadsafety`` | DB-API threadsafety value: 0-3 or unknown. | ``dbapi_threadsafety=2`` |
117+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
118+
| ``dbapi_level`` | DB-API API level: 1.0, 2.0, or unknown. | ``dbapi_level='2.0'`` |
119+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
120+
| ``driver_paramstyle`` | DB-API paramstyle for SQL statement parameter. | ``driver_paramstyle='pyformat'`` |
121+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
122+
| ``mysql_client_version`` | MySQL client version. | ``mysql_client_version='123'`` |
123+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
124+
| ``opentelemetry_values`` | OpenTelemetry context as traceparent at time of query. | ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` |
125+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
120126
121127
SQLComment in span attribute
122128
****************************
123-
If sqlcommenter is enabled, you can optionally configure mysql-connector instrumentation to append sqlcomment to query span attribute for convenience of your platform.
129+
If sqlcommenter is enabled, you can opt into the inclusion of sqlcomment in
130+
the query span ``db.statement`` attribute for your needs. If ``commenter_options``
131+
have been set, the span attribute comment will also be configured by this
132+
setting.
124133
125134
.. code:: python
126135
127136
from opentelemetry.instrumentation.mysql import MySQLInstrumentor
128137
138+
# Opts into sqlcomment for mysql-connector trace integration.
139+
# Opts into sqlcomment for `db.statement` span attribute.
129140
MySQLInstrumentor().instrument(
130141
enable_commenter=True,
131142
enable_attribute_commenter=True,
132143
)
133144
134-
135-
For example,
136-
::
137-
138-
Invoking cursor.execute("select * from auth_users") will lead to sql query "select * from auth_users" but when SQLCommenter and attribute_commenter are enabled
139-
the query will get appended with some configurable tags like "select * from auth_users /*tag=value*/;" for both server query and `db.statement` span attribute.
145+
Warning:
146+
Capture of sqlcomment in ``db.statement`` may have high cardinality without platform normalization. See `Semantic Conventions for database spans <https://opentelemetry.io/docs/specs/semconv/database/database-spans/#generating-a-summary-of-the-query-text>`_ for more information.
140147
141148
API
142149
---

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

Lines changed: 52 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -39,18 +39,24 @@
3939
Configuration
4040
-------------
4141
42-
SQLCOMMENTER
43-
*****************************************
44-
You can optionally configure MySQLClient instrumentation to enable sqlcommenter which enriches
45-
the query with contextual information.
42+
SQLCommenter
43+
************
44+
You can optionally enable sqlcommenter which enriches the query with contextual
45+
information. Queries made after setting up trace integration with sqlcommenter
46+
enabled will have configurable key-value pairs appended to them, e.g.
47+
``"select * from auth_users; /*traceparent=00-01234567-abcd-01*/"``. This
48+
supports context propagation between database client and server when database log
49+
records are enabled. For more information, see:
50+
51+
* `Semantic Conventions - Database Spans <https://github.com/open-telemetry/semantic-conventions/blob/main/docs/database/database-spans.md#sql-commenter>`_
52+
* `sqlcommenter <https://google.github.io/sqlcommenter/>`_
4653
4754
.. code:: python
4855
4956
import MySQLdb
5057
from opentelemetry.instrumentation.mysqlclient import MySQLClientInstrumentor
5158
52-
# Call instrument() to wrap all database connections
53-
MySQLClientInstrumentor().instrument(enable_commenter=True, commenter_options={})
59+
MySQLClientInstrumentor().instrument(enable_commenter=True)
5460
5561
cnx = MySQLdb.connect(database="MySQL_Database")
5662
cursor = cnx.cursor()
@@ -60,94 +66,69 @@
6066
cursor.close()
6167
cnx.close()
6268
69+
SQLCommenter with commenter_options
70+
***********************************
71+
The key-value pairs appended to the query can be configured using
72+
``commenter_options``. When sqlcommenter is enabled, all available KVs/tags
73+
are calculated by default. ``commenter_options`` supports *opting out*
74+
of specific KVs.
75+
6376
.. code:: python
6477
6578
import MySQLdb
6679
from opentelemetry.instrumentation.mysqlclient import MySQLClientInstrumentor
6780
68-
# Alternatively, use instrument_connection for an individual connection
69-
cnx = MySQLdb.connect(database="MySQL_Database")
70-
instrumented_cnx = MySQLClientInstrumentor().instrument_connection(
71-
cnx,
81+
# Opts into sqlcomment for MySQLClient trace integration.
82+
# Opts out of tags for mysql_client_version, db_driver.
83+
MySQLClientInstrumentor().instrument(
7284
enable_commenter=True,
7385
commenter_options={
74-
"db_driver": True,
75-
"mysql_client_version": True,
76-
"driver_paramstyle": False
86+
"mysql_client_version": False,
87+
"db_driver": False,
7788
}
7889
)
79-
cursor = instrumented_cnx.cursor()
80-
cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)")
81-
cursor.execute("INSERT INTO test (testField) VALUES (123)")
82-
instrumented_cnx.commit()
83-
cursor.close()
84-
instrumented_cnx.close()
85-
86-
For example,
87-
::
88-
89-
Invoking cursor.execute("INSERT INTO test (testField) VALUES (123)") will lead to sql query "INSERT INTO test (testField) VALUES (123)" but when SQLCommenter is enabled
90-
the query will get appended with some configurable tags like "INSERT INTO test (testField) VALUES (123) /*tag=value*/;"
91-
92-
SQLCommenter Configurations
93-
***************************
94-
We can configure the tags to be appended to the sqlquery log by adding configuration inside commenter_options(default:{}) keyword
95-
96-
db_driver = True(Default) or False
97-
98-
For example,
99-
::
100-
Enabling this flag will add MySQLdb and its version, e.g. /*MySQLdb%%3A1.2.3*/
10190
102-
dbapi_threadsafety = True(Default) or False
103-
104-
For example,
105-
::
106-
Enabling this flag will add threadsafety /*dbapi_threadsafety=2*/
107-
108-
dbapi_level = True(Default) or False
109-
110-
For example,
111-
::
112-
Enabling this flag will add dbapi_level /*dbapi_level='2.0'*/
113-
114-
mysql_client_version = True(Default) or False
115-
116-
For example,
117-
::
118-
Enabling this flag will add mysql_client_version /*mysql_client_version='123'*/
119-
120-
driver_paramstyle = True(Default) or False
121-
122-
For example,
123-
::
124-
Enabling this flag will add driver_paramstyle /*driver_paramstyle='pyformat'*/
125-
126-
opentelemetry_values = True(Default) or False
127-
128-
For example,
129-
::
130-
Enabling this flag will add traceparent values /*traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'*/
91+
Available commenter_options
92+
###########################
93+
94+
The following sqlcomment key-values can be opted out of through ``commenter_options``:
95+
96+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
97+
| Commenter Option | Description | Example |
98+
+===========================+===========================================================+===========================================================================+
99+
| ``db_driver`` | Database driver name with version (URL encoded). | ``MySQLdb%%%%3A1.2.3`` |
100+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
101+
| ``dbapi_threadsafety`` | DB-API threadsafety value: 0-3 or unknown. | ``dbapi_threadsafety=2`` |
102+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
103+
| ``dbapi_level`` | DB-API API level: 1.0, 2.0, or unknown. | ``dbapi_level='2.0'`` |
104+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
105+
| ``driver_paramstyle`` | DB-API paramstyle for SQL statement parameter. | ``driver_paramstyle='pyformat'`` |
106+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
107+
| ``mysql_client_version`` | MySQL client version. | ``mysql_client_version='123'`` |
108+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
109+
| ``opentelemetry_values`` | OpenTelemetry context as traceparent at time of query. | ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` |
110+
+---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+
131111
132112
SQLComment in span attribute
133113
****************************
134-
If sqlcommenter is enabled, you can optionally configure MySQLClient instrumentation to append sqlcomment to query span attribute for convenience of your platform.
114+
If sqlcommenter is enabled, you can opt into the inclusion of sqlcomment in
115+
the query span ``db.statement`` attribute for your needs. If ``commenter_options``
116+
have been set, the span attribute comment will also be configured by this
117+
setting.
135118
136119
.. code:: python
137120
138121
from opentelemetry.instrumentation.mysqlclient import MySQLClientInstrumentor
139122
123+
# Opts into sqlcomment for mysqlclient trace integration.
124+
# Opts into sqlcomment for `db.statement` span attribute.
140125
MySQLClientInstrumentor().instrument(
141126
enable_commenter=True,
142127
enable_attribute_commenter=True,
143128
)
144129
145-
146-
For example,
147-
::
148-
149-
Invoking cursor.execute("select * from auth_users") will lead to sql query "select * from auth_users" but when SQLCommenter and attribute_commenter are enabled
150-
the query will get appended with some configurable tags like "select * from auth_users /*tag=value*/;" for both server query and `db.statement` span attribute.
130+
Warning:
131+
Capture of sqlcomment in ``db.statement`` may have high cardinality without platform normalization. See `Semantic Conventions for database spans <https://opentelemetry.io/docs/specs/semconv/database/database-spans/#generating-a-summary-of-the-query-text>`_ for more information.
151132
152133
API
153134
---

0 commit comments

Comments
 (0)