OpenTelemetry Psycopg2 Instrumentation
The integration with PostgreSQL supports the Psycopg library, it can be enabled by
using Psycopg2Instrumentor
.
SQLCOMMENTER
You can optionally configure Psycopg2 instrumentation to enable sqlcommenter which enriches the query with contextual information.
Usage
from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
Psycopg2Instrumentor().instrument(enable_commenter=True, commenter_options={})
For example,
Invoking cursor.execute("select * from auth_users") will lead to sql query "select * from auth_users" but when SQLCommenter is enabled
the query will get appended with some configurable tags like "select * from auth_users /*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 psycopg2 and it’s version which is /psycopg2%%3A2.9.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’/
libpq_version = True(Default) or False
For example, :: Enabling this flag will add libpq_version /libpq_version=140001/
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’/
SQLComment in span attribute
If sqlcommenter is enabled, you can optionally configure psycopg2 instrumentation to append sqlcomment to query span attribute for convenience of your platform.
from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
Psycopg2Instrumentor().instrument(
enable_commenter=True,
enable_attribute_commenter=True,
)
For example,
Invoking cursor.execute("select * from auth_users") will lead to postgresql 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.
Usage
import psycopg2
from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
# Call instrument() to wrap all database connections
Psycopg2Instrumentor().instrument()
cnx = psycopg2.connect(database='Database')
cursor = cnx.cursor()
cursor.execute("CREATE TABLE IF NOT EXISTS test (testField INTEGER)")
cursor.execute("INSERT INTO test (testField) VALUES (123)")
cursor.close()
cnx.close()
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("CREATE TABLE IF NOT EXISTS test (testField INTEGER)")
cursor.execute("INSERT INTO test (testField) VALUES (123)")
cursor.close()
instrumented_cnx.close()
API
- class opentelemetry.instrumentation.psycopg2.Psycopg2Instrumentor(*args, **kwargs)[source]
Bases:
BaseInstrumentor
- instrumentation_dependencies()[source]
Return a list of python packages with versions that the will be instrumented.
The format should be the same as used in requirements.txt or pyproject.toml.
For example, if an instrumentation instruments requests 1.x, this method should look like: :rtype:
Collection
[str
]- def instrumentation_dependencies(self) -> Collection[str]:
return [‘requests ~= 1.0’]
This will ensure that the instrumentation will only be used when the specified library is present in the environment.
- static instrument_connection(connection, tracer_provider=None)[source]
Enable instrumentation in a psycopg2 connection.
- Parameters:
connection – psycopg2.extensions.connection The psycopg2 connection object to be instrumented.
tracer_provider – opentelemetry.trace.TracerProvider, optional The TracerProvider to use for instrumentation. If not specified, the global TracerProvider will be used.
- Returns:
An instrumented psycopg2 connection object.
- class opentelemetry.instrumentation.psycopg2.DatabaseApiIntegration(name, database_system, connection_attributes=None, version='', tracer_provider=None, capture_parameters=False, enable_commenter=False, commenter_options=None, connect_module=None, enable_attribute_commenter=False)[source]
Bases:
DatabaseApiIntegration