profiler-md 0.8.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli/index.mjs +22206 -13852
- package/dist/index.d.mts +2677 -787
- package/dist/index.js +2 -2
- package/dist/man/profiler-md.1 +150 -0
- package/dist/node/index.mjs +2 -0
- package/docs/CLAUDE.md +22 -0
- package/docs/api.md +51 -11
- package/docs/formats/ghc-eventlog.md +6 -4
- package/docs/formats/ghc-json-profile.md +1 -1
- package/docs/formats/hprof.md +1 -2
- package/docs/formats/jfr.md +1 -1
- package/docs/formats/jsc-heap-snapshot.md +9 -8
- package/docs/formats/memray.md +9 -14
- package/docs/formats/perf.md +24 -34
- package/docs/formats/pprof.md +6 -4
- package/docs/formats/speedscope.md +3 -3
- package/docs/formats/systing.md +1 -1
- package/docs/formats/trace-event.md +20 -0
- package/docs/formats/v8-cpu-profile.md +1 -1
- package/docs/formats/v8-heap-profile.md +5 -6
- package/docs/formats/v8-heap-snapshot.md +10 -9
- package/docs/formats/webkit-timeline-recording.md +2 -3
- package/docs/languages/c.md +99 -45
- package/docs/languages/elixir.md +4 -3
- package/docs/languages/fortran.md +10 -9
- package/docs/languages/haskell.md +1 -1
- package/docs/languages/java.md +43 -6
- package/docs/languages/javascript.md +107 -3
- package/docs/languages/nix.md +56 -0
- package/docs/languages/python.md +87 -30
- package/docs/languages/swift.md +11 -10
- package/docs/languages/zig.md +45 -47
- package/package.json +53 -34
- package/readme.md +368 -174
- package/skills/profile-optimize/SKILL.md +259 -133
package/dist/index.d.mts
CHANGED
|
@@ -1,77 +1,63 @@
|
|
|
1
1
|
import { RawSourceMap as SourceMap, SourceMapConsumer } from "source-map-js";
|
|
2
|
-
|
|
2
|
+
type DeepReadonly<T> = T extends Map<infer K, infer V> ? ReadonlyMap<K, DeepReadonly<V>> : T extends Set<infer V> ? ReadonlySet<DeepReadonly<V>> : T extends TypedArray ? Readonly<T> : T extends (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]>; } : T;
|
|
3
3
|
type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float16Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
|
|
4
4
|
/**
|
|
5
|
-
*
|
|
6
|
-
*
|
|
5
|
+
* Receives a conversion's diagnostics, one message per call.
|
|
6
|
+
*
|
|
7
|
+
* Only defined methods are called, so `console` qualifies as a logger, and so
|
|
8
|
+
* does `{ warn: console.warn }`.
|
|
7
9
|
*/
|
|
8
|
-
type
|
|
9
|
-
//#endregion
|
|
10
|
-
//#region src/location.d.ts
|
|
11
|
-
/** A source reference, potentially with line and column information. */
|
|
12
|
-
type SourceLocation = SourceReference & {
|
|
13
|
-
/** The 1-based line number in the referenced source. */
|
|
14
|
-
line?: number;
|
|
15
|
-
/** The 1-based column number in the referenced source. */
|
|
16
|
-
column?: number;
|
|
17
|
-
};
|
|
18
|
-
/** A reference to where a function is defined: a file or a logical name. */
|
|
19
|
-
type SourceReference = FileReference | LogicalReference;
|
|
20
|
-
type FileReference = {
|
|
21
|
-
type: `absolute`;
|
|
22
|
-
url: URL;
|
|
23
|
-
} | {
|
|
24
|
-
type: `relative`;
|
|
25
|
-
path: string;
|
|
26
|
-
};
|
|
10
|
+
type Logger = Partial<Record<Exclude<LogLevel, `none`>, (message: string) => void>>;
|
|
27
11
|
/**
|
|
28
|
-
*
|
|
29
|
-
* `
|
|
12
|
+
* The verbosity of a conversion's diagnostics, from `none` (the default) to
|
|
13
|
+
* `debug`. A level enables its own messages and every level before it.
|
|
30
14
|
*/
|
|
31
|
-
type
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
};
|
|
35
|
-
type SourceLocationInput = ({
|
|
36
|
-
type: `file`;
|
|
37
|
-
/** A string parseable into a {@link URL} or file path. */
|
|
38
|
-
urlOrPath: string;
|
|
39
|
-
} | {
|
|
40
|
-
type: `logical`;
|
|
41
|
-
/**
|
|
42
|
-
* The name of a class, module, namespace, assembly, or native library.
|
|
43
|
-
*/
|
|
44
|
-
name: string;
|
|
45
|
-
}) & {
|
|
46
|
-
/** The 1-based line number in the referenced source. */
|
|
47
|
-
line?: number;
|
|
48
|
-
/** The 1-based column number in the referenced source. */
|
|
49
|
-
column?: number;
|
|
50
|
-
};
|
|
51
|
-
//#endregion
|
|
52
|
-
//#region src/modalities/metric.d.ts
|
|
53
|
-
/** Phrases that can be used in prose related to a metric. */
|
|
54
|
-
type MetricPhrases = {
|
|
55
|
-
/** A noun to use in headings, like "CPU", "heap", etc. */
|
|
56
|
-
titleNoun: string;
|
|
57
|
-
/** A noun to use in columns like "time", "size", etc. */
|
|
58
|
-
columnNoun: string;
|
|
59
|
-
/** A verb to use in prose like "took", "allocated", etc. */
|
|
60
|
-
pastTenseVerb: string;
|
|
61
|
-
/** A verb phrase to use in prose like "time spent", "bytes allocated", etc. */
|
|
62
|
-
pastParticipleVerbPhrase: string;
|
|
63
|
-
};
|
|
15
|
+
type LogLevel = (typeof LOG_LEVELS)[number];
|
|
16
|
+
/** Every {@link LogLevel}, least to most verbose. */
|
|
17
|
+
declare const LOG_LEVELS: readonly ["none", "error", "warn", "info", "debug"];
|
|
64
18
|
/**
|
|
65
|
-
*
|
|
19
|
+
* The category of code a function originated from.
|
|
66
20
|
*
|
|
67
|
-
* A
|
|
68
|
-
*
|
|
69
|
-
*
|
|
70
|
-
*
|
|
71
|
-
*
|
|
21
|
+
* A closed set, so a category names the same thing whichever origin wrote the
|
|
22
|
+
* input and formatting can partition by it. The first three record where the
|
|
23
|
+
* code came from, the next two what the profiler could determine about a frame
|
|
24
|
+
* with no source file, and the rest name a runtime activity.
|
|
25
|
+
*
|
|
26
|
+
* These boundaries decide most assignments:
|
|
27
|
+
*
|
|
28
|
+
* - `stdlib` requires positive evidence that the code is the language's or
|
|
29
|
+
* runtime's own library: a standard-library path, module specifier,
|
|
30
|
+
* namespace, or package prefix. A missing source file is never evidence for
|
|
31
|
+
* `stdlib`
|
|
32
|
+
* - `native` is compiled code the profiler attributed to no source file, plus
|
|
33
|
+
* code located in a shared library or in a runtime's own C/C++ sources.
|
|
34
|
+
* `unknown` is a frame the profiler could not identify, a weaker claim,
|
|
35
|
+
* because the code may be a function in the profiled language
|
|
36
|
+
* - `compiler` is the runtime producing executable code, and `jit` is a frame
|
|
37
|
+
* executing code the runtime generated. Where a frame both executes generated
|
|
38
|
+
* code and does the work of a named activity, the activity takes precedence,
|
|
39
|
+
* so a garbage collection write barrier compiled inline is
|
|
40
|
+
* `garbage-collector`
|
|
72
41
|
*/
|
|
73
|
-
type
|
|
74
|
-
|
|
42
|
+
type FunctionCategory = (typeof FUNCTION_CATEGORIES)[number];
|
|
43
|
+
declare const FUNCTION_CATEGORIES: readonly ["ours", "third-party", "stdlib", "native", "unknown", "garbage-collector", "compiler", "jit", "regexp", "kernel", "idle"];
|
|
44
|
+
/**
|
|
45
|
+
* Records why a parse used only part of its input, so the pipeline warns about
|
|
46
|
+
* the partial result, or rejects an input that produced no records.
|
|
47
|
+
*/
|
|
48
|
+
type RecordTally = {
|
|
49
|
+
/**
|
|
50
|
+
* Records that the parser skipped `count` records of `unit` (e.g. `sample`)
|
|
51
|
+
* for `reason`, a participle phrase (e.g. `referencing a missing node`). A
|
|
52
|
+
* `count` of `0` records nothing.
|
|
53
|
+
*/
|
|
54
|
+
skipped: (unit: string, reason: string, count?: number) => void;
|
|
55
|
+
/**
|
|
56
|
+
* Records that the input ends before `missing` (e.g.
|
|
57
|
+
* `the end-of-data marker`), which a complete input contains.
|
|
58
|
+
*/
|
|
59
|
+
endsBefore: (missing: string) => void;
|
|
60
|
+
};
|
|
75
61
|
type Metric = ({
|
|
76
62
|
type: `time`;
|
|
77
63
|
/** The number of milliseconds this time unit takes up. */
|
|
@@ -95,47 +81,79 @@ type Metric = ({
|
|
|
95
81
|
proseUnit: string;
|
|
96
82
|
}) & {
|
|
97
83
|
phrases: MetricPhrases;
|
|
98
|
-
/** Which direction of change in this metric's value is an improvement. */
|
|
99
84
|
improvement: MetricImprovement;
|
|
100
85
|
};
|
|
101
|
-
//#endregion
|
|
102
|
-
//#region src/modalities/stack-frame.d.ts
|
|
103
86
|
/**
|
|
104
|
-
*
|
|
87
|
+
* Which direction of change in a metric's value is an improvement.
|
|
105
88
|
*
|
|
106
|
-
*
|
|
107
|
-
*
|
|
89
|
+
* A profiler records what a program consumed, so a smaller value is a better
|
|
90
|
+
* one for every unit this package recognizes. `increase` is for a metric
|
|
91
|
+
* measuring something a program produces, and `unknown` for a metric whose
|
|
92
|
+
* profiler named a unit this package cannot classify, where a diff states the
|
|
93
|
+
* direction of each change and calls neither better nor worse.
|
|
94
|
+
*/
|
|
95
|
+
type MetricImprovement = `decrease` | `increase` | `unknown`;
|
|
96
|
+
type MetricPhrases = {
|
|
97
|
+
/** A noun to use in headings, like "CPU", "heap", etc. */
|
|
98
|
+
titleNoun: string;
|
|
99
|
+
/** A noun to use in columns like "time", "size", etc. */
|
|
100
|
+
columnNoun: string;
|
|
101
|
+
/** A verb to use in prose like "took", "allocated", etc. */
|
|
102
|
+
pastTenseVerb: string;
|
|
103
|
+
/** A verb phrase to use in prose like "time spent", "bytes allocated", etc. */
|
|
104
|
+
pastParticipleVerbPhrase: string;
|
|
105
|
+
};
|
|
106
|
+
/**
|
|
107
|
+
* A frame record: a parser's record of one function reference, with each
|
|
108
|
+
* position the profiler recorded stored under its semantic.
|
|
108
109
|
*
|
|
109
|
-
* {@link
|
|
110
|
-
*
|
|
110
|
+
* Its {@link name} and {@link definition} identify the function, so frame
|
|
111
|
+
* records sharing them are the same function. {@link executing} is never part
|
|
112
|
+
* of the identity, and the leaf frame's executing line feeds its function's
|
|
113
|
+
* per-line breakdown.
|
|
111
114
|
*
|
|
112
|
-
* A
|
|
113
|
-
*
|
|
114
|
-
*
|
|
115
|
+
* A parser fills each slot from what the profiler records there, per the
|
|
116
|
+
* profiler's own source or spec, and leaves a slot the profiler doesn't record
|
|
117
|
+
* empty. It NEVER infers one position from another. The resolved origin's
|
|
118
|
+
* `normalizeStackFrame` then splits out the source and positions for variants
|
|
119
|
+
* that pack them into the frame string. It also moves a position that a
|
|
120
|
+
* profiler records under a different semantic into its slot.
|
|
115
121
|
*/
|
|
116
122
|
type StackFrame = {
|
|
117
|
-
/** The function's name, if known. */
|
|
118
123
|
name?: string;
|
|
119
|
-
/** Where the function was defined, if known. */
|
|
120
|
-
location?: SourceLocationInput;
|
|
121
124
|
/**
|
|
122
|
-
*
|
|
125
|
+
* Where the function is defined, if known: the source it is in and, when
|
|
126
|
+
* the profiler records it, the position within that source.
|
|
123
127
|
*
|
|
124
|
-
*
|
|
125
|
-
*
|
|
126
|
-
* per-line breakdown. Never a function-identity component.
|
|
128
|
+
* The position is inside the definition because it is a position within
|
|
129
|
+
* that source, so it can't exist without one.
|
|
127
130
|
*/
|
|
128
|
-
|
|
131
|
+
definition?: UnresolvedSourceReference & {
|
|
132
|
+
position?: SourcePosition;
|
|
133
|
+
};
|
|
134
|
+
/**
|
|
135
|
+
* The position this frame was at when recorded, if known.
|
|
136
|
+
*
|
|
137
|
+
* It is meaningful without a {@link definition}, because the line is still a
|
|
138
|
+
* line of the function.
|
|
139
|
+
*/
|
|
140
|
+
executing?: SourcePosition;
|
|
141
|
+
/**
|
|
142
|
+
* Where this function was called: a position in the caller's source, if the
|
|
143
|
+
* profiler recorded it.
|
|
144
|
+
*
|
|
145
|
+
* Identifies and locates the function only under an origin declaring
|
|
146
|
+
* `call-site` identity (`OriginSpec.functionIdentity`), for a profiler that
|
|
147
|
+
* records no other position.
|
|
148
|
+
*/
|
|
149
|
+
callSite?: UnresolvedSourceReference & {
|
|
150
|
+
position: SourcePosition;
|
|
151
|
+
};
|
|
129
152
|
};
|
|
130
|
-
//#endregion
|
|
131
|
-
//#region src/modalities/call-graph/type.d.ts
|
|
132
153
|
/**
|
|
133
154
|
* An input parsed as a weighted call graph: functions with recorded self costs
|
|
134
|
-
* plus caller→callee arcs with recorded call counts and
|
|
155
|
+
* plus caller→callee arcs with recorded call counts and total costs. The
|
|
135
156
|
* formats it comes from record no call stacks.
|
|
136
|
-
*
|
|
137
|
-
* Origin detection, frame normalization, and aggregation run uniformly from
|
|
138
|
-
* here, so a format's only custom logic is parsing into this.
|
|
139
157
|
*/
|
|
140
158
|
type CallGraph = {
|
|
141
159
|
type: `call-graph`;
|
|
@@ -147,41 +165,36 @@ type CallGraph = {
|
|
|
147
165
|
*/
|
|
148
166
|
metrics: Metric[];
|
|
149
167
|
/**
|
|
150
|
-
* Each function
|
|
151
|
-
* with {@link CallGraph.functions}. The aggregator
|
|
152
|
-
*
|
|
153
|
-
* functions whose normalized frames share an identity.
|
|
168
|
+
* Each function's frame record (name and definition location),
|
|
169
|
+
* index-aligned with {@link CallGraph.functions}. The aggregator merges
|
|
170
|
+
* functions whose normalized frame records share an identity.
|
|
154
171
|
*/
|
|
155
172
|
frames: StackFrame[];
|
|
156
|
-
/** The graph's
|
|
173
|
+
/** The graph's functions, indexed by {@link CallGraphArc.callee}. */
|
|
157
174
|
functions: CallGraphFunction[];
|
|
158
175
|
};
|
|
159
|
-
/** A function node in a parsed call graph. */
|
|
160
176
|
type CallGraphFunction = {
|
|
161
177
|
/** The cost recorded directly in the function's body, per metric. */
|
|
162
178
|
selfValues: number[];
|
|
163
179
|
/** Each 1-based line to the self cost recorded at that line, per metric. */
|
|
164
180
|
lineToValues: Map<number, number[]>;
|
|
165
|
-
|
|
166
|
-
calls: CallGraphCall[];
|
|
181
|
+
arcs: CallGraphArc[];
|
|
167
182
|
};
|
|
168
|
-
/** One caller→callee arc: the recorded call count and
|
|
169
|
-
type
|
|
183
|
+
/** One caller→callee arc: the recorded call count and total cost. */
|
|
184
|
+
type CallGraphArc = {
|
|
170
185
|
/** The called function's index in {@link CallGraph.functions}. */
|
|
171
186
|
callee: number;
|
|
172
187
|
/** The recorded number of calls, or `0` when the format records none. */
|
|
173
188
|
callCount: number;
|
|
174
189
|
/**
|
|
175
|
-
* The calls'
|
|
190
|
+
* The calls' total cost per metric: cost recorded in the callee and its
|
|
176
191
|
* callees during these calls.
|
|
177
192
|
*/
|
|
178
193
|
totalValues: number[];
|
|
179
194
|
};
|
|
180
|
-
//#endregion
|
|
181
|
-
//#region src/modalities/call-stack-profile/type.d.ts
|
|
182
195
|
/**
|
|
183
|
-
* A profile parsed into the uniform structure containing the distinct
|
|
184
|
-
* and the observations that reference them.
|
|
196
|
+
* A profile parsed into the uniform structure containing the distinct frame
|
|
197
|
+
* records and the observations that reference them.
|
|
185
198
|
*
|
|
186
199
|
* A format that yields several profiles returns one of these per profile,
|
|
187
200
|
* typically sharing the same {@link CallStackProfile.frames} array reference.
|
|
@@ -189,17 +202,17 @@ type CallGraphCall = {
|
|
|
189
202
|
type CallStackProfile = {
|
|
190
203
|
type: `call-stack-profile`;
|
|
191
204
|
/**
|
|
192
|
-
* The
|
|
193
|
-
*
|
|
194
|
-
*
|
|
205
|
+
* The name the format's own metadata gives the writer (e.g. a recorder's
|
|
206
|
+
* event-type definitions or a writer's self-identification field), set by a
|
|
207
|
+
* parser when that metadata identifies one. It is an origin's ID or a name
|
|
208
|
+
* the origin's {@link OriginSpec.isOriginHint} accepts.
|
|
195
209
|
*
|
|
196
|
-
*
|
|
197
|
-
*
|
|
198
|
-
* marker entry overrides it.
|
|
210
|
+
* Detection resolves to the origin it names over any marker entry, because the
|
|
211
|
+
* metadata is the writer identifying itself. A specified origin ignores it.
|
|
199
212
|
*/
|
|
200
213
|
originHint?: string;
|
|
201
214
|
/**
|
|
202
|
-
* The distinct
|
|
215
|
+
* The distinct frame records the observations reference.
|
|
203
216
|
*
|
|
204
217
|
* A {@link Observation.frameIndices} entry is an index into this list.
|
|
205
218
|
*/
|
|
@@ -224,11 +237,11 @@ type CallStackProfile = {
|
|
|
224
237
|
*/
|
|
225
238
|
lineMetrics?: Iterable<ObservationLineMetrics>;
|
|
226
239
|
};
|
|
227
|
-
/**
|
|
240
|
+
/** A call stack, a value per metric, and how many occurrences it stands for. */
|
|
228
241
|
type Observation = {
|
|
229
242
|
/**
|
|
230
|
-
* An identifier for this
|
|
231
|
-
* format that references stacks by a constant-pool index).
|
|
243
|
+
* An identifier for this observation's call stack, if the caller has one
|
|
244
|
+
* (e.g. a format that references call stacks by a constant-pool index).
|
|
232
245
|
*
|
|
233
246
|
* When provided, the aggregator memoizes the resolved call stack by this ID.
|
|
234
247
|
*/
|
|
@@ -237,21 +250,27 @@ type Observation = {
|
|
|
237
250
|
values: number[];
|
|
238
251
|
/** The call stack as indices into {@link CallStackProfile.frames}. */
|
|
239
252
|
frameIndices: number[];
|
|
240
|
-
/** The 1-based line number the leaf frame was at, if known. */
|
|
241
|
-
line?: number;
|
|
242
253
|
/**
|
|
243
|
-
*
|
|
254
|
+
* The 1-based line number the leaf frame was at, if known. Overrides the
|
|
255
|
+
* leaf frame's {@link StackFrame.executing} line.
|
|
256
|
+
*/
|
|
257
|
+
executingLine?: number;
|
|
258
|
+
/**
|
|
259
|
+
* Whether the profiler dropped the call stack's outermost frames, so its
|
|
260
|
+
* last frame is not where the program's execution started. Set only where
|
|
261
|
+
* the format records it, defaulting to `false`. A root frame the
|
|
262
|
+
* origin recognizes as a truncation marker also sets it.
|
|
263
|
+
*/
|
|
264
|
+
truncated?: boolean;
|
|
265
|
+
/**
|
|
266
|
+
* How many identical occurrences this observation stands for, defaulting to
|
|
267
|
+
* `1`.
|
|
244
268
|
*
|
|
245
269
|
* {@link CallStackProfile.countMetric} states what one of them is.
|
|
246
270
|
*/
|
|
247
271
|
count?: number;
|
|
248
272
|
};
|
|
249
|
-
/**
|
|
250
|
-
* Per-line metrics for one frame, added after the observations.
|
|
251
|
-
*
|
|
252
|
-
* Used by formats that report a function's self time broken down by line
|
|
253
|
-
* separately from its observations.
|
|
254
|
-
*/
|
|
273
|
+
/** Per-line metrics for one frame. */
|
|
255
274
|
type ObservationLineMetrics = {
|
|
256
275
|
/** The frame's index into {@link CallStackProfile.frames}. */
|
|
257
276
|
frame: number;
|
|
@@ -262,8 +281,6 @@ type ObservationLineMetrics = {
|
|
|
262
281
|
values: number[];
|
|
263
282
|
}[];
|
|
264
283
|
};
|
|
265
|
-
//#endregion
|
|
266
|
-
//#region src/modalities/heap-snapshot/graph.d.ts
|
|
267
284
|
/**
|
|
268
285
|
* A successor and predecessor graph between heap snapshot nodes in CSR format.
|
|
269
286
|
*
|
|
@@ -271,67 +288,34 @@ type ObservationLineMetrics = {
|
|
|
271
288
|
*/
|
|
272
289
|
type NodeAdjacencyGraph = {
|
|
273
290
|
/**
|
|
274
|
-
*
|
|
275
|
-
*
|
|
276
|
-
* {@link NodeAdjacencyGraph.
|
|
277
|
-
*
|
|
278
|
-
*
|
|
279
|
-
* Node `i`'s successor ordinals occupy:
|
|
280
|
-
* `[offsetToSuccessorOrdinal[i], offsetToSuccessorOrdinal[i + 1])`.
|
|
281
|
-
*
|
|
282
|
-
* Node `i`'s successor edges occupy:
|
|
283
|
-
* `[offsetToSuccessorEdgeIndex[i], offsetToSuccessorEdgeIndex[i + 1])`.
|
|
291
|
+
* Node `i`'s successors occupy
|
|
292
|
+
* `[ordinalToSuccessorStartOffset[i], ordinalToSuccessorStartOffset[i + 1])`
|
|
293
|
+
* in {@link NodeAdjacencyGraph.offsetToSuccessorOrdinal} and
|
|
294
|
+
* {@link NodeAdjacencyGraph.offsetToSuccessorEdgeIndex}.
|
|
284
295
|
*/
|
|
285
296
|
ordinalToSuccessorStartOffset: Int32Array;
|
|
286
|
-
/**
|
|
287
|
-
* Successor ordinals, packed contiguously and indexed via
|
|
288
|
-
* {@link NodeAdjacencyGraph.ordinalToSuccessorStartOffset}.
|
|
289
|
-
*/
|
|
290
297
|
offsetToSuccessorOrdinal: Int32Array;
|
|
291
|
-
/**
|
|
292
|
-
* Successor edge indices, packed contiguously and indexed via
|
|
293
|
-
* {@link NodeAdjacencyGraph.ordinalToSuccessorStartOffset}.
|
|
294
|
-
*/
|
|
295
298
|
offsetToSuccessorEdgeIndex: Int32Array;
|
|
296
299
|
/**
|
|
297
|
-
*
|
|
298
|
-
*
|
|
299
|
-
* {@link NodeAdjacencyGraph.
|
|
300
|
-
*
|
|
301
|
-
*
|
|
302
|
-
* Node `i`'s predecessor ordinals occupy:
|
|
303
|
-
* `[offsetToPredecessorOrdinal[i], offsetToPredecessorOrdinal[i + 1])`.
|
|
304
|
-
*
|
|
305
|
-
* Node `i`'s predecessor edges occupy:
|
|
306
|
-
* `[offsetToPredecessorEdgeIndex[i], offsetToPredecessorEdgeIndex[i + 1])`.
|
|
300
|
+
* Node `i`'s predecessors occupy
|
|
301
|
+
* `[ordinalToPredecessorStartOffset[i], ordinalToPredecessorStartOffset[i + 1])`
|
|
302
|
+
* in {@link NodeAdjacencyGraph.offsetToPredecessorOrdinal} and
|
|
303
|
+
* {@link NodeAdjacencyGraph.offsetToPredecessorEdgeIndex}.
|
|
307
304
|
*/
|
|
308
305
|
ordinalToPredecessorStartOffset: Int32Array;
|
|
309
|
-
/**
|
|
310
|
-
* Predecessor ordinals, packed contiguously and indexed via
|
|
311
|
-
* {@link NodeAdjacencyGraph.ordinalToPredecessorStartOffset}.
|
|
312
|
-
*/
|
|
313
306
|
offsetToPredecessorOrdinal: Int32Array;
|
|
314
|
-
/**
|
|
315
|
-
* Predecessor edge indices, packed contiguously and indexed via
|
|
316
|
-
* {@link NodeAdjacencyGraph.ordinalToPredecessorStartOffset}.
|
|
317
|
-
*/
|
|
318
307
|
offsetToPredecessorEdgeIndex: Int32Array;
|
|
319
308
|
};
|
|
320
|
-
//#endregion
|
|
321
|
-
//#region src/modalities/heap-snapshot/type.d.ts
|
|
322
309
|
/**
|
|
323
|
-
* A heap snapshot
|
|
324
|
-
* adjacency graph and each node's unresolved category.
|
|
310
|
+
* A parsed heap snapshot.
|
|
325
311
|
*
|
|
326
312
|
* A format that yields several snapshots returns one of these per snapshot.
|
|
327
313
|
*/
|
|
328
314
|
type HeapSnapshot = {
|
|
329
315
|
type: `heap-snapshot`;
|
|
330
|
-
/** Number of nodes in the snapshot. */
|
|
331
316
|
nodeCount: number;
|
|
332
|
-
/**
|
|
317
|
+
/** The edges pointing at a node of the snapshot, retaining it or not. */
|
|
333
318
|
edgeCount: number;
|
|
334
|
-
/** The successor and predecessor graph between the snapshot's nodes. */
|
|
335
319
|
nodeAdjacencyGraph: NodeAdjacencyGraph;
|
|
336
320
|
/** Bytes allocated directly for the node. */
|
|
337
321
|
selfSizeOf: (nodeOrdinal: number) => number;
|
|
@@ -341,15 +325,12 @@ type HeapSnapshot = {
|
|
|
341
325
|
*/
|
|
342
326
|
nodes: Iterable<HeapSnapshotNode>;
|
|
343
327
|
/**
|
|
344
|
-
*
|
|
345
|
-
*
|
|
346
|
-
*/
|
|
347
|
-
formatEdgeLabel: (retainerOrdinal: number, edgeIndex: number, options: FormattingProfileToMdOptions) => string;
|
|
348
|
-
/**
|
|
349
|
-
* Formats a node label, which is computed lazily at formatting time, so it
|
|
350
|
-
* receives the resolved formatting options.
|
|
328
|
+
* How the node at {@link retainerOrdinal} refers to another through the edge
|
|
329
|
+
* at {@link edgeIndex}, whose meaning is the format's own.
|
|
351
330
|
*/
|
|
352
|
-
|
|
331
|
+
retainerEdgeOf: (retainerOrdinal: number, edgeIndex: number) => RetainerEdge;
|
|
332
|
+
/** The node as a retainer path step or a retained node listing shows it. */
|
|
333
|
+
retainerOf: (nodeOrdinal: number) => RetainerNode;
|
|
353
334
|
/** Whether the node is a bookkeeping node that never points to user code. */
|
|
354
335
|
isInternalNode: (nodeOrdinal: number) => boolean;
|
|
355
336
|
/**
|
|
@@ -360,21 +341,28 @@ type HeapSnapshot = {
|
|
|
360
341
|
unresolvedCategoryOf: (nodeOrdinal: number) => UnresolvedHeapSnapshotNodeCategory;
|
|
361
342
|
};
|
|
362
343
|
/**
|
|
363
|
-
*
|
|
364
|
-
*
|
|
365
|
-
* A closed set, so a category names the same thing whichever engine wrote the
|
|
366
|
-
* snapshot and formatting can partition by it. V8 declares its own names for
|
|
367
|
-
* most of these in `meta.node_types`. JavaScriptCore derives them from a node's
|
|
368
|
-
* flags. Where an engine's name is its own, the category takes the name every
|
|
369
|
-
* language shares: `internal` covers V8's `hidden` and JavaScriptCore's
|
|
370
|
-
* `internal`, `function` covers V8's `closure` whether or not the function
|
|
371
|
-
* captures anything, and `big-number` covers V8's `bigint` along with any
|
|
372
|
-
* arbitrary-precision number a runtime allocates on the heap, such as Julia's
|
|
373
|
-
* `BigFloat`.
|
|
344
|
+
* Every node contributes to its category's stats. A node with a `type` also
|
|
345
|
+
* aggregates into that type's entities.
|
|
374
346
|
*/
|
|
375
|
-
type
|
|
376
|
-
|
|
377
|
-
|
|
347
|
+
type HeapSnapshotNode = UnresolvedHeapSnapshotNodeCategory & ({
|
|
348
|
+
type?: undefined;
|
|
349
|
+
} | {
|
|
350
|
+
type: `constructor`;
|
|
351
|
+
name: string;
|
|
352
|
+
location?: SourceLocation;
|
|
353
|
+
/**
|
|
354
|
+
* The file reference the {@link name} parses as, when it is URL-shaped.
|
|
355
|
+
*/
|
|
356
|
+
nameLocation?: FileReference;
|
|
357
|
+
} | {
|
|
358
|
+
type: `function`;
|
|
359
|
+
name: string;
|
|
360
|
+
location?: SourceLocation;
|
|
361
|
+
} | {
|
|
362
|
+
type: `string`;
|
|
363
|
+
/** The (truncated) string value, if known. */
|
|
364
|
+
name?: string;
|
|
365
|
+
});
|
|
378
366
|
/**
|
|
379
367
|
* What a heap snapshot node holds, as the format categorized it, before the
|
|
380
368
|
* origin resolves it.
|
|
@@ -390,212 +378,356 @@ type UnresolvedHeapSnapshotNodeCategory = {
|
|
|
390
378
|
declaredType?: string;
|
|
391
379
|
};
|
|
392
380
|
/**
|
|
393
|
-
*
|
|
381
|
+
* What a heap snapshot node holds.
|
|
394
382
|
*
|
|
395
|
-
*
|
|
396
|
-
*
|
|
383
|
+
* A closed set, so a category names the same thing whichever engine wrote the
|
|
384
|
+
* snapshot and formatting can partition by it. V8 declares its own names for
|
|
385
|
+
* most of these in `meta.node_types`. JavaScriptCore derives them from a node's
|
|
386
|
+
* flags. Where an engine's name is its own, the category takes the name every
|
|
387
|
+
* language shares: `internal` covers V8's `hidden` and JavaScriptCore's
|
|
388
|
+
* `internal`, `function` covers V8's `closure` whether or not the function
|
|
389
|
+
* captures anything, and `big-number` covers V8's `bigint` along with any
|
|
390
|
+
* arbitrary-precision number a runtime allocates on the heap, such as Julia's
|
|
391
|
+
* `BigFloat`.
|
|
397
392
|
*/
|
|
398
|
-
type
|
|
399
|
-
|
|
393
|
+
type HeapSnapshotNodeCategory = (typeof HEAP_SNAPSHOT_NODE_CATEGORIES)[number];
|
|
394
|
+
declare const HEAP_SNAPSHOT_NODE_CATEGORIES: readonly ["object", "array", "string", "concatenated-string", "sliced-string", "function", "code", "regexp", "number", "big-number", "symbol", "native", "object-shape", "internal", "synthetic", "unknown"];
|
|
395
|
+
/** How a retainer refers to the node it retains. */
|
|
396
|
+
type RetainerEdge = {
|
|
397
|
+
type: `property`;
|
|
398
|
+
name: string;
|
|
399
|
+
/** The file reference the {@link name} parses as, when it is URL-shaped. */
|
|
400
|
+
nameLocation?: FileReference;
|
|
400
401
|
} | {
|
|
401
|
-
type: `
|
|
402
|
-
/**
|
|
402
|
+
type: `element`;
|
|
403
|
+
/** Undefined when the format records an index no array can have. */
|
|
404
|
+
index: number | undefined;
|
|
405
|
+
} | {
|
|
406
|
+
/** An edge the format labels as neither a property nor an element. */
|
|
407
|
+
type: `labeled`;
|
|
408
|
+
label: string;
|
|
409
|
+
} | {
|
|
410
|
+
type: `unlabeled`;
|
|
411
|
+
};
|
|
412
|
+
type RetainerNode = {
|
|
413
|
+
/** The retainer's node ordinal. */
|
|
414
|
+
id: number;
|
|
403
415
|
name: string;
|
|
404
|
-
/** The
|
|
416
|
+
/** The file reference the {@link name} parses as, when it is URL-shaped. */
|
|
417
|
+
nameLocation?: FileReference;
|
|
405
418
|
location?: SourceLocation;
|
|
419
|
+
};
|
|
420
|
+
/**
|
|
421
|
+
* An input parsed as a trace: a chronological record of events, each a span
|
|
422
|
+
* with a duration or an instant with none, and of gauge readings.
|
|
423
|
+
*
|
|
424
|
+
* A format that yields several traces returns one of these per trace.
|
|
425
|
+
*/
|
|
426
|
+
type Trace = {
|
|
427
|
+
type: `trace`;
|
|
428
|
+
/** @see {@link CallStackProfile.originHint} */
|
|
429
|
+
originHint?: string;
|
|
406
430
|
/**
|
|
407
|
-
*
|
|
431
|
+
* How many milliseconds one unit of every start, time, duration, and CPU
|
|
432
|
+
* duration below takes up.
|
|
408
433
|
*/
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
/**
|
|
434
|
+
millisecondsPerTimeUnit: number;
|
|
435
|
+
/** The threads the events reference by index. */
|
|
436
|
+
threads: TraceThread[];
|
|
437
|
+
/**
|
|
438
|
+
* The events and readings as a lazily consumed iterable. A span follows the
|
|
439
|
+
* span it is nested in, at the position its {@link TraceSpan.parent} states,
|
|
440
|
+
* and precedes every later span outside that one.
|
|
441
|
+
*/
|
|
442
|
+
events: Iterable<TraceEvent | TraceReading>;
|
|
443
|
+
};
|
|
444
|
+
/**
|
|
445
|
+
* A thread events were recorded on, named as the Markdown shows it. The name
|
|
446
|
+
* includes the thread's process where the trace records several processes.
|
|
447
|
+
*/
|
|
448
|
+
type TraceThread = {
|
|
413
449
|
name: string;
|
|
414
|
-
/** The exact location where the function was defined. */
|
|
415
|
-
location?: SourceLocation;
|
|
416
|
-
} | {
|
|
417
|
-
type: `string`;
|
|
418
|
-
/** The (truncated) string value, if known. */
|
|
419
|
-
name?: string;
|
|
420
|
-
});
|
|
421
|
-
//#endregion
|
|
422
|
-
//#region src/formats/registry.d.ts
|
|
423
|
-
/** Every supported format's converter, keyed by format ID. */
|
|
424
|
-
declare const formatConverters: {
|
|
425
|
-
readonly callgrind: {
|
|
426
|
-
readonly title: "Callgrind";
|
|
427
|
-
readonly extension: "callgrind";
|
|
428
|
-
readonly languages: readonly ["c", "ruby"];
|
|
429
|
-
readonly fallbackOrigin: "valgrind";
|
|
430
|
-
readonly type: "binary";
|
|
431
|
-
readonly matches: (bytes: Uint8Array) => boolean;
|
|
432
|
-
readonly parse: (bytes: Uint8Array) => CallGraph[];
|
|
433
|
-
readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<CallGraph[]>;
|
|
434
|
-
};
|
|
435
|
-
readonly collapsed: {
|
|
436
|
-
readonly title: "Collapsed stacks";
|
|
437
|
-
readonly extension: "collapsed";
|
|
438
|
-
readonly languages: readonly ["elixir", "java", "php", "python", "ruby"];
|
|
439
|
-
readonly fallbackOrigin: "unknown";
|
|
440
|
-
readonly type: "binary";
|
|
441
|
-
readonly matches: (bytes: Uint8Array) => boolean;
|
|
442
|
-
readonly parse: (bytes: Uint8Array) => CallStackProfile[];
|
|
443
|
-
readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<CallStackProfile[]>;
|
|
444
|
-
};
|
|
445
|
-
readonly 'ghc-eventlog': {
|
|
446
|
-
readonly title: "GHC eventlog";
|
|
447
|
-
readonly extension: "eventlog";
|
|
448
|
-
readonly languages: readonly ["haskell"];
|
|
449
|
-
readonly fallbackOrigin: "ghc";
|
|
450
|
-
readonly type: "binary";
|
|
451
|
-
readonly matches: (bytes: Uint8Array) => boolean;
|
|
452
|
-
readonly parse: (bytes: Uint8Array) => CallStackProfile[];
|
|
453
|
-
readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<CallStackProfile[]>;
|
|
454
|
-
};
|
|
455
|
-
readonly 'ghc-json-profile': {
|
|
456
|
-
readonly title: "GHC JSON profile";
|
|
457
|
-
readonly extension: "prof.json";
|
|
458
|
-
readonly languages: readonly ["haskell"];
|
|
459
|
-
readonly fallbackOrigin: "ghc";
|
|
460
|
-
readonly type: "json";
|
|
461
|
-
readonly matches: (json: unknown) => boolean;
|
|
462
|
-
readonly parse: (json: unknown) => CallStackProfile[];
|
|
463
|
-
};
|
|
464
|
-
readonly hprof: {
|
|
465
|
-
readonly title: "HPROF";
|
|
466
|
-
readonly extension: "hprof";
|
|
467
|
-
readonly languages: readonly ["java"];
|
|
468
|
-
readonly fallbackOrigin: "jdk";
|
|
469
|
-
readonly type: "binary";
|
|
470
|
-
readonly matches: (bytes: Uint8Array) => boolean;
|
|
471
|
-
readonly parse: (bytes: Uint8Array) => HeapSnapshot[];
|
|
472
|
-
readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<HeapSnapshot[]>;
|
|
473
|
-
};
|
|
474
|
-
readonly jfr: {
|
|
475
|
-
readonly title: "JFR";
|
|
476
|
-
readonly extension: "jfr";
|
|
477
|
-
readonly languages: readonly ["java"];
|
|
478
|
-
readonly fallbackOrigin: "jdk";
|
|
479
|
-
readonly type: "binary";
|
|
480
|
-
readonly matches: (bytes: Uint8Array) => boolean;
|
|
481
|
-
readonly parse: (bytes: Uint8Array) => CallStackProfile[];
|
|
482
|
-
readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<CallStackProfile[]>;
|
|
483
|
-
};
|
|
484
|
-
readonly 'jsc-heap-snapshot': {
|
|
485
|
-
readonly title: "JSC heap snapshot";
|
|
486
|
-
readonly extension: "jsc-heap-snapshot.json";
|
|
487
|
-
readonly languages: readonly ["javascript"];
|
|
488
|
-
readonly fallbackOrigin: "safari";
|
|
489
|
-
readonly type: "json";
|
|
490
|
-
readonly matches: (json: unknown) => boolean;
|
|
491
|
-
readonly parse: (json: unknown) => HeapSnapshot[];
|
|
492
|
-
};
|
|
493
|
-
readonly memray: {
|
|
494
|
-
readonly title: "memray";
|
|
495
|
-
readonly extension: "memray.bin";
|
|
496
|
-
readonly languages: readonly ["python"];
|
|
497
|
-
readonly fallbackOrigin: "memray";
|
|
498
|
-
readonly type: "binary";
|
|
499
|
-
readonly matches: (bytes: Uint8Array) => boolean;
|
|
500
|
-
readonly parse: (input: Uint8Array) => CallStackProfile[];
|
|
501
|
-
readonly parseAsync: (stream: ReadableStream<Uint8Array<ArrayBufferLike>>) => Promise<CallStackProfile[]>;
|
|
502
|
-
};
|
|
503
|
-
readonly perf: {
|
|
504
|
-
readonly title: "perf.data";
|
|
505
|
-
readonly extension: "perf.data";
|
|
506
|
-
readonly languages: readonly ["c", "zig"];
|
|
507
|
-
readonly fallbackOrigin: "perf";
|
|
508
|
-
readonly type: "binary";
|
|
509
|
-
readonly matches: (bytes: Uint8Array) => boolean;
|
|
510
|
-
readonly parse: (bytes: Uint8Array) => CallStackProfile[];
|
|
511
|
-
readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<CallStackProfile[]>;
|
|
512
|
-
};
|
|
513
|
-
readonly pprof: {
|
|
514
|
-
readonly title: "pprof";
|
|
515
|
-
readonly extension: "pprof";
|
|
516
|
-
readonly languages: readonly ["c", "fortran", "go", "javascript", "julia", "ruby", "rust", "swift", "zig"];
|
|
517
|
-
readonly fallbackOrigin: "unknown";
|
|
518
|
-
readonly type: "binary";
|
|
519
|
-
readonly matches: (bytes: Uint8Array) => boolean;
|
|
520
|
-
readonly parse: (bytes: Uint8Array<ArrayBufferLike>) => CallStackProfile[];
|
|
521
|
-
readonly parseAsync: (stream: ReadableStream<Uint8Array<ArrayBufferLike>>) => Promise<CallStackProfile[]>;
|
|
522
|
-
};
|
|
523
|
-
readonly speedscope: {
|
|
524
|
-
readonly title: "Speedscope";
|
|
525
|
-
readonly extension: "speedscope.json";
|
|
526
|
-
readonly languages: readonly ["csharp", "php", "python", "ruby"];
|
|
527
|
-
readonly fallbackOrigin: "unknown";
|
|
528
|
-
readonly type: "json";
|
|
529
|
-
readonly matches: (json: unknown) => boolean;
|
|
530
|
-
readonly parse: (json: unknown) => CallStackProfile[];
|
|
531
|
-
};
|
|
532
|
-
readonly systing: {
|
|
533
|
-
readonly title: "systing";
|
|
534
|
-
readonly extension: "systing";
|
|
535
|
-
readonly languages: readonly ["c", "python", "rust"];
|
|
536
|
-
readonly fallbackOrigin: "systing";
|
|
537
|
-
readonly type: "binary";
|
|
538
|
-
readonly matches: (bytes: Uint8Array) => boolean;
|
|
539
|
-
readonly parse: (bytes: Uint8Array) => CallStackProfile[];
|
|
540
|
-
readonly parseAsync: (stream: ReadableStream<Uint8Array>) => Promise<CallStackProfile[]>;
|
|
541
|
-
};
|
|
542
|
-
readonly 'v8-cpu-profile': {
|
|
543
|
-
readonly title: "V8 CPU profile";
|
|
544
|
-
readonly extension: "cpuprofile";
|
|
545
|
-
readonly languages: readonly ["javascript"];
|
|
546
|
-
readonly fallbackOrigin: "chrome";
|
|
547
|
-
readonly type: "json";
|
|
548
|
-
readonly matches: (json: unknown) => boolean;
|
|
549
|
-
readonly parse: (json: unknown) => CallStackProfile[];
|
|
550
|
-
};
|
|
551
|
-
readonly 'v8-heap-profile': {
|
|
552
|
-
readonly title: "V8 heap profile";
|
|
553
|
-
readonly extension: "heapprofile";
|
|
554
|
-
readonly languages: readonly ["javascript"];
|
|
555
|
-
readonly fallbackOrigin: "chrome";
|
|
556
|
-
readonly type: "json";
|
|
557
|
-
readonly matches: (json: unknown) => boolean;
|
|
558
|
-
readonly parse: (json: unknown) => CallStackProfile[];
|
|
559
|
-
};
|
|
560
|
-
readonly 'v8-heap-snapshot': {
|
|
561
|
-
readonly title: "V8 heap snapshot";
|
|
562
|
-
readonly extension: "heapsnapshot";
|
|
563
|
-
readonly languages: readonly ["javascript", "julia"];
|
|
564
|
-
readonly fallbackOrigin: "chrome";
|
|
565
|
-
readonly type: "json";
|
|
566
|
-
readonly matches: (json: unknown) => boolean;
|
|
567
|
-
readonly parse: (json: unknown) => HeapSnapshot[];
|
|
568
|
-
};
|
|
569
|
-
readonly 'webkit-timeline-recording': {
|
|
570
|
-
readonly title: "WebKit timeline recording";
|
|
571
|
-
readonly extension: "webkit-timeline-recording.json";
|
|
572
|
-
readonly languages: readonly ["javascript"];
|
|
573
|
-
readonly fallbackOrigin: "safari";
|
|
574
|
-
readonly type: "json";
|
|
575
|
-
readonly matches: (json: unknown) => boolean;
|
|
576
|
-
readonly parse: (json: unknown) => CallStackProfile[];
|
|
577
|
-
};
|
|
578
450
|
};
|
|
579
|
-
|
|
580
|
-
type
|
|
581
|
-
|
|
582
|
-
|
|
451
|
+
type TraceEvent = TraceSpan | TraceInstant;
|
|
452
|
+
type TraceEventFields = {
|
|
453
|
+
name: string;
|
|
454
|
+
/**
|
|
455
|
+
* The event's category, when the parser or a shared event constructor
|
|
456
|
+
* determines it. The origin categorizes an event that has none.
|
|
457
|
+
*/
|
|
458
|
+
category?: TraceEventCategory;
|
|
459
|
+
/**
|
|
460
|
+
* The category names the format records for the event, which the origin
|
|
461
|
+
* maps to a category.
|
|
462
|
+
*/
|
|
463
|
+
declaredCategories?: readonly string[];
|
|
464
|
+
/** The index in {@link Trace.threads} of the thread the event was on. */
|
|
465
|
+
thread?: number;
|
|
466
|
+
/** The attributes the parser or the origin determines. */
|
|
467
|
+
attributes?: readonly TraceAttribute[];
|
|
468
|
+
/**
|
|
469
|
+
* The event's arguments as the format records them. The origin's
|
|
470
|
+
* `normalizeTraceEvent` turns an argument into an attribute or a reading and
|
|
471
|
+
* removes it. Each one left that holds a string is an attribute.
|
|
472
|
+
*/
|
|
473
|
+
arguments?: Readonly<Record<string, unknown>>;
|
|
474
|
+
};
|
|
475
|
+
/** A named event with a duration. */
|
|
476
|
+
type TraceSpan = TraceEventFields & {
|
|
477
|
+
type: `span`;
|
|
478
|
+
/** Absent when the input orders its events without timing them. */
|
|
479
|
+
start?: number;
|
|
480
|
+
/** Absent for a span the input never ends. */
|
|
481
|
+
duration?: number;
|
|
482
|
+
/** The span's CPU time, when recorded. */
|
|
483
|
+
cpuDuration?: number;
|
|
484
|
+
/**
|
|
485
|
+
* Whether the span is an operation that stays pending while threads do
|
|
486
|
+
* other work, overlapping others of its kind. Its duration is the time that
|
|
487
|
+
* elapsed, which no thread spent on it alone, so it has no self time and adds
|
|
488
|
+
* to no category's time.
|
|
489
|
+
*/
|
|
490
|
+
async?: boolean;
|
|
491
|
+
/**
|
|
492
|
+
* The position in {@link Trace.events} of the span this one is nested in.
|
|
493
|
+
* Set only from nesting the input states, or from containment within one
|
|
494
|
+
* thread where the format's spans nest by construction.
|
|
495
|
+
*/
|
|
496
|
+
parent?: number;
|
|
497
|
+
};
|
|
498
|
+
/** A named event at a moment, with no duration. */
|
|
499
|
+
type TraceInstant = TraceEventFields & {
|
|
500
|
+
type: `instant`;
|
|
501
|
+
/** Absent when the input orders its events without timing them. */
|
|
502
|
+
time?: number;
|
|
503
|
+
};
|
|
504
|
+
/** One recorded value of a gauge, a named quantity whose level varies. */
|
|
505
|
+
type TraceReading = {
|
|
506
|
+
type: `reading`;
|
|
507
|
+
/**
|
|
508
|
+
* Readings sharing a name, and a {@link thread} where they state one, are
|
|
509
|
+
* one gauge.
|
|
510
|
+
*/
|
|
511
|
+
gauge: string;
|
|
512
|
+
/** What the gauge measures, the same for every reading of one gauge. */
|
|
513
|
+
metric: Metric;
|
|
514
|
+
/**
|
|
515
|
+
* The index in {@link Trace.threads} of the thread the gauge is a quantity
|
|
516
|
+
* of, where each thread has its own (e.g. a heap). Readings sharing a name
|
|
517
|
+
* on two threads are two gauges.
|
|
518
|
+
*/
|
|
519
|
+
thread?: number;
|
|
520
|
+
/** Absent when the input orders its readings without timing them. */
|
|
521
|
+
time?: number;
|
|
522
|
+
value: number;
|
|
523
|
+
};
|
|
524
|
+
type TraceEventWithReadings = {
|
|
525
|
+
event: TraceEvent;
|
|
526
|
+
readings: readonly TraceReading[];
|
|
527
|
+
};
|
|
583
528
|
/**
|
|
584
|
-
*
|
|
529
|
+
* A key and a value on an event: a string, or an amount of something the event
|
|
530
|
+
* consumed or produced, which sums across events.
|
|
585
531
|
*
|
|
586
|
-
*
|
|
587
|
-
* share a format and whose marker entries overlap must be ordered carefully
|
|
588
|
-
* (e.g. Deno before Node, since Deno supports `node:` specifiers). A parser
|
|
589
|
-
* origin hint loses to a marker entry of a higher-priority origin, so a
|
|
590
|
-
* markerless origin detected by a hint must also precede the origins whose
|
|
591
|
-
* markers it should outrank.
|
|
532
|
+
* A level, which does not sum, is a gauge's {@link TraceReading} instead.
|
|
592
533
|
*/
|
|
593
|
-
|
|
594
|
-
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
534
|
+
type TraceAttribute = {
|
|
535
|
+
key: string;
|
|
536
|
+
value: string | TraceAmount;
|
|
537
|
+
};
|
|
538
|
+
type TraceAmount = {
|
|
539
|
+
amount: number;
|
|
540
|
+
metric: Metric;
|
|
541
|
+
};
|
|
542
|
+
/**
|
|
543
|
+
* The activity a trace event records.
|
|
544
|
+
*
|
|
545
|
+
* A closed set, so a category means the same activity whichever origin wrote
|
|
546
|
+
* the input and formatting can partition by it.
|
|
547
|
+
*
|
|
548
|
+
* `garbage-collection-pause` is a span during which the collector stopped the
|
|
549
|
+
* program, and `garbage-collection` is collector work that ran beside it, so
|
|
550
|
+
* the first one's share of a trace is the share of the run spent paused.
|
|
551
|
+
*/
|
|
552
|
+
type TraceEventCategory = (typeof TRACE_EVENT_CATEGORIES)[number];
|
|
553
|
+
declare const TRACE_EVENT_CATEGORIES: readonly ["script", "parsing", "compilation", "garbage-collection-pause", "garbage-collection", "style", "layout", "paint", "io", "other"];
|
|
554
|
+
/** Every supported format's spec, in canonical order. */
|
|
555
|
+
declare const formatSpecs: readonly [{
|
|
556
|
+
readonly id: "callgrind";
|
|
557
|
+
readonly title: "Callgrind";
|
|
558
|
+
readonly extension: "callgrind";
|
|
559
|
+
readonly languages: readonly ["c", "ruby"];
|
|
560
|
+
readonly fallbackOrigin: "valgrind";
|
|
561
|
+
readonly type: "binary";
|
|
562
|
+
readonly matches: (bytes: Uint8Array) => boolean;
|
|
563
|
+
readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallGraph[];
|
|
564
|
+
readonly parseAsync: (stream: ReadableStream<Uint8Array>, recordTally: RecordTally) => Promise<CallGraph[]>;
|
|
565
|
+
}, {
|
|
566
|
+
readonly id: "collapsed";
|
|
567
|
+
readonly title: "Collapsed stacks";
|
|
568
|
+
readonly extension: "collapsed";
|
|
569
|
+
readonly languages: readonly ["elixir", "java", "nix", "php", "python", "ruby"];
|
|
570
|
+
readonly fallbackOrigin: "unknown";
|
|
571
|
+
readonly type: "binary";
|
|
572
|
+
readonly matches: (bytes: Uint8Array) => boolean;
|
|
573
|
+
readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
|
|
574
|
+
readonly parseAsync: (stream: ReadableStream<Uint8Array>, recordTally: RecordTally) => Promise<CallStackProfile[]>;
|
|
575
|
+
}, {
|
|
576
|
+
readonly id: "ghc-eventlog";
|
|
577
|
+
readonly title: "GHC eventlog";
|
|
578
|
+
readonly extension: "eventlog";
|
|
579
|
+
readonly languages: readonly ["haskell"];
|
|
580
|
+
readonly fallbackOrigin: "ghc";
|
|
581
|
+
readonly type: "binary";
|
|
582
|
+
readonly matches: (bytes: Uint8Array) => boolean;
|
|
583
|
+
readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
|
|
584
|
+
}, {
|
|
585
|
+
readonly id: "ghc-json-profile";
|
|
586
|
+
readonly title: "GHC JSON profile";
|
|
587
|
+
readonly extension: "prof.json";
|
|
588
|
+
readonly languages: readonly ["haskell"];
|
|
589
|
+
readonly fallbackOrigin: "ghc";
|
|
590
|
+
readonly type: "json";
|
|
591
|
+
readonly matches: (json: unknown) => boolean;
|
|
592
|
+
readonly parse: (json: unknown, recordTally: RecordTally) => CallStackProfile[];
|
|
593
|
+
}, {
|
|
594
|
+
readonly id: "hprof";
|
|
595
|
+
readonly title: "HPROF";
|
|
596
|
+
readonly extension: "hprof";
|
|
597
|
+
readonly languages: readonly ["java"];
|
|
598
|
+
readonly fallbackOrigin: "jdk";
|
|
599
|
+
readonly type: "binary";
|
|
600
|
+
readonly matches: (bytes: Uint8Array) => boolean;
|
|
601
|
+
readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => HeapSnapshot[];
|
|
602
|
+
}, {
|
|
603
|
+
readonly id: "jfr";
|
|
604
|
+
readonly title: "JFR";
|
|
605
|
+
readonly extension: "jfr";
|
|
606
|
+
readonly languages: readonly ["java"];
|
|
607
|
+
readonly fallbackOrigin: "jdk";
|
|
608
|
+
readonly type: "binary";
|
|
609
|
+
readonly matches: (bytes: Uint8Array) => boolean;
|
|
610
|
+
readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
|
|
611
|
+
readonly parseAsync: (stream: ReadableStream<Uint8Array>, recordTally: RecordTally) => Promise<CallStackProfile[]>;
|
|
612
|
+
}, {
|
|
613
|
+
readonly id: "jsc-heap-snapshot";
|
|
614
|
+
readonly title: "JSC heap snapshot";
|
|
615
|
+
readonly extension: "jsc-heap-snapshot.json";
|
|
616
|
+
readonly languages: readonly ["javascript"];
|
|
617
|
+
readonly fallbackOrigin: "safari";
|
|
618
|
+
readonly type: "json";
|
|
619
|
+
readonly matches: (json: unknown) => boolean;
|
|
620
|
+
readonly parse: (json: unknown, recordTally: RecordTally) => HeapSnapshot[];
|
|
621
|
+
}, {
|
|
622
|
+
readonly id: "memray";
|
|
623
|
+
readonly title: "memray";
|
|
624
|
+
readonly extension: "memray.bin";
|
|
625
|
+
readonly languages: readonly ["python"];
|
|
626
|
+
readonly fallbackOrigin: "memray";
|
|
627
|
+
readonly type: "binary";
|
|
628
|
+
readonly matches: (bytes: Uint8Array) => boolean;
|
|
629
|
+
readonly parse: (input: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
|
|
630
|
+
readonly parseAsync: (stream: ReadableStream<Uint8Array>, recordTally: RecordTally) => Promise<CallStackProfile[]>;
|
|
631
|
+
}, {
|
|
632
|
+
readonly id: "perf";
|
|
633
|
+
readonly title: "perf.data";
|
|
634
|
+
readonly extension: "perf.data";
|
|
635
|
+
readonly languages: readonly ["c", "zig"];
|
|
636
|
+
readonly fallbackOrigin: "perf";
|
|
637
|
+
readonly type: "binary";
|
|
638
|
+
readonly matches: (bytes: Uint8Array) => boolean;
|
|
639
|
+
readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
|
|
640
|
+
}, {
|
|
641
|
+
readonly id: "pprof";
|
|
642
|
+
readonly title: "pprof";
|
|
643
|
+
readonly extension: "pprof";
|
|
644
|
+
readonly languages: readonly ["c", "fortran", "go", "javascript", "julia", "ruby", "rust", "swift", "zig"];
|
|
645
|
+
readonly fallbackOrigin: "unknown";
|
|
646
|
+
readonly type: "binary";
|
|
647
|
+
readonly matches: (bytes: Uint8Array) => boolean;
|
|
648
|
+
readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
|
|
649
|
+
}, {
|
|
650
|
+
readonly id: "speedscope";
|
|
651
|
+
readonly title: "Speedscope";
|
|
652
|
+
readonly extension: "speedscope.json";
|
|
653
|
+
readonly languages: readonly ["csharp", "php", "python", "ruby"];
|
|
654
|
+
readonly fallbackOrigin: "unknown";
|
|
655
|
+
readonly type: "json";
|
|
656
|
+
readonly matches: (json: unknown) => boolean;
|
|
657
|
+
readonly parse: (json: unknown, recordTally: RecordTally) => CallStackProfile[];
|
|
658
|
+
}, {
|
|
659
|
+
readonly id: "systing";
|
|
660
|
+
readonly title: "systing";
|
|
661
|
+
readonly extension: "systing";
|
|
662
|
+
readonly languages: readonly ["c", "python", "rust"];
|
|
663
|
+
readonly fallbackOrigin: "systing";
|
|
664
|
+
readonly type: "binary";
|
|
665
|
+
readonly matches: (bytes: Uint8Array) => boolean;
|
|
666
|
+
readonly parse: (bytes: Uint8Array, recordTally: RecordTally) => CallStackProfile[];
|
|
667
|
+
readonly parseAsync: (stream: ReadableStream<Uint8Array>, recordTally: RecordTally) => Promise<CallStackProfile[]>;
|
|
668
|
+
}, {
|
|
669
|
+
readonly id: "trace-event";
|
|
670
|
+
readonly title: "Trace Event Format";
|
|
671
|
+
readonly extension: "trace-event.json";
|
|
672
|
+
readonly languages: readonly ["c", "javascript"];
|
|
673
|
+
readonly fallbackOrigin: "chrome";
|
|
674
|
+
readonly type: "json";
|
|
675
|
+
readonly matches: (json: unknown) => boolean;
|
|
676
|
+
readonly parse: (json: unknown, recordTally: RecordTally) => Trace[];
|
|
677
|
+
}, {
|
|
678
|
+
readonly id: "v8-cpu-profile";
|
|
679
|
+
readonly title: "V8 CPU profile";
|
|
680
|
+
readonly extension: "cpuprofile";
|
|
681
|
+
readonly languages: readonly ["javascript"];
|
|
682
|
+
readonly fallbackOrigin: "chrome";
|
|
683
|
+
readonly type: "json";
|
|
684
|
+
readonly matches: (json: unknown) => boolean;
|
|
685
|
+
readonly parse: (json: unknown, recordTally: RecordTally) => CallStackProfile[];
|
|
686
|
+
}, {
|
|
687
|
+
readonly id: "v8-heap-profile";
|
|
688
|
+
readonly title: "V8 heap profile";
|
|
689
|
+
readonly extension: "heapprofile";
|
|
690
|
+
readonly languages: readonly ["javascript"];
|
|
691
|
+
readonly fallbackOrigin: "chrome";
|
|
692
|
+
readonly type: "json";
|
|
693
|
+
readonly matches: (json: unknown) => boolean;
|
|
694
|
+
readonly parse: (json: unknown, recordTally: RecordTally) => CallStackProfile[];
|
|
695
|
+
}, {
|
|
696
|
+
readonly id: "v8-heap-snapshot";
|
|
697
|
+
readonly title: "V8 heap snapshot";
|
|
698
|
+
readonly extension: "heapsnapshot";
|
|
699
|
+
readonly languages: readonly ["javascript", "julia"];
|
|
700
|
+
readonly fallbackOrigin: "chrome";
|
|
701
|
+
readonly type: "json";
|
|
702
|
+
readonly matches: (json: unknown) => boolean;
|
|
703
|
+
readonly parse: (json: unknown, recordTally: RecordTally) => HeapSnapshot[];
|
|
704
|
+
}, {
|
|
705
|
+
readonly id: "webkit-timeline-recording";
|
|
706
|
+
readonly title: "WebKit timeline recording";
|
|
707
|
+
readonly extension: "webkit-timeline-recording.json";
|
|
708
|
+
readonly languages: readonly ["javascript"];
|
|
709
|
+
readonly fallbackOrigin: "safari";
|
|
710
|
+
readonly type: "json";
|
|
711
|
+
readonly matches: (json: unknown) => boolean;
|
|
712
|
+
readonly parse: (json: unknown, recordTally: RecordTally) => CallStackProfile[];
|
|
713
|
+
}];
|
|
714
|
+
type RegisteredFormatSpec = (typeof formatSpecs)[number];
|
|
715
|
+
type Format = RegisteredFormatSpec[`id`];
|
|
716
|
+
/** A trace event, alone or with the gauge readings its arguments record. */
|
|
717
|
+
type NormalizedTraceEvent = TraceEvent | TraceEventWithReadings | null;
|
|
718
|
+
/**
|
|
719
|
+
* All origin specs in global detection-priority order.
|
|
720
|
+
*
|
|
721
|
+
* Within a format, the detector tries candidates in this order, so origins that
|
|
722
|
+
* share a format and whose marker entries overlap must be ordered carefully
|
|
723
|
+
* (e.g. Deno before Node, since Deno supports `node:` specifiers). A parser
|
|
724
|
+
* origin hint outranks every marker entry, so the order ranks only markers.
|
|
725
|
+
*/
|
|
726
|
+
declare const originSpecs: ({
|
|
727
|
+
readonly id: "deno";
|
|
728
|
+
readonly title: "Deno";
|
|
729
|
+
readonly formats: ["v8-cpu-profile"];
|
|
730
|
+
readonly isMarkerEntry: ({ location }: {
|
|
599
731
|
readonly name?: string | undefined;
|
|
600
732
|
readonly location?: {
|
|
601
733
|
readonly type: `absolute`;
|
|
@@ -615,7 +747,6 @@ declare const originSpecs: ({
|
|
|
615
747
|
} | undefined;
|
|
616
748
|
}) => boolean;
|
|
617
749
|
readonly categorizeEntry: (entry: {
|
|
618
|
-
readonly id: number;
|
|
619
750
|
readonly name?: string | undefined;
|
|
620
751
|
readonly location?: {
|
|
621
752
|
readonly type: `absolute`;
|
|
@@ -639,7 +770,6 @@ declare const originSpecs: ({
|
|
|
639
770
|
readonly title: "Bun";
|
|
640
771
|
readonly formats: ["v8-cpu-profile", "jsc-heap-snapshot", "v8-heap-snapshot"];
|
|
641
772
|
readonly isMarkerEntry: ({ name, location }: {
|
|
642
|
-
readonly id: number;
|
|
643
773
|
readonly name?: string | undefined;
|
|
644
774
|
readonly location?: {
|
|
645
775
|
readonly type: `absolute`;
|
|
@@ -659,7 +789,6 @@ declare const originSpecs: ({
|
|
|
659
789
|
} | undefined;
|
|
660
790
|
}) => boolean;
|
|
661
791
|
readonly categorizeEntry: (entry: {
|
|
662
|
-
readonly id: number;
|
|
663
792
|
readonly name?: string | undefined;
|
|
664
793
|
readonly location?: {
|
|
665
794
|
readonly type: `absolute`;
|
|
@@ -678,13 +807,13 @@ declare const originSpecs: ({
|
|
|
678
807
|
readonly column?: number | undefined;
|
|
679
808
|
} | undefined;
|
|
680
809
|
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
681
|
-
readonly categorizeHeapSnapshotConstructor: (name: string) => "string" | "number" | "symbol" | "object" | "function" | "native" | "unknown" | "regexp" | "array" | "concatenated-string" | "sliced-string" | "
|
|
810
|
+
readonly categorizeHeapSnapshotConstructor: (name: string) => "string" | "number" | "symbol" | "object" | "function" | "code" | "native" | "unknown" | "regexp" | "array" | "concatenated-string" | "sliced-string" | "big-number" | "object-shape" | "internal" | "synthetic" | undefined;
|
|
811
|
+
readonly matchHeapSnapshotEdgeName: (name: string) => string | undefined;
|
|
682
812
|
} | {
|
|
683
813
|
readonly id: "node";
|
|
684
814
|
readonly title: "Node.js";
|
|
685
|
-
readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile"];
|
|
815
|
+
readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile", "trace-event"];
|
|
686
816
|
readonly isMarkerEntry: ({ location }: {
|
|
687
|
-
readonly id: number;
|
|
688
817
|
readonly name?: string | undefined;
|
|
689
818
|
readonly location?: {
|
|
690
819
|
readonly type: `absolute`;
|
|
@@ -704,7 +833,6 @@ declare const originSpecs: ({
|
|
|
704
833
|
} | undefined;
|
|
705
834
|
}) => boolean;
|
|
706
835
|
readonly categorizeEntry: (entry: {
|
|
707
|
-
readonly id: number;
|
|
708
836
|
readonly name?: string | undefined;
|
|
709
837
|
readonly location?: {
|
|
710
838
|
readonly type: `absolute`;
|
|
@@ -724,12 +852,17 @@ declare const originSpecs: ({
|
|
|
724
852
|
} | undefined;
|
|
725
853
|
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
726
854
|
readonly categorizeHeapSnapshotConstructor: (name: string) => HeapSnapshotNodeCategory | undefined;
|
|
855
|
+
readonly matchHeapSnapshotEdgeName: (name: string) => string | undefined;
|
|
856
|
+
readonly categorizeTraceEvent: (event: {
|
|
857
|
+
readonly name: string;
|
|
858
|
+
readonly declaredCategories?: readonly string[] | undefined;
|
|
859
|
+
}) => "script" | "parsing" | "compilation" | "garbage-collection-pause" | "garbage-collection" | "style" | "layout" | "paint" | "io" | "other" | undefined;
|
|
860
|
+
readonly normalizeTraceEvent: (event: TraceEvent) => NormalizedTraceEvent;
|
|
727
861
|
} | {
|
|
728
862
|
readonly id: "chrome";
|
|
729
863
|
readonly title: "Chrome";
|
|
730
|
-
readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile"];
|
|
864
|
+
readonly formats: ["v8-cpu-profile", "v8-heap-snapshot", "v8-heap-profile", "trace-event"];
|
|
731
865
|
readonly isMarkerEntry: ({ name, location }: {
|
|
732
|
-
readonly id: number;
|
|
733
866
|
readonly name?: string | undefined;
|
|
734
867
|
readonly location?: {
|
|
735
868
|
readonly type: `absolute`;
|
|
@@ -749,7 +882,6 @@ declare const originSpecs: ({
|
|
|
749
882
|
} | undefined;
|
|
750
883
|
}) => boolean;
|
|
751
884
|
readonly categorizeEntry: (entry: {
|
|
752
|
-
readonly id: number;
|
|
753
885
|
readonly name?: string | undefined;
|
|
754
886
|
readonly location?: {
|
|
755
887
|
readonly type: `absolute`;
|
|
@@ -769,11 +901,13 @@ declare const originSpecs: ({
|
|
|
769
901
|
} | undefined;
|
|
770
902
|
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
771
903
|
readonly categorizeHeapSnapshotConstructor: (name: string) => HeapSnapshotNodeCategory | undefined;
|
|
904
|
+
readonly matchHeapSnapshotEdgeName: (name: string) => string | undefined;
|
|
905
|
+
readonly categorizeTraceEvent: ({ name, declaredCategories }: DeepReadonly<Pick<TraceEvent, `name` | `declaredCategories`>>) => TraceEventCategory | undefined;
|
|
906
|
+
readonly normalizeTraceEvent: (event: TraceEvent) => NormalizedTraceEvent;
|
|
772
907
|
} | {
|
|
773
908
|
readonly id: "node-pprof";
|
|
774
909
|
readonly formats: ["pprof"];
|
|
775
910
|
readonly isMarkerEntry: ({ name, location }: {
|
|
776
|
-
readonly id: number;
|
|
777
911
|
readonly name?: string | undefined;
|
|
778
912
|
readonly location?: {
|
|
779
913
|
readonly type: `absolute`;
|
|
@@ -793,7 +927,6 @@ declare const originSpecs: ({
|
|
|
793
927
|
} | undefined;
|
|
794
928
|
}) => boolean;
|
|
795
929
|
readonly categorizeEntry: (entry: {
|
|
796
|
-
readonly id: number;
|
|
797
930
|
readonly name?: string | undefined;
|
|
798
931
|
readonly location?: {
|
|
799
932
|
readonly type: `absolute`;
|
|
@@ -817,7 +950,6 @@ declare const originSpecs: ({
|
|
|
817
950
|
readonly id: "pprof-rs";
|
|
818
951
|
readonly formats: ["pprof"];
|
|
819
952
|
readonly isMarkerEntry: (entry: {
|
|
820
|
-
readonly id: number;
|
|
821
953
|
readonly name?: string | undefined;
|
|
822
954
|
readonly location?: {
|
|
823
955
|
readonly type: `absolute`;
|
|
@@ -837,7 +969,6 @@ declare const originSpecs: ({
|
|
|
837
969
|
} | undefined;
|
|
838
970
|
}) => boolean;
|
|
839
971
|
readonly categorizeEntry: (entry: {
|
|
840
|
-
readonly id: number;
|
|
841
972
|
readonly name?: string | undefined;
|
|
842
973
|
readonly location?: {
|
|
843
974
|
readonly type: `absolute`;
|
|
@@ -857,12 +988,12 @@ declare const originSpecs: ({
|
|
|
857
988
|
} | undefined;
|
|
858
989
|
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
859
990
|
readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
|
|
991
|
+
readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
|
|
860
992
|
} | {
|
|
861
993
|
readonly id: "go";
|
|
862
994
|
readonly title: "pprof";
|
|
863
995
|
readonly formats: ["pprof"];
|
|
864
996
|
readonly isMarkerEntry: (entry: {
|
|
865
|
-
readonly id: number;
|
|
866
997
|
readonly name?: string | undefined;
|
|
867
998
|
readonly location?: {
|
|
868
999
|
readonly type: `absolute`;
|
|
@@ -881,8 +1012,8 @@ declare const originSpecs: ({
|
|
|
881
1012
|
readonly column?: number | undefined;
|
|
882
1013
|
} | undefined;
|
|
883
1014
|
}) => boolean;
|
|
1015
|
+
readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
|
|
884
1016
|
readonly categorizeEntry: (entry: {
|
|
885
|
-
readonly id: number;
|
|
886
1017
|
readonly name?: string | undefined;
|
|
887
1018
|
readonly location?: {
|
|
888
1019
|
readonly type: `absolute`;
|
|
@@ -905,7 +1036,6 @@ declare const originSpecs: ({
|
|
|
905
1036
|
readonly id: "pprof-jl";
|
|
906
1037
|
readonly formats: ["pprof"];
|
|
907
1038
|
readonly isMarkerEntry: (entry: {
|
|
908
|
-
readonly id: number;
|
|
909
1039
|
readonly name?: string | undefined;
|
|
910
1040
|
readonly location?: {
|
|
911
1041
|
readonly type: `absolute`;
|
|
@@ -925,7 +1055,6 @@ declare const originSpecs: ({
|
|
|
925
1055
|
} | undefined;
|
|
926
1056
|
}) => boolean;
|
|
927
1057
|
readonly categorizeEntry: (entry: {
|
|
928
|
-
readonly id: number;
|
|
929
1058
|
readonly name?: string | undefined;
|
|
930
1059
|
readonly location?: {
|
|
931
1060
|
readonly type: `absolute`;
|
|
@@ -944,13 +1073,13 @@ declare const originSpecs: ({
|
|
|
944
1073
|
readonly column?: number | undefined;
|
|
945
1074
|
} | undefined;
|
|
946
1075
|
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
1076
|
+
readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
|
|
947
1077
|
readonly normalizeStackFrame: (input: StackFrame) => StackFrame | null;
|
|
948
1078
|
} | {
|
|
949
1079
|
readonly id: "profile-jl";
|
|
950
1080
|
readonly title: "Profile";
|
|
951
1081
|
readonly formats: ["v8-heap-snapshot"];
|
|
952
1082
|
readonly isMarkerEntry: ({ name, location }: {
|
|
953
|
-
readonly id: number;
|
|
954
1083
|
readonly name?: string | undefined;
|
|
955
1084
|
readonly location?: {
|
|
956
1085
|
readonly type: `absolute`;
|
|
@@ -970,12 +1099,11 @@ declare const originSpecs: ({
|
|
|
970
1099
|
} | undefined;
|
|
971
1100
|
}) => boolean;
|
|
972
1101
|
readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
|
|
973
|
-
readonly categorizeHeapSnapshotDeclaredType: (declaredType: string) =>
|
|
1102
|
+
readonly categorizeHeapSnapshotDeclaredType: (declaredType: string) => "string" | "number" | "symbol" | "object" | "function" | "code" | "native" | "unknown" | "regexp" | "array" | "concatenated-string" | "sliced-string" | "big-number" | "object-shape" | "internal" | "synthetic" | undefined;
|
|
974
1103
|
} | {
|
|
975
1104
|
readonly id: "pyinstrument";
|
|
976
1105
|
readonly formats: ["speedscope"];
|
|
977
1106
|
readonly isMarkerEntry: (entry: {
|
|
978
|
-
readonly id: number;
|
|
979
1107
|
readonly name?: string | undefined;
|
|
980
1108
|
readonly location?: {
|
|
981
1109
|
readonly type: `absolute`;
|
|
@@ -995,7 +1123,6 @@ declare const originSpecs: ({
|
|
|
995
1123
|
} | undefined;
|
|
996
1124
|
}) => boolean;
|
|
997
1125
|
readonly categorizeEntry: (entry: {
|
|
998
|
-
readonly id: number;
|
|
999
1126
|
readonly name?: string | undefined;
|
|
1000
1127
|
readonly location?: {
|
|
1001
1128
|
readonly type: `absolute`;
|
|
@@ -1015,19 +1142,20 @@ declare const originSpecs: ({
|
|
|
1015
1142
|
} | undefined;
|
|
1016
1143
|
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
1017
1144
|
readonly normalizeStackFrame: (input: StackFrame) => StackFrame | {
|
|
1018
|
-
|
|
1145
|
+
definition: {
|
|
1019
1146
|
type: `file`;
|
|
1020
1147
|
urlOrPath: string;
|
|
1021
|
-
column?: number;
|
|
1022
1148
|
};
|
|
1023
1149
|
name?: string;
|
|
1024
|
-
|
|
1150
|
+
executing?: SourcePosition;
|
|
1151
|
+
callSite?: UnresolvedSourceReference & {
|
|
1152
|
+
position: SourcePosition;
|
|
1153
|
+
};
|
|
1025
1154
|
} | null;
|
|
1026
1155
|
} | {
|
|
1027
1156
|
readonly id: "py-spy";
|
|
1028
1157
|
readonly formats: ["collapsed", "speedscope"];
|
|
1029
1158
|
readonly isMarkerEntry: (entry: {
|
|
1030
|
-
readonly id: number;
|
|
1031
1159
|
readonly name?: string | undefined;
|
|
1032
1160
|
readonly location?: {
|
|
1033
1161
|
readonly type: `absolute`;
|
|
@@ -1046,13 +1174,13 @@ declare const originSpecs: ({
|
|
|
1046
1174
|
readonly column?: number | undefined;
|
|
1047
1175
|
} | undefined;
|
|
1048
1176
|
}) => boolean;
|
|
1177
|
+
readonly isOriginHint: (hint: string) => boolean;
|
|
1049
1178
|
readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
|
|
1050
|
-
readonly normalizeStackFrame: (input: StackFrame, format: "callgrind" | "collapsed" | "
|
|
1179
|
+
readonly normalizeStackFrame: (input: StackFrame, format: "callgrind" | "collapsed" | "ghc-eventlog" | "ghc-json-profile" | "hprof" | "jfr" | "jsc-heap-snapshot" | "memray" | "perf" | "pprof" | "speedscope" | "systing" | "trace-event" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => StackFrame;
|
|
1051
1180
|
} | {
|
|
1052
1181
|
readonly id: "tachyon";
|
|
1053
1182
|
readonly formats: ["collapsed"];
|
|
1054
1183
|
readonly isMarkerEntry: (entry: {
|
|
1055
|
-
readonly id: number;
|
|
1056
1184
|
readonly name?: string | undefined;
|
|
1057
1185
|
readonly location?: {
|
|
1058
1186
|
readonly type: `absolute`;
|
|
@@ -1071,13 +1199,30 @@ declare const originSpecs: ({
|
|
|
1071
1199
|
readonly column?: number | undefined;
|
|
1072
1200
|
} | undefined;
|
|
1073
1201
|
}) => boolean;
|
|
1074
|
-
readonly categorizeEntry: (entry:
|
|
1075
|
-
|
|
1202
|
+
readonly categorizeEntry: (entry: {
|
|
1203
|
+
readonly name?: string | undefined;
|
|
1204
|
+
readonly location?: {
|
|
1205
|
+
readonly type: `absolute`;
|
|
1206
|
+
readonly url: URL;
|
|
1207
|
+
readonly line?: number | undefined;
|
|
1208
|
+
readonly column?: number | undefined;
|
|
1209
|
+
} | {
|
|
1210
|
+
readonly type: `relative`;
|
|
1211
|
+
readonly path: string;
|
|
1212
|
+
readonly line?: number | undefined;
|
|
1213
|
+
readonly column?: number | undefined;
|
|
1214
|
+
} | {
|
|
1215
|
+
readonly type: `logical`;
|
|
1216
|
+
readonly name: string;
|
|
1217
|
+
readonly line?: number | undefined;
|
|
1218
|
+
readonly column?: number | undefined;
|
|
1219
|
+
} | undefined;
|
|
1220
|
+
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
1221
|
+
readonly normalizeStackFrame: (input: StackFrame) => StackFrame | null;
|
|
1076
1222
|
} | {
|
|
1077
1223
|
readonly id: "async-profiler";
|
|
1078
1224
|
readonly formats: ["jfr", "collapsed"];
|
|
1079
1225
|
readonly isMarkerEntry: (entry: {
|
|
1080
|
-
readonly id: number;
|
|
1081
1226
|
readonly name?: string | undefined;
|
|
1082
1227
|
readonly location?: {
|
|
1083
1228
|
readonly type: `absolute`;
|
|
@@ -1098,7 +1243,7 @@ declare const originSpecs: ({
|
|
|
1098
1243
|
}) => boolean;
|
|
1099
1244
|
readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
|
|
1100
1245
|
readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
|
|
1101
|
-
readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
|
|
1246
|
+
readonly normalizeStackFrame: (input: StackFrame) => StackFrame | null;
|
|
1102
1247
|
} | {
|
|
1103
1248
|
readonly id: "jdk";
|
|
1104
1249
|
readonly title: "JDK";
|
|
@@ -1111,7 +1256,6 @@ declare const originSpecs: ({
|
|
|
1111
1256
|
readonly id: "dotnet-trace";
|
|
1112
1257
|
readonly formats: ["speedscope"];
|
|
1113
1258
|
readonly isMarkerEntry: (entry: {
|
|
1114
|
-
readonly id: number;
|
|
1115
1259
|
readonly name?: string | undefined;
|
|
1116
1260
|
readonly location?: {
|
|
1117
1261
|
readonly type: `absolute`;
|
|
@@ -1130,8 +1274,8 @@ declare const originSpecs: ({
|
|
|
1130
1274
|
readonly column?: number | undefined;
|
|
1131
1275
|
} | undefined;
|
|
1132
1276
|
}) => boolean;
|
|
1277
|
+
readonly isOriginHint: (hint: string) => boolean;
|
|
1133
1278
|
readonly categorizeEntry: (entry: {
|
|
1134
|
-
readonly id: number;
|
|
1135
1279
|
readonly name?: string | undefined;
|
|
1136
1280
|
readonly location?: {
|
|
1137
1281
|
readonly type: `absolute`;
|
|
@@ -1150,12 +1294,12 @@ declare const originSpecs: ({
|
|
|
1150
1294
|
readonly column?: number | undefined;
|
|
1151
1295
|
} | undefined;
|
|
1152
1296
|
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
1297
|
+
readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
|
|
1153
1298
|
readonly normalizeStackFrame: (input: StackFrame) => StackFrame | null;
|
|
1154
1299
|
} | {
|
|
1155
1300
|
readonly id: "eflambe";
|
|
1156
1301
|
readonly formats: ["collapsed"];
|
|
1157
1302
|
readonly isMarkerEntry: (entry: {
|
|
1158
|
-
readonly id: number;
|
|
1159
1303
|
readonly name?: string | undefined;
|
|
1160
1304
|
readonly location?: {
|
|
1161
1305
|
readonly type: `absolute`;
|
|
@@ -1174,9 +1318,8 @@ declare const originSpecs: ({
|
|
|
1174
1318
|
readonly column?: number | undefined;
|
|
1175
1319
|
} | undefined;
|
|
1176
1320
|
}) => boolean;
|
|
1177
|
-
readonly countMetric: (format: "callgrind" | "collapsed" | "
|
|
1321
|
+
readonly countMetric: (format: "callgrind" | "collapsed" | "ghc-eventlog" | "ghc-json-profile" | "hprof" | "jfr" | "jsc-heap-snapshot" | "memray" | "perf" | "pprof" | "speedscope" | "systing" | "trace-event" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => Metric | undefined;
|
|
1178
1322
|
readonly categorizeEntry: (entry: {
|
|
1179
|
-
readonly id: number;
|
|
1180
1323
|
readonly name?: string | undefined;
|
|
1181
1324
|
readonly location?: {
|
|
1182
1325
|
readonly type: `absolute`;
|
|
@@ -1197,13 +1340,10 @@ declare const originSpecs: ({
|
|
|
1197
1340
|
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
1198
1341
|
readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
|
|
1199
1342
|
} | {
|
|
1200
|
-
readonly id: "
|
|
1201
|
-
readonly title: "
|
|
1202
|
-
readonly formats: ["
|
|
1203
|
-
readonly isMarkerEntry: (
|
|
1204
|
-
readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
|
|
1205
|
-
readonly hasRuntimeInsertedArcs: ({ name }: {
|
|
1206
|
-
readonly id: number;
|
|
1343
|
+
readonly id: "nix";
|
|
1344
|
+
readonly title: "Nix";
|
|
1345
|
+
readonly formats: ["collapsed"];
|
|
1346
|
+
readonly isMarkerEntry: ({ name }: {
|
|
1207
1347
|
readonly name?: string | undefined;
|
|
1208
1348
|
readonly location?: {
|
|
1209
1349
|
readonly type: `absolute`;
|
|
@@ -1222,11 +1362,32 @@ declare const originSpecs: ({
|
|
|
1222
1362
|
readonly column?: number | undefined;
|
|
1223
1363
|
} | undefined;
|
|
1224
1364
|
}) => boolean;
|
|
1365
|
+
readonly categorizeEntry: (entry: {
|
|
1366
|
+
readonly name?: string | undefined;
|
|
1367
|
+
readonly location?: {
|
|
1368
|
+
readonly type: `absolute`;
|
|
1369
|
+
readonly url: URL;
|
|
1370
|
+
readonly line?: number | undefined;
|
|
1371
|
+
readonly column?: number | undefined;
|
|
1372
|
+
} | {
|
|
1373
|
+
readonly type: `relative`;
|
|
1374
|
+
readonly path: string;
|
|
1375
|
+
readonly line?: number | undefined;
|
|
1376
|
+
readonly column?: number | undefined;
|
|
1377
|
+
} | {
|
|
1378
|
+
readonly type: `logical`;
|
|
1379
|
+
readonly name: string;
|
|
1380
|
+
readonly line?: number | undefined;
|
|
1381
|
+
readonly column?: number | undefined;
|
|
1382
|
+
} | undefined;
|
|
1383
|
+
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
1384
|
+
readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
|
|
1385
|
+
readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
|
|
1386
|
+
readonly functionIdentity: "call-site";
|
|
1225
1387
|
} | {
|
|
1226
1388
|
readonly id: "rbspy";
|
|
1227
1389
|
readonly formats: ["callgrind", "collapsed", "pprof", "speedscope"];
|
|
1228
1390
|
readonly isMarkerEntry: (entry: {
|
|
1229
|
-
readonly id: number;
|
|
1230
1391
|
readonly name?: string | undefined;
|
|
1231
1392
|
readonly location?: {
|
|
1232
1393
|
readonly type: `absolute`;
|
|
@@ -1245,8 +1406,9 @@ declare const originSpecs: ({
|
|
|
1245
1406
|
readonly column?: number | undefined;
|
|
1246
1407
|
} | undefined;
|
|
1247
1408
|
}) => boolean;
|
|
1409
|
+
readonly isOriginHint: (hint: string, format: "callgrind" | "collapsed" | "ghc-eventlog" | "ghc-json-profile" | "hprof" | "jfr" | "jsc-heap-snapshot" | "memray" | "perf" | "pprof" | "speedscope" | "systing" | "trace-event" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => boolean;
|
|
1410
|
+
readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
|
|
1248
1411
|
readonly categorizeEntry: (entry: {
|
|
1249
|
-
readonly id: number;
|
|
1250
1412
|
readonly name?: string | undefined;
|
|
1251
1413
|
readonly location?: {
|
|
1252
1414
|
readonly type: `absolute`;
|
|
@@ -1265,14 +1427,13 @@ declare const originSpecs: ({
|
|
|
1265
1427
|
readonly column?: number | undefined;
|
|
1266
1428
|
} | undefined;
|
|
1267
1429
|
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
1268
|
-
readonly normalizeStackFrame: (input: StackFrame, format: "callgrind" | "collapsed" | "
|
|
1430
|
+
readonly normalizeStackFrame: (input: StackFrame, format: "callgrind" | "collapsed" | "ghc-eventlog" | "ghc-json-profile" | "hprof" | "jfr" | "jsc-heap-snapshot" | "memray" | "perf" | "pprof" | "speedscope" | "systing" | "trace-event" | "v8-cpu-profile" | "v8-heap-profile" | "v8-heap-snapshot" | "webkit-timeline-recording") => StackFrame;
|
|
1269
1431
|
} | {
|
|
1270
1432
|
readonly id: "safari";
|
|
1271
1433
|
readonly title: "Safari";
|
|
1272
1434
|
readonly formats: ["jsc-heap-snapshot", "webkit-timeline-recording"];
|
|
1273
1435
|
readonly isMarkerEntry: ({ name, location }: DeepReadonly<ProfileEntry>) => boolean;
|
|
1274
1436
|
readonly categorizeEntry: (entry: {
|
|
1275
|
-
readonly id: number;
|
|
1276
1437
|
readonly name?: string | undefined;
|
|
1277
1438
|
readonly location?: {
|
|
1278
1439
|
readonly type: `absolute`;
|
|
@@ -1291,12 +1452,12 @@ declare const originSpecs: ({
|
|
|
1291
1452
|
readonly column?: number | undefined;
|
|
1292
1453
|
} | undefined;
|
|
1293
1454
|
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
1294
|
-
readonly categorizeHeapSnapshotConstructor: (name: string) => "string" | "number" | "symbol" | "object" | "function" | "native" | "unknown" | "regexp" | "array" | "concatenated-string" | "sliced-string" | "
|
|
1455
|
+
readonly categorizeHeapSnapshotConstructor: (name: string) => "string" | "number" | "symbol" | "object" | "function" | "code" | "native" | "unknown" | "regexp" | "array" | "concatenated-string" | "sliced-string" | "big-number" | "object-shape" | "internal" | "synthetic" | undefined;
|
|
1456
|
+
readonly matchHeapSnapshotEdgeName: (name: string) => string | undefined;
|
|
1295
1457
|
} | {
|
|
1296
1458
|
readonly id: "systing";
|
|
1297
1459
|
readonly formats: ["systing"];
|
|
1298
1460
|
readonly isMarkerEntry: (entry: {
|
|
1299
|
-
readonly id: number;
|
|
1300
1461
|
readonly name?: string | undefined;
|
|
1301
1462
|
readonly location?: {
|
|
1302
1463
|
readonly type: `absolute`;
|
|
@@ -1316,7 +1477,6 @@ declare const originSpecs: ({
|
|
|
1316
1477
|
} | undefined;
|
|
1317
1478
|
}) => boolean;
|
|
1318
1479
|
readonly categorizeEntry: (entry: {
|
|
1319
|
-
readonly id: number;
|
|
1320
1480
|
readonly name?: string | undefined;
|
|
1321
1481
|
readonly location?: {
|
|
1322
1482
|
readonly type: `absolute`;
|
|
@@ -1335,13 +1495,13 @@ declare const originSpecs: ({
|
|
|
1335
1495
|
readonly column?: number | undefined;
|
|
1336
1496
|
} | undefined;
|
|
1337
1497
|
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
1498
|
+
readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
|
|
1338
1499
|
readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
|
|
1339
1500
|
} | {
|
|
1340
|
-
readonly id: "
|
|
1341
|
-
readonly
|
|
1342
|
-
readonly
|
|
1343
|
-
readonly
|
|
1344
|
-
readonly id: number;
|
|
1501
|
+
readonly id: "excimer";
|
|
1502
|
+
readonly title: "Excimer";
|
|
1503
|
+
readonly formats: ["collapsed", "speedscope"];
|
|
1504
|
+
readonly isMarkerEntry: ({ name }: {
|
|
1345
1505
|
readonly name?: string | undefined;
|
|
1346
1506
|
readonly location?: {
|
|
1347
1507
|
readonly type: `absolute`;
|
|
@@ -1359,13 +1519,9 @@ declare const originSpecs: ({
|
|
|
1359
1519
|
readonly line?: number | undefined;
|
|
1360
1520
|
readonly column?: number | undefined;
|
|
1361
1521
|
} | undefined;
|
|
1362
|
-
}) =>
|
|
1363
|
-
|
|
1364
|
-
readonly
|
|
1365
|
-
readonly title: "Excimer";
|
|
1366
|
-
readonly formats: ["collapsed", "speedscope"];
|
|
1367
|
-
readonly isMarkerEntry: ({ name }: {
|
|
1368
|
-
readonly id: number;
|
|
1522
|
+
}) => boolean;
|
|
1523
|
+
readonly isOriginHint: (hint: string) => hint is "Excimer";
|
|
1524
|
+
readonly categorizeEntry: (entry: {
|
|
1369
1525
|
readonly name?: string | undefined;
|
|
1370
1526
|
readonly location?: {
|
|
1371
1527
|
readonly type: `absolute`;
|
|
@@ -1383,9 +1539,14 @@ declare const originSpecs: ({
|
|
|
1383
1539
|
readonly line?: number | undefined;
|
|
1384
1540
|
readonly column?: number | undefined;
|
|
1385
1541
|
} | undefined;
|
|
1386
|
-
}) =>
|
|
1542
|
+
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
1543
|
+
readonly isTruncationMarker: ({ name }: StackFrame) => boolean;
|
|
1544
|
+
readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
|
|
1545
|
+
} | {
|
|
1546
|
+
readonly id: "gperftools";
|
|
1547
|
+
readonly formats: ["pprof"];
|
|
1548
|
+
readonly isMarkerEntry: () => false;
|
|
1387
1549
|
readonly categorizeEntry: (entry: {
|
|
1388
|
-
readonly id: number;
|
|
1389
1550
|
readonly name?: string | undefined;
|
|
1390
1551
|
readonly location?: {
|
|
1391
1552
|
readonly type: `absolute`;
|
|
@@ -1404,7 +1565,58 @@ declare const originSpecs: ({
|
|
|
1404
1565
|
readonly column?: number | undefined;
|
|
1405
1566
|
} | undefined;
|
|
1406
1567
|
}) => "ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle";
|
|
1568
|
+
readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
|
|
1569
|
+
readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
|
|
1570
|
+
} | {
|
|
1571
|
+
readonly id: "clang";
|
|
1572
|
+
readonly title: "Clang";
|
|
1573
|
+
readonly formats: ["trace-event"];
|
|
1574
|
+
readonly isMarkerEntry: () => false;
|
|
1575
|
+
readonly isOriginHint: (hint: string) => boolean;
|
|
1576
|
+
readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
|
|
1577
|
+
readonly categorizeTraceEvent: ({ name }: {
|
|
1578
|
+
readonly name: string;
|
|
1579
|
+
readonly declaredCategories?: readonly string[] | undefined;
|
|
1580
|
+
}) => "parsing" | "compilation";
|
|
1581
|
+
readonly normalizeTraceEvent: (event: TraceEvent) => TraceEvent | null;
|
|
1582
|
+
} | {
|
|
1583
|
+
readonly id: "tsc";
|
|
1584
|
+
readonly title: "TypeScript compiler";
|
|
1585
|
+
readonly formats: ["trace-event"];
|
|
1586
|
+
readonly isMarkerEntry: () => false;
|
|
1587
|
+
readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
|
|
1588
|
+
readonly categorizeTraceEvent: ({ declaredCategories }: {
|
|
1589
|
+
readonly name: string;
|
|
1590
|
+
readonly declaredCategories?: readonly string[] | undefined;
|
|
1591
|
+
}) => "parsing" | "compilation";
|
|
1592
|
+
} | {
|
|
1593
|
+
readonly id: "valgrind";
|
|
1594
|
+
readonly title: "Valgrind";
|
|
1595
|
+
readonly formats: ["callgrind"];
|
|
1596
|
+
readonly isMarkerEntry: () => false;
|
|
1597
|
+
readonly isOriginHint: (hint: string) => boolean;
|
|
1598
|
+
readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
|
|
1599
|
+
readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
|
|
1407
1600
|
readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
|
|
1601
|
+
readonly hasRuntimeInsertedArcs: ({ name }: {
|
|
1602
|
+
readonly name?: string | undefined;
|
|
1603
|
+
readonly location?: {
|
|
1604
|
+
readonly type: `absolute`;
|
|
1605
|
+
readonly url: URL;
|
|
1606
|
+
readonly line?: number | undefined;
|
|
1607
|
+
readonly column?: number | undefined;
|
|
1608
|
+
} | {
|
|
1609
|
+
readonly type: `relative`;
|
|
1610
|
+
readonly path: string;
|
|
1611
|
+
readonly line?: number | undefined;
|
|
1612
|
+
readonly column?: number | undefined;
|
|
1613
|
+
} | {
|
|
1614
|
+
readonly type: `logical`;
|
|
1615
|
+
readonly name: string;
|
|
1616
|
+
readonly line?: number | undefined;
|
|
1617
|
+
readonly column?: number | undefined;
|
|
1618
|
+
} | undefined;
|
|
1619
|
+
}) => boolean;
|
|
1408
1620
|
} | {
|
|
1409
1621
|
readonly id: "memray";
|
|
1410
1622
|
readonly formats: ["memray"];
|
|
@@ -1416,7 +1628,6 @@ declare const originSpecs: ({
|
|
|
1416
1628
|
readonly formats: ["ghc-eventlog", "ghc-json-profile"];
|
|
1417
1629
|
readonly isMarkerEntry: () => false;
|
|
1418
1630
|
readonly categorizeEntry: (entry: {
|
|
1419
|
-
readonly id: number;
|
|
1420
1631
|
readonly name?: string | undefined;
|
|
1421
1632
|
readonly location?: {
|
|
1422
1633
|
readonly type: `absolute`;
|
|
@@ -1440,19 +1651,21 @@ declare const originSpecs: ({
|
|
|
1440
1651
|
readonly formats: ["perf"];
|
|
1441
1652
|
readonly isMarkerEntry: () => false;
|
|
1442
1653
|
readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
|
|
1654
|
+
readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
|
|
1655
|
+
readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
|
|
1443
1656
|
} | {
|
|
1444
1657
|
readonly id: "perf";
|
|
1445
1658
|
readonly formats: ["perf"];
|
|
1446
1659
|
readonly isMarkerEntry: () => false;
|
|
1447
1660
|
readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
|
|
1661
|
+
readonly matchEntry: (entry: DeepReadonly<ProfileEntry>) => EntryMatch | undefined;
|
|
1662
|
+
readonly normalizeStackFrame: (input: StackFrame) => StackFrame;
|
|
1448
1663
|
} | {
|
|
1449
1664
|
readonly id: "unknown";
|
|
1450
1665
|
readonly formats: [];
|
|
1451
1666
|
readonly isMarkerEntry: () => false;
|
|
1452
1667
|
readonly categorizeEntry: (entry: DeepReadonly<ProfileEntry>) => FunctionCategory;
|
|
1453
1668
|
})[];
|
|
1454
|
-
//#endregion
|
|
1455
|
-
//#region src/origins/index.d.ts
|
|
1456
1669
|
/**
|
|
1457
1670
|
* The profiler tool or runtime that wrote an input (e.g. `node` for
|
|
1458
1671
|
* Node's native V8 profiler, `node-pprof` for the `pprof` npm package,
|
|
@@ -1461,309 +1674,119 @@ declare const originSpecs: ({
|
|
|
1461
1674
|
* Auto-detected from a profile's entries via {@link OriginDetector}, or
|
|
1462
1675
|
* specified explicitly.
|
|
1463
1676
|
*/
|
|
1464
|
-
type Origin =
|
|
1465
|
-
/**
|
|
1466
|
-
|
|
1467
|
-
|
|
1468
|
-
|
|
1469
|
-
|
|
1470
|
-
|
|
1471
|
-
|
|
1472
|
-
|
|
1473
|
-
|
|
1474
|
-
|
|
1475
|
-
|
|
1476
|
-
|
|
1477
|
-
|
|
1478
|
-
|
|
1479
|
-
|
|
1480
|
-
};
|
|
1481
|
-
/** One function's recorded costs during its calls to a given direct callee. */
|
|
1482
|
-
type AggregatedCallGraphCalleeMetrics = {
|
|
1483
|
-
/** The callee corresponding to the ID. */
|
|
1484
|
-
callee: AggregatedCallGraphFunction;
|
|
1485
|
-
/** The recorded number of calls, or `0` when the format records none. */
|
|
1486
|
-
callCount: number;
|
|
1677
|
+
type Origin = RegisteredOriginSpec[`id`];
|
|
1678
|
+
/**
|
|
1679
|
+
* Determines the origin of an input from its entries.
|
|
1680
|
+
*
|
|
1681
|
+
* Resolves to the origin a parser's origin hint names, or else tries each
|
|
1682
|
+
* origin that can emit the format in priority order, resolving to the
|
|
1683
|
+
* highest-priority one with a marker entry among the added entries, and
|
|
1684
|
+
* falling back to the format's fallback origin when none match.
|
|
1685
|
+
*
|
|
1686
|
+
* An explicit origin skips detection.
|
|
1687
|
+
*/
|
|
1688
|
+
declare class OriginDetector {
|
|
1689
|
+
#private;
|
|
1690
|
+
constructor({ id: format, fallbackOrigin }: {
|
|
1691
|
+
id: Format;
|
|
1692
|
+
fallbackOrigin: Origin;
|
|
1693
|
+
}, origin?: Origin);
|
|
1487
1694
|
/**
|
|
1488
|
-
*
|
|
1489
|
-
*
|
|
1695
|
+
* Whether the origin is already decided, so a caller may skip building
|
|
1696
|
+
* further entries to add.
|
|
1490
1697
|
*/
|
|
1491
|
-
|
|
1492
|
-
};
|
|
1493
|
-
/** An aggregation of one function's recorded costs within a call graph. */
|
|
1494
|
-
type AggregatedCallGraphFunction = {
|
|
1495
|
-
type: `function`;
|
|
1496
|
-
/** An index that uniquely identifies this function. */
|
|
1497
|
-
id: number;
|
|
1498
|
-
/** The name of the function in code. */
|
|
1499
|
-
name: string;
|
|
1500
|
-
/** Where the function was defined, if known. */
|
|
1501
|
-
location?: SourceLocation;
|
|
1502
|
-
/** The category of functions this function belongs to. */
|
|
1503
|
-
category: FunctionCategory;
|
|
1698
|
+
get decided(): boolean;
|
|
1504
1699
|
/**
|
|
1505
|
-
*
|
|
1506
|
-
*
|
|
1700
|
+
* Returns whether the origin is now decided, so a caller may stop adding
|
|
1701
|
+
* early. Adding further entries is harmless.
|
|
1507
1702
|
*/
|
|
1508
|
-
|
|
1703
|
+
add(entry: DeepReadonly<ProfileEntry>): boolean;
|
|
1509
1704
|
/**
|
|
1510
|
-
*
|
|
1511
|
-
*
|
|
1512
|
-
*
|
|
1513
|
-
*
|
|
1705
|
+
* Applies an origin hint set by a parser: format-level metadata (e.g. a
|
|
1706
|
+
* recorder's own event types or a writer's self-identification field)
|
|
1707
|
+
* pointing at an origin whose entries carry no marker.
|
|
1708
|
+
*
|
|
1709
|
+
* A hint outranks every marker entry, because it is the writer identifying
|
|
1710
|
+
* itself. A specified origin and an earlier hint ignore it, and so does a
|
|
1711
|
+
* hint no candidate for the format accepts.
|
|
1514
1712
|
*/
|
|
1515
|
-
|
|
1516
|
-
|
|
1517
|
-
|
|
1518
|
-
|
|
1519
|
-
|
|
1520
|
-
|
|
1521
|
-
|
|
1713
|
+
hint(hint: string): void;
|
|
1714
|
+
addAll(entries: readonly DeepReadonly<ProfileEntry>[]): void;
|
|
1715
|
+
/** Resolves the detected origin from every entry added so far. */
|
|
1716
|
+
resolve(): Origin;
|
|
1717
|
+
/** The origin evidence {@link resolve} selects the origin by. */
|
|
1718
|
+
get evidence(): OriginEvidence;
|
|
1719
|
+
/** The IDs of the origins that can emit the format, in priority order. */
|
|
1720
|
+
get candidates(): Origin[];
|
|
1721
|
+
}
|
|
1722
|
+
type OriginEvidence = {
|
|
1723
|
+
type: `specified`;
|
|
1724
|
+
} | {
|
|
1725
|
+
type: `marker`;
|
|
1726
|
+
entry: DeepReadonly<ProfileEntry>;
|
|
1727
|
+
} | {
|
|
1728
|
+
type: `hint`;
|
|
1729
|
+
} | {
|
|
1730
|
+
type: `fallback`;
|
|
1731
|
+
};
|
|
1732
|
+
/** One of the concrete origin specs, with its literal {@link Origin} ID. */
|
|
1733
|
+
type RegisteredOriginSpec = (typeof originSpecs)[number];
|
|
1734
|
+
/** The caller's source maps, each keyed by the generated file it maps. */
|
|
1735
|
+
type NormalizedSourceMaps = readonly NormalizedSourceMap[];
|
|
1736
|
+
type NormalizedSourceMap = {
|
|
1737
|
+
consumer: SourceMapConsumer;
|
|
1738
|
+
fileReference: FileReference;
|
|
1522
1739
|
};
|
|
1523
|
-
//#endregion
|
|
1524
|
-
//#region src/modalities/call-stack-profile/aggregate.d.ts
|
|
1525
1740
|
/**
|
|
1526
|
-
*
|
|
1527
|
-
*
|
|
1741
|
+
* Applies the caller's source maps to one conversion's locations, and records
|
|
1742
|
+
* each generated file's outcome for {@link SourceMapResolver.report}.
|
|
1528
1743
|
*/
|
|
1529
|
-
|
|
1530
|
-
|
|
1531
|
-
|
|
1532
|
-
* this line.
|
|
1533
|
-
*/
|
|
1534
|
-
count: number;
|
|
1744
|
+
declare class SourceMapResolver {
|
|
1745
|
+
#private;
|
|
1746
|
+
constructor(sourceMaps: NormalizedSourceMaps, logger: Logger);
|
|
1535
1747
|
/**
|
|
1536
|
-
*
|
|
1537
|
-
*
|
|
1538
|
-
* this line.
|
|
1748
|
+
* Records {@link location}'s generated file, so {@link report} counts it
|
|
1749
|
+
* whether or not formatting resolves a location in it.
|
|
1539
1750
|
*/
|
|
1540
|
-
|
|
1541
|
-
};
|
|
1542
|
-
/**
|
|
1543
|
-
* An aggregation of observations recorded directly within a function's body
|
|
1544
|
-
* with a given direct caller.
|
|
1545
|
-
*/
|
|
1546
|
-
type AggregatedCallStackProfileCallerMetrics = {
|
|
1547
|
-
/** The caller corresponding to the ID. */
|
|
1548
|
-
caller: AggregatedCallStackProfileFunction;
|
|
1751
|
+
addGeneratedFile(location: SourceLocation): void;
|
|
1549
1752
|
/**
|
|
1550
|
-
*
|
|
1551
|
-
*
|
|
1753
|
+
* Applies the matching source map, if any, to {@link location}.
|
|
1754
|
+
*
|
|
1755
|
+
* A mapped source that is a relative path resolves against the resolved
|
|
1756
|
+
* `baseURL`, including one inferred by `baseURL: 'auto'`. The resolved source
|
|
1757
|
+
* may then be outside the inferred directory and format with `../`
|
|
1758
|
+
* segments. Without a base URL the location stays unmapped.
|
|
1552
1759
|
*/
|
|
1553
|
-
|
|
1760
|
+
resolve(location: SourceLocation, baseURL: URL | undefined): SourceLocation;
|
|
1554
1761
|
/**
|
|
1555
|
-
*
|
|
1556
|
-
*
|
|
1557
|
-
*
|
|
1762
|
+
* Logs what the source maps did across the generated files recorded so far:
|
|
1763
|
+
* a summary of the generated files at `info`, each supplied map that matched
|
|
1764
|
+
* no generated file at `warn`, and each generated file's outcome at `debug`.
|
|
1765
|
+
*
|
|
1766
|
+
* {@link baseURL} is the base URL formatting resolved relative sources
|
|
1767
|
+
* against, so the report states which relative sources stayed unmapped.
|
|
1558
1768
|
*/
|
|
1559
|
-
|
|
1560
|
-
}
|
|
1769
|
+
report(baseURL: URL | undefined): void;
|
|
1770
|
+
}
|
|
1771
|
+
/** Profile data that can be synchronously parsed and converted to Markdown. */
|
|
1772
|
+
type ProfileData = string | Uint8Array | Iterable<Uint8Array>;
|
|
1773
|
+
/** Profile data that can be asynchronously parsed and converted to Markdown. */
|
|
1774
|
+
type AsyncProfileData = Blob | ReadableStream<Uint8Array>;
|
|
1561
1775
|
/**
|
|
1562
|
-
*
|
|
1563
|
-
*
|
|
1776
|
+
* Profile data with an optional explicit format and origin, and an optional
|
|
1777
|
+
* name for the data's source.
|
|
1778
|
+
*
|
|
1779
|
+
* The format and origin are auto-detected if not specified. The name is
|
|
1780
|
+
* reported with a failure the input causes, so a diff states which of its two
|
|
1781
|
+
* inputs failed.
|
|
1564
1782
|
*/
|
|
1565
|
-
type
|
|
1566
|
-
|
|
1567
|
-
|
|
1568
|
-
|
|
1569
|
-
|
|
1570
|
-
|
|
1571
|
-
|
|
1572
|
-
totalCount: number;
|
|
1573
|
-
/**
|
|
1574
|
-
* For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
|
|
1575
|
-
* values from observations recorded directly within the function's body,
|
|
1576
|
-
* _and_ all its callees, with this callee.
|
|
1577
|
-
*/
|
|
1578
|
-
totalValues: Float64Array;
|
|
1579
|
-
/**
|
|
1580
|
-
* Internal aggregation bookkeeping: the epoch of the most recent call stack
|
|
1581
|
-
* whose total this frame pair was counted into, so one that recurs within
|
|
1582
|
-
* one call stack is counted just once.
|
|
1583
|
-
*/
|
|
1584
|
-
lastSeenEpoch: number;
|
|
1585
|
-
};
|
|
1586
|
-
/**
|
|
1587
|
-
* An aggregation of data from every observation involving a given function
|
|
1588
|
-
* within a profile.
|
|
1589
|
-
*/
|
|
1590
|
-
type AggregatedCallStackProfileFunction = {
|
|
1591
|
-
type: `function`;
|
|
1592
|
-
/** An index that uniquely identifies this function. */
|
|
1593
|
-
id: number;
|
|
1594
|
-
/** The name of the function in code. */
|
|
1595
|
-
name: string;
|
|
1596
|
-
/** Where the function was defined, if known. */
|
|
1597
|
-
location?: SourceLocation;
|
|
1598
|
-
/** The category of functions this function belongs to. */
|
|
1599
|
-
category: FunctionCategory;
|
|
1600
|
-
/**
|
|
1601
|
-
* The number of observations recorded directly within the function's body,
|
|
1602
|
-
* excluding its callees.
|
|
1603
|
-
*/
|
|
1604
|
-
selfCount: number;
|
|
1605
|
-
/**
|
|
1606
|
-
* The number of observations recorded directly within the function's body
|
|
1607
|
-
* _and_ all its callees.
|
|
1608
|
-
*/
|
|
1609
|
-
totalCount: number;
|
|
1610
|
-
/**
|
|
1611
|
-
* For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
|
|
1612
|
-
* values from observations recorded directly within the function's body,
|
|
1613
|
-
* excluding its callees.
|
|
1614
|
-
*/
|
|
1615
|
-
selfValues: Float64Array;
|
|
1616
|
-
/**
|
|
1617
|
-
* For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
|
|
1618
|
-
* values from observations recorded directly within the function's body _and_
|
|
1619
|
-
* all its callees.
|
|
1620
|
-
*/
|
|
1621
|
-
totalValues: Float64Array;
|
|
1622
|
-
/** 1-based line number to values and count for that line. */
|
|
1623
|
-
lineToMetrics: Map<number, AggregatedCallStackProfileLineMetrics>;
|
|
1624
|
-
/**
|
|
1625
|
-
* Direct caller id to values and count with that caller's calls to
|
|
1626
|
-
* this function.
|
|
1627
|
-
*/
|
|
1628
|
-
callerIdToMetrics: Map<number, AggregatedCallStackProfileCallerMetrics>;
|
|
1629
|
-
/**
|
|
1630
|
-
* Direct callee id to values and count for that callee's calls where
|
|
1631
|
-
* this function was a direct or transitive caller.
|
|
1632
|
-
*/
|
|
1633
|
-
calleeIdToMetrics: Map<number, AggregatedCallStackProfileCalleeMetrics>;
|
|
1634
|
-
};
|
|
1635
|
-
//#endregion
|
|
1636
|
-
//#region src/modalities/heap-snapshot/aggregate.d.ts
|
|
1637
|
-
type AggregatedHeapSnapshotNode = {
|
|
1638
|
-
type: `node`;
|
|
1639
|
-
/** Unique ID for this node that can also be used as an index. */
|
|
1640
|
-
id: number;
|
|
1641
|
-
/** A human readable label for this node. */
|
|
1642
|
-
name?: string;
|
|
1643
|
-
/**
|
|
1644
|
-
* The file reference the {@link name} parses as, when it is URL-shaped
|
|
1645
|
-
* (e.g. a V8 module namespace object named by its file URL). Formatting
|
|
1646
|
-
* shows it relative to the base URL in place of the raw name.
|
|
1647
|
-
*/
|
|
1648
|
-
nameLocation?: FileReference;
|
|
1649
|
-
/** Bytes allocated directly for this node. */
|
|
1650
|
-
selfSize: number;
|
|
1651
|
-
/** What this node holds. */
|
|
1652
|
-
category: HeapSnapshotNodeCategory;
|
|
1653
|
-
/**
|
|
1654
|
-
* Bytes allocated for this node, as well as all nodes that would be freed if
|
|
1655
|
-
* the node were garbage collected.
|
|
1656
|
-
*/
|
|
1657
|
-
retainedSize: number;
|
|
1658
|
-
/** The exact location where the node was defined. */
|
|
1659
|
-
location?: SourceLocation;
|
|
1660
|
-
};
|
|
1661
|
-
//#endregion
|
|
1662
|
-
//#region src/source-map.d.ts
|
|
1663
|
-
type NormalizedSourceMap = {
|
|
1664
|
-
consumer: SourceMapConsumer;
|
|
1665
|
-
fileReference: FileReference;
|
|
1666
|
-
};
|
|
1667
|
-
type NormalizedSourceMaps = NormalizedSourceMap[];
|
|
1668
|
-
//#endregion
|
|
1669
|
-
//#region src/options.d.ts
|
|
1670
|
-
/** Profile data that can be synchronously parsed and converted to Markdown. */
|
|
1671
|
-
type ProfileData = string | Uint8Array | Iterable<Uint8Array>;
|
|
1672
|
-
/** Profile data that can be asynchronously parsed and converted to Markdown. */
|
|
1673
|
-
type AsyncProfileData = Blob | ReadableStream<Uint8Array>;
|
|
1674
|
-
/**
|
|
1675
|
-
* Profile data with an optional explicit format and origin.
|
|
1676
|
-
*
|
|
1677
|
-
* The format and origin are auto-detected if not specified.
|
|
1678
|
-
*/
|
|
1679
|
-
type ProfileInput<Data> = Data | {
|
|
1680
|
-
data: Data;
|
|
1681
|
-
format?: Format;
|
|
1682
|
-
origin?: Origin;
|
|
1683
|
-
};
|
|
1684
|
-
/**
|
|
1685
|
-
* The category of code a function originated from.
|
|
1686
|
-
*
|
|
1687
|
-
* A closed set, so a category names the same thing whichever origin wrote the
|
|
1688
|
-
* input and formatting can partition by it. The first three record where the
|
|
1689
|
-
* code came from, the next two what the profiler could determine about a frame
|
|
1690
|
-
* with no source file, and the rest name a runtime activity.
|
|
1691
|
-
*
|
|
1692
|
-
* These boundaries decide most assignments:
|
|
1693
|
-
*
|
|
1694
|
-
* - `stdlib` requires positive evidence that the code is the language's or
|
|
1695
|
-
* runtime's own library: a standard-library path, module specifier,
|
|
1696
|
-
* namespace, or package prefix. A missing source file is never evidence for
|
|
1697
|
-
* `stdlib`
|
|
1698
|
-
* - `native` is compiled code the profiler attributed to no source file, plus
|
|
1699
|
-
* code located in a shared library or in a runtime's own C/C++ sources.
|
|
1700
|
-
* `unknown` is a frame the profiler could not identify, a weaker claim,
|
|
1701
|
-
* because the code may be a function in the profiled language
|
|
1702
|
-
* - `compiler` is the runtime producing executable code, and `jit` is a frame
|
|
1703
|
-
* executing code the runtime generated. Where a frame both executes generated
|
|
1704
|
-
* code and does the work of a named activity, the activity takes precedence,
|
|
1705
|
-
* so a garbage collection write barrier compiled inline is
|
|
1706
|
-
* `garbage-collector`
|
|
1707
|
-
*/
|
|
1708
|
-
type FunctionCategory = (typeof FUNCTION_CATEGORIES)[number];
|
|
1709
|
-
/** Every category {@link FunctionCategory} allows. */
|
|
1710
|
-
declare const FUNCTION_CATEGORIES: readonly ["ours", "third-party", "stdlib", "native", "unknown", "garbage-collector", "compiler", "jit", "regexp", "kernel", "idle"];
|
|
1711
|
-
/** A single entry in a formatted profile. */
|
|
1712
|
-
type ProfileEntry = {
|
|
1713
|
-
/** An index that uniquely identifies this entry. */
|
|
1714
|
-
id: number;
|
|
1715
|
-
/**
|
|
1716
|
-
* The name of the entity corresponding to this entry (e.g. a function name)
|
|
1717
|
-
* if it has one.
|
|
1718
|
-
*/
|
|
1719
|
-
name?: string;
|
|
1720
|
-
/**
|
|
1721
|
-
* The location where the entity corresponding to this entry was defined: a
|
|
1722
|
-
* file, or a logical name such as a JVM class or a BEAM module when the
|
|
1723
|
-
* runtime reports no file. Undefined if unknown.
|
|
1724
|
-
*/
|
|
1725
|
-
location?: SourceLocation;
|
|
1726
|
-
};
|
|
1727
|
-
/**
|
|
1728
|
-
* Normalized entry fields used to match an entry across diffed profiles.
|
|
1729
|
-
*
|
|
1730
|
-
* Only affects matching; the entry's displayed name and location are
|
|
1731
|
-
* unchanged.
|
|
1732
|
-
*/
|
|
1733
|
-
type EntryMatch = {
|
|
1734
|
-
/** The name to match by. Omit to match by the entry's name. */
|
|
1735
|
-
name?: string;
|
|
1736
|
-
/**
|
|
1737
|
-
* The location to match by, as a URL, file path, or logical name string.
|
|
1738
|
-
* Omit to match by the entry's location. An empty string matches by name
|
|
1739
|
-
* alone.
|
|
1740
|
-
*/
|
|
1741
|
-
location?: string;
|
|
1742
|
-
};
|
|
1743
|
-
/**
|
|
1744
|
-
* The keys an entry is paired by across a diff's two sides, derived from its
|
|
1745
|
-
* {@link EntryMatch}.
|
|
1746
|
-
*/
|
|
1747
|
-
type EntryMatchKeys = {
|
|
1748
|
-
/**
|
|
1749
|
-
* The key pairing entries by normalized name alone, for entities whose
|
|
1750
|
-
* location varies between profiles of the same program.
|
|
1751
|
-
*/
|
|
1752
|
-
name: string;
|
|
1753
|
-
/** The key pairing entries by normalized name and location. */
|
|
1754
|
-
nameAndLocation: string;
|
|
1755
|
-
};
|
|
1756
|
-
/** An aggregated entry in a formatted profile. */
|
|
1757
|
-
type AggregatedProfileEntry = AggregatedCallStackProfileFunction | AggregatedCallGraphFunction | AggregatedHeapSnapshotNode;
|
|
1758
|
-
/** The context in which a profile is being converted to Markdown. */
|
|
1759
|
-
type ProfileToMdContext = {
|
|
1760
|
-
/** The format of the profile being converted. */
|
|
1761
|
-
format: Format;
|
|
1762
|
-
/** The origin of the profile being converted. */
|
|
1763
|
-
origin: Origin;
|
|
1764
|
-
};
|
|
1765
|
-
/** Options for profile to Markdown converters. */
|
|
1766
|
-
type ProfileToMdOptions = {
|
|
1783
|
+
type ProfileInput<Data> = Data | {
|
|
1784
|
+
data: Data;
|
|
1785
|
+
format?: Format;
|
|
1786
|
+
origin?: Origin;
|
|
1787
|
+
name?: string;
|
|
1788
|
+
};
|
|
1789
|
+
type ProfileToMdOptions = {
|
|
1767
1790
|
/**
|
|
1768
1791
|
* The number of entries to display when computing the "top N" by some metric.
|
|
1769
1792
|
*
|
|
@@ -1771,9 +1794,10 @@ type ProfileToMdOptions = {
|
|
|
1771
1794
|
* split into per-category subsections displays up to this many entries in
|
|
1772
1795
|
* every one of them. See {@link minCategoryShare}.
|
|
1773
1796
|
*
|
|
1774
|
-
*
|
|
1797
|
+
* A quarter of this value, rounded up, limits the lists nested under each
|
|
1798
|
+
* entry, such as its hottest lines.
|
|
1775
1799
|
*
|
|
1776
|
-
* Defaults to 20.
|
|
1800
|
+
* Must be a positive integer. Defaults to 20.
|
|
1777
1801
|
*/
|
|
1778
1802
|
topN?: number;
|
|
1779
1803
|
/**
|
|
@@ -1798,12 +1822,14 @@ type ProfileToMdOptions = {
|
|
|
1798
1822
|
/**
|
|
1799
1823
|
* Base URL to show paths relative to in the Markdown output.
|
|
1800
1824
|
*
|
|
1801
|
-
* Accepts an absolute file path string or URL.
|
|
1802
|
-
*
|
|
1825
|
+
* Accepts an absolute file path string or URL.
|
|
1826
|
+
*
|
|
1827
|
+
* A value of `'auto'` infers a base URL from the locations of the program's
|
|
1828
|
+
* own code.
|
|
1803
1829
|
*
|
|
1804
|
-
* A
|
|
1805
|
-
*
|
|
1806
|
-
*
|
|
1830
|
+
* A path stays absolute when it goes up more than two directories from the
|
|
1831
|
+
* base URL. A `file:` path also stays absolute when it shares no directory
|
|
1832
|
+
* with the base URL, including when it is on another Windows drive.
|
|
1807
1833
|
*
|
|
1808
1834
|
* A value of `null` leaves URLs absolute.
|
|
1809
1835
|
*
|
|
@@ -1822,13 +1848,41 @@ type ProfileToMdOptions = {
|
|
|
1822
1848
|
*/
|
|
1823
1849
|
sourceMaps?: SourceMap[] | Record<string, SourceMap>;
|
|
1824
1850
|
/**
|
|
1825
|
-
*
|
|
1826
|
-
*
|
|
1827
|
-
*
|
|
1851
|
+
* Receive the conversion's diagnostics: at `warn`, an option or input that
|
|
1852
|
+
* had no effect; at `info`, each decision made on your behalf; and at
|
|
1853
|
+
* `debug`, the reasoning behind each decision.
|
|
1854
|
+
*
|
|
1855
|
+
* Only defined methods are called, so `console` qualifies. The logger
|
|
1856
|
+
* receives only the levels {@link logLevel} enables.
|
|
1857
|
+
*/
|
|
1858
|
+
logger?: Logger;
|
|
1859
|
+
/**
|
|
1860
|
+
* The most verbose level {@link logger} receives.
|
|
1861
|
+
*
|
|
1862
|
+
* Defaults to `none`.
|
|
1863
|
+
*/
|
|
1864
|
+
logLevel?: LogLevel;
|
|
1865
|
+
/**
|
|
1866
|
+
* Returns an entry match, the name and location to match this entry by
|
|
1867
|
+
* across diffed profiles, or `undefined` to match by the entry's own name
|
|
1868
|
+
* and location.
|
|
1828
1869
|
*
|
|
1829
1870
|
* Only affects which entries are considered the same entity when diffing
|
|
1830
1871
|
* (e.g. profile functions); displayed names and locations, categorization,
|
|
1831
|
-
* and source map resolution
|
|
1872
|
+
* and source map resolution use the entry's real name and location, except
|
|
1873
|
+
* where a diff side merges functions.
|
|
1874
|
+
*
|
|
1875
|
+
* `profileToMd` and `profileToMdAsync` ignore it and log a warning.
|
|
1876
|
+
*
|
|
1877
|
+
* A call stack profile or call graph diff first pairs entries whose own names
|
|
1878
|
+
* and locations are equal, and pairs only the rest by their entry matches.
|
|
1879
|
+
* Where an entry match gives distinct entities one key, the diff still pairs
|
|
1880
|
+
* each entity whose identifier is unchanged with itself. Each side of a call
|
|
1881
|
+
* stack profile or heap snapshot diff merges its entities with no line that
|
|
1882
|
+
* share a match key and that the other side lacks into one entity, named and
|
|
1883
|
+
* located by the entry match, because the diff has no position to pair them
|
|
1884
|
+
* by. The entity it pairs with on the other side takes the same name and
|
|
1885
|
+
* location.
|
|
1832
1886
|
*
|
|
1833
1887
|
* Matched entries display the _current_ profile's name and location (not
|
|
1834
1888
|
* _base_).
|
|
@@ -1840,20 +1894,15 @@ type ProfileToMdOptions = {
|
|
|
1840
1894
|
* Returns a {@link FunctionCategory} per entry of a profile, as an array
|
|
1841
1895
|
* aligned with {@link entries} (index `i` categorizes entry `i`).
|
|
1842
1896
|
*
|
|
1843
|
-
* The categories are a closed set, so a category names the same thing
|
|
1844
|
-
* whichever origin wrote the input.
|
|
1845
|
-
*
|
|
1846
1897
|
* Used to compute:
|
|
1847
1898
|
* - A category breakdown in the Markdown output
|
|
1848
1899
|
* - The `baseURL` when using `baseURL: 'auto'`
|
|
1849
1900
|
* - Which entries to show in {@link defaultShowEntry}
|
|
1850
1901
|
*
|
|
1851
|
-
* Called once per profile with all its {@link entries}.
|
|
1852
|
-
* up front lets the categorizer decide from the full set rather than per
|
|
1853
|
-
* entry in isolation.
|
|
1902
|
+
* Called once per profile with all its {@link entries}.
|
|
1854
1903
|
*
|
|
1855
|
-
* Doesn't apply to heap snapshots
|
|
1856
|
-
*
|
|
1904
|
+
* Doesn't apply to heap snapshots, which record their own node categories,
|
|
1905
|
+
* or to traces, whose events the origin categorizes.
|
|
1857
1906
|
*
|
|
1858
1907
|
* Defaults to {@link defaultCategorizeFunctions}.
|
|
1859
1908
|
*/
|
|
@@ -1867,55 +1916,96 @@ type ProfileToMdOptions = {
|
|
|
1867
1916
|
*/
|
|
1868
1917
|
showEntry?: (entry: DeepReadonly<AggregatedProfileEntry>, context: ProfileToMdContext) => boolean;
|
|
1869
1918
|
};
|
|
1919
|
+
/**
|
|
1920
|
+
* The name and location overrides an entry's match key is built from, with the
|
|
1921
|
+
* identifiers that differ per run or build stripped.
|
|
1922
|
+
*
|
|
1923
|
+
* Only affects matching; the entry's displayed name and location are
|
|
1924
|
+
* unchanged.
|
|
1925
|
+
*/
|
|
1926
|
+
type EntryMatch = {
|
|
1927
|
+
/** The name to match by. Omit to match by the entry's name. */
|
|
1928
|
+
name?: string;
|
|
1929
|
+
/**
|
|
1930
|
+
* The location to match by, as a URL, file path, or logical name string.
|
|
1931
|
+
* Omit to match by the entry's location. An empty string matches by name
|
|
1932
|
+
* alone.
|
|
1933
|
+
*/
|
|
1934
|
+
location?: string;
|
|
1935
|
+
};
|
|
1870
1936
|
/** {@link ProfileToMdOptions} with defaults applied. */
|
|
1871
1937
|
type NormalizedProfileToMdOptions = {
|
|
1872
1938
|
topN: number;
|
|
1873
1939
|
minCategoryShare: number;
|
|
1874
1940
|
baseURL: URL | `auto` | undefined;
|
|
1875
1941
|
sourceMaps: NormalizedSourceMaps;
|
|
1942
|
+
logger: Logger;
|
|
1876
1943
|
entryMatchKeys: (entry: ProfileEntry, context: ProfileToMdContext) => EntryMatchKeys;
|
|
1877
1944
|
categorizeFunctions: (entries: readonly ProfileEntry[], context: ProfileToMdContext) => readonly FunctionCategory[];
|
|
1878
1945
|
showEntry: (entry: DeepReadonly<AggregatedProfileEntry>, context: ProfileToMdContext) => boolean;
|
|
1879
1946
|
};
|
|
1880
1947
|
/**
|
|
1881
|
-
*
|
|
1882
|
-
*
|
|
1883
|
-
* Everything except `baseURL`, which only affects formatting and, for `'auto'`,
|
|
1884
|
-
* is resolvable only after aggregation (from the aggregated entries). The
|
|
1885
|
-
* omission keeps aggregation logic from depending on it.
|
|
1948
|
+
* Omits the options that only affect formatting, so aggregation cannot depend
|
|
1949
|
+
* on them. `baseURL: 'auto'` resolves only from the aggregated entries.
|
|
1886
1950
|
*/
|
|
1887
|
-
type AggregationProfileToMdOptions = Omit<NormalizedProfileToMdOptions, `baseURL`>;
|
|
1951
|
+
type AggregationProfileToMdOptions = Omit<NormalizedProfileToMdOptions, `baseURL` | `sourceMaps`>;
|
|
1888
1952
|
/**
|
|
1889
|
-
* The options formatting code receives.
|
|
1890
|
-
*
|
|
1891
1953
|
* {@link NormalizedProfileToMdOptions} with `'auto'` resolved to a concrete
|
|
1892
|
-
* base URL (or `undefined` when nothing qualified for inference)
|
|
1954
|
+
* base URL (or `undefined` when nothing qualified for inference), and the
|
|
1955
|
+
* source maps wrapped in a resolver that records one conversion's outcomes.
|
|
1893
1956
|
*/
|
|
1894
1957
|
type FormattingProfileToMdOptions = AggregationProfileToMdOptions & {
|
|
1895
1958
|
baseURL: URL | undefined;
|
|
1959
|
+
/**
|
|
1960
|
+
* A diff's base side's own base URL, for the locations below it, when the
|
|
1961
|
+
* sides' base URLs differ only by what an entry match removes.
|
|
1962
|
+
* {@link baseURL} applies to every other location.
|
|
1963
|
+
*/
|
|
1964
|
+
baseSideBaseURL?: URL;
|
|
1965
|
+
sourceMaps: SourceMapResolver;
|
|
1966
|
+
/**
|
|
1967
|
+
* Whether a diffed entity's base and current sources are one source.
|
|
1968
|
+
* Defaults to whether they are the same source reference.
|
|
1969
|
+
*/
|
|
1970
|
+
isSameMatchedSource?: (base: SourceLocation, current: SourceLocation) => boolean;
|
|
1971
|
+
};
|
|
1972
|
+
/** A single entry in a formatted profile. */
|
|
1973
|
+
type ProfileEntry = {
|
|
1974
|
+
/** The name of the entity corresponding to this entry (e.g. a function name). */
|
|
1975
|
+
name?: string;
|
|
1976
|
+
/**
|
|
1977
|
+
* The location where the entity corresponding to this entry was defined: a
|
|
1978
|
+
* file, or a logical name such as a JVM class or a BEAM module when the
|
|
1979
|
+
* runtime reports no file. Undefined if unknown.
|
|
1980
|
+
*/
|
|
1981
|
+
location?: SourceLocation;
|
|
1982
|
+
};
|
|
1983
|
+
type ProfileToMdContext = {
|
|
1984
|
+
format: Format;
|
|
1985
|
+
origin: Origin;
|
|
1896
1986
|
};
|
|
1897
1987
|
/**
|
|
1898
1988
|
* The default {@link ProfileToMdOptions.matchEntry}.
|
|
1899
1989
|
*
|
|
1900
|
-
*
|
|
1901
|
-
*
|
|
1902
|
-
*
|
|
1990
|
+
* Builds the origin's entry match for the entry, stripping the origin's known
|
|
1991
|
+
* run-varying identifiers (e.g. Rust build hashes for `pprof-rs`, JVM runtime
|
|
1992
|
+
* addresses for `jdk`), or returns `undefined` if the entry contains none.
|
|
1903
1993
|
*/
|
|
1904
|
-
declare const defaultMatchEntry: (entry: DeepReadonly<ProfileEntry>, { origin }: ProfileToMdContext) => EntryMatch | undefined;
|
|
1994
|
+
export declare const defaultMatchEntry: (entry: DeepReadonly<ProfileEntry>, { origin }: ProfileToMdContext) => EntryMatch | undefined;
|
|
1905
1995
|
/**
|
|
1906
1996
|
* The default {@link ProfileToMdOptions.categorizeFunctions}.
|
|
1907
1997
|
*
|
|
1908
1998
|
* Applies the library's origin-aware categorization to each entry.
|
|
1909
1999
|
*/
|
|
1910
|
-
declare const defaultCategorizeFunctions: (entries: readonly DeepReadonly<ProfileEntry>[], { origin }: ProfileToMdContext) => FunctionCategory[];
|
|
2000
|
+
export declare const defaultCategorizeFunctions: (entries: readonly DeepReadonly<ProfileEntry>[], { origin }: ProfileToMdContext) => FunctionCategory[];
|
|
1911
2001
|
/**
|
|
1912
|
-
*
|
|
2002
|
+
* The default {@link ProfileToMdOptions.showEntry}.
|
|
1913
2003
|
*
|
|
1914
2004
|
* Excludes synthetic entries, which correspond to nothing in the profiled
|
|
1915
2005
|
* program. Every function it ran is shown, and each ranking breaks down by
|
|
1916
2006
|
* category, so a reader chooses which code to read.
|
|
1917
2007
|
*/
|
|
1918
|
-
declare const defaultShowEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
|
|
2008
|
+
export declare const defaultShowEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
|
|
1919
2009
|
/**
|
|
1920
2010
|
* Returns true if the entry is synthetic.
|
|
1921
2011
|
*
|
|
@@ -1925,23 +2015,1823 @@ declare const defaultShowEntry: (entry: DeepReadonly<AggregatedProfileEntry>) =>
|
|
|
1925
2015
|
* A heap snapshot node holding text takes the text as its name, so a string
|
|
1926
2016
|
* whose value equals a synthetic name is not a synthetic entry.
|
|
1927
2017
|
*/
|
|
1928
|
-
declare const isSyntheticEntry: ({ name, category }: DeepReadonly<AggregatedProfileEntry>) => boolean;
|
|
1929
|
-
|
|
1930
|
-
|
|
2018
|
+
export declare const isSyntheticEntry: ({ name, category }: DeepReadonly<AggregatedProfileEntry>) => boolean;
|
|
2019
|
+
/**
|
|
2020
|
+
* The keys an entry is paired by across a diff's two sides, derived from its
|
|
2021
|
+
* {@link EntryMatch}.
|
|
2022
|
+
*/
|
|
2023
|
+
type EntryMatchKeys = {
|
|
2024
|
+
/**
|
|
2025
|
+
* The key pairing entries by their entry match's name alone, for entities
|
|
2026
|
+
* whose location varies between profiles of the same program.
|
|
2027
|
+
*/
|
|
2028
|
+
name: string;
|
|
2029
|
+
/**
|
|
2030
|
+
* The source reference ID the entry match pairs the entry by, or the
|
|
2031
|
+
* entry's own. Empty when the entry match pairs by name alone.
|
|
2032
|
+
*/
|
|
2033
|
+
location: string | undefined;
|
|
2034
|
+
nameAndLocation: string;
|
|
2035
|
+
/**
|
|
2036
|
+
* The key built from the entry's own name and location, ignoring its
|
|
2037
|
+
* {@link EntryMatch}.
|
|
2038
|
+
*/
|
|
2039
|
+
ownNameAndLocation: string;
|
|
2040
|
+
};
|
|
2041
|
+
type SourceLocation = SourceReference & {
|
|
2042
|
+
/** The 1-based line number in the referenced source. */
|
|
2043
|
+
line?: number;
|
|
2044
|
+
/** The 1-based column number in the referenced source. */
|
|
2045
|
+
column?: number;
|
|
2046
|
+
};
|
|
2047
|
+
/** A reference to where a function is defined. */
|
|
2048
|
+
type SourceReference = FileReference | LogicalReference;
|
|
2049
|
+
type FileReference = {
|
|
2050
|
+
type: `absolute`;
|
|
2051
|
+
url: URL;
|
|
2052
|
+
} | {
|
|
2053
|
+
type: `relative`;
|
|
2054
|
+
path: string;
|
|
2055
|
+
};
|
|
2056
|
+
/**
|
|
2057
|
+
* A named class, module, namespace, assembly, or native library (e.g.
|
|
2058
|
+
* `java.util.HashMap`).
|
|
2059
|
+
*/
|
|
2060
|
+
type LogicalReference = {
|
|
2061
|
+
type: `logical`;
|
|
2062
|
+
name: string;
|
|
2063
|
+
};
|
|
2064
|
+
/**
|
|
2065
|
+
* A source reference as the parser records it, before resolution to a
|
|
2066
|
+
* {@link SourceReference}.
|
|
2067
|
+
*/
|
|
2068
|
+
type UnresolvedSourceReference = {
|
|
2069
|
+
type: `file`;
|
|
2070
|
+
urlOrPath: string;
|
|
2071
|
+
} | {
|
|
2072
|
+
type: `logical`;
|
|
2073
|
+
/**
|
|
2074
|
+
* The name of a class, module, namespace, assembly, or native library.
|
|
2075
|
+
*/
|
|
2076
|
+
name: string;
|
|
2077
|
+
};
|
|
2078
|
+
type SourcePosition = {
|
|
2079
|
+
/** The 1-based line number in the referenced source. */
|
|
2080
|
+
line: number;
|
|
2081
|
+
/** The 1-based column number in the referenced source. */
|
|
2082
|
+
column?: number;
|
|
2083
|
+
};
|
|
2084
|
+
type InputAggregator<Aggregated> = {
|
|
2085
|
+
/**
|
|
2086
|
+
* Passes this input's origin-detection entries to the raw input's shared
|
|
2087
|
+
* detector.
|
|
2088
|
+
*
|
|
2089
|
+
* May be skipped when the detector decides early.
|
|
2090
|
+
*/
|
|
2091
|
+
detectOrigin: (detector: OriginDetector) => void;
|
|
2092
|
+
/**
|
|
2093
|
+
* Aggregates the input under the raw input's resolved context. On a side of
|
|
2094
|
+
* a diff, {@link otherSide} is the other side's input that the diff pairs
|
|
2095
|
+
* with this one.
|
|
2096
|
+
*/
|
|
2097
|
+
aggregate: (options: AggregationProfileToMdOptions, context: ProfileToMdContext, otherSide?: OtherSideInput) => Aggregated;
|
|
2098
|
+
};
|
|
2099
|
+
/** An input's aggregator, under the context of the raw input it is part of. */
|
|
2100
|
+
type OtherSideInput = {
|
|
2101
|
+
aggregator: InputAggregator<unknown>;
|
|
2102
|
+
context: ProfileToMdContext;
|
|
2103
|
+
};
|
|
2104
|
+
/** An aggregation of all observations within a call stack profile. */
|
|
2105
|
+
type AggregatedCallStackProfile = {
|
|
2106
|
+
type: `call-stack-profile`;
|
|
2107
|
+
/**
|
|
2108
|
+
* The context (format and resolved origin) this profile was aggregated under.
|
|
2109
|
+
* Match keys vary by origin, so build each diffed side's keys under that
|
|
2110
|
+
* side's own context. Sides that resolved different origins can normalize
|
|
2111
|
+
* match keys differently and miss matches.
|
|
2112
|
+
*/
|
|
2113
|
+
context: ProfileToMdContext;
|
|
2114
|
+
/** Metrics recorded in this profile. */
|
|
2115
|
+
metrics: Metric[];
|
|
2116
|
+
/**
|
|
2117
|
+
* What one unit of {@link Observation.count} measures: a periodic sample of
|
|
2118
|
+
* the call stack, an entry into a function, an allocated object, a
|
|
2119
|
+
* microsecond of traced time.
|
|
2120
|
+
*
|
|
2121
|
+
* With a count metric, the output formats the count as a count and states a
|
|
2122
|
+
* rate per one of the things counted. With a time or size metric, the output
|
|
2123
|
+
* formats the count as that quantity and states no rate, since a quantity
|
|
2124
|
+
* has no unit to state a rate per.
|
|
2125
|
+
*
|
|
2126
|
+
* `null` when the counts measure nothing, so the profile reports its metrics
|
|
2127
|
+
* alone.
|
|
2128
|
+
*/
|
|
2129
|
+
countMetric: Metric | null;
|
|
2130
|
+
/** The number of counted units recorded within this profile. */
|
|
2131
|
+
totalCount: number;
|
|
2132
|
+
/**
|
|
2133
|
+
* For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
|
|
2134
|
+
* values from observations recorded within this profile.
|
|
2135
|
+
*/
|
|
2136
|
+
totalValues: Float64Array;
|
|
2137
|
+
/**
|
|
2138
|
+
* For each metric in {@link AggregatedCallStackProfile.metrics}, the average
|
|
2139
|
+
* metric value per counted unit (total value ÷ total count).
|
|
2140
|
+
*
|
|
2141
|
+
* Meaningless, and unreported, for a profile whose counts measure nothing or
|
|
2142
|
+
* that counted nothing.
|
|
2143
|
+
*/
|
|
2144
|
+
rates: Float64Array;
|
|
2145
|
+
/**
|
|
2146
|
+
* Function category to values and count for calls of functions with
|
|
2147
|
+
* that category.
|
|
2148
|
+
*/
|
|
2149
|
+
categoryToMetrics: Map<FunctionCategory, AggregatedCallStackProfileCategoryMetrics>;
|
|
2150
|
+
/** Aggregated data for all functions called in this profile. */
|
|
2151
|
+
functions: AggregatedCallStackProfileFunction[];
|
|
2152
|
+
/** Aggregated data for all call stacks encountered in this profile. */
|
|
2153
|
+
callStacks: AggregatedCallStackProfileCallStack[];
|
|
2154
|
+
};
|
|
2155
|
+
declare class CallStackProfileAggregator implements InputAggregator<AggregatedCallStackProfile> {
|
|
2156
|
+
#private;
|
|
2157
|
+
constructor(profile: CallStackProfile);
|
|
2158
|
+
detectOrigin(detector: OriginDetector): void;
|
|
2159
|
+
/** The identity keys of the input's functions with no line. */
|
|
2160
|
+
linelessFunctionKeys(context: ProfileToMdContext): ReadonlySet<string>;
|
|
2161
|
+
aggregate(options: AggregationProfileToMdOptions, context: ProfileToMdContext, otherSide?: OtherSideInput): AggregatedCallStackProfile;
|
|
2162
|
+
}
|
|
2163
|
+
/**
|
|
2164
|
+
* An aggregation of data from every observation of functions with a given
|
|
2165
|
+
* category within a profile.
|
|
2166
|
+
*/
|
|
2167
|
+
type AggregatedCallStackProfileCategoryMetrics = {
|
|
2168
|
+
/** The number of observations recorded for functions with this category. */
|
|
2169
|
+
count: number;
|
|
2170
|
+
/**
|
|
2171
|
+
* For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
|
|
2172
|
+
* values from observations recorded for functions with this category.
|
|
2173
|
+
*/
|
|
2174
|
+
values: Float64Array;
|
|
2175
|
+
};
|
|
2176
|
+
/**
|
|
2177
|
+
* An aggregation of data from every observation involving a given function
|
|
2178
|
+
* within a profile.
|
|
2179
|
+
*/
|
|
2180
|
+
type AggregatedCallStackProfileFunction = {
|
|
2181
|
+
type: `function`;
|
|
2182
|
+
/** An index that uniquely identifies this function. */
|
|
2183
|
+
id: number;
|
|
2184
|
+
name: string;
|
|
2185
|
+
/** Where the function was defined, if known. */
|
|
2186
|
+
location?: SourceLocation;
|
|
2187
|
+
/**
|
|
2188
|
+
* Whether the function merges several functions of a diff side that have no
|
|
2189
|
+
* line and share a match key, so the entry match names and locates it.
|
|
2190
|
+
*/
|
|
2191
|
+
merged?: boolean;
|
|
2192
|
+
category: FunctionCategory;
|
|
2193
|
+
/**
|
|
2194
|
+
* The number of observations recorded directly within the function's body,
|
|
2195
|
+
* excluding its callees.
|
|
2196
|
+
*/
|
|
2197
|
+
selfCount: number;
|
|
2198
|
+
/**
|
|
2199
|
+
* The number of observations recorded directly within the function's body
|
|
2200
|
+
* _and_ all its callees.
|
|
2201
|
+
*/
|
|
2202
|
+
totalCount: number;
|
|
2203
|
+
/**
|
|
2204
|
+
* For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
|
|
2205
|
+
* values from observations recorded directly within the function's body,
|
|
2206
|
+
* excluding its callees.
|
|
2207
|
+
*/
|
|
2208
|
+
selfValues: Float64Array;
|
|
2209
|
+
/**
|
|
2210
|
+
* For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
|
|
2211
|
+
* values from observations recorded directly within the function's body _and_
|
|
2212
|
+
* all its callees.
|
|
2213
|
+
*/
|
|
2214
|
+
totalValues: Float64Array;
|
|
2215
|
+
/** 1-based line number to values and count for that line. */
|
|
2216
|
+
lineToMetrics: Map<number, AggregatedCallStackProfileLineMetrics>;
|
|
2217
|
+
/**
|
|
2218
|
+
* Direct caller id to values and count with that caller's calls to
|
|
2219
|
+
* this function.
|
|
2220
|
+
*/
|
|
2221
|
+
callerIdToMetrics: Map<number, AggregatedCallStackProfileCallerMetrics>;
|
|
2222
|
+
/**
|
|
2223
|
+
* Direct callee id to values and count for that callee's calls where
|
|
2224
|
+
* this function was a direct or transitive caller.
|
|
2225
|
+
*/
|
|
2226
|
+
calleeIdToMetrics: Map<number, AggregatedCallStackProfileCalleeMetrics>;
|
|
2227
|
+
};
|
|
2228
|
+
/**
|
|
2229
|
+
* An aggregation of observations recorded at a given line within a function's
|
|
2230
|
+
* body.
|
|
2231
|
+
*/
|
|
2232
|
+
type AggregatedCallStackProfileLineMetrics = {
|
|
2233
|
+
/**
|
|
2234
|
+
* The number of observations recorded directly within the function's body at
|
|
2235
|
+
* this line.
|
|
2236
|
+
*/
|
|
2237
|
+
count: number;
|
|
2238
|
+
/**
|
|
2239
|
+
* For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
|
|
2240
|
+
* values from observations recorded directly within the function's body at
|
|
2241
|
+
* this line.
|
|
2242
|
+
*/
|
|
2243
|
+
values: Float64Array;
|
|
2244
|
+
};
|
|
2245
|
+
/**
|
|
2246
|
+
* An aggregation of observations recorded directly within a function's body
|
|
2247
|
+
* with a given direct caller.
|
|
2248
|
+
*/
|
|
2249
|
+
type AggregatedCallStackProfileCallerMetrics = {
|
|
2250
|
+
/** The caller corresponding to the ID. */
|
|
2251
|
+
caller: AggregatedCallStackProfileFunction;
|
|
2252
|
+
/**
|
|
2253
|
+
* The number of observations recorded directly within the function's body
|
|
2254
|
+
* with this caller.
|
|
2255
|
+
*/
|
|
2256
|
+
selfCount: number;
|
|
2257
|
+
/**
|
|
2258
|
+
* For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
|
|
2259
|
+
* values from observations recorded directly within the function's body with
|
|
2260
|
+
* this caller.
|
|
2261
|
+
*/
|
|
2262
|
+
selfValues: Float64Array;
|
|
2263
|
+
};
|
|
2264
|
+
/**
|
|
2265
|
+
* An aggregation of observations recorded within a function's body, _and_ all
|
|
2266
|
+
* its callees, with a given direct callee.
|
|
2267
|
+
*/
|
|
2268
|
+
type AggregatedCallStackProfileCalleeMetrics = {
|
|
2269
|
+
/** The callee corresponding to the ID. */
|
|
2270
|
+
callee: AggregatedCallStackProfileFunction;
|
|
2271
|
+
/**
|
|
2272
|
+
* The number of observations recorded directly within the function's body,
|
|
2273
|
+
* _and_ all its callees, with this callee.
|
|
2274
|
+
*/
|
|
2275
|
+
totalCount: number;
|
|
2276
|
+
/**
|
|
2277
|
+
* For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
|
|
2278
|
+
* values from observations recorded directly within the function's body,
|
|
2279
|
+
* _and_ all its callees, with this callee.
|
|
2280
|
+
*/
|
|
2281
|
+
totalValues: Float64Array;
|
|
2282
|
+
/**
|
|
2283
|
+
* Internal aggregation bookkeeping: the epoch of the most recent call stack
|
|
2284
|
+
* whose total this frame pair was counted into, so one that recurs within
|
|
2285
|
+
* one call stack is counted just once.
|
|
2286
|
+
*/
|
|
2287
|
+
lastSeenEpoch: number;
|
|
2288
|
+
};
|
|
2289
|
+
/**
|
|
2290
|
+
* An aggregation of data from every observation involving a given function call
|
|
2291
|
+
* stack within a profile.
|
|
2292
|
+
*/
|
|
2293
|
+
type AggregatedCallStackProfileCallStack = {
|
|
2294
|
+
/** The functions on the call stack in callee to caller order. */
|
|
2295
|
+
frames: AggregatedCallStackProfileFunction[];
|
|
2296
|
+
/** @see {@link Observation.truncated} */
|
|
2297
|
+
truncated: boolean;
|
|
2298
|
+
/** The number of observations recorded with this exact call stack. */
|
|
2299
|
+
selfCount: number;
|
|
2300
|
+
/**
|
|
2301
|
+
* For each metric in {@link AggregatedCallStackProfile.metrics}, the sum of
|
|
2302
|
+
* values from observations recorded with this exact call stack.
|
|
2303
|
+
*/
|
|
2304
|
+
selfValues: Float64Array;
|
|
2305
|
+
};
|
|
2306
|
+
// ## Interfaces
|
|
2307
|
+
/**
|
|
2308
|
+
* Info associated with nodes by the ecosystem.
|
|
2309
|
+
*
|
|
2310
|
+
* This space is guaranteed to never be specified by unist or specifications
|
|
2311
|
+
* implementing unist.
|
|
2312
|
+
* But you can use it in utilities and plugins to store data.
|
|
2313
|
+
*
|
|
2314
|
+
* This type can be augmented to register custom data.
|
|
2315
|
+
* For example:
|
|
2316
|
+
*
|
|
2317
|
+
* ```ts
|
|
2318
|
+
* declare module 'unist' {
|
|
2319
|
+
* interface Data {
|
|
2320
|
+
* // `someNode.data.myId` is typed as `number | undefined`
|
|
2321
|
+
* myId?: number | undefined
|
|
2322
|
+
* }
|
|
2323
|
+
* }
|
|
2324
|
+
* ```
|
|
2325
|
+
*/
|
|
2326
|
+
interface Data$1 {}
|
|
2327
|
+
/**
|
|
2328
|
+
* One place in a source file.
|
|
2329
|
+
*/
|
|
2330
|
+
interface Point {
|
|
2331
|
+
/**
|
|
2332
|
+
* Line in a source file (1-indexed integer).
|
|
2333
|
+
*/
|
|
2334
|
+
line: number;
|
|
2335
|
+
/**
|
|
2336
|
+
* Column in a source file (1-indexed integer).
|
|
2337
|
+
*/
|
|
2338
|
+
column: number;
|
|
2339
|
+
/**
|
|
2340
|
+
* Character in a source file (0-indexed integer).
|
|
2341
|
+
*/
|
|
2342
|
+
offset?: number | undefined;
|
|
2343
|
+
}
|
|
2344
|
+
/**
|
|
2345
|
+
* Position of a node in a source document.
|
|
2346
|
+
*
|
|
2347
|
+
* A position is a range between two points.
|
|
2348
|
+
*/
|
|
2349
|
+
interface Position {
|
|
2350
|
+
/**
|
|
2351
|
+
* Place of the first character of the parsed source region.
|
|
2352
|
+
*/
|
|
2353
|
+
start: Point;
|
|
2354
|
+
/**
|
|
2355
|
+
* Place of the first character after the parsed source region.
|
|
2356
|
+
*/
|
|
2357
|
+
end: Point;
|
|
2358
|
+
}
|
|
2359
|
+
/**
|
|
2360
|
+
* Abstract unist node.
|
|
2361
|
+
*
|
|
2362
|
+
* The syntactic unit in unist syntax trees are called nodes.
|
|
2363
|
+
*
|
|
2364
|
+
* This interface is supposed to be extended.
|
|
2365
|
+
* If you can use {@link Literal} or {@link Parent}, you should.
|
|
2366
|
+
* But for example in markdown, a `thematicBreak` (`***`), is neither literal
|
|
2367
|
+
* nor parent, but still a node.
|
|
2368
|
+
*/
|
|
2369
|
+
interface Node$1 {
|
|
2370
|
+
/**
|
|
2371
|
+
* Node type.
|
|
2372
|
+
*/
|
|
2373
|
+
type: string;
|
|
2374
|
+
/**
|
|
2375
|
+
* Info from the ecosystem.
|
|
2376
|
+
*/
|
|
2377
|
+
data?: Data$1 | undefined;
|
|
2378
|
+
/**
|
|
2379
|
+
* Position of a node in a source document.
|
|
2380
|
+
*
|
|
2381
|
+
* Nodes that are generated (not in the original source document) must not
|
|
2382
|
+
* have a position.
|
|
2383
|
+
*/
|
|
2384
|
+
position?: Position | undefined;
|
|
2385
|
+
}
|
|
2386
|
+
// ## Enumeration
|
|
2387
|
+
/**
|
|
2388
|
+
* How phrasing content is aligned
|
|
2389
|
+
* ({@link https://drafts.csswg.org/css-text/ | [CSSTEXT]}).
|
|
2390
|
+
*
|
|
2391
|
+
* * `'left'`: See the
|
|
2392
|
+
* {@link https://drafts.csswg.org/css-text/#valdef-text-align-left | left}
|
|
2393
|
+
* value of the `text-align` CSS property
|
|
2394
|
+
* * `'right'`: See the
|
|
2395
|
+
* {@link https://drafts.csswg.org/css-text/#valdef-text-align-right | right}
|
|
2396
|
+
* value of the `text-align` CSS property
|
|
2397
|
+
* * `'center'`: See the
|
|
2398
|
+
* {@link https://drafts.csswg.org/css-text/#valdef-text-align-center | center}
|
|
2399
|
+
* value of the `text-align` CSS property
|
|
2400
|
+
* * `null`: phrasing content is aligned as defined by the host environment
|
|
2401
|
+
*
|
|
2402
|
+
* Used in GFM tables.
|
|
2403
|
+
*/
|
|
2404
|
+
type AlignType = "center" | "left" | "right" | null;
|
|
2405
|
+
/**
|
|
2406
|
+
* Explicitness of a reference.
|
|
2407
|
+
*
|
|
2408
|
+
* `'shortcut'`: the reference is implicit, its identifier inferred from its
|
|
2409
|
+
* content
|
|
2410
|
+
* `'collapsed'`: the reference is explicit, its identifier inferred from its
|
|
2411
|
+
* content
|
|
2412
|
+
* `'full'`: the reference is explicit, its identifier explicitly set
|
|
2413
|
+
*/
|
|
2414
|
+
type ReferenceType = "shortcut" | "collapsed" | "full";
|
|
2415
|
+
// ## Mixin
|
|
2416
|
+
/**
|
|
2417
|
+
* Node with a fallback.
|
|
2418
|
+
*/
|
|
2419
|
+
interface Alternative {
|
|
2420
|
+
/**
|
|
2421
|
+
* Equivalent content for environments that cannot represent the node as
|
|
2422
|
+
* intended.
|
|
2423
|
+
*/
|
|
2424
|
+
alt?: string | null | undefined;
|
|
2425
|
+
}
|
|
2426
|
+
/**
|
|
2427
|
+
* Internal relation from one node to another.
|
|
2428
|
+
*
|
|
2429
|
+
* Whether the value of `identifier` is expected to be a unique identifier or
|
|
2430
|
+
* not depends on the type of node including the Association.
|
|
2431
|
+
* An example of this is that they should be unique on {@link Definition},
|
|
2432
|
+
* whereas multiple {@link LinkReference}s can be non-unique to be associated
|
|
2433
|
+
* with one definition.
|
|
2434
|
+
*/
|
|
2435
|
+
interface Association {
|
|
2436
|
+
/**
|
|
2437
|
+
* Relation of association.
|
|
2438
|
+
*
|
|
2439
|
+
* `identifier` is a source value: character escapes and character
|
|
2440
|
+
* references are not parsed.
|
|
2441
|
+
*
|
|
2442
|
+
* It can match another node.
|
|
2443
|
+
*
|
|
2444
|
+
* Its value must be normalized.
|
|
2445
|
+
* To normalize a value, collapse markdown whitespace (`[\t\n\r ]+`) to a space,
|
|
2446
|
+
* trim the optional initial and/or final space, and perform Unicode-aware
|
|
2447
|
+
* case-folding.
|
|
2448
|
+
*/
|
|
2449
|
+
identifier: string;
|
|
2450
|
+
/**
|
|
2451
|
+
* Relation of association, in parsed form.
|
|
2452
|
+
*
|
|
2453
|
+
* `label` is a `string` value: it works just like `title` on {@link Link}
|
|
2454
|
+
* or a `lang` on {@link Code}: character escapes and character references
|
|
2455
|
+
* are parsed.
|
|
2456
|
+
*
|
|
2457
|
+
* It can match another node.
|
|
2458
|
+
*/
|
|
2459
|
+
label?: string | null | undefined;
|
|
2460
|
+
}
|
|
2461
|
+
/**
|
|
2462
|
+
* Marker that is associated to another node.
|
|
2463
|
+
*/
|
|
2464
|
+
interface Reference extends Association {
|
|
2465
|
+
/**
|
|
2466
|
+
* Explicitness of the reference.
|
|
2467
|
+
*/
|
|
2468
|
+
referenceType: ReferenceType;
|
|
2469
|
+
}
|
|
2470
|
+
/**
|
|
2471
|
+
* Reference to resource.
|
|
2472
|
+
*/
|
|
2473
|
+
interface Resource {
|
|
2474
|
+
/**
|
|
2475
|
+
* URL to the referenced resource.
|
|
2476
|
+
*/
|
|
2477
|
+
url: string;
|
|
2478
|
+
/**
|
|
2479
|
+
* Advisory information for the resource, such as would be appropriate for
|
|
2480
|
+
* a tooltip.
|
|
2481
|
+
*/
|
|
2482
|
+
title?: string | null | undefined;
|
|
2483
|
+
}
|
|
2484
|
+
// ## Interfaces
|
|
2485
|
+
/**
|
|
2486
|
+
* Info associated with mdast nodes by the ecosystem.
|
|
2487
|
+
*
|
|
2488
|
+
* This space is guaranteed to never be specified by unist or mdast.
|
|
2489
|
+
* But you can use it in utilities and plugins to store data.
|
|
2490
|
+
*
|
|
2491
|
+
* This type can be augmented to register custom data.
|
|
2492
|
+
* For example:
|
|
2493
|
+
*
|
|
2494
|
+
* ```ts
|
|
2495
|
+
* declare module 'mdast' {
|
|
2496
|
+
* interface Data {
|
|
2497
|
+
* // `someNode.data.myId` is typed as `number | undefined`
|
|
2498
|
+
* myId?: number | undefined
|
|
2499
|
+
* }
|
|
2500
|
+
* }
|
|
2501
|
+
* ```
|
|
2502
|
+
*/
|
|
2503
|
+
interface Data extends Data$1 {}
|
|
2504
|
+
// ## Content maps
|
|
2505
|
+
/**
|
|
2506
|
+
* Union of registered mdast nodes that can occur where block content is
|
|
2507
|
+
* expected.
|
|
2508
|
+
*
|
|
2509
|
+
* To register custom mdast nodes, add them to {@link BlockContentMap}.
|
|
2510
|
+
* They will be automatically added here.
|
|
2511
|
+
*/
|
|
2512
|
+
type BlockContent = BlockContentMap[keyof BlockContentMap];
|
|
2513
|
+
/**
|
|
2514
|
+
* Registry of all mdast nodes that can occur where {@link BlockContent} is
|
|
2515
|
+
* expected.
|
|
2516
|
+
*
|
|
2517
|
+
* This interface can be augmented to register custom node types:
|
|
2518
|
+
*
|
|
2519
|
+
* ```ts
|
|
2520
|
+
* declare module 'mdast' {
|
|
2521
|
+
* interface BlockContentMap {
|
|
2522
|
+
* // Allow using MDX ESM nodes defined by `remark-mdx`.
|
|
2523
|
+
* mdxjsEsm: MdxjsEsm;
|
|
2524
|
+
* }
|
|
2525
|
+
* }
|
|
2526
|
+
* ```
|
|
2527
|
+
*
|
|
2528
|
+
* For a union of all block content, see {@link RootContent}.
|
|
2529
|
+
*/
|
|
2530
|
+
interface BlockContentMap {
|
|
2531
|
+
blockquote: Blockquote;
|
|
2532
|
+
code: Code;
|
|
2533
|
+
heading: Heading;
|
|
2534
|
+
html: Html;
|
|
2535
|
+
list: List;
|
|
2536
|
+
paragraph: Paragraph;
|
|
2537
|
+
table: Table;
|
|
2538
|
+
thematicBreak: ThematicBreak;
|
|
2539
|
+
}
|
|
2540
|
+
/**
|
|
2541
|
+
* Union of registered mdast nodes that can occur where definition content is
|
|
2542
|
+
* expected.
|
|
2543
|
+
*
|
|
2544
|
+
* To register custom mdast nodes, add them to {@link DefinitionContentMap}.
|
|
2545
|
+
* They will be automatically added here.
|
|
2546
|
+
*/
|
|
2547
|
+
type DefinitionContent = DefinitionContentMap[keyof DefinitionContentMap];
|
|
2548
|
+
/**
|
|
2549
|
+
* Registry of all mdast nodes that can occur where {@link DefinitionContent}
|
|
2550
|
+
* is expected.
|
|
2551
|
+
*
|
|
2552
|
+
* This interface can be augmented to register custom node types:
|
|
2553
|
+
*
|
|
2554
|
+
* ```ts
|
|
2555
|
+
* declare module 'mdast' {
|
|
2556
|
+
* interface DefinitionContentMap {
|
|
2557
|
+
* custom: Custom;
|
|
2558
|
+
* }
|
|
2559
|
+
* }
|
|
2560
|
+
* ```
|
|
2561
|
+
*
|
|
2562
|
+
* For a union of all definition content, see {@link RootContent}.
|
|
2563
|
+
*/
|
|
2564
|
+
interface DefinitionContentMap {
|
|
2565
|
+
definition: Definition;
|
|
2566
|
+
footnoteDefinition: FootnoteDefinition;
|
|
2567
|
+
}
|
|
2568
|
+
/**
|
|
2569
|
+
* Union of registered mdast nodes that can occur where list content is
|
|
2570
|
+
* expected.
|
|
2571
|
+
*
|
|
2572
|
+
* To register custom mdast nodes, add them to {@link ListContentMap}.
|
|
2573
|
+
* They will be automatically added here.
|
|
2574
|
+
*/
|
|
2575
|
+
type ListContent = ListContentMap[keyof ListContentMap];
|
|
2576
|
+
/**
|
|
2577
|
+
* Registry of all mdast nodes that can occur where {@link ListContent}
|
|
2578
|
+
* is expected.
|
|
2579
|
+
*
|
|
2580
|
+
* This interface can be augmented to register custom node types:
|
|
2581
|
+
*
|
|
2582
|
+
* ```ts
|
|
2583
|
+
* declare module 'mdast' {
|
|
2584
|
+
* interface ListContentMap {
|
|
2585
|
+
* custom: Custom;
|
|
2586
|
+
* }
|
|
2587
|
+
* }
|
|
2588
|
+
* ```
|
|
2589
|
+
*
|
|
2590
|
+
* For a union of all list content, see {@link RootContent}.
|
|
2591
|
+
*/
|
|
2592
|
+
interface ListContentMap {
|
|
2593
|
+
listItem: ListItem;
|
|
2594
|
+
}
|
|
2595
|
+
/**
|
|
2596
|
+
* Union of registered mdast nodes that can occur where phrasing content is
|
|
2597
|
+
* expected.
|
|
2598
|
+
*
|
|
2599
|
+
* To register custom mdast nodes, add them to {@link PhrasingContentMap}.
|
|
2600
|
+
* They will be automatically added here.
|
|
2601
|
+
*/
|
|
2602
|
+
type PhrasingContent = PhrasingContentMap[keyof PhrasingContentMap];
|
|
2603
|
+
/**
|
|
2604
|
+
* Registry of all mdast nodes that can occur where {@link PhrasingContent}
|
|
2605
|
+
* is expected.
|
|
2606
|
+
*
|
|
2607
|
+
* This interface can be augmented to register custom node types:
|
|
2608
|
+
*
|
|
2609
|
+
* ```ts
|
|
2610
|
+
* declare module 'mdast' {
|
|
2611
|
+
* interface PhrasingContentMap {
|
|
2612
|
+
* // Allow using MDX JSX (text) nodes defined by `remark-mdx`.
|
|
2613
|
+
* mdxJsxTextElement: MDXJSXTextElement;
|
|
2614
|
+
* }
|
|
2615
|
+
* }
|
|
2616
|
+
* ```
|
|
2617
|
+
*
|
|
2618
|
+
* For a union of all phrasing content, see {@link RootContent}.
|
|
2619
|
+
*/
|
|
2620
|
+
interface PhrasingContentMap {
|
|
2621
|
+
break: Break;
|
|
2622
|
+
delete: Delete;
|
|
2623
|
+
emphasis: Emphasis;
|
|
2624
|
+
footnoteReference: FootnoteReference;
|
|
2625
|
+
html: Html;
|
|
2626
|
+
image: Image;
|
|
2627
|
+
imageReference: ImageReference;
|
|
2628
|
+
inlineCode: InlineCode;
|
|
2629
|
+
link: Link;
|
|
2630
|
+
linkReference: LinkReference;
|
|
2631
|
+
strong: Strong;
|
|
2632
|
+
text: Text;
|
|
2633
|
+
}
|
|
2634
|
+
/**
|
|
2635
|
+
* Union of registered mdast nodes that can occur in {@link Root}.
|
|
2636
|
+
*
|
|
2637
|
+
* To register custom mdast nodes, add them to {@link RootContentMap}.
|
|
2638
|
+
* They will be automatically added here.
|
|
2639
|
+
*/
|
|
2640
|
+
type RootContent = RootContentMap[keyof RootContentMap];
|
|
2641
|
+
/**
|
|
2642
|
+
* Registry of all mdast nodes that can occur as children of {@link Root}.
|
|
2643
|
+
*
|
|
2644
|
+
* > **Note**: {@link Root} does not need to be an entire document.
|
|
2645
|
+
* > it can also be a fragment.
|
|
2646
|
+
*
|
|
2647
|
+
* This interface can be augmented to register custom node types:
|
|
2648
|
+
*
|
|
2649
|
+
* ```ts
|
|
2650
|
+
* declare module 'mdast' {
|
|
2651
|
+
* interface RootContentMap {
|
|
2652
|
+
* // Allow using toml nodes defined by `remark-frontmatter`.
|
|
2653
|
+
* toml: TOML;
|
|
2654
|
+
* }
|
|
2655
|
+
* }
|
|
2656
|
+
* ```
|
|
2657
|
+
*
|
|
2658
|
+
* For a union of all {@link Root} children, see {@link RootContent}.
|
|
2659
|
+
*/
|
|
2660
|
+
interface RootContentMap {
|
|
2661
|
+
blockquote: Blockquote;
|
|
2662
|
+
break: Break;
|
|
2663
|
+
code: Code;
|
|
2664
|
+
definition: Definition;
|
|
2665
|
+
delete: Delete;
|
|
2666
|
+
emphasis: Emphasis;
|
|
2667
|
+
footnoteDefinition: FootnoteDefinition;
|
|
2668
|
+
footnoteReference: FootnoteReference;
|
|
2669
|
+
heading: Heading;
|
|
2670
|
+
html: Html;
|
|
2671
|
+
image: Image;
|
|
2672
|
+
imageReference: ImageReference;
|
|
2673
|
+
inlineCode: InlineCode;
|
|
2674
|
+
link: Link;
|
|
2675
|
+
linkReference: LinkReference;
|
|
2676
|
+
list: List;
|
|
2677
|
+
listItem: ListItem;
|
|
2678
|
+
paragraph: Paragraph;
|
|
2679
|
+
strong: Strong;
|
|
2680
|
+
table: Table;
|
|
2681
|
+
tableCell: TableCell;
|
|
2682
|
+
tableRow: TableRow;
|
|
2683
|
+
text: Text;
|
|
2684
|
+
thematicBreak: ThematicBreak;
|
|
2685
|
+
yaml: Yaml;
|
|
2686
|
+
}
|
|
2687
|
+
/**
|
|
2688
|
+
* Union of registered mdast nodes that can occur where row content is
|
|
2689
|
+
* expected.
|
|
2690
|
+
*
|
|
2691
|
+
* To register custom mdast nodes, add them to {@link RowContentMap}.
|
|
2692
|
+
* They will be automatically added here.
|
|
2693
|
+
*/
|
|
2694
|
+
type RowContent = RowContentMap[keyof RowContentMap];
|
|
2695
|
+
/**
|
|
2696
|
+
* Registry of all mdast nodes that can occur where {@link RowContent}
|
|
2697
|
+
* is expected.
|
|
2698
|
+
*
|
|
2699
|
+
* This interface can be augmented to register custom node types:
|
|
2700
|
+
*
|
|
2701
|
+
* ```ts
|
|
2702
|
+
* declare module 'mdast' {
|
|
2703
|
+
* interface RowContentMap {
|
|
2704
|
+
* custom: Custom;
|
|
2705
|
+
* }
|
|
2706
|
+
* }
|
|
2707
|
+
* ```
|
|
2708
|
+
*
|
|
2709
|
+
* For a union of all row content, see {@link RootContent}.
|
|
2710
|
+
*/
|
|
2711
|
+
interface RowContentMap {
|
|
2712
|
+
tableCell: TableCell;
|
|
2713
|
+
}
|
|
2714
|
+
/**
|
|
2715
|
+
* Union of registered mdast nodes that can occur where table content is
|
|
2716
|
+
* expected.
|
|
2717
|
+
*
|
|
2718
|
+
* To register custom mdast nodes, add them to {@link TableContentMap}.
|
|
2719
|
+
* They will be automatically added here.
|
|
2720
|
+
*/
|
|
2721
|
+
type TableContent = TableContentMap[keyof TableContentMap];
|
|
2722
|
+
/**
|
|
2723
|
+
* Registry of all mdast nodes that can occur where {@link TableContent}
|
|
2724
|
+
* is expected.
|
|
2725
|
+
*
|
|
2726
|
+
* This interface can be augmented to register custom node types:
|
|
2727
|
+
*
|
|
2728
|
+
* ```ts
|
|
2729
|
+
* declare module 'mdast' {
|
|
2730
|
+
* interface TableContentMap {
|
|
2731
|
+
* custom: Custom;
|
|
2732
|
+
* }
|
|
2733
|
+
* }
|
|
2734
|
+
* ```
|
|
2735
|
+
*
|
|
2736
|
+
* For a union of all table content, see {@link RootContent}.
|
|
2737
|
+
*/
|
|
2738
|
+
interface TableContentMap {
|
|
2739
|
+
tableRow: TableRow;
|
|
2740
|
+
}
|
|
2741
|
+
// ## Abstract nodes
|
|
2742
|
+
/**
|
|
2743
|
+
* Abstract mdast node that contains the smallest possible value.
|
|
2744
|
+
*
|
|
2745
|
+
* This interface is supposed to be extended if you make custom mdast nodes.
|
|
2746
|
+
*
|
|
2747
|
+
* For a union of all registered mdast literals, see {@link Literals}.
|
|
2748
|
+
*/
|
|
2749
|
+
interface Literal extends Node {
|
|
2750
|
+
/**
|
|
2751
|
+
* Plain-text value.
|
|
2752
|
+
*/
|
|
2753
|
+
value: string;
|
|
2754
|
+
}
|
|
2755
|
+
/**
|
|
2756
|
+
* Abstract mdast node.
|
|
2757
|
+
*
|
|
2758
|
+
* This interface is supposed to be extended.
|
|
2759
|
+
* If you can use {@link Literal} or {@link Parent}, you should.
|
|
2760
|
+
* But for example in markdown, a thematic break (`***`) is neither literal nor
|
|
2761
|
+
* parent, but still a node.
|
|
2762
|
+
*
|
|
2763
|
+
* To register custom mdast nodes, add them to {@link RootContentMap} and other
|
|
2764
|
+
* places where relevant (such as {@link ElementContentMap}).
|
|
2765
|
+
*
|
|
2766
|
+
* For a union of all registered mdast nodes, see {@link Nodes}.
|
|
2767
|
+
*/
|
|
2768
|
+
interface Node extends Node$1 {
|
|
2769
|
+
/**
|
|
2770
|
+
* Info from the ecosystem.
|
|
2771
|
+
*/
|
|
2772
|
+
data?: Data | undefined;
|
|
2773
|
+
}
|
|
2774
|
+
/**
|
|
2775
|
+
* Abstract mdast node that contains other mdast nodes (*children*).
|
|
2776
|
+
*
|
|
2777
|
+
* This interface is supposed to be extended if you make custom mdast nodes.
|
|
2778
|
+
*
|
|
2779
|
+
* For a union of all registered mdast parents, see {@link Parents}.
|
|
2780
|
+
*/
|
|
2781
|
+
interface Parent extends Node {
|
|
2782
|
+
/**
|
|
2783
|
+
* List of children.
|
|
2784
|
+
*/
|
|
2785
|
+
children: RootContent[];
|
|
2786
|
+
}
|
|
2787
|
+
// ## Concrete nodes
|
|
2788
|
+
/**
|
|
2789
|
+
* Markdown block quote.
|
|
2790
|
+
*/
|
|
2791
|
+
interface Blockquote extends Parent {
|
|
2792
|
+
/**
|
|
2793
|
+
* Node type of mdast block quote.
|
|
2794
|
+
*/
|
|
2795
|
+
type: "blockquote";
|
|
2796
|
+
/**
|
|
2797
|
+
* Children of block quote.
|
|
2798
|
+
*/
|
|
2799
|
+
children: Array<BlockContent | DefinitionContent>;
|
|
2800
|
+
/**
|
|
2801
|
+
* Data associated with the mdast block quote.
|
|
2802
|
+
*/
|
|
2803
|
+
data?: BlockquoteData | undefined;
|
|
2804
|
+
}
|
|
2805
|
+
/**
|
|
2806
|
+
* Info associated with mdast block quote nodes by the ecosystem.
|
|
2807
|
+
*/
|
|
2808
|
+
interface BlockquoteData extends Data {}
|
|
2809
|
+
/**
|
|
2810
|
+
* Markdown break.
|
|
2811
|
+
*/
|
|
2812
|
+
interface Break extends Node {
|
|
2813
|
+
/**
|
|
2814
|
+
* Node type of mdast break.
|
|
2815
|
+
*/
|
|
2816
|
+
type: "break";
|
|
2817
|
+
/**
|
|
2818
|
+
* Data associated with the mdast break.
|
|
2819
|
+
*/
|
|
2820
|
+
data?: BreakData | undefined;
|
|
2821
|
+
}
|
|
2822
|
+
/**
|
|
2823
|
+
* Info associated with mdast break nodes by the ecosystem.
|
|
2824
|
+
*/
|
|
2825
|
+
interface BreakData extends Data {}
|
|
2826
|
+
/**
|
|
2827
|
+
* Markdown code (flow) (block).
|
|
2828
|
+
*/
|
|
2829
|
+
interface Code extends Literal {
|
|
2830
|
+
/**
|
|
2831
|
+
* Node type of mdast code (flow).
|
|
2832
|
+
*/
|
|
2833
|
+
type: "code";
|
|
2834
|
+
/**
|
|
2835
|
+
* Language of computer code being marked up.
|
|
2836
|
+
*/
|
|
2837
|
+
lang?: string | null | undefined;
|
|
2838
|
+
/**
|
|
2839
|
+
* Custom information relating to the node.
|
|
2840
|
+
*
|
|
2841
|
+
* If the lang field is present, a meta field can be present.
|
|
2842
|
+
*/
|
|
2843
|
+
meta?: string | null | undefined;
|
|
2844
|
+
/**
|
|
2845
|
+
* Data associated with the mdast code (flow).
|
|
2846
|
+
*/
|
|
2847
|
+
data?: CodeData | undefined;
|
|
2848
|
+
}
|
|
2849
|
+
/**
|
|
2850
|
+
* Info associated with mdast code (flow) (block) nodes by the ecosystem.
|
|
2851
|
+
*/
|
|
2852
|
+
interface CodeData extends Data {}
|
|
2853
|
+
/**
|
|
2854
|
+
* Markdown definition.
|
|
2855
|
+
*/
|
|
2856
|
+
interface Definition extends Node, Association, Resource {
|
|
2857
|
+
/**
|
|
2858
|
+
* Node type of mdast definition.
|
|
2859
|
+
*/
|
|
2860
|
+
type: "definition";
|
|
2861
|
+
/**
|
|
2862
|
+
* Data associated with the mdast definition.
|
|
2863
|
+
*/
|
|
2864
|
+
data?: DefinitionData | undefined;
|
|
2865
|
+
}
|
|
2866
|
+
/**
|
|
2867
|
+
* Info associated with mdast definition nodes by the ecosystem.
|
|
2868
|
+
*/
|
|
2869
|
+
interface DefinitionData extends Data {}
|
|
2870
|
+
/**
|
|
2871
|
+
* Markdown GFM delete (strikethrough).
|
|
2872
|
+
*/
|
|
2873
|
+
interface Delete extends Parent {
|
|
2874
|
+
/**
|
|
2875
|
+
* Node type of mdast GFM delete.
|
|
2876
|
+
*/
|
|
2877
|
+
type: "delete";
|
|
2878
|
+
/**
|
|
2879
|
+
* Children of GFM delete.
|
|
2880
|
+
*/
|
|
2881
|
+
children: PhrasingContent[];
|
|
2882
|
+
/**
|
|
2883
|
+
* Data associated with the mdast GFM delete.
|
|
2884
|
+
*/
|
|
2885
|
+
data?: DeleteData | undefined;
|
|
2886
|
+
}
|
|
2887
|
+
/**
|
|
2888
|
+
* Info associated with mdast GFM delete nodes by the ecosystem.
|
|
2889
|
+
*/
|
|
2890
|
+
interface DeleteData extends Data {}
|
|
2891
|
+
/**
|
|
2892
|
+
* Markdown emphasis.
|
|
2893
|
+
*/
|
|
2894
|
+
interface Emphasis extends Parent {
|
|
2895
|
+
/**
|
|
2896
|
+
* Node type of mdast emphasis.
|
|
2897
|
+
*/
|
|
2898
|
+
type: "emphasis";
|
|
2899
|
+
/**
|
|
2900
|
+
* Children of emphasis.
|
|
2901
|
+
*/
|
|
2902
|
+
children: PhrasingContent[];
|
|
2903
|
+
/**
|
|
2904
|
+
* Data associated with the mdast emphasis.
|
|
2905
|
+
*/
|
|
2906
|
+
data?: EmphasisData | undefined;
|
|
2907
|
+
}
|
|
2908
|
+
/**
|
|
2909
|
+
* Info associated with mdast emphasis nodes by the ecosystem.
|
|
2910
|
+
*/
|
|
2911
|
+
interface EmphasisData extends Data {}
|
|
2912
|
+
/**
|
|
2913
|
+
* Markdown GFM footnote definition.
|
|
2914
|
+
*/
|
|
2915
|
+
interface FootnoteDefinition extends Parent, Association {
|
|
2916
|
+
/**
|
|
2917
|
+
* Node type of mdast GFM footnote definition.
|
|
2918
|
+
*/
|
|
2919
|
+
type: "footnoteDefinition";
|
|
2920
|
+
/**
|
|
2921
|
+
* Children of GFM footnote definition.
|
|
2922
|
+
*/
|
|
2923
|
+
children: Array<BlockContent | DefinitionContent>;
|
|
2924
|
+
/**
|
|
2925
|
+
* Data associated with the mdast GFM footnote definition.
|
|
2926
|
+
*/
|
|
2927
|
+
data?: FootnoteDefinitionData | undefined;
|
|
2928
|
+
}
|
|
2929
|
+
/**
|
|
2930
|
+
* Info associated with mdast GFM footnote definition nodes by the ecosystem.
|
|
2931
|
+
*/
|
|
2932
|
+
interface FootnoteDefinitionData extends Data {}
|
|
2933
|
+
/**
|
|
2934
|
+
* Markdown GFM footnote reference.
|
|
2935
|
+
*/
|
|
2936
|
+
interface FootnoteReference extends Association, Node {
|
|
2937
|
+
/**
|
|
2938
|
+
* Node type of mdast GFM footnote reference.
|
|
2939
|
+
*/
|
|
2940
|
+
type: "footnoteReference";
|
|
2941
|
+
/**
|
|
2942
|
+
* Data associated with the mdast GFM footnote reference.
|
|
2943
|
+
*/
|
|
2944
|
+
data?: FootnoteReferenceData | undefined;
|
|
2945
|
+
}
|
|
2946
|
+
/**
|
|
2947
|
+
* Info associated with mdast GFM footnote reference nodes by the ecosystem.
|
|
2948
|
+
*/
|
|
2949
|
+
interface FootnoteReferenceData extends Data {}
|
|
2950
|
+
/**
|
|
2951
|
+
* Markdown heading.
|
|
2952
|
+
*/
|
|
2953
|
+
interface Heading extends Parent {
|
|
2954
|
+
/**
|
|
2955
|
+
* Node type of mdast heading.
|
|
2956
|
+
*/
|
|
2957
|
+
type: "heading";
|
|
2958
|
+
/**
|
|
2959
|
+
* Heading rank.
|
|
2960
|
+
*
|
|
2961
|
+
* A value of `1` is said to be the highest rank and `6` the lowest.
|
|
2962
|
+
*/
|
|
2963
|
+
depth: 1 | 2 | 3 | 4 | 5 | 6;
|
|
2964
|
+
/**
|
|
2965
|
+
* Children of heading.
|
|
2966
|
+
*/
|
|
2967
|
+
children: PhrasingContent[];
|
|
2968
|
+
/**
|
|
2969
|
+
* Data associated with the mdast heading.
|
|
2970
|
+
*/
|
|
2971
|
+
data?: HeadingData | undefined;
|
|
2972
|
+
}
|
|
2973
|
+
/**
|
|
2974
|
+
* Info associated with mdast heading nodes by the ecosystem.
|
|
2975
|
+
*/
|
|
2976
|
+
interface HeadingData extends Data {}
|
|
2977
|
+
/**
|
|
2978
|
+
* Markdown HTML.
|
|
2979
|
+
*/
|
|
2980
|
+
interface Html extends Literal {
|
|
2981
|
+
/**
|
|
2982
|
+
* Node type of mdast HTML.
|
|
2983
|
+
*/
|
|
2984
|
+
type: "html";
|
|
2985
|
+
/**
|
|
2986
|
+
* Data associated with the mdast HTML.
|
|
2987
|
+
*/
|
|
2988
|
+
data?: HtmlData | undefined;
|
|
2989
|
+
}
|
|
2990
|
+
/**
|
|
2991
|
+
* Info associated with mdast HTML nodes by the ecosystem.
|
|
2992
|
+
*/
|
|
2993
|
+
interface HtmlData extends Data {}
|
|
2994
|
+
/**
|
|
2995
|
+
* Markdown image.
|
|
2996
|
+
*/
|
|
2997
|
+
interface Image extends Alternative, Node, Resource {
|
|
2998
|
+
/**
|
|
2999
|
+
* Node type of mdast image.
|
|
3000
|
+
*/
|
|
3001
|
+
type: "image";
|
|
3002
|
+
/**
|
|
3003
|
+
* Data associated with the mdast image.
|
|
3004
|
+
*/
|
|
3005
|
+
data?: ImageData | undefined;
|
|
3006
|
+
}
|
|
3007
|
+
/**
|
|
3008
|
+
* Info associated with mdast image nodes by the ecosystem.
|
|
3009
|
+
*/
|
|
3010
|
+
interface ImageData extends Data {}
|
|
3011
|
+
/**
|
|
3012
|
+
* Markdown image reference.
|
|
3013
|
+
*/
|
|
3014
|
+
interface ImageReference extends Alternative, Node, Reference {
|
|
3015
|
+
/**
|
|
3016
|
+
* Node type of mdast image reference.
|
|
3017
|
+
*/
|
|
3018
|
+
type: "imageReference";
|
|
3019
|
+
/**
|
|
3020
|
+
* Data associated with the mdast image reference.
|
|
3021
|
+
*/
|
|
3022
|
+
data?: ImageReferenceData | undefined;
|
|
3023
|
+
}
|
|
3024
|
+
/**
|
|
3025
|
+
* Info associated with mdast image reference nodes by the ecosystem.
|
|
3026
|
+
*/
|
|
3027
|
+
interface ImageReferenceData extends Data {}
|
|
3028
|
+
/**
|
|
3029
|
+
* Markdown code (text) (inline).
|
|
3030
|
+
*/
|
|
3031
|
+
interface InlineCode extends Literal {
|
|
3032
|
+
/**
|
|
3033
|
+
* Node type of mdast code (text).
|
|
3034
|
+
*/
|
|
3035
|
+
type: "inlineCode";
|
|
3036
|
+
/**
|
|
3037
|
+
* Data associated with the mdast code (text).
|
|
3038
|
+
*/
|
|
3039
|
+
data?: InlineCodeData | undefined;
|
|
3040
|
+
}
|
|
3041
|
+
/**
|
|
3042
|
+
* Info associated with mdast code (text) (inline) nodes by the ecosystem.
|
|
3043
|
+
*/
|
|
3044
|
+
interface InlineCodeData extends Data {}
|
|
3045
|
+
/**
|
|
3046
|
+
* Markdown link.
|
|
3047
|
+
*/
|
|
3048
|
+
interface Link extends Parent, Resource {
|
|
3049
|
+
/**
|
|
3050
|
+
* Node type of mdast link.
|
|
3051
|
+
*/
|
|
3052
|
+
type: "link";
|
|
3053
|
+
/**
|
|
3054
|
+
* Children of link.
|
|
3055
|
+
*/
|
|
3056
|
+
children: PhrasingContent[];
|
|
3057
|
+
/**
|
|
3058
|
+
* Data associated with the mdast link.
|
|
3059
|
+
*/
|
|
3060
|
+
data?: LinkData | undefined;
|
|
3061
|
+
}
|
|
3062
|
+
/**
|
|
3063
|
+
* Info associated with mdast link nodes by the ecosystem.
|
|
3064
|
+
*/
|
|
3065
|
+
interface LinkData extends Data {}
|
|
3066
|
+
/**
|
|
3067
|
+
* Markdown link reference.
|
|
3068
|
+
*/
|
|
3069
|
+
interface LinkReference extends Parent, Reference {
|
|
3070
|
+
/**
|
|
3071
|
+
* Node type of mdast link reference.
|
|
3072
|
+
*/
|
|
3073
|
+
type: "linkReference";
|
|
3074
|
+
/**
|
|
3075
|
+
* Children of link reference.
|
|
3076
|
+
*/
|
|
3077
|
+
children: PhrasingContent[];
|
|
3078
|
+
/**
|
|
3079
|
+
* Data associated with the mdast link reference.
|
|
3080
|
+
*/
|
|
3081
|
+
data?: LinkReferenceData | undefined;
|
|
3082
|
+
}
|
|
3083
|
+
/**
|
|
3084
|
+
* Info associated with mdast link reference nodes by the ecosystem.
|
|
3085
|
+
*/
|
|
3086
|
+
interface LinkReferenceData extends Data {}
|
|
3087
|
+
/**
|
|
3088
|
+
* Markdown list.
|
|
3089
|
+
*/
|
|
3090
|
+
interface List extends Parent {
|
|
3091
|
+
/**
|
|
3092
|
+
* Node type of mdast list.
|
|
3093
|
+
*/
|
|
3094
|
+
type: "list";
|
|
3095
|
+
/**
|
|
3096
|
+
* Whether the items have been intentionally ordered (when `true`), or that
|
|
3097
|
+
* the order of items is not important (when `false` or not present).
|
|
3098
|
+
*/
|
|
3099
|
+
ordered?: boolean | null | undefined;
|
|
3100
|
+
/**
|
|
3101
|
+
* The starting number of the list, when the `ordered` field is `true`.
|
|
3102
|
+
*/
|
|
3103
|
+
start?: number | null | undefined;
|
|
3104
|
+
/**
|
|
3105
|
+
* Whether one or more of the children are separated with a blank line from
|
|
3106
|
+
* its siblings (when `true`), or not (when `false` or not present).
|
|
3107
|
+
*/
|
|
3108
|
+
spread?: boolean | null | undefined;
|
|
3109
|
+
/**
|
|
3110
|
+
* Children of list.
|
|
3111
|
+
*/
|
|
3112
|
+
children: ListContent[];
|
|
3113
|
+
/**
|
|
3114
|
+
* Data associated with the mdast list.
|
|
3115
|
+
*/
|
|
3116
|
+
data?: ListData | undefined;
|
|
3117
|
+
}
|
|
3118
|
+
/**
|
|
3119
|
+
* Info associated with mdast list nodes by the ecosystem.
|
|
3120
|
+
*/
|
|
3121
|
+
interface ListData extends Data {}
|
|
3122
|
+
/**
|
|
3123
|
+
* Markdown list item.
|
|
3124
|
+
*/
|
|
3125
|
+
interface ListItem extends Parent {
|
|
3126
|
+
/**
|
|
3127
|
+
* Node type of mdast list item.
|
|
3128
|
+
*/
|
|
3129
|
+
type: "listItem";
|
|
3130
|
+
/**
|
|
3131
|
+
* Whether the item is a tasklist item (when `boolean`).
|
|
3132
|
+
*
|
|
3133
|
+
* When `true`, the item is complete.
|
|
3134
|
+
* When `false`, the item is incomplete.
|
|
3135
|
+
*/
|
|
3136
|
+
checked?: boolean | null | undefined;
|
|
3137
|
+
/**
|
|
3138
|
+
* Whether one or more of the children are separated with a blank line from
|
|
3139
|
+
* its siblings (when `true`), or not (when `false` or not present).
|
|
3140
|
+
*/
|
|
3141
|
+
spread?: boolean | null | undefined;
|
|
3142
|
+
/**
|
|
3143
|
+
* Children of list item.
|
|
3144
|
+
*/
|
|
3145
|
+
children: Array<BlockContent | DefinitionContent>;
|
|
3146
|
+
/**
|
|
3147
|
+
* Data associated with the mdast list item.
|
|
3148
|
+
*/
|
|
3149
|
+
data?: ListItemData | undefined;
|
|
3150
|
+
}
|
|
3151
|
+
/**
|
|
3152
|
+
* Info associated with mdast list item nodes by the ecosystem.
|
|
3153
|
+
*/
|
|
3154
|
+
interface ListItemData extends Data {}
|
|
3155
|
+
/**
|
|
3156
|
+
* Markdown paragraph.
|
|
3157
|
+
*/
|
|
3158
|
+
interface Paragraph extends Parent {
|
|
3159
|
+
/**
|
|
3160
|
+
* Node type of mdast paragraph.
|
|
3161
|
+
*/
|
|
3162
|
+
type: "paragraph";
|
|
3163
|
+
/**
|
|
3164
|
+
* Children of paragraph.
|
|
3165
|
+
*/
|
|
3166
|
+
children: PhrasingContent[];
|
|
3167
|
+
/**
|
|
3168
|
+
* Data associated with the mdast paragraph.
|
|
3169
|
+
*/
|
|
3170
|
+
data?: ParagraphData | undefined;
|
|
3171
|
+
}
|
|
3172
|
+
/**
|
|
3173
|
+
* Info associated with mdast paragraph nodes by the ecosystem.
|
|
3174
|
+
*/
|
|
3175
|
+
interface ParagraphData extends Data {}
|
|
3176
|
+
/**
|
|
3177
|
+
* Markdown strong.
|
|
3178
|
+
*/
|
|
3179
|
+
interface Strong extends Parent {
|
|
3180
|
+
/**
|
|
3181
|
+
* Node type of mdast strong.
|
|
3182
|
+
*/
|
|
3183
|
+
type: "strong";
|
|
3184
|
+
/**
|
|
3185
|
+
* Children of strong.
|
|
3186
|
+
*/
|
|
3187
|
+
children: PhrasingContent[];
|
|
3188
|
+
/**
|
|
3189
|
+
* Data associated with the mdast strong.
|
|
3190
|
+
*/
|
|
3191
|
+
data?: StrongData | undefined;
|
|
3192
|
+
}
|
|
3193
|
+
/**
|
|
3194
|
+
* Info associated with mdast strong nodes by the ecosystem.
|
|
3195
|
+
*/
|
|
3196
|
+
interface StrongData extends Data {}
|
|
3197
|
+
/**
|
|
3198
|
+
* Markdown GFM table.
|
|
3199
|
+
*/
|
|
3200
|
+
interface Table extends Parent {
|
|
3201
|
+
/**
|
|
3202
|
+
* Node type of mdast GFM table.
|
|
3203
|
+
*/
|
|
3204
|
+
type: "table";
|
|
3205
|
+
/**
|
|
3206
|
+
* How cells in columns are aligned.
|
|
3207
|
+
*/
|
|
3208
|
+
align?: AlignType[] | null | undefined;
|
|
3209
|
+
/**
|
|
3210
|
+
* Children of GFM table.
|
|
3211
|
+
*/
|
|
3212
|
+
children: TableContent[];
|
|
3213
|
+
/**
|
|
3214
|
+
* Data associated with the mdast GFM table.
|
|
3215
|
+
*/
|
|
3216
|
+
data?: TableData | undefined;
|
|
3217
|
+
}
|
|
3218
|
+
/**
|
|
3219
|
+
* Info associated with mdast GFM table nodes by the ecosystem.
|
|
3220
|
+
*/
|
|
3221
|
+
interface TableData extends Data {}
|
|
3222
|
+
/**
|
|
3223
|
+
* Markdown GFM table row.
|
|
3224
|
+
*/
|
|
3225
|
+
interface TableRow extends Parent {
|
|
3226
|
+
/**
|
|
3227
|
+
* Node type of mdast GFM table row.
|
|
3228
|
+
*/
|
|
3229
|
+
type: "tableRow";
|
|
3230
|
+
/**
|
|
3231
|
+
* Children of GFM table row.
|
|
3232
|
+
*/
|
|
3233
|
+
children: RowContent[];
|
|
3234
|
+
/**
|
|
3235
|
+
* Data associated with the mdast GFM table row.
|
|
3236
|
+
*/
|
|
3237
|
+
data?: TableRowData | undefined;
|
|
3238
|
+
}
|
|
3239
|
+
/**
|
|
3240
|
+
* Info associated with mdast GFM table row nodes by the ecosystem.
|
|
3241
|
+
*/
|
|
3242
|
+
interface TableRowData extends Data {}
|
|
3243
|
+
/**
|
|
3244
|
+
* Markdown GFM table cell.
|
|
3245
|
+
*/
|
|
3246
|
+
interface TableCell extends Parent {
|
|
3247
|
+
/**
|
|
3248
|
+
* Node type of mdast GFM table cell.
|
|
3249
|
+
*/
|
|
3250
|
+
type: "tableCell";
|
|
3251
|
+
/**
|
|
3252
|
+
* Children of GFM table cell.
|
|
3253
|
+
*/
|
|
3254
|
+
children: PhrasingContent[];
|
|
3255
|
+
/**
|
|
3256
|
+
* Data associated with the mdast GFM table cell.
|
|
3257
|
+
*/
|
|
3258
|
+
data?: TableCellData | undefined;
|
|
3259
|
+
}
|
|
3260
|
+
/**
|
|
3261
|
+
* Info associated with mdast GFM table cell nodes by the ecosystem.
|
|
3262
|
+
*/
|
|
3263
|
+
interface TableCellData extends Data {}
|
|
3264
|
+
/**
|
|
3265
|
+
* Markdown text.
|
|
3266
|
+
*/
|
|
3267
|
+
interface Text extends Literal {
|
|
3268
|
+
/**
|
|
3269
|
+
* Node type of mdast text.
|
|
3270
|
+
*/
|
|
3271
|
+
type: "text";
|
|
3272
|
+
/**
|
|
3273
|
+
* Data associated with the mdast text.
|
|
3274
|
+
*/
|
|
3275
|
+
data?: TextData | undefined;
|
|
3276
|
+
}
|
|
3277
|
+
/**
|
|
3278
|
+
* Info associated with mdast text nodes by the ecosystem.
|
|
3279
|
+
*/
|
|
3280
|
+
interface TextData extends Data {}
|
|
3281
|
+
/**
|
|
3282
|
+
* Markdown thematic break (horizontal rule).
|
|
3283
|
+
*/
|
|
3284
|
+
interface ThematicBreak extends Node {
|
|
3285
|
+
/**
|
|
3286
|
+
* Node type of mdast thematic break.
|
|
3287
|
+
*/
|
|
3288
|
+
type: "thematicBreak";
|
|
3289
|
+
/**
|
|
3290
|
+
* Data associated with the mdast thematic break.
|
|
3291
|
+
*/
|
|
3292
|
+
data?: ThematicBreakData | undefined;
|
|
3293
|
+
}
|
|
3294
|
+
/**
|
|
3295
|
+
* Info associated with mdast thematic break nodes by the ecosystem.
|
|
3296
|
+
*/
|
|
3297
|
+
interface ThematicBreakData extends Data {}
|
|
3298
|
+
/**
|
|
3299
|
+
* Markdown YAML.
|
|
3300
|
+
*/
|
|
3301
|
+
interface Yaml extends Literal {
|
|
3302
|
+
/**
|
|
3303
|
+
* Node type of mdast YAML.
|
|
3304
|
+
*/
|
|
3305
|
+
type: "yaml";
|
|
3306
|
+
/**
|
|
3307
|
+
* Data associated with the mdast YAML.
|
|
3308
|
+
*/
|
|
3309
|
+
data?: YamlData | undefined;
|
|
3310
|
+
}
|
|
3311
|
+
/**
|
|
3312
|
+
* Info associated with mdast YAML nodes by the ecosystem.
|
|
3313
|
+
*/
|
|
3314
|
+
interface YamlData extends Data {}
|
|
3315
|
+
/**
|
|
3316
|
+
* Reports what a parsed input's records yield to the conversion pipeline, so it
|
|
3317
|
+
* classifies an error the parser throws while aggregation consumes them the
|
|
3318
|
+
* same way as one it throws before returning, and rejects an input with no
|
|
3319
|
+
* records.
|
|
3320
|
+
*/
|
|
3321
|
+
type RecordReader = {
|
|
3322
|
+
/** Returns the lazily consumed {@link records}, noting each it yields. */
|
|
3323
|
+
records: <Value>(records: Iterable<Value>) => Iterable<Value>;
|
|
3324
|
+
/** Returns a lazily consumed {@link iterable} that yields no records. */
|
|
3325
|
+
iterable: <Value>(iterable: Iterable<Value>) => Iterable<Value>;
|
|
3326
|
+
/** Notes {@link count} records the parser read before returning. */
|
|
3327
|
+
parsed: (count: number) => void;
|
|
3328
|
+
};
|
|
3329
|
+
type EntityLocation = {
|
|
3330
|
+
location: SourceLocation;
|
|
3331
|
+
inferable: boolean;
|
|
3332
|
+
};
|
|
3333
|
+
type AggregatedCallGraph = {
|
|
3334
|
+
type: `call-graph`;
|
|
3335
|
+
/** @see {@link AggregatedCallStackProfile.context} */
|
|
3336
|
+
context: ProfileToMdContext;
|
|
3337
|
+
metrics: Metric[];
|
|
3338
|
+
/**
|
|
3339
|
+
* For each metric in {@link AggregatedCallGraph.metrics}, the whole
|
|
3340
|
+
* input's recorded cost: the sum of every function's self values.
|
|
3341
|
+
*/
|
|
3342
|
+
totalValues: Float64Array;
|
|
3343
|
+
/** Function category to the summed self values of that category. */
|
|
3344
|
+
categoryToMetrics: Map<FunctionCategory, AggregatedCallGraphCategoryMetrics>;
|
|
3345
|
+
functions: AggregatedCallGraphFunction[];
|
|
3346
|
+
};
|
|
3347
|
+
type AggregatedCallGraphCategoryMetrics = {
|
|
3348
|
+
/**
|
|
3349
|
+
* For each metric in {@link AggregatedCallGraph.metrics}, the summed self
|
|
3350
|
+
* values of functions with this category.
|
|
3351
|
+
*/
|
|
3352
|
+
values: Float64Array;
|
|
3353
|
+
};
|
|
3354
|
+
type AggregatedCallGraphFunction = {
|
|
3355
|
+
type: `function`;
|
|
3356
|
+
/** An index that uniquely identifies this function. */
|
|
3357
|
+
id: number;
|
|
3358
|
+
name: string;
|
|
3359
|
+
/** Where the function was defined. */
|
|
3360
|
+
location?: SourceLocation;
|
|
3361
|
+
category: FunctionCategory;
|
|
3362
|
+
/**
|
|
3363
|
+
* For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
|
|
3364
|
+
* directly in the function's body, excluding its callees.
|
|
3365
|
+
*/
|
|
3366
|
+
selfValues: Float64Array;
|
|
3367
|
+
/**
|
|
3368
|
+
* For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
|
|
3369
|
+
* in the function's body and all its callees: its self values plus its
|
|
3370
|
+
* outgoing arcs' total values, excluding the arcs to functions in its own
|
|
3371
|
+
* recursion cycle, which re-count the same work.
|
|
3372
|
+
*/
|
|
3373
|
+
totalValues: Float64Array;
|
|
3374
|
+
/** 1-based line number to the self values recorded at that line. */
|
|
3375
|
+
lineToMetrics: Map<number, Float64Array>;
|
|
3376
|
+
/** Direct caller ID to the costs recorded during that caller's calls. */
|
|
3377
|
+
callerIdToMetrics: Map<number, AggregatedCallGraphCallerMetrics>;
|
|
3378
|
+
/** Direct callee ID to the costs recorded during calls to that callee. */
|
|
3379
|
+
calleeIdToMetrics: Map<number, AggregatedCallGraphCalleeMetrics>;
|
|
3380
|
+
};
|
|
3381
|
+
/** One function's recorded costs during calls from a given direct caller. */
|
|
3382
|
+
type AggregatedCallGraphCallerMetrics = {
|
|
3383
|
+
caller: AggregatedCallGraphFunction;
|
|
3384
|
+
/** The recorded number of calls, or `0` when the format records none. */
|
|
3385
|
+
callCount: number;
|
|
3386
|
+
/**
|
|
3387
|
+
* For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
|
|
3388
|
+
* in the function and its callees during calls from this caller.
|
|
3389
|
+
*/
|
|
3390
|
+
totalValues: Float64Array;
|
|
3391
|
+
};
|
|
3392
|
+
/** One function's recorded costs during its calls to a given direct callee. */
|
|
3393
|
+
type AggregatedCallGraphCalleeMetrics = {
|
|
3394
|
+
callee: AggregatedCallGraphFunction;
|
|
3395
|
+
/** The recorded number of calls, or `0` when the format records none. */
|
|
3396
|
+
callCount: number;
|
|
3397
|
+
/**
|
|
3398
|
+
* For each metric in {@link AggregatedCallGraph.metrics}, the cost recorded
|
|
3399
|
+
* in the callee and its callees during this function's calls to it.
|
|
3400
|
+
*/
|
|
3401
|
+
totalValues: Float64Array;
|
|
3402
|
+
};
|
|
3403
|
+
declare class CallGraphAggregator implements InputAggregator<AggregatedCallGraph> {
|
|
3404
|
+
#private;
|
|
3405
|
+
constructor(graph: CallGraph);
|
|
3406
|
+
detectOrigin(detector: OriginDetector): void;
|
|
3407
|
+
aggregate(options: AggregationProfileToMdOptions, context: ProfileToMdContext): AggregatedCallGraph;
|
|
3408
|
+
}
|
|
3409
|
+
/** What an entity's instances retain, alone or together. */
|
|
3410
|
+
type EntityRetention = {
|
|
3411
|
+
/**
|
|
3412
|
+
* The summed self size of every node that becomes unreachable from the GC
|
|
3413
|
+
* root once every instance of the entity is garbage collected.
|
|
3414
|
+
*/
|
|
3415
|
+
retainedSize: number;
|
|
3416
|
+
/**
|
|
3417
|
+
* The instances no other node the entity retains dominates. Their retained
|
|
3418
|
+
* nodes are disjoint, and contain those of the entity's instances not listed.
|
|
3419
|
+
*/
|
|
3420
|
+
outermostInstanceOrdinals: number[];
|
|
3421
|
+
/**
|
|
3422
|
+
* The nodes other than instances that the entity retains and whose immediate
|
|
3423
|
+
* dominators it does not. No single instance dominates one, so at least two
|
|
3424
|
+
* instances are on the paths to it.
|
|
3425
|
+
*/
|
|
3426
|
+
jointlyRetainedOrdinals: number[];
|
|
3427
|
+
};
|
|
3428
|
+
type AggregatedHeapSnapshot = {
|
|
3429
|
+
type: `heap-snapshot`;
|
|
3430
|
+
/**
|
|
3431
|
+
* The context this snapshot was aggregated under. Diffed sides that resolved
|
|
3432
|
+
* different origins can normalize match keys differently and miss matches.
|
|
3433
|
+
*/
|
|
3434
|
+
context: ProfileToMdContext;
|
|
3435
|
+
/** The summed self sizes of every node in the snapshot. */
|
|
3436
|
+
heldSize: number;
|
|
3437
|
+
nodeCount: number;
|
|
3438
|
+
edgeCount: number;
|
|
3439
|
+
nodeCategoryToStats: Map<HeapSnapshotNodeCategory, NodeCategoryStats>;
|
|
3440
|
+
constructors: AggregatedHeapSnapshotConstructor[];
|
|
3441
|
+
functions: AggregatedHeapSnapshotFunction[];
|
|
3442
|
+
strings: AggregatedHeapSnapshotString[];
|
|
3443
|
+
/**
|
|
3444
|
+
* What each given set of distinct instance ordinals retains, alone or
|
|
3445
|
+
* together. No node may be in two sets.
|
|
3446
|
+
*/
|
|
3447
|
+
retentionsOf: (instanceOrdinalSets: readonly (readonly number[])[]) => EntityRetention[];
|
|
3448
|
+
/**
|
|
3449
|
+
* The first hop of a node's retainer path along its dominators, or
|
|
3450
|
+
* `undefined` for the GC root, a node without predecessors, and an
|
|
3451
|
+
* unreachable node. Following each hop's
|
|
3452
|
+
* {@link RetainerHop.dominatorOrdinal} ends at one of them.
|
|
3453
|
+
*/
|
|
3454
|
+
retainerHopOf: (nodeOrdinal: number) => RetainerHop | undefined;
|
|
3455
|
+
/** The node as a retainer path step shows it. */
|
|
3456
|
+
retainerOf: (nodeOrdinal: number) => RetainerNode;
|
|
3457
|
+
nodeOf: (nodeOrdinal: number, options: FormattingProfileToMdOptions) => AggregatedHeapSnapshotNode;
|
|
3458
|
+
/** The nodes the node dominates. */
|
|
3459
|
+
retainedNodesOf: (nodeOrdinal: number, options: FormattingProfileToMdOptions) => AggregatedHeapSnapshotNode[];
|
|
3460
|
+
/** Whether the node is a bookkeeping node that never points to user code. */
|
|
3461
|
+
isInternalNode: (nodeOrdinal: number) => boolean;
|
|
3462
|
+
};
|
|
3463
|
+
type NodeCategoryStats = {
|
|
3464
|
+
/** Bytes allocated directly for nodes in this category. */
|
|
3465
|
+
size: number;
|
|
3466
|
+
nodeCount: number;
|
|
3467
|
+
};
|
|
3468
|
+
type AggregatedHeapSnapshotConstructor = AggregatedHeapSnapshotEntity & {
|
|
3469
|
+
name: string;
|
|
3470
|
+
/**
|
|
3471
|
+
* What this constructor's instances hold: the category the origin assigns to
|
|
3472
|
+
* its class, falling back to the category holding the most of their self
|
|
3473
|
+
* size.
|
|
3474
|
+
*/
|
|
3475
|
+
category: HeapSnapshotNodeCategory;
|
|
3476
|
+
instances: AggregatedHeapSnapshotNode[];
|
|
3477
|
+
} & EntityRetention;
|
|
3478
|
+
type AggregatedHeapSnapshotFunction = AggregatedHeapSnapshotEntity & {
|
|
3479
|
+
/**
|
|
3480
|
+
* The ordinal of the instance with the largest individual retained size,
|
|
3481
|
+
* which is the instance the function's rows show.
|
|
3482
|
+
*/
|
|
3483
|
+
id: number;
|
|
3484
|
+
name: string;
|
|
3485
|
+
/** What this function holds, taken from the instance {@link id} identifies. */
|
|
3486
|
+
category: HeapSnapshotNodeCategory;
|
|
3487
|
+
instanceOrdinals: number[];
|
|
3488
|
+
} & EntityRetention;
|
|
3489
|
+
type AggregatedHeapSnapshotString = AggregatedHeapSnapshotEntity & {
|
|
3490
|
+
/** What this string holds: its representation in the heap. */
|
|
3491
|
+
category: HeapSnapshotNodeCategory;
|
|
3492
|
+
};
|
|
3493
|
+
/** A constructor, function, or string, aggregating the nodes it identifies. */
|
|
3494
|
+
type AggregatedHeapSnapshotEntity = {
|
|
3495
|
+
type: `node`;
|
|
3496
|
+
/** The ordinal of one of the entity's nodes. */
|
|
3497
|
+
id: number;
|
|
3498
|
+
name?: string;
|
|
3499
|
+
/**
|
|
3500
|
+
* The file reference the {@link name} parses as, when it is URL-shaped
|
|
3501
|
+
* (e.g. a V8 module namespace object named by its file URL). Formatting
|
|
3502
|
+
* shows it relative to the base URL in place of the raw name.
|
|
3503
|
+
*/
|
|
3504
|
+
nameLocation?: FileReference;
|
|
3505
|
+
/** Bytes allocated directly for the entity's nodes. */
|
|
3506
|
+
selfSize: number;
|
|
3507
|
+
category: HeapSnapshotNodeCategory;
|
|
3508
|
+
/**
|
|
3509
|
+
* Bytes allocated for the entity's nodes, as well as all nodes that would be
|
|
3510
|
+
* freed if they were garbage collected. A lower bound on a graph that exhausts
|
|
3511
|
+
* the budget of {@link computeEntityRetentions}.
|
|
3512
|
+
*/
|
|
3513
|
+
retainedSize: number;
|
|
3514
|
+
location?: SourceLocation;
|
|
3515
|
+
};
|
|
3516
|
+
/** A constructor's instance, or a node an instance retains. */
|
|
3517
|
+
type AggregatedHeapSnapshotNode = {
|
|
3518
|
+
type: `node`;
|
|
3519
|
+
/** The node's ordinal. */
|
|
3520
|
+
id: number;
|
|
3521
|
+
/** The node's label, which for an instance is its constructor's name. */
|
|
3522
|
+
name: string;
|
|
3523
|
+
/** Bytes allocated directly for this node. */
|
|
3524
|
+
selfSize: number;
|
|
3525
|
+
category: HeapSnapshotNodeCategory;
|
|
3526
|
+
/**
|
|
3527
|
+
* Bytes allocated for this node, as well as all nodes that would be freed if
|
|
3528
|
+
* the node were garbage collected.
|
|
3529
|
+
*/
|
|
3530
|
+
retainedSize: number;
|
|
3531
|
+
/** The location of the constructor or function the node is an instance of. */
|
|
3532
|
+
location?: SourceLocation;
|
|
3533
|
+
};
|
|
3534
|
+
/**
|
|
3535
|
+
* A retainer path step's edge. A path that groups the elements of an array
|
|
3536
|
+
* records an element edge as any element. A step whose retainer holds no edge
|
|
3537
|
+
* to the node, which it retains through the node's several retainers, records
|
|
3538
|
+
* several retainers. On a step to a node that an entity's instances retain only
|
|
3539
|
+
* together, it records that every path passes through an instance of the entity.
|
|
3540
|
+
*/
|
|
3541
|
+
type RetainerPathEdge = RetainerEdge | {
|
|
3542
|
+
type: `any-element`;
|
|
3543
|
+
} | {
|
|
3544
|
+
type: `several-retainers`;
|
|
3545
|
+
} | {
|
|
3546
|
+
type: `several-instance-paths`;
|
|
3547
|
+
entityName: string;
|
|
3548
|
+
};
|
|
3549
|
+
/**
|
|
3550
|
+
* Aggregates one {@link HeapSnapshot}.
|
|
3551
|
+
*
|
|
3552
|
+
* The constructor computes everything that needs no origin, including the
|
|
3553
|
+
* entries origin detection reads. {@link aggregate} categorizes under the
|
|
3554
|
+
* resolved origin.
|
|
3555
|
+
*/
|
|
3556
|
+
declare class HeapSnapshotAggregator implements InputAggregator<AggregatedHeapSnapshot> {
|
|
3557
|
+
#private;
|
|
3558
|
+
constructor(snapshot: HeapSnapshot);
|
|
3559
|
+
detectOrigin(detector: OriginDetector): void;
|
|
3560
|
+
aggregate(options: AggregationProfileToMdOptions, context: ProfileToMdContext): AggregatedHeapSnapshot;
|
|
3561
|
+
}
|
|
3562
|
+
/** A node's immediate dominator, and the dominator's edge to the node. */
|
|
3563
|
+
type RetainerHop = {
|
|
3564
|
+
dominatorOrdinal: number;
|
|
3565
|
+
edge: RetainerPathEdge;
|
|
3566
|
+
/** Whether the dominator is an internal node. */
|
|
3567
|
+
internal: boolean;
|
|
3568
|
+
};
|
|
3569
|
+
type AggregatedTrace = {
|
|
3570
|
+
type: `trace`;
|
|
3571
|
+
/** @see {@link AggregatedCallStackProfile.context} */
|
|
3572
|
+
context: ProfileToMdContext;
|
|
3573
|
+
/** The number of spans and instants recorded. */
|
|
3574
|
+
eventCount: number;
|
|
3575
|
+
/**
|
|
3576
|
+
* The milliseconds from the earliest time any event or reading records to
|
|
3577
|
+
* the latest, or `undefined` when the input times none of them.
|
|
3578
|
+
*/
|
|
3579
|
+
duration: number | undefined;
|
|
3580
|
+
/**
|
|
3581
|
+
* Whether any thread span is nested in another, so self and total time
|
|
3582
|
+
* differ.
|
|
3583
|
+
*/
|
|
3584
|
+
hasNesting: boolean;
|
|
3585
|
+
hasCpuTime: boolean;
|
|
3586
|
+
threads: AggregatedTraceThread[];
|
|
3587
|
+
/**
|
|
3588
|
+
* Category to the summed self time and count of that category's events. A
|
|
3589
|
+
* span nested in a span of an exclusive category counts toward that
|
|
3590
|
+
* category.
|
|
3591
|
+
*/
|
|
3592
|
+
categoryToStats: Map<TraceEventCategory, AggregatedTraceStats>;
|
|
3593
|
+
spans: AggregatedTraceSpan[];
|
|
3594
|
+
instants: AggregatedTraceInstant[];
|
|
3595
|
+
gauges: AggregatedTraceGauge[];
|
|
3596
|
+
};
|
|
3597
|
+
/** A number of events and the milliseconds of span time they account for. */
|
|
3598
|
+
type AggregatedTraceStats = {
|
|
3599
|
+
time: number;
|
|
3600
|
+
count: number;
|
|
3601
|
+
};
|
|
3602
|
+
/**
|
|
3603
|
+
* The events sharing one of an entity's breakdown keys, with the longest one's
|
|
3604
|
+
* milliseconds.
|
|
3605
|
+
*/
|
|
3606
|
+
type AggregatedTraceBreakdownStats = AggregatedTraceStats & {
|
|
3607
|
+
max: number;
|
|
3608
|
+
};
|
|
3609
|
+
type AggregatedTraceThread = AggregatedTraceStats & {
|
|
3610
|
+
/** An index that uniquely identifies this thread. */
|
|
3611
|
+
id: number;
|
|
3612
|
+
name: string;
|
|
3613
|
+
};
|
|
3614
|
+
/** Every span sharing a name. */
|
|
3615
|
+
type AggregatedTraceSpan = {
|
|
3616
|
+
type: `span`;
|
|
3617
|
+
/** An index that uniquely identifies this entity among spans and instants. */
|
|
3618
|
+
id: number;
|
|
3619
|
+
name: string;
|
|
3620
|
+
location?: undefined;
|
|
3621
|
+
category: TraceEventCategory;
|
|
3622
|
+
/**
|
|
3623
|
+
* Whether the spans are async spans, whose time is the time that elapsed.
|
|
3624
|
+
* An async span and a thread span sharing a name are two entities.
|
|
3625
|
+
*/
|
|
3626
|
+
async: boolean;
|
|
3627
|
+
/** The number of spans, including those the input never ends. */
|
|
3628
|
+
count: number;
|
|
3629
|
+
/** The number of spans with a duration. */
|
|
3630
|
+
timedCount: number;
|
|
3631
|
+
cpuTimedCount: number;
|
|
3632
|
+
/**
|
|
3633
|
+
* The summed milliseconds within the spans, excluding their children. An
|
|
3634
|
+
* async span adds nothing, because its time is not a thread's.
|
|
3635
|
+
*/
|
|
3636
|
+
selfTime: number;
|
|
3637
|
+
/** The milliseconds of the span with the most self time. */
|
|
3638
|
+
maxSelfTime: number;
|
|
3639
|
+
/**
|
|
3640
|
+
* The summed milliseconds within the spans, including their children. A
|
|
3641
|
+
* span nested in another of the same name adds nothing, because the outer
|
|
3642
|
+
* span's duration already includes it.
|
|
3643
|
+
*/
|
|
3644
|
+
totalTime: number;
|
|
3645
|
+
/** The summed milliseconds of every span's duration, nested or not. */
|
|
3646
|
+
summedTime: number;
|
|
3647
|
+
/** The longest span's milliseconds. */
|
|
3648
|
+
maxTime: number;
|
|
3649
|
+
/** @see {@link selfTime}, in milliseconds of CPU time. */
|
|
3650
|
+
selfCpuTime: number;
|
|
3651
|
+
/** @see {@link maxSelfTime}, in milliseconds of CPU time. */
|
|
3652
|
+
maxSelfCpuTime: number;
|
|
3653
|
+
/** @see {@link summedTime}, in milliseconds of CPU time. */
|
|
3654
|
+
summedCpuTime: number;
|
|
3655
|
+
/** @see {@link maxTime}, in milliseconds of CPU time. */
|
|
3656
|
+
maxCpuTime: number;
|
|
3657
|
+
/** @see {@link totalTime}, in milliseconds of CPU time. */
|
|
3658
|
+
totalCpuTime: number;
|
|
3659
|
+
/** Attribute key to each of its string values' share of the spans. */
|
|
3660
|
+
attributeToValues: Map<string, Map<string, AggregatedTraceBreakdownStats>>;
|
|
3661
|
+
/** Attribute key to the amounts the spans record under it. */
|
|
3662
|
+
attributeToAmount: Map<string, AggregatedTraceAmount>;
|
|
3663
|
+
/** Thread ID to the spans recorded on that thread. */
|
|
3664
|
+
threadIdToStats: Map<number, AggregatedTraceBreakdownStats>;
|
|
3665
|
+
/** Parent span ID to the spans nested directly in a span of that name. */
|
|
3666
|
+
parentIdToStats: Map<number, AggregatedTraceBreakdownStats>;
|
|
3667
|
+
/**
|
|
3668
|
+
* Parent span ID to the spans nested directly in a span of that name, with
|
|
3669
|
+
* their self time.
|
|
3670
|
+
*/
|
|
3671
|
+
parentIdToSelfStats: Map<number, AggregatedTraceBreakdownStats>;
|
|
3672
|
+
/** Child span ID to the spans of that name nested directly in these. */
|
|
3673
|
+
childIdToStats: Map<number, AggregatedTraceBreakdownStats>;
|
|
3674
|
+
instances: AggregatedTraceInstance[];
|
|
3675
|
+
};
|
|
3676
|
+
/** One span with a duration. */
|
|
3677
|
+
type AggregatedTraceInstance = {
|
|
3678
|
+
/** Milliseconds from the trace's start, or `undefined` for an untimed span. */
|
|
3679
|
+
start: number | undefined;
|
|
3680
|
+
time: number;
|
|
3681
|
+
/** The span's CPU time in milliseconds, when recorded. */
|
|
3682
|
+
cpuTime: number | undefined;
|
|
3683
|
+
threadId: number | undefined;
|
|
3684
|
+
attributes: readonly TraceAttribute[] | undefined;
|
|
3685
|
+
};
|
|
3686
|
+
/** The amounts events record under one attribute key. */
|
|
3687
|
+
type AggregatedTraceAmount = {
|
|
3688
|
+
metric: Metric;
|
|
3689
|
+
/** The number of events recording an amount, and their summed time. */
|
|
3690
|
+
count: number;
|
|
3691
|
+
time: number;
|
|
3692
|
+
total: number;
|
|
3693
|
+
max: number;
|
|
3694
|
+
};
|
|
3695
|
+
/** Every instant sharing a name. */
|
|
3696
|
+
type AggregatedTraceInstant = {
|
|
3697
|
+
type: `instant`;
|
|
3698
|
+
/** An index that uniquely identifies this entity among spans and instants. */
|
|
3699
|
+
id: number;
|
|
3700
|
+
name: string;
|
|
3701
|
+
location?: undefined;
|
|
3702
|
+
category: TraceEventCategory;
|
|
3703
|
+
count: number;
|
|
3704
|
+
/** Attribute key to the number of instants with each of its string values. */
|
|
3705
|
+
attributeToValues: Map<string, Map<string, AggregatedTraceBreakdownStats>>;
|
|
3706
|
+
/** Attribute key to the amounts the instants record under it. */
|
|
3707
|
+
attributeToAmount: Map<string, AggregatedTraceAmount>;
|
|
3708
|
+
/** Thread ID to the instants recorded on that thread. */
|
|
3709
|
+
threadIdToStats: Map<number, AggregatedTraceBreakdownStats>;
|
|
3710
|
+
};
|
|
3711
|
+
type AggregatedTraceEntity = AggregatedTraceSpan | AggregatedTraceInstant;
|
|
3712
|
+
type AggregatedTraceGaugeTiming = {
|
|
3713
|
+
/**
|
|
3714
|
+
* The milliseconds from the trace's start to the earliest reading at the
|
|
3715
|
+
* gauge's minimum.
|
|
3716
|
+
*/
|
|
3717
|
+
minTime: number;
|
|
3718
|
+
/** @see {@link minTime}, for the earliest reading at the gauge's maximum. */
|
|
3719
|
+
maxTime: number;
|
|
3720
|
+
/** The mean weighted by the time from each reading to the next. */
|
|
3721
|
+
mean: number;
|
|
3722
|
+
};
|
|
3723
|
+
type AggregatedTraceGauge = {
|
|
3724
|
+
/** Unique among the gauges of its {@link thread}. */
|
|
3725
|
+
name: string;
|
|
3726
|
+
/** The name of the thread the gauge is a quantity of, if it is one's. */
|
|
3727
|
+
thread: string | undefined;
|
|
3728
|
+
metric: Metric;
|
|
3729
|
+
/** The number of readings. */
|
|
3730
|
+
count: number;
|
|
3731
|
+
min: number;
|
|
3732
|
+
max: number;
|
|
3733
|
+
/** The earliest reading's value, or the first one's when none is timed. */
|
|
3734
|
+
first: number;
|
|
3735
|
+
/** The latest reading's value, or the last one's when none is timed. */
|
|
3736
|
+
last: number;
|
|
3737
|
+
/** What the readings' times state, or `undefined` when they are untimed. */
|
|
3738
|
+
timing: AggregatedTraceGaugeTiming | undefined;
|
|
3739
|
+
/**
|
|
3740
|
+
* The gauge's level across the trace: the highest reading within each equal
|
|
3741
|
+
* part of the recorded duration, or of the readings' order when they are
|
|
3742
|
+
* untimed. A part with no reading holds the level of the reading before it,
|
|
3743
|
+
* and is `undefined` before the first reading.
|
|
3744
|
+
*/
|
|
3745
|
+
trend: (number | undefined)[];
|
|
3746
|
+
};
|
|
3747
|
+
declare class TraceAggregator implements InputAggregator<AggregatedTrace> {
|
|
3748
|
+
#private;
|
|
3749
|
+
constructor(trace: Trace);
|
|
3750
|
+
detectOrigin(detector: OriginDetector): void;
|
|
3751
|
+
aggregate(_options: AggregationProfileToMdOptions, context: ProfileToMdContext): AggregatedTrace;
|
|
3752
|
+
}
|
|
3753
|
+
declare const modalitySpecs: readonly [{
|
|
3754
|
+
readonly categorySet: {
|
|
3755
|
+
readonly title: "Function categories";
|
|
3756
|
+
readonly noun: "function";
|
|
3757
|
+
readonly categories: readonly ["ours", "third-party", "stdlib", "native", "unknown", "garbage-collector", "compiler", "jit", "regexp", "kernel", "idle"];
|
|
3758
|
+
};
|
|
3759
|
+
readonly locations: ({ functions }: {
|
|
3760
|
+
functions: readonly AggregatedCallStackProfileFunction[];
|
|
3761
|
+
}) => Iterable<EntityLocation>;
|
|
3762
|
+
readonly entries: ({ functions }: {
|
|
3763
|
+
functions: readonly AggregatedCallStackProfileFunction[];
|
|
3764
|
+
}) => Iterable<AggregatedCallStackProfileFunction>;
|
|
3765
|
+
readonly categories: ({ functions }: {
|
|
3766
|
+
functions: readonly AggregatedCallStackProfileFunction[];
|
|
3767
|
+
}) => ("ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle")[];
|
|
3768
|
+
readonly id: "call-stack-profile";
|
|
3769
|
+
readonly aggregator: (profile: CallStackProfile, reader: RecordReader) => CallStackProfileAggregator;
|
|
3770
|
+
readonly format: (profile: AggregatedCallStackProfile, options: FormattingProfileToMdOptions) => RootContent[];
|
|
3771
|
+
readonly formatDiff: (base: AggregatedCallStackProfile, current: AggregatedCallStackProfile, options: FormattingProfileToMdOptions) => RootContent[];
|
|
3772
|
+
}, {
|
|
3773
|
+
readonly categorySet: {
|
|
3774
|
+
readonly title: "Function categories";
|
|
3775
|
+
readonly noun: "function";
|
|
3776
|
+
readonly categories: readonly ["ours", "third-party", "stdlib", "native", "unknown", "garbage-collector", "compiler", "jit", "regexp", "kernel", "idle"];
|
|
3777
|
+
};
|
|
3778
|
+
readonly locations: ({ functions }: {
|
|
3779
|
+
functions: readonly AggregatedCallGraphFunction[];
|
|
3780
|
+
}) => Iterable<EntityLocation>;
|
|
3781
|
+
readonly entries: ({ functions }: {
|
|
3782
|
+
functions: readonly AggregatedCallGraphFunction[];
|
|
3783
|
+
}) => Iterable<AggregatedCallGraphFunction>;
|
|
3784
|
+
readonly categories: ({ functions }: {
|
|
3785
|
+
functions: readonly AggregatedCallGraphFunction[];
|
|
3786
|
+
}) => ("ours" | "third-party" | "stdlib" | "native" | "unknown" | "garbage-collector" | "compiler" | "jit" | "regexp" | "kernel" | "idle")[];
|
|
3787
|
+
readonly id: "call-graph";
|
|
3788
|
+
readonly aggregator: (graph: CallGraph, reader: RecordReader) => CallGraphAggregator;
|
|
3789
|
+
readonly format: (graph: AggregatedCallGraph, options: FormattingProfileToMdOptions) => RootContent[];
|
|
3790
|
+
readonly formatDiff: (base: AggregatedCallGraph, current: AggregatedCallGraph, options: FormattingProfileToMdOptions) => RootContent[];
|
|
3791
|
+
}, {
|
|
3792
|
+
readonly id: "heap-snapshot";
|
|
3793
|
+
readonly categorySet: {
|
|
3794
|
+
readonly title: "Heap snapshot categories";
|
|
3795
|
+
readonly noun: "heap snapshot node";
|
|
3796
|
+
readonly categories: readonly ["object", "array", "string", "concatenated-string", "sliced-string", "function", "code", "regexp", "number", "big-number", "symbol", "native", "object-shape", "internal", "synthetic", "unknown"];
|
|
3797
|
+
};
|
|
3798
|
+
readonly aggregator: (snapshot: HeapSnapshot, reader: RecordReader) => HeapSnapshotAggregator;
|
|
3799
|
+
readonly format: (snapshot: AggregatedHeapSnapshot, options: FormattingProfileToMdOptions) => RootContent[];
|
|
3800
|
+
readonly formatDiff: (base: AggregatedHeapSnapshot, current: AggregatedHeapSnapshot, options: FormattingProfileToMdOptions) => RootContent[];
|
|
3801
|
+
readonly locations: (snapshot: AggregatedHeapSnapshot) => Iterable<EntityLocation>;
|
|
3802
|
+
readonly entries: ({ constructors, functions }: AggregatedHeapSnapshot) => Iterable<AggregatedHeapSnapshotEntity>;
|
|
3803
|
+
readonly categories: (snapshot: AggregatedHeapSnapshot) => MapIterator<"string" | "number" | "symbol" | "object" | "function" | "code" | "native" | "unknown" | "regexp" | "array" | "concatenated-string" | "sliced-string" | "big-number" | "object-shape" | "internal" | "synthetic">;
|
|
3804
|
+
}, {
|
|
3805
|
+
readonly id: "trace";
|
|
3806
|
+
readonly categorySet: {
|
|
3807
|
+
readonly title: "Trace event categories";
|
|
3808
|
+
readonly noun: "trace event";
|
|
3809
|
+
readonly categories: readonly ["script", "parsing", "compilation", "garbage-collection-pause", "garbage-collection", "style", "layout", "paint", "io", "other"];
|
|
3810
|
+
};
|
|
3811
|
+
readonly aggregator: (trace: Trace, reader: RecordReader) => TraceAggregator;
|
|
3812
|
+
readonly format: (trace: AggregatedTrace, options: FormattingProfileToMdOptions) => RootContent[];
|
|
3813
|
+
readonly formatDiff: (base: AggregatedTrace, current: AggregatedTrace, options: FormattingProfileToMdOptions) => RootContent[];
|
|
3814
|
+
readonly locations: () => never[];
|
|
3815
|
+
readonly entries: ({ spans, instants }: AggregatedTrace) => Iterable<AggregatedTraceEntity>;
|
|
3816
|
+
readonly categories: (trace: AggregatedTrace) => MapIterator<"script" | "parsing" | "compilation" | "garbage-collection-pause" | "garbage-collection" | "style" | "layout" | "paint" | "io" | "other">;
|
|
3817
|
+
}];
|
|
3818
|
+
type RegisteredModalitySpec = (typeof modalitySpecs)[number];
|
|
3819
|
+
/** An entry of an aggregated input, which `showEntry` filters. */
|
|
3820
|
+
type AggregatedProfileEntry = ReturnType<RegisteredModalitySpec[`entries`]> extends Iterable<infer Entry> ? Entry : never;
|
|
1931
3821
|
/**
|
|
1932
3822
|
* Converts the given profile data to Markdown.
|
|
1933
3823
|
*
|
|
1934
3824
|
* See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
|
|
1935
3825
|
* for supported formats and generation instructions.
|
|
1936
3826
|
*/
|
|
1937
|
-
declare const profileToMd: (input: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
|
|
3827
|
+
export declare const profileToMd: (input: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
|
|
1938
3828
|
/**
|
|
1939
3829
|
* Asynchronously converts the given profile data to Markdown.
|
|
1940
3830
|
*
|
|
1941
3831
|
* See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
|
|
1942
3832
|
* for supported formats and generation instructions.
|
|
1943
3833
|
*/
|
|
1944
|
-
declare const profileToMdAsync: (input: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
|
|
3834
|
+
export declare const profileToMdAsync: (input: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
|
|
1945
3835
|
/**
|
|
1946
3836
|
* Diffs the given base and current profile data, returning the difference as
|
|
1947
3837
|
* Markdown.
|
|
@@ -1951,7 +3841,7 @@ declare const profileToMdAsync: (input: ProfileInput<AsyncProfileData>, options?
|
|
|
1951
3841
|
* See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
|
|
1952
3842
|
* for supported formats and generation instructions.
|
|
1953
3843
|
*/
|
|
1954
|
-
declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
|
|
3844
|
+
export declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
|
|
1955
3845
|
/**
|
|
1956
3846
|
* Asynchronously diffs the given base and current profile data, returning the
|
|
1957
3847
|
* difference as Markdown.
|
|
@@ -1961,18 +3851,18 @@ declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileIn
|
|
|
1961
3851
|
* See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs)
|
|
1962
3852
|
* for supported formats and generation instructions.
|
|
1963
3853
|
*/
|
|
1964
|
-
declare const diffProfilesAsync: (base: ProfileInput<AsyncProfileData>, current: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
|
|
1965
|
-
//#endregion
|
|
1966
|
-
//#region src/error.d.ts
|
|
3854
|
+
export declare const diffProfilesAsync: (base: ProfileInput<AsyncProfileData>, current: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
|
|
1967
3855
|
/**
|
|
1968
3856
|
* Thrown when a caller's input or options are unusable: an unrecognized
|
|
1969
3857
|
* format, a malformed profile, an invalid option.
|
|
1970
3858
|
*
|
|
1971
3859
|
* A failure the caller cannot fix throws a plain `Error` instead, because such
|
|
1972
|
-
* a failure is a bug in this package.
|
|
3860
|
+
* a failure is a bug in this package. The exception is a parser failing on an
|
|
3861
|
+
* error it did not classify, which is either an input violating the format in
|
|
3862
|
+
* a way the parser does not check or a parser bug. That failure throws a
|
|
3863
|
+
* `ProfilerMdError` too, and `mayBeParserBug` identifies it.
|
|
1973
3864
|
*/
|
|
1974
|
-
declare class ProfilerMdError extends Error {
|
|
3865
|
+
export declare class ProfilerMdError extends Error {
|
|
1975
3866
|
constructor(message: string, options?: ErrorOptions);
|
|
1976
3867
|
}
|
|
1977
|
-
|
|
1978
|
-
export { type AggregatedProfileEntry, type AsyncProfileData, type EntryMatch, type FileReference, type Format, type FunctionCategory, type LogicalReference, type Origin, type ProfileData, type ProfileEntry, type ProfileInput, type ProfileToMdContext, type ProfileToMdOptions, ProfilerMdError, type SourceLocation, type SourceMap, type SourceReference, defaultCategorizeFunctions, defaultMatchEntry, defaultShowEntry, diffProfiles, diffProfilesAsync, isSyntheticEntry, profileToMd, profileToMdAsync };
|
|
3868
|
+
export type { AggregatedProfileEntry, AsyncProfileData, EntryMatch, FileReference, Format, FunctionCategory, LogLevel, Logger, LogicalReference, Origin, ProfileData, ProfileEntry, ProfileInput, ProfileToMdContext, ProfileToMdOptions, SourceLocation, SourceMap, SourceReference };
|