feat(traces): OTel database query span support + SQLCommenter correlation

[Makisuo]

What & why

Foundation for database query observability, built entirely off the db.* OpenTelemetry semantic-convention spans that instrumented apps already emit — no connection, no configuration. It benefits every DB-instrumented service (Postgres / MySQL / ClickHouse / Redis / …), not just one engine.

This came out of a customer request for native ClickHouse query timing + resource allocation. The ask splits cleanly by what telemetry can supply it:

• Query timing correlated with traces → the client-side OTel DB span the app already emits (this PR).
• Resource allocation (memory, rows/bytes scanned, ProfileEvents) → only ClickHouse system.query_log has it → a follow-up poller (see below).

So this PR is the broadly-useful OTel-SQL foundation; ClickHouse-specific work layers on top.

Changes

• Generic database span adapter — packages/ui/src/lib/cloud-platforms/database.ts. Detects db.system.name (with legacy db.system fallback) on any DB-client span and renders a query summary block in the span detail panel: system, db.namespace, table, operation, rows returned, batch size, server.address:port, and error.type as the outcome. Humanizes ~30 known db.system.name values and tints the icon per engine. Reuses the existing span-annotation adapter registry (same pattern as cloudflare.ts) — registered in index.ts, no component changes.
• SQLCommenter traceparent parser — @maple/domain/sqlcommenter. Extracts the W3C traceparent from a SQLCommenter comment embedded in query text (/*traceparent='00-<trace>-<span>-01'*/). Pure, dependency-free string parsing (safe in web/cli/scraper bundles). This is the seam that lets server-side query logs nest under the client span that issued them.
• Semconv completeness — added db.system.name / db.system to the trace-view projection allowlist (TREE_SPAN_ATTR_KEYS) so DB spans detect promptly without waiting for the lazy per-span detail fetch.
• Docs — docs/database-query-observability.md.

Testing

• packages/domain/src/sqlcommenter.test.ts — 6 cases (trailing comment, sampled/unsampled flag, alongside other sqlcommenter keys, URL-encoded/whitespace/uppercase tolerance, absent, malformed/all-zero ids). ✅ passing.
• bun typecheck clean for @maple/domain, @maple/ui, @maple/query-engine.

Reviewer notes

• The adapter reuses the cloud-platforms registry even though a database isn't a "cloud platform"; the normalized CloudPlatformInfo shape is generic enough to describe a DB call, and it keeps the span-detail render path unchanged. A serverless span and a DB-client span are disjoint in practice.
• Follow-ups on this branch: (1) a cross-service Queries surface (the existing serviceDbTopQueriesSQL already supports dropping the service filter, so it's mostly a new web route); (2) the ClickHouse system.query_log poller (Model B: poll → OTLP into Maple via the apps/scraper pattern, nesting via the SQLCommenter parser above) for resource allocation.

🤖 Generated with Claude Code

---

[pullfrog]

Your LLM provider API key was rejected. Rotate the key in your provider dashboard, then update the matching GitHub Actions secret.

Update repo secret → · Model settings → · Setup docs → · Ask in Discord →

  ^{｜ ⚠️ this action is pinned to a commit SHA, which freezes the cleanup step — switch to @v0 or keep the SHA fresh with Dependabot ｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ Using Claude Opus ｜ 𝕏}