Skip to content

⚗️ [PROF-16224] start early profiling before the SDK is loaded - #5192

Open
thomasbertet wants to merge 15 commits into
mainfrom
thomas.bertet/PROF-16224-early-collection-errors-profiling
Open

thomasbertet wants to merge 15 commits into
mainfrom
thomas.bertet/PROF-16224-early-collection-errors-profiling

Conversation

@thomasbertet

@thomasbertet thomasbertet commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator

Motivation

The JS Self-Profiling Profiler only starts when the profiler chunk loads, so everything between HTML parse and chunk load is invisible in profiles: typically the most CPU-intensive window of the page (bundle evaluation, hydration, first paint). Staging measurements in PROF-16083 showed the early snippet covering 74% of the page-load window vs 32% for an SDK-internal early start.

PROF-16224 RFC proposes an early collection package: a tiny script evaluated as the first script of the page. This implements its first slice: profiling only. Other RUM events collectors (raw errors, fetch/XHR, console) may be added to the same mechanism in later iterations, behind the same window._DD_EARLY_COLLECTION contract.

Changes

  • New package @datadog/browser-early-collection: a standalone, dependency-free script (bundle datadog-early-collection.js, 257 B min / 257 B gz). Evaluating it starts a JS Self-Profiling API Profiler session (sampleInterval: 10, maxBufferSize: 9000; fails silently when the API is unsupported or the Document-Policy: js-profiling response header is missing) and publishes window._DD_EARLY_COLLECTION = { version, startClocks, profiler }. No API, no config, no network. The npm surface is side-effect-free (explicit startEarlyCollection()); the auto-start entry lives in entries/main.ts, outside src/, because the disallow-side-effects rule scopes to packages/*/src.
  • SDK side (browser-rum only, one small module earlyCollectionProfiler.ts):
    • The profiler chunk adopts the early instance as its first periodic instance, so the first collected profile covers the early collection period and continues seamlessly (collection_type: 'early' in the profiling context; the instance is stopped by the normal periodic lifecycle at its first rollover). Already-stopped instances are skipped, and the global is deleted on claim so it can be taken only once.
    • profilerApi stops the early profiler on all not-profiling paths (no session, not sampled, unsupported browser, chunk load failure or throw, SDK stop). These paths run before the chunk is ever requested, so no race is possible.
  • datadog-logs.js and datadog-rum-slim.js ship zero early-collection bytes (byte-identical builds vs main).
  • Bundle footprint vs main 119e0c72 (min / gzip -9): datadog-rum.js +449 B / +142 B, profiler chunk +103 B, datadog-logs.js and datadog-rum-slim.js +0, snippet 257 B new.

Note for reviewers: this implementation was written by an AI coding agent and reviewed by a human; the files most worth a careful pass are earlyCollectionProfiler.ts (the claim/stop helper) and the datadogProfiler.ts adoption wiring.

Test instructions

  • yarn workspace @datadog/browser-early-collection build produces packages/browser-early-collection/bundle/datadog-early-collection.js
  • yarn test:unit --spec packages/browser-early-collection/src/index.spec.ts
  • yarn test:unit --spec packages/browser-rum/src/domain/profiling/earlyCollectionProfiler.spec.ts
  • yarn test:unit --spec packages/browser-rum/src/boot/profilerApi.spec.ts --spec packages/browser-rum/src/domain/profiling/datadogProfiler.spec.ts
  • Dogfood: inject the built snippet as the first script of a page (requires the Document-Policy: js-profiling header), load the SDK async, and check that the first profile covers the early window with collection_type: 'early'.

Checklist

  • Tested locally
  • Tested on staging
  • Added unit tests for this change.
  • Added e2e/integration tests for this change.
  • Updated documentation and/or relevant AGENTS.md file

@cit-pr-commenter-54b7da

cit-pr-commenter-54b7da Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Bundles Sizes Evolution

📦 Bundle Name Base Size Local Size 𝚫 𝚫% Status
Rum Salesforce 192.54 KiB 192.97 KiB +438 B +0.22% ✅
Rum 192.52 KiB 192.95 KiB +438 B +0.22% ✅
Rum Salesforce Profiler 8.01 KiB 8.10 KiB +100 B +1.22% ✅
Rum Profiler 8.01 KiB 8.10 KiB +100 B +1.22% ✅
Rum Salesforce Recorder 32.62 KiB 32.62 KiB 0 B 0.00% ✅
Rum Recorder 32.62 KiB 32.62 KiB 0 B 0.00% ✅
Logs 60.26 KiB 60.26 KiB 0 B 0.00% ✅
Rum Slim 148.45 KiB 148.45 KiB 0 B 0.00% ✅
Worker 24.23 KiB 24.23 KiB 0 B 0.00% ✅
Rum Shopify 223.58 KiB 224.01 KiB +438 B +0.19% ✅
Rum Shopify Profiler 8.00 KiB 8.10 KiB +100 B +1.22% ✅
Rum Shopify Recorder 4.85 KiB 4.85 KiB 0 B 0.00% ✅
Early Collection N/A 309 B N/A N/A N/A

@datadog-prod-us1-5

datadog-prod-us1-5 Bot commented Oct 27, 2026 •

Copy link
Copy Markdown

Pipelines  Tests

✨ Unblock PR with BitsAI

❌ Errors

Your PR has failed checks. Please review the issues below and take necessary action before merging.

🚦 1 Pipeline job failed

DataDog/browser-sdk | check-schemas — 🔧 Needs a code fix, caused by this PR

View more details · View in GitLab

ℹ️ Info

No other issues found (see more)

🧪 All tests passed
❄️ No new flaky tests detected

🎯 Code Coverage (details)
• Patch Coverage: 75.61%
• Overall Coverage: 78.13% (+0.04%)

Useful? React with 👍 / 👎

This comment will be updated automatically if new data arrives.
🔗 Commit SHA: e0e7a0f | Docs | View more details | Give us feedback!

@thomasbertet thomasbertet changed the title ⚗️ [PROF-16224] start early collection of errors and profiling before the SDK is loaded ⚗️ [PROF-16224] start early profiling before the SDK is loaded Oct 30, 2026
@thomasbertet
thomasbertet marked this pull request as ready for review November 16, 2026 13:55
@thomasbertet
thomasbertet requested a review from a team as a code owner November 16, 2026 13:55

@datadog-prod-us1-5 datadog-prod-us1-5 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.

Bits Code Review: FAIL

An early profiler that fills before RUM starts can be adopted without resuming sampling, creating up to a minute of additional missing data. The standalone bundle is also absent from the CDN deployment list.

Open Bits AI session

🤖 Bits Code Review · Commit dce7158

@datadog-prod-us1-5 datadog-prod-us1-5 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.

Bits Code Review: FAIL

The PR adds pre-SDK profiling and handoff to RUM, but package version 7.16.2 fails validation against release 7.18.0. Both earlier issues remain unfixed: exhausted early buffers can leave sampling idle for another minute, and the standalone bundle is missing from CDN deployment registration.

Open Bits AI session

🤖 Bits Code Review · Commit 7b3e9ac

The early collection snippet now records a bufferFull flag via its own
samplebufferfull listener. When the SDK adopts an instance whose buffer
filled before load, the profiler chunk collects it immediately and starts
a fresh instance instead of waiting for the first collection interval,
preserving the early samples.
Register browser-early-collection in the deploy and source map upload
package lists so the 345 B snippet ships to the CDN (prod, datacenters,
staging, canary and pull-request previews) with cache invalidation.

@datadog-prod-us1-5 datadog-prod-us1-5 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.

Bits Code Review: FAIL

Pre-SDK profiling now handles exhausted buffers and CDN deployment, and the package version matches the release. Immediate rollover introduces a quota race: an early profile can be uploaded before a pending quota check denies the session.

Open Bits AI session

🤖 Bits Code Review · Commit 96e7f97

…rs-profiling

Conflict in datadogProfiler.ts resolved: main's RUM-20021 refactor moved profile
assembly (histories, buildProfileEvent) out of the orchestrator into
contexts/ and profileAssembly.ts; the early-collection adoption branch
(adopted Profiler instance, ClocksState, bufferFull immediate rollover) is
kept on main's structure.
…ontract

Reverts the bufferFull contract field and the immediate rollover of an
exhausted early Profiler. Buffer exhaustion stays undetected at adoption:
the exhausted instance is adopted as running and the normal collection
interval does the rollover. The limitation is now documented explicitly at
the adoption site: in the rare case where the SDK evaluates more than ~90 s
after page load, the buffered samples are preserved but no new sample is
taken until adoption + collectIntervalMs.

@datadog-prod-us1-5 datadog-prod-us1-5 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.

Bits Code Review: PASS

More details

The PR starts profiling before SDK load and hands the instance to RUM, with CDN and package-version fixes retained. Removing immediate rollover closes the reported quota race; it explicitly accepts up to another minute without new samples when the early buffer has already filled.

Was this helpful? React 👍 or 👎

Open Bits AI session

🤖 Bits Code Review · Commit 5e313b6

Per review feedback on PR #5192: the profiling context no longer carries
collection_type 'standard' for every profiled session. The field is now
optional in ProfilingInternalContextSchema and set to 'early' only while
the Profiler instance started by the early collection package is running;
it is absent for instances the SDK starts itself, so only early collection
is reported in _dd.profiling.

@datadog-prod-us1-5 datadog-prod-us1-5 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.

Bits Code Review: FAIL

Pre-SDK profiling retains the CDN/version fixes and avoids the immediate-rollover quota race, while explicitly accepting delayed sampling after buffer exhaustion. The new early-only collection tag is added directly to generated types without updating the pinned source schema, so schema consistency CI will fail.

Open Bits AI session

🤖 Bits Code Review · Commit 15aa5a5

* first collected profile covers the early collection period, from snippet evaluation to SDK takeover.
* The attribute is absent when the SDK started the Profiler instance itself.
*/
readonly collection_type?: 'early'

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2 Generate the new property from the source schema

The pinned rum-events-format source schema lacks collection_type. CI regenerates this file in check-schemas, which will remove this manually added property and fail the consistency check. Add the property to the source schema, update the pinned dependency, and regenerate the types.

React: 👍 useful · 👎 wrong · 😕 unclear · 👀 right, but not acting on it

What each reaction means
  • 👍 Useful: correct, and you're fixing it or will.
  • 👎 Wrong: the finding is incorrect, for example the bug can't happen or the code was misread.
  • 😕 Unclear: you can't tell what it means or why it matters.
  • 👀 Right, not acting: correct, but intended, out of scope for this PR, a known risk, or too minor.

🤖 Bits Code Review · Open Bits AI session

Per review feedback on PR #5192: a shared layout plus a page template, or a
tag manager, can evaluate the script twice. The second evaluation now
returns early when window._DD_EARLY_COLLECTION is already published:
overwriting the global would orphan the first running Profiler instance,
which keeps sampling until its buffer fills and nothing can stop it. The
earliest session wins, as it captures the most of the pre-SDK window.

@mormubis mormubis left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

LGTM! I've approved the rum events format too!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants