Annotation of performance entries

[eliperelman]

From: http://lists.w3.org/Archives/Public/public-web-perf/2014Feb/0056.html

@jatinder: Another piece feedback I’ve heard on the Timing APIs is that it would be great if we provided the ability to “annotate” entries with app-specific meta data. For example, if someone wanted to add in specific information on what the server was doing during a certain time period they could annotate the timeline so you can see the complete client and server side interaction. Additionally, one could also annotate why a measure might have taken as long as it did (e.g. how many items were rendered, which column was sorted, etc.). Something like performance.annotateMeasure(“measureName”, “keyName”, “value”). Does something like this sound remotely interesting?

Juan Carlos Estibariz: The annotations would be very useful, and it would be even better if it was possible to add annotations directly from the server (e.g. by adding a header defined by this specification), this would allow direct correlation between client side and server side performance measurements.

@josh: User timings in the response header sounds elegant. We currently shove all our server timings into a hidden element in the page footer as data- attributes. Then we have to parse these out on page load.

---

Having the ability to somehow annotate an entry with custom metadata would open the doorway to some very interesting tooling improvements with multi-page UIs, e.g. multi-frame pages or multi-process apps like in Firefox OS.

Is there enough information available to work towards this? Based on @jatinder's recommendation I see:

partial interface Performance {
  void annotateMark(DOMString markName, DOMString key, DOMString value);
  void annotateMeasure(DOMString measureName, DOMString key, DOMString value);
};

[igrigorik]

Can we split the server-sent marks discussion into a separate thread? That functionality is orthogonal to mark annotations.

For mark annotations, I'm not yet convinced that it's really necessary? Let's say you're iterating over a set of entries and executing some logic on the client (rendering, or some such): you can emit a mark each time you execute your logic, and you can then call measure() with first and last mark to build an aggregate view across multiple marks - e.g. [mark:e1, mark:e2, mark:e3, measure: e1-e3]. The choice of mark + measure names can also communicate a lot of meta data.

What other meta-data would you attach to marks, and how would you use it? Am I missing something?

[eliperelman]

+1 on the server-sent marks.

As strange as it sounds, being able to annotate a marker with it's intended origin would help solve a difficult use case for Firefox OS, but could also be used for mutli-frame websites.

Let's say that you wanted to time how long it takes to launch a phone application from a home screen application. If I were to create a normal marker in my home screen application:

performance.mark('launchApplication');

It would have timing contextual to the home screen application. In my phone application:

performance.mark('mark_fully_visible');

If I wanted to time the difference between these entries, there is currently no mechanism available to do so, and my home screen marker would be lost every time I launched a different application. I need to somehow relate these markers to each other, which annotations could solve, but I am not sure that they should solve. I may start a new thread to discuss different solutions, but in the meantime, linking two markers with a URL would give a start to being able to achieve this.

[igrigorik]

Are you implying that your launch application would use "server sent marks" mechanism to communicate marks to the application that's being launched? If so, once again... let's start a new thread.

I'm still trying to understand the value of:

partial interface Performance {
  void annotateMark(DOMString markName, DOMString key, DOMString value);
  void annotateMeasure(DOMString measureName, DOMString key, DOMString value);
};

I.e. adding arbitrary payloads to an existing mark/measure.

[eliperelman]

Sorry, I am not implying any usage of server-sent marks. I think the confusion here is arising from my intent to use an annotation mechanism to solve an orthogonal use case. I will raise my use case on the list and we can go from there on whether annotations or something different would be a good solution. :smile:

[nicjansma]

Currently the only PerformanceTimeline entries that are generated from userland are UserTiming. The one scenario I can think of that might be useful would be to specify a payload alongside a mark, for example:

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).

I'm not convinced this is a huge benefit to UserTiming, but I'm sure some could find it useful.

Are there other scenarios / PerformanceEntries where it would be useful to annotate, for example, ResourceTiming? I'm not coming up with any useful scenarios for the other types.

[igrigorik]

Relevant thread for server timing events (and need for some form of non-timing annotations): http://lists.w3.org/Archives/Public/public-web-perf/2014Nov/0006.html

@nicjansma if we go down this route, I'd vote for exposing a DomString - we want to keep it simple, and we don't want applications stuffing large objects into the timeline.

[nicjansma]

@igrigorik A DomString would work, though there might need to be an arbitrary size limit (say 1k or 32k or something) to enforce the idea that the payload should be lightweight.

Otherwise devs may be like "I can't pass an arbitrary object? No problems, let's JSON.stringify it!" and it'll end up taking more size due to serialization :)

[igrigorik]

Reading through the thread once over...

• The server timing use cases are now addressed via (appropriately named :)) Server Timing spec.
• @nicjansma: custom annotations beyond current "markName": still seems to me that much of this can be encoded in the mark name itself? That said, if you think there is a strong need for this, let's open a bug on User Timing repo?
• @eliperelman: if I'm following your use case of "linking records", perhaps this can address it: https://github.com/w3c/performance-timeline/pull/9#issuecomment-89042906 ?

Since this seems like a meta-bug, can we close this one and/or split other discussions into separate issues?

[nicjansma]

Opened a separate issue in UserTiming https://github.com/w3c/user-timing/issues/3

[igrigorik]

Closing this, let's continue the User Timing discussion in https://github.com/w3c/user-timing/issues/3.