Update INSTALL.md

Quickstart leaves out installing the examples.

GCC 6 behaves slightly differently when using -isystem, and our use of
that parameter is causing a build failure. Avoid using -isystem on
gcc6+ for now, until that compiler becomes a bit more mainstream and
we can debug further.

Failure had been introuced in d19e0cb0.
Signed-off-by: Marco Leogrande <marcol@plumgrid.com>

* bcc: Allow custom bucket formatting for histogram keys

When histogram keys are complex structures (`ct.Structure`
created from C struct), they can't be used as dictionary keys
for counting purposes without a custom hashing function.
Allow the user to provide such hashing function when calling
`print_log_hist` to print the histogram.

* bcc: Allow regular expression in attach_uretprobe

Similarly to `attach_uprobe`, `attach_uretprobe` now supports
taking a regular expression.

* funclatency: Support user functions

funclatency now supports user functions (including regular
expressions) in addition to kernel functions. When multiple
processes are traced, the output is always per-function, per-
process. When a single process is traced, the output can be
combined for all traced functions (as with kernel functions).

Usage examples:

```
funclatency pthread:*mutex* -p 6449 -F
funclatency c:read
funclatency dd:* -p $(pidof dd) -uF
```

FC23 and FC24 need Clang 3.9.0 because of ABI changes in the C++
runtime library. Split the installation instructions to FC22 and
FC23/24.

* cc: Add USDT location and argument reporting

libbcc now exposes USDT location and argument information using
two new APIs: `bcc_usdt_get_location` and `bcc_usdt_get_argument`.

* python: Retrieve USDT locations and arguments

Add wrappers in the libbcc.py file to access the new APIs for
retrieving USDT location and argument information. Also add
high-level classes in usdt.py to access this information and
format arguments and locations in a shape suitable for display.

* tplist: Print USDT locations and arguments

Add super-verbose mode (-vv) to tplist where it prints USDT locations
and arguments including full detail on registers, offsets, and global
identifier offsets.

this is initial commit of LuaJIT bytecode to BPF
compiler project that enables writing both kernel
and user-part of the code as Lua

* stackcount: Support user-space functions

Add support for user-space functions in `stackcount` by taking an additional
`-l` command-line parameter specifying the name of the user-space library.
When a user-space library is specified, `stackcount` attaches to a specific
process and traces a user-space function with user-space stacks only.
Regex support for uprobes (similar to what is available for kprobes) is
not currently provided.

Also add a couple of functions to the `BPF` object for consistency.

* bcc: Support regex in attach_uprobe

attach_kprobe allows a regular expression for the function name,
while attach_uprobe does not. Add support in libccc for enumerating
all the function symbols in a binary, and use that in the BPF module
to attach uprobes according to a regular expression. For example:

```python
bpf = BPF(text="...")
bpf.attach_uprobe(name="c", sym_re=".*write$", fn_name="probe")
```

* python: Support regex in attach_tracepoint

Modify attach_tracepoint to take a regex argument, in which case
it enumerates all tracepoints matching that regex and attaches to
all of them. The logic for enumerating tracepoints should eventually
belong in libccc and be shared across all the tools (tplist, trace
and so on).

* cc: Fix termination condition bug in symbol enumeration

bcc_elf would not terminate the enumeration correctly when the
user-provided callback returned -1 but there were still more
sections remaining in the ELF to be enumerated.

* stackcount: Support uprobes and tracepoints

Refactored stackcount and added support for uprobes and tracepoints,
which also required changes to the BPF module. USDT support still
pending.

* bcc: Refactor symbol listing to use foreach-style

Refactor symbol listing from paging style to foreach-style with a
callback function per-symbol. Even though we're now performing a
callback from C to Python for each symbol, this is preferable to the
paging approach because we need all the symbols in the current use
case.

Also refactored `stackcount` slightly; only missing support for USDT
probes now.

* stackcount: Support per-process displays

For user-space functions, or when requested for kernel-space
functions or tracepoints, group the output by process. Toggled
with the -P switch, off by default (except for user-space).

* Fix rebase issues, print pid only when there is one

* stackcount: Add USDT support

Now, stackcount supports USDT tracepoints in addition to
kernel functions, user functions, and kernel tracepoints.
The format is the same as with the other general-purpose
tools (argdist, trace):

```
stackcount -p $(pidof node) u:node:gc*
stackcount -p 185 u:pthread:pthread_create
```

* stackcount: Update examples and man page

Add examples and man page documentation for kernel
tracepoints, USDT tracepoints, and other features.

* stackcount: Change printing format slightly

When -p is specified, don't print the comm and pid. Also,
when -P is specified for kernel probes (kprobes and
tracepoints), use -1 for symbol resolution so that we
don't try to resolve kernel functions as user symbols.
Finally, print the comm and pid at the end of the stack
output and not at the beginning.

Fixes #722, in which a USDT probe that has more than
one location and the type of the argument is a string
caused trace to potentially access an uninitialized
stack variable, thereby not passing BPF program
verification at load time.

* Remove tracepoint.py

The `Tracepoint` class which implements the necessary
support for the tracepoint kprobe-based hack is no
longer needed and can be removed.

* argdist: Native tracepoint support

This commit migrates argdist to use the native bcc/BPF
tracepoint support instead of the hackish kprobe-
based approach. The resulting programs are cleaner
and likely more efficient.

As a result of this change, there is a slight API
change in how argdist is used with tracepoints. To
access fields from the tracepoint structure, the user
is expected to use `args->field` directly. This
leverages most of the built-in bcc support for
generating the tracepoint probe function.

* trace: Native tracepoint support

This commit migrates trace to use the native bcc/BPF
tracepoint support instead of the hackish kprobe-
based approach. The resulting programs are cleaner
and likely more efficient.

As with argdist, users are now expected to use the
`args` structure pointer to access the tracepoint's
arguments.

For example:

```
trace 't:irq:irq_handler_entry (args->irq != 27) "irq %d", args->irq'
```

By default, argdist now clears the histograms or freq
count maps after each display interval. The new `-c`
option enables cumulative mode, where maps are not
cleared at each interval. This fixes #718.

When verbose mode is enabled, ask all USDT helper
objects to print out the argument helper functions,
which help retrieve the argument values for each
individual probe location. This can be useful for
debugging probes; the helper functions are part of
the loaded BPF program, so they need to be printed
in verbose mode.

Fixes the error message from `BPF._find_exe` which would
occur if argdist or trace had a naked executable name
not qualified with a path, such as:

```
trace 'r:bash:readline "%s", retval'
```

This is now supported again.

Following brendangregg's suggestion
(https://github.com/iovisor/bcc/pull/577#issuecomment-251052371), this
commit replaces the former list with a new one: more features are
listed, along with commit ids and references (but no comments detailing
the features, though).

wasn't working for kernel ver less than 4.5.

If LLVM_INCLUDE_DIRS includes multiple directories, separated by
semicolon, the string would be incorrectly propagated all the way down
to the shell, that would interpret such semicolon as a command
separator. E.g. we would have:

 c++ ... -isystem /w/llvm/include;/w/llvm/bld/include ...

Instead, we need to parse the string as a CMake list (that are defined
as strings composed by semicolon-separated tokens) and build a string
in the form:

 c++ ... -isystem /w/llvm/include -isystem /w/llvm/bld/include ...

This bug was introduced in d19e0cb0.
This commit fixes #707.
Signed-off-by: Marco Leogrande <marcol@plumgrid.com>

* Flag ${LLVM_INCLUDE_DIRS} as a system include directory

g++ supports a -isystem switch, that can be used to mark a given
directory as a system include directory. Warnings generated by system
include directories are ignored by default.

This commit hides a long list of warnings, like the following one,
generated by llvm header files included from ${LLVM_INCLUDE_DIRS}:

 /usr/lib/llvm-3.7/include/clang/AST/APValue.h:373:44: warning:
   dereferencing type-punned pointer will break strict-aliasing rules [-Wstrict-aliasing]
Signed-off-by: Marco Leogrande <marcol@plumgrid.com>

* Fix 'defined but not used' warning

Remove unused function from the USDT probes test.

The warning was:

 tests/cc/test_usdt_probes.cc:59:15: warning:
   ‘size_t countsubs(const string&, const string&)’ defined but not used [-Wunused-function]
Signed-off-by: Marco Leogrande <marcol@plumgrid.com>

* Allow argdist to enable USDT probes without a pid

The current code would only pass the pid to the USDT
class, thereby not allowing USDT probes to be enabled
from the binary path only. If the probe doesn't have
a semaphore, it can actually be enabled for all
processes in a uniform fashion -- which is now
supported.

* Reintroduce USDT support into tplist

To print USDT probe information, tplist needs an API
to return the probe data, including the number of
arguments and locations for each probe. This commit
introduces this API, called bcc_usdt_foreach, and
invokes it from the revised tplist implementation.

Although the result is not 100% identical to the
original tplist, which could also print the probe
argument information, this is not strictly required
for users of the argdist and trace tools, which is
why it was omitted for now.

* Fix trace.py tracepoint support

Somehow, the import of the Perf class was omitted
from tracepoint.py, which would cause failures when
trace enables kernel tracepoints.

* trace: Native bcc USDT support

trace now works again by using the new bcc USDT support
instead of the home-grown Python USDT parser. This
required an additional change in the BPF Python API
to allow multiple USDT context objects to be passed to
the constructor in order to support multiple USDT
probes in a single invocation of trace. Otherwise, the
USDT-related code in trace was greatly simplified, and
uses the `bpf_usdt_readarg` macros to obtain probe
argument values.

One minor inconvenience that was introduced in the bcc
USDT API is that USDT probes with multiple locations
that reside in a shared object *must* have a pid
specified to enable, even if they don't have an
associated semaphore. The reason is that the bcc USDT
code figures out which location invoked the probe by
inspecting `ctx->ip`, which, for shared objects, can
only be determined when the specific process context is
available to figure out where the shared object was
loaded. This limitation did not previously exist,
because instead of looking at `ctx->ip`, the Python
USDT reader generated separate code for each probe
location with an incrementing identifier. It's not a
very big deal because it only means that some probes
can't be enabled without specifying a process id, which
is almost always desired anyway for USDT probes.

argdist has not yet been retrofitted with support for
multiple USDT probes, and needs to be updated in a
separate commit.

* argdist: Support multiple USDT probes

argdist now supports multiple USDT probes, as it did
before the transition to the native bcc USDT support.
This requires aggregating the USDT objects from each
probe and passing them together to the BPF constructor
when the probes are initialized and attached.

Also add a more descriptive exception message to the
USDT class when it fails to enable a probe.

This is similar in spirit to what was done in PR #677 to fix the
problem reported in #609.

filelife.py is now converted to use the right struct field.
Signed-off-by: Marco Leogrande <marcol@plumgrid.com>

There are situations, specially when using non-folded mode, where we are
interested only in very high latencies that happen due to blocking.

While we can certainly filter out the very small ones out of the output, it is a
lot more convenient to do this from the tool itself, as it would be difficult
from an external filter to do this in one pass.

But if we are to discard unused measurements, we can do even better: we can
change the bpf code itself not to grab those traces, and gain a bit of
efficiency in scenarios in which we are only concerned about peak latencies.

This scheme can be easily extended to also allow a maximum cap in the latencies
we are interested in.

After this patch is applied, the options -m and -M can be used to set those
limits respectively.

Fixes: #588

[tcpconnect] filter traced connection based on destination ports

Test:
While running:
while [ 1 ]; do nc -w 1 100.127.0.1 80; nc -w 1 100.127.0.1 81; done

root@vagrant:/mnt/bcc# ./tools/tcpconnect.py
PID    COMM         IP SADDR            DADDR            DPORT
19978  nc           4  10.0.2.15        100.127.0.1      80
19979  nc           4  10.0.2.15        100.127.0.1      81
19980  nc           4  10.0.2.15        100.127.0.1      80
19981  nc           4  10.0.2.15        100.127.0.1      81
root@vagrant:/mnt/bcc# ./tools/tcpconnect.py  -P 80
PID    COMM         IP SADDR            DADDR            DPORT
19987  nc           4  10.0.2.15        100.127.0.1      80
19989  nc           4  10.0.2.15        100.127.0.1      80
19991  nc           4  10.0.2.15        100.127.0.1      80
19993  nc           4  10.0.2.15        100.127.0.1      80
19995  nc           4  10.0.2.15        100.127.0.1      80
root@vagrant:/mnt/bcc# ./tools/tcpconnect.py  -P 80,81
PID    COMM         IP SADDR            DADDR            DPORT
8725   nc           4  10.0.2.15        100.127.0.1      80
8726   nc           4  10.0.2.15        100.127.0.1      81
8727   nc           4  10.0.2.15        100.127.0.1      80
8728   nc           4  10.0.2.15        100.127.0.1      81
8729   nc           4  10.0.2.15        100.127.0.1      80

Fixes #681

* add new tool: capable

* refactor a little, remove extra bpf_get_current_pid_tgid()

Use tempfile module to create a temp file

Fix some review input

Fix style check

Style

Style check

Remove builtin module from python test to run fedora ctest

Let the program calling bpf_prog_load to handle the log buffer

Check max instruction before the syscall. Fix other review comment

minor cleanup + process partial name matching

Signed-off-by: KarimAllah Ahmed <karim.allah.ahmed@gmail.com>

Signed-off-by: KarimAllah Ahmed <karim.allah.ahmed@gmail.com>

... since they are unused.
Signed-off-by: KarimAllah Ahmed <karim.allah.ahmed@gmail.com>

Prepare debian changelog for v0.2.0 tag

Signed-off-by: Brenden Blanco <bblanco@plumgrid.com>

examples: fix indentation in tracing/tcpv4connect