@arcote.tech/arc-otel 0.7.6

package/README.md

@@ -0,0 +1,246 @@
+# @arcote.tech/arc-otel
+
+OpenTelemetry instrumentation primitives for the Arc framework. Wraps the
+core OTel SDKs (`@opentelemetry/*`) behind an Arc-friendly API with
+PII-safe defaults, dev/prod sampling modes, and W3C Trace Context
+propagation.
+
+This package is **optional**. Arc apps run identically whether you import
+it or not — every span call short-circuits when no SDK is attached. Opt
+in by setting `observability.enabled: true` in `deploy.arc.json` (or by
+exporting `ARC_OTEL_ENABLED=true` for ad-hoc local runs).
+
+---
+
+## Architecture
+
+```
+┌─ browser ───────────────────────────────────────────┐
+│  start-app.ts                                       │
+│  └─ if (window.__ARC_OTEL_CONFIG)                   │
+│     await import("@arcote.tech/arc-otel/browser")   │
+│     initBrowserTelemetry({...})                     │
+└─────────────────────────────────────────────────────┘
+                       │
+                       │ OTLP/HTTP  ──/otel/v1/traces──┐
+                       ▼                                ▼
+┌─ arc-prod container ─────────┐         ┌─ otel-collector ────┐
+│  startPlatformServer()       │  OTLP   │  receivers.otlp     │
+│  └─ initServerTelemetry({…}) ├────────▶│  processors:        │
+│     traces + logs + metrics  │         │   - tail_sampling   │
+│  createArcServer({telemetry})│         │   - attributes      │
+│  └─ HTTP span                │         │   - batch           │
+│  └─ WS message span          │         │  exporters:         │
+│  └─ command.<name> span      │         │   - tempo (traces)  │
+│  └─ db.find/set/commit span  │         │   - loki  (logs)    │
+└──────────────────────────────┘         │   - prom  (metrics) │
+                                          └────────┬────────────┘
+                                                   │
+                                ┌──────────────────┼────────────────┐
+                                ▼                  ▼                ▼
+                       ┌─ tempo ────┐   ┌─ loki ─────┐   ┌─ prometheus ┐
+                       │ 7d traces  │   │ 7d logs    │   │ 30d metrics │
+                       └────────────┘   └────────────┘   └─────────────┘
+                                \              |              /
+                                 \             |             /
+                                  ▼            ▼            ▼
+                                ┌─ grafana (HTTPS via Caddy basic-auth) ─┐
+                                │  observability.<apex-of-app-domain>    │
+                                │  admin / ARC_OBSERVABILITY_PASSWORD    │
+                                └────────────────────────────────────────┘
+```
+
+---
+
+## Quick start (production deploy)
+
+Opt-in via `deploy.arc.json`:
+
+```jsonc
+{
+  "target": {...},
+  "envs": {
+    "prod": { "domain": "app.example.com", "db": { "type": "postgres" } }
+  },
+  "caddy": { "email": "ops@example.com" },
+  "registry": { "domain": "registry.example.com", "passwordEnv": "ARC_REGISTRY_PASSWORD" },
+
+  "observability": {
+    "enabled": true
+    // optional:
+    // "subdomain": "observability",
+    // "adminPasswordEnv": "ARC_OBSERVABILITY_PASSWORD",
+    // "retention": { "traces": "168h", "logs": "168h", "metrics": "30d" }
+  }
+}
+```
+
+Then:
+
+```bash
+arc platform deploy prod
+```
+
+First deploy auto-generates `ARC_OBSERVABILITY_PASSWORD` into
+`deploy.arc.env` (gitignored) and provisions five sidecar containers:
+`otel-collector`, `tempo`, `loki`, `prometheus`, `grafana`. Grafana is
+reachable at `https://observability.<apex>/` behind Caddy basic-auth
+(`admin` / generated password).
+
+Existing deploys that don't set `observability` are unchanged — no new
+containers, no env-vars on the app, zero added latency.
+
+---
+
+## What's instrumented
+
+### Server (always when `ARC_OTEL_ENABLED=true`)
+
+| Span name | Source | Notable attrs |
+|---|---|---|
+| `${METHOD} ${PATH}` | arc-host fetch handler | `http.request.method`, `http.route`, `http.response.status_code` |
+| `ws.${type}` | arc-host websocket dispatch | `messaging.message.type`, `arc.ws.client_id` |
+| `command.${name}` | ContextHandler.executeCommand | `rpc.system=arc`, `arc.command.name`, `arc.command.params_size`, payload in dev only |
+| `db.${op} ${store}` | wrapDbAdapter (postgres/sqlite) | `db.system`, `db.operation.name`, `db.collection.name`, `db.response.row_count` |
+
+Server emits **metrics** automatically:
+
+| Metric | Type | Labels |
+|---|---|---|
+| `arc.commands.total` | Counter | `arc.command.name` |
+| `arc.command.duration_ms` | Histogram | `arc.command.name` |
+| `arc.db.find_ms` | Histogram | `db.system`, `db.collection.name` |
+
+### Browser (when `window.__ARC_OTEL_CONFIG` is present)
+
+- W3C Trace Context propagator registered globally — outbound `fetch`
+  calls automatically attach `traceparent` / `tracestate` headers so the
+  server's HTTP span can pick up the client trace.
+- SDK chunk is `import()`-ed on demand from `start-app.ts`, so initial
+  bundle size stays untouched when observability is off.
+- Anonymous session id stored in `sessionStorage` (`arc:otel-session-id`)
+  groups spans per tab — never use as a user identifier.
+
+> Per-hook spans (`useQuery`, `useMutation`) and WS-frame trace context
+> injection are **deliberately out of scope** for v1. The server already
+> wraps every command/query in a span that's parented to the HTTP route,
+> which gives end-to-end visibility for traffic that originates from
+> `fetch` calls. WS traceparent propagation is a follow-up — when added,
+> call `injectTraceContext` on outbound messages.
+
+---
+
+## Sampling
+
+The SDK is configured `parentbased_always_on` on the server and
+`traceIdRatioBased(0.1)` on the browser by default. Final decisions are
+made by the **collector's tail sampler**, evaluated 10s after the trace
+finishes:
+
+1. **All errors** are kept (any span with status_code=ERROR).
+2. **All slow traces** are kept (duration > 500 ms).
+3. **10% of everything else** is kept (random).
+
+This guarantees you'll never miss a failure or a latency outlier, while
+typical happy-path traffic costs ~10% of total trace bandwidth.
+
+Tune in `observability-configs.ts:generateOtelCollectorConfig` — edit
+the `tail_sampling` block's policies (full spec in the OTel collector docs).
+
+---
+
+## PII safety
+
+Span attributes go through `sanitizeAttrs()` by default, which:
+
+- Drops any key matching `(password|token|secret|authorization|jwt|api_key|cookie|email|credit_card|ssn)` (case-insensitive, recursive).
+- Truncates strings longer than 2 KB.
+- Truncates serialized objects longer than 4 KB.
+- Catches circular references → `"[circular]"`.
+
+`shouldIncludePayloads()` defaults to **true in development, false in
+production**. Instrumentation sites that attach raw mutation params
+gate on this flag — so a prod span shows `arc.command.params_size`,
+while a dev span shows the (sanitized) payload itself.
+
+DATABASE_URL and similar credentials passing through error messages
+are run through `redactConnectionString()`.
+
+**Forbidden** (never attach as a span attribute):
+- Raw JWT / rawToken
+- `TokenPayload.params` in full — only `tokenType` + sanitized id-like params
+- Full event payload in prod
+- Raw DB error parameters
+
+---
+
+## Local development
+
+For a fast feedback loop without the full sidecar stack:
+
+```bash
+# Terminal 1 — Jaeger all-in-one (only traces, no logs/metrics).
+docker run --rm -d --name jaeger \
+  -p 16686:16686 -p 4318:4318 \
+  cr.jaegertracing.io/jaegertracing/all-in-one:1.62
+
+# Terminal 2 — your app
+export ARC_OTEL_ENABLED=true
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+arc platform dev
+
+# Open http://localhost:16686 — service "arc-<env>"
+```
+
+Browser spans need `window.__ARC_OTEL_CONFIG` injected by
+`generateShellHtml`, which fires when the server has
+`ARC_OTEL_ENABLED=true` — so a single env var enables both sides.
+
+---
+
+## API surface
+
+```ts
+import {
+  ArcTelemetry,
+  sanitizeAttrs,
+  redactConnectionString,
+  injectTraceContext,
+  extractTraceContext,
+  contextFromHeaders,
+  wrapDbAdapter,
+} from "@arcote.tech/arc-otel";
+
+import { initServerTelemetry } from "@arcote.tech/arc-otel/server";
+import { initBrowserTelemetry } from "@arcote.tech/arc-otel/browser";
+```
+
+Key methods on `ArcTelemetry`:
+
+```ts
+// Wrap an async function in a span; auto-records exceptions + sets status.
+await telemetry.startSpan(name, async (span) => {...}, { kind, attributes });
+
+// Counter / histogram / log API mirrors OTel's.
+telemetry.incrementCounter("arc.foo.total", 1, { label: "x" });
+telemetry.recordHistogram("arc.foo.duration_ms", elapsed, {...});
+telemetry.log("info", "message", { attr: "value" });
+
+// Bridge inbound trace context (HTTP headers, WS frame fields) before
+// starting the active span.
+telemetry.runWithExtractedContext(req.headers, () =>
+  telemetry.startSpan("http.request", async () => {...}),
+);
+```
+
+---
+
+## Out of scope
+
+- Alerting (Grafana alerts + notifier config).
+- Long-term storage (S3/GCS) for traces and logs — needs cloud creds.
+- Continuous profiling (Pyroscope/Parca).
+- Synthetic uptime monitoring.
+- Per-hook React span instrumentation (planned follow-up).
+- WS frame traceparent injection on the client (helper exists,
+  integration with EventWire/CommandWire pending).

package/dist/context-propagation.d.ts

@@ -0,0 +1,29 @@
+import { type Context, type Span } from "@opentelemetry/api";
+/** Standard W3C headers we care about. Useful as a constant for HTTP setup. */
+export declare const TRACE_CONTEXT_HEADERS: readonly ["traceparent", "tracestate"];
+/**
+ * Inject the current active span's trace context into `carrier`.
+ *
+ * Use case: serializing a WS frame payload. The receiver passes the same
+ * carrier to `extractTraceContext` and runs the handler inside that context.
+ */
+export declare function injectTraceContext(carrier?: Record<string, string>): Record<string, string>;
+/**
+ * Extract a parent trace context from `carrier` and return it. Run handler
+ * code via `context.with(parentCtx, () => ...)` or `telemetry.withSpan` so
+ * spans created inside link back to the parent automatically.
+ *
+ * Returns the current context unchanged when no traceparent is present —
+ * fine for unauthenticated probes or older clients without instrumentation.
+ */
+export declare function extractTraceContext(carrier: Record<string, unknown>): Context;
+/**
+ * Pull the parent span out of an arbitrary headers-like object (lowercased
+ * keys) and return it as an OTel-ready context. Convenience wrapper used by
+ * the HTTP server handler.
+ */
+export declare function contextFromHeaders(headers: Headers | Record<string, string | string[] | undefined>): Context;
+/** Get the currently active span. Convenience re-export so callers don't
+ *  need to depend on @opentelemetry/api directly. */
+export declare function getActiveSpan(): Span | undefined;
+//# sourceMappingURL=context-propagation.d.ts.map

package/dist/context-propagation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-propagation.d.ts","sourceRoot":"","sources":["../src/context-propagation.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,OAAO,EACZ,KAAK,IAAI,EACV,MAAM,oBAAoB,CAAC;AAY5B,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,wCAAyC,CAAC;AAE5E;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAG/F;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,OAAO,CAe5G;AAED;qDACqD;AACrD,wBAAgB,aAAa,IAAI,IAAI,GAAG,SAAS,CAEhD"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { ArcTelemetry, type ObservabilityMode, type SpanOptions, type TelemetryConfig, } from "./telemetry";
+export { sanitizeAttrs, redactConnectionString, DEFAULT_REDACT_KEY_PATTERN, DEFAULT_MAX_STRING_LEN, DEFAULT_MAX_JSON_LEN, type SanitizeOptions, } from "./sanitize";
+export { injectTraceContext, extractTraceContext, contextFromHeaders, getActiveSpan, TRACE_CONTEXT_HEADERS, } from "./context-propagation";
+export { wrapDbAdapter } from "./wrap-db-adapter";
+export { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+export type { Attributes, Span } from "@opentelemetry/api";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,eAAe,GACrB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,0BAA0B,EAC1B,sBAAsB,EACtB,oBAAoB,EACpB,KAAK,eAAe,GACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,qBAAqB,GACtB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAGlD,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,362 @@
+// src/telemetry.ts
+import {
+  context,
+  propagation,
+  SpanStatusCode,
+  trace
+} from "@opentelemetry/api";
+import {
+  logs,
+  SeverityNumber
+} from "@opentelemetry/api-logs";
+
+// src/sanitize.ts
+var DEFAULT_REDACT_KEY_PATTERN = /(password|passwd|token|secret|authorization|jwt|api[_-]?key|cookie|email|credit[_-]?card|ssn)/i;
+var DEFAULT_MAX_STRING_LEN = 2048;
+var DEFAULT_MAX_JSON_LEN = 4096;
+function sanitizeAttrs(input, opts = {}) {
+  if (!input)
+    return {};
+  const redactPattern = opts.redactKeyPattern ?? DEFAULT_REDACT_KEY_PATTERN;
+  const maxStr = opts.maxStringLen ?? DEFAULT_MAX_STRING_LEN;
+  const maxJson = opts.maxJsonLen ?? DEFAULT_MAX_JSON_LEN;
+  const out = {};
+  for (const [key, raw] of Object.entries(input)) {
+    if (redactPattern.test(key))
+      continue;
+    const value = sanitizeValue(raw, redactPattern, maxStr, maxJson);
+    if (value !== undefined)
+      out[key] = value;
+  }
+  return out;
+}
+function sanitizeValue(raw, redactPattern, maxStr, maxJson) {
+  if (raw === null || raw === undefined)
+    return;
+  if (typeof raw === "boolean" || typeof raw === "number")
+    return raw;
+  if (typeof raw === "string") {
+    return raw.length > maxStr ? `${raw.slice(0, maxStr)}…(truncated:${raw.length})` : raw;
+  }
+  try {
+    const filtered = filterRedacted(raw, redactPattern);
+    const json = JSON.stringify(filtered);
+    if (json === undefined)
+      return;
+    return json.length > maxJson ? `${json.slice(0, maxJson)}…(truncated:${json.length})` : json;
+  } catch {
+    return "[unserializable]";
+  }
+}
+function filterRedacted(node, pattern, seen = new WeakSet) {
+  if (node === null || typeof node !== "object")
+    return node;
+  if (seen.has(node))
+    return "[circular]";
+  seen.add(node);
+  if (Array.isArray(node)) {
+    return node.map((v) => filterRedacted(v, pattern, seen));
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(node)) {
+    if (pattern.test(k))
+      continue;
+    out[k] = filterRedacted(v, pattern, seen);
+  }
+  return out;
+}
+function redactConnectionString(url) {
+  if (!url)
+    return "";
+  try {
+    const u = new URL(url);
+    if (u.password)
+      u.password = "***";
+    return u.toString();
+  } catch {
+    return "[unparseable]";
+  }
+}
+
+// src/telemetry.ts
+class ArcTelemetry {
+  config;
+  tracer = null;
+  logger = null;
+  meter = null;
+  histograms = new Map;
+  counters = new Map;
+  constructor(config) {
+    const mode = config.mode ?? "development";
+    const enabled = config.enabled ?? mode !== "disabled";
+    const sampleRate = config.sampleRate ?? (config.environment === "server" ? 1 : 0.1);
+    this.config = {
+      ...config,
+      enabled,
+      sampleRate,
+      mode,
+      debug: config.debug ?? false
+    };
+  }
+  attach(opts) {
+    this.tracer = opts.tracer;
+    this.logger = opts.logger ?? null;
+    this.meter = opts.meter ?? null;
+  }
+  get active() {
+    return this.config.enabled && this.tracer !== null;
+  }
+  shouldIncludePayloads() {
+    if (this.config.includePayloads !== undefined)
+      return this.config.includePayloads;
+    return this.config.mode === "development";
+  }
+  async startSpan(name, fn, options = {}) {
+    if (!this.active || !this.tracer) {
+      return fn(trace.getActiveSpan() ?? noopSpan());
+    }
+    const attributes = this.toAttributes(options.attributes, options.unsafeAttrs);
+    return this.tracer.startActiveSpan(name, { kind: options.kind, attributes }, async (span) => {
+      try {
+        const result = await fn(span);
+        span.setStatus({ code: SpanStatusCode.OK });
+        return result;
+      } catch (error) {
+        this.recordError(span, error);
+        throw error;
+      } finally {
+        span.end();
+      }
+    });
+  }
+  createSpan(name, options = {}) {
+    if (!this.active || !this.tracer)
+      return noopSpan();
+    const attributes = this.toAttributes(options.attributes, options.unsafeAttrs);
+    return this.tracer.startSpan(name, { kind: options.kind, attributes });
+  }
+  getCurrentSpan() {
+    return trace.getActiveSpan();
+  }
+  withSpan(parent, fn) {
+    return context.with(trace.setSpan(context.active(), parent), fn);
+  }
+  runWithExtractedContext(carrier, fn) {
+    if (!this.active)
+      return fn();
+    const flat = {};
+    if (typeof Headers !== "undefined" && carrier instanceof Headers) {
+      carrier.forEach((value, key) => {
+        flat[key.toLowerCase()] = value;
+      });
+    } else if (carrier) {
+      for (const [k, v] of Object.entries(carrier)) {
+        if (typeof v === "string")
+          flat[k.toLowerCase()] = v;
+      }
+    }
+    const parent = propagation.extract(context.active(), flat);
+    return context.with(parent, fn);
+  }
+  recordError(span, error) {
+    const err = error instanceof Error ? error : new Error(String(error ?? "unknown error"));
+    try {
+      span.setStatus({ code: SpanStatusCode.ERROR, message: err.message });
+      span.recordException(err);
+    } catch {}
+  }
+  addAttributes(attrs, unsafeAttrs = false) {
+    const span = this.getCurrentSpan();
+    if (!span)
+      return;
+    span.setAttributes(this.toAttributes(attrs, unsafeAttrs));
+  }
+  log(level, body, attrs = {}, unsafeAttrs = false) {
+    if (!this.active)
+      return;
+    const logger = this.logger ?? logs.getLogger(this.config.serviceName);
+    const record = {
+      severityNumber: severityFor(level),
+      severityText: level.toUpperCase(),
+      body,
+      attributes: this.toAttributes(attrs, unsafeAttrs)
+    };
+    try {
+      logger.emit(record);
+    } catch {}
+  }
+  incrementCounter(name, value = 1, attrs = {}) {
+    if (!this.active || !this.meter)
+      return;
+    let counter = this.counters.get(name);
+    if (!counter) {
+      counter = this.meter.createCounter(name);
+      this.counters.set(name, counter);
+    }
+    try {
+      counter.add(value, attrs);
+    } catch {}
+  }
+  recordHistogram(name, value, attrs = {}) {
+    if (!this.active || !this.meter)
+      return;
+    let histogram = this.histograms.get(name);
+    if (!histogram) {
+      histogram = this.meter.createHistogram(name, { unit: "ms" });
+      this.histograms.set(name, histogram);
+    }
+    try {
+      histogram.record(value, attrs);
+    } catch {}
+  }
+  measureSince(name, start, attrs = {}) {
+    this.recordHistogram(name, Date.now() - start, attrs);
+  }
+  toAttributes(raw, unsafe) {
+    if (!raw)
+      return {};
+    if (unsafe)
+      return raw;
+    return sanitizeAttrs(raw, this.config.sanitize);
+  }
+}
+function severityFor(level) {
+  switch (level) {
+    case "debug":
+      return SeverityNumber.DEBUG;
+    case "info":
+      return SeverityNumber.INFO;
+    case "warn":
+      return SeverityNumber.WARN;
+    case "error":
+      return SeverityNumber.ERROR;
+    default:
+      return SeverityNumber.INFO;
+  }
+}
+function noopSpan() {
+  return trace.getActiveSpan() ?? trace.wrapSpanContext({
+    traceId: "00000000000000000000000000000000",
+    spanId: "0000000000000000",
+    traceFlags: 0
+  });
+}
+// src/context-propagation.ts
+import {
+  context as context2,
+  propagation as propagation2,
+  trace as trace2
+} from "@opentelemetry/api";
+var TRACE_CONTEXT_HEADERS = ["traceparent", "tracestate"];
+function injectTraceContext(carrier = {}) {
+  propagation2.inject(context2.active(), carrier);
+  return carrier;
+}
+function extractTraceContext(carrier) {
+  return propagation2.extract(context2.active(), carrier);
+}
+function contextFromHeaders(headers) {
+  const carrier = {};
+  if (headers instanceof Headers) {
+    for (const name of TRACE_CONTEXT_HEADERS) {
+      const value = headers.get(name);
+      if (value)
+        carrier[name] = value;
+    }
+  } else {
+    for (const name of TRACE_CONTEXT_HEADERS) {
+      const raw = headers[name];
+      const value = Array.isArray(raw) ? raw[0] : raw;
+      if (value)
+        carrier[name] = value;
+    }
+  }
+  return extractTraceContext(carrier);
+}
+function getActiveSpan() {
+  return trace2.getActiveSpan();
+}
+// src/wrap-db-adapter.ts
+function wrapDbAdapter(adapter, telemetry, dbSystem) {
+  if (!telemetry || !telemetry.active)
+    return adapter;
+  const wrapRead = (tx) => ({
+    find: async (store, options) => telemetry.startSpan(`db.find ${store}`, async (span) => {
+      const start = Date.now();
+      try {
+        const rows = await tx.find(store, options);
+        span.setAttribute("db.response.row_count", rows.length);
+        return rows;
+      } finally {
+        telemetry.measureSince("arc.db.find_ms", start, {
+          "db.system": dbSystem,
+          "db.collection.name": store
+        });
+      }
+    }, {
+      kind: 3,
+      attributes: {
+        "db.system": dbSystem,
+        "db.operation.name": "find",
+        "db.collection.name": store
+      }
+    })
+  });
+  const wrapReadWrite = (tx) => ({
+    ...wrapRead(tx),
+    set: async (store, data) => telemetry.startSpan(`db.set ${store}`, () => tx.set(store, data), {
+      kind: 3,
+      attributes: {
+        "db.system": dbSystem,
+        "db.operation.name": "set",
+        "db.collection.name": store
+      }
+    }),
+    remove: async (store, id) => telemetry.startSpan(`db.remove ${store}`, () => tx.remove(store, id), {
+      kind: 3,
+      attributes: {
+        "db.system": dbSystem,
+        "db.operation.name": "remove",
+        "db.collection.name": store
+      }
+    }),
+    commit: async () => telemetry.startSpan("db.commit", () => tx.commit(), {
+      kind: 3,
+      attributes: {
+        "db.system": dbSystem,
+        "db.operation.name": "commit"
+      }
+    })
+  });
+  return new Proxy(adapter, {
+    get(target, prop) {
+      const orig = target[prop];
+      if (prop === "readTransaction") {
+        return (...args) => wrapRead(orig.apply(target, args));
+      }
+      if (prop === "readWriteTransaction") {
+        return (...args) => wrapReadWrite(orig.apply(target, args));
+      }
+      return typeof orig === "function" ? orig.bind(target) : orig;
+    }
+  });
+}
+
+// src/index.ts
+import { SpanKind as SpanKind2, SpanStatusCode as SpanStatusCode2 } from "@opentelemetry/api";
+export {
+  wrapDbAdapter,
+  sanitizeAttrs,
+  redactConnectionString,
+  injectTraceContext,
+  getActiveSpan,
+  extractTraceContext,
+  contextFromHeaders,
+  TRACE_CONTEXT_HEADERS,
+  SpanStatusCode2 as SpanStatusCode,
+  SpanKind2 as SpanKind,
+  DEFAULT_REDACT_KEY_PATTERN,
+  DEFAULT_MAX_STRING_LEN,
+  DEFAULT_MAX_JSON_LEN,
+  ArcTelemetry
+};

package/dist/init-browser.d.ts

@@ -0,0 +1,8 @@
+import { ArcTelemetry, type TelemetryConfig } from "./telemetry";
+export interface BrowserInitResult {
+    telemetry: ArcTelemetry;
+    /** Flush pending spans (best-effort) when the page is about to unload. */
+    flush: () => Promise<void>;
+}
+export declare function initBrowserTelemetry(config: TelemetryConfig): BrowserInitResult;
+//# sourceMappingURL=init-browser.d.ts.map

package/dist/init-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-browser.d.ts","sourceRoot":"","sources":["../src/init-browser.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAUjE,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,YAAY,CAAC;IACxB,0EAA0E;IAC1E,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5B;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,CAgE/E"}