event annotation on the heatmap visualization

[iori-yja]

We are considering to add an annotation feature on the heatmap to represent simultaneous events on the heatmap so that users can visually grasp relation between "hot-spot" on the heatmap and co-occurring events or can seek to an event on the heatmap.
I'd like to discuss with you about this feature before we start to implement, because this feature may require several decision to contribute to the mainline.

The hardest thing to decide is representation of the metadata, which will contain the absolute time information to relate start time of the sampling to the date time, and the information where to retrieve the event collection.
The other one to be decided is event format which may contain {name, start_at, in_or_out, length...} for example. in_or_out is presenting whether the event is shown as "in" event on top of the heatmap or as "out" event below (for more concisely, it will be good representation to rotate the map 90° clock wise so the map extends below as time goes by; and the event is plotted left and right corresponding to the attribute).

                (start)

(in)           ++++++++++           (out)
               ++++++++++
/login_________±±±$++++++
  :            ++++++++++
  :            ++++++#±±±______ Redis [session]
  :            ++++#±±±±±______ MySQL [account] 
  \____________±$++++++++

                 (end)
[a blueprint of annotating the heatmap with events]

A possible solution is just leave not to decide the precise detailed specification of the event collection and metadata but prepare a standardized way for add-ons to overlay any information. In this case, the work on flamescope won't be so large and most part of it is laying on d3 specific (actually I'm not front guy but I think letting add-ons to invoke d3.compose can solve most part of it; yet questions "what is 'add-ons' and how to place it" still remain).

The other solution is define the structure of those data and support them. In this case, I will be happy if I could discuss all the people interested in the feature and seek well-defined data format for that.

[spiermar]

@iori-yja the overlay solution would be the most flexible, but not that trivial. The data-based solution depends on what kind of annotation you have in mind. Instant events, of events with duration, etc. Not sure if I got the use case for in_or_out, but a common format is the Trace Event format, with begin and end events, complete events (start + duration) and instant events. I'm implementing support for this format here soon, but nothing prevents having a sidecar file with the perf script output, containing the annotation metadada.