Awesome Open Source
Awesome Open Source


Build Status Go Report Card Documentation

A nice and convenient way to work with eBPF programs / perf events from Go.


  • Go 1.10+
  • Linux Kernel 4.15+

Supported eBPF features

  • eBPF programs
    • SocketFilter
    • XDP
    • Kprobe / Kretprobe
  • Perf Events

Support for other program types / features can be added in future. Meanwhile your contributions are warmly welcomed.. :)


# Main library
go get

# Mock version (if needed)
go get

Quick start

Consider very simple example of Read / Load / Attach

    // In order to be simple this examples does not handle errors
    bpf := goebpf.NewDefaultEbpfSystem()
    // Read clang compiled binary
    // Load XDP program into kernel (name matches function name in C)
    xdp := bpf.GetProgramByName("xdp_test")
    // Attach to interface
    defer xdp.Detach()
    // Work with maps
    test := bpf.GetMapByName("test")
    value, _ := test.LookupInt(0)
    fmt.Printf("Value at index 0 of map 'test': %d\n", )

Like it? Check our examples

Perf Events

Library currently has support for one, most popular use case of perf_events - where eBPF map key maps to cpu_id. So eBPF and go parts actually bind cpu_id to map index. It maybe as simple as:

    // Define special, perf_events map where key maps to CPU_ID
    BPF_MAP_DEF(perfmap) = {
        .map_type = BPF_MAP_TYPE_PERF_EVENT_ARRAY,
        .max_entries = 128,     // Max supported CPUs

    // ...

    // Emit perf event with "data" to map "perfmap" where index is current CPU_ID
    bpf_perf_event_output(ctx, &perfmap, BPF_F_CURRENT_CPU, &data, sizeof(data));

And the go part:

    perf, err := goebpf.NewPerfEvents("perfmap")
    // 4096 is ring buffer size
    perfEvents, err := perf.StartForAllProcessesAndCPUs(4096)
    defer perf.Stop()

    for {
        select {
            case data := <-perfEvents:

Simple? Check full XDP dump example


Library currently has support for kprobes and kretprobes. It can be as simple as:

    // kprobe handler function
    int execve_entry(struct pt_regs *ctx) {
      // ...
      return 0;

And the go part:

	// Cleanup old probes
	err := goebpf.CleanupProbes()

	// Attach all probe programs
	for _, prog := range bpf.GetPrograms() {
		err := prog.Attach(nil)

	// Create perf events
	eventsMap := p.bpf.GetMapByName("events"), err = goebpf.NewPerfEvents(eventsMap)
	events, err :=
	defer events.Stop()

	for {
		select {
		case data := <-events:
			fmt.Println(data) // kProbe event

Simple? Check exec dump example

Good readings

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
go (14,920
golang (3,813
golang-library (138
cats (50
ebpf (33
bpf (28
cats-effect (18