first commit

docs/persistence/database/db/src/telemetry/trace.md

@@ -0,0 +1,76 @@
+# withDbSpan
+
+## Purpose
+
+`withDbSpan` is a thin OTel tracing helper that wraps any async database operation in a named span. It handles the boilerplate of starting a span, setting its status on success or error, recording exceptions, and always ending the span — so concrete adapters and migration runners can add tracing with a single wrapper call rather than repeating the span lifecycle pattern in every method.
+
+Like the instruments module, `withDbSpan` relies on the OTel no-op tracer when no SDK is configured, so it is safe to call in any environment including tests with no OTel setup.
+
+## Features
+
+- Creates a named span via `trace.getTracer("@suaveplan/db")`
+- Sets `SpanStatusCode.OK` on successful completion
+- Sets `SpanStatusCode.ERROR` and records the exception on throw
+- Always ends the span (via `finally`) — no span leaks
+- Accepts optional `Attributes` for span metadata (e.g. `db.name`, `db.operation`)
+- Works with the OTel no-op provider — zero overhead when no exporter is registered
+
+## Usage: Basic Example
+
+```ts
+import { withDbSpan } from "@suaveplan/db/telemetry/trace";
+
+const rows = await withDbSpan("db.query", async () => {
+  return driver.query("SELECT * FROM users");
+});
+```
+
+## Usage: Advanced Example
+
+```ts
+import { withDbSpan } from "@suaveplan/db/telemetry/trace";
+
+// With span attributes for richer trace data
+const result = await withDbSpan(
+  "db.execute",
+  async () => driver.execute("DELETE FROM sessions WHERE expires_at < ?", [Date.now()]),
+  {
+    "db.name": "app",
+    "db.operation": "execute",
+    "db.statement": "DELETE FROM sessions",
+  }
+);
+
+// Wrapping a full transaction
+const transferResult = await withDbSpan("db.transaction.transfer", async () => {
+  return adapter.transaction(async (tx) => {
+    await tx.execute("UPDATE accounts SET balance = balance - ? WHERE id = ?", [100, "sender"]);
+    await tx.execute("UPDATE accounts SET balance = balance + ? WHERE id = ?", [100, "receiver"]);
+    return { ok: true };
+  });
+}, { "transfer.amount": 100 });
+```
+
+## API Reference
+
+### `withDbSpan<T>`
+
+```ts
+withDbSpan<T>(
+  name: string,
+  fn: () => Promise<T>,
+  attrs?: Attributes
+): Promise<T>
+```
+
+- **`name`** — OTel span name (e.g. `"db.query"`, `"db.migrate"`)
+- **`fn`** — async function to execute inside the span
+- **`attrs`** — optional `Attributes` map attached to the span at creation time
+- **Returns** — the resolved value of `fn()`
+- **Throws** — re-throws whatever `fn()` throws after recording the exception on the span
+
+## Implementation Notes
+
+`withDbSpan` uses the module-level `tracer` constant (created once at import time via `trace.getTracer("@suaveplan/db")`) rather than calling `getTracer` on every invocation. The OTel spec guarantees that `getTracer` with the same name returns the same tracer instance, so this is a safe optimisation.
+
+Non-Error thrown values (e.g. strings, numbers) are wrapped in `new Error(String(err))` before being passed to `span.recordException`. This satisfies the OTel SDK's type requirement for `recordException` while still re-throwing the original value, so callers that catch strings continue to work as before.