Repository navigation
feat(o11y): capture UTM query parameters and landing referrer as attributes - #877
Merged
Merged
Conversation
Add a `captureQueryParams` option to the Observe plugin. At init the SDK reads `location.search` once and sets each listed parameter that is present as a global attribute (through `setAttributes`, so reserved keys are ignored, explicit `setAttributes` values win and `removeAttributes` removes them). The attributes land on every span, log, error and metric for the rest of the page load, including after SPA navigation and with `manualStart`. Defaults to the five UTM parameters; `false` or `[]` turns it off, a custom list replaces the default and a trailing `*` matches a prefix. Values are kept in memory only; nothing is written to storage or cookies. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Generated-by: termag
…fqqr4hswpm7w0jzydp0f Generated-by: termag
- On SPA navigation to a URL carrying any listed query param, replace the captured values with that URL's and remove previously captured keys it lacks. Navigations without listed params keep the values. Keys the app set with setAttributes are never replaced or removed. The page view of the new landing carries the new values; started spans keep theirs. - Add `captureReferrer` (default true): a cross-origin document.referrer is set as `landing.referrer`, with query string, fragment and credentials stripped. Same-origin or empty referrers set nothing. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Generated-by: termag
Contributor
Author
|
bugbot run |
Each PathListener call wrapped pushState/replaceState again and every wrap dispatched its own locationchange, so the captureQueryParams listener added an extra navigation event for every subscriber (session replay records an extra Navigate). PathListener now installs a single refcounted wrap shared on window, and ObserveSDK keeps the landing listener's unsubscribe, removing it on stop() and reinstalling it on start(). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Generated-by: termag
Contributor
Author
|
bugbot run |
abelonogov-ld
approved these changes
Nov 4, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Generated-by: termag
Contributor
Author
|
bugbot run |
There was a problem hiding this comment.
✅ Bugbot reviewed your changes and found no new issues!
Comment @cursor review or bugbot run to trigger another review on this PR
Reviewed by Cursor Bugbot for commit 40791b8. Configure here.
vadim-korolik
enabled auto-merge (squash)
November 4, 2026 02:18
Merged
vadim-korolik
pushed a commit
that referenced
this pull request
Nov 6, 2026
🤖 I have created a release *beep* *boop* --- <details><summary>launchdarkly-observability-python: 1.4.0</summary> ## [1.4.0](launchdarkly-observability-python-1.3.4...launchdarkly-observability-python-1.4.0) (2026-11-06) ### Features * **python:** add set_attributes and custom span/log processors ([#859](#859)) ([3f04a85](3f04a85)) </details> <details><summary>launchdarkly-observability-android: 0.70.0</summary> ## [0.70.0](launchdarkly-observability-android-0.69.1...launchdarkly-observability-android-0.70.0) (2026-11-06) ### Features * **android:** add setAttributes and removeAttributes ([#860](#860)) ([a1c02b2](a1c02b2)) </details> <details><summary>launchdarkly-java-server-sdk-observability: 0.2.0</summary> ## [0.2.0](launchdarkly-java-server-sdk-observability-0.1.0...launchdarkly-java-server-sdk-observability-0.2.0) (2026-11-06) ### Features * **java:** add setAttributes and custom span/log processors ([#861](#861)) ([d0ee65e](d0ee65e)) </details> <details><summary>o11y: 1.6.0</summary> ## [1.6.0](o11y-1.5.0...o11y-1.6.0) (2026-11-06) ### Features * **o11y:** capture UTM query parameters and landing referrer as attributes ([#877](#877)) ([f32637b](f32637b)) ### Bug Fixes * **o11y:** report @launchdarkly/o11y as telemetry.distro.name ([#879](#879)) ([7f339e1](7f339e1)) </details> <details><summary>observability: 1.5.0</summary> ## [1.5.0](observability-1.4.0...observability-1.5.0) (2026-11-06) ### Features * **o11y:** capture UTM query parameters and landing referrer as attributes ([#877](#877)) ([f32637b](f32637b)) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/o11y bumped to 1.6.0 </details> <details><summary>observability-next: 0.3.6</summary> ## [0.3.6](observability-next-0.3.5...observability-next-0.3.6) (2026-11-06) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/observability bumped to 1.5.0 * @launchdarkly/session-replay bumped to 1.2.6 </details> <details><summary>session-replay: 1.2.6</summary> ## [1.2.6](session-replay-1.2.5...session-replay-1.2.6) (2026-11-06) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/o11y bumped to 1.6.0 </details> <details><summary>highlight.run: 10.8.6</summary> ## [10.8.6](highlight.run-10.8.5...highlight.run-10.8.6) (2026-11-06) ### Dependencies * The following workspace dependencies were updated * dependencies * @launchdarkly/o11y bumped to 1.6.0 </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Overview** > **Release automation** updates `.release-please-manifest.json` and every consumer manifest to cut `@launchdarkly/o11y` **1.6.0**, `@launchdarkly/observability` **1.5.0**, `@launchdarkly/session-replay` **1.2.6**, `highlight.run` **10.8.6**, `@launchdarkly/observability-next` **0.3.6**, Android **0.70.0**, Java **0.2.0**, and Python **1.4.0** while regenerating their CHANGELOG notes. > > **Packaging metadata** bumps Gradle `version` tokens (`sdk/@launchdarkly/observability-android/gradle.properties`, `sdk/@launchdarkly/observability-java/gradle.properties`) and `INSTRUMENTATION_VERSION` so published telemetry reports the new Java plugin revision, refreshes `pyproject.toml`/`PROVENANCE.md` for the Python wheel, and keeps `@launchdarkly/observability-java`’s constants aligned. > > **Doc churn** extends each touched SDK changelog with the corresponding feature or dependency bullets (e.g., marketing UTM capture for browser o11y, attribute helpers on Android/Java/Python, workspace dependency bumps for Next/session-replay/highlight packages). > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 18ddf54. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Demo
A vitest/jsdom harness runs the real
ObserveSDKwith the real span processor, document-load/location-change/fetch instrumentations and a real OTel metrics pipeline, all exporting to memory. The page loads at/?utm_campaign=spring&utm_source=email&other=xwithdocument.referrerset tohttps://www.google.com/search?q=me%40mail.com&token=abc#top. It then does:/products,/checkout)/promo?utm_campaign=fallThe demo has three runs: default config with a cross-origin referrer, default config with a same-origin referrer, and both options off.
Default config, cross-origin referrer (excerpt):
otheris never captured, and the referrer's query string and fragment are stripped. On the/promolanding,utm_sourceis removed andutm_campaignbecomesfall(last touch). A same-origin referrer sets nolanding.referrer. With both optionsfalse, none of these attributes appear.What
Two options on the Observe plugin (
ObserveOptions, exposed through@launchdarkly/observability).captureQueryParams?: string[] | falseOn by default with
['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content'].falseor[]turns it off, and a custom list replaces the default. A trailing*matches a prefix ('utm_*').location.searchand sets each listed parameter that is present as a global attribute named after the parameter. It uses the feat(o11y): add setAttributes/removeAttributes and stamp context keys on every span #855setAttributesstore, so the reserved-key rules are the same. Empty values are skipped, and for a repeated parameter the first value wins.pushState,replaceStateorpopstate) lands on a URL with any listed parameter, the captured values are replaced by that URL's values, and previously captured keys missing from it are removed. A navigation without listed parameters keeps the current values. The page_view span of the new landing already carries the new values. Spans that were already started keep their values, because attributes are stamped at span start.setAttributes(before init or after) is never touched.removeAttributesremoves a captured value, and a later landing with that parameter captures it again.manualStart: the values are present while tracing is set up (the document load span) and on telemetry buffered beforestart(). Navigation is tracked from SDK construction.PathListenerwhen constructed, before the page_view instrumentation's, so last-touch works even when page views are disabled.captureReferrer?: booleanDefault
true.document.referreris set aslanding.referrer. Only the origin and path are kept: the query string, fragment and credentials are stripped.setAttributescan override it.landing.is not a reserved namespace, so the requested name is used as-is.Unchanged
@launchdarkly/observability): documents both options, last touch, and a recipe for keeping UTMs across a full page load or an auth redirect (sessionStorage +LDObserve.setAttributeson loads whose URL has none).@launchdarkly/session-replay(itsRecordOptionsdoesn't apply global attributes) or onH.init(which doesn't constructObserveSDK).Overlap
setAttributes, superseded by feat(o11y): add setAttributes/removeAttributes and stamp context keys on every span #855): this PR builds on feat(o11y): add setAttributes/removeAttributes and stamp context keys on every span #855, which is onmain. feat(o11y): add setAttributes and removeAttributes #865 would conflict withsdk/observe.tsif it were revived.sdk/highlight-run/paths. Related: the upstreamdocumentLoadspan's rawhttp.urland the page_viewurl.fullstill carry the full query string (other=xin the demo). That is existing behaviour and unchanged here; it's what fix: sanitize page URLs recorded into telemetry #729 is about.Tests
src/sdk/observe.captureQueryParams.test.tshas 35 tests.Capture:
falseand[]disabling captureutm_*prefix patternremoveAttributessetAttributeswinningmanualStartLast touch:
replaceStatesetAttributeskeys (before or after init) never replaced or removedremoveAttributesReferrer:
falsecaptureQueryParams, not updated on navigationsetAttributesoverrideMutation checks: 10 tests fail without the init capture, 6 without last touch, and 4 without the referrer stripping.
yarn workspace @launchdarkly/o11y test: 46 files, 661 tests passedtsc --noEmit(typegen:check): cleanturbo lint(o11y, observability, session-replay): passedyarn enforce-size: 173.4 kB brotli (limit 256 kB)prettier --checkon the changed files: cleanAsked by
vkorolikthroughtermag ask; follow up withtermag ask … --thread cmw1cfqqr4hswpm7w0jzydp0f.🤖 Generated with Claude Code
Opened from termag
Note
Overview
Adds automatic campaign and landing metadata to observability global attributes via two new
ObserveOptions:captureQueryParams(on by default with standard UTM keys, optional prefix patterns likeutm_*, disable withfalse/[]) andcaptureReferrer(defaulttrue, sets sanitized cross-originlanding.referrer).Captured query values flow through the existing
setAttributesstore onto spans, logs, errors, and metrics for the page load, persisting after SPA navigations that drop the query string. Last-touch updates captured keys when a navigation lands on a URL with any listed parameter (replacing/removing prior captured keys); navigations without listed params leave values unchanged.setAttributes/ pre-init buffered attributes win over capture;removeAttributescan drop captured keys for re-capture later.PathListeneris refactored to install a single sharedhistorywrap onwindow(reference-counted subscribers, safe teardown when another wrap sits on top) so multiple SDK instances or bundles emit onelocationchangeper navigation.ObserveSDKwires landing capture at construct time, re-attaches the navigation listener onstart(), and detaches onstop().New helpers in
queryParams.ts, expanded TSDoc, README sections (including a sessionStorage recipe for redirects), and broad vitest coverage for parsing, referrer stripping, telemetry stamping, and multi-instance behavior.Reviewed by Cursor Bugbot for commit 40791b8. Bugbot is set up for automated code reviews on this repo. Configure here.