Merge pull request iovisor#949 from ShelbyFrances/trace_enhancements

tools/trace accepts abspath arguments to -I (and some doc tweaks)

tools/argdist.py

@@ -619,7 +619,8 @@ def __init__(self):
  "(see examples below)")
  parser.add_argument("-I", "--include", action="append",
  metavar="header",
- help="additional header files to include in the BPF program")
+ help="additional header files to include in the BPF program "
+ "as either full path, or relative to '/usr/include'")
  self.args = parser.parse_args()
  self.usdt_ctx = None
 
@@ -640,7 +641,12 @@ def _generate_program(self):
 #include <uapi/linux/ptrace.h>
  """ % self.args.string_size
  for include in (self.args.include or []):
- bpf_source += "#include <%s>\n" % include
+ if include.startswith((".", "/")):
+ include = os.path.abspath(include)
+ bpf_source += "#include \"%s\"\n" % include
+ else:
+ bpf_source += "#include <%s>\n" % include
+
  bpf_source += BPF.generate_auto_includes(
  map(lambda p: p.raw_spec, self.probes))
  for probe in self.probes:

tools/argdist_example.txt

@@ -363,6 +363,7 @@ optional arguments:
  below)
  -I header, --include header
  additional header files to include in the BPF program
+ as either full path, or relative to '/usr/include'
 
 Probe specifier syntax:
  {p,r,t,u}:{[library],category}:function(signature)[:type[,type...]:expr[,expr...][:filter]][#label]

tools/trace.py

@@ -624,7 +624,8 @@ def __init__(self):
  help="probe specifier (see examples)")
  parser.add_argument("-I", "--include", action="append",
  metavar="header",
- help="additional header files to include in the BPF program")
+ help="additional header files to include in the BPF program "
+ "as either full path, or relative to '/usr/include'")
  self.args = parser.parse_args()
  if self.args.tgid and self.args.pid:
  parser.error("only one of -p and -t may be specified")
@@ -644,7 +645,11 @@ def _generate_program(self):
 
 """
  for include in (self.args.include or []):
- self.program += "#include <%s>\n" % include
+ if include.startswith((".", "/")):
+ include = os.path.abspath(include)
+ self.program += "#include \"%s\"\n" % include
+ else:
+ self.program += "#include <%s>\n" % include
  self.program += BPF.generate_auto_includes(
  map(lambda p: p.raw_probe, self.probes))
  for probe in self.probes:

tools/trace_example.txt

@@ -2,8 +2,8 @@ Demonstrations of trace.
 
 
 trace probes functions you specify and displays trace messages if a particular
-condition is met. You can control the message format to display function 
-arguments and return values. 
+condition is met. You can control the message format to display function
+arguments and return values.
 
 For example, suppose you want to trace all commands being exec'd across the
 system:
@@ -135,6 +135,16 @@ TIME PID COMM FUNC -
 In the previous invocation, arg1 and arg2 are the class name and method name
 for the Ruby method being invoked.
 
+You can also trace exported functions from shared libraries, or an imported
+function on the actual executable:
+
+# sudo ./trace.py 'r:/usr/lib64/libtinfo.so:curses_version "Version=%s", retval'
+# tput -V
+
+PID TID COMM FUNC -
+21720 21720 tput curses_version Version=ncurses 6.0.20160709
+^C
+
 
 Occasionally, it can be useful to filter specific strings. For example, you
 might be interested in open() calls that open a specific file:
@@ -164,8 +174,12 @@ PID TID COMM FUNC -
 777 785 automount SyS_nanosleep sleep for 500000000 ns
 ^C
 
+Remember to use the -I argument include the appropriate header file. We didn't
+need to do that here because `struct timespec` is used internally by the tool,
+so it always includes this header file.
+
 
-As a final example, let's trace open syscalls for a specific process. By 
+As a final example, let's trace open syscalls for a specific process. By
 default, tracing is system-wide, but the -p switch overrides this:
 
 # trace -p 2740 'do_sys_open "%s", arg2' -T
@@ -215,6 +229,7 @@ optional arguments:
  -U, --user-stack output user stack trace
  -I header, --include header
  additional header files to include in the BPF program
+ as either full path, or relative to '/usr/include'
 
 EXAMPLES: