Skip to content

feat(o11y): capture UTM query parameters and landing referrer as attributes - #877

Merged
vadim-korolik merged 5 commits into
mainfrom
termag-vkorolik/cmw1cfqqr4hswpm7w0jzydp0f
Nov 4, 2026
Merged

vadim-korolik merged 5 commits into
mainfrom
termag-vkorolik/cmw1cfqqr4hswpm7w0jzydp0f

Conversation

@vadim-korolik

@vadim-korolik vadim-korolik commented Nov 4, 2026 •

Copy link
Copy Markdown
Contributor

Demo

A vitest/jsdom harness runs the real ObserveSDK with 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=x with document.referrer set to https://www.google.com/search?q=me%40mail.com&token=abc#top. It then does:

  1. two SPA navigations (/products, /checkout)
  2. a fetch, a log, an error and a metric
  3. an SPA landing on /promo?utm_campaign=fall
  4. another log and metric

The 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):

documentLoad        {"landing.referrer":"https://www.google.com/search","utm_campaign":"spring","utm_source":"email", ...}
page_view           {"url.full":".../checkout","landing.referrer":"https://www.google.com/search","utm_campaign":"spring","utm_source":"email"}
HTTP GET            {"http.url":"https://api.example.com/cart","landing.referrer":"https://www.google.com/search","utm_campaign":"spring","utm_source":"email"}
page_view           {"url.full":".../promo?utm_campaign=fall","landing.referrer":"https://www.google.com/search","utm_campaign":"fall"}
  log event "promo opened" {"landing.referrer":"https://www.google.com/search","utm_campaign":"fall"}
checkout.views      value=1 {"landing.referrer":"https://www.google.com/search","utm_campaign":"spring","utm_source":"email"}
promo.views         value=1 {"landing.referrer":"https://www.google.com/search","utm_campaign":"fall"}

other is never captured, and the referrer's query string and fragment are stripped. On the /promo landing, utm_source is removed and utm_campaign becomes fall (last touch). A same-origin referrer sets no landing.referrer. With both options false, none of these attributes appear.

What

Two options on the Observe plugin (ObserveOptions, exposed through @launchdarkly/observability).

captureQueryParams?: string[] | false

On by default with ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content'].

  • false or [] turns it off, and a custom list replaces the default. A trailing * matches a prefix ('utm_*').
  • At init, the SDK reads location.search and 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 #855 setAttributes store, so the reserved-key rules are the same. Empty values are skipped, and for a repeated parameter the first value wins.
  • Last touch: when an SPA navigation (pushState, replaceState or popstate) 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.
  • Precedence: capture only replaces or removes keys whose current value came from capture. A key the app set with setAttributes (before init or after) is never touched. removeAttributes removes a captured value, and a later landing with that parameter captures it again.
  • It works with manualStart: the values are present while tracing is set up (the document load span) and on telemetry buffered before start(). Navigation is tracked from SDK construction.
  • The SDK registers its own PathListener when constructed, before the page_view instrumentation's, so last-touch works even when page views are disabled.

captureReferrer?: boolean

Default true.

  • At init, a non-empty, cross-origin document.referrer is set as landing.referrer. Only the origin and path are kept: the query string, fragment and credentials are stripped.
  • A same-origin, empty or unparseable referrer sets nothing.
  • The value is not updated on SPA navigation, and setAttributes can override it.
  • landing. is not a reserved namespace, so the requested name is used as-is.

Unchanged

  • Everything is kept in memory for the current page load. Nothing is written to storage or cookies.
  • Metrics carry the captured attributes.
  • Privacy: only listed keys are captured, the default list is UTM-only, and the referrer is reduced to origin and path. This is stated in the TSDoc and the README.
  • README (@launchdarkly/observability): documents both options, last touch, and a recipe for keeping UTMs across a full page load or an auth redirect (sessionStorage + LDObserve.setAttributes on loads whose URL has none).
  • Not exposed on @launchdarkly/session-replay (its RecordOptions doesn't apply global attributes) or on H.init (which doesn't construct ObserveSDK).

Overlap

Tests

src/sdk/observe.captureQueryParams.test.ts has 35 tests.

Capture:

  • the default list captured without configuration
  • false and [] disabling capture
  • a custom list replacing the default
  • the utm_* prefix pattern
  • unlisted params ignored
  • a page load without UTMs capturing nothing
  • reserved keys ignored
  • removeAttributes
  • explicit and pre-init setAttributes winning
  • nothing written to storage or cookies
  • values on document load, page views, fetch, log, error and metric
  • disabled: no values on telemetry
  • manualStart

Last touch:

  • replace and remove on a new landing
  • keep on navigations without listed params
  • replaceState
  • explicit setAttributes keys (before or after init) never replaced or removed
  • re-capture after removeAttributes
  • no tracking when disabled
  • the new landing's page_view carries the new values while a span started before it keeps the old ones

Referrer:

  • cross-origin, stripped of query, fragment and credentials
  • same-origin
  • empty
  • unparseable
  • false
  • independent of captureQueryParams, not updated on navigation
  • setAttributes override

Mutation 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 passed
  • tsc --noEmit (typegen:check): clean
  • turbo lint (o11y, observability, session-replay): passed
  • yarn enforce-size: 173.4 kB brotli (limit 256 kB)
  • prettier --check on the changed files: clean

Asked by vkorolik through termag ask; follow up with termag 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 like utm_*, disable with false/[]) and captureReferrer (default true, sets sanitized cross-origin landing.referrer).

Captured query values flow through the existing setAttributes store 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; removeAttributes can drop captured keys for re-capture later.

PathListener is refactored to install a single shared history wrap on window (reference-counted subscribers, safe teardown when another wrap sits on top) so multiple SDK instances or bundles emit one locationchange per navigation. ObserveSDK wires landing capture at construct time, re-attaches the navigation listener on start(), and detaches on stop().

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.

vadim-korolik and others added 3 commits November 4, 2026 00:07
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
- 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
@vadim-korolik vadim-korolik changed the title feat(o11y): capture UTM query parameters as attributes feat(o11y): capture UTM query parameters and landing referrer as attributes Nov 4, 2026
@vadim-korolik

Copy link
Copy Markdown
Contributor Author

bugbot run

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

@vadim-korolik
vadim-korolik marked this pull request as ready for review November 4, 2026 01:39
@vadim-korolik
vadim-korolik requested a review from a team as a code owner November 4, 2026 01:39
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
@vadim-korolik

Copy link
Copy Markdown
Contributor Author

bugbot run

@cursor cursor Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Stale Bugbot comment from a previous run.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Generated-by: termag
@vadim-korolik

Copy link
Copy Markdown
Contributor Author

bugbot run

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅ 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
vadim-korolik enabled auto-merge (squash) November 4, 2026 02:18
@vadim-korolik vadim-korolik added the merge-ready Approved, CI green, Bugbot clean, no open threads label Nov 4, 2026
@vadim-korolik
vadim-korolik merged commit f32637b into main Nov 4, 2026
26 checks passed
@vadim-korolik
vadim-korolik deleted the termag-vkorolik/cmw1cfqqr4hswpm7w0jzydp0f branch November 4, 2026 02:26
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 -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

merge-ready Approved, CI green, Bugbot clean, no open threads

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants