feat(cloudflare): Add Cloudflare D1 instrumentation

packages/cloudflare/README.md

@@ -136,3 +136,15 @@ Sentry.captureEvent({
   ],
 });
 ```
+
+## Cloudflare D1 Instrumentation
+
+You can use the `instrumentD1WithSentry` method to instrument [Cloudflare D1](https://developers.cloudflare.com/d1/),
+Cloudflare's serverless SQL database with Sentry.
+
+```javascript
+// env.DB is the D1 DB binding configured in your `wrangler.toml`
+const db = instrumentD1WithSentry(env.DB);
+// Now you can use the database as usual
+await db.prepare('SELECT * FROM table WHERE id = ?').bind(1).run();
+```

packages/cloudflare/src/d1.ts

@@ -0,0 +1,154 @@
+import type { D1Database, D1PreparedStatement, D1Response } from '@cloudflare/workers-types';
+import { SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN, SPAN_STATUS_ERROR, addBreadcrumb, startSpan } from '@sentry/core';
+import type { Span, SpanAttributes, StartSpanOptions } from '@sentry/types';
+
+// Patching is based on internal Cloudflare D1 API
+// https://github.com/cloudflare/workerd/blob/cd5279e7b305003f1d9c851e73efa9d67e4b68b2/src/cloudflare/internal/d1-api.ts
+
+const patchedStatement = new WeakSet<D1PreparedStatement>();
+
+/**
+ * Patches the query methods of a Cloudflare D1 prepared statement with Sentry.
+ */
+function instrumentD1PreparedStatementQueries(statement: D1PreparedStatement, query: string): D1PreparedStatement {
+  if (patchedStatement.has(statement)) {
+    return statement;
+  }
+
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  statement.first = new Proxy(statement.first, {
+    apply(target, thisArg, args: Parameters<typeof statement.first>) {
+      return startSpan(createStartSpanOptions(query, 'first'), async () => {
+        const res = await Reflect.apply(target, thisArg, args);
+        createD1Breadcrumb(query, 'first');
+        return res;
+      });
+    },
+  });
+
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  statement.run = new Proxy(statement.run, {
+    apply(target, thisArg, args: Parameters<typeof statement.run>) {
+      return startSpan(createStartSpanOptions(query, 'run'), async span => {
+        const d1Response = await Reflect.apply(target, thisArg, args);
+        applyD1ReturnObjectToSpan(span, d1Response);
+        createD1Breadcrumb(query, 'run', d1Response);
+        return d1Response;
+      });
+    },
+  });
+
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  statement.all = new Proxy(statement.all, {
+    apply(target, thisArg, args: Parameters<typeof statement.all>) {
+      return startSpan(createStartSpanOptions(query, 'all'), async span => {
+        const d1Result = await Reflect.apply(target, thisArg, args);
+        applyD1ReturnObjectToSpan(span, d1Result);
+        createD1Breadcrumb(query, 'all', d1Result);
+        return d1Result;
+      });
+    },
+  });
+
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  statement.raw = new Proxy(statement.raw, {
+    apply(target, thisArg, args: Parameters<typeof statement.raw>) {
+      return startSpan(createStartSpanOptions(query, 'raw'), async () => {
+        const res = await Reflect.apply(target, thisArg, args);
+        createD1Breadcrumb(query, 'raw');
+        return res;
+      });
+    },
+  });
+
+  patchedStatement.add(statement);
+
+  return statement;
+}
+
+/**
+ * Instruments a Cloudflare D1 prepared statement with Sentry.
+ *
+ * This is meant to be used as a top-level call, under the hood it calls `instrumentD1PreparedStatementQueries`
+ * to patch the query methods. The reason for this abstraction is to ensure that the `bind` method is also patched.
+ */
+function instrumentD1PreparedStatement(statement: D1PreparedStatement, query: string): D1PreparedStatement {
+  // statement.bind() returns a new instance of D1PreparedStatement, so we have to patch it as well.
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  statement.bind = new Proxy(statement.bind, {
+    apply(target, thisArg, args: Parameters<typeof statement.bind>) {
+      return instrumentD1PreparedStatementQueries(Reflect.apply(target, thisArg, args), query);
+    },
+  });
+
+  return instrumentD1PreparedStatementQueries(statement, query);
+}
+
+/**
+ * Add D1Response meta information to a span.
+ *
+ * See: https://developers.cloudflare.com/d1/build-with-d1/d1-client-api/#return-object
+ */
+function applyD1ReturnObjectToSpan(span: Span, d1Result: D1Response): void {
+  if (!d1Result.success) {
+    span.setStatus({ code: SPAN_STATUS_ERROR });
+  }
+
+  span.setAttributes(getAttributesFromD1Response(d1Result));
+}
+
+function getAttributesFromD1Response(d1Result: D1Response): SpanAttributes {
+  return {
+    'cloudflare.d1.duration': d1Result.meta.duration,
+    'cloudflare.d1.rows_read': d1Result.meta.rows_read,
+    'cloudflare.d1.rows_written': d1Result.meta.rows_written,
+  };
+}
+
+function createD1Breadcrumb(query: string, type: 'first' | 'run' | 'all' | 'raw', d1Result?: D1Response): void {
+  addBreadcrumb({
+    category: 'query',
+    message: query,
+    data: {
+      ...(d1Result ? getAttributesFromD1Response(d1Result) : {}),
+      'cloudflare.d1.query_type': type,
+    },
+  });
+}
+
+function createStartSpanOptions(query: string, type: 'first' | 'run' | 'all' | 'raw'): StartSpanOptions {
+  return {
+    op: 'db.query',
+    name: query,
+    attributes: {
+      'cloudflare.d1.query_type': type,
+      [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.db.cloudflare.d1',
+    },
+  };
+}
+
+/**
+ * Instruments Cloudflare D1 bindings with Sentry.
+ *
+ * Currently, only prepared statements are instrumented. `db.exec` and `db.batch` are not instrumented.
+ *
+ * @example
+ *
+ * ```js
+ * // env.DB is the D1 DB binding configured in your `wrangler.toml`
+ * const db = instrumentD1WithSentry(env.DB);
+ * // Now you can use the database as usual
+ * await db.prepare('SELECT * FROM table WHERE id = ?').bind(1).run();
+ * ```
+ */
+export function instrumentD1WithSentry(db: D1Database): D1Database {
+  // eslint-disable-next-line @typescript-eslint/unbound-method
+  db.prepare = new Proxy(db.prepare, {
+    apply(target, thisArg, args: Parameters<typeof db.prepare>) {
+      const [query] = args;
+      return instrumentD1PreparedStatement(Reflect.apply(target, thisArg, args), query);
+    },
+  });
+
+  return db;
+}

packages/cloudflare/src/index.ts

@@ -91,3 +91,5 @@ export { CloudflareClient } from './client';
 export { getDefaultIntegrations } from './sdk';
 
 export { fetchIntegration } from './integrations/fetch';
+
+export { instrumentD1WithSentry } from './d1';