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/cli.mjs +1646 -920
- package/dist/index.d.mts +91 -36
- package/dist/index.js +2 -2
- package/package.json +24 -12
- package/readme.md +31 -22
package/dist/index.d.mts
CHANGED
|
@@ -1,38 +1,48 @@
|
|
|
1
|
-
//#region src/
|
|
2
|
-
/** A
|
|
3
|
-
type
|
|
4
|
-
/** The
|
|
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
|
|
7
|
-
* code.
|
|
13
|
+
* The name of the entity corresponding to this entry (e.g. a function name).
|
|
8
14
|
*/
|
|
9
|
-
|
|
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
|
|
12
|
-
type
|
|
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
|
|
34
|
+
* Whether to include the given entry in the Markdown output.
|
|
21
35
|
*
|
|
22
|
-
* Excluding
|
|
23
|
-
*
|
|
24
|
-
* Defaults to {@link defaultIncludeCallFrame}.
|
|
36
|
+
* Excluding an entry does not exclude it from metric computations.
|
|
25
37
|
*/
|
|
26
|
-
|
|
38
|
+
includeEntry?: (entry: ProfileEntry) => boolean;
|
|
27
39
|
/**
|
|
28
|
-
* Whether the given
|
|
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
|
-
|
|
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
|
|
58
|
+
* Returns whether to include the given entry in the Markdown output.
|
|
49
59
|
*
|
|
50
|
-
*
|
|
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
|
-
*
|
|
53
|
-
* display. For example, Node internals related to ESM loading are excluded.
|
|
69
|
+
* Excludes `node_modules` only by default.
|
|
54
70
|
*/
|
|
55
|
-
declare const
|
|
71
|
+
declare const defaultIsThirdPartyEntry: (entry: ProfileEntry) => boolean;
|
|
72
|
+
//#endregion
|
|
73
|
+
//#region src/formats/pprof/index.d.ts
|
|
56
74
|
/**
|
|
57
|
-
*
|
|
75
|
+
* Converts the given pprof to Markdown.
|
|
58
76
|
*
|
|
59
|
-
*
|
|
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
|
-
*
|
|
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
|
|
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 |
|
|
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
|
-
* - [`
|
|
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 |
|
|
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 |
|
|
163
|
+
declare const v8HeapSnapshotToMd: (data: string | Uint8Array, options?: ProfileToMdOptions) => string;
|
|
109
164
|
//#endregion
|
|
110
|
-
export {
|
|
165
|
+
export { type ProfileEntry, type ProfileToMdOptions, defaultIncludeEntry, defaultIsThirdPartyEntry, pprofToMd, speedscopeProfileToMd, v8CpuProfileToMd, v8HeapProfileToMd, v8HeapSnapshotToMd };
|