Database performance
title: Database performance description: Find slow database calls and repeated query families in collected traces.
Open Metrics → Traces → Database performance to find expensive database operations and inspect their supporting request traces. Select a period, service or database system. Detection thresholds are adjustable for each report.
Connect database spans
Use the existing OpenTelemetry connection with a secret ingest key for the intended application and environment. Export database spans with these attributes:
| Field | Example | Purpose |
|---|---|---|
| Span kind | CLIENT |
A database call observed by your application |
service.name resource |
checkout-api |
Groups calls by service |
db.system.name |
postgresql |
Database system |
db.operation.name |
SELECT |
Operation type |
db.query.summary |
SELECT orders |
Optional stable query-family label |
| Parent span | Active request or operation | Connects calls to their request and sibling calls |
Legacy db.system and db.operation attributes also work. Prefer the stable names. The Python OpenTelemetry integration forwards the same safe summary attribute.
Use a fixed label such as SELECT orders, not a query body or a dynamically generated customer identifier. Labels accept at most 255 ASCII letters, digits, spaces and _ . : / -, starting with a letter or underscore. SQL operators, quotes, comments and literal-bearing clause keywords are rejected. Common credentials, emails, IP addresses and URLs are also refused. This restricted label check is not a SQL anonymizer; configure instrumentation to supply technical labels without personal data.
Raw db.query.text, db.statement, query parameters and explain plans are discarded. The collector does not extract summaries from SQL text. Existing retained spans without a summary remain useful for operation-level timing; repeated-query detection begins when summarized spans arrive.
Read the findings
| Finding | Meaning |
|---|---|
| Slow call | One database client span takes at least 100 ms by default |
| Repeated-call candidate | At least five calls with the same service, system, operation and summary share a collected parent and total at least 50 ms |
| p95 duration | 95th percentile of retained individual database calls |
| Combined duration | Sum of database call durations, including overlapping calls |
Choose a query family to see up to 20 of its slowest supporting spans. Each links directly to the corresponding span in the request timeline, with parent and release context when available. Families without a summary group by operation only and never generate repeated-query candidates. Calls whose parent was not collected also cannot establish repeated siblings.
Repeated calls can indicate an N+1 loop, retries or intentional repeated work. Inspect the trace before deciding. Client spans include pool, driver and network time; their durations do not measure database CPU time. Summed durations are not request latency.
Scope and limits
Reports use the current trace collection policy and retained data only. Sampling, missing parents and collector limits can hide work; totals are not extrapolated. Filtering by service or database system also changes the report's denominators. The selected period filters individual call start times, and an expired parent trace hides its children immediately.
The report supports 1 hour to 30 days, capped by effective trace retention. It returns 25 families per page, ordered by combined duration, with 20 evidence spans at most. Collection retains at most 200,000 spans per environment and 2,000 per trace, subject to the existing byte and daily budgets. No additional database payload is stored by this report.
Reading requires the Metrics module and metrics.read. The Management API equivalent is GET /api/v1/apps/{app}/metrics/traces/database?env=production, using a Management token. Filters: range, service, system, slowMs, repeatCount, repeatMs, group and page. Trace deletion and retention immediately remove corresponding evidence from the report.
Semantic references: OpenTelemetry database spans and SQL conventions.