OpenTelemetry Psycopg Instrumentation

The integration with PostgreSQL supports the Psycopg library, it can be enabled by using PsycopgInstrumentor.

SQLCOMMENTER

You can optionally configure Psycopg instrumentation to enable sqlcommenter which enriches the query with contextual information.

Usage

from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor

PsycopgInstrumentor().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 psycopg and it’s version which is /psycopg%%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 psycopg instrumentation to append sqlcomment to query span attribute for convenience of your platform.

from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor

PsycopgInstrumentor().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 psycopg
from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor

# Call instrument() to wrap all database connections
PsycopgInstrumentor().instrument()

cnx = psycopg.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 psycopg
from opentelemetry.instrumentation.psycopg import PsycopgInstrumentor

# Alternatively, use instrument_connection for an individual connection
cnx = psycopg.connect(database='Database')
instrumented_cnx = PsycopgInstrumentor().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.psycopg.PsycopgInstrumentor(*args, **kwargs)

Bases: BaseInstrumentor

instrumentation_dependencies()

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)

Enable instrumentation in a psycopg connection.

Parameters:

• connection (TypeVar(ConnectionT, Connection, AsyncConnection)) – psycopg.Connection The psycopg connection object to be instrumented.

• tracer_provider (Optional[TracerProvider]) – opentelemetry.trace.TracerProvider, optional The TracerProvider to use for instrumentation. If not provided, the global TracerProvider will be used.

Return type:

TypeVar(ConnectionT, Connection, AsyncConnection)

Returns:

An instrumented psycopg connection object.

static uninstrument_connection(connection)

Return type:

TypeVar(ConnectionT, Connection, AsyncConnection)

class opentelemetry.instrumentation.psycopg.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)

Bases: DatabaseApiIntegration

wrapped_connection(connect_method, args, kwargs)

Add object proxy to connection object.

class opentelemetry.instrumentation.psycopg.DatabaseApiAsyncIntegration(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)

Bases: DatabaseApiIntegration

async wrapped_connection(connect_method, args, kwargs)

Add object proxy to connection object.

class opentelemetry.instrumentation.psycopg.CursorTracer(db_api_integration)

Bases: CursorTracer

get_operation_name(cursor, args)

Return type:

str

get_statement(cursor, args)

Return type:

str