profiler-md 0.2.0 → 0.4.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.
Files changed (41) hide show
  1. package/dist/cli/index.mjs +2787 -1669
  2. package/dist/index.d.mts +249 -78
  3. package/dist/index.js +2 -2
  4. package/docs/formats/collapsed.md +12 -0
  5. package/docs/formats/jsc-heap-snapshot.md +13 -0
  6. package/docs/formats/webkit-timeline-recording.md +9 -0
  7. package/docs/languages/c.md +1 -1
  8. package/docs/languages/cpp.md +136 -0
  9. package/docs/languages/csharp.md +49 -0
  10. package/docs/languages/elixir.md +42 -0
  11. package/docs/languages/erlang.md +42 -0
  12. package/docs/languages/fsharp.md +49 -0
  13. package/docs/languages/go.md +2 -2
  14. package/docs/languages/java.md +10 -7
  15. package/docs/languages/javascript.md +69 -0
  16. package/docs/languages/julia.md +42 -0
  17. package/docs/languages/kotlin.md +120 -0
  18. package/docs/languages/python.md +10 -4
  19. package/docs/languages/typescript.md +254 -0
  20. package/examples/bun.cpuprofile.md +94 -116
  21. package/examples/deno.cpuprofile.md +11 -18
  22. package/examples/jsc-heap-snapshot.base.json.md +507 -0
  23. package/examples/jsc-heap-snapshot.current.json.md +504 -0
  24. package/examples/jsc-heap-snapshot.diff.json.md +119 -0
  25. package/examples/node.base.cpuprofile.md +451 -0
  26. package/examples/node.current.cpuprofile.md +449 -0
  27. package/examples/node.diff.cpuprofile.md +82 -0
  28. package/examples/node.heapprofile.md +178 -223
  29. package/examples/node.heapsnapshot.md +268 -266
  30. package/examples/node.pprof.md +36 -45
  31. package/examples/python.base.collapsed.md +116 -0
  32. package/examples/python.current.collapsed.md +125 -0
  33. package/examples/python.diff.collapsed.md +51 -0
  34. package/examples/{rust1.pprof.md → rust.base.pprof.md} +223 -226
  35. package/examples/{rust2.pprof.md → rust.current.pprof.md} +199 -199
  36. package/examples/rust.diff.pprof.md +117 -0
  37. package/examples/webkit-timeline-recording.json.md +434 -0
  38. package/package.json +30 -18
  39. package/readme.md +173 -85
  40. package/examples/node.cpuprofile.md +0 -499
  41. package/examples/node.speedscope.json.md +0 -416
package/dist/index.d.mts CHANGED
@@ -1,25 +1,180 @@
1
1
  import { RawSourceMap as SourceMap } from "source-map-js";
2
+
3
+ //#region src/helpers/types.d.ts
4
+ type TypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float16Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
5
+ /**
6
+ * Recursively makes all properties of `T` readonly, including nested objects,
7
+ * arrays, and `Map`/`Set` collections.
8
+ */
9
+ 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;
10
+ //#endregion
2
11
  //#region src/location.d.ts
3
- /** A {@link URL} to a file, potentially with line and column information. */
4
- type ProfileLocation = {
5
- url: URL; /** The 1-based line number in the file at {@link ProfileLocation.url}. */
6
- line?: number; /** The 1-based column number in the file at {@link ProfileLocation.url}. */
12
+ /** A file reference, potentially with line and column information. */
13
+ type SourceLocation = FileReference & {
14
+ /** The 1-based line number in the file. */line?: number; /** The 1-based column number in the file. */
7
15
  column?: number;
8
16
  };
17
+ declare const fileReferenceId: (fileReference: DeepReadonly<FileReference>) => string;
18
+ type FileReference = {
19
+ type: `absolute`;
20
+ url: URL;
21
+ } | {
22
+ type: `relative`;
23
+ path: string;
24
+ };
25
+ //#endregion
26
+ //#region src/profile/aggregate.d.ts
27
+ /** An aggregation of samples taken at a given line within a function's body. */
28
+ type AggregatedProfileLineMetrics = {
29
+ /**
30
+ * The number of samples taken directly within the function's body at this
31
+ * line.
32
+ */
33
+ sampleCount: number;
34
+ /**
35
+ * For each metric in {@link AggregatedProfile.metrics}, the sum of values from
36
+ * samples taken directly within the function's body at this line.
37
+ */
38
+ values: Float64Array;
39
+ };
40
+ /**
41
+ * An aggregation of samples taken directly within a function's body with a
42
+ * given direct caller.
43
+ */
44
+ type AggregatedProfileCallerMetrics = {
45
+ /** The caller corresponding to the ID. */caller: AggregatedProfileFunction;
46
+ /**
47
+ * The number of samples taken directly within the function's body with this
48
+ * caller.
49
+ */
50
+ selfSampleCount: number;
51
+ /**
52
+ * For each metric in {@link AggregatedProfile.metrics}, the sum of values from
53
+ * samples taken directly within the function's body with this caller.
54
+ */
55
+ selfValues: Float64Array;
56
+ };
57
+ /**
58
+ * An aggregation of samples taken within a function's body, _and_ all its
59
+ * callees, with a given direct callee.
60
+ */
61
+ type AggregatedProfileCalleeMetrics = {
62
+ /** The callee corresponding to the ordinal. */callee: AggregatedProfileFunction;
63
+ /**
64
+ * The number of samples taken directly within the function's, _and_ all
65
+ * its callees, with this callee.
66
+ */
67
+ totalSampleCount: number;
68
+ /**
69
+ * For each metric in {@link AggregatedProfile.metrics}, the sum of values from
70
+ * samples taken directly within the function's body, _and_ all its
71
+ * callees. with this callee.
72
+ */
73
+ totalValues: Float64Array;
74
+ };
75
+ /**
76
+ * An aggregation of data from every sample involving a given function within a
77
+ * profile.
78
+ */
79
+ type AggregatedProfileFunction = {
80
+ type: `function`; /** An index that uniquely identifies this function. */
81
+ id: number; /** The name of the function in code. */
82
+ name: string; /** Where the function was defined, if known. */
83
+ location?: SourceLocation; /** A string describing the category of functions this function belongs to.*/
84
+ category: string;
85
+ /**
86
+ * The number of samples taken directly within the function's body, excluding
87
+ * its callees.
88
+ */
89
+ selfSampleCount: number;
90
+ /**
91
+ * The number of samples taken directly within the function's body _and_ all
92
+ * its callees.
93
+ */
94
+ totalSampleCount: number;
95
+ /**
96
+ * For each metric in {@link AggregatedProfile.metrics}, the sum of values from samples
97
+ * taken directly within the function's body, excluding its callees.
98
+ */
99
+ selfValues: Float64Array;
100
+ /**
101
+ * For each metric in {@link AggregatedProfile.metrics}, the sum of values from samples
102
+ * taken directly within the function's body _and_ all its callees.
103
+ */
104
+ totalValues: Float64Array; /** 1-based line number to values and sample count for that line. */
105
+ lineToMetrics: Map<number, AggregatedProfileLineMetrics>;
106
+ /**
107
+ * Direct caller id to values and sample count with that caller's calls to
108
+ * this function.
109
+ */
110
+ callerIdToMetrics: Map<number, AggregatedProfileCallerMetrics>;
111
+ /**
112
+ * Direct callee id to values and sample count for that callee's calls where
113
+ * this function was a direct or transitive caller.
114
+ */
115
+ calleeIdToMetrics: Map<number, AggregatedProfileCalleeMetrics>;
116
+ };
117
+ //#endregion
118
+ //#region src/snapshot/aggregate.d.ts
119
+ type AggregatedSnapshotNode = {
120
+ type: `node`; /** Unique ID for this node that can also be used as an index. */
121
+ id: number; /** A human readable label for this node. */
122
+ name?: string; /** Bytes allocated directly for this node. */
123
+ selfSize: number;
124
+ /**
125
+ * Bytes allocated for this node, as well as all nodes that would be freed if
126
+ * the node were garbage collected.
127
+ */
128
+ retainedSize: number; /** The exact location where the node was defined. */
129
+ location?: SourceLocation;
130
+ };
9
131
  //#endregion
10
132
  //#region src/options.d.ts
133
+ /** Profile data that can be synchronously parsed and converted to Markdown. */
134
+ type ProfileData = string | Uint8Array | Iterable<Uint8Array>;
135
+ /** Profile data that can be asynchronously parsed and converted to Markdown. */
136
+ type AsyncProfileData = Blob | ReadableStream<Uint8Array>;
137
+ /**
138
+ * Profile data with or without an explicit format.
139
+ *
140
+ * The format is auto-detected if no format is specified.
141
+ */
142
+ type ProfileInput<Data> = Data | {
143
+ data: Data;
144
+ format: Format;
145
+ };
146
+ /** The category of code an entry originated from. */
147
+ type EntryOrigin = `ours` | `stdlib` | `third-party`;
11
148
  /** A single entry in a rendered profile. */
12
149
  type ProfileEntry = {
150
+ /** An index that uniquely identifies this entry. */id: number;
13
151
  /**
14
- * The name of the entity corresponding to this entry (e.g. a function name).
152
+ * The name of the entity corresponding to this entry (e.g. a function name)
153
+ * if it has one.
15
154
  */
16
- name: string;
155
+ name?: string;
17
156
  /**
18
157
  * The location where the entity corresponding to this entry was defined, or
19
158
  * undefined if it's unknown.
20
159
  */
21
- location?: ProfileLocation;
160
+ location?: SourceLocation;
22
161
  };
162
+ /**
163
+ * Normalized entry fields used to match an entry across diffed profiles.
164
+ *
165
+ * Only affects matching; the entry's displayed name and location are
166
+ * unchanged.
167
+ */
168
+ type NormalizedEntry = {
169
+ /** The name to match by. Omit to match by the entry's name. */name?: string;
170
+ /**
171
+ * The location to match by, as a URL or file path string. Omit to match by
172
+ * the entry's location.
173
+ */
174
+ location?: string;
175
+ };
176
+ /** A aggregated entry in a rendered profile. */
177
+ type AggregatedProfileEntry = AggregatedProfileFunction | AggregatedSnapshotNode;
23
178
  /** Options for profile to Markdown converters. */
24
179
  type ProfileToMdOptions = {
25
180
  /**
@@ -32,28 +187,17 @@ type ProfileToMdOptions = {
32
187
  */
33
188
  topN?: number;
34
189
  /**
35
- * Whether to include the given entry in the Markdown output.
36
- *
37
- * Excluding an entry does not exclude it from metric computations.
38
- */
39
- includeEntry?: (entry: ProfileEntry) => boolean;
40
- /**
41
- * Whether the given entry points to third-party code.
190
+ * Base URL to show paths relative to in the Markdown output.
42
191
  *
43
- * This is used to compute summaries in the Markdown output and make other
44
- * decisions about what's important to display.
45
- */
46
- isThirdPartyEntry?: (entry: ProfileEntry) => boolean;
47
- /**
48
- * The current working directory to use to make file paths relative in the
49
- * Markdown output.
192
+ * Accepts an absolute file path string or URL. File paths are converted to
193
+ * `file://` URLs internally.
50
194
  *
51
- * A value of `null` indicates that the paths should be absolute.
195
+ * A value of `null` indicates that URLs should be absolute.
52
196
  *
53
197
  * Defaults to `process.cwd()` when available. Otherwise leaves paths
54
198
  * absolute.
55
199
  */
56
- cwd?: string | null;
200
+ baseURL?: string | URL | null;
57
201
  /**
58
202
  * Source maps to apply when rendering profile locations.
59
203
  *
@@ -64,85 +208,112 @@ type ProfileToMdOptions = {
64
208
  * map's `file` field (and optionally `sourceRoot`).
65
209
  */
66
210
  sourceMaps?: SourceMap[] | Record<string, SourceMap>;
211
+ /**
212
+ * Returns a normalized name and location to match this entry by across
213
+ * diffed profiles, or `undefined` to match by the entry's own name and
214
+ * location.
215
+ *
216
+ * Only affects which entries are considered the same entity when diffing
217
+ * (profile functions and snapshot closures); displayed names and locations,
218
+ * categorization, and source map resolution always use the entry's real
219
+ * name and location. Matched entries display the current profile's name and
220
+ * location.
221
+ *
222
+ * Defaults to {@link defaultMatchEntry}, which strips known build hashes from
223
+ * locations so that the same function matches across profiles built from the
224
+ * same source.
225
+ */
226
+ matchEntry?: (entry: DeepReadonly<ProfileEntry>) => NormalizedEntry | undefined;
227
+ /**
228
+ * Returns an arbitrary category string for this entry.
229
+ *
230
+ * Used to compute a category breakdown in the Markdown output.
231
+ */
232
+ categorizeEntry?: (entry: DeepReadonly<ProfileEntry>) => EntryOrigin | (string & {});
233
+ /**
234
+ * Whether to include the given entry in the Markdown output.
235
+ *
236
+ * Not showing an entry does not exclude it from metric computations.
237
+ */
238
+ showEntry?: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
67
239
  };
68
240
  /**
69
- * Returns whether to include the given entry in the Markdown output.
70
- *
71
- * Excludes synthetic profile data and redundant internals by default.
241
+ * Returns a location to match this entry by with known build hashes (Cargo
242
+ * build-script and rustc commit-hash directories) stripped, or `undefined` if
243
+ * the location contains no known hashes.
72
244
  */
73
- declare const defaultIncludeEntry: ({
74
- name,
75
- location
76
- }: ProfileEntry) => boolean;
245
+ declare const defaultMatchEntry: (entry: DeepReadonly<ProfileEntry>) => NormalizedEntry | undefined;
77
246
  /**
78
- * Returns whether the given entry points to third-party code.
247
+ * Returns an arbitrary category string for this entry.
79
248
  *
80
- * Excludes `node_modules` only by default.
249
+ * Categorizes into `ours`, `stdlib`, `third-party`, and a few other categories
250
+ * by default.
81
251
  */
82
- declare const defaultIsThirdPartyEntry: (entry: ProfileEntry) => boolean;
83
- //#endregion
84
- //#region src/formats/pprof/index.d.ts
252
+ declare const defaultCategorizeEntry: (entry: DeepReadonly<ProfileEntry>) => EntryOrigin | (string & {});
85
253
  /**
86
- * Converts the given pprof to Markdown.
87
- *
88
- * It is assumed that {@link data} is a valid pprof (raw protobuf). The behavior
89
- * of this function is undefined for invalid profiles.
254
+ * Returns whether to include the given entry in the Markdown output.
90
255
  *
91
- * See the [pprof docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/pprof.md)
92
- * for supported tools and generation instructions (`profiler-md --help pprof`).
256
+ * Excludes synthetic and external-private entries.
93
257
  */
94
- declare const pprofToMd: (data: Uint8Array, options?: ProfileToMdOptions) => string;
95
- //#endregion
96
- //#region src/formats/speedscope/index.d.ts
258
+ declare const defaultShowEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
97
259
  /**
98
- * Converts the given Speedscope profile to Markdown.
260
+ * Returns true if the entry is a synthetic artifacts.
99
261
  *
100
- * It is assumed that {@link data} is a valid Speedscope JSON file. The behavior
101
- * of this function is undefined for invalid profiles.
262
+ * These entries are artifacts generated by the profiler and don't correspond to
263
+ * something that actually exists in code or at runtime. For example, a
264
+ * synthetic `(root)` node is typically created for heap snapshots.
265
+ */
266
+ declare const isSyntheticEntry: ({
267
+ name
268
+ }: DeepReadonly<AggregatedProfileEntry>) => boolean;
269
+ /**
270
+ * Returns true if the entry corresponds to an external function (`stdlib` or
271
+ * `third-party`) that's never directly called by `ours` code.
102
272
  *
103
- * See the [Speedscope docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/speedscope.md)
104
- * for supported tools and generation instructions
105
- * (`profiler-md --help speedscope`).
273
+ * These entries are typically implementation details of external code that your
274
+ * own code cannot directly call. Excluding these entries from the Markdown
275
+ * leaves only your code and the public API surface of `stdlib` and
276
+ * `third-party` code.
106
277
  */
107
- declare const speedscopeProfileToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
278
+ declare const isExternalImplementationDetailEntry: (entry: DeepReadonly<AggregatedProfileEntry>) => boolean;
108
279
  //#endregion
109
- //#region src/formats/v8/cpu-profile/index.d.ts
280
+ //#region src/formats/index.d.ts
110
281
  /**
111
- * Converts the given V8 CPU profile to Markdown.
282
+ * Converts the given profile data to Markdown.
112
283
  *
113
- * It is assumed that {@link data} is a valid profile. The behavior of this
114
- * function is undefined for invalid profiles.
284
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
285
+ * for supported formats and generation instructions.
286
+ */
287
+ declare const profileToMd: (input: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
288
+ /**
289
+ * Asynchronously converts the given profile data to Markdown.
115
290
  *
116
- * See the [V8 CPU profile docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/v8-cpu-profile.md)
117
- * for supported runtimes and generation instructions
118
- * (`profiler-md --help v8-cpu-profile`).
291
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
292
+ * for supported formats and generation instructions.
119
293
  */
120
- declare const v8CpuProfileToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
121
- //#endregion
122
- //#region src/formats/v8/heap-profile/index.d.ts
294
+ declare const profileToMdAsync: (input: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
123
295
  /**
124
- * Converts the given V8 sampling heap profile to Markdown.
296
+ * Diffs the given base and current profile data, returning the difference as
297
+ * Markdown.
125
298
  *
126
- * It is assumed that {@link data} is a valid profile. The behavior of this
127
- * function is undefined for invalid profiles.
299
+ * Each side accepts the same input as {@link profileToMd}.
128
300
  *
129
- * See the [V8 heap profile docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/v8-heap-profile.md)
130
- * for supported runtimes and generation instructions
131
- * (`profiler-md --help v8-heap-profile`).
301
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
302
+ * for supported formats and generation instructions.
132
303
  */
133
- declare const v8HeapProfileToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
134
- //#endregion
135
- //#region src/formats/v8/heap-snapshot/index.d.ts
304
+ declare const diffProfiles: (base: ProfileInput<ProfileData>, current: ProfileInput<ProfileData>, options?: ProfileToMdOptions) => string;
136
305
  /**
137
- * Converts the given V8 heap snapshot to Markdown.
306
+ * Asynchronously diffs the given base and current profile data, returning the
307
+ * difference as Markdown.
138
308
  *
139
- * It is assumed that {@link data} is a valid snapshot. The behavior of this
140
- * function is undefined for invalid snapshots.
309
+ * Each side accepts the same input as {@link profileToMdAsync}.
141
310
  *
142
- * See the [V8 heap snapshot docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats/v8-heap-snapshot.md)
143
- * for supported runtimes and generation instructions
144
- * (`profiler-md --help v8-heap-snapshot`).
311
+ * See the [docs](https://github.com/TomerAberbach/profiler-md/blob/main/docs/formats)
312
+ * for supported formats and generation instructions.
145
313
  */
146
- declare const v8HeapSnapshotToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
314
+ declare const diffProfilesAsync: (base: ProfileInput<AsyncProfileData>, current: ProfileInput<AsyncProfileData>, options?: ProfileToMdOptions) => Promise<string>;
315
+ declare const formats: readonly ["collapsed", "jsc-heap-snapshot", "pprof", "speedscope", "v8-cpu-profile", "v8-heap-profile", "v8-heap-snapshot", "webkit-timeline-recording"];
316
+ /** Supported profile format IDs. */
317
+ type Format = (typeof formats)[number];
147
318
  //#endregion
148
- export { type ProfileEntry, type ProfileToMdOptions, type SourceMap, defaultIncludeEntry, defaultIsThirdPartyEntry, pprofToMd, speedscopeProfileToMd, v8CpuProfileToMd, v8HeapProfileToMd, v8HeapSnapshotToMd };
319
+ export { type AggregatedProfileEntry, type AsyncProfileData, type EntryOrigin, type FileReference, type Format, type NormalizedEntry, type ProfileData, type ProfileEntry, type ProfileInput, type ProfileToMdOptions, type SourceLocation, type SourceMap, defaultCategorizeEntry, defaultMatchEntry, defaultShowEntry, diffProfiles, diffProfilesAsync, fileReferenceId, isExternalImplementationDetailEntry, isSyntheticEntry, profileToMd, profileToMdAsync };