Package io.opentelemetry.instrumentation.api.incubator.semconv.db

Interface SqlClientAttributesGetter<REQUEST,RESPONSE>

All Superinterfaces:

DbClientAttributesGetter<REQUEST,RESPONSE>, io.opentelemetry.instrumentation.api.semconv.network.NetworkAttributesGetter<REQUEST,RESPONSE>, io.opentelemetry.instrumentation.api.semconv.network.ServerAttributesGetter<REQUEST>

public interface SqlClientAttributesGetter<REQUEST,RESPONSE>
extends DbClientAttributesGetter<REQUEST,RESPONSE>

An interface for getting SQL database client attributes.

Instrumentation authors will create implementations of this interface for their specific library/framework. It will be used by the SqlClientAttributesExtractor to obtain the various SQL database client attributes in a type-generic way.

If an attribute is not available in this library, it is appropriate to return null from the attribute methods, but implement as many as possible for best compliance with the OpenTelemetry specification.

Method Summary

Modifier and Type	Method	Description
default String	getDbCollectionName(REQUEST request)	SQL instrumentations must not override or call this method.
default String	getDbOperationName(REQUEST request)	SQL instrumentations must not override or call this method.
default String	getDbQuerySummary(REQUEST request)	SQL instrumentations must not override or call this method.
default String	getDbQueryText(REQUEST request)	SQL instrumentations must not override or call this method.
Collection<String>	getRawQueryTexts(REQUEST request)	Get the raw SQL query texts.
default Collection<String>	getRawQueryTextsForOldSemconv(REQUEST request)	Deprecated. This method supports old database semantic conventions and will be removed in 3.0.
SqlDialect	getSqlDialect(REQUEST request)	Returns the SQL dialect used by the database.
default boolean	isParameterizedQuery(REQUEST request, int queryIndex)	Returns whether the query at queryIndex in getRawQueryTexts(Object) is parameterized.

Methods inherited from interface io.opentelemetry.instrumentation.api.incubator.semconv.db.DbClientAttributesGetter

getConnectionString, getDbName, getDbNamespace, getDbOperation, getDbOperationBatchSize, getDbQueryParameters, getDbSystem, getDbSystemName, getErrorType, getUser

Methods inherited from interface io.opentelemetry.instrumentation.api.semconv.network.NetworkAttributesGetter

getNetworkLocalAddress, getNetworkLocalInetSocketAddress, getNetworkLocalPort, getNetworkPeerAddress, getNetworkPeerInetSocketAddress, getNetworkPeerPort, getNetworkProtocolName, getNetworkProtocolVersion, getNetworkTransport, getNetworkType

Methods inherited from interface io.opentelemetry.instrumentation.api.semconv.network.ServerAttributesGetter

getServerAddress, getServerPort

Method Details

getDbOperationName

default String getDbOperationName(REQUEST request)

SQL instrumentations must not override or call this method.

Provide raw query text through getRawQueryTexts(REQUEST) instead. When the database system does not support query text with multiple operations in non-batch operations, enable SqlClientAttributesExtractorBuilder.setSingleOperationAndCollection(boolean) and SqlClientAttributesExtractor will derive db.operation.name from db.query.text.

Specified by:

getDbOperationName in interface DbClientAttributesGetter<REQUEST,RESPONSE>

Throws:

UnsupportedOperationException - always

getDbQueryText

default String getDbQueryText(REQUEST request)

SQL instrumentations must not override or call this method.

Provide raw query text through getRawQueryTexts(REQUEST) instead. SqlClientAttributesExtractor will derive db.query.text from the raw query text.

Specified by:

getDbQueryText in interface DbClientAttributesGetter<REQUEST,RESPONSE>

Throws:

UnsupportedOperationException - always

getDbQuerySummary

default String getDbQuerySummary(REQUEST request)

SQL instrumentations must not override or call this method.

Provide raw query text through getRawQueryTexts(REQUEST) instead. SqlClientAttributesExtractor will derive db.query.summary from the raw query text.

Specified by:

getDbQuerySummary in interface DbClientAttributesGetter<REQUEST,RESPONSE>

Throws:

UnsupportedOperationException - always

getDbCollectionName

default String getDbCollectionName(REQUEST request)

SQL instrumentations must not override or call this method.

Provide raw query text through getRawQueryTexts(REQUEST) instead. When the database system does not support query text with multiple collections in non-batch operations, enable SqlClientAttributesExtractorBuilder.setSingleOperationAndCollection(boolean) and SqlClientAttributesExtractor will derive db.collection.name from db.query.text. Do not enable that option when the database system supports query text with multiple collections in non-batch operations.

Specified by:

getDbCollectionName in interface DbClientAttributesGetter<REQUEST,RESPONSE>

Throws:

UnsupportedOperationException - always

getSqlDialect

SqlDialect getSqlDialect(REQUEST request)

Returns the SQL dialect used by the database.

getRawQueryTexts

Collection<String> getRawQueryTexts(REQUEST request)

Get the raw SQL query texts. The values returned by this method are later sanitized by the SqlClientAttributesExtractor before being set as span attribute.

If request is not a batch query, then this method should return a collection with a single element.

getRawQueryTextsForOldSemconv

@Deprecated
default Collection<String> getRawQueryTextsForOldSemconv(REQUEST request)

Deprecated.

This method supports old database semantic conventions and will be removed in 3.0.

Returns the raw SQL query texts used to derive old semantic convention attributes and span names.

By default, this returns getRawQueryTexts(Object). Instrumentations may override this method when preserving old semantic convention telemetry requires a different query representation.

isParameterizedQuery

default boolean isParameterizedQuery(REQUEST request,
 int queryIndex)

Returns whether the query at queryIndex in getRawQueryTexts(Object) is parameterized. Prepared statements are always considered parameterized even if no parameters are bound. By using a parameterized query the user is giving a strong signal that any sensitive data will be passed as parameter values, and so the query does not need to be sanitized. See sanitization of db.query.text.

The queryIndex is zero-based and follows the iteration order of getRawQueryTexts(Object). This supports batch operations where individual entries may have different parameterization.