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
| | =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 log:
MWRAP=dump_path:$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_path:$FILENAME
Dumps the output at exit to a given filename:
total_bytes call_count location
In the future, dumping to a self-describing CSV will be supported.
=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
|