Separate instrument_connection() docstring block for mysql, mysqlclient, psycopg, psycopg2, pymysql, sqlite3

Author: beijiez

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

@@ -26,6 +26,7 @@
     import mysql.connector
     from opentelemetry.instrumentation.mysql import MySQLInstrumentor
 
+    # Call instrument() to wrap all database connections
     MySQLInstrumentor().instrument()
 
     cnx = mysql.connector.connect(database="MySQL_Database")
@@ -34,11 +35,18 @@
     cursor.close()
     cnx.close()
 
-    cnx = MySQLInstrumentor().instrument_connection(cnx)
-    cursor = cnx.cursor()
+.. code:: python
+
+    import mysql.connector
+    from opentelemetry.instrumentation.mysql import MySQLInstrumentor
+
+    # Alternatively, use instrument_connection for an individual connection
+    cnx = mysql.connector.connect(database="MySQL_Database")
+    instrumented_cnx = MySQLInstrumentor().instrument_connection(cnx)
+    cursor = instrumented_cnx.cursor()
     cursor.execute("INSERT INTO test (testField) VALUES (123)")
     cursor.close()
-    cnx.close()
+    instrumented_cnx.close()
 
 API
 ---

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

@@ -46,7 +46,7 @@
     import MySQLdb
     from opentelemetry.instrumentation.mysqlclient import MySQLClientInstrumentor
 
-
+    # Call instrument() to wrap all database connections
     MySQLClientInstrumentor().instrument(enable_commenter=True, commenter_options={})
 
     cnx = MySQLdb.connect(database="MySQL_Database")
@@ -56,6 +56,13 @@
     cursor.close()
     cnx.close()
 
+.. 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,
         enable_commenter=True,

instrumentation/opentelemetry-instrumentation-psycopg/src/opentelemetry/instrumentation/psycopg/__init__.py

@@ -88,7 +88,7 @@
     import psycopg
     from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor
 
-
+    # Call instrument() to wrap all database connections
     PsycopgInstrumentor().instrument()
 
     cnx = psycopg.connect(database='Database')
@@ -98,6 +98,13 @@
     cursor.close()
     cnx.close()
 
+.. code-block:: python
+
+    import psycopg
+    from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor
+
+    # Alternatively, use instrument_connection for an individual connection
+    cnx = psycopg.connect(database='Database')
     instrumented_cnx = instrument_connection(cnx)
     cursor = instrumented_cnx.cursor()
     cursor.execute("INSERT INTO test (testField) VALUES (123)")

instrumentation/opentelemetry-instrumentation-psycopg2/src/opentelemetry/instrumentation/psycopg2/__init__.py

@@ -88,7 +88,7 @@
     import psycopg2
     from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
 
-
+    # Call instrument() to wrap all database connections
     Psycopg2Instrumentor().instrument()
 
     cnx = psycopg2.connect(database='Database')
@@ -98,6 +98,13 @@
     cursor.close()
     cnx.close()
 
+.. code-block:: python
+
+    import psycopg2
+    from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
+
+    # Alternatively, use instrument_connection for an individual connection
+    cnx = psycopg2.connect(database='Database')
     instrumented_cnx = Psycopg2Instrumentor.instrument_connection(cnx)
     cursor = instrumented_cnx.cursor()
     cursor.execute("INSERT INTO test (testField) VALUES (123)")

instrumentation/opentelemetry-instrumentation-pymysql/src/opentelemetry/instrumentation/pymysql/__init__.py

@@ -26,6 +26,7 @@
     import pymysql
     from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor
 
+    # Call instrument() to wrap all database connections
     PyMySQLInstrumentor().instrument()
 
     cnx = pymysql.connect(database="MySQL_Database")
@@ -35,6 +36,28 @@
     cursor.close()
     cnx.close()
 
+
+.. code:: python
+
+    import pymysql
+    from opentelemetry.instrumentation.pymysql import PyMySQLInstrumentor
+
+    # Alternatively, use instrument_connection for an individual connection
+    cnx = pymysql.connect(database="MySQL_Database")
+    instrumented_cnx = PyMySQLInstrumentor().instrument_connection(
+        cnx,
+        enable_commenter=True,
+        commenter_options={
+            "db_driver": True,
+            "mysql_client_version": True
+        }
+    )
+    cursor = instrumented_cnx.cursor()
+    cursor.execute("INSERT INTO test (testField) VALUES (123)"
+    instrumented_cnx.commit()
+    cursor.close()
+    instrumented_cnx.close()
+
 SQLCOMMENTER
 *****************************************
 You can optionally configure PyMySQL instrumentation to enable sqlcommenter which enriches
@@ -57,20 +80,6 @@
     cursor.close()
     cnx.close()
 
-    instrumented_cnx = PyMySQLInstrumentor().instrument_connection(
-        cnx,
-        enable_commenter=True,
-        commenter_options={
-            "db_driver": True,
-            "mysql_client_version": True
-        }
-    )
-    cursor = instrumented_cnx.cursor()
-    cursor.execute("INSERT INTO test (testField) VALUES (123)"
-    instrumented_cnx.commit()
-    cursor.close()
-    instrumented_cnx.close()
-
 
 For example,
 ::

instrumentation/opentelemetry-instrumentation-sqlite3/src/opentelemetry/instrumentation/sqlite3/__init__.py

@@ -27,7 +27,7 @@
     import sqlite3
     from opentelemetry.instrumentation.sqlite3 import SQLite3Instrumentor
 
-
+    # Call instrument() to wrap all database connections
     SQLite3Instrumentor().instrument()
 
     cnx = sqlite3.connect(':memory:')
@@ -36,6 +36,13 @@
     cursor.execute("INSERT INTO test (testField) VALUES (123)")
     cursor.close()
     cnx.close()
+
+.. code:: python
+
+    import sqlite3
+    from opentelemetry.instrumentation.sqlite3 import SQLite3Instrumentor
+
+    # Alternatively, use instrument_connection for an individual connection
     conn = sqlite3.connect(":memory:")
     instrumented_connection = SQLite3Instrumentor.instrument_connection(conn)
     cursor = instrumented_connection.cursor()