feat: add http.route and the OTel url.* attribute set (#92)

* feat: add http.route and the OTel url.* attribute set

Mirrors flare.entry_point.handler.identifier into http.route, and splits
url.full into url.scheme, url.path and url.query through one shared core
helper so redaction is applied once and the parts can never disagree.

* task: simplify the comments added in this branch

Author: DriesH

e2e/specs/react.spec.ts

@@ -47,7 +47,11 @@ test.describe('react playground', () => {
         expect(pageload && attr(pageload, 'flare.entry_point.handler.identifier')).toEqual({
             stringValue: '/product/$id',
         });
+        expect(pageload && attr(pageload, 'http.route')).toEqual({ stringValue: '/product/$id' });
         expect(pageload && attr(pageload, 'flare.route.source')).toEqual({ stringValue: 'route' });
+        // http.route is the route template, url.path is the path the user actually hit.
+        expect(pageload && attr(pageload, 'url.path')).toEqual({ stringValue: '/product/p01' });
+        expect(pageload && attr(pageload, 'url.scheme')).toEqual({ stringValue: 'http' });
     });
 
     test('navigation root carries the parameterized route (not the concrete path)', async ({ page, fakeFlare }) => {

packages/core/src/Flare.ts

@@ -489,6 +489,8 @@ export class Flare {
         const entryPointOverrides: Attributes = {};
         if (entryPoint?.identifier !== undefined) {
             entryPointOverrides['flare.entry_point.handler.identifier'] = entryPoint.identifier;
+            // The OTel name for the same value. Set both here so they cannot drift apart.
+            entryPointOverrides['http.route'] = entryPoint.identifier;
         }
         if (entryPoint?.type !== undefined) {
             entryPointOverrides['flare.entry_point.handler.type'] = entryPoint.type;

packages/core/src/index.ts

@@ -48,6 +48,7 @@ export {
     safeClone,
     safeDecode,
     toCustomContext,
+    urlAttributes,
 } from './util';
 export type { RejectionReporter, SafeCloneOptions, SdkTaggable } from './util';
 

packages/core/src/util/index.ts

@@ -12,4 +12,5 @@ export * from './rejection';
 export * from './safeClone';
 export * from './statelessRegExp';
 export * from './toCustomContext';
+export * from './urlAttributes';
 // utf8Bytes is deliberately not re-exported: an internal envelope-sizing helper, not a public seam.

packages/core/src/util/urlAttributes.ts

@@ -0,0 +1,33 @@
+import type { Attributes } from '../types';
+import { DEFAULT_URL_DENYLIST, redactUrlQuery } from './redactUrl';
+
+/**
+ * Builds the OTel `url.*` attributes for one absolute URL.
+ *
+ * Redacts the URL first and splits it after, so `url.full` and `url.query` always show the same
+ * redacted values.
+ *
+ * Leaves out `url.query` when there is no query string. Returns only `url.full` when the URL cannot
+ * be parsed, for example a relative one.
+ */
+export function urlAttributes(url: string, denylist: RegExp = DEFAULT_URL_DENYLIST): Attributes {
+    const full = redactUrlQuery(url, denylist);
+    const attributes: Attributes = { 'url.full': full };
+
+    let parsed: URL;
+    try {
+        parsed = new URL(full);
+    } catch {
+        return attributes;
+    }
+
+    // `protocol` ends with a colon, url.scheme does not.
+    attributes['url.scheme'] = parsed.protocol.slice(0, -1);
+    attributes['url.path'] = parsed.pathname;
+
+    if (parsed.search) {
+        attributes['url.query'] = parsed.search.slice(1);
+    }
+
+    return attributes;
+}

packages/core/tests/setEntryPoint.test.ts

@@ -15,6 +15,9 @@ function browserCollector(_config: Readonly<Config>): Attributes {
     const attrs: Attributes = { 'flare.entry_point.type': 'web' };
     if (typeof window !== 'undefined' && window?.location?.pathname) {
         attrs['flare.entry_point.handler.identifier'] = window.location.pathname;
+        // The real browser collector also sets http.route. Copy that here so the tests below can
+        // check both keys move together.
+        attrs['http.route'] = window.location.pathname;
         attrs['flare.entry_point.handler.type'] = 'browser';
     }
     return attrs;
@@ -40,6 +43,7 @@ test('default entry point handler is pathname + browser', async () => {
 
     const a = fakeApi.lastReport!.attributes;
     expect(a['flare.entry_point.handler.identifier']).toBe('/users/42');
+    expect(a['http.route']).toBe('/users/42');
     expect(a['flare.entry_point.handler.type']).toBe('browser');
     expect(a['flare.entry_point.handler.name']).toBeUndefined();
 });
@@ -51,6 +55,8 @@ test('setEntryPoint overrides identifier, type, and name', async () => {
 
     const a = fakeApi.lastReport!.attributes;
     expect(a['flare.entry_point.handler.identifier']).toBe('/users/:id');
+    // http.route copies the identifier, so the override has to win here too.
+    expect(a['http.route']).toBe('/users/:id');
     expect(a['flare.entry_point.handler.type']).toBe('vue_route');
     expect(a['flare.entry_point.handler.name']).toBe('UserShow');
 });
@@ -74,6 +80,7 @@ test('setEntryPoint with only name falls back to collector defaults for identifi
     const a = fakeApi.lastReport!.attributes;
     // identifier falls back to default pathname from browser collector
     expect(a['flare.entry_point.handler.identifier']).toBe('/users/42');
+    expect(a['http.route']).toBe('/users/42');
     // type falls back to default 'browser' from browser collector
     expect(a['flare.entry_point.handler.type']).toBe('browser');
 });

packages/core/tests/urlAttributes.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+
+import { urlAttributes } from '../src/util/urlAttributes';
+
+describe('urlAttributes', () => {
+    it('splits an absolute url into the OTel url.* set', () => {
+        expect(urlAttributes('https://shop.test/product/p01?size=l&color=red')).toEqual({
+            'url.full': 'https://shop.test/product/p01?size=l&color=red',
+            'url.scheme': 'https',
+            'url.path': '/product/p01',
+            'url.query': 'size=l&color=red',
+        });
+    });
+
+    it('leaves url.query out when there is no query string', () => {
+        const attrs = urlAttributes('https://shop.test/cart');
+
+        expect(attrs).toEqual({
+            'url.full': 'https://shop.test/cart',
+            'url.scheme': 'https',
+            'url.path': '/cart',
+        });
+        expect('url.query' in attrs).toBe(false);
+    });
+
+    it('leaves url.query out for a bare question mark', () => {
+        expect('url.query' in urlAttributes('https://shop.test/cart?')).toBe(false);
+    });
+
+    it('redacts denylisted query values in both url.full and url.query', () => {
+        const attrs = urlAttributes('https://shop.test/reset?token=abc123&name=dries');
+
+        expect(attrs['url.full']).toBe('https://shop.test/reset?token=[redacted]&name=dries');
+        expect(attrs['url.query']).toBe('token=[redacted]&name=dries');
+    });
+
+    it('honours a custom denylist', () => {
+        const attrs = urlAttributes('https://shop.test/x?order_id=9&token=abc', /order_id/i);
+
+        expect(attrs['url.query']).toBe('order_id=[redacted]&token=abc');
+    });
+
+    it('strips userinfo from url.full', () => {
+        const attrs = urlAttributes('https://dries:hunter2@shop.test/account');
+
+        expect(attrs['url.full']).toBe('https://shop.test/account');
+        expect(attrs['url.path']).toBe('/account');
+    });
+
+    it('leaves path segments alone even when they look denylisted', () => {
+        expect(urlAttributes('https://shop.test/token/abc123')['url.path']).toBe('/token/abc123');
+    });
+
+    it('keeps the fragment on url.full but out of path and query', () => {
+        const attrs = urlAttributes('https://shop.test/faq?q=1#shipping');
+
+        expect(attrs['url.full']).toBe('https://shop.test/faq?q=1#shipping');
+        expect(attrs['url.path']).toBe('/faq');
+        expect(attrs['url.query']).toBe('q=1');
+    });
+
+    it('returns url.full alone for a url that will not parse', () => {
+        expect(urlAttributes('/relative/path?token=abc')).toEqual({
+            'url.full': '/relative/path?token=[redacted]',
+        });
+    });
+
+    it('reports non-http schemes', () => {
+        const attrs = urlAttributes('file:///Users/dries/app/index.html');
+
+        expect(attrs['url.scheme']).toBe('file');
+        expect(attrs['url.path']).toBe('/Users/dries/app/index.html');
+    });
+});

packages/js/src/browser/context/collectBrowser.ts

@@ -3,7 +3,6 @@ import { redactUrlQuery } from '@flareapp/core';
 
 import cookie from './cookie';
 import request from './request';
-import requestData from './requestData';
 
 export function browserEntryPoint(config: Readonly<Config>, urlOverride?: URL): Attributes {
     if (typeof window === 'undefined') {
@@ -22,6 +21,7 @@ export function browserEntryPoint(config: Readonly<Config>, urlOverride?: URL):
         const pathname = urlOverride ? urlOverride.pathname : window?.location?.pathname;
         if (pathname) {
             attrs['flare.entry_point.handler.identifier'] = pathname;
+            attrs['http.route'] = pathname;
             attrs['flare.entry_point.handler.type'] = 'browser';
         }
     }
@@ -33,7 +33,7 @@ export const collectBrowser: ContextCollector = (config: Readonly<Config>): Attr
     const attrs: Attributes = { ...browserEntryPoint(config) };
 
     // No window (SSR/node): browserEntryPoint already returned the entry point type on its own.
-    // request()/requestData()/cookie() below touch window unguarded, so stop here.
+    // request()/cookie() below touch window unguarded, so stop here.
     if (typeof window === 'undefined') {
         return attrs;
     }
@@ -46,7 +46,6 @@ export const collectBrowser: ContextCollector = (config: Readonly<Config>): Attr
     }
 
     Object.assign(attrs, request(config.urlDenylist));
-    Object.assign(attrs, requestData(config.urlDenylist));
     Object.assign(attrs, cookie(config.urlDenylist));
 
     return attrs;

packages/js/src/browser/context/collectBrowserSpanContext.ts

@@ -1,5 +1,5 @@
 import type { Attributes, Config } from '@flareapp/core';
-import { redactUrlQuery } from '@flareapp/core';
+import { urlAttributes } from '@flareapp/core';
 
 import { absoluteUrl } from '../../tracing/absoluteHref';
 import { browserEntryPoint } from './collectBrowser';
@@ -23,11 +23,14 @@ export function collectBrowserSpanContext(config: Readonly<Config>, hrefOverride
 }
 
 /**
- * Re-stamps a root's url after a redirect, or when a newer navigation replaces this one: the root opened
- * with the first destination, so it would otherwise report a page the user never landed on.
+ * Updates a root's url after a redirect, or when a newer navigation replaces this one. The root opened
+ * with the first destination, so without this it reports a page the user never reached.
  *
- * Leaves `flare.entry_point.handler.identifier` alone. The route template owns that, and deriving it from
- * the href would turn `/product/[id]` back into `/product/p01`.
+ * Does not touch `flare.entry_point.handler.identifier` or `http.route`. Those hold the route template,
+ * and reading them back from the href would turn `/product/[id]` into `/product/p01`.
+ *
+ * Always sets `url.query`, even to an empty string. You can overwrite a span attribute but not remove
+ * it, so going from `/a?x=1` to `/b` would otherwise keep the old query.
  */
 export function browserSpanUrlAttributes(config: Readonly<Config>, href: string): Attributes {
     if (typeof window === 'undefined') {
@@ -37,6 +40,6 @@ export function browserSpanUrlAttributes(config: Readonly<Config>, href: string)
     if (!resolved) {
         return {};
     }
-    const redacted = redactUrlQuery(resolved.href, config.urlDenylist);
-    return { 'url.full': redacted, 'flare.entry_point.value': redacted };
+    const attributes = urlAttributes(resolved.href, config.urlDenylist);
+    return { 'url.query': '', ...attributes, 'flare.entry_point.value': attributes['url.full'] };
 }

packages/js/src/browser/context/request.ts

@@ -1,14 +1,14 @@
 import type { Attributes } from '@flareapp/core';
-import { redactUrlQuery } from '@flareapp/core';
+import { redactUrlQuery, urlAttributes } from '@flareapp/core';
 
 /**
- * @param hrefOverride when set, `url.full` is derived from it instead of the live
+ * @param hrefOverride when set, the `url.*` attributes come from it instead of the live
  * `window.location.href` (a framework navigation root whose router knows the destination
  * before the URL commits). The override is pre-validated by the caller.
  */
 export default function request(urlDenylist: RegExp, hrefOverride?: string): Attributes {
     return {
-        'url.full': redactUrlQuery(hrefOverride ?? window.location.href, urlDenylist),
+        ...urlAttributes(hrefOverride ?? window.location.href, urlDenylist),
         'user_agent.original': window.navigator.userAgent,
         'http.request.referrer': redactUrlQuery(window.document.referrer, urlDenylist),
         'document.ready_state': window.document.readyState,