Finalize browser RUM lifecycle alpha

Expose browser instrumentation factories and lazy auto-instrumentation through the Logfire browser package so applications can opt into richer RUM setup without importing OpenTelemetry web auto-instrumentations directly.

Keep Web Vitals spans provider-owned, add explicit Logfire page URL attributes, document replay correlation tradeoffs, and bump @pydantic/logfire-browser to 0.17.0-alpha.2 so the alpha release workflow publishes these SDK changes.

Author: petyosi

.changeset/pre.json

@@ -14,9 +14,11 @@
     "@pydantic/logfire-browser": "0.16.4",
     "@pydantic/logfire-cf-workers": "0.12.4",
     "@pydantic/logfire-node": "0.18.2",
-    "@pydantic/logfire-session-replay": "0.0.0"
+    "@pydantic/logfire-session-replay": "0.0.0",
+    "@pydantic/otel-cf-workers": "1.0.0"
   },
   "changesets": [
+    "browser-rum-lifecycle",
     "browser-rum-session",
     "browser-rum-web-vitals-metrics",
     "browser-rum-web-vitals",

docs/packages/browser.md

@@ -12,13 +12,12 @@ Browser telemetry must be sent through your own backend proxy. Do not put a Logf
 ## Install
 
 ```bash
-npm install @pydantic/logfire-browser @opentelemetry/auto-instrumentations-web
+npm install @pydantic/logfire-browser
 ```
 
 ## Configure
 
 ```ts
-import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web'
 import * as logfire from '@pydantic/logfire-browser'
 
 const url = new URL('/logfire-proxy/v1/traces', window.location.origin)
@@ -27,19 +26,21 @@ logfire.configure({
   traceUrl: url.toString(),
   serviceName: 'web-app',
   serviceVersion: '1.0.0',
-  instrumentations: [getWebAutoInstrumentations()],
+  autoInstrumentations: true,
 })
 ```
 
 `traceUrl` should point to a server-side endpoint that accepts OTLP trace requests from your browser instrumentation, forwards them to Logfire, and adds the `Authorization` header on the server.
 
+`autoInstrumentations` is opt-in and lazily loads OpenTelemetry browser auto-instrumentations after the Logfire browser provider is ready. For advanced integrations, `instrumentations` also accepts factories, so custom instrumentation construction can be deferred until `configure()` has registered the provider.
+
 Use `diagLogLevel` while troubleshooting local browser instrumentation:
 
 ```ts
 logfire.configure({
   traceUrl: '/logfire-proxy/v1/traces',
   serviceName: 'web-app',
-  instrumentations: [getWebAutoInstrumentations()],
+  autoInstrumentations: true,
   diagLogLevel: logfire.DiagLogLevel.ALL,
 })
 ```
@@ -67,9 +68,13 @@ of total duration by default. Each span gets `session.id` and
 `browser.session.id`; `session.id` is the OpenTelemetry semantic attribute and
 `browser.session.id` is emitted for Logfire Platform compatibility.
 
-Session-enabled spans also get `url.full` and `url.path` by default. If your
-URLs may contain sensitive query strings or fragments, sanitize or suppress
-these attributes:
+Session-enabled spans also get `logfire.page.url.full` and
+`logfire.page.url.path` by default for current page context. During the alpha,
+the SDK also emits compatibility `url.full` and `url.path` values with the same
+sanitized page URL. Prefer `logfire.page.url.*` for page grouping because
+OpenTelemetry fetch/resource spans may use `url.*` for the network target URL.
+If your URLs may contain sensitive query strings or fragments, sanitize or
+suppress these attributes:
 
 ```ts
 logfire.configure({
@@ -177,13 +182,14 @@ Metric data point attributes are intentionally low-cardinality:
 `web_vital.name` and `web_vital.rating` by default. They do not include
 `session.id`, `browser.session.id`, `url.full`, `url.path`, Web Vital
 ids/deltas, DOM selectors, attribution fields, or raw PerformanceEntry data. Use
-spans for raw-sample drilldown, session/replay correlation, exact URL context,
-and attribution selectors.
+spans for raw-sample drilldown, session/replay correlation, exact page context,
+and attribution selectors. When metrics are configured, Logfire Platform should
+treat these histograms as the aggregate Web Vitals surface.
 
 For modern single-page apps, these are standard document-level Web Vitals, not
-route-level soft-navigation metrics. Span URL attributes describe the browser
-URL when the callback fires; route-specific Core Web Vitals need separate route
-or soft-navigation instrumentation. To add a route dimension to metrics, pass a
+route-level soft-navigation metrics. Span page URL attributes describe the
+browser URL when the callback fires; route-specific Core Web Vitals need
+separate route or soft-navigation instrumentation. To add a route dimension to metrics, pass a
 low-cardinality template such as `/products/:id` through
 `rum.webVitals.metrics.attributes`.
 
@@ -218,10 +224,13 @@ logfire.configure({
 ```
 
 `sessionReplay` implies default RUM session behavior. Replay chunks and browser
-spans share `session.id` / `browser.session.id`, and spans started while replay
-is active include `logfire.session_replay.active` and
-`logfire.session_replay.mode`. The browser SDK does not populate replay
-`traceIds` from active-span polling.
+spans share `session.id` / `browser.session.id`. Spans started after replay has
+loaded and sampled into `full` or `buffer` mode include
+`logfire.session_replay.active` and `logfire.session_replay.mode`. Those active
+attributes are truthful best-effort annotations, not the primary correlation
+key; early spans should be correlated to replay by browser session id and replay
+time bounds. The browser SDK does not populate replay `traceIds` from
+active-span polling.
 
 Direct token usage is available as an advanced escape hatch, but it exposes the
 write token to browser code and should not be the default browser deployment

examples/browser-rum-replay/package.json

@@ -10,7 +10,6 @@
     "preview": "vp preview --host 127.0.0.1 --port 4174"
   },
   "dependencies": {
-    "@opentelemetry/auto-instrumentations-web": "catalog:",
     "cors": "^2.8.5",
     "express": "^4.21.2"
   },

examples/browser-rum-replay/src/main.ts

@@ -1,4 +1,3 @@
-import { getWebAutoInstrumentations } from '@opentelemetry/auto-instrumentations-web'
 import * as logfire from '@pydantic/logfire-browser'
 
 interface CatalogProduct {
@@ -76,20 +75,18 @@ logfire.configure({
       },
     },
   },
-  instrumentations: [
-    getWebAutoInstrumentations({
-      '@opentelemetry/instrumentation-document-load': { enabled: true },
-      '@opentelemetry/instrumentation-fetch': {
-        enabled: true,
-        clearTimingResources: true,
-      },
-      '@opentelemetry/instrumentation-user-interaction': {
-        enabled: true,
-        eventNames: ['click', 'change'],
-      },
-      '@opentelemetry/instrumentation-xml-http-request': { enabled: true },
-    }),
-  ],
+  autoInstrumentations: {
+    '@opentelemetry/instrumentation-document-load': { enabled: true },
+    '@opentelemetry/instrumentation-fetch': {
+      enabled: true,
+      clearTimingResources: true,
+    },
+    '@opentelemetry/instrumentation-user-interaction': {
+      enabled: true,
+      eventNames: ['click', 'change'],
+    },
+    '@opentelemetry/instrumentation-xml-http-request': { enabled: true },
+  },
   diagLogLevel: import.meta.env.VITE_LOGFIRE_DIAG === 'true' ? logfire.DiagLogLevel.ALL : logfire.DiagLogLevel.ERROR,
   batchSpanProcessorConfig: {
     maxExportBatchSize: 8,

examples/nextjs-client-side-instrumentation/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @pydantic/nextjs-client-side-instrumentation
 
+## 0.1.16-alpha.2
+
+### Patch Changes
+
+- Updated dependencies
+  - @pydantic/logfire-browser@0.17.0-alpha.2
+
 ## 0.1.16-alpha.1
 
 ### Patch Changes

examples/nextjs-client-side-instrumentation/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pydantic/nextjs-client-side-instrumentation",
-  "version": "0.1.16-alpha.1",
+  "version": "0.1.16-alpha.2",
   "private": true,
   "scripts": {
     "dev": "next dev --turbopack --port 8080",

packages/logfire-browser/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @pydantic/logfire-browser
 
+## 0.17.0-alpha.2
+
+### Minor Changes
+
+- Stabilize browser RUM lifecycle setup with deferred instrumentation factories, opt-in lazy `autoInstrumentations`, provider-owned Web Vitals spans, explicit page URL attributes, and clarified session replay correlation semantics.
+
 ## 0.17.0-alpha.1
 
 ### Patch Changes

packages/logfire-browser/README.md

@@ -70,9 +70,13 @@ or 4 hours of total duration by default. Spans get `session.id` and
 `browser.session.id`; `session.id` is the OpenTelemetry semantic attribute and
 `browser.session.id` is emitted for Logfire Platform compatibility.
 
-By default, session-enabled spans also get `url.full` and `url.path` from the
-current page URL. If your app has sensitive query strings or fragments, provide
-a sanitizer or suppress URL attributes:
+By default, session-enabled spans also get `logfire.page.url.full` and
+`logfire.page.url.path` from the current page URL. During the alpha, the SDK
+also emits compatibility `url.full` and `url.path` values with the same
+sanitized page URL. Prefer `logfire.page.url.*` for page grouping because
+OpenTelemetry fetch/resource spans may use `url.*` for the network target URL.
+If your app has sensitive query strings or fragments, provide a sanitizer or
+suppress URL attributes:
 
 ```js
 logfire.configure({
@@ -183,13 +187,14 @@ Metric data point attributes are intentionally low-cardinality:
 `web_vital.name` and `web_vital.rating` by default. They do not include
 `session.id`, `browser.session.id`, `url.full`, `url.path`, Web Vital
 ids/deltas, DOM selectors, attribution fields, or raw PerformanceEntry data. Use
-spans for raw-sample drilldown, session/replay correlation, exact URL context,
-and attribution selectors.
+spans for raw-sample drilldown, session/replay correlation, exact page context,
+and attribution selectors. When metrics are configured, Logfire Platform should
+treat these histograms as the aggregate Web Vitals surface.
 
 For modern single-page apps, these are standard document-level Web Vitals, not
-route-level soft-navigation metrics. Span URL attributes describe the browser
-URL when the callback fires; route-specific Core Web Vitals need separate route
-or soft-navigation instrumentation. To add a route dimension to metrics, pass a
+route-level soft-navigation metrics. Span page URL attributes describe the
+browser URL when the callback fires; route-specific Core Web Vitals need
+separate route or soft-navigation instrumentation. To add a route dimension to metrics, pass a
 low-cardinality template such as `/products/:id` through
 `rum.webVitals.metrics.attributes`.
 
@@ -225,10 +230,13 @@ logfire.configure({
 ```
 
 `sessionReplay` implies default browser session attributes. Replay chunks and
-browser spans share `session.id` / `browser.session.id`, and spans started
-while replay is active get `logfire.session_replay.active` and
-`logfire.session_replay.mode`. The browser integration intentionally does not
-poll active trace context into replay chunks.
+browser spans share `session.id` / `browser.session.id`. Spans started after
+replay has loaded and sampled into `full` or `buffer` mode get
+`logfire.session_replay.active` and `logfire.session_replay.mode`. Those active
+attributes are truthful best-effort annotations, not the primary correlation
+key; early spans should be correlated to replay by browser session id and replay
+time bounds. The browser integration intentionally does not poll active trace
+context into replay chunks.
 
 Use a backend proxy for browser replay uploads. The proxy should authenticate
 the browser request with your application session or CSRF mechanism and add the

packages/logfire-browser/package.json

@@ -25,7 +25,7 @@
     "stats",
     "monitoring"
   ],
-  "version": "0.17.0-alpha.1",
+  "version": "0.17.0-alpha.2",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -54,6 +54,7 @@
   },
   "dependencies": {
     "@opentelemetry/api": "catalog:",
+    "@opentelemetry/auto-instrumentations-web": "catalog:",
     "@opentelemetry/core": "catalog:",
     "@opentelemetry/exporter-metrics-otlp-http": "catalog:",
     "@opentelemetry/exporter-trace-otlp-http": "catalog:",

packages/logfire-browser/src/BrowserSessionSpanProcessor.test.ts

@@ -104,6 +104,8 @@ describe('BrowserSessionSpanProcessor', () => {
 
     expect(span.attributes).toEqual({
       'browser.session.id': 'session-1',
+      'logfire.page.url.full': 'https://example.com/dashboard?tab=activity#recent',
+      'logfire.page.url.path': '/dashboard',
       'session.id': 'session-1',
       'url.full': 'https://example.com/dashboard?tab=activity#recent',
       'url.path': '/dashboard',
@@ -138,12 +140,28 @@ describe('BrowserSessionSpanProcessor', () => {
 
     expect(span.attributes).toEqual({
       'browser.session.id': 'session-1',
+      'logfire.page.url.full': 'https://example.com/dashboard',
+      'logfire.page.url.path': '/sanitized',
       'session.id': 'session-1',
       'url.full': 'https://example.com/dashboard',
       'url.path': '/sanitized',
     })
   })
 
+  it('keeps explicit page URL attributes alongside compatibility URL attributes', () => {
+    setLocation({ href: 'https://example.com/products/123?token=secret' })
+    const span = createSpan()
+
+    startSpan(createProcessor(), span)
+
+    expect(span.attributes).toMatchObject({
+      'logfire.page.url.full': 'https://example.com/products/123?token=secret',
+      'logfire.page.url.path': '/products/123',
+      'url.full': 'https://example.com/products/123?token=secret',
+      'url.path': '/products/123',
+    })
+  })
+
   it('does not throw when location is unavailable', () => {
     setLocation(undefined)
     const span = createSpan()