stacksnoop: Retire and move to examples/tracing

Move stacksnoop to examples/tracing. Originally we considered
leaving a script that redirects to the `trace` tool, but decided
not to. Any users of stacksnoop can migrate directly to `trace`.

Resolves #737.

diff --git a/README.md b/README.md
index 2bbe502..499802c 100644 (file)
--- a/README.md
+++ b/README.md
@@ -66,6 +66,8 @@ pair of .c and .py files, and some are directories of files.
 - examples/[hello_world.py](examples/hello_world.py): Prints "Hello, World!" for new processes.
 - examples/tracing/[mysqld_query.py](examples/tracing/mysqld_query.py): Trace MySQL server queries using USDT probes. [Examples](examples/tracing/mysqld_query_example.txt).
 - examples/tracing/[nodejs_http_server.py](examples/tracing/nodejs_http_server.py): Trace Node.js HTTP server requests using USDT probes. [Examples](examples/tracing/nodejs_http_server_example.txt).
+- examples/tracing/[stacksnoop](examples/tracing/stacksnoop.py): Trace a kernel function and print all kernel stack traces. [Examples](examples/stacksnoop_example.txt).
+- tools/[statsnoop](tools/statsnoop.py): Trace stat() syscalls. [Examples](tools/statsnoop_example.txt).
 - examples/tracing/[task_switch.py](examples/tracing/task_switch.py): Count task switches with from and to PIDs.
 - examples/tracing/[tcpv4connect.py](examples/tracing/tcpv4connect.py): Trace TCP IPv4 active connections. [Examples](examples/tracing/tcpv4connect_example.txt).
 - examples/tracing/[trace_fields.py](examples/tracing/trace_fields.py): Simple example of printing fields from traced events.
@@ -123,8 +125,6 @@ pair of .c and .py files, and some are directories of files.
 - tools/[solisten](tools/solisten.py): Trace TCP socket listen. [Examples](tools/solisten_example.txt).
 - tools/[sslsniff](tools/sslsniff.py): Sniff OpenSSL written and readed data. [Examples](tools/sslsniff_example.txt).
 - tools/[stackcount](tools/stackcount.py): Count kernel function calls and their stack traces. [Examples](tools/stackcount_example.txt).
-- tools/[stacksnoop](tools/stacksnoop.py): Trace a kernel function and print all kernel stack traces. [Examples](tools/stacksnoop_example.txt).
-- tools/[statsnoop](tools/statsnoop.py): Trace stat() syscalls. [Examples](tools/statsnoop_example.txt).
 - tools/[syncsnoop](tools/syncsnoop.py): Trace sync() syscall. [Examples](tools/syncsnoop_example.txt).
 - tools/[syscount](tools/syscount.py): Summarize syscall counts and latencies. [Examples](tools/syscount_example.txt).
 - tools/[tcpaccept](tools/tcpaccept.py): Trace TCP passive connections (accept()). [Examples](tools/tcpaccept_example.txt).

diff --git a/tools/stacksnoop.py b/examples/tracing/stacksnoop.py
similarity index 90%
rename from tools/stacksnoop.py
rename to examples/tracing/stacksnoop.py
index a54d524..e4bbb51 100755 (executable)
--- a/tools/stacksnoop.py
+++ b/examples/tracing/stacksnoop.py
@@ -5,13 +5,6 @@
 #
 # USAGE: stacksnoop [-h] [-p PID] [-s] [-v] function
 #
-# The current implementation uses an unrolled loop for x86_64, and was written
-# as a proof of concept. This implementation should be replaced in the future
-# with an appropriate bpf_ call, when available.
-#
-# The stack depth is limited to 10 (+1 for the current instruction pointer).
-# This could be tunable in a future version.
-#
 # Copyright 2016 Netflix, Inc.
 # Licensed under the Apache License, Version 2.0 (the "License")
 #

diff --git a/tools/stacksnoop_example.txt b/examples/tracing/stacksnoop_example.txt
similarity index 100%
rename from tools/stacksnoop_example.txt
rename to examples/tracing/stacksnoop_example.txt

diff --git a/man/man8/stacksnoop.8 b/man/man8/stacksnoop.8
deleted file mode 100644 (file)
index 7cfa8a1..0000000
--- a/man/man8/stacksnoop.8
+++ /dev/null
@@ -1,78 +0,0 @@
-.TH stacksnoop 8  "2016-01-14" "USER COMMANDS"
-.SH NAME
-stacksnoop \- Print kernel stack traces for kernel functions. Uses Linux eBPF/bcc.
-.SH SYNOPSIS
-.B stacksnoop [\-h] [\-p PID] [\-s] [\-v] function
-.SH DESCRIPTION
-stacksnoop traces a given kernel function and for each call, prints the
-kernel stack back trace for that call. This shows the ancestry of function
-calls, and is a quick way to investigate low frequency kernel functions and
-their cause. For high frequency kernel functions, see stackcount.
-
-This tool only works on Linux 4.6+. Stack traces are obtained using the new BPF_STACK_TRACE` APIs.
-For kernels older than 4.6, see the version under tools/old.
-.SH REQUIREMENTS
-CONFIG_BPF and bcc.
-.SH OPTIONS
-.TP
-\-h
-Print usage message.
-.TP
-\-s
-Show address offsets.
-.TP
-\-v
-Print more fields.
-.TP
-\-p PID
-Trace this process ID only (filtered in-kernel).
-.TP
-function
-Kernel function name.
-.SH EXAMPLES
-.TP
-Print kernel stack traces for each call to ext4_sync_fs:
-#
-.B stacksnoop ext4_sync_fs
-.TP
-Also show the symbol offsets:
-#
-.B stacksnoop -s ext4_sync_fs
-.TP
-Show extra columns:
-#
-.B stacksnoop -v ext4_sync_fs
-.TP
-Only trace when PID 185 is on-CPU:
-#
-.B stacksnoop -p 185 ext4_sync_fs
-.SH FIELDS
-.TP
-TIME(s)
-Time of the call, in seconds.
-.TP
-STACK
-Kernel stack trace. The first column shows "ip" for instruction pointer, and
-"r#" for each return pointer in the stack. The second column is the stack trace
-as hexadecimal. The third column is the translated kernel symbol names.
-.SH OVERHEAD
-This can have significant overhead if frequently called functions (> 1000/s) are
-traced, and is only intended for low frequency function calls. This is because
-details including the stack trace for every call is passed to user space and
-processed. See stackcount for higher frequency calls, which performs in-kernel
-summaries.
-.SH SOURCE
-This is from bcc.
-.IP
-https://github.com/iovisor/bcc
-.PP
-Also look in the bcc distribution for a companion _examples.txt file containing
-example usage, output, and commentary for this tool.
-.SH OS
-Linux
-.SH STABILITY
-Unstable - in development.
-.SH AUTHOR
-Brendan Gregg
-.SH SEE ALSO
-stackcount(8)

diff --git a/tests/python/test_tools_smoke.py b/tests/python/test_tools_smoke.py
index 258812d..885ffca 100755 (executable)
--- a/tests/python/test_tools_smoke.py
+++ b/tests/python/test_tools_smoke.py
@@ -257,10 +257,6 @@ class SmokeTests(TestCase):
     def test_stackcount(self):
         self.run_with_int("stackcount.py __kmalloc -i 1")
 
-    @skipUnless(kernel_version_ge(4,6), "requires kernel >= 4.6")
-    def test_stacksnoop(self):
-        self.run_with_int("stacksnoop.py SyS_open")
-
     @skipUnless(kernel_version_ge(4,4), "requires kernel >= 4.4")
     def test_statsnoop(self):
         self.run_with_int("statsnoop.py")