1 # TraceViewers Internals 2 3 ## Module system 4 5 * Tracing currently uses html imports for modules. 6 * We aspire to one-class-per file. Feel free to break up big files as you 7 encounter them, they exist purely for legacy reasons. 8 9 ## Tests 10 11 * See unittest.html -- mostly compatible with closure tests 12 * See [[/docs/dev-server-tests.md]] for more information 13 14 ## Components 15 16 * New UI elements should be Polymer components. 17 * You will see some old references to tvcm.ui.define('x'). This is our old 18 approach for building components. Its like polymer, in that you can subclass 19 the element, but it doesn't use shadow dom or have any templating or data 20 binding. 21 22 ## Rough module breakdown 23 24 * *Importers:* load files, produce a model 25 * *Model:* stateless, just the data that came from different trace formats 26 * *TimelineTrackView:* shows the data in gantt-chart form 27 * *Tracks:* visualize a particular part of the model 28 * *Selection:* a vector of things in the tracks that the user has selected (counter samples, slices) 29 * *Analysis:* provides summary of selection 30 * *TimelineView:* glues everything together 31 * *ProfilingView:* chrome-specific UI and glue 32 33 ## Importer notes 34 35 * The importer to model abstraction is meant to allow us to support multiple trace formats 36 37 ## Model notes 38 39 * The most important concept in the model is a slice. A slice is a range of time, and some metadata about that range, e.g. title, arguments, etc. 40 * Model has 41 * Processes 42 * Counters 43 * Counter samples (at ts=0.2s, we had 10mb allocated and 3mb free) 44 * Threads 45 * Slices (the FFT::compute function ran from 0.7s to 0.9s) 46 * AsyncSlices (at 0.2s we started a file read in the background and it finished at 0.5s) 47 * CpuSlices (at ts=0.2s we were running on cpu2) 48 * CPUs 49 * Slices (at ts=0.2 to 0.4 we were running "top") 50 * Counters (the clock frequency was 1.2ghz at ts=0.1s) 51 52 ## Slice 53 A slice is something which consumes time synchronously on a CPU or a thread. The 54 canonical example of this would be a B/E event pair. An async operation is also 55 considered a slice. Things get a bit more murky when looking at instant events. 56 A thread scoped instant event is a duration 0 slice. Other instant events, 57 process or global scoped, don't correlate to a thread or CPU and aren't 58 considered slices. 59 60 A flow event, on the other hand, is not a slice. It doesn't consume time and is, 61 conceptually, a graph of data flow in the system. 62 63 64 ## Slice groups 65 66 * When you see the tracing UI, you see lots of things like this: 67 68 ``` 69 Thread 7: [ a ] [ c ] 70 [ b ] 71 ``` 72 73 * This of visualization starts as a *flat* array of slices: 74 75 ``` 76 [{title: a, start: 0, end: 1), {title: c, start: 1.5, end: 3.5}, {title: b, start: 0.5, end: 0.8}[ 77 ``` 78 79 * We call this a slice group. A slice group can be composed into subRows -- a subRow is an array of slices that are all non-overlapping. E.g. in the thread7 example above, there are two subrows: 80 81 ``` 82 subrow 1: [ a ] [ c ] 83 subrow 2: [ b ] 84 ``` 85 86 * The SliceTrack is built around the idea of visualizing a single subrow. So when you see a thread like thread 7, youre really looking at 2 !SliceTracks, each of which has its own subrow. 87 88 * We have two slice group types: 89 * SliceGroup, for nested data. Used for threads. 90 * e.g. like ( (0,2), (0.1,0.3) ) 91 * We convert the slices into subrows based on containment. 92 * b is considered contained by a if b.start >= a.start && b.end <= a.end 93 * AsyncSliceGroup, for overlapping data. Used for async operations. 94 * e.g. ( (0, 2), (1, 3) ) 95 * We convert the slices into subrows by greedily packing them into rows, adding rows as needed when theres no room on an existing subrow 96 97 ## Timeline notes 98 99 * Timeline is just an array of tracks. A track is one of the rows in the UI. A single thread of data may turn into 5+ tracks, one track for each row of squares. 100 * The core of the Timeline is Slice 101 * Panning/zooming state is on the TimelineViewport, as is the grid and user defined markers 102 103 ## Tracks 104 ### there are three broad types of tracks 105 106 * Building blocks 107 * *Container track* 108 * A track that is itself made up of more tracks. Just a div plus logic to delegate overall track interface calls down to its children. 109 * *CanvasBasedTrack* 110 * A track that renders its content using HTML5 canvas 111 * Visualizations 112 * *SliceTrack:* visualizes an array of non-overlapping monotonically-increasing slices. Has some simple but critical logic to efficiently render even with thousands (or more) slices by merging small slices together when they really close together. 113 * *CounterTrack:* visualizes an array of samples values over time. Has support for stacked area charts. Tries to merge samples together when they are not perceptually significant to reduce canvas drawing overhead. 114 * *Model tracks:* e.g. ThreadTrack 115 * Derives from a container track, takes a timeline model object, e.g. a thread, and creates the appropriate child tracks that visualize that thread 116 117 ## Selection notes 118 119 * When you drag to select, that creates a selection object by asking every track to append things that intersect the dragged-box to the selection 120 * A selection object is an array of hits. 121 * A hit is the pairing of the track-level entity that was selected with the model-level entity that that visual thing represents. 122 * Eg a thread has a bunch of slices in it. That gets turned into a bunch of subrows that we then turn into !SliceTracks. When you click on a slice in a thread in the UI, the hit is {slice: <the slice you clicked>, thread: <the thread it came from>}. 123 * The hit concept exists partly because slices cant know their parent (see model section for why). Yet, analysis code want to know parentage in order to do things like group-by-thread. 124 125 ## Analysis code 126 127 * Takes as input a selection 128 * Does the numeric analysis and dumps the numeric results to a builder 129 * The builder is responsible for creating HTML (or any other textual representation of the results) 130
