pkg: add pfpstatus package

the pfpstatus package is an extended version of the
package originally added in `openshift-kni/scheduler-plugins/pkg-kni`
which wants to make it easier to troubleshoot PFP desync issues.

It is meant to be consumed by any program which produces or consumes PFPs.

Signed-off-by: Francesco Romani <fromani@redhat.com>

Author: ffromani

go.mod

@@ -10,6 +10,7 @@ require (
 	github.com/google/cadvisor v0.52.1
 	github.com/google/go-cmp v0.6.0
 	github.com/jaypipes/ghw v0.12.0
+	github.com/k8stopologyawareschedwg/podfingerprint v0.2.3
 	github.com/onsi/ginkgo v1.14.0
 	github.com/onsi/gomega v1.35.1
 	github.com/safchain/ethtool v0.3.0
@@ -33,6 +34,7 @@ require (
 )
 
 require (
+	github.com/OneOfOne/xxhash v1.2.8 // indirect
 	github.com/StackExchange/wmi v1.2.1 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/emicklei/go-restful/v3 v3.11.0 // indirect

go.sum

@@ -1,3 +1,5 @@
+github.com/OneOfOne/xxhash v1.2.8 h1:31czK/TI9sNkxIKfaUfGlU47BAxQ0ztGgd9vPyqimf8=
+github.com/OneOfOne/xxhash v1.2.8/go.mod h1:eZbhyaAYD41SGSSsnmcpxVoRiQ/MPUTjUdIIOT9Um7Q=
 github.com/StackExchange/wmi v1.2.1 h1:VIkavFPXSjcnS+O8yTq7NI32k0R5Aj+v39y29VYDOSA=
 github.com/StackExchange/wmi v1.2.1/go.mod h1:rcmrprowKIVzvc+NUiLncP2uuArMWLCbu9SBzvHz7e8=
 github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
@@ -73,6 +75,8 @@ github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8Hm
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/k8stopologyawareschedwg/podfingerprint v0.2.3 h1:nVKmzn6g7CHhDtB+jG85Db/B/ALRY9VLh5ueAfVPEHU=
+github.com/k8stopologyawareschedwg/podfingerprint v0.2.3/go.mod h1:E0bjgihZTSwRIJVjNV45Lm0C/j5w+YkGSnfpYXoI8Ws=
 github.com/kisielk/errcheck v1.5.0/go.mod h1:pFxgyoBC7bSaBwPgfKdkLd5X25qrDl4LWUI2bnpBCr8=
 github.com/kisielk/gotool v1.0.0/go.mod h1:XhKaO+MFFWcvkIS/tQcRk01m1F5IRFswLeQ+oQHNcck=
 github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=

pkg/pfpstatus/README.md

@@ -0,0 +1,14 @@
+# PFPStatus
+
+PFPStatus offer facilities to store and expose [podfingerprint](https://github.com/k8stopologyawareschedwg/podfingerprint) status info.
+
+The status info is exposed read-only; external actors cannot alter the PFP status.
+The PFP status exposes the namespace/name pairs of the pods whose container have exclusive resources assigned and which are
+detected by the system. While the information discolosure is minimal, this may be undesirable, so caution is advised.
+
+## Exposing status info
+
+The status info can be exposed by
+- dumping the content as JSON files, one per node, in the filesystem.
+  We recommend to use a fixed size tmpfs to avoid unbounded storage consumption.
+  The writer dumps the status content atomically and intentionally ignores write errors because assumes fixed size storage.

pkg/pfpstatus/pfpstatus.go

@@ -0,0 +1,131 @@
+/*
+ * Copyright 2025 Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package pfpstatus
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"sync"
+	"time"
+
+	"github.com/go-logr/logr"
+
+	"github.com/k8stopologyawareschedwg/podfingerprint"
+
+	"github.com/openshift-kni/debug-tools/pkg/pfpstatus/record"
+)
+
+const (
+	PFPStatusDumpEnvVar string = "PFP_STATUS_DUMP"
+)
+
+const (
+	DefaultDumpDirectory string = "/run/pfpstatus"
+)
+
+const (
+	defaultMaxNodes          = 5000
+	defaultMaxSamplesPerNode = 10
+	defaultDumpPeriod        = 10 * time.Second
+)
+
+type StorageParams struct {
+	Enabled   bool
+	Directory string
+	Period    time.Duration
+}
+
+type Params struct {
+	Storage StorageParams
+}
+
+type environ struct {
+	mu  sync.Mutex
+	rec *record.Recorder
+	lh  logr.Logger
+}
+
+func DefaultParams() Params {
+	return Params{
+		Storage: StorageParams{
+			Enabled:   false,
+			Directory: DefaultDumpDirectory,
+			Period:    10 * time.Second,
+		},
+	}
+}
+
+func ParamsFromEnv(lh logr.Logger, params *Params) {
+	dumpDir, ok := os.LookupEnv(PFPStatusDumpEnvVar)
+	if !ok || dumpDir == "" {
+		params.Storage.Enabled = false
+	} else {
+		params.Storage.Enabled = true
+		params.Storage.Directory = dumpDir
+	}
+
+	// let's try to keep the amount of code we do in init() at minimum.
+	// This may happen if the container didn't have the directory mounted
+	if !existsBaseDirectory(dumpDir) {
+		lh.Info("base directory not found, will discard everything", "baseDirectory", dumpDir)
+		params.Storage.Enabled = false
+	}
+}
+
+func Setup(logh logr.Logger, params Params) {
+	if !params.Storage.Enabled {
+		logh.Info("no backend enabled, nothing to do")
+		return
+	}
+
+	logh.Info("Setup in progress", "params", fmt.Sprintf("%+#v", params))
+
+	rec, err := record.NewRecorder(defaultMaxNodes, defaultMaxSamplesPerNode, time.Now)
+	if err != nil {
+		logh.Error(err, "cannot create a status recorder")
+		return
+	}
+
+	ctx := context.Background()
+	env := environ{
+		rec: rec,
+		lh:  logh,
+	}
+
+	ch := make(chan podfingerprint.Status)
+	podfingerprint.SetCompletionSink(ch)
+	go collectLoop(ctx, &env, ch)
+	if params.Storage.Enabled {
+		go dumpLoop(ctx, &env, params.Storage)
+	}
+}
+
+func collectLoop(ctx context.Context, env *environ, updates <-chan podfingerprint.Status) {
+	env.lh.V(4).Info("collect loop started")
+	defer env.lh.V(4).Info("collect loop finished")
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case st := <-updates:
+			env.mu.Lock()
+			_ = env.rec.Push(st) // intentionally ignore error
+			env.mu.Unlock()
+		}
+	}
+}

pkg/pfpstatus/pfpstatus_file.go

@@ -0,0 +1,64 @@
+/*
+ * Copyright 2025 Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package pfpstatus
+
+import (
+	"context"
+	"os"
+	"sync"
+	"time"
+
+	"github.com/openshift-kni/debug-tools/pkg/pfpstatus/record"
+)
+
+func dumpLoop(ctx context.Context, env *environ, params StorageParams) {
+	env.lh.V(4).Info("dump loop started")
+	defer env.lh.V(4).Info("dump loop finished")
+	ticker := time.NewTicker(params.Period)
+	defer ticker.Stop()
+	for {
+		select {
+		case <-ctx.Done():
+			return
+		case <-ticker.C:
+			env.mu.Lock()
+			snapshot := env.rec.Content()
+			env.mu.Unlock()
+
+			var wg sync.WaitGroup
+			for nodeName, statuses := range snapshot {
+				wg.Add(1)
+				go func(fileName string, statuses []record.RecordedStatus) {
+					defer wg.Done()
+					err := record.DumpToFile(params.Directory, fileName, statuses)
+					if err != nil {
+						env.lh.V(6).Error(err, "dumping file", "dir", params.Directory, "file", fileName, "statusCount", len(statuses))
+					}
+				}(record.NodeNameToFileName(nodeName), statuses)
+			}
+			wg.Wait()
+		}
+	}
+}
+
+func existsBaseDirectory(baseDir string) bool {
+	info, err := os.Stat(baseDir)
+	if err != nil {
+		return false
+	}
+	return info.IsDir()
+}

pkg/pfpstatus/pfpstatus_test.go

@@ -0,0 +1,72 @@
+/*
+ * Copyright 2025 Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package pfpstatus
+
+import (
+	"testing"
+
+	"github.com/go-logr/logr/testr"
+	"github.com/google/go-cmp/cmp"
+)
+
+func TestParamsFromEnv(t *testing.T) {
+	type envvar struct {
+		name  string
+		value string
+	}
+	type testCase struct {
+		name     string
+		envs     []envvar
+		expected Params
+	}
+
+	testCases := []testCase{
+		{
+			name:     "no env",
+			expected: Params{},
+		},
+		{
+			name: "enable using existing var",
+			envs: []envvar{
+				{
+					name:  PFPStatusDumpEnvVar,
+					value: "/tmp", // we know this will always exist
+				},
+			},
+			expected: Params{
+				Storage: StorageParams{
+					Enabled:   true,
+					Directory: "/tmp",
+				},
+			},
+		},
+	}
+
+	for _, tcase := range testCases {
+		t.Run(tcase.name, func(t *testing.T) {
+			for _, env := range tcase.envs {
+				t.Setenv(env.name, env.value)
+			}
+			var got Params
+			ParamsFromEnv(testr.New(t), &got)
+
+			if diff := cmp.Diff(got, tcase.expected); diff != "" {
+				t.Errorf("compare failed: %s", diff)
+			}
+		})
+	}
+}

pkg/pfpstatus/record/codec.go

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2025 Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package record
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+)
+
+func NodeNameToFileName(name string) string {
+	return strings.ReplaceAll(name, ".", "_")
+}
+
+func FileNameToNodeName(name string) string {
+	return strings.ReplaceAll(name, "_", ".")
+}
+
+// DumpToFile encodes in JSON and dumps the given `obj` to a file.
+// `dir` is the base directory on which the file must be created
+// `file` is the name of the file to create in `dir`.
+// The old file, if present, is always updated atomically.
+func DumpToFile(dir, file string, obj any) error {
+	data, err := json.Marshal(obj)
+	if err != nil {
+		return err
+	}
+
+	dst, err := os.CreateTemp(dir, "__"+file)
+	if err != nil {
+		return err
+	}
+	defer os.Remove(dst.Name()) // either way, we need to get rid of this
+
+	_, err = dst.Write(data)
+	if err != nil {
+		return err
+	}
+
+	err = dst.Close()
+	if err != nil {
+		return err
+	}
+
+	return os.Rename(dst.Name(), filepath.Join(dir, file))
+}
+
+// LoadFromFile decodes the JSON data found in `file` placed in `dir`
+// and stores it into `obj`, which must be a pointer.
+func LoadFromFile(dir, file string, obj any) error {
+	data, err := os.ReadFile(filepath.Join(dir, file))
+	if err != nil {
+		return err
+	}
+	return json.Unmarshal(data, obj)
+}