feat: harden Lambda snapshot capture and comparison

- Prevent accidental snapshot overwrites without --overwrite
- Preserve usable stream pages after partial CloudWatch failures
- Complete split invocation pages before stopping pagination
- Reject unrelated JSON before running snapshot comparisons
- Add duration and memory regression gates plus JSON output
- Normalize volatile log values to reduce noisy diffs
- Add version subcommand
- Add selfupdate subcommand

Author: naterator

.github/workflows/build.yml

@@ -27,7 +27,7 @@ jobs:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           goos: ${{ matrix.goos }}
           goarch: ${{ matrix.goarch }}
-          ldflags: -s -w
+          ldflags: -s -w -X main.appVersion=${{ github.event.release.tag_name }}
           build_flags: -trimpath
           overwrite: true
           sha256sum: true

README.md

@@ -12,6 +12,12 @@ Or you can install by building from source directly as follows. Go 1.25 or later
 go install github.com/naterator/lambda-deploy-log-compare@latest
 ```
 
+To check for a newer GitHub release and replace the current executable:
+
+```bash
+lambda-deploy-log-compare selfupdate
+```
+
 ## Quick Start
 
 ```bash
@@ -57,12 +63,13 @@ lambda-deploy-log-compare capture --function <name>[,<name>,...] --label <label>
 | `--out` | `.` | Output directory for snapshot JSON files |
 | `--region` | `us-west-2` | AWS region |
 | `--profile` | | AWS CLI profile name |
+| `--overwrite` | `false` | Replace an existing snapshot file with the same function and label |
 
 Log groups are derived as `/aws/lambda/<function-name>`.
 
 Duplicate function names are rejected so one capture run cannot silently rescan the same Lambda and overwrite the same snapshot path.
 
-Output files are named from sanitized `<function-name>_<label>.json` components in the output directory. Path separators and traversal-style input such as `..` are rewritten so snapshot writes stay inside the chosen output directory. Each function gets its own snapshot file, and the output directory is created automatically when a snapshot is written.
+Output files are named from sanitized `<function-name>_<label>.json` components in the output directory. Path separators and traversal-style input such as `..` are rewritten so snapshot writes stay inside the chosen output directory. Each function gets its own snapshot file, and the output directory is created automatically when a snapshot is written. Existing snapshot files are not replaced unless `--overwrite` is set.
 
 The `--offset` flag lets you look further back in time. For example, `--offset 100 --count 20` skips the 100 most recent invocations and captures the 20 after that. This is useful for grabbing a historical baseline to compare against.
 
@@ -82,17 +89,37 @@ lambda-deploy-log-compare compare --a <baseline.json> --b <new.json> [options]
 | `--b` | | Path to new snapshot JSON file (required) |
 | `--strict` | `false` | Fail if either snapshot is missing `function_name` / `log_group`, or if those fields disagree |
 | `--fail-on-regression` | `false` | Exit non-zero if the new snapshot has more errors or new error patterns |
+| `--max-duration-regression-pct` | `0` | Exit non-zero if new p90 duration exceeds baseline p90 by more than this percentage. `0` disables this gate. |
+| `--max-memory-regression-pct` | `0` | Exit non-zero if new max peak memory exceeds baseline max peak memory by more than this percentage. `0` disables this gate. |
+| `--json` | `false` | Print a machine-readable JSON comparison summary instead of the human report |
 
 The comparison includes:
 
 - **Error count** — warns if errors increased
 - **Error patterns** — new patterns that appeared, old patterns that disappeared
-- **Regression gate** — `--fail-on-regression` returns a non-zero exit after printing the report if errors increased or new error patterns appeared
+- **Regression gates** — `--fail-on-regression` returns a non-zero exit after printing the report if errors increased or new error patterns appeared; the duration and memory threshold flags also return non-zero when their configured gates are exceeded
 - **Duration stats** — min, avg, p50, p90, max (in milliseconds), ignoring malformed values with an explicit ignored count
 - **Memory usage** — min, avg, max peak memory (in MB), ignoring malformed values with an explicit ignored count
-- **Log pattern diff** — new and gone log line patterns (UUIDs normalized)
+- **Log pattern diff** — new and gone log line patterns, normalizing request-specific values such as UUIDs, request IDs, timestamps, ARNs, long numeric IDs, and durations
+- **JSON output** — `--json` emits counts, pattern diffs, metric stats, warnings, and regression reasons for CI consumers
 - **Snapshot mismatch warnings** — warns when the two files appear to be from different Lambda functions or log groups; `--strict` also fails when snapshot identity fields are missing
 
+### `selfupdate`
+
+Checks the latest GitHub release, downloads the matching binary and `.sha256` checksum for the current OS/architecture, verifies the checksum, and replaces the running executable when a newer release is available.
+
+```
+lambda-deploy-log-compare selfupdate
+```
+
+### `version`
+
+Prints the current build version and exits. Release builds can set this with `-ldflags "-X main.appVersion=v1.2.3"`.
+
+```
+lambda-deploy-log-compare version
+```
+
 ## Snapshot Format
 
 Each snapshot file contains one `Snapshot` object with metadata plus an `invocations` array.
@@ -104,6 +131,7 @@ Important field notes:
 - `max_memory_used_mb` stores Lambda `Max Memory Used`, which is the value used for memory comparison stats and `peak_mem` in compare output.
 - Invocations that never emit a `REPORT` line are still captured, with blank duration and memory fields, so crashes and truncated runs are not silently dropped.
 - Older snapshots that used `mem_used_mb` and `max_mem_mb` still load correctly.
+- Compare rejects files that have neither snapshot metadata nor invocation records, so unrelated JSON is not treated as an empty snapshot.
 
 ## AWS Authentication
 
@@ -117,10 +145,10 @@ The IAM principal needs these permissions:
 ## How It Works
 
 1. **Stream discovery** — Fetches recent log streams ordered by last event time (most recent first) page by page until the requested `offset + count` is satisfied or the log group is exhausted.
-2. **Invocation parsing** — Reads each stream from newest events backward, tracks invocations from Lambda `START` and `REPORT` markers, and uses inline `RequestId` hints plus current stream context to associate log lines that land outside the normal `START -> logs -> REPORT` sequence. Extracts duration, billed duration, memory size, and max memory used from `REPORT` lines when present, while still preserving recent invocations that crashed or were truncated before `REPORT`. Each stream gets a 30-second timeout, and collection stops early once enough invocations are found.
+2. **Invocation parsing** — Reads each stream from newest events backward, tracks invocations from Lambda `START` and `REPORT` markers, and uses inline `RequestId` hints plus current stream context to associate log lines that land outside the normal `START -> logs -> REPORT` sequence. Extracts duration, billed duration, memory size, and max memory used from `REPORT` lines when present, while still preserving recent invocations that crashed or were truncated before `REPORT`. Each stream gets a 30-second timeout, collection stops early once enough newest invocations have their `START` boundary in the collected pages, and pages fetched before a later stream read failure are still used with a warning.
 3. **Error detection** — Flags explicit error-style log lines such as `error`, `panic`, `fatal`, `traceback`, `exception`, and Lambda runtime failure messages, while skipping common benign counter-style phrases like `error_count=0`.
 4. **Snapshot selection** — From all discovered invocations (sorted by time, most recent first), skips the first `offset` invocations, then takes the next `count`.
-5. **Pattern normalization** — For comparison, log lines are normalized by collapsing UUID-like hex strings (32+ chars) to `<UUID>` and truncating to 100 characters. This lets you compare structural patterns rather than exact values.
+5. **Pattern normalization** — For comparison, log lines are normalized by collapsing request-specific values such as UUID-like hex strings (32+ chars), Lambda request IDs, timestamps, ARNs, long numeric IDs, and durations before truncating to 100 characters. This lets you compare structural patterns rather than exact values.
 
 ## Project Structure
 

TODO.md

@@ -3,6 +3,7 @@ package main
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"os"
 	"path/filepath"
@@ -23,11 +24,19 @@ type LogsClient interface {
 
 const logEventsPageLimit int32 = 10_000
 
+type CaptureOptions struct {
+	Overwrite bool
+}
+
 func logGroupForFunction(name string) string {
 	return "/aws/lambda/" + name
 }
 
 func runCapture(client LogsClient, funcName, logGroup string, count, offset int, label, outDir string) error {
+	return runCaptureWithOptions(client, funcName, logGroup, count, offset, label, outDir, CaptureOptions{})
+}
+
+func runCaptureWithOptions(client LogsClient, funcName, logGroup string, count, offset int, label, outDir string, opts CaptureOptions) error {
 	if count <= 0 {
 		return fmt.Errorf("count must be greater than 0")
 	}
@@ -74,8 +83,11 @@ func runCapture(client LogsClient, funcName, logGroup string, count, offset int,
 			events, err := fetchLogEvents(evCtx, client, logGroup, *stream.LogStreamName, needed-len(allInvocations))
 			evCancel()
 			if err != nil {
-				fmt.Fprintf(stderr, "  Warning: failed to get events from stream %s: %v\n", *stream.LogStreamName, err)
-				continue
+				if len(events) == 0 {
+					fmt.Fprintf(stderr, "  Warning: failed to get events from stream %s: %v\n", *stream.LogStreamName, err)
+					continue
+				}
+				fmt.Fprintf(stderr, "  Warning: failed to get complete events from stream %s: %v; using %d event(s) fetched before the failure\n", *stream.LogStreamName, err, len(events))
 			}
 
 			invocations := parseInvocations(events)
@@ -126,14 +138,35 @@ func runCapture(client LogsClient, funcName, logGroup string, count, offset int,
 	if err := os.MkdirAll(outDir, 0755); err != nil {
 		return fmt.Errorf("create output directory: %w", err)
 	}
-	if err := os.WriteFile(outPath, data, 0644); err != nil {
+	if err := writeSnapshotOutputFile(outPath, data, opts.Overwrite); err != nil {
 		return fmt.Errorf("write snapshot: %w", err)
 	}
 
 	fmt.Fprintf(stdout, "  Wrote snapshot to %s (%d invocations)\n", outPath, len(records))
 	return nil
 }
 
+func writeSnapshotOutputFile(path string, data []byte, overwrite bool) error {
+	if overwrite {
+		return os.WriteFile(path, data, 0644)
+	}
+
+	file, err := os.OpenFile(path, os.O_WRONLY|os.O_CREATE|os.O_EXCL, 0644)
+	if err != nil {
+		if errors.Is(err, os.ErrExist) {
+			return fmt.Errorf("snapshot already exists at %s; use --overwrite to replace it", path)
+		}
+		return err
+	}
+
+	_, writeErr := file.Write(data)
+	closeErr := file.Close()
+	if writeErr != nil {
+		return writeErr
+	}
+	return closeErr
+}
+
 func fetchLogStreamPage(ctx context.Context, client LogsClient, logGroup string, limit int32, nextToken *string) ([]types.LogStream, *string, error) {
 	out, err := client.DescribeLogStreams(ctx, &cloudwatchlogs.DescribeLogStreamsInput{
 		LogGroupName: &logGroup,
@@ -181,7 +214,7 @@ func fetchLogEvents(ctx context.Context, client LogsClient, logGroup, streamName
 			eventPages = append(eventPages, pageEvents)
 			tracker.addPage(pageEvents)
 
-			if tracker.count() >= neededInvocations {
+			if tracker.hasCompleteNewest(neededInvocations) {
 				break
 			}
 		}
@@ -208,11 +241,17 @@ func flattenLogEventPages(pages [][]types.OutputLogEvent) []types.OutputLogEvent
 }
 
 type invocationCompletenessTracker struct {
-	seen map[string]struct{}
+	observations map[string]*invocationObservation
+}
+
+type invocationObservation struct {
+	requestID string
+	firstSeen time.Time
+	hasStart  bool
 }
 
 func newInvocationCompletenessTracker() *invocationCompletenessTracker {
-	return &invocationCompletenessTracker{seen: make(map[string]struct{})}
+	return &invocationCompletenessTracker{observations: make(map[string]*invocationObservation)}
 }
 
 func (t *invocationCompletenessTracker) addPage(events []types.OutputLogEvent) {
@@ -223,38 +262,80 @@ func (t *invocationCompletenessTracker) addPage(events []types.OutputLogEvent) {
 			continue
 		}
 		msg := strings.TrimSpace(*ev.Message)
+		ts := time.UnixMilli(*ev.Timestamp)
 
 		switch {
 		case strings.HasPrefix(msg, "START RequestId: "):
 			currentReqID = extractRequestID(msg, "START RequestId: ")
-			t.mark(currentReqID)
+			t.markStart(currentReqID, ts)
 
 		case strings.HasPrefix(msg, "END RequestId: "):
 			currentReqID = extractRequestID(msg, "END RequestId: ")
+			t.observe(currentReqID, ts)
 
 		case strings.HasPrefix(msg, "REPORT RequestId: "):
 			currentReqID = extractRequestID(msg, "REPORT RequestId: ")
-			t.mark(currentReqID)
+			t.observe(currentReqID, ts)
 
 		default:
 			if reqID := extractInlineRequestID(msg); reqID != "" {
-				t.mark(reqID)
+				t.observe(reqID, ts)
 				continue
 			}
-			t.mark(currentReqID)
+			t.observe(currentReqID, ts)
 		}
 	}
 }
 
-func (t *invocationCompletenessTracker) mark(reqID string) {
-	if reqID == "" {
+func (t *invocationCompletenessTracker) markStart(reqID string, ts time.Time) {
+	observation := t.observe(reqID, ts)
+	if observation == nil {
 		return
 	}
-	t.seen[reqID] = struct{}{}
+	observation.hasStart = true
 }
 
-func (t *invocationCompletenessTracker) count() int {
-	return len(t.seen)
+func (t *invocationCompletenessTracker) observe(reqID string, ts time.Time) *invocationObservation {
+	if reqID == "" {
+		return nil
+	}
+	observation, ok := t.observations[reqID]
+	if !ok {
+		observation = &invocationObservation{requestID: reqID, firstSeen: ts}
+		t.observations[reqID] = observation
+		return observation
+	}
+	if observation.firstSeen.IsZero() || ts.Before(observation.firstSeen) {
+		observation.firstSeen = ts
+	}
+	return observation
+}
+
+func (t *invocationCompletenessTracker) hasCompleteNewest(needed int) bool {
+	if needed <= 0 {
+		needed = 1
+	}
+	if len(t.observations) < needed {
+		return false
+	}
+
+	observations := make([]*invocationObservation, 0, len(t.observations))
+	for _, observation := range t.observations {
+		observations = append(observations, observation)
+	}
+	sort.SliceStable(observations, func(i, j int) bool {
+		if observations[i].firstSeen.Equal(observations[j].firstSeen) {
+			return observations[i].requestID < observations[j].requestID
+		}
+		return observations[i].firstSeen.After(observations[j].firstSeen)
+	})
+
+	for i := 0; i < needed; i++ {
+		if !observations[i].hasStart {
+			return false
+		}
+	}
+	return true
 }
 
 func reverseLogEvents(events []types.OutputLogEvent) {