@syncular/core 0.0.1-83 → 0.0.1-89

package/dist/index.d.ts

@@ -16,6 +16,7 @@ export * from './logger';
 export * from './proxy';
 export * from './schemas';
 export * from './scopes';
+export * from './telemetry';
 export * from './transforms';
 export * from './types';
 export * from './utils';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,cAAc,SAAS,CAAC;AAExB,cAAc,YAAY,CAAC;AAE3B,cAAc,oBAAoB,CAAC;AAEnC,cAAc,UAAU,CAAC;AAEzB,cAAc,SAAS,CAAC;AAExB,cAAc,WAAW,CAAC;AAE1B,cAAc,UAAU,CAAC;AAEzB,cAAc,cAAc,CAAC;AAE7B,cAAc,SAAS,CAAC;AAExB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,cAAc,SAAS,CAAC;AAExB,cAAc,YAAY,CAAC;AAE3B,cAAc,oBAAoB,CAAC;AAEnC,cAAc,UAAU,CAAC;AAEzB,cAAc,SAAS,CAAC;AAExB,cAAc,WAAW,CAAC;AAE1B,cAAc,UAAU,CAAC;AAEzB,cAAc,aAAa,CAAC;AAE5B,cAAc,cAAc,CAAC;AAE7B,cAAc,SAAS,CAAC;AAExB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -23,6 +23,8 @@ export * from './proxy/index.js';
 export * from './schemas/index.js';
 // Scope types, patterns, and utilities
 export * from './scopes/index.js';
+// Telemetry abstraction
+export * from './telemetry.js';
 // Data transformation hooks
 export * from './transforms.js';
 // Transport and conflict types (protocol types come from ./schemas)

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,kFAAkF;AAClF,cAAc,SAAS,CAAC;AACxB,+BAA+B;AAC/B,cAAc,YAAY,CAAC;AAC3B,0BAA0B;AAC1B,cAAc,oBAAoB,CAAC;AACnC,oBAAoB;AACpB,cAAc,UAAU,CAAC;AACzB,uBAAuB;AACvB,cAAc,SAAS,CAAC;AACxB,gBAAgB;AAChB,cAAc,WAAW,CAAC;AAC1B,uCAAuC;AACvC,cAAc,UAAU,CAAC;AACzB,4BAA4B;AAC5B,cAAc,cAAc,CAAC;AAC7B,oEAAoE;AACpE,cAAc,SAAS,CAAC;AACxB,2BAA2B;AAC3B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,kFAAkF;AAClF,cAAc,SAAS,CAAC;AACxB,+BAA+B;AAC/B,cAAc,YAAY,CAAC;AAC3B,0BAA0B;AAC1B,cAAc,oBAAoB,CAAC;AACnC,oBAAoB;AACpB,cAAc,UAAU,CAAC;AACzB,uBAAuB;AACvB,cAAc,SAAS,CAAC;AACxB,gBAAgB;AAChB,cAAc,WAAW,CAAC;AAC1B,uCAAuC;AACvC,cAAc,UAAU,CAAC;AACzB,wBAAwB;AACxB,cAAc,aAAa,CAAC;AAC5B,4BAA4B;AAC5B,cAAc,cAAc,CAAC;AAC7B,oEAAoE;AACpE,cAAc,SAAS,CAAC;AACxB,2BAA2B;AAC3B,cAAc,SAAS,CAAC"}

package/dist/logger.d.ts

@@ -1,35 +1,19 @@
 /**
  * @syncular/core - Structured logging utilities for sync operations
  *
- * Outputs JSON lines for easy parsing by log aggregation tools.
- * Each log event includes a timestamp and event type.
+ * Uses the active telemetry backend configured via `configureSyncTelemetry()`.
  */
+import { type SyncTelemetryEvent } from './telemetry';
 /**
- * Sync log event structure
+ * Sync log event structure.
  */
-interface SyncLogEvent {
-    /** Event type identifier */
-    event: string;
-    /** User ID (optional) */
-    userId?: string;
-    /** Operation duration in milliseconds (optional) */
-    durationMs?: number;
-    /** Number of rows affected (optional) */
-    rowCount?: number;
-    /** Whether a full reset was required (optional) */
-    resetRequired?: boolean;
-    /** Error message if operation failed (optional) */
-    error?: string;
-    /** Additional arbitrary properties */
-    [key: string]: unknown;
-}
+export type SyncLogEvent = SyncTelemetryEvent;
 /**
- * Logger function type - allows custom logging implementations
+ * Logger function type.
  */
-type SyncLogger = (event: SyncLogEvent) => void;
+export type SyncLogger = (event: SyncLogEvent) => void;
 /**
- * Log a sync event using the default logger.
- * For custom logging, create your own logger with createDefaultLogger pattern.
+ * Log a sync event using the currently configured telemetry backend.
  */
 export declare const logSyncEvent: SyncLogger;
 /**
@@ -42,5 +26,4 @@ export declare const logSyncEvent: SyncLogger;
  * logSyncEvent({ event: 'work_complete', durationMs: elapsed() });
  */
 export declare function createSyncTimer(): () => number;
-export {};
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,UAAU,YAAY;IACpB,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mDAAmD;IACnD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,sCAAsC;IACtC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,KAAK,UAAU,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AA+BhD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,UAAkC,CAAC;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,MAAM,MAAM,CAG9C"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAExE;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAE9C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AAEvD;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,UAE1B,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,eAAe,IAAI,MAAM,MAAM,CAG9C"}

package/dist/logger.js

@@ -1,37 +1,15 @@
 /**
  * @syncular/core - Structured logging utilities for sync operations
  *
- * Outputs JSON lines for easy parsing by log aggregation tools.
- * Each log event includes a timestamp and event type.
+ * Uses the active telemetry backend configured via `configureSyncTelemetry()`.
  */
+import { getSyncTelemetry } from './telemetry.js';
 /**
- * Default logger that outputs JSON lines to console.
- * Non-blocking - defers logging to avoid blocking the event loop.
- *
- * On server (Node.js), uses setImmediate.
- * On client (browser), uses setTimeout(0).
- */
-function createDefaultLogger() {
-    // Detect environment
-    const isNode = typeof globalThis !== 'undefined' &&
-        typeof globalThis.setImmediate === 'function';
-    const defer = isNode
-        ? (fn) => globalThis.setImmediate(fn)
-        : (fn) => setTimeout(fn, 0);
-    return (event) => {
-        defer(() => {
-            console.log(JSON.stringify({
-                timestamp: new Date().toISOString(),
-                ...event,
-            }));
-        });
-    };
-}
-/**
- * Log a sync event using the default logger.
- * For custom logging, create your own logger with createDefaultLogger pattern.
+ * Log a sync event using the currently configured telemetry backend.
  */
-export const logSyncEvent = createDefaultLogger();
+export const logSyncEvent = (event) => {
+    getSyncTelemetry().log(event);
+};
 /**
  * Create a timer for measuring operation duration.
  * Returns the elapsed time in milliseconds when called.

package/dist/logger.js.map

@@ -1 +1 @@
-{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA2BH;;;;;;GAMG;AACH,SAAS,mBAAmB,GAAe;IACzC,qBAAqB;IACrB,MAAM,MAAM,GACV,OAAO,UAAU,KAAK,WAAW;QACjC,OAAO,UAAU,CAAC,YAAY,KAAK,UAAU,CAAC;IAEhD,MAAM,KAAK,GAAG,MAAM;QAClB,CAAC,CAAC,CAAC,EAAc,EAAE,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QACjD,CAAC,CAAC,CAAC,EAAc,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;IAE1C,OAAO,CAAC,KAAmB,EAAE,EAAE,CAAC;QAC9B,KAAK,CAAC,GAAG,EAAE,CAAC;YACV,OAAO,CAAC,GAAG,CACT,IAAI,CAAC,SAAS,CAAC;gBACb,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;gBACnC,GAAG,KAAK;aACT,CAAC,CACH,CAAC;QAAA,CACH,CAAC,CAAC;IAAA,CACJ,CAAC;AAAA,CACH;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAe,mBAAmB,EAAE,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,GAAiB;IAC9C,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAChC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;AAAA,CACpD"}
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAA2B,MAAM,aAAa,CAAC;AAYxE;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAe,CAAC,KAAK,EAAE,EAAE,CAAC;IACjD,gBAAgB,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAAA,CAC/B,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,GAAiB;IAC9C,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC;IAChC,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,CAAC;AAAA,CACpD"}

package/dist/telemetry.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @syncular/core - Runtime telemetry abstraction
+ *
+ * Provides vendor-neutral logging, tracing, and metrics interfaces so
+ * Syncular libraries can emit telemetry without coupling to a specific SDK.
+ */
+/**
+ * Supported log levels.
+ */
+export type SyncTelemetryLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * Primitive attribute value used by traces and metrics.
+ */
+export type SyncTelemetryAttributeValue = string | number | boolean;
+/**
+ * Attribute bag used by traces and metrics.
+ */
+export type SyncTelemetryAttributes = Record<string, SyncTelemetryAttributeValue>;
+/**
+ * Structured sync log event.
+ */
+export interface SyncTelemetryEvent {
+    event: string;
+    level?: SyncTelemetryLevel;
+    userId?: string;
+    durationMs?: number;
+    rowCount?: number;
+    resetRequired?: boolean;
+    error?: string;
+    [key: string]: unknown;
+}
+/**
+ * Span creation options.
+ */
+export interface SyncSpanOptions {
+    name: string;
+    op?: string;
+    attributes?: SyncTelemetryAttributes;
+}
+/**
+ * Span API exposed to Syncular internals.
+ */
+export interface SyncSpan {
+    setAttribute(name: string, value: SyncTelemetryAttributeValue): void;
+    setAttributes(attributes: SyncTelemetryAttributes): void;
+    setStatus(status: 'ok' | 'error'): void;
+}
+/**
+ * Tracing interface.
+ */
+export interface SyncTracer {
+    startSpan<T>(options: SyncSpanOptions, callback: (span: SyncSpan) => T): T;
+}
+/**
+ * Metric record options.
+ */
+export interface SyncMetricOptions {
+    attributes?: SyncTelemetryAttributes;
+    unit?: string;
+}
+/**
+ * Metrics interface.
+ */
+export interface SyncMetrics {
+    count(name: string, value?: number, options?: SyncMetricOptions): void;
+    gauge(name: string, value: number, options?: SyncMetricOptions): void;
+    distribution(name: string, value: number, options?: SyncMetricOptions): void;
+}
+/**
+ * Unified telemetry interface.
+ */
+export interface SyncTelemetry {
+    log(event: SyncTelemetryEvent): void;
+    tracer: SyncTracer;
+    metrics: SyncMetrics;
+    captureException(error: unknown, context?: Record<string, unknown>): void;
+}
+/**
+ * Create console-backed default telemetry (logs only; no-op tracing/metrics).
+ */
+export declare function createDefaultSyncTelemetry(): SyncTelemetry;
+/**
+ * Get currently configured telemetry backend.
+ */
+export declare function getSyncTelemetry(): SyncTelemetry;
+/**
+ * Replace active telemetry backend.
+ */
+export declare function configureSyncTelemetry(telemetry: SyncTelemetry): void;
+/**
+ * Reset telemetry backend to default console implementation.
+ */
+export declare function resetSyncTelemetry(): void;
+/**
+ * Capture an exception through the active telemetry backend.
+ */
+export declare function captureSyncException(error: unknown, context?: Record<string, unknown>): void;
+/**
+ * Start a span through the active telemetry backend.
+ */
+export declare function startSyncSpan<T>(options: SyncSpanOptions, callback: (span: SyncSpan) => T): T;
+/**
+ * Record a counter metric through the active telemetry backend.
+ */
+export declare function countSyncMetric(name: string, value?: number, options?: SyncMetricOptions): void;
+/**
+ * Record a gauge metric through the active telemetry backend.
+ */
+export declare function gaugeSyncMetric(name: string, value: number, options?: SyncMetricOptions): void;
+/**
+ * Record a distribution metric through the active telemetry backend.
+ */
+export declare function distributionSyncMetric(name: string, value: number, options?: SyncMetricOptions): void;
+//# sourceMappingURL=telemetry.d.ts.map

package/dist/telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.ts","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}

package/dist/telemetry.js

@@ -0,0 +1,113 @@
+/**
+ * @syncular/core - Runtime telemetry abstraction
+ *
+ * Provides vendor-neutral logging, tracing, and metrics interfaces so
+ * Syncular libraries can emit telemetry without coupling to a specific SDK.
+ */
+const noopSpan = {
+    setAttribute() { },
+    setAttributes() { },
+    setStatus() { },
+};
+const noopTracer = {
+    startSpan(_options, callback) {
+        return callback(noopSpan);
+    },
+};
+const noopMetrics = {
+    count() { },
+    gauge() { },
+    distribution() { },
+};
+function createConsoleLogger() {
+    const isNode = typeof globalThis !== 'undefined' &&
+        typeof globalThis.setImmediate === 'function';
+    const defer = isNode
+        ? (fn) => globalThis.setImmediate(fn)
+        : (fn) => setTimeout(fn, 0);
+    return (event) => {
+        defer(() => {
+            const level = event.level ?? (event.error ? 'error' : 'info');
+            const payload = {
+                timestamp: new Date().toISOString(),
+                level,
+                ...event,
+            };
+            console.log(JSON.stringify(payload));
+        });
+    };
+}
+/**
+ * Create console-backed default telemetry (logs only; no-op tracing/metrics).
+ */
+export function createDefaultSyncTelemetry() {
+    const logger = createConsoleLogger();
+    return {
+        log(event) {
+            logger(event);
+        },
+        tracer: noopTracer,
+        metrics: noopMetrics,
+        captureException(error, context) {
+            const message = error instanceof Error
+                ? error.message
+                : `Unknown error: ${String(error)}`;
+            logger({
+                event: 'sync.exception',
+                level: 'error',
+                error: message,
+                ...(context ?? {}),
+            });
+        },
+    };
+}
+let activeSyncTelemetry = createDefaultSyncTelemetry();
+/**
+ * Get currently configured telemetry backend.
+ */
+export function getSyncTelemetry() {
+    return activeSyncTelemetry;
+}
+/**
+ * Replace active telemetry backend.
+ */
+export function configureSyncTelemetry(telemetry) {
+    activeSyncTelemetry = telemetry;
+}
+/**
+ * Reset telemetry backend to default console implementation.
+ */
+export function resetSyncTelemetry() {
+    activeSyncTelemetry = createDefaultSyncTelemetry();
+}
+/**
+ * Capture an exception through the active telemetry backend.
+ */
+export function captureSyncException(error, context) {
+    activeSyncTelemetry.captureException(error, context);
+}
+/**
+ * Start a span through the active telemetry backend.
+ */
+export function startSyncSpan(options, callback) {
+    return activeSyncTelemetry.tracer.startSpan(options, callback);
+}
+/**
+ * Record a counter metric through the active telemetry backend.
+ */
+export function countSyncMetric(name, value, options) {
+    activeSyncTelemetry.metrics.count(name, value, options);
+}
+/**
+ * Record a gauge metric through the active telemetry backend.
+ */
+export function gaugeSyncMetric(name, value, options) {
+    activeSyncTelemetry.metrics.gauge(name, value, options);
+}
+/**
+ * Record a distribution metric through the active telemetry backend.
+ */
+export function distributionSyncMetric(name, value, options) {
+    activeSyncTelemetry.metrics.distribution(name, value, options);
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../src/telemetry.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncular/core",
-  "version": "0.0.1-83",
+  "version": "0.0.1-89",
   "description": "Core protocol types and shared utilities for the Syncular sync framework",
   "license": "MIT",
   "author": "Benjamin Kniffler",

package/src/__tests__/telemetry.test.ts

@@ -0,0 +1,170 @@
+import { describe, expect, test } from 'bun:test';
+import { logSyncEvent } from '../logger';
+import {
+  captureSyncException,
+  configureSyncTelemetry,
+  countSyncMetric,
+  distributionSyncMetric,
+  gaugeSyncMetric,
+  getSyncTelemetry,
+  resetSyncTelemetry,
+  type SyncMetricOptions,
+  type SyncSpan,
+  type SyncSpanOptions,
+  type SyncTelemetry,
+  type SyncTelemetryEvent,
+  startSyncSpan,
+} from '../telemetry';
+
+interface CapturedCountMetric {
+  name: string;
+  value: number | undefined;
+  options: SyncMetricOptions | undefined;
+}
+
+interface CapturedValueMetric {
+  name: string;
+  value: number;
+  options: SyncMetricOptions | undefined;
+}
+
+function createTestTelemetry(calls: {
+  logs: SyncTelemetryEvent[];
+  countMetrics: CapturedCountMetric[];
+  gaugeMetrics: CapturedValueMetric[];
+  distributionMetrics: CapturedValueMetric[];
+  spans: SyncSpanOptions[];
+  exceptions: Array<{
+    error: unknown;
+    context: Record<string, unknown> | undefined;
+  }>;
+}): SyncTelemetry {
+  return {
+    log(event) {
+      calls.logs.push(event);
+    },
+    tracer: {
+      startSpan(options, callback) {
+        calls.spans.push(options);
+        const span: SyncSpan = {
+          setAttribute() {},
+          setAttributes() {},
+          setStatus() {},
+        };
+        return callback(span);
+      },
+    },
+    metrics: {
+      count(name, value, options) {
+        calls.countMetrics.push({ name, value, options });
+      },
+      gauge(name, value, options) {
+        calls.gaugeMetrics.push({ name, value, options });
+      },
+      distribution(name, value, options) {
+        calls.distributionMetrics.push({ name, value, options });
+      },
+    },
+    captureException(error, context) {
+      calls.exceptions.push({ error, context });
+    },
+  };
+}
+
+describe('sync telemetry configuration', () => {
+  test('routes logger, metrics, spans, and exceptions to configured backend', () => {
+    const calls = {
+      logs: [] as SyncTelemetryEvent[],
+      countMetrics: [] as CapturedCountMetric[],
+      gaugeMetrics: [] as CapturedValueMetric[],
+      distributionMetrics: [] as CapturedValueMetric[],
+      spans: [] as SyncSpanOptions[],
+      exceptions: [] as Array<{
+        error: unknown;
+        context: Record<string, unknown> | undefined;
+      }>,
+    };
+    const telemetry = createTestTelemetry(calls);
+    const previous = getSyncTelemetry();
+
+    try {
+      configureSyncTelemetry(telemetry);
+
+      logSyncEvent({ event: 'sync.test.log', rowCount: 3 });
+
+      const spanResult = startSyncSpan(
+        {
+          name: 'sync.test.span',
+          op: 'sync.test',
+          attributes: { transport: 'ws' },
+        },
+        () => 'done'
+      );
+
+      countSyncMetric('sync.test.count', 2, {
+        attributes: { source: 'unit-test' },
+      });
+      gaugeSyncMetric('sync.test.gauge', 7, { unit: 'millisecond' });
+      distributionSyncMetric('sync.test.dist', 13);
+      captureSyncException(new Error('boom'), {
+        operation: 'unit-test',
+      });
+
+      expect(spanResult).toBe('done');
+      expect(calls.logs).toEqual([{ event: 'sync.test.log', rowCount: 3 }]);
+      expect(calls.spans).toEqual([
+        {
+          name: 'sync.test.span',
+          op: 'sync.test',
+          attributes: { transport: 'ws' },
+        },
+      ]);
+      expect(calls.countMetrics).toEqual([
+        {
+          name: 'sync.test.count',
+          value: 2,
+          options: { attributes: { source: 'unit-test' } },
+        },
+      ]);
+      expect(calls.gaugeMetrics).toEqual([
+        {
+          name: 'sync.test.gauge',
+          value: 7,
+          options: { unit: 'millisecond' },
+        },
+      ]);
+      expect(calls.distributionMetrics).toEqual([
+        {
+          name: 'sync.test.dist',
+          value: 13,
+          options: undefined,
+        },
+      ]);
+      expect(calls.exceptions).toHaveLength(1);
+      expect(calls.exceptions[0]?.context).toEqual({ operation: 'unit-test' });
+    } finally {
+      configureSyncTelemetry(previous);
+    }
+  });
+
+  test('resetSyncTelemetry swaps out custom telemetry backend', () => {
+    const calls = {
+      logs: [] as SyncTelemetryEvent[],
+      countMetrics: [] as CapturedCountMetric[],
+      gaugeMetrics: [] as CapturedValueMetric[],
+      distributionMetrics: [] as CapturedValueMetric[],
+      spans: [] as SyncSpanOptions[],
+      exceptions: [] as Array<{
+        error: unknown;
+        context: Record<string, unknown> | undefined;
+      }>,
+    };
+    const telemetry = createTestTelemetry(calls);
+
+    configureSyncTelemetry(telemetry);
+    resetSyncTelemetry();
+    logSyncEvent({ event: 'sync.default.logger' });
+
+    expect(calls.logs).toHaveLength(0);
+  });
+});

package/src/index.ts

@@ -24,6 +24,8 @@ export * from './proxy';
 export * from './schemas';
 // Scope types, patterns, and utilities
 export * from './scopes';
+// Telemetry abstraction
+export * from './telemetry';
 // Data transformation hooks
 export * from './transforms';
 // Transport and conflict types (protocol types come from ./schemas)

package/src/logger.ts

@@ -1,69 +1,27 @@
 /**
  * @syncular/core - Structured logging utilities for sync operations
  *
- * Outputs JSON lines for easy parsing by log aggregation tools.
- * Each log event includes a timestamp and event type.
+ * Uses the active telemetry backend configured via `configureSyncTelemetry()`.
  */
 
-/**
- * Sync log event structure
- */
-interface SyncLogEvent {
-  /** Event type identifier */
-  event: string;
-  /** User ID (optional) */
-  userId?: string;
-  /** Operation duration in milliseconds (optional) */
-  durationMs?: number;
-  /** Number of rows affected (optional) */
-  rowCount?: number;
-  /** Whether a full reset was required (optional) */
-  resetRequired?: boolean;
-  /** Error message if operation failed (optional) */
-  error?: string;
-  /** Additional arbitrary properties */
-  [key: string]: unknown;
-}
+import { getSyncTelemetry, type SyncTelemetryEvent } from './telemetry';
 
 /**
- * Logger function type - allows custom logging implementations
+ * Sync log event structure.
  */
-type SyncLogger = (event: SyncLogEvent) => void;
+export type SyncLogEvent = SyncTelemetryEvent;
 
 /**
- * Default logger that outputs JSON lines to console.
- * Non-blocking - defers logging to avoid blocking the event loop.
- *
- * On server (Node.js), uses setImmediate.
- * On client (browser), uses setTimeout(0).
+ * Logger function type.
  */
-function createDefaultLogger(): SyncLogger {
-  // Detect environment
-  const isNode =
-    typeof globalThis !== 'undefined' &&
-    typeof globalThis.setImmediate === 'function';
-
-  const defer = isNode
-    ? (fn: () => void) => globalThis.setImmediate(fn)
-    : (fn: () => void) => setTimeout(fn, 0);
-
-  return (event: SyncLogEvent) => {
-    defer(() => {
-      console.log(
-        JSON.stringify({
-          timestamp: new Date().toISOString(),
-          ...event,
-        })
-      );
-    });
-  };
-}
+export type SyncLogger = (event: SyncLogEvent) => void;
 
 /**
- * Log a sync event using the default logger.
- * For custom logging, create your own logger with createDefaultLogger pattern.
+ * Log a sync event using the currently configured telemetry backend.
  */
-export const logSyncEvent: SyncLogger = createDefaultLogger();
+export const logSyncEvent: SyncLogger = (event) => {
+  getSyncTelemetry().log(event);
+};
 
 /**
  * Create a timer for measuring operation duration.

package/src/telemetry.ts

@@ -0,0 +1,238 @@
+/**
+ * @syncular/core - Runtime telemetry abstraction
+ *
+ * Provides vendor-neutral logging, tracing, and metrics interfaces so
+ * Syncular libraries can emit telemetry without coupling to a specific SDK.
+ */
+
+/**
+ * Supported log levels.
+ */
+export type SyncTelemetryLevel =
+  | 'trace'
+  | 'debug'
+  | 'info'
+  | 'warn'
+  | 'error'
+  | 'fatal';
+
+/**
+ * Primitive attribute value used by traces and metrics.
+ */
+export type SyncTelemetryAttributeValue = string | number | boolean;
+
+/**
+ * Attribute bag used by traces and metrics.
+ */
+export type SyncTelemetryAttributes = Record<
+  string,
+  SyncTelemetryAttributeValue
+>;
+
+/**
+ * Structured sync log event.
+ */
+export interface SyncTelemetryEvent {
+  event: string;
+  level?: SyncTelemetryLevel;
+  userId?: string;
+  durationMs?: number;
+  rowCount?: number;
+  resetRequired?: boolean;
+  error?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Span creation options.
+ */
+export interface SyncSpanOptions {
+  name: string;
+  op?: string;
+  attributes?: SyncTelemetryAttributes;
+}
+
+/**
+ * Span API exposed to Syncular internals.
+ */
+export interface SyncSpan {
+  setAttribute(name: string, value: SyncTelemetryAttributeValue): void;
+  setAttributes(attributes: SyncTelemetryAttributes): void;
+  setStatus(status: 'ok' | 'error'): void;
+}
+
+/**
+ * Tracing interface.
+ */
+export interface SyncTracer {
+  startSpan<T>(options: SyncSpanOptions, callback: (span: SyncSpan) => T): T;
+}
+
+/**
+ * Metric record options.
+ */
+export interface SyncMetricOptions {
+  attributes?: SyncTelemetryAttributes;
+  unit?: string;
+}
+
+/**
+ * Metrics interface.
+ */
+export interface SyncMetrics {
+  count(name: string, value?: number, options?: SyncMetricOptions): void;
+  gauge(name: string, value: number, options?: SyncMetricOptions): void;
+  distribution(name: string, value: number, options?: SyncMetricOptions): void;
+}
+
+/**
+ * Unified telemetry interface.
+ */
+export interface SyncTelemetry {
+  log(event: SyncTelemetryEvent): void;
+  tracer: SyncTracer;
+  metrics: SyncMetrics;
+  captureException(error: unknown, context?: Record<string, unknown>): void;
+}
+
+const noopSpan: SyncSpan = {
+  setAttribute() {},
+  setAttributes() {},
+  setStatus() {},
+};
+
+const noopTracer: SyncTracer = {
+  startSpan(_options, callback) {
+    return callback(noopSpan);
+  },
+};
+
+const noopMetrics: SyncMetrics = {
+  count() {},
+  gauge() {},
+  distribution() {},
+};
+
+function createConsoleLogger(): (event: SyncTelemetryEvent) => void {
+  const isNode =
+    typeof globalThis !== 'undefined' &&
+    typeof globalThis.setImmediate === 'function';
+
+  const defer = isNode
+    ? (fn: () => void) => globalThis.setImmediate(fn)
+    : (fn: () => void) => setTimeout(fn, 0);
+
+  return (event: SyncTelemetryEvent) => {
+    defer(() => {
+      const level = event.level ?? (event.error ? 'error' : 'info');
+      const payload = {
+        timestamp: new Date().toISOString(),
+        level,
+        ...event,
+      };
+      console.log(JSON.stringify(payload));
+    });
+  };
+}
+
+/**
+ * Create console-backed default telemetry (logs only; no-op tracing/metrics).
+ */
+export function createDefaultSyncTelemetry(): SyncTelemetry {
+  const logger = createConsoleLogger();
+  return {
+    log(event) {
+      logger(event);
+    },
+    tracer: noopTracer,
+    metrics: noopMetrics,
+    captureException(error, context) {
+      const message =
+        error instanceof Error
+          ? error.message
+          : `Unknown error: ${String(error)}`;
+      logger({
+        event: 'sync.exception',
+        level: 'error',
+        error: message,
+        ...(context ?? {}),
+      });
+    },
+  };
+}
+
+let activeSyncTelemetry: SyncTelemetry = createDefaultSyncTelemetry();
+
+/**
+ * Get currently configured telemetry backend.
+ */
+export function getSyncTelemetry(): SyncTelemetry {
+  return activeSyncTelemetry;
+}
+
+/**
+ * Replace active telemetry backend.
+ */
+export function configureSyncTelemetry(telemetry: SyncTelemetry): void {
+  activeSyncTelemetry = telemetry;
+}
+
+/**
+ * Reset telemetry backend to default console implementation.
+ */
+export function resetSyncTelemetry(): void {
+  activeSyncTelemetry = createDefaultSyncTelemetry();
+}
+
+/**
+ * Capture an exception through the active telemetry backend.
+ */
+export function captureSyncException(
+  error: unknown,
+  context?: Record<string, unknown>
+): void {
+  activeSyncTelemetry.captureException(error, context);
+}
+
+/**
+ * Start a span through the active telemetry backend.
+ */
+export function startSyncSpan<T>(
+  options: SyncSpanOptions,
+  callback: (span: SyncSpan) => T
+): T {
+  return activeSyncTelemetry.tracer.startSpan(options, callback);
+}
+
+/**
+ * Record a counter metric through the active telemetry backend.
+ */
+export function countSyncMetric(
+  name: string,
+  value?: number,
+  options?: SyncMetricOptions
+): void {
+  activeSyncTelemetry.metrics.count(name, value, options);
+}
+
+/**
+ * Record a gauge metric through the active telemetry backend.
+ */
+export function gaugeSyncMetric(
+  name: string,
+  value: number,
+  options?: SyncMetricOptions
+): void {
+  activeSyncTelemetry.metrics.gauge(name, value, options);
+}
+
+/**
+ * Record a distribution metric through the active telemetry backend.
+ */
+export function distributionSyncMetric(
+  name: string,
+  value: number,
+  options?: SyncMetricOptions
+): void {
+  activeSyncTelemetry.metrics.distribution(name, value, options);
+}