Spec console.timeStamp

[domfarolino]

See #27.

[and-oli]

Reusing this open issue to discuss a proposal to explore potential enhancements to the console.timeStamp API, which is a non-standard but it’s implemented in several major browsers. The goal is to improve its utility for customizing the Performance panel in developer tools, particularly in the context of modern web frameworks that often abstract the browser's underlying model. (This proposal is being submitted on behalf of the Chrome Page Quality team at Google).

Explored Changes:

Custom Measurements: Allow developers to add custom measurements to the Performance panel using console.timeStamp, in addition to the current instant markers. This could involve additional arguments to the API, such as a measurement name and a way to indicate the start and end time of the measurement.
Swimlane Control: Enable developers to specify the swimlane in which their custom measurements appear. This could be achieved through another argument to the API or a separate configuration option.
Custom presentation format: A generalization of the point above, so that other presentation parameters like entry color, details, etc. can be customized as well.

Use Cases:

Debugging Complex Apps: In large applications, custom measurements could help isolate performance bottlenecks related to specific components or interactions.

Framework and tools Integration: Developers using frameworks could add framework-specific performance metrics to the Performance panel, aligning it with their mental models.

Considerations:

• Standardization: As console.timeStamp is not currently standardized, any changes should be considered for potential future standardization.
• Compatibility: The proposed enhancements should aim to be compatible with existing implementations in major browsers, if possible.

Alternative Approaches and why console.timeStamp:

We considered extending the existing performance.mark and performance.measure APIs. However, these APIs are designed to create user space-observable data (the data is buffered and readable / observable in the page), and maintaining this infrastructure introduces a slight overhead, which is particularly noticeable when the API is called extensively. Since the sole purpose of console.timeStamp is to add data to the DevTools Performance panel, it can be optimized for minimal overhead, particularly in cases where profiling is disabled. Additionally this functionality, being primarily for interaction with DevTools, aligns better with the console API.

Potential API Prototype:

Overloading console.timeStamp

type TimeStampName = string;
// Current impl: Single instant marker.
console.timeStamp(timeStampName: TimeStampName);

// Override: Measurement with custom start and options.
console.timeStamp(
  measureName: TimeStampName,
  start: TimeStampName,
  devtoolsOptions?: DevToolsOptions
);

// Example
// t = 0
console.timeStamp("start");
// t = 10
console.timeStamp("measure", "start", { 
  // optional devtools options (lane, color, etc.)
}); // measure = [0, 10]

Alternatively: a new API or a even a new namespace could be defined under which further features to assist with the integration with the performance tool are implemented:

console.timeline.mark();
console.timeline.measure(measure: TimeStampName, start: TimeStampName);
// ... (Potentially more methods for advanced interactions)

Open Questions:

• Does this discussion fit in the console API space or is it a better fit for the performance API space?
• Which API prototype is more intuitive and ergonomic for developers?
• What should the DevToolsOptions interface include (e.g., swimlane, color, etc.)?

[dcrousso]

instead of adding a start to console.timeStamp why not just use the existing console.time/console.timeEnd? in WebKit, console.time/console.timeLog/console.timeEnd already has plumbing to send the necessary data to Web Inspector so long as the developer provides a label, meaning that exposing it in the Timelines Tab is just a matter of building the UI. we could/should also make console.timeLog do something similar to console.timeStamp

as far as enhancements, i could see developers appreciating a way to suggest a color or category/importance. im generally favorable of the idea so long as it's not something binding (e.g. ignore the suggested color if it's too similar to the background, drop the category/importance if it's too long of a string, etc.)

[and-oli]

the reason we thought about console.timeStamp is because it is meant specifically to add data to the performance tool which means it doesn't log into the console, unlike console.time/timeEnd. In complex applications this is important because the console could potentially be spammed with many logs otherwise.

as far as enhancements, i could see developers appreciating a way to suggest a color or category/importance

There are existing requests for something that achieves this specifically, for example: w3c/user-timing#109 & w3c/user-timing#25. Although these are requested for the UserTimings API, they could be added to the console.timeStamp API as well, since it's meant primarily for integrating with the browser's Performance tool.

im generally favorable of the idea so long as it's not something binding (e.g. ignore the suggested color if it's too similar to the background, drop the category/importance if it's too long of a string, etc.)

Agreed. Also, these properties should be completely optional for the developer

[bgirard]

For my use case it's important that the API allows specifying both a startTime and an endTime in the case of blocks otherwise the API is not useful. Side note is that Android's Trace API suffers from this deficiency and has caused a lot of pain. Here's some of my use case where start/end times are required and that we can't use an 'immediate' tracing API:

• Facebook Web's performance tracing code will watch DOM mutations and wait for certain end-to-end triggers (~~ DOMContentLoaded et al.). When the end-to-end load triggers have been set and we don't expect any more startup DOM mutations we will retroactively setup a measure from navigation start to the last DOM mutations which has occurred in the past.
• React will gather timestamps throughout rendering but will only emit the performance measures/blocks at the end. Currently adding 1000s of rendering measures can take in the order of 10-50ms. Instead of having that overhead interlaced with the rendering code, we can create a distinct flush instrumentation block and we can time and easily ignore that 50ms chunk in the timeline.
• Sometime you're working with an API that doesn't provide callbacks from which to add immediate measures, but only provides timestamps after the fact.

[bgirard]

Alternatively: a new API or a even a new namespace could be defined under which further features to assist with the integration with the performance tool are implemented

I like the idea of adding something like console.timeline.*. We can group calls there such as marker/instant, measure/block/event, and potentially in the future we can add counters and flow (link) events.

[and-oli]

For my use case it's important that the API allows specifying both a startTime and an endTime in the case of blocks otherwise the API is not useful.

It makes sense to have something like this that's analogous to the ergonomics of performance.measure("", {start, end}). Ideally it can still be cheap / free in the no-op cases, but that is implementation detail. In Chrome at least there are ways in which this can be done.

like the idea of adding something like console.timeline.*.

Thinking more about it as with your examples I think it can get very interesting this way

[domfarolino]

Does this discussion fit in the console API space or is it a better fit for the performance API space?

Personally I think I'm convinced by your reasoning for pursuing this as a console API instead of extending existing performance APIs. @dcrousso, what do you think about this and @and-oli's reasoning for new APIs instead of time()/timeEnd()?

Which API prototype is more intuitive and ergonomic for developers?

First, at a high level I lean towards following the design precedents articulated in w3ctag/design-principles#426 (comment), which would have us avoiding console.timeline.foo(), in favor of console.foo() instead. So I personally like what I see in the first code snippet, with a few nits.

Second, instead of having the following overloads:

• console.timeStamp(timeStampName)
• console.timeStamp(measureName, start, optional options)

What about console.timeStamp(measureName, optional OptionsDictionary), where OptionsDictionary contains start and the devtools options?

[and-oli]

What about console.timeStamp(measureName, optional OptionsDictionary), where OptionsDictionary contains start and the devtools options?

Don't feel strongly about it, but that would make it slightly harder to call the API in what's likely the most common use case of the API: adding a measurement without further options. With no dedicated overload you would have to use an object with a single property every time: console.timeStamp(measureName, {start}).

These overloads take inspiration from the performance.measure syntax, which I believe had a similar reasoning.

[domfarolino]

These overloads take inspiration from the performance.measure syntax, which I believe had a similar reasoning.

OK thanks for explaining, happy to not go against that precedent.

[dcrousso]

i can understand the rationale behind console.timeStamp being used differently from console.time/console.timeLog/console.timeEnd, but i generally dislike having more than one API that all do extremely similar things

id much rather allow/encourage browsers to add UI that allows the developer to control where the data is shown (e.g. there could be a setting for "Timelines Tab: Show console.timeLog" as well as "Console Tab: Show console.timeLog/console.timeEnd")

but i suppose we're kinda past that point a bit since console.timeStamp already exists :/

as far as adding new things, the only major concern i have with start is what we define it as relative to (e.g. is it from when the page first started loading or when performance.now() === 0 or something else?), as well as whether that's compatible with how developer tooling does other time measurements (e.g. how console.time/console.timeLog/console.timeEnd appear in the UI relative to other things outside of the developer's control)