1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
| | =head1 NAME
mwrap - run any command under mwrap
=head1 SYNOPSIS
# to trace a long-running program and access it via $DIR/$PID.sock:
MWRAP=socket_dir:$DIR mwrap COMMAND
# to trace a short-lived command and dump its output to a CSV:
MWRAP=dump_csv:$FILENAME mwrap COMMAND
=head1 DESCRIPTION
mwrap is a command-line to automatically add mwrap.so as an
LD_PRELOAD for any command. It will resolve malloc-family calls
to a Ruby file and line number, and it can also provide a backtrace
of native (C/C++) functions for non-Ruby programs.
=head1 ENVIRONMENT
C<MWRAP> is the only environment variable read. It contains multiple
options delimited by C<,> with names and values delimited by C<:>
=over 4
=item socket_dir:$DIR
This launches an embedded HTTP server in each process and binds it
to C<$DIR/$PID.sock>. C<curl --unix-socket $DIR/$PID.sock>
or L<mwrap-rproxy(1p)> (from L<https://80x24.org/mwrap-perl.git>) may
be used to access various endpoints in the HTTP server.
=item bt:$DEPTH
The backtrace depth for L<backtrace(3)> in addition to the Perl
file and line number where C<$DEPTH> is a non-negative number.
The maximum allowed value is 32, though values of 5 or less are
typically useful. Increasing this to even 2 or 3 can significantly
increase the amount of memory mwrap (and liburcu) itself uses.
This is only useful in conjunction with C<socket_dir>
This may be changed via POST request (see below).
Default: 0
=item dump_csv:$FILENAME
Dump CSV to the given filename.
This output matches the HTTP server output and includes column headers,
but is subject to change in future releases.
C<dump_csv> without the C<:> may also be used in conjunction with
C<dump_fd>, such as C<MWRAP=dump_fd:2,dump_csv>.
As of mwrap 3.0,
C<$FILENAME> may contain C<%p> where C<%p> is a placeholder for
the PID being dumped. No other use of C<%> is accepted, and
multiple C<%> means all C<%> (including C<%p>) are handled as-is.
=item dump_path:$FILENAME
Dumps the output at exit to a given filename:
total_bytes call_count location
Expands C<%p> to the PID in C<$FILENAME> as described for C<dump_csv>
=item dump_fd:$DESCRIPTOR
As with dump_path, but dumps the output to a given file descriptor.
=back
=head1 HTTP POST API
In addition to the various GET endpoints linked via C<http://0/$PID/>,
there are some POST endpoints which are typically accessed via
C<curl --unix-socket $DIR/$PID.sock>
=over 4
=item POST http://0/$PID/reset
C<curl --unix-socket $DIR/$PID.sock -XPOST http://0/$PID/reset>
Reset all internal counters. This is not done atomically and does
not release any memory.
=item POST http://0/$PID/trim
C<curl --unix-socket $DIR/$PID.sock -XPOST http://0/$PID/trim>
Runs L<malloc_trim(3)> with a 0 pad value to release unused memory
back to the kernel. In our malloc implementation, this is done
lazily to avoid contention and does not happen unless sleeping threads.
=item POST http://0/$PID/ctl
Set various internal knobs. Currently, C<X-Mwrap-BT> is the
only knob supported:
C<curl --unix-socket $DIR/$PID.sock -XPOST -HX-Mwrap-BT:1 http://0/$PID/ctl>
Using the C<X-Mwrap-BT> header allows changing the aforementioned
C<bt:> value to a specified depth level. As with C<bt:>, only make small
adjustments as the memory cost can increase exponentially with each step.
It is typically a good idea to reset (C<http://0/$PID/reset>) after changing
the depth on a running process.
Headers other than C<X-Mwrap-BT> may be accepted in the future to
tweak other settings.
=back
=head1 CONTACT
Feedback welcome via plain-text mail to L<mailto:mwrap-public@80x24.org>
Mail archives are hosted at L<https://80x24.org/mwrap-public/>
=head1 COPYRIGHT
Copyright all contributors L<mailto:mwrap-public@80x24.org>
License: GPL-3.0+ L<https://www.gnu.org/licenses/gpl-3.0.txt>
Source code is at L<https://80x24.org/mwrap.git/>
=head1 SEE ALSO
L<mwrap-rproxy(1)>, L<Devel::Mwrap(3pm)>, L<https://80x24.org/mwrap-perl.git>
=cut
|