diff --git a/CHANGELOG.md b/CHANGELOG.md index 024990c91d..522379945b 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-mysql`, `opentelemetry-instrumentation-mysqlclient`, `opentelemetry-instrumentation-pymysql`: improve readthedocs for sqlcommenter configuration. + ([#3885](https://github.com/open-telemetry/opentelemetry-python-contrib/pull/3885)) + ## Version 1.38.0/0.59b0 (2025-10-16) ### Fixed diff --git a/instrumentation/opentelemetry-instrumentation-mysql/src/opentelemetry/instrumentation/mysql/__init__.py b/instrumentation/opentelemetry-instrumentation-mysql/src/opentelemetry/instrumentation/mysql/__init__.py index 0d30036707..0f344fada2 100644 --- a/instrumentation/opentelemetry-instrumentation-mysql/src/opentelemetry/instrumentation/mysql/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-mysql/src/opentelemetry/instrumentation/mysql/__init__.py @@ -53,16 +53,24 @@ Configuration ------------- -SQLCOMMENTER -***************************************** -You can optionally configure mysql-connector 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; /*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 import mysql.connector from opentelemetry.instrumentation.mysql import MySQLInstrumentor - MySQLInstrumentor().instrument(enable_commenter=True, commenter_options={}) + MySQLInstrumentor().instrument(enable_commenter=True) cnx = mysql.connector.connect(database="MySQL_Database") cursor = cnx.cursor() @@ -70,73 +78,72 @@ cursor.close() cnx.close() -For example, -:: +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``. - 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 - the query will get appended with some configurable tags like "INSERT INTO test (testField) VALUES (123) /*tag=value*/;" +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. -**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``. - -SQLCommenter Configurations -*************************** -We can configure the tags to be appended to the sqlquery log by adding configuration inside commenter_options(default:{}) keyword - -db_driver = True(Default) or False - -For example, -:: -Enabling this flag will add mysql.connector and its version, e.g. /*mysql.connector%%3A1.2.3*/ - -dbapi_threadsafety = True(Default) or False - -For example, -:: -Enabling this flag will add threadsafety /*dbapi_threadsafety=2*/ - -dbapi_level = True(Default) or False - -For example, -:: -Enabling this flag will add dbapi_level /*dbapi_level='2.0'*/ - -mysql_client_version = True(Default) or False - -For example, -:: -Enabling this flag will add mysql_client_version /*mysql_client_version='123'*/ - -driver_paramstyle = True(Default) or False +.. code:: python -For example, -:: -Enabling this flag will add driver_paramstyle /*driver_paramstyle='pyformat'*/ + import mysql.connector + from opentelemetry.instrumentation.mysql import MySQLInstrumentor -opentelemetry_values = True(Default) or False + # Opts into sqlcomment for mysql-connector trace integration. + # Opts out of tags for mysql_client_version, db_driver. + MySQLInstrumentor().instrument( + enable_commenter=True, + commenter_options={ + "mysql_client_version": False, + "db_driver": False, + } + ) -For example, -:: -Enabling this flag will add traceparent values /*traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'*/ +Available commenter_options +########################### + +The following sqlcomment key-values can be opted out of through ``commenter_options``: + ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| Commenter Option | Description | Example | ++===========================+===========================================================+===========================================================================+ +| ``db_driver`` | Database driver name with version (URL encoded). | ``mysql.connector%%%%3A2.2.9`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``dbapi_threadsafety`` | DB-API threadsafety value: 0-3 or unknown. | ``dbapi_threadsafety=2`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``dbapi_level`` | DB-API API level: 1.0, 2.0, or unknown. | ``dbapi_level='2.0'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``driver_paramstyle`` | DB-API paramstyle for SQL statement parameter. | ``driver_paramstyle='pyformat'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``mysql_client_version`` | MySQL client version. | ``mysql_client_version='123'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``opentelemetry_values`` | OpenTelemetry context as traceparent at time of query. | ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ SQLComment in span attribute **************************** -If sqlcommenter is enabled, you can optionally configure mysql-connector instrumentation to append sqlcomment to query span attribute for convenience of your platform. +If sqlcommenter is enabled, you can opt into the inclusion of sqlcomment in +the query span ``db.statement`` attribute for your needs. If ``commenter_options`` +have been set, the span attribute comment will also be configured by this +setting. .. code:: python from opentelemetry.instrumentation.mysql import MySQLInstrumentor + # Opts into sqlcomment for mysql-connector trace integration. + # Opts into sqlcomment for `db.statement` span attribute. MySQLInstrumentor().instrument( enable_commenter=True, enable_attribute_commenter=True, ) - -For example, -:: - - Invoking cursor.execute("select * from auth_users") will lead to sql query "select * from auth_users" but when SQLCommenter and attribute_commenter are enabled - 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. +Warning: + Capture of sqlcomment in ``db.statement`` may have high cardinality without platform normalization. See `Semantic Conventions for database spans `_ for more information. API --- diff --git a/instrumentation/opentelemetry-instrumentation-mysqlclient/src/opentelemetry/instrumentation/mysqlclient/__init__.py b/instrumentation/opentelemetry-instrumentation-mysqlclient/src/opentelemetry/instrumentation/mysqlclient/__init__.py index 553d4574aa..fb08600505 100644 --- a/instrumentation/opentelemetry-instrumentation-mysqlclient/src/opentelemetry/instrumentation/mysqlclient/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-mysqlclient/src/opentelemetry/instrumentation/mysqlclient/__init__.py @@ -39,18 +39,24 @@ Configuration ------------- -SQLCOMMENTER -***************************************** -You can optionally configure MySQLClient 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; /*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 import MySQLdb from opentelemetry.instrumentation.mysqlclient import MySQLClientInstrumentor - # Call instrument() to wrap all database connections - MySQLClientInstrumentor().instrument(enable_commenter=True, commenter_options={}) + MySQLClientInstrumentor().instrument(enable_commenter=True) cnx = MySQLdb.connect(database="MySQL_Database") cursor = cnx.cursor() @@ -60,94 +66,69 @@ cursor.close() cnx.close() +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 import MySQLdb from opentelemetry.instrumentation.mysqlclient import MySQLClientInstrumentor - # Alternatively, use instrument_connection for an individual connection - cnx = MySQLdb.connect(database="MySQL_Database") - instrumented_cnx = MySQLClientInstrumentor().instrument_connection( - cnx, + # Opts into sqlcomment for MySQLClient trace integration. + # Opts out of tags for mysql_client_version, db_driver. + MySQLClientInstrumentor().instrument( enable_commenter=True, commenter_options={ - "db_driver": True, - "mysql_client_version": True, - "driver_paramstyle": False + "mysql_client_version": False, + "db_driver": False, } ) - cursor = instrumented_cnx.cursor() - cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)") - cursor.execute("INSERT INTO test (testField) VALUES (123)") - instrumented_cnx.commit() - cursor.close() - instrumented_cnx.close() - -For example, -:: - - 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 - the query will get appended with some configurable tags like "INSERT INTO test (testField) VALUES (123) /*tag=value*/;" - -SQLCommenter Configurations -*************************** -We can configure the tags to be appended to the sqlquery log by adding configuration inside commenter_options(default:{}) keyword - -db_driver = True(Default) or False - -For example, -:: -Enabling this flag will add MySQLdb and its version, e.g. /*MySQLdb%%3A1.2.3*/ -dbapi_threadsafety = True(Default) or False - -For example, -:: -Enabling this flag will add threadsafety /*dbapi_threadsafety=2*/ - -dbapi_level = True(Default) or False - -For example, -:: -Enabling this flag will add dbapi_level /*dbapi_level='2.0'*/ - -mysql_client_version = True(Default) or False - -For example, -:: -Enabling this flag will add mysql_client_version /*mysql_client_version='123'*/ - -driver_paramstyle = True(Default) or False - -For example, -:: -Enabling this flag will add driver_paramstyle /*driver_paramstyle='pyformat'*/ - -opentelemetry_values = True(Default) or False - -For example, -:: -Enabling this flag will add traceparent values /*traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'*/ +Available commenter_options +########################### + +The following sqlcomment key-values can be opted out of through ``commenter_options``: + ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| Commenter Option | Description | Example | ++===========================+===========================================================+===========================================================================+ +| ``db_driver`` | Database driver name with version (URL encoded). | ``MySQLdb%%%%3A1.2.3`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``dbapi_threadsafety`` | DB-API threadsafety value: 0-3 or unknown. | ``dbapi_threadsafety=2`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``dbapi_level`` | DB-API API level: 1.0, 2.0, or unknown. | ``dbapi_level='2.0'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``driver_paramstyle`` | DB-API paramstyle for SQL statement parameter. | ``driver_paramstyle='pyformat'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``mysql_client_version`` | MySQL client version. | ``mysql_client_version='123'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``opentelemetry_values`` | OpenTelemetry context as traceparent at time of query. | ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ SQLComment in span attribute **************************** -If sqlcommenter is enabled, you can optionally configure MySQLClient instrumentation to append sqlcomment to query span attribute for convenience of your platform. +If sqlcommenter is enabled, you can opt into the inclusion of sqlcomment in +the query span ``db.statement`` attribute for your needs. If ``commenter_options`` +have been set, the span attribute comment will also be configured by this +setting. .. code:: python from opentelemetry.instrumentation.mysqlclient import MySQLClientInstrumentor + # Opts into sqlcomment for mysqlclient trace integration. + # Opts into sqlcomment for `db.statement` span attribute. MySQLClientInstrumentor().instrument( enable_commenter=True, enable_attribute_commenter=True, ) - -For example, -:: - - Invoking cursor.execute("select * from auth_users") will lead to sql query "select * from auth_users" but when SQLCommenter and attribute_commenter are enabled - 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. +Warning: + Capture of sqlcomment in ``db.statement`` may have high cardinality without platform normalization. See `Semantic Conventions for database spans `_ for more information. API --- diff --git a/instrumentation/opentelemetry-instrumentation-pymysql/src/opentelemetry/instrumentation/pymysql/__init__.py b/instrumentation/opentelemetry-instrumentation-pymysql/src/opentelemetry/instrumentation/pymysql/__init__.py index 2c8951385e..587aafbd55 100644 --- a/instrumentation/opentelemetry-instrumentation-pymysql/src/opentelemetry/instrumentation/pymysql/__init__.py +++ b/instrumentation/opentelemetry-instrumentation-pymysql/src/opentelemetry/instrumentation/pymysql/__init__.py @@ -62,17 +62,24 @@ Configuration ------------- -SQLCOMMENTER -***************************************** -You can optionally configure PyMySQL 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; /*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 import pymysql from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor - PyMySQLInstrumentor().instrument(enable_commenter=True, commenter_options={}) + PyMySQLInstrumentor().instrument(enable_commenter=True) cnx = pymysql.connect(database="MySQL_Database") cursor = cnx.cursor() @@ -82,71 +89,69 @@ cursor.close() cnx.close() -For example, -:: +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. - 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 - the query will get appended with some configurable tags like "INSERT INTO test (testField) VALUES (123) /*tag=value*/;" - - -SQLCommenter Configurations -*************************** -We can configure the tags to be appended to the sqlquery log by adding configuration inside commenter_options(default:{}) keyword - -db_driver = True(Default) or False - -For example, -:: -Enabling this flag will add pymysql and its version, e.g. /*pymysql%%3A1.2.3*/ - -dbapi_threadsafety = True(Default) or False - -For example, -:: -Enabling this flag will add threadsafety /*dbapi_threadsafety=2*/ - -dbapi_level = True(Default) or False - -For example, -:: -Enabling this flag will add dbapi_level /*dbapi_level='2.0'*/ - -mysql_client_version = True(Default) or False - -For example, -:: -Enabling this flag will add mysql_client_version /*mysql_client_version='123'*/ - -driver_paramstyle = True(Default) or False +.. code:: python -For example, -:: -Enabling this flag will add driver_paramstyle /*driver_paramstyle='pyformat'*/ + import pymysql + from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor -opentelemetry_values = True(Default) or False + # Opts into sqlcomment for PyMySQL trace integration. + # Opts out of tags for mysql_client_version, db_driver. + PyMySQLInstrumentor().instrument( + enable_commenter=True, + commenter_options={ + "mysql_client_version": False, + "db_driver": False, + } + ) -For example, -:: -Enabling this flag will add traceparent values /*traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'*/ +Available commenter_options +########################### + +The following sqlcomment key-values can be opted out of through ``commenter_options``: + ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| Commenter Option | Description | Example | ++===========================+===========================================================+===========================================================================+ +| ``db_driver`` | Database driver name with version. | ``pymysql='1.2.3'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``dbapi_threadsafety`` | DB-API threadsafety value: 0-3 or unknown. | ``dbapi_threadsafety=2`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``dbapi_level`` | DB-API API level: 1.0, 2.0, or unknown. | ``dbapi_level='2.0'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``driver_paramstyle`` | DB-API paramstyle for SQL statement parameter. | ``driver_paramstyle='pyformat'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``mysql_client_version`` | MySQL client version. | ``mysql_client_version='123'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ +| ``opentelemetry_values`` | OpenTelemetry context as traceparent at time of query. | ``traceparent='00-03afa25236b8cd948fa853d67038ac79-405ff022e8247c46-01'`` | ++---------------------------+-----------------------------------------------------------+---------------------------------------------------------------------------+ SQLComment in span attribute **************************** -If sqlcommenter is enabled, you can optionally configure PyMySQL instrumentation to append sqlcomment to query span attribute for convenience of your platform. +If sqlcommenter is enabled, you can opt into the inclusion of sqlcomment in +the query span ``db.statement`` attribute for your needs. If ``commenter_options`` +have been set, the span attribute comment will also be configured by this +setting. .. code:: python from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor + # Opts into sqlcomment for PyMySQL trace integration. + # Opts into sqlcomment for `db.statement` span attribute. PyMySQLInstrumentor().instrument( enable_commenter=True, enable_attribute_commenter=True, ) -For example, -:: - - Invoking cursor.execute("select * from auth_users") will lead to sql query "select * from auth_users" but when SQLCommenter and attribute_commenter are enabled - 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. +Warning: + Capture of sqlcomment in ``db.statement`` may have high cardinality without platform normalization. See `Semantic Conventions for database spans `_ for more information. API ---