prog: add Program.Stats() and related ProgramStats struct

This commit lifts runtime statistics out of ProgramInfo to allow them to be
queried without fetching all of ProgramInfo, which would otherwise require
multiple calls to OBJ_INFO, multiple allocations, as well as parsing fdinfo.

Signed-off-by: Timo Beckers <timo@isovalent.com>

Author: ti-mo

info.go

@@ -185,15 +185,41 @@ func (mi *MapInfo) Frozen() bool {
 	return mi.frozen
 }
 
-// programStats holds statistics of a program.
-type programStats struct {
-	// Total accumulated runtime of the program ins ns.
-	runtime time.Duration
-	// Total number of times the program was called.
-	runCount uint64
-	// Total number of times the programm was NOT called.
-	// Added in commit 9ed9e9ba2337 ("bpf: Count the number of times recursion was prevented").
-	recursionMisses uint64
+// ProgramStats contains runtime statistics for a single [Program], returned by
+// [Program.Stats].
+//
+// Will contain mostly zero values if the collection of statistics is not
+// enabled, see [EnableStats].
+type ProgramStats struct {
+	// Total accumulated runtime of the Program.
+	//
+	// Requires at least Linux 5.8.
+	Runtime time.Duration
+
+	// Total number of times the Program has executed.
+	//
+	// Requires at least Linux 5.8.
+	RunCount uint64
+
+	// Total number of times the program was not executed due to recursion. This
+	// can happen when another bpf program is already running on the cpu, when bpf
+	// program execution is interrupted, for example.
+	//
+	// Requires at least Linux 5.12.
+	RecursionMisses uint64
+}
+
+func newProgramStatsFromFd(fd *sys.FD) (*ProgramStats, error) {
+	var info sys.ProgInfo
+	if err := sys.ObjInfo(fd, &info); err != nil {
+		return nil, fmt.Errorf("getting program info: %w", err)
+	}
+
+	return &ProgramStats{
+		Runtime:         time.Duration(info.RunTimeNs),
+		RunCount:        info.RunCnt,
+		RecursionMisses: info.RecursionMisses,
+	}, nil
 }
 
 // programJitedInfo holds information about JITed info of a program.
@@ -230,7 +256,8 @@ type programJitedInfo struct {
 	numFuncLens uint32
 }
 
-// ProgramInfo describes a program.
+// ProgramInfo describes a Program's immutable metadata. For runtime statistics,
+// see [ProgramStats].
 type ProgramInfo struct {
 	Type ProgramType
 	id   ProgramID
@@ -242,7 +269,6 @@ type ProgramInfo struct {
 	createdByUID     uint32
 	haveCreatedByUID bool
 	btf              btf.ID
-	stats            *programStats
 	loadTime         time.Duration
 
 	maps                 []MapID
@@ -275,16 +301,11 @@ func newProgramInfoFromFd(fd *sys.FD) (*ProgramInfo, error) {
 	}
 
 	pi := ProgramInfo{
-		Type: typ,
-		id:   ProgramID(info.Id),
-		Tag:  hex.EncodeToString(info.Tag[:]),
-		Name: unix.ByteSliceToString(info.Name[:]),
-		btf:  btf.ID(info.BtfId),
-		stats: &programStats{
-			runtime:         time.Duration(info.RunTimeNs),
-			runCount:        info.RunCnt,
-			recursionMisses: info.RecursionMisses,
-		},
+		Type:                 typ,
+		id:                   ProgramID(info.Id),
+		Tag:                  hex.EncodeToString(info.Tag[:]),
+		Name:                 unix.ByteSliceToString(info.Name[:]),
+		btf:                  btf.ID(info.BtfId),
 		jitedSize:            info.JitedProgLen,
 		loadTime:             time.Duration(info.LoadTime),
 		verifiedInstructions: info.VerifiedInsns,
@@ -453,38 +474,6 @@ func (pi *ProgramInfo) BTFID() (btf.ID, bool) {
 	return pi.btf, pi.btf > 0
 }
 
-// RunCount returns the total number of times the program was called.
-//
-// Can return 0 if the collection of statistics is not enabled. See EnableStats().
-// The bool return value indicates whether this optional field is available.
-func (pi *ProgramInfo) RunCount() (uint64, bool) {
-	if pi.stats != nil {
-		return pi.stats.runCount, true
-	}
-	return 0, false
-}
-
-// Runtime returns the total accumulated runtime of the program.
-//
-// Can return 0 if the collection of statistics is not enabled. See EnableStats().
-// The bool return value indicates whether this optional field is available.
-func (pi *ProgramInfo) Runtime() (time.Duration, bool) {
-	if pi.stats != nil {
-		return pi.stats.runtime, true
-	}
-	return time.Duration(0), false
-}
-
-// RecursionMisses returns the total number of times the program was NOT called.
-// This can happen when another bpf program is already running on the cpu, which
-// is likely to happen for example when you interrupt bpf program execution.
-func (pi *ProgramInfo) RecursionMisses() (uint64, bool) {
-	if pi.stats != nil {
-		return pi.stats.recursionMisses, true
-	}
-	return 0, false
-}
-
 // btfSpec returns the BTF spec associated with the program.
 func (pi *ProgramInfo) btfSpec() (*btf.Spec, error) {
 	id, ok := pi.BTFID()
@@ -836,12 +825,16 @@ func zero(arg any) bool {
 	return v.IsZero()
 }
 
-// EnableStats starts the measuring of the runtime
-// and run counts of eBPF programs.
+// EnableStats starts collecting runtime statistics of eBPF programs, like the
+// amount of program executions and the cumulative runtime.
+//
+// Specify a BPF_STATS_* constant to select which statistics to collect, like
+// [unix.BPF_STATS_RUN_TIME]. Closing the returned [io.Closer] will stop
+// collecting statistics.
 //
-// Collecting statistics can have an impact on the performance.
+// Collecting statistics may have a performance impact.
 //
-// Requires at least 5.8.
+// Requires at least Linux 5.8.
 func EnableStats(which uint32) (io.Closer, error) {
 	fd, err := sys.EnableStats(&sys.EnableStatsAttr{
 		Type: which,

info_test.go

@@ -1,7 +1,6 @@
 package ebpf
 
 import (
-	"errors"
 	"fmt"
 	"os"
 	"reflect"
@@ -404,56 +403,40 @@ func BenchmarkScanFdInfoReader(b *testing.B) {
 	}
 }
 
-// TestStats loads a BPF program once and executes back-to-back test runs
+// TestProgramStats loads a BPF program once and executes back-to-back test runs
 // of the program. See testStats for details.
-func TestStats(t *testing.T) {
+func TestProgramStats(t *testing.T) {
 	testutils.SkipOnOldKernel(t, "5.8", "BPF_ENABLE_STATS")
 
 	prog := createBasicProgram(t)
 
-	pi, err := prog.Info()
-	if err != nil {
-		t.Errorf("failed to get ProgramInfo: %v", err)
-	}
-
-	rc, ok := pi.RunCount()
-	if !ok {
-		t.Errorf("expected run count info to be available")
-	}
-	if rc != 0 {
-		t.Errorf("expected a run count of 0 but got %d", rc)
-	}
+	s, err := prog.Stats()
+	qt.Assert(t, qt.IsNil(err))
 
-	rt, ok := pi.Runtime()
-	if !ok {
-		t.Errorf("expected runtime info to be available")
-	}
-	if runtime.GOARCH != "arm64" && rt != 0 {
-		t.Errorf("expected a runtime of 0ns but got %v", rt)
-	}
+	qt.Assert(t, qt.Equals(s.RunCount, 0))
+	qt.Assert(t, qt.Equals(s.RecursionMisses, 0))
 
-	rm, ok := pi.RecursionMisses()
-	if !ok {
-		t.Errorf("expected recursion misses info to be available")
-	}
-	if rm != 0 {
-		t.Errorf("expected a recursion misses of 0 but got %v", rm)
+	if runtime.GOARCH != "arm64" {
+		// Runtime is flaky on arm64.
+		qt.Assert(t, qt.Equals(s.Runtime, 0))
 	}
 
-	if err := testStats(prog); err != nil {
+	if err := testStats(t, prog); err != nil {
 		testutils.SkipIfNotSupportedOnOS(t, err)
 		t.Error(err)
 	}
 }
 
 // BenchmarkStats is a benchmark of TestStats. See testStats for details.
 func BenchmarkStats(b *testing.B) {
+	b.ReportAllocs()
+
 	testutils.SkipOnOldKernel(b, "5.8", "BPF_ENABLE_STATS")
 
 	prog := createBasicProgram(b)
 
 	for n := 0; n < b.N; n++ {
-		if err := testStats(prog); err != nil {
+		if err := testStats(b, prog); err != nil {
 			testutils.SkipIfNotSupportedOnOS(b, err)
 			b.Fatal(fmt.Errorf("iter %d: %w", n, err))
 		}
@@ -470,7 +453,9 @@ func BenchmarkStats(b *testing.B) {
 // resulting in RunCount incrementing by more than one. Expecting RunCount to
 // be of a specific value after a call to Test() is therefore not possible.
 // See https://golang.org/doc/go1.14#runtime for more details.
-func testStats(prog *Program) error {
+func testStats(tb testing.TB, prog *Program) error {
+	tb.Helper()
+
 	in := internal.EmptyBPFContext
 
 	stats, err := EnableStats(uint32(sys.BPF_STATS_RUN_TIME))
@@ -485,61 +470,25 @@ func testStats(prog *Program) error {
 		return fmt.Errorf("failed to trigger program: %w", err)
 	}
 
-	pi, err := prog.Info()
-	if err != nil {
-		return fmt.Errorf("failed to get ProgramInfo: %w", err)
-	}
+	s1, err := prog.Stats()
+	qt.Assert(tb, qt.IsNil(err))
 
-	rc, ok := pi.RunCount()
-	if !ok {
-		return errors.New("expected run count info to be available")
-	}
-	if rc < 1 {
-		return fmt.Errorf("expected a run count of at least 1 but got %d", rc)
-	}
-	// Store the run count for the next invocation.
-	lc := rc
+	qt.Assert(tb, qt.Not(qt.Equals(s1.RunCount, 0)), qt.Commentf("expected run count to be at least 1 after first invocation"))
+	qt.Assert(tb, qt.Not(qt.Equals(s1.Runtime, 0)), qt.Commentf("expected runtime to be at least 1ns after first invocation"))
 
-	rt, ok := pi.Runtime()
-	if !ok {
-		return errors.New("expected runtime info to be available")
-	}
-	if rt == 0 {
-		return errors.New("expected a runtime other than 0ns")
-	}
-	// Store the runtime value for the next invocation.
-	lt := rt
-
-	if err := stats.Close(); err != nil {
-		return fmt.Errorf("failed to disable statistics: %w", err)
-	}
+	qt.Assert(tb, qt.IsNil(stats.Close()))
 
 	// Second program execution, with runtime statistics gathering disabled.
 	// Total runtime and run counters are not expected to increase.
 	if _, _, err := prog.Test(in); err != nil {
 		return fmt.Errorf("failed to trigger program: %w", err)
 	}
 
-	pi, err = prog.Info()
-	if err != nil {
-		return fmt.Errorf("failed to get ProgramInfo: %w", err)
-	}
-
-	rc, ok = pi.RunCount()
-	if !ok {
-		return errors.New("expected run count info to be available")
-	}
-	if rc != lc {
-		return fmt.Errorf("run count unexpectedly increased over previous value (current: %v, prev: %v)", rc, lc)
-	}
+	s2, err := prog.Stats()
+	qt.Assert(tb, qt.IsNil(err))
 
-	rt, ok = pi.Runtime()
-	if !ok {
-		return errors.New("expected runtime info to be available")
-	}
-	if rt != lt {
-		return fmt.Errorf("runtime unexpectedly increased over the previous value (current: %v, prev: %v)", rt, lt)
-	}
+	qt.Assert(tb, qt.Equals(s2.RunCount, s1.RunCount), qt.Commentf("run count (%d) increased after first invocation (%d)", s2.RunCount, s1.RunCount))
+	qt.Assert(tb, qt.Equals(s2.Runtime, s1.Runtime), qt.Commentf("runtime (%d) increased after first invocation (%d)", s2.Runtime, s1.Runtime))
 
 	return nil
 }

prog.go

@@ -599,6 +599,14 @@ func (p *Program) Info() (*ProgramInfo, error) {
 	return newProgramInfoFromFd(p.fd)
 }
 
+// Stats returns runtime statistics about the Program. Requires BPF statistics
+// collection to be enabled, see [EnableStats].
+//
+// Requires at least Linux 5.8.
+func (p *Program) Stats() (*ProgramStats, error) {
+	return newProgramStatsFromFd(p.fd)
+}
+
 // Handle returns a reference to the program's type information in the kernel.
 //
 // Returns ErrNotSupported if the kernel has no BTF support, or if there is no