1 | ![build status](https://travis-ci.org/heimdalljs/heimdalljs-lib.svg)
|
2 |
|
3 | ## Global Session
|
4 |
|
5 | Heimdall tracks a graph of timing and domain-specific stats for performance.
|
6 | Stat collection and monitoring is separated from graph construction to provide
|
7 | control over context detail. Users can create fewer nodes to have reduced
|
8 | performance overhead, or create more nodes to provide more detail.
|
9 |
|
10 | The graph obviously needs to be global. This is not a problem in the browser,
|
11 | but in node we may have multiple different versions of heimdalljs loaded at
|
12 | once. Each one will have its own `Heimdall` instance, but will use the same
|
13 | session, saved on `process`. This means that the session will have a
|
14 | heterogeneous graph of `HeimdallNode`s. For this reason, versions of heimdalljs
|
15 | that change `Session`, or the APIs of `HeimdallNode` or `Cookie` will use a
|
16 | different property to store their session (`process._heimdall_session_<n>`). It
|
17 | is quite easy for this to result in lost detail & lost stats, although it is
|
18 | also easy to detect this situation and issue a warning.
|
19 |
|
20 | ## API
|
21 |
|
22 | ### Heimdall
|
23 |
|
24 | ### Creating a Heimdall instance
|
25 |
|
26 | `require('heimdalljs')` to access an instance using the globally shared session.
|
27 |
|
28 | You can create your own instance with its own session, but this is generally
|
29 | reommended only for testing.
|
30 |
|
31 | ```js
|
32 | var Heimdall = require('heimdalljs/heimdall');
|
33 | // this will create its own session and not use the global session
|
34 | var myInstance = new Heimdall();
|
35 | ```
|
36 |
|
37 | #### Properties
|
38 |
|
39 | - `heimdall.current` Return the leaf `HeimdallNode` of the currently active nodes.
|
40 | - `heimdall.root` Return the root `HeimdallNode`
|
41 |
|
42 | #### Functions
|
43 |
|
44 | - `heimdall.start(id, Schema)` Create a new node with id `id`. This node becomes the
|
45 | active node. Its parent is the currently active node. Return this node's
|
46 | `Cookie`.
|
47 | - `heimdall.node(id, [Schema], callback, [context])` Create a new node, invoke
|
48 | `callback` passing in the newly created node's `stats` object and then stop
|
49 | the node.
|
50 | - `registerMonitor(name, Schema)` register a monitor under namespace `name`. An
|
51 | error will be thrown if the reserved names `own` or `time` are used, or if a
|
52 | monitor with that name has already been registered for this session.
|
53 | - `statsFor(name)` return the stats object for the monitor under namespace
|
54 | `name`.
|
55 | - `configFor(name)` return the config object under `name`. Heimdall does not do
|
56 | anything with these config objects: it is a place for downstream consumers to
|
57 | share config across a heimdall session (see eg
|
58 | [heimdalljs-logger](https://github.com/heimdalljs/heimdalljs-logger)).
|
59 | - `toJSON()` return the json for the entire graph. This is intended to be
|
60 | written via `JSON.stringify` and then consumed by downstream apps (see eg
|
61 | [broccoli-viz](https://github.com/stefanpenner/broccoli-viz)).
|
62 | - `visitPreOrder(callback)` sugar for `root.visitPreOrder(callback)`
|
63 | - `visitPostOrder(callback)` sugar for `root.visitPostOrder(callback)`
|
64 |
|
65 |
|
66 | ### HeimdallNode
|
67 |
|
68 | #### Identifiers
|
69 |
|
70 | #### Properties
|
71 |
|
72 | - `isRoot` returns true for the root node, and false for all other nodes.
|
73 |
|
74 | #### Functions
|
75 |
|
76 | - `visitPreOrder(callback)` visit the subtree rooted at this node with a
|
77 | depth-first pre-order traversal.
|
78 | - `visitPostOrder(callback)` visit the subtree rooted at this node with a
|
79 | depth-first post-order traversal.
|
80 | - `forEachChild(callback)` invoke `callback` for each child of this node (but
|
81 | not other descendants).
|
82 | - `remove` remove this node from its parent. May only be called on an inactive,
|
83 | non-root node. Intended for long-running applications to free up memory after
|
84 | saving a subgraph via `toJSONSubgraph`.
|
85 | - `toJSON()` Return the serialized representation of this ndoe.
|
86 | - `toJSONSubgraph()` Return the serialized representation of the subtree rooted at
|
87 | this node.
|
88 |
|
89 | ### Cookie
|
90 |
|
91 | #### Functions
|
92 |
|
93 | - `stop()` stop the node associated with this cookie. May only be called on the
|
94 | current node.
|
95 | - `resume()` resume a stopped node. This is useful for nodes that are restarted
|
96 | asynchronously.
|
97 |
|
98 | ## Example Usage
|
99 |
|
100 | ### Simple
|
101 |
|
102 | ```js
|
103 | var heimdall = require('heimdall');
|
104 |
|
105 | function BroccoliNodeSchema() {
|
106 | this.builds = 0;
|
107 | }
|
108 |
|
109 |
|
110 | heimdall.node('broccoli', function () {
|
111 | heimdall.node('node:babel', BroccoliNodeSchema, function (h) {
|
112 | h.builds++;
|
113 |
|
114 | heimdall.node('node:persistent-filter', BroccoliNodeSchema, function (h) {
|
115 | h.builds++;
|
116 | });
|
117 |
|
118 | heimdall.node('node:caching-writer', BroccoliNodeSchema, function (h) {
|
119 | h.builds++;
|
120 | });
|
121 | });
|
122 | });
|
123 |
|
124 | ```
|
125 |
|
126 | ```json
|
127 | {
|
128 | "nodes": [{
|
129 | "id": 0,
|
130 | "name": "broccoli",
|
131 | "stats": {
|
132 | "cpu": {
|
133 | "self": 10,
|
134 | },
|
135 | },
|
136 | "children": {
|
137 | "start": [1],
|
138 | "end": [1],
|
139 | },
|
140 | }, {
|
141 | "id": 1,
|
142 | "name": "node:babel",
|
143 | "stats": {
|
144 | "builds": 1,
|
145 | "cpu": {
|
146 | "self": 20,
|
147 | },
|
148 | },
|
149 | "children": {
|
150 | "start": [2, 3],
|
151 | "end": [2, 3],
|
152 | },
|
153 | }, {
|
154 | "id": 2,
|
155 | "name": "node:persistent-filter",
|
156 | "stats": {
|
157 | "builds": 1,
|
158 | "cpu": {
|
159 | "self": 30,
|
160 | },
|
161 | },
|
162 | }, {
|
163 | "id": 3,
|
164 | "name": "node:caching-writer",
|
165 | "stats": {
|
166 | "builds": 1,
|
167 | "cpu": {
|
168 | "self": 40,
|
169 | },
|
170 | },
|
171 | }],
|
172 | }
|
173 | ```
|
174 |
|
175 | ### With Monitors
|
176 |
|
177 | ```js
|
178 | var heimdall = require('heimdall');
|
179 | var fs = require('fs');
|
180 |
|
181 | var origLstatSync = fs.lstatSync;
|
182 | var origMkdirSync = fs.mkdirSync;
|
183 |
|
184 | heimdall.registerMonitor('fs', function FSSchema() {
|
185 | this.lstatCount = 0;
|
186 | this.mkdirCount = 0;
|
187 | });
|
188 |
|
189 | fs.lstatSync = function () {
|
190 | heimdall.statsFor('fs').lstatCount++;
|
191 | return origLstatSync.apply(fs, arguments);
|
192 | }
|
193 |
|
194 | fs.mkdirSync = function () {
|
195 | heimdall.statsFor('fs').mkdirCount++;
|
196 | return origMkdirSync.apply(fs, arguments);
|
197 | }
|
198 |
|
199 |
|
200 | function BroccoliNodeSchema() {
|
201 | this.builds = 0;
|
202 | }
|
203 |
|
204 |
|
205 | heimdall.node('broccoli', function () {
|
206 | heimdall.node('node:babel', BroccoliNodeSchema, function (h) {
|
207 | h.builds++;
|
208 |
|
209 | heimdall.node('node:persistent-filter', BroccoliNodeSchema, function (h) {
|
210 | h.builds++;
|
211 | fs.mkdirSync('./tmp');
|
212 | });
|
213 |
|
214 | heimdall.node('node:caching-writer', BroccoliNodeSchema, function (h) {
|
215 | h.builds++;
|
216 | fs.lstatSync('./tmp');
|
217 | });
|
218 | });
|
219 | });
|
220 |
|
221 | ```
|
222 |
|
223 | ```json
|
224 | {
|
225 | "nodes": [{
|
226 | "id": 0,
|
227 | "name": "broccoli",
|
228 | "stats": {
|
229 | "cpu": {
|
230 | "self": 10,
|
231 | },
|
232 | "fs": {
|
233 | "lstatCount": 0,
|
234 | "mkdirCount": 0,
|
235 | },
|
236 | },
|
237 | "children": {
|
238 | "start": [1],
|
239 | "end": [1],
|
240 | },
|
241 | }, {
|
242 | "id": 1,
|
243 | "name": "node:babel",
|
244 | "stats": {
|
245 | "builds": 1,
|
246 | "cpu": {
|
247 | "self": 20,
|
248 | },
|
249 | "fs": {
|
250 | "lstatCount": 0,
|
251 | "mkdirCount": 0,
|
252 | },
|
253 | },
|
254 | "children": {
|
255 | "start": [2, 3],
|
256 | "end": [2, 3],
|
257 | },
|
258 | }, {
|
259 | "id": 2,
|
260 | "name": "node:persistent-filter",
|
261 | "stats": {
|
262 | "builds": 1,
|
263 | "cpu": {
|
264 | "self": 30,
|
265 | },
|
266 | "fs": {
|
267 | "lstatCount": 0,
|
268 | "mkdirCount": 1,
|
269 | },
|
270 | },
|
271 | }, {
|
272 | "id": 3,
|
273 | "name": "node:caching-writer",
|
274 | "stats": {
|
275 | "builds": 1,
|
276 | "cpu": {
|
277 | "self": 40,
|
278 | },
|
279 | "fs": {
|
280 | "lstatCount": 1,
|
281 | "mkdirCount": 0,
|
282 | },
|
283 | },
|
284 | }],
|
285 | }
|
286 | ```
|