profiler-md 0.8.1 → 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.
@@ -0,0 +1,150 @@
1
+ .TH "PROFILER\-MD" 1 "November 2026" "profiler\-md 0.9.0"
2
+ .SH NAME
3
+ profiler\-md \- Converts performance profiles to human and LLM friendly Markdown.
4
+ .SH SYNOPSIS
5
+ .B "profiler\-md"
6
+ ([\fIOPTIONS\fR] [\fIFILE\fR] | [\fIOPTIONS\fR] \fIBASE\fR \fICURRENT\fR | \fB\-\-help\fR [\fITOPIC\fR])
7
+ .SH DESCRIPTION
8
+ Converts a profile to Markdown, or diffs a base profile against a current one.
9
+ .PP
10
+ Run \fBprofiler\-md \-\-help <language>\fR for how to profile a language, and \fBprofiler\-md \-\-help <format>\fR for what a format contains.
11
+ .SH "ARGUMENTS"
12
+ .TP
13
+ \fIFILE\fR
14
+ Profile to convert (default: stdin)
15
+ .TP
16
+ \fIBASE\fR
17
+ Base profile to diff
18
+ .TP
19
+ \fICURRENT\fR
20
+ Current profile to diff against the base
21
+ .SH "OUTPUT"
22
+ .TP
23
+ \fB\-o\fR, \fB\-\-output\fR \fIFILE\fR
24
+ Output file (default: - for stdout)
25
+ .TP
26
+ \fB\-\-log\-level\fR \fILEVEL\fR
27
+ Verbosity of diagnostics printed to stderr, overriding $PROFILER_MD_LOG (default: warn)
28
+ .TP
29
+ \fB\-\-no\-pager\fR
30
+ Disable stdout paging (default: auto)
31
+ .TP
32
+ \fB\-\-color\fR, \fB\-\-no\-color\fR
33
+ Enable or disable ANSI syntax highlighting (default: auto)
34
+ .SH "INPUT"
35
+ .TP
36
+ \fB\-f\fR, \fB\-\-format\fR \fIFORMAT\fR
37
+ Input profile format (default: auto)
38
+ .TP
39
+ \fB\-r\fR, \fB\-\-origin\fR \fIORIGIN\fR
40
+ Input profile origin (default: auto)
41
+ .TP
42
+ \fB\-\-source\-maps\fR \fIGLOB\fR
43
+ Source maps (JSON or inline) to apply to locations (repeatable)
44
+ .TP
45
+ \fB\-\-base\-url\fR \fISTRING\fR
46
+ Base URL or path to show paths relative to, or auto to infer one from the program's own code (default: cwd)
47
+ .SH "RANKING"
48
+ .TP
49
+ \fB\-\-top\-n\fR \fIN\fR
50
+ Entries to show per ranking, including category subsections (default: 20)
51
+ .TP
52
+ \fB\-\-min\-category\-share\fR \fIFRACTION\fR
53
+ Share of the shown entries' self values a category needs for its own subsection, from 0 to 1 (default: 0.01)
54
+ .SH "FILTERING"
55
+ .TP
56
+ \fB\-\-category\fR \fIREGEX=CATEGORY\fR
57
+ Categorize functions whose name or location matches REGEX as CATEGORY, first rule winning (repeatable)
58
+ .TP
59
+ \fB\-\-hide\fR \fIREGEX\fR
60
+ Hide entries whose name or location matches REGEX, still counting hidden entries in totals (repeatable)
61
+ .TP
62
+ \fB\-\-show\fR \fIREGEX\fR
63
+ Show only entries whose name or location matches REGEX, still counting hidden entries in totals (repeatable)
64
+ .TP
65
+ \fB\-\-hide\-category\fR \fICATEGORY\fR
66
+ Hide entries of CATEGORY, still counting hidden entries in totals (repeatable)
67
+ .TP
68
+ \fB\-\-show\-category\fR \fICATEGORY\fR
69
+ Show only entries of CATEGORY, still counting hidden entries in totals (repeatable)
70
+ .SH "DIFFING"
71
+ .TP
72
+ \fB\-\-match\-name\fR \fIREGEX=REPLACEMENT\fR
73
+ Rewrite names matching REGEX to REPLACEMENT when pairing diffed entries (repeatable)
74
+ .TP
75
+ \fB\-\-match\-location\fR \fIREGEX=REPLACEMENT\fR
76
+ Rewrite locations (URL, path, or logical name) matching REGEX to REPLACEMENT when pairing diffed entries (repeatable)
77
+ .SH "HELP"
78
+ .TP
79
+ \fB\-h\fR, \fB\-\-help\fR \fI[TOPIC]\fR
80
+ Show this help message or topic docs
81
+ .TP
82
+ \fB\-\-version\fR
83
+ Show the version
84
+ .TP
85
+ \fB\-\-completion\fR \fISHELL\fR
86
+ Print a completion script for SHELL (bash, fish, nu, pwsh, or zsh)
87
+ .SH "FORMATS"
88
+ .TP
89
+ 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
90
+ .SH "ORIGINS"
91
+ .TP
92
+ async-profiler, bun, chrome, clang, deno, dotnet-trace, eflambe, excimer, ghc, go, gperftools, jdk, memray, nix, node, node-pprof, perf, pprof-jl, pprof-rs, profile-jl, py-spy, pyinstrument, rbspy, safari, simpleperf, systing, tachyon, tsc, unknown, valgrind
93
+ .SH "FUNCTION CATEGORIES"
94
+ .TP
95
+ ours, third-party, stdlib, native, unknown, garbage-collector, compiler, jit, regexp, kernel, idle
96
+ .SH "HEAP SNAPSHOT CATEGORIES"
97
+ .TP
98
+ object, array, string, concatenated-string, sliced-string, function, code, regexp, number, big-number, symbol, native, object-shape, internal, synthetic, unknown
99
+ .SH "TRACE EVENT CATEGORIES"
100
+ .TP
101
+ script, parsing, compilation, garbage-collection-pause, garbage-collection, style, layout, paint, io, other
102
+ .SH "LANGUAGES"
103
+ .TP
104
+ c/cpp, csharp/fsharp, elixir/erlang, fortran, go, haskell, java/kotlin/groovy, javascript/typescript, julia, nix, php, python, ruby, rust, swift, zig
105
+ .SH "ENVIRONMENT"
106
+ .TP
107
+ PROFILER_MD_LOG
108
+ Verbosity of diagnostics printed to stderr when \fB\-\-log\-level\fR is not passed (default: warn)
109
+ .TP
110
+ PAGER
111
+ Pager for stdout output, or an empty value to disable paging (default: less)
112
+ .TP
113
+ LESS
114
+ Flags passed to less (default: FIRSX -#6)
115
+ .TP
116
+ NO_COLOR
117
+ Disables ANSI syntax highlighting unless \fB\-\-color\fR is passed
118
+ .TP
119
+ FORCE_COLOR
120
+ Enables ANSI syntax highlighting, or disables it when 0, overriding \fB\-\-color\fR and \fB\-\-no\-color\fR
121
+ .SH "EXIT STATUS"
122
+ .TP
123
+ 0
124
+ Success
125
+ .TP
126
+ 1
127
+ The input or a file could not be read, converted, or written, or profiler-md failed with a bug
128
+ .TP
129
+ 2
130
+ The flags or arguments are invalid
131
+ .SH "EXAMPLES"
132
+ .TP
133
+ \fBprofiler\-md profile.cpuprofile\fR
134
+ Convert a profile, paged and syntax highlighted
135
+ .TP
136
+ \fBprofiler\-md base.cpuprofile current.cpuprofile\fR
137
+ Diff two profiles or two heap snapshots
138
+ .TP
139
+ \fBprofiler\-md profile.pb.gz \-o profile.md\fR
140
+ Write the Markdown to a file
141
+ .TP
142
+ \fBnode \-\-cpu\-prof app.js && cat *.cpuprofile | profiler\-md\fR
143
+ Read a profile from stdin
144
+ .TP
145
+ \fBprofiler\-md \-\-help python\fR
146
+ Show how to profile a language
147
+ .SH BUGS
148
+ Report bugs at \fIhttps://github.com/TomerAberbach/profiler\-md/issues\fR.
149
+ .SH AUTHOR
150
+ Tomer Aberbach <tomer@aberba.ch>