@syncular/observability-sentry 0.0.1-100

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@syncular/observability-sentry",
+  "version": "0.0.1-100",
+  "description": "Sentry adapters for Syncular telemetry",
+  "license": "MIT",
+  "author": "Benjamin Kniffler",
+  "homepage": "https://syncular.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/syncular/syncular.git",
+    "directory": "packages/observability-sentry"
+  },
+  "bugs": {
+    "url": "https://github.com/syncular/syncular/issues"
+  },
+  "keywords": [
+    "sync",
+    "offline-first",
+    "observability",
+    "sentry",
+    "telemetry"
+  ],
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": {
+        "types": "./src/index.ts",
+        "default": "./src/index.ts"
+      }
+    }
+  },
+  "scripts": {
+    "test": "bun test src",
+    "tsgo": "tsgo --noEmit",
+    "build": "tsgo",
+    "release": "bunx syncular-publish"
+  },
+  "dependencies": {
+    "@sentry/cloudflare": "^10.38.0",
+    "@sentry/react": "^10.38.0",
+    "@syncular/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@syncular/config": "0.0.0"
+  },
+  "files": [
+    "dist",
+    "src"
+  ]
+}

package/src/browser.ts

@@ -0,0 +1,215 @@
+import * as Sentry from '@sentry/react';
+import {
+  configureSyncTelemetry,
+  type SyncMetricOptions,
+  type SyncTelemetry,
+  type SyncTelemetryAttributeValue,
+} from '@syncular/core';
+import { createSentrySyncTelemetry } from './shared';
+
+export type BrowserSentryInitOptions = Parameters<typeof Sentry.init>[0];
+export type BrowserSentryCaptureMessageLevel = Parameters<
+  typeof Sentry.captureMessage
+>[1];
+
+interface BrowserSentryCaptureMessageOptions {
+  level?: BrowserSentryCaptureMessageLevel;
+  tags?: Record<string, string>;
+}
+
+type BrowserSentryLogLevel =
+  | 'trace'
+  | 'debug'
+  | 'info'
+  | 'warn'
+  | 'error'
+  | 'fatal';
+
+interface BrowserSentryLogOptions {
+  level?: BrowserSentryLogLevel;
+  attributes?: Record<string, SyncTelemetryAttributeValue>;
+}
+
+function resolveBrowserLogMethod(
+  level: BrowserSentryLogLevel
+):
+  | ((
+      message: string,
+      attributes?: Record<string, SyncTelemetryAttributeValue>
+    ) => void)
+  | null {
+  switch (level) {
+    case 'trace':
+      return Sentry.logger.trace ?? Sentry.logger.debug ?? Sentry.logger.info;
+    case 'debug':
+      return Sentry.logger.debug ?? Sentry.logger.info;
+    case 'info':
+      return Sentry.logger.info;
+    case 'warn':
+      return Sentry.logger.warn ?? Sentry.logger.info;
+    case 'error':
+      return Sentry.logger.error ?? Sentry.logger.warn ?? Sentry.logger.info;
+    case 'fatal':
+      return (
+        Sentry.logger.fatal ??
+        Sentry.logger.error ??
+        Sentry.logger.warn ??
+        Sentry.logger.info
+      );
+    default:
+      return Sentry.logger.info;
+  }
+}
+
+function toCountMetricOptions(
+  options?: SyncMetricOptions
+): Parameters<typeof Sentry.metrics.count>[2] | undefined {
+  if (!options?.attributes) return undefined;
+  return { attributes: options.attributes };
+}
+
+function toValueMetricOptions(
+  options?: SyncMetricOptions
+): Parameters<typeof Sentry.metrics.gauge>[2] | undefined {
+  if (!options) return undefined;
+  const hasAttributes = Boolean(options.attributes);
+  const hasUnit = Boolean(options.unit);
+  if (!hasAttributes && !hasUnit) return undefined;
+  return {
+    attributes: options.attributes,
+    unit: options.unit,
+  };
+}
+
+/**
+ * Create a Syncular telemetry backend wired to `@sentry/react`.
+ */
+export function createBrowserSentryTelemetry(): SyncTelemetry {
+  return createSentrySyncTelemetry({
+    logger: Sentry.logger,
+    startSpan(options, callback) {
+      return Sentry.startSpan(options, (span) =>
+        callback({
+          setAttribute(name, value) {
+            span.setAttribute(name, value);
+          },
+          setAttributes(attributes) {
+            span.setAttributes(attributes);
+          },
+          setStatus(status) {
+            span.setStatus({
+              code: status === 'ok' ? 1 : 2,
+            });
+          },
+        })
+      );
+    },
+    metrics: {
+      count(name, value, options) {
+        const metricOptions = toCountMetricOptions(options);
+        if (metricOptions) {
+          Sentry.metrics.count(name, value, metricOptions);
+          return;
+        }
+        Sentry.metrics.count(name, value);
+      },
+      gauge(name, value, options) {
+        const metricOptions = toValueMetricOptions(options);
+        if (metricOptions) {
+          Sentry.metrics.gauge(name, value, metricOptions);
+          return;
+        }
+        Sentry.metrics.gauge(name, value);
+      },
+      distribution(name, value, options) {
+        const metricOptions = toValueMetricOptions(options);
+        if (metricOptions) {
+          Sentry.metrics.distribution(name, value, metricOptions);
+          return;
+        }
+        Sentry.metrics.distribution(name, value);
+      },
+    },
+    captureException(error) {
+      Sentry.captureException(error);
+    },
+  });
+}
+
+/**
+ * Configure Syncular core telemetry to use the browser Sentry adapter.
+ */
+export function configureBrowserSentryTelemetry(): SyncTelemetry {
+  const telemetry = createBrowserSentryTelemetry();
+  configureSyncTelemetry(telemetry);
+  return telemetry;
+}
+
+/**
+ * Initialize browser Sentry and configure Syncular telemetry.
+ */
+export function initAndConfigureBrowserSentry(
+  options: BrowserSentryInitOptions
+): SyncTelemetry {
+  const configuredOptions = ensureBrowserTracingIntegration(options);
+  Sentry.init(configuredOptions);
+  return configureBrowserSentryTelemetry();
+}
+
+function ensureBrowserTracingIntegration(
+  options: BrowserSentryInitOptions
+): BrowserSentryInitOptions {
+  const integrations = options.integrations;
+  if (typeof integrations === 'function') return options;
+
+  const configuredIntegrations = integrations ?? [];
+  const hasBrowserTracing = configuredIntegrations.some(
+    (integration) => integration.name === 'BrowserTracing'
+  );
+  if (hasBrowserTracing) return options;
+
+  return {
+    ...options,
+    integrations: [
+      Sentry.browserTracingIntegration(),
+      ...configuredIntegrations,
+    ],
+  };
+}
+
+/**
+ * Capture a browser message in Sentry with optional tags.
+ */
+export function captureBrowserSentryMessage(
+  message: string,
+  options?: BrowserSentryCaptureMessageOptions
+): void {
+  if (!options?.tags || Object.keys(options.tags).length === 0) {
+    Sentry.captureMessage(message, options?.level);
+    return;
+  }
+
+  Sentry.withScope((scope) => {
+    for (const [name, value] of Object.entries(options.tags ?? {})) {
+      scope.setTag(name, value);
+    }
+    Sentry.captureMessage(message, options?.level);
+  });
+}
+
+/**
+ * Emit a browser Sentry log entry.
+ */
+export function logBrowserSentryMessage(
+  message: string,
+  options?: BrowserSentryLogOptions
+): void {
+  const level = options?.level ?? 'info';
+  const logMethod = resolveBrowserLogMethod(level);
+  if (!logMethod) return;
+  if (!options?.attributes || Object.keys(options.attributes).length === 0) {
+    logMethod(message);
+    return;
+  }
+  logMethod(message, options.attributes);
+}

package/src/cloudflare.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  attachCloudflareSentryTraceHeaders,
+  getCloudflareSentryTraceHeaders,
+} from './cloudflare';
+
+describe('cloudflare tracing helpers', () => {
+  test('extracts trace headers from sentry trace data', () => {
+    expect(
+      getCloudflareSentryTraceHeaders({
+        'sentry-trace': 'trace-id-span-id-1',
+        baggage: 'sample_rate=1',
+      })
+    ).toEqual({
+      sentryTrace: 'trace-id-span-id-1',
+      baggage: 'sample_rate=1',
+    });
+  });
+
+  test('returns original request when trace headers are missing', () => {
+    const request = new Request('https://example.com/api/sync', {
+      method: 'POST',
+      headers: { 'x-custom': '1' },
+      body: '{}',
+    });
+
+    const result = attachCloudflareSentryTraceHeaders(request, {});
+    expect(result).toBe(request);
+  });
+
+  test('adds sentry trace headers to cloned request', async () => {
+    const request = new Request('https://example.com/api/sync', {
+      method: 'POST',
+      headers: { 'x-custom': '1' },
+      body: '{"ok":true}',
+    });
+
+    const result = attachCloudflareSentryTraceHeaders(request, {
+      sentryTrace: 'trace-id-span-id-1',
+      baggage: 'sample_rate=1',
+    });
+
+    expect(result).not.toBe(request);
+    expect(result.headers.get('x-custom')).toBe('1');
+    expect(result.headers.get('sentry-trace')).toBe('trace-id-span-id-1');
+    expect(result.headers.get('baggage')).toBe('sample_rate=1');
+    expect(await result.text()).toBe('{"ok":true}');
+  });
+});

package/src/cloudflare.ts

@@ -0,0 +1,230 @@
+import * as Sentry from '@sentry/cloudflare';
+import {
+  configureSyncTelemetry,
+  type SyncMetricOptions,
+  type SyncTelemetry,
+  type SyncTelemetryAttributeValue,
+} from '@syncular/core';
+import { createSentrySyncTelemetry } from './shared';
+
+function toCountMetricOptions(
+  options?: SyncMetricOptions
+): Parameters<typeof Sentry.metrics.count>[2] | undefined {
+  if (!options?.attributes) return undefined;
+  return { attributes: options.attributes };
+}
+
+function toValueMetricOptions(
+  options?: SyncMetricOptions
+): Parameters<typeof Sentry.metrics.gauge>[2] | undefined {
+  if (!options) return undefined;
+  const hasAttributes = Boolean(options.attributes);
+  const hasUnit = Boolean(options.unit);
+  if (!hasAttributes && !hasUnit) return undefined;
+  return {
+    attributes: options.attributes,
+    unit: options.unit,
+  };
+}
+
+export type CloudflareSentryCaptureMessageLevel = Parameters<
+  typeof Sentry.captureMessage
+>[1];
+
+interface CloudflareSentryCaptureMessageOptions {
+  level?: CloudflareSentryCaptureMessageLevel;
+  tags?: Record<string, string>;
+}
+
+type CloudflareSentryLogLevel =
+  | 'trace'
+  | 'debug'
+  | 'info'
+  | 'warn'
+  | 'error'
+  | 'fatal';
+
+interface CloudflareSentryLogOptions {
+  level?: CloudflareSentryLogLevel;
+  attributes?: Record<string, SyncTelemetryAttributeValue>;
+}
+
+function resolveCloudflareLogMethod(
+  level: CloudflareSentryLogLevel
+):
+  | ((
+      message: string,
+      attributes?: Record<string, SyncTelemetryAttributeValue>
+    ) => void)
+  | null {
+  switch (level) {
+    case 'trace':
+      return Sentry.logger.trace ?? Sentry.logger.debug ?? Sentry.logger.info;
+    case 'debug':
+      return Sentry.logger.debug ?? Sentry.logger.info;
+    case 'info':
+      return Sentry.logger.info;
+    case 'warn':
+      return Sentry.logger.warn ?? Sentry.logger.info;
+    case 'error':
+      return Sentry.logger.error ?? Sentry.logger.warn ?? Sentry.logger.info;
+    case 'fatal':
+      return (
+        Sentry.logger.fatal ??
+        Sentry.logger.error ??
+        Sentry.logger.warn ??
+        Sentry.logger.info
+      );
+    default:
+      return Sentry.logger.info;
+  }
+}
+
+/**
+ * Re-export Cloudflare Sentry worker wrapper.
+ */
+export const withCloudflareSentry = Sentry.withSentry;
+export const instrumentCloudflareDurableObjectWithSentry =
+  Sentry.instrumentDurableObjectWithSentry;
+
+export interface CloudflareSentryTraceHeaders {
+  sentryTrace?: string;
+  baggage?: string;
+}
+
+/**
+ * Read current trace headers from the active Cloudflare Sentry scope.
+ */
+export function getCloudflareSentryTraceHeaders(
+  traceData: ReturnType<typeof Sentry.getTraceData> = Sentry.getTraceData()
+): CloudflareSentryTraceHeaders {
+  const sentryTrace = traceData['sentry-trace']?.trim();
+  const baggage = traceData.baggage?.trim();
+  return {
+    ...(sentryTrace ? { sentryTrace } : {}),
+    ...(baggage ? { baggage } : {}),
+  };
+}
+
+/**
+ * Clone a request and attach active Cloudflare trace headers when available.
+ */
+export function attachCloudflareSentryTraceHeaders(
+  request: Request,
+  traceHeaders: CloudflareSentryTraceHeaders = getCloudflareSentryTraceHeaders()
+): Request {
+  if (!traceHeaders.sentryTrace && !traceHeaders.baggage) {
+    return request;
+  }
+
+  const headers = new Headers(request.headers);
+  if (traceHeaders.sentryTrace) {
+    headers.set('sentry-trace', traceHeaders.sentryTrace);
+  }
+  if (traceHeaders.baggage) {
+    headers.set('baggage', traceHeaders.baggage);
+  }
+
+  return new Request(request, { headers });
+}
+
+/**
+ * Create a Syncular telemetry backend wired to `@sentry/cloudflare`.
+ */
+export function createCloudflareSentryTelemetry(): SyncTelemetry {
+  return createSentrySyncTelemetry({
+    logger: Sentry.logger,
+    startSpan(options, callback) {
+      return Sentry.startSpan(options, (span) =>
+        callback({
+          setAttribute(name, value) {
+            span.setAttribute(name, value);
+          },
+          setAttributes(attributes) {
+            span.setAttributes(attributes);
+          },
+          setStatus(status) {
+            span.setStatus({
+              code: status === 'ok' ? 1 : 2,
+            });
+          },
+        })
+      );
+    },
+    metrics: {
+      count(name, value, options) {
+        const metricOptions = toCountMetricOptions(options);
+        if (metricOptions) {
+          Sentry.metrics.count(name, value, metricOptions);
+          return;
+        }
+        Sentry.metrics.count(name, value);
+      },
+      gauge(name, value, options) {
+        const metricOptions = toValueMetricOptions(options);
+        if (metricOptions) {
+          Sentry.metrics.gauge(name, value, metricOptions);
+          return;
+        }
+        Sentry.metrics.gauge(name, value);
+      },
+      distribution(name, value, options) {
+        const metricOptions = toValueMetricOptions(options);
+        if (metricOptions) {
+          Sentry.metrics.distribution(name, value, metricOptions);
+          return;
+        }
+        Sentry.metrics.distribution(name, value);
+      },
+    },
+    captureException(error) {
+      Sentry.captureException(error);
+    },
+  });
+}
+
+/**
+ * Configure Syncular core telemetry to use the Cloudflare Sentry adapter.
+ */
+export function configureCloudflareSentryTelemetry(): SyncTelemetry {
+  const telemetry = createCloudflareSentryTelemetry();
+  configureSyncTelemetry(telemetry);
+  return telemetry;
+}
+
+/**
+ * Capture a worker message in Sentry with optional tags.
+ */
+export function captureCloudflareSentryMessage(
+  message: string,
+  options?: CloudflareSentryCaptureMessageOptions
+): void {
+  if (!options?.tags || Object.keys(options.tags).length === 0) {
+    Sentry.captureMessage(message, options?.level);
+    return;
+  }
+
+  Sentry.withScope((scope) => {
+    for (const [name, value] of Object.entries(options.tags ?? {})) {
+      scope.setTag(name, value);
+    }
+    Sentry.captureMessage(message, options?.level);
+  });
+}
+
+/**
+ * Emit a Cloudflare Sentry log entry.
+ */
+export function logCloudflareSentryMessage(
+  message: string,
+  options?: CloudflareSentryLogOptions
+): void {
+  const level = options?.level ?? 'info';
+  const logMethod = resolveCloudflareLogMethod(level);
+  if (!logMethod) return;
+  if (!options?.attributes || Object.keys(options.attributes).length === 0) {
+    logMethod(message);
+    return;
+  }
+  logMethod(message, options.attributes);
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export * from './browser';
+export * from './cloudflare';
+export * from './shared';

package/src/shared.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from 'bun:test';
+import type { SyncSpanOptions } from '@syncular/core';
+import {
+  createSentrySyncTelemetry,
+  type SentryTelemetryAdapter,
+} from './shared';
+
+describe('createSentrySyncTelemetry', () => {
+  test('routes logs, spans, metrics, and exceptions', () => {
+    const logs: Array<{
+      level: string;
+      message: string;
+      attributes?: Record<string, unknown>;
+    }> = [];
+    const spans: SyncSpanOptions[] = [];
+    const metricCalls: Array<{ type: string; name: string; value: number }> =
+      [];
+    const exceptions: unknown[] = [];
+
+    const adapter: SentryTelemetryAdapter = {
+      logger: {
+        info(message, attributes) {
+          logs.push({ level: 'info', message, attributes });
+        },
+        error(message, attributes) {
+          logs.push({ level: 'error', message, attributes });
+        },
+      },
+      startSpan(options, callback) {
+        spans.push(options);
+        return callback({
+          setAttribute() {},
+          setAttributes() {},
+          setStatus() {},
+        });
+      },
+      metrics: {
+        count(name, value) {
+          metricCalls.push({ type: 'count', name, value });
+        },
+        gauge(name, value) {
+          metricCalls.push({ type: 'gauge', name, value });
+        },
+        distribution(name, value) {
+          metricCalls.push({ type: 'distribution', name, value });
+        },
+      },
+      captureException(error) {
+        exceptions.push(error);
+      },
+    };
+
+    const telemetry = createSentrySyncTelemetry(adapter);
+
+    telemetry.log({ event: 'sync.ok', rowCount: 2 });
+    telemetry.log({ event: 'sync.fail', error: 'boom' });
+
+    const spanValue = telemetry.tracer.startSpan(
+      {
+        name: 'sync.span',
+        op: 'sync',
+      },
+      (span) => {
+        span.setAttribute('transport', 'ws');
+        span.setStatus('ok');
+        return 123;
+      }
+    );
+
+    telemetry.metrics.count('sync.count');
+    telemetry.metrics.gauge('sync.gauge', 7);
+    telemetry.metrics.distribution('sync.dist', 42);
+    telemetry.captureException(new Error('crash'), { requestId: 'r1' });
+
+    expect(spanValue).toBe(123);
+    expect(logs[0]).toEqual({
+      level: 'info',
+      message: 'sync.ok',
+      attributes: { rowCount: 2 },
+    });
+    expect(logs[1]).toEqual({
+      level: 'error',
+      message: 'sync.fail',
+      attributes: { error: 'boom' },
+    });
+    expect(spans).toEqual([
+      {
+        name: 'sync.span',
+        op: 'sync',
+      },
+    ]);
+    expect(metricCalls).toEqual([
+      { type: 'count', name: 'sync.count', value: 1 },
+      { type: 'gauge', name: 'sync.gauge', value: 7 },
+      { type: 'distribution', name: 'sync.dist', value: 42 },
+    ]);
+    expect(exceptions).toHaveLength(1);
+    expect(logs.at(-1)).toEqual({
+      level: 'error',
+      message: 'sync.exception.context',
+      attributes: { requestId: 'r1' },
+    });
+  });
+
+  test('sanitizes non-primitive log attributes', () => {
+    const logs: Array<{
+      level: string;
+      message: string;
+      attributes?: Record<string, unknown>;
+    }> = [];
+
+    const telemetry = createSentrySyncTelemetry({
+      logger: {
+        info(message, attributes) {
+          logs.push({ level: 'info', message, attributes });
+        },
+      },
+    });
+
+    telemetry.log({
+      event: 'sync.attributes',
+      id: 'abc',
+      nested: { ok: true },
+      values: [1, 2, 3],
+      enabled: true,
+      count: 3,
+      ignored: undefined,
+      nonFinite: Number.POSITIVE_INFINITY,
+    });
+
+    expect(logs).toEqual([
+      {
+        level: 'info',
+        message: 'sync.attributes',
+        attributes: {
+          id: 'abc',
+          nested: '{"ok":true}',
+          values: '[1,2,3]',
+          enabled: true,
+          count: 3,
+        },
+      },
+    ]);
+  });
+});