OpenTelemetry Psycopg2 Instrumentation
The integration with PostgreSQL supports the psycopg2 library. It can be enabled by
using Psycopg2Instrumentor.
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()
Configuration
SQLCommenter
You can optionally configure Psycopg2 instrumentation to 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:
from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
Psycopg2Instrumentor().instrument(enable_commenter=True)
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.
from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
# Opts into sqlcomment for Psycopg2 trace integration.
# Opts out of tags for libpq_version, db_driver.
Psycopg2Instrumentor().instrument(
enable_commenter=True,
commenter_options={
"libpq_version": False,
"db_driver": False,
}
)
Available commenter_options
The following sqlcomment key-values can be opted out of through commenter_options:
Commenter Option |
Description |
Example |
|---|---|---|
|
Database driver name with version. |
|
|
DB-API threadsafety value: 0-3 or unknown. |
|
|
DB-API API level: 1.0, 2.0, or unknown. |
|
|
DB-API paramstyle for SQL statement parameter. |
|
|
PostgreSQL libpq version |
|
|
OpenTelemetry context as traceparent at time of query. |
|
SQLComment in span attribute
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.
from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
# Opts into sqlcomment for Psycopg2 trace integration.
# Opts into sqlcomment for `db.statement` span attribute.
Psycopg2Instrumentor().instrument(
enable_commenter=True,
enable_attribute_commenter=True,
)
Warning
Capture of sqlcomment in db.statement may have high cardinality without platform normalization. See Semantic Conventions for database spans for more information.
Capture parameters
By default, only statements are captured, without the associated query parameters. To capture query parameters in the span attribute db.statement.parameters, enable capture_parameters.
from opentelemetry.instrumentation.psycopg2 import Psycopg2Instrumentor
Psycopg2Instrumentor().instrument(
capture_parameters=True,
)
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.
Uses _INSTRUMENTED_CONNECTIONS to store the original cursor_factory per connection.
- Parameters:
connection (
connection) – The psycopg2 connection object to be instrumented.tracer_provider (
Optional[TracerProvider]) – opentelemetry.trace.TracerProvider, optional The TracerProvider to use for instrumentation. If not specified, the global TracerProvider will be used.
- Return type:
- 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