From 24f77d7b5050f22907ab17d1f77d7ff4e0b13ff6 Mon Sep 17 00:00:00 2001 From: Sasha Goldshtein Date: Thu, 30 Mar 2017 06:32:23 -0400 Subject: [PATCH] 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. --- README.md | 4 +- {tools => examples/tracing}/stacksnoop.py | 7 -- .../tracing}/stacksnoop_example.txt | 0 man/man8/stacksnoop.8 | 78 ------------------- tests/python/test_tools_smoke.py | 4 - 5 files changed, 2 insertions(+), 91 deletions(-) rename {tools => examples/tracing}/stacksnoop.py (90%) rename {tools => examples/tracing}/stacksnoop_example.txt (100%) delete mode 100644 man/man8/stacksnoop.8 diff --git a/README.md b/README.md index 2bbe50221082..499802c4e1ad 100644 --- 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 a54d524206d8..e4bbb5179f08 100755 --- 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 index 7cfa8a1fab88..000000000000 --- 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 258812d5b08a..885ffca0f853 100755 --- a/tests/python/test_tools_smoke.py +++ b/tests/python/test_tools_smoke.py @@ -257,10 +257,6 @@ def test_sslsniff(self): 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")