API Cleanup / New Helpers / Detailed Examples and usage guides. (#9)

- Moved the bindata generated `Assets` api for public (non-lib-internal) use.
- event.Trace->Argv is now a `call.Function` instead of a naked interface{}
- Added `call.Function.Arguments()` accessor method.
- Moved cmd/loadBPFargs helper function into cmd/loader.go
- Removed `event.TraceEvent.WithTopology` (now covered by `WithContainerLookup`
- `event.TraceEvent.WithContainerLookup` is now used as a callback for resolving
  pid-namespace->container resolution
- Added `kernel.Probe.DetectAndSetOffsets()` helpers for auto-discovering proper struct
  member offsets using the running kernel.
- kernel.Probe.InitProbe() now has optional configuration options
  * WithOffsetDetection() - struct task_struct member offset detection
  * WithDefaultFilter()   - sets up default kernel filters for the BPF
- Moved `hub.Hub` under the Topology API (pkg/topology)
- Moved `hub.Job` under the Topology API (pkg/topology)
- the Hub API no longer uses its own `hub.Observer`, this is derived from the
  `Observer` it was created with.
- A metric buttload of documentation additions along with some pretty verbose
  examples.

Makefile

@@ -38,7 +38,7 @@ swoll: bindata ## Build the swoll binary
 
 ## Build the BPF probe and generate embedded asset file
 bindata: $(GOBINDATA) bpf
-	$(GOBINDATA) -nometadata -nocompress -pkg assets -tags !nobindata -o internal/pkg/assets/bindata.go ./internal/bpf/probe*.o
+	$(GOBINDATA) -nometadata -nocompress -pkg assets -tags !nobindata -o pkg/kernel/assets/compiled.go ./internal/bpf/probe*.o
 
 all: bpf bindata generate cmd/ internal/bpf swoll ## Build the BPF probe and swoll binary
 

README.md

@@ -237,7 +237,7 @@ func main() {
         decoded.Ingest(msg)
 
         // fetch the arguments associated with the call
-        args := decoded.Argv.(call.Function).Arguments()
+        args := decoded.Argv.Arguments()
 
         fmt.Printf("comm:%-15s pid:%-8d %s(%s)\n", decoded.Comm, decoded.Pid, decoded.Syscall, args)
     }
@@ -303,7 +303,7 @@ func main() {
 
     // attach to the running trace and print out stuff
     kHub.AttachTrace(trace, func(id string, ev *event.TraceEvent) {
-        args := ev.Argv.(call.Function).Arguments()
+        args := ev.Argv.Arguments()
 
         fmt.Printf("container=%s pod=%s namespace=%s comm:%-15s pid:%-8d %s(%s)\n",
             ev.Container.Name, ev.Container.Pod, ev.Container.Namespace,

cmd/client.go

@@ -14,7 +14,6 @@ import (
 
 	"github.com/criticalstack/swoll/api/v1alpha1"
 	"github.com/criticalstack/swoll/pkg/client"
-	"github.com/criticalstack/swoll/pkg/event/call"
 	color "github.com/fatih/color"
 	uuid "github.com/google/uuid"
 	log "github.com/sirupsen/logrus"
@@ -293,7 +292,7 @@ var cmdClientCreate = &cobra.Command{
 				case ev := <-outChan:
 					switch out {
 					case "cli":
-						fn := ev.Data.Argv.(call.Function)
+						fn := ev.Data.Argv
 						args := fn.Arguments()
 
 						green := color.New(color.FgGreen).SprintFunc()

cmd/controller.go

@@ -21,7 +21,7 @@ import (
 )
 
 const (
-	defaultImageName = "cinderegg:5000/swoll:latest"
+	defaultImageName = "criticalstack/swoll:latest"
 )
 
 var (

cmd/loader.go

@@ -0,0 +1,47 @@
+package cmd
+
+import (
+	"io/ioutil"
+	"os"
+
+	"github.com/criticalstack/swoll/pkg/kernel/assets"
+	"github.com/spf13/cobra"
+)
+
+// loadBPFargs will attempt to find the BPF object file via the commandline,
+// If the argument is empty (default), we check the local environment, and if
+// that fails, we attempt to load the go-bindata generated asset.
+func loadBPFargs(cmd *cobra.Command, args []string) ([]byte, error) {
+	var (
+		bpf []byte
+		err error
+	)
+
+	// first check to see if the bpf object was defined at the commandline
+	bpfFile, err = cmd.Flags().GetString("bpf")
+	if err != nil {
+		return nil, err
+	}
+
+	if bpfFile == "" {
+		// not found on the command-line, now try environment
+		bpfFile = os.Getenv("SWOLL_BPFOBJECT")
+	}
+
+	if bpfFile != "" {
+		// attempt to read the bpf object file if defined
+		bpf, err = ioutil.ReadFile(bpfFile)
+		if err != nil && !os.IsNotExist(err) {
+			// only error if the error is *NOT* of type "file not found"
+			return nil, err
+		}
+	}
+
+	if len(bpf) == 0 {
+		// we've tried all sorts of ways to load this file, by default
+		// it attempts to use the go-bindata generated asset resource.
+		bpf = assets.LoadBPF()
+	}
+
+	return bpf, err
+}