profiler-md 0.0.1 → 0.1.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/index.d.mts CHANGED
@@ -1,38 +1,48 @@
1
- //#region src/v8/common.d.ts
2
- /** A single call frame in a V8 profile as seen by callers. */
3
- type V8ProfileCallFrame = {
4
- /** The name of the function, or undefined for anonymous functions. */functionName?: string;
1
+ //#region src/location.d.ts
2
+ /** A {@link URL} to a file, potentially with line and column information. */
3
+ type ProfileLocation = {
4
+ url: URL; /** The 1-based line number in the file at {@link ProfileLocation.url}. */
5
+ line?: number; /** The 1-based column number in the file at {@link ProfileLocation.url}. */
6
+ column?: number;
7
+ };
8
+ //#endregion
9
+ //#region src/options.d.ts
10
+ /** A single entry in a rendered profile. */
11
+ type ProfileEntry = {
5
12
  /**
6
- * The URL of the script this frame belongs to, or undefined if it's native
7
- * code.
13
+ * The name of the entity corresponding to this entry (e.g. a function name).
8
14
  */
9
- url?: URL;
15
+ name: string;
16
+ /**
17
+ * The location where the entity corresponding to this entry was defined, or
18
+ * undefined if it's unknown.
19
+ */
20
+ location?: ProfileLocation;
10
21
  };
11
- /** Options for V8 profile converters. */
12
- type V8ProfileToMdOptions = {
22
+ /** Options for profile to Markdown converters. */
23
+ type ProfileToMdOptions = {
13
24
  /**
14
25
  * The number of entries to display when computing the "top N" by some metric.
15
26
  *
27
+ * This value is also be used to limit subsection entry count by dividing it
28
+ * by a constant.
29
+ *
16
30
  * Defaults to 20.
17
31
  */
18
32
  topN?: number;
19
33
  /**
20
- * Whether to include the given call frame in the Markdown output.
34
+ * Whether to include the given entry in the Markdown output.
21
35
  *
22
- * Excluding a call frame does not exclude it from metric computations.
23
- *
24
- * Defaults to {@link defaultIncludeCallFrame}.
36
+ * Excluding an entry does not exclude it from metric computations.
25
37
  */
26
- includeCallFrame?: (callFrame: V8ProfileCallFrame) => boolean;
38
+ includeEntry?: (entry: ProfileEntry) => boolean;
27
39
  /**
28
- * Whether the given URL points to third-party code.
40
+ * Whether the given entry points to third-party code.
29
41
  *
30
42
  * This is used to compute summaries in the Markdown output and make other
31
43
  * decisions about what's important to display.
32
- *
33
- * Defaults to {@link defaultIsThirdPartyURL}.
34
44
  */
35
- isThirdPartyURL?: (url: URL) => boolean;
45
+ isThirdPartyEntry?: (entry: ProfileEntry) => boolean;
36
46
  /**
37
47
  * The current working directory to use to make file paths relative in the
38
48
  * Markdown output.
@@ -45,24 +55,52 @@ type V8ProfileToMdOptions = {
45
55
  cwd?: string | null;
46
56
  };
47
57
  /**
48
- * Returns whether to include the given call frame in the Markdown output.
58
+ * Returns whether to include the given entry in the Markdown output.
49
59
  *
50
- * This is the default value for {@link V8ProfileToMdOptions.includeCallFrame}.
60
+ * Excludes synthetic profile data and redundant internals by default.
61
+ */
62
+ declare const defaultIncludeEntry: ({
63
+ name,
64
+ location
65
+ }: ProfileEntry) => boolean;
66
+ /**
67
+ * Returns whether the given entry points to third-party code.
51
68
  *
52
- * It makes reasonable assumptions about which call frames are uninteresting to
53
- * display. For example, Node internals related to ESM loading are excluded.
69
+ * Excludes `node_modules` only by default.
54
70
  */
55
- declare const defaultIncludeCallFrame: (callFrame: V8ProfileCallFrame) => boolean;
71
+ declare const defaultIsThirdPartyEntry: (entry: ProfileEntry) => boolean;
72
+ //#endregion
73
+ //#region src/formats/pprof/index.d.ts
56
74
  /**
57
- * Returns whether the given URL points to third-party code.
75
+ * Converts the given pprof to Markdown.
58
76
  *
59
- * This is the default value for {@link V8ProfileToMdOptions.isThirdPartyURL}.
77
+ * It is assumed that {@link data} is a valid pprof (raw protobuf). The behavior
78
+ * of this function is undefined for invalid profiles.
60
79
  *
61
- * Excludes `node_modules` only by default.
80
+ * pprof can be generated by many tools, including:
81
+ * - Go's [`runtime/pprof`](https://pkg.go.dev/runtime/pprof) package
82
+ * - Node.js's [`pprof`](https://www.npmjs.com/package/pprof) npm package
83
+ * - Python's [`py-spy`](https://github.com/benfred/py-spy)
84
+ * - Rust's [`pprof-rs`](https://github.com/tikv/pprof-rs)
85
+ */
86
+ declare const pprofToMd: (data: Uint8Array, options?: ProfileToMdOptions) => string;
87
+ //#endregion
88
+ //#region src/formats/speedscope/index.d.ts
89
+ /**
90
+ * Converts the given speedscope profile to Markdown.
91
+ *
92
+ * It is assumed that {@link data} is a valid speedscope JSON file. The behavior
93
+ * of this function is undefined for invalid profiles.
94
+ *
95
+ * Speedscope profiles can be generated by many tools, including:
96
+ * - [speedscope](https://www.speedscope.app) (drag and drop any supported profile)
97
+ * - [rbspy](https://rbspy.github.io) for Ruby
98
+ * - [py-spy](https://github.com/benfred/py-spy) for Python (`--format speedscope`)
99
+ * - [pprof-rs](https://github.com/tikv/pprof-rs) for Rust
62
100
  */
63
- declare const defaultIsThirdPartyURL: (url: URL) => boolean;
101
+ declare const speedscopeProfileToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
64
102
  //#endregion
65
- //#region src/v8/cpu-profile/index.d.ts
103
+ //#region src/formats/v8/cpu-profile/index.d.ts
66
104
  /**
67
105
  * Converts the given V8 CPU profile to Markdown.
68
106
  *
@@ -71,14 +109,21 @@ declare const defaultIsThirdPartyURL: (url: URL) => boolean;
71
109
  *
72
110
  * You can generate a V8 CPU profile in several ways:
73
111
  * - [`node --cpu-prof`](https://nodejs.org/api/cli.html#cpu-prof)
74
- * - [`deno --cpu-prof`](https://docs.deno.com/runtime/fundamentals/debugging/#cpu-profiling)
112
+ * - [`deno run --cpu-prof`](https://docs.deno.com/runtime/fundamentals/debugging/#cpu-profiling)
75
113
  * - [`bun --cpu-prof`](https://bun.com/docs/project/benchmarking#cpu-profiling)
114
+ * (NOTE: output was incorrect until
115
+ * [v1.3.13](https://bun.com/blog/bun-v1.3.13#node-js-compatibility-improvements))
116
+ * - [`node --inspect`](https://nodejs.org/api/debugger.html#v8-inspector-integration-for-nodejs),
117
+ * [`deno run --inspect`](https://docs.deno.com/runtime/fundamentals/debugging/#--inspect),
118
+ * or [`bun --inspect`](https://bun.com/docs/runtime/debugger#inspect) with
119
+ * [Chrome DevTools](https://developer.chrome.com/docs/devtools/performance/nodejs)
120
+ * - [Chrome DevTools directly](https://developer.chrome.com/docs/devtools/performance#record)
76
121
  *
77
122
  * Lower the sampling interval to capture more granular data.
78
123
  */
79
- declare const v8CpuProfileToMd: (data: string | Buffer, options?: V8ProfileToMdOptions) => string;
124
+ declare const v8CpuProfileToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
80
125
  //#endregion
81
- //#region src/v8/heap-profile/index.d.ts
126
+ //#region src/formats/v8/heap-profile/index.d.ts
82
127
  /**
83
128
  * Converts the given V8 sampling heap profile to Markdown.
84
129
  *
@@ -87,14 +132,18 @@ declare const v8CpuProfileToMd: (data: string | Buffer, options?: V8ProfileToMdO
87
132
  *
88
133
  * You can generate a V8 heap profile in several ways:
89
134
  * - [`node --heap-prof`](https://nodejs.org/api/cli.html#--heap-prof)
90
- * - [`v8.writeHeapProfileSync()`](https://nodejs.org/api/v8.html#v8writeheapprofilesyncfilename)
135
+ * - [`node --inspect`](https://nodejs.org/api/debugger.html#v8-inspector-integration-for-nodejs),
136
+ * [`deno run --inspect`](https://docs.deno.com/runtime/fundamentals/debugging/#--inspect),
137
+ * or [`bun --inspect`](https://bun.com/docs/runtime/debugger#inspect) with
138
+ * [Chrome DevTools](https://developer.chrome.com/docs/devtools/memory-problems/allocation-profiler)
139
+ * - [Chrome DevTools directly](https://developer.chrome.com/docs/devtools/memory-problems/allocation-profiler)
91
140
  *
92
141
  * Note that [`bun --heap-prof`](https://bun.com/docs/project/benchmarking#heap-profiling)
93
142
  * generates a heap _snapshot_ on exit, not a heap _profile_.
94
143
  */
95
- declare const v8HeapProfileToMd: (data: string | Buffer, options?: V8ProfileToMdOptions) => string;
144
+ declare const v8HeapProfileToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
96
145
  //#endregion
97
- //#region src/v8/heap-snapshot/index.d.ts
146
+ //#region src/formats/v8/heap-snapshot/index.d.ts
98
147
  /**
99
148
  * Converts the given V8 heap snapshot to Markdown.
100
149
  *
@@ -103,8 +152,14 @@ declare const v8HeapProfileToMd: (data: string | Buffer, options?: V8ProfileToMd
103
152
  *
104
153
  * You can generate a V8 heap snapshot in several ways:
105
154
  * - [`node --heapsnapshot-signal`](https://nodejs.org/api/cli.html#--heapsnapshot-signalsignal)
155
+ * - [`bun --heap-prof`](https://bun.com/docs/project/benchmarking#heap-profiling)
106
156
  * - [`v8.writeHeapSnapshot()`](https://nodejs.org/api/v8.html#v8writeheapsnapshotfilename)
157
+ * - [`node --inspect`](https://nodejs.org/api/debugger.html#v8-inspector-integration-for-nodejs),
158
+ * [`deno run --inspect`](https://docs.deno.com/runtime/fundamentals/debugging/#--inspect),
159
+ * or [`bun --inspect`](https://bun.com/docs/runtime/debugger#inspect) with
160
+ * [Chrome DevTools](https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots)
161
+ * - [Chrome DevTools directly](https://developer.chrome.com/docs/devtools/memory-problems/heap-snapshots)
107
162
  */
108
- declare const v8HeapSnapshotToMd: (data: string | Buffer, options?: V8ProfileToMdOptions) => string;
163
+ declare const v8HeapSnapshotToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
109
164
  //#endregion
110
- export { V8ProfileCallFrame, V8ProfileToMdOptions, defaultIncludeCallFrame, defaultIsThirdPartyURL, v8CpuProfileToMd, v8HeapProfileToMd, v8HeapSnapshotToMd };
165
+ export { type ProfileEntry, type ProfileToMdOptions, defaultIncludeEntry, defaultIsThirdPartyEntry, pprofToMd, speedscopeProfileToMd, v8CpuProfileToMd, v8HeapProfileToMd, v8HeapSnapshotToMd };