When to use this pattern
Use this pattern when request latency or errors appear around database operations, or when application connection pools are under pressure.
Investigation flow
- Start with the affected service, environment, operation, and request trace. Identify the database target and recorded client calls.
- Separate connection acquisition, retries, network time, and query duration where instrumentation provides those measurements.
- Match database observations using target identity, time, and a normalized query group or a supported explicit trace association.
- Compare equivalent queries and unaffected callers. Check waits, locks, and pool occupancy before choosing which part of the path to change.
Required fields
| Field or dimension | Purpose |
|---|---|
| service, environment, and trace context | Preserve the application request scope when opening database-related telemetry. |
| database target and namespace | Distinguish database instances and logical databases; map available attributes such as server.address and db.namespace. |
| normalized query summary or fingerprint | Compare the same query class without depending on literal values. |
| pool acquisition timing and query timing | Separate waiting for an application connection from work observed at the database. |
Worked example: A connection wait looks like a slow database request
Checkout calls involving the database take two seconds. Separate acquisition measurements show a 1.8-second wait for a pooled connection, while the query completes in about 100 ms. The application pool and the lifecycle of its connections are better starting points than a query rewrite. Database-side waits may still explain why connections remain occupied, so inspect both sides.
| Evidence | Observation |
|---|---|
| Application | Recorded pool acquisition wait is 1.8 seconds. |
| Query | The matching query executes in approximately 100 ms. |
| Next check | Compare occupied connections, query waits, and connection release behavior. |
Limitations and false matches
- A client span measures an instrumented operation; its boundaries may include retries or waits beyond database execution.
- A query fingerprint groups similar queries and is not an identifier for one execution.
- Database-side trace correlation requires supported drivers, agents, and propagation settings; service-level associations are less specific than request-level links.
- Use sanitized query details. Raw SQL literals and parameters can expose data without improving the join.
Verification checklist
- Run a known request and confirm the application identifies the intended database target.
- Verify which time intervals the client instrumentation measures, especially pool acquisition and retries.
- Confirm an explicit database association resolves to the same request when supported; otherwise label the comparison as aggregate evidence.
Supported by
Documented examples, not an exhaustive compatibility list. Features require suitable instrumentation and configuration; availability can depend on the runtime, backend, and subscription.
- OpenTelemetry — Database client conventions describe target and query attributes; available fields depend on instrumentation.
- Datadog APM and Database Monitoring — Supported integrations associate APM and database observations using configured propagation; service and full trace modes have different scope.
Related signals
Related concepts
Related patterns
Related guides
FAQ
Does a long database client span prove the query was slow?
No. Its duration depends on the instrumentation boundaries. Separate client-side waiting and retries from evidence of query execution and database waits.