feature: OTLP format support (#173)

* analysis: native multi-format profile model (pprof + OTLP)

Teaches the analyzer to read OTLP (OpenTelemetry profiles) in addition to
google/pprof, so scenarios can assert on profilers that emit OTLP.

Rather than convert OTLP --> pprof (which loses what pprof can't represent, e.g.
trace/span links), both formats are read into one small format-neutral model
and assertions run on that. So the same expected_profile.json can, in
principle, work across several formats.

* analysis: add cmd/prof-dump and ignore volatile OTLP attrs in capture

cmd/prof-dump loads a profile file (pprof or OTLP) via the public LoadProfileSet
API and prints the neutral ProfileSet — per-type duration, values, stacks and
labels. Useful for seeing how each format's tags/resource attributes land as
labels and for authoring expectations.

Running it on real host-profiler OTLP showed resource/sample attributes are
flattened onto samples (intended), including some that vary per sample or per
run: cpu.logical_number, container.id, process.context.label.check_id. Add
these to captureKeysToIgnore so they don't split otherwise-identical stacks in
the bootstrap JSON. Assertions are unaffected.

Author: r1viollet

README.md

@@ -108,6 +108,22 @@ Describe what you expect in a json file within the same folder. *This data is ca
 }
 ```
 
+### Profile input formats
+
+The analyzer reads both **pprof** and **OTLP** (OpenTelemetry profiles), so the
+same `expected_profile.json` can be used whichever format a profiler emits.
+Drop OTLP files with a `.otlp` (protobuf) or `.otlp.json` suffix; everything
+else is treated as pprof.
+
+### Semantic differences between formats
+
+Formats express the same concept in different ways (for example a span link is
+a plain label in pprof but a `LinkTable` entry in OTLP). The goal is that one
+expectation in `expected_profile.json` works across formats, with each format's
+native encoding normalized to a shared set of label keys (see `canonKey` in
+`analysis/model.go`). This normalization is not complete yet, so some
+expectations may still need format-specific values.
+
 ### Run your test
 
 ```

analysis/analysis.go

@@ -14,7 +14,6 @@ import (
 	"path/filepath"
 	"regexp"
 	"sort"
-	"strconv"
 	"strings"
 
 	"github.com/google/pprof/profile"
@@ -221,11 +220,17 @@ func containsStr(s []string, v string) bool {
 // entry instead of producing a separate JSON line each.
 var captureKeysToIgnore = []string{
 	"thread native id",
-	"thread id",
-	"process_id",
+	LabelThreadID,
+	LabelProcessID,
 	"end_timestamp_ns",
-	"span id",
-	"local root span id",
+	LabelTraceID,
+	LabelSpanID,
+	LabelLocalRootSID,
+	// OTLP resource/sample attributes that vary per sample or per run and would
+	// otherwise split otherwise-identical stacks in the bootstrap JSON.
+	"cpu.logical_number",             // per-sample: which CPU the sample hit
+	"container.id",                   // per-run
+	"process.context.label.check_id", // per-run
 }
 
 // labelsKey produces a stable string key from a label set (which has already
@@ -240,7 +245,7 @@ func labelsKey(labels []Labels) string {
 	for _, l := range labels {
 		b.WriteString(l.Key)
 		b.WriteByte('=')
-		for _, v := range l.Values { // Values is already sorted by getProfileType
+		for _, v := range l.Values { // Values is already sorted by the format adapter
 			b.WriteString(v)
 			b.WriteByte(',')
 		}
@@ -249,16 +254,20 @@ func labelsKey(labels []Labels) string {
 	return b.String()
 }
 
-func captureProfData(r Reporter, prof *profile.Profile, path string, testName string, profileDuration float64) {
+func captureProfData(r Reporter, ps *ProfileSet, path string, testName string) {
 	var capturedData StackTestData
 	capturedData.TestName = testName
 
-	for _, sampleType := range prof.SampleType {
+	for _, sampleType := range ps.SampleTypes() {
 		var typedStack TypedStacks
-		typedStack.ProfileType = sampleType.Type
+		typedStack.ProfileType = sampleType
 		typedStack.ErrorMargin = 1
 
-		typedProf := getProfileType(r, prof, sampleType.Type)
+		// Rate-scale each type by its own duration (a file may mix, e.g., a
+		// 10s allocation profile with a 60s CPU profile).
+		profileDuration := ps.Duration(sampleType)
+
+		typedProf, _ := ps.Samples(sampleType)
 
 		// Group samples by (stack, kept-labels) and sum their values. Without
 		// this, ephemeral labels like end_timestamp_ns produce one entry per
@@ -324,7 +333,7 @@ func captureProfData(r Reporter, prof *profile.Profile, path string, testName st
 		capturedData.Stacks = append(capturedData.Stacks, typedStack)
 	}
 
-	jsonPath := filepath.Join(filepath.Dir(path), fileNameWithoutExt(filepath.Base(path))) + ".json"
+	jsonPath := captureJSONPath(path)
 
 	err := writeToJSONFile(capturedData, jsonPath)
 	if err != nil {
@@ -334,57 +343,19 @@ func captureProfData(r Reporter, prof *profile.Profile, path string, testName st
 	}
 }
 
-func getProfileType(r Reporter, prof *profile.Profile, type_ string) []StackSample {
-	typeIdx := -1
-	for i, sampleType := range prof.SampleType {
-		if sampleType.Type == type_ {
-			typeIdx = i
-		}
-	}
-	if typeIdx == -1 {
-		r.Fatalf("Couldn't find sample type %s", type_)
-	}
-
-	if err := prof.Aggregate(true, true, false, false, false, false); err != nil {
-		r.Fatalf("Error aggregating profile samples: %v", err)
-	}
-	prof = prof.Compact()
-	sort.Slice(prof.Sample, func(i, j int) bool {
-		return prof.Sample[i].Value[0] > prof.Sample[j].Value[0]
-	})
-
-	var out []StackSample
-	for _, sample := range prof.Sample {
-		var frames []string
-		for i := range sample.Location {
-			loc := sample.Location[len(sample.Location)-i-1]
-			for j := range loc.Line {
-				line := loc.Line[len(loc.Line)-j-1]
-				name := line.Function.Name
-				frames = append(frames, name)
-			}
-		}
-		labels := make(map[string][]string)
-		for k, v := range sample.Label {
-			// ease the comparison by sorting string values
-			sort.Strings(v)
-			labels[k] = v
-		}
-		for k, v := range sample.NumLabel {
-			for _, i := range v {
-				labels[k] = append(labels[k], strconv.FormatInt(i, 10))
-			}
-			sort.Strings(labels[k])
-		}
-
-		ss := StackSample{
-			Stack:  strings.Join(frames, ";"),
-			Val:    sample.Value[typeIdx],
-			Labels: labels,
-		}
-		out = append(out, ss)
-	}
-	return out
+// captureJSONPath is where captureProfData writes the observed-stacks JSON: the
+// profile's basename with its extension replaced by .json. It guards against
+// clobbering the source: inputs whose own extension is already .json (e.g.
+// foo.otlp.json) would otherwise resolve back to the input path, so a
+// .capture.json variant is used instead.
+func captureJSONPath(path string) string {
+	dir := filepath.Dir(path)
+	base := filepath.Base(path)
+	jsonPath := filepath.Join(dir, fileNameWithoutExt(base)+".json")
+	if jsonPath == path {
+		jsonPath = filepath.Join(dir, fileNameWithoutExt(base)+".capture.json")
+	}
+	return jsonPath
 }
 
 func checkLabels(r Reporter, labels map[string][]string, expectedLabels []Labels) bool {
@@ -608,15 +579,10 @@ func getMatchingFiles(folder string, filenameRegex *regexp.Regexp) ([]string, er
 	return matchingFiles, nil
 }
 
-// ReadPprofFile reads a pprof file from disk, transparently decompressing lz4
-// or zstd frames if present, and returns the parsed profile.
-func ReadPprofFile(pprofFile string) (*profile.Profile, error) {
-	file, err := os.Open(pprofFile)
-	if err != nil {
-		return nil, err
-	}
-	defer file.Close()
-	content, err := io.ReadAll(file)
+// readAndDecompress reads a profile file, transparently decompressing lz4 or
+// zstd frames if present, and returns the raw payload bytes.
+func readAndDecompress(path string) ([]byte, error) {
+	content, err := os.ReadFile(path)
 	if err != nil {
 		return nil, err
 	}
@@ -651,36 +617,46 @@ func ReadPprofFile(pprofFile string) (*profile.Profile, error) {
 			content = decompressed
 		}
 	}
-	prof, err := profile.ParseData(content)
+	return content, nil
+}
+
+// ReadPprofFile reads a pprof file from disk (decompressing lz4/zstd if needed)
+// and returns the parsed google/pprof profile. Retained for consumers that
+// want the raw pprof model; the analyzer itself uses LoadProfileSet.
+func ReadPprofFile(pprofFile string) (*profile.Profile, error) {
+	content, err := readAndDecompress(pprofFile)
 	if err != nil {
 		return nil, err
 	}
-	return prof, nil
+	return profile.ParseData(content)
 }
 
 // AnalyzePprofFile reads a single pprof file and asserts the given typedStacks
 // expectations against it. If captureData is true, a JSON dump of the actual
 // stacks observed in the profile is written next to the pprof file (useful to
 // bootstrap an expected_profile.json).
 func AnalyzePprofFile(r Reporter, pprofFile string, typedStacks TypedStacks, testName string, captureData bool, scaleByDuration bool, allowFailure bool) {
-	prof, err := ReadPprofFile(pprofFile)
+	ps, err := LoadProfileSet(pprofFile)
 	if err != nil {
-		r.Fatalf("Error reading file %s", pprofFile)
+		r.Fatalf("Error reading file %s: %v", pprofFile, err)
 	}
 	r.Logf("Analyzing results in %s for profile type %s", pprofFile, typedStacks.ProfileType)
 
-	profileDuration := float64(prof.DurationNanos) / 1000000000.0
+	profileDuration := ps.Duration(typedStacks.ProfileType)
 	r.Logf("Found a profile duration of %.1f seconds (in %s)", profileDuration, filepath.Base(pprofFile))
 
 	// Store current data in a json file to help users create their tests
 	if captureData {
-		captureProfData(r, prof, pprofFile, testName, profileDuration)
+		captureProfData(r, ps, pprofFile, testName)
 	}
 	if !scaleByDuration {
 		// ignore duration, values can be considered absolute
 		profileDuration = 0
 	}
-	typedProf := getProfileType(r, prof, typedStacks.ProfileType)
+	typedProf, ok := ps.Samples(typedStacks.ProfileType)
+	if !ok {
+		r.Fatalf("Couldn't find sample type %s", typedStacks.ProfileType)
+	}
 	analyzeProfDataWithFailureHandling(r, typedProf, typedStacks, profileDuration, allowFailure)
 }