From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: X-Spam-Status: No, score=-3.4 required=3.0 tests=ALL_TRUSTED,AWL,BAYES_00, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,NUMERIC_HTTP_ADDR shortcircuit=no autolearn=ham autolearn_force=no version=3.4.2 Received: from localhost (dcvr.yhbt.net [127.0.0.1]) by dcvr.yhbt.net (Postfix) with ESMTP id 404861FAF0 for ; Fri, 16 Dec 2022 14:39:34 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=80x24.org; s=selector1; t=1671201574; bh=bXOD2xjTNFKpglTvueRYqzEEEuEp3fic+cwOL23y6ig=; h=From:To:Subject:Date:In-Reply-To:References:From; b=RrbJoHwNYMKW/hDMv1M1vOnVprJkAhr8NI6jU64cg1TK9AqrmfC79geTtxPvo2ncv mpUi5MWcys1WGtJnfQhiX8MmW861slR+jBzMh4RuHijVn5CGMHSbSDOTrzckGVRHiq B5NOiruD6A2bEFxnUAMj0fOl/mc64A5zJKCblVo8= From: Eric Wong To: mwrap-perl@80x24.org Subject: [PATCH 3/3] various documentation updates Date: Fri, 16 Dec 2022 14:39:33 +0000 Message-Id: <20221216143933.22430-4-e@80x24.org> In-Reply-To: <20221216143933.22430-1-e@80x24.org> References: <20221216143933.22430-1-e@80x24.org> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit List-Id: mwrap_httpd will have online help :> --- httpd.h | 29 ++++++++++++---- script/mwrap-perl | 78 +++++++++++++++++++++++++++++++++++++++++ script/mwrap-rproxy | 84 ++++++++++++++++++++++++++++++++++++++++++--- 3 files changed, 180 insertions(+), 11 deletions(-) diff --git a/httpd.h b/httpd.h index fc7b873..afce2a1 100644 --- a/httpd.h +++ b/httpd.h @@ -483,7 +483,7 @@ static off_t write_loc_name(FILE *fp, const struct src_loc *l) if (!s) return -1; if (l->f) fputc('\n', fp); - /* omit local " [$ADDRESS]" if doing deep backtraces */ + /* omit local " [RETURN_ADDRESS]" if doing deep backtraces */ for (uint32_t i = 0; i < l->bt_len; ++i) { char *c = memrchr(s[i], '[', strlen(s[i])); if (c && c > (s[i] + 2) && c[-1] == ' ') @@ -723,12 +723,29 @@ static enum mw_qev pid_root(struct mw_h1 *h1, struct mw_h1req *h1r) if (!fp) return h1_close(h1); #define default_min "2000" - FPUTS("mwrap demo" - "

mwrap demo", fp); + int pid = (int)getpid(); + fprintf(fp, "mwrap PID:%d" + "

mwrap PID:%d", pid, pid);
 	show_stats(fp);
-	FPUTS("
allocations >"
-		default_min " bytes"
-		"
" URL "", fp);
+	FPUTS("\n\nallocations >"
+		default_min " bytes""
" +"To get source file and line info for native backtraces, consult your\n" +"distro for -dbg, -dbgsym, or -debug packages.\n" +"And/or rebuild your code with debug flags (e.g. `-ggdb3' if using gcc)\n" +"and don't strip the resulting binaries.\n" +"You should see locations from the backtrace_symbols(3) function\n" +"in the form of FILENAME(+OFFSET) or FILENAME(SYMBOL+OFFSET)\n" +"(e.g. /usr/lib/foo.so(+0xdead) or /usr/lib/foo.so(func+(0xbeef))\n" +"\n" +"Any version of addr2line should decode FILENAME(+OFFSET) locations:\n" +"\n" +" addr2line -e FILENAME OFFSET\n" +"\n" +"SYMBOL+OFFSET requires addr2line from GNU binutils 2.39+ (Aug 2022):\n" +"\n" +" addr2line -e FILENAME SYMBOL+OFFSET\n", fp); + + FPUTS("\n" URL "", fp); return h1_200(h1, &html, TYPE_HTML); #undef default_min } diff --git a/script/mwrap-perl b/script/mwrap-perl index 78e71e3..53eaa10 100644 --- a/script/mwrap-perl +++ b/script/mwrap-perl @@ -6,6 +6,10 @@ use Devel::Mwrap; my ($so) = grep(m!/Mwrap\.so\z!, @DynaLoader::dl_shared_objects); defined($so) or die 'Mwrap.so not loaded'; my $cur = $ENV{LD_PRELOAD}; +if (!@ARGV || ($ARGV[0] // '') =~ /\A(?:-h|--help)\z/) { + require Pod::Usage; + Pod::Usage::pod2usage(@ARGV ? 0 : 1); +} if (defined $cur) { my @cur = split(/[: \t]+/, $cur); if (!grep(/\A\Q$so\E\z/, @cur)) { @@ -17,3 +21,77 @@ if (defined $cur) { $ENV{LD_PRELOAD} = $so; } exec @ARGV; +__END__ +=head1 NAME + +mwrap-perl - run any command under mwrap + +=head1 SYNOPSIS + + # to trace a long-running program and access it via $DIRECTORY/$PID.sock: + MWRAP=socket_dir:$DIRECTORY mwrap-perl COMMAND + + # to trace a short-lived command and dump its output to a log: + MWRAP=dump_path:$FILENAME mwrap-perl COMMAND + +=head1 DESCRIPTION + +mwrap-perl is a command-line to automatically add Mwrap.so as an +LD_PRELOAD for any command. It will resolve malloc-family calls +to a Perl file and line number, and it can also provide a backtrace +of native (C/C++) functions for non-Perl programs. + +=head1 ENVIRONMENT + +C is the only environment variable read. It contains multiple +options delimited by C<,> with names and values delimited by C<:> + +=item socket_dir:$DIRECTORY + +This launches an embedded HTTP server in each process and binds it +to C<$DIRECTORY/$PID.sock>. C +or L may be used to access various endpoints in +the HTTP server. + +=item: bt:$DEPTH + +The backtrace depth for L 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 + +Default: 0 + +=item dump_path:$FILENAME + +Dumps the output + + total_bytes call_count location + +In the future, dumping to a self-describing CSV will be supported + +=back + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +Mail archives are hosted at L + +=head1 COPYRIGHT + +Copyright all contributors L + +License: GPL-2.0+ L + +Source code is at L + +=head1 SEE ALSO + +L, L + +=cut diff --git a/script/mwrap-rproxy b/script/mwrap-rproxy index 97cca8e..da5379a 100644 --- a/script/mwrap-rproxy +++ b/script/mwrap-rproxy @@ -4,14 +4,17 @@ # thin wrapper for Devel::Mwrap::Rproxy use v5.12; # strict eval { require Plack::Runner } or die "Plack not installed: $@\n"; -require Devel::Mwrap::Rproxy; use Getopt::Long qw(:config no_ignore_case no_auto_abbrev pass_through); my $usage = "$0 --socket-dir=/path/to/socket-dir [PLACKUP_OPTIONS]\n"; -my $socket_dir; -my $gz = 1; -GetOptions('socket-dir=s' => \$socket_dir, 'deflate!' => \$gz) or die $usage; +my %opt = (deflate => 1); +GetOptions(\%opt, 'socket-dir=s', 'deflate!', 'help|h') or do { + require Pod::Usage; Pod::Usage::pod2usage(1); +}; +if ($opt{help}) { require Pod::Usage; Pod::Usage::pod2usage(0) } +my $socket_dir = delete $opt{'socket-dir'}; $socket_dir //= ($ENV{MWRAP} // '') =~ m!\bsocket_dir:([^,]+)! ? $1 : undef; $socket_dir // die $usage; +require Devel::Mwrap::Rproxy; my $rproxy = Devel::Mwrap::Rproxy->new($socket_dir); my $app = sub { $rproxy->call(@_) }; my $runner = Plack::Runner->new; @@ -28,7 +31,78 @@ Inherited socket (fd=3) is non-blocking, making it blocking. $runner->set_options(listen_sock => $s); } } -if ($gz && eval { require Plack::Middleware::Deflater } and !$@) { +if ($opt{deflate} && eval { require Plack::Middleware::Deflater } and !$@) { $app = Plack::Middleware::Deflater->wrap($app); } $runner->run($app); +__END__ +=head1 NAME + +mwrap-rproxy - reverse proxy for embedded per-process mwrap httpd + +=head1 SYNOPSIS + + # start the long-running COMMAND you wish to trace: + MWRAP=socket_dir:$DIRECTORY mwrap-perl COMMAND + + # in a different terminal, point mwrap-proxy to the mwrap-perl socket_dir + mwrap-rproxy --socket-dir=$DIRECTORY -l 127.0.0.1:8080 + + # open http://127.0.0.1:8080/ in your favorite web browser: + w3m http://127.0.0.1:8080/ + +=head1 DESCRIPTION + +B is a PSGI reverse proxy to provide access +via TCP to the native, Unix-socket-only httpd embedded inside +mwrap core. It provides a listing of process IDs of each process +traced via mwrap. + +B does not have a hard dependency on mwrap-perl itself, +it exists to provide a convenient interface to programs being +traced by mwrap-perl. + +=head1 OPTIONS + +=over 4 + +=item --socket-dir=DIRECTORY + +If unset, it will attempt to parse C from the C +environment (see L). + +=item --no-deflate + +L is loaded by default if available. +Using C<--no-deflate> will save CPU cycles at the expe + +=back + +Additionally, all options in L are supported. Notably, +C<-l>/C<--listen> and C<--path=/prefix> may be useful. + +=head1 ENVIRONMENT + +mwrap-rproxy supports systemd (and compatible) socket activation via +C and C variables. See L +and L. + +=head1 CONTACT + +Feedback welcome via plain-text mail to L + +Mail archives are hosted at L + +=head1 COPYRIGHT + +Copyright all contributors L + +License: GPL-2.0+ L + +Source code is at L + +=head1 SEE ALSO + +L + +=cut