feat(cloudflare): Improve http span data (#16232)

While helping debug work in https://github.com/getsentry/sentry-mcp, I
noticed that we didn't attach `url.path` to the http fetch spans, which
made using the trace explorer harder to use.

This PR updates the cloudflare http instrumentation (fetch handlers for
regular workers and durable objects) to use a new
`getHttpSpanDetailsFromUrlObject` abstraction I built.

`getHttpSpanDetailsFromUrlObject` returns the http span name and it's
associated attributes, taking care to handle source, route names, and
handling both relative and full URLs.

This is related to all the
#15767 work I've
been doing.

Author: AbhiPrasad

packages/cloudflare/src/request.ts

@@ -1,17 +1,13 @@
 import type { ExecutionContext, IncomingRequestCfProperties } from '@cloudflare/workers-types';
-import type { SpanAttributes } from '@sentry/core';
 import {
   captureException,
   continueTrace,
   flush,
-  SEMANTIC_ATTRIBUTE_HTTP_REQUEST_METHOD,
+  getHttpSpanDetailsFromUrlObject,
+  parseStringToURLObject,
   SEMANTIC_ATTRIBUTE_SENTRY_OP,
-  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
-  SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
-  SEMANTIC_ATTRIBUTE_URL_FULL,
   setHttpStatus,
   startSpan,
-  stripUrlQueryAndFragment,
   withIsolationScope,
 } from '@sentry/core';
 import type { CloudflareOptions } from './client';
@@ -42,28 +38,15 @@ export function wrapRequestHandler(
     const client = init(options);
     isolationScope.setClient(client);
 
-    const attributes: SpanAttributes = {
-      [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: 'auto.http.cloudflare',
-      [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url',
-      [SEMANTIC_ATTRIBUTE_SENTRY_OP]: 'http.server',
-      [SEMANTIC_ATTRIBUTE_HTTP_REQUEST_METHOD]: request.method,
-      [SEMANTIC_ATTRIBUTE_URL_FULL]: request.url,
-    };
+    const urlObject = parseStringToURLObject(request.url);
+    const [name, attributes] = getHttpSpanDetailsFromUrlObject(urlObject, 'server', 'auto.http.cloudflare', request);
 
     const contentLength = request.headers.get('content-length');
     if (contentLength) {
       attributes['http.request.body.size'] = parseInt(contentLength, 10);
     }
 
-    let pathname = '';
-    try {
-      const url = new URL(request.url);
-      pathname = url.pathname;
-      attributes['server.address'] = url.hostname;
-      attributes['url.scheme'] = url.protocol.replace(':', '');
-    } catch {
-      // skip
-    }
+    attributes[SEMANTIC_ATTRIBUTE_SENTRY_OP] = 'http.server';
 
     addCloudResourceContext(isolationScope);
     if (request) {
@@ -74,8 +57,6 @@ export function wrapRequestHandler(
       }
     }
 
-    const routeName = `${request.method} ${pathname ? stripUrlQueryAndFragment(pathname) : '/'}`;
-
     // Do not capture spans for OPTIONS and HEAD requests
     if (request.method === 'OPTIONS' || request.method === 'HEAD') {
       try {
@@ -96,7 +77,7 @@ export function wrapRequestHandler(
         // See: https://developers.cloudflare.com/workers/runtime-apis/performance/
         return startSpan(
           {
-            name: routeName,
+            name,
             attributes,
           },
           async span => {

packages/cloudflare/test/request.test.ts

@@ -254,12 +254,13 @@ describe('withSentry', () => {
         data: {
           'sentry.origin': 'auto.http.cloudflare',
           'sentry.op': 'http.server',
-          'sentry.source': 'url',
+          'sentry.source': 'route',
           'http.request.method': 'GET',
           'url.full': 'https://example.com/',
           'server.address': 'example.com',
           'network.protocol.name': 'HTTP/1.1',
-          'url.scheme': 'https',
+          'url.scheme': 'https:',
+          'url.path': '/',
           'sentry.sample_rate': 1,
           'http.response.status_code': 200,
           'http.request.body.size': 10,
@@ -269,6 +270,8 @@ describe('withSentry', () => {
         span_id: expect.stringMatching(/[a-f0-9]{16}/),
         status: 'ok',
         trace_id: expect.stringMatching(/[a-f0-9]{32}/),
+        parent_span_id: undefined,
+        links: undefined,
       });
     });
   });

packages/core/src/index.ts

@@ -255,6 +255,7 @@ export {
   parseUrl,
   stripUrlQueryAndFragment,
   parseStringToURLObject,
+  getHttpSpanDetailsFromUrlObject,
   isURLObjectRelative,
   getSanitizedUrlStringFromUrlObject,
 } from './utils-hoist/url';

packages/core/src/utils-hoist/url.ts

@@ -1,3 +1,11 @@
+import {
+  SEMANTIC_ATTRIBUTE_HTTP_REQUEST_METHOD,
+  SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN,
+  SEMANTIC_ATTRIBUTE_SENTRY_SOURCE,
+  SEMANTIC_ATTRIBUTE_URL_FULL,
+} from '../semanticAttributes';
+import type { SpanAttributes } from '../types-hoist/span';
+
 type PartialURL = {
   host?: string;
   path?: string;
@@ -53,7 +61,7 @@ export function isURLObjectRelative(url: URLObject): url is RelativeURL {
  * @returns The parsed URL object or undefined if the URL is invalid
  */
 export function parseStringToURLObject(url: string, urlBase?: string | URL | undefined): URLObject | undefined {
-  const isRelative = url.startsWith('/');
+  const isRelative = url.indexOf('://') <= 0 && url.indexOf('//') !== 0;
   const base = urlBase ?? (isRelative ? DEFAULT_BASE_URL : undefined);
   try {
     // Use `canParse` to short-circuit the URL constructor if it's not a valid URL
@@ -107,6 +115,95 @@ export function getSanitizedUrlStringFromUrlObject(url: URLObject): string {
   return newUrl.toString();
 }
 
+type PartialRequest = {
+  method?: string;
+};
+
+function getHttpSpanNameFromUrlObject(
+  urlObject: URLObject | undefined,
+  kind: 'server' | 'client',
+  request?: PartialRequest,
+  routeName?: string,
+): string {
+  const method = request?.method?.toUpperCase() ?? 'GET';
+  const route = routeName
+    ? routeName
+    : urlObject
+      ? kind === 'client'
+        ? getSanitizedUrlStringFromUrlObject(urlObject)
+        : urlObject.pathname
+      : '/';
+
+  return `${method} ${route}`;
+}
+
+/**
+ * Takes a parsed URL object and returns a set of attributes for the span
+ * that represents the HTTP request for that url. This is used for both server
+ * and client http spans.
+ *
+ * Follows https://opentelemetry.io/docs/specs/semconv/http/.
+ *
+ * @param urlObject - see {@link parseStringToURLObject}
+ * @param kind - The type of HTTP operation (server or client)
+ * @param spanOrigin - The origin of the span
+ * @param request - The request object, see {@link PartialRequest}
+ * @param routeName - The name of the route, must be low cardinality
+ * @returns The span name and attributes for the HTTP operation
+ */
+export function getHttpSpanDetailsFromUrlObject(
+  urlObject: URLObject | undefined,
+  kind: 'server' | 'client',
+  spanOrigin: string,
+  request?: PartialRequest,
+  routeName?: string,
+): [name: string, attributes: SpanAttributes] {
+  const attributes: SpanAttributes = {
+    [SEMANTIC_ATTRIBUTE_SENTRY_ORIGIN]: spanOrigin,
+    [SEMANTIC_ATTRIBUTE_SENTRY_SOURCE]: 'url',
+  };
+
+  if (routeName) {
+    // This is based on https://opentelemetry.io/docs/specs/semconv/http/http-spans/#name
+    attributes[kind === 'server' ? 'http.route' : 'url.template'] = routeName;
+    attributes[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE] = 'route';
+  }
+
+  if (request?.method) {
+    attributes[SEMANTIC_ATTRIBUTE_HTTP_REQUEST_METHOD] = request.method.toUpperCase();
+  }
+
+  if (urlObject) {
+    if (urlObject.search) {
+      attributes['url.query'] = urlObject.search;
+    }
+    if (urlObject.hash) {
+      attributes['url.fragment'] = urlObject.hash;
+    }
+    if (urlObject.pathname) {
+      attributes['url.path'] = urlObject.pathname;
+      if (urlObject.pathname === '/') {
+        attributes[SEMANTIC_ATTRIBUTE_SENTRY_SOURCE] = 'route';
+      }
+    }
+
+    if (!isURLObjectRelative(urlObject)) {
+      attributes[SEMANTIC_ATTRIBUTE_URL_FULL] = urlObject.href;
+      if (urlObject.port) {
+        attributes['url.port'] = urlObject.port;
+      }
+      if (urlObject.protocol) {
+        attributes['url.scheme'] = urlObject.protocol;
+      }
+      if (urlObject.hostname) {
+        attributes[kind === 'server' ? 'server.address' : 'url.domain'] = urlObject.hostname;
+      }
+    }
+  }
+
+  return [getHttpSpanNameFromUrlObject(urlObject, kind, request, routeName), attributes];
+}
+
 /**
  * Parses string form of URL into an object
  * // borrowed from https://tools.ietf.org/html/rfc3986#appendix-B