Custom UserTiming Payloads

[nicjansma]

Forked from w3c/performance-timeline#2 and relevant for w3c/performance-timeline#9 (comment).

It might be useful to be able to specify a payload that would be stored along with your marks or measures.

The new method signature might be:

void mark(DOMString markName, object data);

data could be whatever, say {taskid: 1, widgets: 100}

This data attribute would be persisted along with that mark and attached to the PerformanceMark interface:

interface PerformanceMark : PerformanceEntry {
    object data;
};

(I don't know the correct IDL).

data could also be a DOMString. If so, I think there should be a specified string length limit, so people don't just JSON.stringify() a huge payload into it (which would be a lot less efficient than a native object).

This may help with w3c/performance-timeline#9, which discusses a "group" concept useful for any PerformanceEntry in the PerformanceTimeline. @igrigorik mentions being able to query for any entries that share an attribute via a new getEntries(DOMString attributeName, optional DOMString attributeValue) method, but a lone data attribute on UserTiming might not then be useful, unless its properties were automatically attached to the base PerformanceEntry (which I'm sure would introduce headaches with naming collisions).

[stevesouders]

I need a way to specify a mark's startTime that is NOT the current time.

It's counter-intuitive to create a mark (which results in a startTime value of the current time), and then setting the startTime value to my desired time value. I also don't think that's a preferred approach. (We probably want to make startTime readonly, altho it's currently not in Chrome.)

Would there be a way to set the startTime property with the approach suggested here? If not, how can I do that?

Possible use case, I want a user timing mark for when the first image request above-the-fold started. Or I want a mark based on a comparison, such as the max of duration of three images.

[igrigorik]

@stevesouders I agree, we shouldn't muck with UA generated startTime.

Based on @nicjansma's suggestion, you'd pass in a data object, which would then be accessible as a property on the event.. e.g:

mark("custom-mark", {time: ..., other: ...});

var m = performance.getEntriesByName("custom-mark");
console.log(m.data.time);
...

[eliperelman]

Bringing over my use cases from w3c/performance-timeline#2, I like this proposal, but would want to extend this to measures as well. Unfortunately the nature of .measure taking optional parameters would mean a little weirdness with its signature if we adopted just another argument. Forcing the argument to be an object helps though.

@stevesouders Wouldn't your use case be better suited to .measure? e.g.:

performance.mark('desiredStart');
...
performance.measure('customMark', 'desiredStart');

All in all, I am for this change and would like to see it move forward.

[eliperelman]

@igrigorik there is very strong support for having this feature for a wide variety of use cases here at Mozilla, and I think we should make an effort on moving this forward from a standards perspective. We are going to experiment with this to see how well it works and will report back if there are any caveats.

[eliperelman]

Specifically what we want to experiment with:

void mark(DOMString markName, optional dictionary payload);
void measure(DOMString measureName, optional DOMString startMark, optional DOMString endMark, optional dictionary payload);

[igrigorik]

@eliperelman crazy thought...

• window.markPayloads = {} -> stores "markName -> payload"
• patch mark and measure to automatically write and pull from both places, or.. define new methods

That's all we're looking for here, right?

[eliperelman]

<bikshed>
Not sure about exposing another global on window, but maybe window.performance.payloads?
</bikeshed>

Not sure about the implementation at the moment, but for my specific use cases, I would need access to the payload data from Gecko as well as JS, so a function may be in order.

[igrigorik]

@eliperelman I'm thinking something even simpler... Namely, I'm questioning if this needs to be specced and implemented at platform level at all, since you can easily implement this yourself.

[eliperelman]

Yes, I suppose that could be done. Going back to @stevesouders case, it would probably mean wrapping the performance.mark call altogether:

var mark = function(markName, payload) {
  mark.cache[markName] = merge(payload, {
    time: Date.now()
  });
  performance.mark(markName);
};
mark.cache = {};

[eliperelman]

I guess the nice-to-have deals with the retrieving of data, either on the platform side, or the getEntries et al side. You would need to patch getEntries to also fetch the payload associated with the mark.

Given enough demand though for this type of use case, does it make sense for everyone to duplicate this feature in their apps, or bake it into the web? That's a question that I do not yet know the answer to, @igrigorik. It would be nice to know how people feel about it.

[igrigorik]

Yep, that's exactly what I was thinking... except, with performance.now() instead of Date :)

We can document the pattern and apps can adopt it on as-needed basis. If we find lots of folks using it out in the wild, we can then revisit and see if offering a 'native' version offers any benefit. Yay/nay?

[eliperelman]

@igrigorik the performance.mark call will already have the startTime, so adding another performance.now() time is redundant. I used Date.now() just as an example of some sample data, in case you wanted to know the Unix epoch of the mark in addition to the High-Res time. :)