feat: add surface label by joaquin-diaz · Pull Request #1162 · embrace-io/embrace-web-sdk

joaquin-diaz · 2026-02-23T20:43:03Z

What problem is this solving?

Allows users to group telemetry by document title until they provide a better default or they use the (future) URL regex to label parsing in the dash

Short description of changes

Add surface label api to Page api
Add surface label to all telemetry
Grab surface label from document.title if is not set

How has this been tested?

Unit tests, e2e tests, local run

github-actions · 2026-02-23T20:52:39Z

Chrome DevTools Protocol Tracing (Script: 122.04ms, Heap: 14.20MB)

	Number of Requests	Size of Requests	Script Duration	Task Duration	Heap Used Size
Requests	+3 requests	+30.33 KB
Page Loaded			+18.54 ms	+16.42 ms	+1.02 MB
Generate 100 fetch requests			+25.25 ms	+113.02 ms	+1.63 MB
Generate 100 XHR requests			+43.36 ms	+121.86 ms	+2.05 MB
Click 100 buttons and generate 100 logs			+23.68 ms	+26.95 ms	+3.16 MB
Throw a 100 exceptions			+2.74 ms	+35.89 ms	+2.85 MB
End Session			+8.46 ms	+12.87 ms	+3.49 MB
Total	+3 requests	+30.33 KB	+122.04 ms	+327.01 ms	+14.20 MB

Lighthouse (Script Eval: 132.94ms)

	Difference	Description
Total Blocking Time	+19 ms	Difference in Total Blocking Time: Sum of all time periods between FCP and Time to Interactive, when task length exceeded 50ms, expressed in milliseconds. Learn more about the Total Blocking Time metric.
Main Thread Time	+114.46 ms	Difference in Main Thread Time: Consider reducing the time spent parsing, compiling and executing JS. You may find delivering smaller JS payloads helps with this. Learn how to minimize main-thread work
Script Evaluation Time	+132.94 ms	Difference in Script Evaluation Time: Consider reducing the time spent parsing, compiling, and executing JS. You may find delivering smaller JS payloads helps with this. Learn how to reduce Javascript execution time.

Platform Tests (vite-7 es2015 gzip: 66.48KB)

vite-6 Platform Tests

	Total Uncompressed Size	Total Gzip Size
vite-6 - es2015	+187.23 KB	+66.52 KB

vite-7 Platform Tests

	Total Uncompressed Size	Total Gzip Size
vite-7 - es2015	+187.23 KB	+66.48 KB

webpack-5 Platform Tests

	Total Uncompressed Size	Total Gzip Size
webpack-5 - es2015	+136.33 KB	+49.29 KB

…l API

jpmunz · 2026-02-24T14:11:10Z

packages/web-sdk/src/processors/PageLogRecordProcessor/PageLogRecordProcessor.ts

      );
    }
+
+    const appSurfaceLabel = this._pageManager.getAppSurfaceLabel();


similar to the check above should we avoid doing this if KEY_APP_SURFACE_LABEL is already set?

jpmunz · 2026-02-24T14:14:09Z

packages/web-sdk/src/processors/PageSpanProcessor/PageSpanProcessor.ts

      span.attributes[KEY_EMB_PAGE_ID] = currentPageId;
    }
+
+    const appSurfaceLabel = this._pageManager.getAppSurfaceLabel();


similar question

jpmunz · 2026-02-24T15:57:57Z

packages/web-sdk/src/managers/EmbracePageManager/EmbracePageManager.ts


  public getCurrentRoute = () => this._currentRoute;

+  public setAppSurfaceLabel = (label: string): void => {


should label instead be included as part of Route and set with setCurrentRoute? Could we end up with inconsistencies with this being set separately?

In that case you'll be forced to pass something as route.path where you might not have it. I think I'd rather keep them independent right now. I can add it as a optional route value so users can set that up when they setCurrentRoute but I'd still keep the label setter. I'm also going to change the API to be:
setRouteLabel and getRouteLabel to be consistent

packages/web-sdk/src/managers/EmbracePageManager/EmbracePageManager.ts

packages/web-sdk/src/managers/EmbracePageManager/types.ts

…n tests

jpmunz · 2026-02-27T16:09:22Z

packages/web-sdk/src/processors/PageSpanProcessor/PageSpanProcessor.ts

      span.attributes[KEY_EMB_PAGE_ID] = currentPageId;
    }
+
+    const appSurfaceLabel = this._pageManager.getPageLabel();


one more on this one and packages/web-sdk/src/processors/PageLogRecordProcessor/PageLogRecordProcessor.ts, feel free to ignore if it's a situation that can't really happen:

should the early exit above just wrap the above block instead? e.g.:

// If the span already has page attributes, do not override them if ( !(span.attributes[KEY_EMB_PAGE_PATH] && span.attributes[KEY_EMB_PAGE_ID]) ) { const currentRoute = this._pageManager.getCurrentRoute(); const currentPageId = this._pageManager.getCurrentPageId(); if (currentRoute && currentPageId) { span.attributes[KEY_EMB_PAGE_PATH] = currentRoute.path; span.attributes[KEY_EMB_PAGE_ID] = currentPageId; } }

just wondering if there would ever be a case where those attributes are set but we'd still want to continue with the surface label logic

No, I missed that. It made sense before but not after my changes, updating

overbalance · 2026-02-27T15:48:56Z

packages/web-sdk/src/api-page/manager/types.ts

  path: string;
  // This is the URL of the route after replacing the URL params. i.e. /products/123
  url: string;
+  // Optional label for the route, used as app.surface.label


I like the examples given above. Maybe you could add something like:
"OLED Televisions - Electronics - BigStore.com"

jpmunz · 2026-02-27T22:13:40Z

packages/web-sdk/src/processors/PageLogRecordProcessor/PageLogRecordProcessor.ts

    if (
-      logRecord.attributes[KEY_EMB_PAGE_PATH] ||
-      logRecord.attributes[KEY_EMB_PAGE_ID]
+      !logRecord.attributes[KEY_EMB_PAGE_PATH] ||


I think the logic changed here inadvertently, before it was skipping the setting if either were set, now it could override if one is set

If either is missing it overrides both

Yeah, if one is missing I override both so make sure they are using the same route. This shouldn't happen in theory, we always set them at the same time but just to be safe. That's why before if either one was present we don't change it.

ah yep that makes sense to me

overbalance · 2026-02-28T16:27:55Z

packages/web-sdk/src/managers/EmbracePageManager/EmbracePageManager.ts

    this._currentRoute = route;
+
+    if (route.label) {
+      this._pageLabel = route.label;


If the route changes but no label is set, it will reuse the previous label. Should this be cleared out instead?

Yep, good catch

overbalance · 2026-02-28T16:29:18Z

packages/web-sdk/src/processors/PageLogRecordProcessor/PageLogRecordProcessor.ts

    if (
-      logRecord.attributes[KEY_EMB_PAGE_PATH] ||
-      logRecord.attributes[KEY_EMB_PAGE_ID]
+      !logRecord.attributes[KEY_EMB_PAGE_PATH] ||


If either is missing it overrides both

…ub.com:embrace-io/embrace-web-sdk into joaquin-diaz/feat/EMBR-10673-add-surface-label

jpmunz · 2026-03-02T14:50:30Z

packages/web-sdk/src/processors/PageLogRecordProcessor/PageLogRecordProcessor.ts

    if (
-      logRecord.attributes[KEY_EMB_PAGE_PATH] ||
-      logRecord.attributes[KEY_EMB_PAGE_ID]
+      !logRecord.attributes[KEY_EMB_PAGE_PATH] ||


ah yep that makes sense to me

joaquin-diaz requested a review from a team as a code owner February 23, 2026 20:43

github-actions bot added feat semver-minor labels Feb 23, 2026

joaquin-diaz changed the title ~~feat: add surface label~~ feat: add surface label Feb 23, 2026

joaquin-diaz added 2 commits February 24, 2026 12:00

feat: add surface label attribute to logs and spans. Add surface labe…

a287361

…l API

chore: update golden files with new surface label attribute

95918bc

joaquin-diaz force-pushed the joaquin-diaz/feat/EMBR-10673-add-surface-label branch from a6709e4 to 95918bc Compare February 24, 2026 15:00

jpmunz reviewed Feb 24, 2026

View reviewed changes

overbalance reviewed Feb 24, 2026

View reviewed changes

packages/web-sdk/src/managers/EmbracePageManager/EmbracePageManager.ts Show resolved Hide resolved

packages/web-sdk/src/managers/EmbracePageManager/types.ts Outdated Show resolved Hide resolved

joaquin-diaz added 2 commits February 24, 2026 15:07

chore: rename surface label to page label, adress pr feedback

7632869

chore(test): revert golden files and disable page label in integratio…

c97d41d

…n tests

jpmunz approved these changes Feb 27, 2026

View reviewed changes

joaquin-diaz and others added 2 commits February 27, 2026 13:35

chore: remove early return when page attributes are present

79e5b2c

Merge branch 'main' into joaquin-diaz/feat/EMBR-10673-add-surface-label

dc11e54

overbalance approved these changes Feb 27, 2026

View reviewed changes

jpmunz requested changes Feb 27, 2026

View reviewed changes

overbalance reviewed Feb 28, 2026

View reviewed changes

joaquin-diaz added 2 commits March 2, 2026 11:32

chore: clear page label if none is set when the route changes

12d9a46

Merge branch 'joaquin-diaz/feat/EMBR-10673-add-surface-label' of gith…

cb2c524

…ub.com:embrace-io/embrace-web-sdk into joaquin-diaz/feat/EMBR-10673-add-surface-label

jpmunz approved these changes Mar 2, 2026

View reviewed changes

Merge branch 'main' into joaquin-diaz/feat/EMBR-10673-add-surface-label

d16ae7e

joaquin-diaz merged commit 0159adc into main Mar 2, 2026
18 checks passed

joaquin-diaz deleted the joaquin-diaz/feat/EMBR-10673-add-surface-label branch March 2, 2026 15:03

github-actions bot mentioned this pull request Mar 2, 2026

release: bump version to 2.12.0 #1172

Merged


		public getCurrentRoute = () => this._currentRoute;

		public setAppSurfaceLabel = (label: string): void => {

Conversation

joaquin-diaz commented Feb 23, 2026

What problem is this solving?

Short description of changes

How has this been tested?

Uh oh!

github-actions bot commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

vite-6 Platform Tests

vite-7 Platform Tests

webpack-5 Platform Tests

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joaquin-diaz Feb 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions bot commented Feb 23, 2026 •

edited

Loading

joaquin-diaz Feb 24, 2026 •

edited

Loading