iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
OpenTelemetry can show a database call as part of an application request by recording the logical database operation as a client span and linking it to the active trace context. That gives you visibility into what the application asked the database client to do; it does not, by itself, trace work inside the database server. Server-side visibility and client/server correlation require support from the particular driver, database, and server configuration.
How a database call becomes part of an application trace
A trace is a collection of related spans. Each span represents a unit of work and can include a name, parent span ID, timestamps, trace context, attributes, events, and status. The active context lets instrumentation establish parent-child relationships, so a database operation can appear beneath the application work that triggered it. OpenTelemetry describes these concepts in its tracing documentation.
In a typical request, framework instrumentation creates a server span when the application receives a request. Instrumentation for code and libraries creates additional spans, and database-client instrumentation records the logical database operation as a child span. The trace exporter then sends the data to standard output for local debugging, an OpenTelemetry Collector, or a tracing backend. A Collector or backend receives and processes telemetry; it does not replace instrumentation in the application or database driver.
Instrument the logical database operation
The database span should represent the logical request made to the database. OpenTelemetry library guidance distinguishes that work from the physical network activity used to carry it: the database library should trace the logical database request, while lower-level networking libraries should trace their own network requests when appropriate. Instrumenting the same logical operation at both layers can make a trace misleading by counting one action twice. See the library instrumentation guidance.
#1 Best Overall
Database calls are generally represented with a span of kind CLIENT, because the database usually runs in another process or is reached over a protocol. The right boundary depends on the API: a higher-level operation such as a stored-procedure call may know more about what the application requested than a generic query layer does. The database span conventions describe client spans and their attributes.
Check which database conventions your instrumentation emits
Database semantic conventions are evolving. The conventions page currently labels their overall status “Mixed”: it covers database client spans, metrics, and exceptions, but individual conventions can have different stability statuses. Instrumentations using v1.24.0 or earlier are advised not to silently change their emitted conventions by default within the same major version.
The conventions document OTEL_SEMCONV_STABILITY_OPT_IN=database for opting into stable database conventions instead of the prior experimental conventions, and database/dup for emitting both sets during a phased migration. Do not assume these options behave identically in every integration. Check the exact instrumentation library version and its migration notes, then inspect emitted spans to confirm the attributes and names your collector receives. Details are in the database semantic conventions.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Keep query attributes useful without exposing sensitive data
Query text can contain personal information, secrets, or other sensitive values, and even sanitized text can be long and high-cardinality. The conventions say db.query.text should be collected by default only when sanitization removes sensitive information. Sanitization should replace literal values with placeholders. Parameterized query text is not subject to that sanitization rule, but you should still assess what your application sends and how your instrumentation captures it.
For a compact, lower-cardinality description, use db.query.summary where the instrumentation supports it. It should be short and must not contain dynamic or sensitive data. Do not use raw query text as a metric label: distinct query strings can create unbounded label values. The database span conventions define these query attributes and their handling.
Know what client spans do—and do not—show
A client span can show that the application issued a database operation, its timing, and the attributes the instrumentation captured. It does not automatically show how the database server executed that operation. Context propagation correlates spans across instrumented boundaries, but making trace context visible in server logs or server-side instrumentation can require a database-specific bridge, compatible driver and server support, and server configuration.
Oracle illustrates why this is database-specific rather than automatic. Its conventions describe driver mechanisms for carrying context and require compatible driver and server support; end-to-end tracing works only when server-side tracing is explicitly configured. Oracle context may persist as session state, so instrumentation must scope or clear it as needed to prevent pooled sessions from applying stale context to later statements. Supported APIs differ by language and driver. Confirm the versions and setup requirements in the Oracle database conventions.
Use SQL commenter only when the database integration supports it
SQL commenter can append trace context to query comments so database-side logs can associate a statement with an application trace. It is optional and database-aware, not a prerequisite for ordinary client tracing. The semantic conventions state: “SQL commenter-based context propagation SHOULD NOT be enabled by default, but instrumentation MAY allow users to opt into it.” High-cardinality comments can also affect performance on some database systems.
Best Value
For example, the Python DB-API instrumentation documentation describes an optional SQL commenter integration. When enabled, configured key-value context is appended to queries; the documentation describes client/server propagation when database log records are enabled. That behavior is specific to the integration and should not be assumed for other languages or drivers.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Choose an export destination after instrumentation works
During development, an exporter can write spans to standard output. For collection and processing, spans can be sent to an OpenTelemetry Collector or an open-source or vendor backend. Treat these as separate decisions: instrumentation generates spans and propagates context, while collectors and backends receive, process, store, or display them. A backend cannot reconstruct a database span that the application’s instrumentation never created.
- Confirm the application framework and database driver are instrumented for the language and versions you use.
- Verify that a database operation appears as a client span under the expected request context.
- Check the emitted semantic-convention version and query-data settings.
- Decide whether client-side timing is sufficient or database-specific server-side correlation is required.
- Configure an exporter and collector or backend to receive the resulting trace data.
OpenTelemetry’s tracing documentation describes supported export paths and trace structure.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
