Proposal: Introduce a Lazy Activation Mode for JS-Self Profiling API

[thomasbertet]

Context

During our WebPerf WG Call on December 4th, we revisited the current state of the JS-Self Profiling API and discussed several pain points and challenges.

A key topic was the need for a mechanism that allows JS-Self Profiling to be enabled on a page without immediately incurring profiling overhead.

Today, the Document-Policy: js-profiling header performs two roles:

• (A) It authorizes scripts to create a new Profiler() instance and collect samples.
• (B) It triggers a warm-up of the necessary Chromium/V8 components so that the new Profiler() call is nearly instantaneous.

However, usage and benchmarks show that this warm-up phase is responsible for most of the overhead during page load—notably affecting metrics such as FCP and LCP.
Because this warm-up occurs eagerly whenever the header is present, the current model is essentially always-on, regardless of whether the profiler is ever instantiated.

Why do we need a lazy mode?

There are several pain points with the current “eager” approach:

1. Performance trade-offs between loading and profiling

   • There is no way to defer profiling overhead to a non-critical period (e.g., after page load).
   • There is no way to incur overhead only if the Profiling API is actually used.
   • Many users (including Datadog’s internal dogfooding and external adopters) are unwilling to trade page load performance for profiling capabilities.

2. Sampling strategy coupling between backend (server) and frontend (client)

   • To avoid overhead on unsampled sessions, sampling must be aligned between server and client, which introduces operational complexity.
   • In many setups, sampling occurs on the client side; keeping server and client in sync requires additional tooling.
   • Even if a session is not sampled, the presence of the header means the page still pays the warm-up cost.

Suggestions

During the call, we explored several ways to introduce a more flexible activation model—specifically, a lazy mode—such as:

• Adding a new HTTP Header "Document-Policy" value like: Document-Policy: js-profiling-lazy OR
• Introducing an HTML hint (e.g., a meta tag): <meta name="js-profiling" value="lazy" />

These options would not impact the existing eager behavior.
Sites that want profiling initialized immediately could continue using: Document-Policy: js-profiling

Meanwhile, developers who want to defer profiling overhead until later in the lifecycle could opt into the lazy mode.

Under this proposal, the new header (or meta tag) would:

• Allow scripts to use the JS-Self Profiling API when needed, without performing any warm-up during page load.

Discussion

There was broad agreement on the call that the current “eager” mode is not an ideal default.
A lazy mode would reduce surprise and avoid unintended load-time performance regressions, especially for users who want profiling only during targeted parts of the session.

Both Sentry (Sigrid Huemer @s1gr1d) and Datadog (Thomas Bertet @thomasbertet) expressed strong support for exploring this direction, as it would meaningfully improve adoption and usability.

If there is consensus on the design, both vendors are willing to contribute implementation work—with support from browser-side collaborators (e.g., @mmocny and others).

And with all that, let's open the discussion!

[mmocny]

We've heard this request several times from several sources over the years, so I support finally trying to get it done. Thanks for poking and offering to pick up this work.

Aside: There also seems to be a growing activity / usage of the api, so the timing is right for someone to take more ownership over it again.

If there is consensus on the design, both vendors are willing to contribute implementation work—with support from browser-side collaborators (e.g., @mmocny and others).

My humble suggestion would be that it seems better to start with just a new HTTP header based document policy value, rather than supporting dynamic injection via meta tag. I do understand the ergonomic advantages of the latter, but I think it comes with some new risks that need careful evaluation, vs adding what amounts to a LESS capable/impactful variant of what is already available.

Perhaps you could create a PR for the spec change? And then file a Chromium issue for the implementation work, and we can discuss implementation specifics there?

---

(In short-- I worry that enabling this API via <meta> would support any JS snippet embedded on the page to enable profiling, and that has new risks that need to be thought through. We know there is a negative effect on performance to using this api and so it should be carefully sampled and selectively used-- but the general appeal of using the api might be too enticing for some parties, and and site owners will not be empowered to control access if it can be injected. This is theoretically no worse than status quo, but in practice...)

[thomasbertet]

Here is the Chromium issue and the Specification update.