Add docstring for instrument_connection for aiopg and mysqlclient

open-telemetry · Dec 13, 2024 · db31f28 · db31f28
1 parent 4369a05
commit db31f28
Show file tree

Hide file tree

Showing 3 changed files with 53 additions and 10 deletions.
diff --git a/...n/opentelemetry-instrumentation-aiopg/src/opentelemetry/instrumentation/aiopg/__init__.py b/...n/opentelemetry-instrumentation-aiopg/src/opentelemetry/instrumentation/aiopg/__init__.py
@@ -35,12 +35,19 @@
     cnx.close()
 
     pool = await aiopg.create_pool(database='Database')
+    
     cnx = await pool.acquire()
     cursor = await cnx.cursor()
     await cursor.execute("INSERT INTO test (testField) VALUES (123)")
     cursor.close()
     cnx.close()
-
+    
+    cnx = AiopgInstrumentor().instrument_connection(cnx)
+    cursor = await cnx.cursor()
+    await cursor.execute("INSERT INTO test (testField) VALUES (123)")
+    cursor.close()
+    cnx.close()
+    
 API
 ---
 """

diff --git a/...n/opentelemetry-instrumentation-mysql/src/opentelemetry/instrumentation/mysql/__init__.py b/...n/opentelemetry-instrumentation-mysql/src/opentelemetry/instrumentation/mysql/__init__.py
@@ -92,12 +92,16 @@ def instrument_connection(self, connection, tracer_provider=None):
         """Enable instrumentation in a MySQL connection.
 
         Args:
-            connection: The connection to instrument.
-            tracer_provider: The optional tracer provider to use. If omitted
-                the current globally configured one is used.
+            connection (mysql.connector.Connection):
+                The existing MySQL connection instance to instrument. This connection is typically
+                obtained through `mysql.connector.connect()` and is instrumented to collect telemetry
+                data about database interactions.
+            tracer_provider (TracerProvider, optional):
+                An optional `TracerProvider` instance to use for tracing. If not provided, the globally
+                configured tracer provider will be automatically used.
 
         Returns:
-            An instrumented connection.
+            An instrumented MySQL connection with OpenTelemetry tracing enabled,
         """
         return dbapi.instrument_connection(
             __name__,

diff --git a/...try-instrumentation-mysqlclient/src/opentelemetry/instrumentation/mysqlclient/__init__.py b/...try-instrumentation-mysqlclient/src/opentelemetry/instrumentation/mysqlclient/__init__.py
@@ -55,6 +55,21 @@
     cnx.commit()
     cursor.close()
     cnx.close()
+    
+    instrumented_connection = MySQLClientInstrumentor.instrument_connection(
+        cnx,
+        enable_commenter=True,
+        commenter_options={
+            "db_driver": True,
+            "mysql_client_version": True,
+            "driver_paramstyle": False
+            }
+        )
+    cursor = instrumented_connection.cursor()
+    cursor.execute("INSERT INTO test (testField) VALUES (123)"
+    instrumented_connection.commit()
+    cursor.close()
+    instrumented_connection.close()
 
 For example,
 ::
@@ -162,12 +177,29 @@ def instrument_connection(
         """Enable instrumentation in a mysqlclient connection.
 
         Args:
-            connection: The connection to instrument.
-            tracer_provider: The optional tracer provider to use. If omitted
-                the current globally configured one is used.
-
+            connection (MySQLdb.connect or Connection object):
+                The MySQL connection instance to instrument. This connection is typically
+                created using `MySQLdb.connect()` and needs to be wrapped to collect telemetry.
+            tracer_provider (TracerProvider, optional):
+                A custom `TracerProvider` instance to be used for tracing. If not specified,
+                the globally configured tracer provider will be used.
+            enable_commenter (bool, optional):
+                A flag to enable the OpenTelemetry SQLCommenter feature. If set to `True`,
+                SQL queries will be enriched with contextual information (e.g., database client details).
+                Default is `None`.
+            commenter_options (dict, optional):
+                A dictionary of configuration options for SQLCommenter. This allows you to customize
+                metadata appended to queries. Possible options include:
+                    - `db_driver`: Adds the database driver name and version.
+                    - `dbapi_threadsafety`: Adds threadsafety information.
+                    - `dbapi_level`: Adds the DB-API version.
+                    - `mysql_client_version`: Adds the MySQL client version.
+                    - `driver_paramstyle`: Adds the parameter style.
+                    - `opentelemetry_values`: Includes traceparent values.
+                Refer to *SQLCommenter Configurations* above for more information
+                
         Returns:
-            An instrumented connection.
+            An instrumented MySQL connection with OpenTelemetry support enabled.
         """
 
         return dbapi.instrument_connection(