@syncular/server 0.0.1-73 → 0.0.1-88

package/src/pull.ts

@@ -1,15 +1,19 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { promisify } from 'node:util';
 import { gzip, gzipSync } from 'node:zlib';
-import type {
-  ScopeValues,
-  SyncBootstrapState,
-  SyncChange,
-  SyncCommit,
-  SyncPullRequest,
-  SyncPullResponse,
-  SyncPullSubscriptionResponse,
-  SyncSnapshot,
+import {
+  captureSyncException,
+  countSyncMetric,
+  distributionSyncMetric,
+  type ScopeValues,
+  type SyncBootstrapState,
+  type SyncChange,
+  type SyncCommit,
+  type SyncPullRequest,
+  type SyncPullResponse,
+  type SyncPullSubscriptionResponse,
+  type SyncSnapshot,
+  startSyncSpan,
 } from '@syncular/core';
 import type { Kysely } from 'kysely';
 import type { ServerSyncDialect } from './dialect/types';
@@ -96,6 +100,106 @@ function mergeScopes(subscriptions: { scopes: ScopeValues }[]): ScopeValues {
   return merged;
 }
 
+interface PullResponseStats {
+  subscriptionCount: number;
+  activeSubscriptionCount: number;
+  revokedSubscriptionCount: number;
+  bootstrapSubscriptionCount: number;
+  commitCount: number;
+  changeCount: number;
+  snapshotPageCount: number;
+}
+
+function summarizePullResponse(response: SyncPullResponse): PullResponseStats {
+  const subscriptions = response.subscriptions ?? [];
+  let activeSubscriptionCount = 0;
+  let revokedSubscriptionCount = 0;
+  let bootstrapSubscriptionCount = 0;
+  let commitCount = 0;
+  let changeCount = 0;
+  let snapshotPageCount = 0;
+
+  for (const sub of subscriptions) {
+    if (sub.status === 'revoked') {
+      revokedSubscriptionCount += 1;
+    } else {
+      activeSubscriptionCount += 1;
+    }
+
+    if (sub.bootstrap) {
+      bootstrapSubscriptionCount += 1;
+    }
+
+    const commits = sub.commits ?? [];
+    commitCount += commits.length;
+    for (const commit of commits) {
+      changeCount += commit.changes?.length ?? 0;
+    }
+
+    snapshotPageCount += sub.snapshots?.length ?? 0;
+  }
+
+  return {
+    subscriptionCount: subscriptions.length,
+    activeSubscriptionCount,
+    revokedSubscriptionCount,
+    bootstrapSubscriptionCount,
+    commitCount,
+    changeCount,
+    snapshotPageCount,
+  };
+}
+
+function recordPullMetrics(args: {
+  status: string;
+  dedupeRows: boolean;
+  durationMs: number;
+  stats: PullResponseStats;
+}): void {
+  const { status, dedupeRows, durationMs, stats } = args;
+  const attributes = {
+    status,
+    dedupe_rows: dedupeRows,
+  };
+
+  countSyncMetric('sync.server.pull.requests', 1, { attributes });
+  distributionSyncMetric('sync.server.pull.duration_ms', durationMs, {
+    unit: 'millisecond',
+    attributes,
+  });
+  distributionSyncMetric(
+    'sync.server.pull.subscriptions',
+    stats.subscriptionCount,
+    { attributes }
+  );
+  distributionSyncMetric(
+    'sync.server.pull.active_subscriptions',
+    stats.activeSubscriptionCount,
+    { attributes }
+  );
+  distributionSyncMetric(
+    'sync.server.pull.revoked_subscriptions',
+    stats.revokedSubscriptionCount,
+    { attributes }
+  );
+  distributionSyncMetric(
+    'sync.server.pull.bootstrap_subscriptions',
+    stats.bootstrapSubscriptionCount,
+    { attributes }
+  );
+  distributionSyncMetric('sync.server.pull.commits', stats.commitCount, {
+    attributes,
+  });
+  distributionSyncMetric('sync.server.pull.changes', stats.changeCount, {
+    attributes,
+  });
+  distributionSyncMetric(
+    'sync.server.pull.snapshot_pages',
+    stats.snapshotPageCount,
+    { attributes }
+  );
+}
+
 export async function pull<DB extends SyncCoreDb>(args: {
   db: Kysely<DB>;
   dialect: ServerSyncDialect;
@@ -113,439 +217,526 @@ export async function pull<DB extends SyncCoreDb>(args: {
   const { request, dialect } = args;
   const db = args.db;
   const partitionId = args.partitionId ?? 'default';
-
-  // Validate and sanitize request limits
-  const limitCommits = sanitizeLimit(request.limitCommits, 50, 1, 500);
-  const limitSnapshotRows = sanitizeLimit(
-    request.limitSnapshotRows,
-    1000,
-    1,
-    5000
-  );
-  const maxSnapshotPages = sanitizeLimit(request.maxSnapshotPages, 1, 1, 50);
-  const dedupeRows = request.dedupeRows === true;
-
-  // Resolve effective scopes for each subscription
-  const resolved = await resolveEffectiveScopesForSubscriptions({
-    db,
-    actorId: args.actorId,
-    subscriptions: request.subscriptions ?? [],
-    shapes: args.shapes,
-  });
-
-  return dialect.executeInTransaction(db, async (trx) => {
-    await dialect.setRepeatableRead(trx);
-
-    const maxCommitSeq = await dialect.readMaxCommitSeq(trx, { partitionId });
-    const minCommitSeq = await dialect.readMinCommitSeq(trx, { partitionId });
-
-    const subResponses: SyncPullSubscriptionResponse[] = [];
-    const activeSubscriptions: { scopes: ScopeValues }[] = [];
-    const nextCursors: number[] = [];
-
-    for (const sub of resolved) {
-      const cursor = Math.max(-1, sub.cursor ?? -1);
-      // Validate shape exists (throws if not registered)
-      args.shapes.getOrThrow(sub.shape);
-
-      if (sub.status === 'revoked' || Object.keys(sub.scopes).length === 0) {
-        subResponses.push({
-          id: sub.id,
-          status: 'revoked',
-          scopes: {},
-          bootstrap: false,
-          nextCursor: cursor,
-          commits: [],
+  const requestedSubscriptionCount = Array.isArray(request.subscriptions)
+    ? request.subscriptions.length
+    : 0;
+  const startedAtMs = Date.now();
+
+  return startSyncSpan(
+    {
+      name: 'sync.server.pull',
+      op: 'sync.pull',
+      attributes: {
+        requested_subscription_count: requestedSubscriptionCount,
+        dedupe_rows: request.dedupeRows === true,
+      },
+    },
+    async (span) => {
+      try {
+        // Validate and sanitize request limits
+        const limitCommits = sanitizeLimit(request.limitCommits, 50, 1, 500);
+        const limitSnapshotRows = sanitizeLimit(
+          request.limitSnapshotRows,
+          1000,
+          1,
+          5000
+        );
+        const maxSnapshotPages = sanitizeLimit(
+          request.maxSnapshotPages,
+          1,
+          1,
+          50
+        );
+        const dedupeRows = request.dedupeRows === true;
+
+        // Resolve effective scopes for each subscription
+        const resolved = await resolveEffectiveScopesForSubscriptions({
+          db,
+          actorId: args.actorId,
+          subscriptions: request.subscriptions ?? [],
+          shapes: args.shapes,
         });
-        continue;
-      }
-
-      const effectiveScopes = sub.scopes;
-      activeSubscriptions.push({ scopes: effectiveScopes });
-
-      const needsBootstrap =
-        sub.bootstrapState != null ||
-        cursor < 0 ||
-        cursor > maxCommitSeq ||
-        (minCommitSeq > 0 && cursor < minCommitSeq - 1);
-
-      if (needsBootstrap) {
-        const tables = args.shapes
-          .getBootstrapOrderFor(sub.shape)
-          .map((handler) => handler.table);
-
-        const initState: SyncBootstrapState = {
-          asOfCommitSeq: maxCommitSeq,
-          tables,
-          tableIndex: 0,
-          rowCursor: null,
-        };
-
-        const requestedState = sub.bootstrapState ?? null;
-        const state =
-          requestedState &&
-          typeof requestedState.asOfCommitSeq === 'number' &&
-          Array.isArray(requestedState.tables) &&
-          typeof requestedState.tableIndex === 'number'
-            ? (requestedState as SyncBootstrapState)
-            : initState;
-
-        // If the bootstrap state's asOfCommitSeq is no longer catch-up-able, restart bootstrap.
-        const effectiveState =
-          state.asOfCommitSeq < minCommitSeq - 1 ? initState : state;
-
-        const tableName = effectiveState.tables[effectiveState.tableIndex];
-
-        // No tables (or ran past the end): treat bootstrap as complete.
-        if (!tableName) {
-          subResponses.push({
-            id: sub.id,
-            status: 'active',
-            scopes: effectiveScopes,
-            bootstrap: true,
-            bootstrapState: null,
-            nextCursor: effectiveState.asOfCommitSeq,
-            commits: [],
-            snapshots: [],
-          });
-          nextCursors.push(effectiveState.asOfCommitSeq);
-          continue;
-        }
-
-        const snapshots: SyncSnapshot[] = [];
-        let nextState: SyncBootstrapState | null = effectiveState;
-
-        for (let pageIndex = 0; pageIndex < maxSnapshotPages; pageIndex++) {
-          if (!nextState) break;
 
-          const nextTableName = nextState.tables[nextState.tableIndex];
-          if (!nextTableName) {
-            nextState = null;
-            break;
-          }
-
-          const tableHandler = args.shapes.getOrThrow(nextTableName);
-          const isFirstPage = nextState.rowCursor == null;
+        const result = await dialect.executeInTransaction(db, async (trx) => {
+          await dialect.setRepeatableRead(trx);
 
-          const page = await tableHandler.snapshot(
-            {
-              db: trx,
-              actorId: args.actorId,
-              scopeValues: effectiveScopes,
-              cursor: nextState.rowCursor,
-              limit: limitSnapshotRows,
-            },
-            sub.params
-          );
-
-          const isLastPage = page.nextCursor == null;
-
-          // Always use NDJSON+gzip for bootstrap snapshots
-          const ttlMs = tableHandler.snapshotChunkTtlMs ?? 24 * 60 * 60 * 1000; // 24h
-          const nowIso = new Date().toISOString();
-
-          // Use scope hash for caching
-          const cacheKey = `${partitionId}:${scopesToCacheKey(effectiveScopes)}`;
-          const cached = await readSnapshotChunkRefByPageKey(trx, {
+          const maxCommitSeq = await dialect.readMaxCommitSeq(trx, {
+            partitionId,
+          });
+          const minCommitSeq = await dialect.readMinCommitSeq(trx, {
             partitionId,
-            scopeKey: cacheKey,
-            scope: nextTableName,
-            asOfCommitSeq: effectiveState.asOfCommitSeq,
-            rowCursor: nextState.rowCursor,
-            rowLimit: limitSnapshotRows,
-            encoding: 'ndjson',
-            compression: 'gzip',
-            nowIso,
           });
 
-          let chunkRef = cached;
-
-          if (!chunkRef) {
-            const lines: string[] = [];
-            for (const r of page.rows ?? []) {
-              const s = JSON.stringify(r);
-              lines.push(s === undefined ? 'null' : s);
+          const subResponses: SyncPullSubscriptionResponse[] = [];
+          const activeSubscriptions: { scopes: ScopeValues }[] = [];
+          const nextCursors: number[] = [];
+
+          for (const sub of resolved) {
+            const cursor = Math.max(-1, sub.cursor ?? -1);
+            // Validate shape exists (throws if not registered)
+            args.shapes.getOrThrow(sub.shape);
+
+            if (
+              sub.status === 'revoked' ||
+              Object.keys(sub.scopes).length === 0
+            ) {
+              subResponses.push({
+                id: sub.id,
+                status: 'revoked',
+                scopes: {},
+                bootstrap: false,
+                nextCursor: cursor,
+                commits: [],
+              });
+              continue;
             }
-            const ndjson = lines.length > 0 ? `${lines.join('\n')}\n` : '';
-            const gz = await compressSnapshotNdjson(ndjson);
-            const sha256 = createHash('sha256').update(ndjson).digest('hex');
-            const expiresAt = new Date(
-              Date.now() + Math.max(1000, ttlMs)
-            ).toISOString();
-
-            // Use external chunk storage if available, otherwise fall back to inline
-            if (args.chunkStorage) {
-              chunkRef = await args.chunkStorage.storeChunk({
-                partitionId,
-                scopeKey: cacheKey,
-                scope: nextTableName,
-                asOfCommitSeq: effectiveState.asOfCommitSeq,
-                rowCursor: nextState.rowCursor ?? null,
-                rowLimit: limitSnapshotRows,
-                encoding: 'ndjson',
-                compression: 'gzip',
-                sha256,
-                body: gz,
-                expiresAt,
+
+            const effectiveScopes = sub.scopes;
+            activeSubscriptions.push({ scopes: effectiveScopes });
+
+            const needsBootstrap =
+              sub.bootstrapState != null ||
+              cursor < 0 ||
+              cursor > maxCommitSeq ||
+              (minCommitSeq > 0 && cursor < minCommitSeq - 1);
+
+            if (needsBootstrap) {
+              const tables = args.shapes
+                .getBootstrapOrderFor(sub.shape)
+                .map((handler) => handler.table);
+
+              const initState: SyncBootstrapState = {
+                asOfCommitSeq: maxCommitSeq,
+                tables,
+                tableIndex: 0,
+                rowCursor: null,
+              };
+
+              const requestedState = sub.bootstrapState ?? null;
+              const state =
+                requestedState &&
+                typeof requestedState.asOfCommitSeq === 'number' &&
+                Array.isArray(requestedState.tables) &&
+                typeof requestedState.tableIndex === 'number'
+                  ? (requestedState as SyncBootstrapState)
+                  : initState;
+
+              // If the bootstrap state's asOfCommitSeq is no longer catch-up-able, restart bootstrap.
+              const effectiveState =
+                state.asOfCommitSeq < minCommitSeq - 1 ? initState : state;
+
+              const tableName =
+                effectiveState.tables[effectiveState.tableIndex];
+
+              // No tables (or ran past the end): treat bootstrap as complete.
+              if (!tableName) {
+                subResponses.push({
+                  id: sub.id,
+                  status: 'active',
+                  scopes: effectiveScopes,
+                  bootstrap: true,
+                  bootstrapState: null,
+                  nextCursor: effectiveState.asOfCommitSeq,
+                  commits: [],
+                  snapshots: [],
+                });
+                nextCursors.push(effectiveState.asOfCommitSeq);
+                continue;
+              }
+
+              const snapshots: SyncSnapshot[] = [];
+              let nextState: SyncBootstrapState | null = effectiveState;
+
+              for (
+                let pageIndex = 0;
+                pageIndex < maxSnapshotPages;
+                pageIndex++
+              ) {
+                if (!nextState) break;
+
+                const nextTableName = nextState.tables[nextState.tableIndex];
+                if (!nextTableName) {
+                  nextState = null;
+                  break;
+                }
+
+                const tableHandler = args.shapes.getOrThrow(nextTableName);
+                const isFirstPage = nextState.rowCursor == null;
+
+                const page = await tableHandler.snapshot(
+                  {
+                    db: trx,
+                    actorId: args.actorId,
+                    scopeValues: effectiveScopes,
+                    cursor: nextState.rowCursor,
+                    limit: limitSnapshotRows,
+                  },
+                  sub.params
+                );
+
+                const isLastPage = page.nextCursor == null;
+
+                // Always use NDJSON+gzip for bootstrap snapshots
+                const ttlMs =
+                  tableHandler.snapshotChunkTtlMs ?? 24 * 60 * 60 * 1000; // 24h
+                const nowIso = new Date().toISOString();
+
+                // Use scope hash for caching
+                const cacheKey = `${partitionId}:${scopesToCacheKey(effectiveScopes)}`;
+                const cached = await readSnapshotChunkRefByPageKey(trx, {
+                  partitionId,
+                  scopeKey: cacheKey,
+                  scope: nextTableName,
+                  asOfCommitSeq: effectiveState.asOfCommitSeq,
+                  rowCursor: nextState.rowCursor,
+                  rowLimit: limitSnapshotRows,
+                  encoding: 'ndjson',
+                  compression: 'gzip',
+                  nowIso,
+                });
+
+                let chunkRef = cached;
+
+                if (!chunkRef) {
+                  const lines: string[] = [];
+                  for (const r of page.rows ?? []) {
+                    const s = JSON.stringify(r);
+                    lines.push(s === undefined ? 'null' : s);
+                  }
+                  const ndjson =
+                    lines.length > 0 ? `${lines.join('\n')}\n` : '';
+                  const gz = await compressSnapshotNdjson(ndjson);
+                  const sha256 = createHash('sha256')
+                    .update(ndjson)
+                    .digest('hex');
+                  const expiresAt = new Date(
+                    Date.now() + Math.max(1000, ttlMs)
+                  ).toISOString();
+
+                  // Use external chunk storage if available, otherwise fall back to inline
+                  if (args.chunkStorage) {
+                    chunkRef = await args.chunkStorage.storeChunk({
+                      partitionId,
+                      scopeKey: cacheKey,
+                      scope: nextTableName,
+                      asOfCommitSeq: effectiveState.asOfCommitSeq,
+                      rowCursor: nextState.rowCursor ?? null,
+                      rowLimit: limitSnapshotRows,
+                      encoding: 'ndjson',
+                      compression: 'gzip',
+                      sha256,
+                      body: gz,
+                      expiresAt,
+                    });
+                  } else {
+                    const chunkId = randomUUID();
+                    chunkRef = await insertSnapshotChunk(trx, {
+                      chunkId,
+                      partitionId,
+                      scopeKey: cacheKey,
+                      scope: nextTableName,
+                      asOfCommitSeq: effectiveState.asOfCommitSeq,
+                      rowCursor: nextState.rowCursor,
+                      rowLimit: limitSnapshotRows,
+                      encoding: 'ndjson',
+                      compression: 'gzip',
+                      sha256,
+                      body: gz,
+                      expiresAt,
+                    });
+                  }
+                }
+
+                snapshots.push({
+                  table: nextTableName,
+                  rows: [],
+                  chunks: [chunkRef],
+                  isFirstPage,
+                  isLastPage,
+                });
+
+                if (page.nextCursor != null) {
+                  nextState = { ...nextState, rowCursor: page.nextCursor };
+                  continue;
+                }
+
+                if (nextState.tableIndex + 1 < nextState.tables.length) {
+                  nextState = {
+                    ...nextState,
+                    tableIndex: nextState.tableIndex + 1,
+                    rowCursor: null,
+                  };
+                  continue;
+                }
+
+                nextState = null;
+                break;
+              }
+
+              subResponses.push({
+                id: sub.id,
+                status: 'active',
+                scopes: effectiveScopes,
+                bootstrap: true,
+                bootstrapState: nextState,
+                nextCursor: effectiveState.asOfCommitSeq,
+                commits: [],
+                snapshots,
               });
+              nextCursors.push(effectiveState.asOfCommitSeq);
+              continue;
+            }
+
+            // Incremental pull for this subscription
+            // Read the commit window for this table up-front so the subscription cursor
+            // can advance past commits that don't match the requested scopes.
+            const scannedCommitSeqs = await dialect.readCommitSeqsForPull(trx, {
+              partitionId,
+              cursor,
+              limitCommits,
+              tables: [sub.shape],
+            });
+            const maxScannedCommitSeq =
+              scannedCommitSeqs.length > 0
+                ? scannedCommitSeqs[scannedCommitSeqs.length - 1]!
+                : cursor;
+
+            // Use streaming when available to reduce memory pressure for large pulls
+            const pullRowStream = dialect.streamIncrementalPullRows
+              ? dialect.streamIncrementalPullRows(trx, {
+                  partitionId,
+                  table: sub.shape,
+                  scopes: effectiveScopes,
+                  cursor,
+                  limitCommits,
+                })
+              : null;
+
+            // Collect rows and compute nextCursor in a single pass
+            const incrementalRows: Array<{
+              commit_seq: number;
+              actor_id: string;
+              created_at: string;
+              change_id: number;
+              table: string;
+              row_id: string;
+              op: 'upsert' | 'delete';
+              row_json: unknown | null;
+              row_version: number | null;
+              scopes: Record<string, string | string[]>;
+            }> = [];
+
+            let nextCursor = cursor;
+
+            if (pullRowStream) {
+              // Streaming path: process rows as they arrive
+              for await (const row of pullRowStream) {
+                incrementalRows.push(row);
+                nextCursor = Math.max(nextCursor, row.commit_seq);
+              }
             } else {
-              const chunkId = randomUUID();
-              chunkRef = await insertSnapshotChunk(trx, {
-                chunkId,
+              // Non-streaming fallback: load all rows at once
+              const rows = await dialect.readIncrementalPullRows(trx, {
                 partitionId,
-                scopeKey: cacheKey,
-                scope: nextTableName,
-                asOfCommitSeq: effectiveState.asOfCommitSeq,
-                rowCursor: nextState.rowCursor,
-                rowLimit: limitSnapshotRows,
-                encoding: 'ndjson',
-                compression: 'gzip',
-                sha256,
-                body: gz,
-                expiresAt,
+                table: sub.shape,
+                scopes: effectiveScopes,
+                cursor,
+                limitCommits,
               });
+              incrementalRows.push(...rows);
+              for (const r of incrementalRows) {
+                nextCursor = Math.max(nextCursor, r.commit_seq);
+              }
             }
-          }
-
-          snapshots.push({
-            table: nextTableName,
-            rows: [],
-            chunks: [chunkRef],
-            isFirstPage,
-            isLastPage,
-          });
-
-          if (page.nextCursor != null) {
-            nextState = { ...nextState, rowCursor: page.nextCursor };
-            continue;
-          }
 
-          if (nextState.tableIndex + 1 < nextState.tables.length) {
-            nextState = {
-              ...nextState,
-              tableIndex: nextState.tableIndex + 1,
-              rowCursor: null,
-            };
-            continue;
-          }
-
-          nextState = null;
-          break;
-        }
-
-        subResponses.push({
-          id: sub.id,
-          status: 'active',
-          scopes: effectiveScopes,
-          bootstrap: true,
-          bootstrapState: nextState,
-          nextCursor: effectiveState.asOfCommitSeq,
-          commits: [],
-          snapshots,
-        });
-        nextCursors.push(effectiveState.asOfCommitSeq);
-        continue;
-      }
+            nextCursor = Math.max(nextCursor, maxScannedCommitSeq);
 
-      // Incremental pull for this subscription
-      // Read the commit window for this table up-front so the subscription cursor
-      // can advance past commits that don't match the requested scopes.
-      const scannedCommitSeqs = await dialect.readCommitSeqsForPull(trx, {
-        partitionId,
-        cursor,
-        limitCommits,
-        tables: [sub.shape],
-      });
-      const maxScannedCommitSeq =
-        scannedCommitSeqs.length > 0
-          ? scannedCommitSeqs[scannedCommitSeqs.length - 1]!
-          : cursor;
-
-      // Use streaming when available to reduce memory pressure for large pulls
-      const pullRowStream = dialect.streamIncrementalPullRows
-        ? dialect.streamIncrementalPullRows(trx, {
-            partitionId,
-            table: sub.shape,
-            scopes: effectiveScopes,
-            cursor,
-            limitCommits,
-          })
-        : null;
-
-      // Collect rows and compute nextCursor in a single pass
-      const incrementalRows: Array<{
-        commit_seq: number;
-        actor_id: string;
-        created_at: string;
-        change_id: number;
-        table: string;
-        row_id: string;
-        op: 'upsert' | 'delete';
-        row_json: unknown | null;
-        row_version: number | null;
-        scopes: Record<string, string | string[]>;
-      }> = [];
-
-      let nextCursor = cursor;
-
-      if (pullRowStream) {
-        // Streaming path: process rows as they arrive
-        for await (const row of pullRowStream) {
-          incrementalRows.push(row);
-          nextCursor = Math.max(nextCursor, row.commit_seq);
-        }
-      } else {
-        // Non-streaming fallback: load all rows at once
-        const rows = await dialect.readIncrementalPullRows(trx, {
-          partitionId,
-          table: sub.shape,
-          scopes: effectiveScopes,
-          cursor,
-          limitCommits,
-        });
-        incrementalRows.push(...rows);
-        for (const r of incrementalRows) {
-          nextCursor = Math.max(nextCursor, r.commit_seq);
-        }
-      }
+            if (incrementalRows.length === 0) {
+              subResponses.push({
+                id: sub.id,
+                status: 'active',
+                scopes: effectiveScopes,
+                bootstrap: false,
+                nextCursor,
+                commits: [],
+              });
+              nextCursors.push(nextCursor);
+              continue;
+            }
 
-      nextCursor = Math.max(nextCursor, maxScannedCommitSeq);
+            if (dedupeRows) {
+              const latestByRowKey = new Map<
+                string,
+                {
+                  commitSeq: number;
+                  createdAt: string;
+                  actorId: string;
+                  changeId: number;
+                  change: SyncChange;
+                }
+              >();
+
+              for (const r of incrementalRows) {
+                const rowKey = `${r.table}\u0000${r.row_id}`;
+                const change: SyncChange = {
+                  table: r.table,
+                  row_id: r.row_id,
+                  op: r.op,
+                  row_json: r.row_json,
+                  row_version: r.row_version,
+                  scopes: dialect.dbToScopes(r.scopes),
+                };
+
+                latestByRowKey.set(rowKey, {
+                  commitSeq: r.commit_seq,
+                  createdAt: r.created_at,
+                  actorId: r.actor_id,
+                  changeId: r.change_id,
+                  change,
+                });
+              }
+
+              const latest = Array.from(latestByRowKey.values()).sort(
+                (a, b) => a.commitSeq - b.commitSeq || a.changeId - b.changeId
+              );
+
+              const commitsBySeq = new Map<number, SyncCommit>();
+              for (const item of latest) {
+                let commit = commitsBySeq.get(item.commitSeq);
+                if (!commit) {
+                  commit = {
+                    commitSeq: item.commitSeq,
+                    createdAt: item.createdAt,
+                    actorId: item.actorId,
+                    changes: [],
+                  };
+                  commitsBySeq.set(item.commitSeq, commit);
+                }
+                commit.changes.push(item.change);
+              }
+
+              const commits = Array.from(commitsBySeq.values()).sort(
+                (a, b) => a.commitSeq - b.commitSeq
+              );
+
+              subResponses.push({
+                id: sub.id,
+                status: 'active',
+                scopes: effectiveScopes,
+                bootstrap: false,
+                nextCursor,
+                commits,
+              });
+              nextCursors.push(nextCursor);
+              continue;
+            }
 
-      if (incrementalRows.length === 0) {
-        subResponses.push({
-          id: sub.id,
-          status: 'active',
-          scopes: effectiveScopes,
-          bootstrap: false,
-          nextCursor,
-          commits: [],
-        });
-        nextCursors.push(nextCursor);
-        continue;
-      }
+            const commitsBySeq = new Map<number, SyncCommit>();
+            const commitSeqs: number[] = [];
+
+            for (const r of incrementalRows) {
+              const seq = r.commit_seq;
+              let commit = commitsBySeq.get(seq);
+              if (!commit) {
+                commit = {
+                  commitSeq: seq,
+                  createdAt: r.created_at,
+                  actorId: r.actor_id,
+                  changes: [],
+                };
+                commitsBySeq.set(seq, commit);
+                commitSeqs.push(seq);
+              }
+
+              const change: SyncChange = {
+                table: r.table,
+                row_id: r.row_id,
+                op: r.op,
+                row_json: r.row_json,
+                row_version: r.row_version,
+                scopes: dialect.dbToScopes(r.scopes),
+              };
+              commit.changes.push(change);
+            }
 
-      if (dedupeRows) {
-        const latestByRowKey = new Map<
-          string,
-          {
-            commitSeq: number;
-            createdAt: string;
-            actorId: string;
-            changeId: number;
-            change: SyncChange;
+            const commits: SyncCommit[] = commitSeqs
+              .map((seq) => commitsBySeq.get(seq))
+              .filter((c): c is SyncCommit => !!c)
+              .filter((c) => c.changes.length > 0);
+
+            subResponses.push({
+              id: sub.id,
+              status: 'active',
+              scopes: effectiveScopes,
+              bootstrap: false,
+              nextCursor,
+              commits,
+            });
+            nextCursors.push(nextCursor);
           }
-        >();
-
-        for (const r of incrementalRows) {
-          const rowKey = `${r.table}\u0000${r.row_id}`;
-          const change: SyncChange = {
-            table: r.table,
-            row_id: r.row_id,
-            op: r.op,
-            row_json: r.row_json,
-            row_version: r.row_version,
-            scopes: dialect.dbToScopes(r.scopes),
-          };
 
-          latestByRowKey.set(rowKey, {
-            commitSeq: r.commit_seq,
-            createdAt: r.created_at,
-            actorId: r.actor_id,
-            changeId: r.change_id,
-            change,
-          });
-        }
+          const effectiveScopes = mergeScopes(activeSubscriptions);
+          const clientCursor =
+            nextCursors.length > 0 ? Math.min(...nextCursors) : maxCommitSeq;
 
-        const latest = Array.from(latestByRowKey.values()).sort(
-          (a, b) => a.commitSeq - b.commitSeq || a.changeId - b.changeId
-        );
-
-        const commitsBySeq = new Map<number, SyncCommit>();
-        for (const item of latest) {
-          let commit = commitsBySeq.get(item.commitSeq);
-          if (!commit) {
-            commit = {
-              commitSeq: item.commitSeq,
-              createdAt: item.createdAt,
-              actorId: item.actorId,
-              changes: [],
-            };
-            commitsBySeq.set(item.commitSeq, commit);
-          }
-          commit.changes.push(item.change);
-        }
+          return {
+            response: {
+              ok: true as const,
+              subscriptions: subResponses,
+            },
+            effectiveScopes,
+            clientCursor,
+          };
+        });
 
-        const commits = Array.from(commitsBySeq.values()).sort(
-          (a, b) => a.commitSeq - b.commitSeq
-        );
+        const durationMs = Math.max(0, Date.now() - startedAtMs);
+        const stats = summarizePullResponse(result.response);
+
+        span.setAttribute('status', 'ok');
+        span.setAttribute('duration_ms', durationMs);
+        span.setAttribute('subscription_count', stats.subscriptionCount);
+        span.setAttribute('commit_count', stats.commitCount);
+        span.setAttribute('change_count', stats.changeCount);
+        span.setAttribute('snapshot_page_count', stats.snapshotPageCount);
+        span.setStatus('ok');
+
+        recordPullMetrics({
+          status: 'ok',
+          dedupeRows,
+          durationMs,
+          stats,
+        });
 
-        subResponses.push({
-          id: sub.id,
-          status: 'active',
-          scopes: effectiveScopes,
-          bootstrap: false,
-          nextCursor,
-          commits,
+        return result;
+      } catch (error) {
+        const durationMs = Math.max(0, Date.now() - startedAtMs);
+
+        span.setAttribute('status', 'error');
+        span.setAttribute('duration_ms', durationMs);
+        span.setStatus('error');
+
+        recordPullMetrics({
+          status: 'error',
+          dedupeRows: request.dedupeRows === true,
+          durationMs,
+          stats: {
+            subscriptionCount: 0,
+            activeSubscriptionCount: 0,
+            revokedSubscriptionCount: 0,
+            bootstrapSubscriptionCount: 0,
+            commitCount: 0,
+            changeCount: 0,
+            snapshotPageCount: 0,
+          },
         });
-        nextCursors.push(nextCursor);
-        continue;
-      }
 
-      const commitsBySeq = new Map<number, SyncCommit>();
-      const commitSeqs: number[] = [];
-
-      for (const r of incrementalRows) {
-        const seq = r.commit_seq;
-        let commit = commitsBySeq.get(seq);
-        if (!commit) {
-          commit = {
-            commitSeq: seq,
-            createdAt: r.created_at,
-            actorId: r.actor_id,
-            changes: [],
-          };
-          commitsBySeq.set(seq, commit);
-          commitSeqs.push(seq);
-        }
-
-        const change: SyncChange = {
-          table: r.table,
-          row_id: r.row_id,
-          op: r.op,
-          row_json: r.row_json,
-          row_version: r.row_version,
-          scopes: dialect.dbToScopes(r.scopes),
-        };
-        commit.changes.push(change);
+        captureSyncException(error, {
+          event: 'sync.server.pull',
+          requestedSubscriptionCount,
+          dedupeRows: request.dedupeRows === true,
+        });
+        throw error;
       }
-
-      const commits: SyncCommit[] = commitSeqs
-        .map((seq) => commitsBySeq.get(seq))
-        .filter((c): c is SyncCommit => !!c)
-        .filter((c) => c.changes.length > 0);
-
-      subResponses.push({
-        id: sub.id,
-        status: 'active',
-        scopes: effectiveScopes,
-        bootstrap: false,
-        nextCursor,
-        commits,
-      });
-      nextCursors.push(nextCursor);
     }
-
-    const effectiveScopes = mergeScopes(activeSubscriptions);
-    const clientCursor =
-      nextCursors.length > 0 ? Math.min(...nextCursors) : maxCommitSeq;
-
-    return {
-      response: {
-        ok: true as const,
-        subscriptions: subResponses,
-      },
-      effectiveScopes,
-      clientCursor,
-    };
-  });
+  );
 }