[stacktrace] implement stacktrace.CaptureCaller function

New function captures single frame with specified skip. This is more
performant for cases when only caller's frame required.

Also:
- Utilize Frame structure in Stack.
- Rename `stacktrace.Capture` to `stacktrace.CaptureStack`.

Change-Id: Ida92c73d800b4ff6b2fea72fb0b950cdb2985761

Author: xobotyi

logger/logger.go

@@ -387,7 +387,7 @@ func (l Logger) WithStackTrace(skip int) Logger {
 	}
 
 	l.adapter = l.adapter.WithFields(l.mappers.stackTrace(
-		stacktrace.Capture(skip+1, stackTraceDepth),
+		stacktrace.CaptureStack(skip+1, stackTraceDepth),
 	))
 
 	return l

stacktrace/doc.go

@@ -7,29 +7,54 @@
 //
 // To capture the current stack trace:
 //
-//	stack := stacktrace.Capture(0, stacktrace.DefaultDepth)
+//	stack := stacktrace.CaptureStack(0, stacktrace.DefaultDepth)
 //	fmt.Println(stack.String())
 //
+// To capture only the immediate caller:
+//
+//	frame := stacktrace.CaptureCaller(0)
+//	fmt.Println(frame.FullPath()) // prints: /path/to/file.go:123
+//
+// # Frame Type
+//
+// The Frame type represents a single stack frame with program counter, file path,
+// line number, and function name. It provides several formatting methods:
+//
+//	frame := stacktrace.CaptureCaller(0)
+//	frame.FullPath()  // Returns: "/path/to/file.go:123"
+//	frame.String()    // Returns: "function.name\n\t/path/to/file.go:123"
+//
+// Use CaptureCaller when you only need information about the immediate caller,
+// as it's more efficient than capturing a full stack trace.
+//
 // # Controlling Depth
 //
 // Capture a limited number of frames:
 //
-//	stack := stacktrace.Capture(0, 10) // Capture up to 10 frames
+//	stack := stacktrace.CaptureStack(0, 10) // Capture up to 10 frames
 //
 // Capture the complete stack trace:
 //
-//	stack := stacktrace.Capture(0, math.MaxInt) // Unlimited depth
+//	stack := stacktrace.CaptureStack(0, math.MaxInt) // Unlimited depth
 //
 // # Skipping Frames
 //
 // Skip frames to exclude wrapper functions from the trace:
 //
 //	func myLogger(msg string) {
 //	    // Skip 1 frame to exclude myLogger from the trace
-//	    stack := stacktrace.Capture(1, stacktrace.DefaultDepth)
+//	    stack := stacktrace.CaptureStack(1, stacktrace.DefaultDepth)
 //	    log.Printf("%s\n%s", msg, stack.String())
 //	}
 //
+// The same skip parameter works with CaptureCaller:
+//
+//	func getCallerInfo() string {
+//	    // Skip 1 to get the caller of getCallerInfo, not getCallerInfo itself
+//	    frame := stacktrace.CaptureCaller(1)
+//	    return frame.FullPath()
+//	}
+//
 // # Output Format
 //
 // The Stack.String() method formats stack traces as:
@@ -46,7 +71,7 @@
 //
 // Access individual frames using the iterator for custom processing or formatting:
 //
-//	stack := stacktrace.Capture(0, stacktrace.DefaultDepth)
+//	stack := stacktrace.CaptureStack(0, stacktrace.DefaultDepth)
 //	for idx, frame := range stack.Frames() {
 //	    fmt.Printf("%d: %s at %s:%d\n", idx, frame.Function, frame.File, frame.Line)
 //	}

stacktrace/stacktrace.go

@@ -6,7 +6,6 @@ import (
 	"math"
 	"runtime"
 	"strconv"
-	"strings"
 )
 
 // Frame represents a single stack frame containing program counter, file path,
@@ -83,13 +82,13 @@ func (f Frame) Write(b *bytes.Buffer) {
 
 // Stack represents a captured call stack consisting of program counter frames.
 type Stack struct {
-	frames []runtime.Frame
+	frames []Frame
 }
 
 // Frames returns an iterator over the stack frames.
 // The iterator yields (index, frame) pairs for each frame in the stack.
-func (s *Stack) Frames() iter.Seq2[int, runtime.Frame] {
-	return func(yield func(int, runtime.Frame) bool) {
+func (s *Stack) Frames() iter.Seq2[int, Frame] {
+	return func(yield func(int, Frame) bool) {
 		for i, frame := range s.frames {
 			if !yield(i, frame) {
 				break
@@ -111,38 +110,49 @@ func (s *Stack) String() string {
 	}
 
 	// Estimate capacity: ~100 bytes per frame on average
-	b := strings.Builder{}
-	b.Grow(len(s.frames) * 100) //nolint:mnd
+	b := bytes.NewBuffer(make([]byte, 0, len(s.frames)*100)) //nolint:mnd
 
 	for i, f := range s.frames {
 		if i > 0 {
 			b.WriteRune('\n')
 		}
 
-		WriteFrameToBuffer(f, &b)
+		f.Write(b)
 	}
 
 	return b.String()
 }
 
-// WriteFrameToBuffer formats a single runtime.Frame and writes it to the
-// provided buffer. The frame is formatted as "function\n\tfile:line".
-func WriteFrameToBuffer(f runtime.Frame, b *strings.Builder) {
-	b.WriteString(f.Function)
-	b.WriteString("\n\t")
-	b.WriteString(f.File)
-	b.WriteRune(':')
-	b.WriteString(strconv.Itoa(f.Line))
-}
-
 // DefaultDepth is the default maximum number of stack frames to capture.
 const DefaultDepth = 64
 
-// Capture captures the current goroutine's call stack. The skip argument
+// CaptureCaller captures a single caller frame from the current goroutine's call
+// stack. The skip argument specifies the number of frames to skip before
+// recording (0 means the direct caller of CaptureCaller).
+//
+// This is more efficient than CaptureStack when only the immediate caller information
+// is needed, as it only captures and processes a single frame.
+func CaptureCaller(skip int) Frame {
+	skip += 2 // we don't want current function and runtime.Callers to get to trace
+
+	var pcs [1]uintptr
+
+	n := runtime.Callers(skip, pcs[:])
+
+	if n == 0 {
+		return Frame{} //nolint:exhaustruct
+	}
+
+	runtimeFrame, _ := runtime.CallersFrames(pcs[:n]).Next()
+
+	return NewFrame(runtimeFrame)
+}
+
+// CaptureStack captures the current goroutine's call stack. The skip argument
 // specifies the number of frames to skip before recording (0 means start at
 // caller). The depth argument specifies the maximum number of frames to capture
 // (use math.MaxInt for unlimited).
-func Capture(skip, depth int) *Stack {
+func CaptureStack(skip, depth int) *Stack {
 	skip++ // we don't want current function to get to trace
 
 	var pcs []uintptr
@@ -152,13 +162,13 @@ func Capture(skip, depth int) *Stack {
 		pcs = callersFinite(skip, depth)
 	}
 
-	stack := &Stack{frames: make([]runtime.Frame, 0, len(pcs))}
+	stack := &Stack{frames: make([]Frame, 0, len(pcs))}
 	frames := runtime.CallersFrames(pcs)
 
 	for {
 		frame, next := frames.Next()
 
-		stack.frames = append(stack.frames, frame)
+		stack.frames = append(stack.frames, NewFrame(frame))
 
 		if !next {
 			break

stacktrace/stacktrace_test.go

@@ -1,7 +1,6 @@
 package stacktrace_test
 
 import (
-	"bytes"
 	"math"
 	"runtime"
 	"strings"
@@ -63,7 +62,7 @@ func TestFrame(t *testing.T) {
 		assert.Equal(t, "undefined", fullPath)
 	})
 
-	t.Run("Write formats correctly", func(t *testing.T) {
+	t.Run("String formats correctly", func(t *testing.T) {
 		t.Parallel()
 
 		frame := stacktrace.Frame{
@@ -73,14 +72,10 @@ func TestFrame(t *testing.T) {
 			Function: "main.run",
 		}
 
-		buf := &bytes.Buffer{}
-		frame.Write(buf)
-
-		expected := "main.run\n\t/Users/test/main.go:100"
-		assert.Equal(t, expected, buf.String())
+		assert.Equal(t, "main.run\n\t/Users/test/main.go:100", frame.String())
 	})
 
-	t.Run("Write handles zero PC", func(t *testing.T) {
+	t.Run("String handles zero PC", func(t *testing.T) {
 		t.Parallel()
 
 		frame := stacktrace.Frame{
@@ -90,16 +85,13 @@ func TestFrame(t *testing.T) {
 			Function: "package.Function",
 		}
 
-		buf := &bytes.Buffer{}
-		frame.Write(buf)
-
-		assert.Equal(t, "undefined", buf.String())
+		assert.Equal(t, "undefined", frame.String())
 	})
 }
 
 func recursionA(i, depth int) *stacktrace.Stack {
 	if i == 0 {
-		return stacktrace.Capture(0, depth)
+		return stacktrace.CaptureStack(0, depth)
 	}
 
 	fn := recursionB
@@ -112,7 +104,7 @@ func recursionA(i, depth int) *stacktrace.Stack {
 
 func recursionB(i, depth int) *stacktrace.Stack {
 	if i == 0 {
-		return stacktrace.Capture(0, depth)
+		return stacktrace.CaptureStack(0, depth)
 	}
 
 	fn := recursionB
@@ -123,16 +115,19 @@ func recursionB(i, depth int) *stacktrace.Stack {
 	return fn(i-1, depth)
 }
 
-func TestCapture(t *testing.T) {
+func TestCaptureStack(t *testing.T) {
 	t.Parallel()
 
+	assert.Empty(t, new(stacktrace.Stack).String(), "empty stack should produce empty string")
+
 	t.Run("shallow stack", func(t *testing.T) {
 		t.Parallel()
 
 		// Capture a very shallow stack with only 2 frames
-		s := stacktrace.Capture(0, 2)
+		s := stacktrace.CaptureStack(0, 2)
 		require.Equal(t, 2, s.Len())
 
+		// Test through the .String function to also check stringification validity.
 		str := s.String()
 		require.NotEmpty(t, str)
 
@@ -141,7 +136,7 @@ func TestCapture(t *testing.T) {
 		require.Len(t, lines, 4, "should have 4 lines: func1, location1, func2, location2")
 
 		// First frame: function name (the current test function)
-		require.Contains(t, lines[0], "TestCapture", "first frame should be test function")
+		require.Contains(t, lines[0], "TestCaptureStack", "first frame should be test function")
 		require.Contains(t, lines[0], "stacktrace_test", "first frame should be in stacktrace_test package")
 
 		// First frame: location (starts with tab)
@@ -194,3 +189,42 @@ func TestCapture(t *testing.T) {
 		require.Equal(t, s.Len(), count, "iterator should yield same number of frames as Len()")
 	})
 }
+
+func TestCaptureCaller(t *testing.T) {
+	t.Parallel()
+
+	t.Run("captures direct caller", func(t *testing.T) {
+		t.Parallel()
+
+		frame := stacktrace.CaptureCaller(0)
+		require.NotEmpty(t, frame.Function, "should capture function name")
+		require.Contains(t, frame.Function, "TestCaptureCaller", "should contain test function name")
+		require.NotEmpty(t, frame.File, "should capture file path")
+		require.Contains(t, frame.File, "stacktrace_test.go", "should be from test file")
+		require.Positive(t, frame.Line, "should have positive line number")
+	})
+
+	t.Run("skip parameter works", func(t *testing.T) {
+		t.Parallel()
+
+		// CaptureStack from this test directly with different skip values
+		frame0 := stacktrace.CaptureCaller(0)
+		require.Contains(t, frame0.Function, "TestCaptureCaller", "skip=0 should capture test function")
+
+		// Use helper to test skip=1
+		helperFunc := func() stacktrace.Frame {
+			return stacktrace.CaptureCaller(1) // skip=1 skips helper, captures test
+		}
+
+		frame1 := helperFunc()
+		require.Contains(t, frame1.Function, "TestCaptureCaller", "skip=1 should skip helper and capture test")
+	})
+
+	t.Run("returns empty frame when no caller", func(t *testing.T) {
+		t.Parallel()
+
+		// Very large skip should result in empty frame
+		frame := stacktrace.CaptureCaller(1000)
+		require.Empty(t, frame.Function, "should return empty frame for too-large skip")
+	})
+}