diff options
Diffstat (limited to 'Documentation/mwrap.pod')
-rw-r--r-- | Documentation/mwrap.pod | 123 |
1 files changed, 123 insertions, 0 deletions
diff --git a/Documentation/mwrap.pod b/Documentation/mwrap.pod new file mode 100644 index 0000000..6832430 --- /dev/null +++ b/Documentation/mwrap.pod @@ -0,0 +1,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 |