Skip to content

docs(bench): add repo allocation micro-benchmarks and remove non-technical docs #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SShogun merged 1 commit into from
Oct 20, 2026
Merged

docs(bench): add repo allocation micro-benchmarks and remove non-technical docs #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,24 @@ make down

The tests use `testcontainers-go` where Redis behavior matters. Handler integration tests run against a pinned Redis Stack image, while Streams recovery tests run against a pinned Redis image and prove group bootstrap replay, cursor-complete stale claiming, and ACK-failure handling. Producer tests also prove create/update/delete action emission and synchronous append error propagation.

## Performance & Allocation Profile

### 1. Repository Orchestration & Concurrency Micro-Benchmarks
Measured via `go test -run=^$ -bench=. -benchmem -cpu=1,4,8 ./internal/repo` on Linux `amd64` (13th Gen Intel Core i5-13450HX). Isolates the Go cache-aside state machine, lock contention, and heap allocation overhead from network TCP latency:

| Benchmark Path | Cores (`GOMAXPROCS`) | Latency (`ns/op`) | Throughput (In-Process) | Bytes / Op | Heap Allocs / Op |
| :--- | :---: | :---: | :---: | :---: | :---: |
| **Cache Hit (`GetByID_CacheHit`)** | 8 | `36.98 ns/op` | ~27.0M ops/sec | `0 B/op` | `0 allocs/op` |
| **Parallel Contention (`GetByID_Contention`)** | 8 | `42.99 ns/op` | ~23.3M ops/sec | `0 B/op` | `0 allocs/op` |
| **Cache Miss Fast-Path (`GetByID_CacheMiss`)** | 8 | `73.99 ns/op` | ~13.5M ops/sec | `0 B/op` | `0 allocs/op` |

@sourcery-ai sourcery-ai Bot Oct 20, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Medium · Cache miss work mislabeled

When readers compare the reported row as a fast-path result, BenchmarkCacheItemRepo_GetByID_CacheMiss gets a cache miss on every iteration, then runs the fallback and attempts a cache backfill. Its result therefore includes that work, not a cache-miss fast path.

Rename the row to describe the fallback and backfill work, or change the benchmark to measure an actual fast path.

Prompt for AI agents 
In `README.md` at line 205:

**Cache miss work mislabeled**

When readers compare the reported row as a fast-path result, `BenchmarkCacheItemRepo_GetByID_CacheMiss` gets a cache miss on every iteration, then runs the fallback and attempts a cache backfill. Its result therefore includes that work, not a cache-miss fast path.

Rename the row to describe the fallback and backfill work, or change the benchmark to measure an actual fast path.

| **Cold Miss + Cache Backfill (`GetByID_BackfillPath`)** | 8 | `418.90 ns/op` | ~2.39M ops/sec | `352 B/op` | `2 allocs/op` |

*Key Takeaway:* Hot-path cache lookups and parallel read contention execute with **zero heap allocations (`0 B/op`, `0 allocs/op`)**, eliminating Go garbage collector (GC) pressure during read spikes. Heap allocations (`352 B/op`, `2 allocs/op`) are strictly confined to cold cache-miss backfill writes.

### 2. End-to-End Multi-Module Verification Harness
Full integration verification across live Redis Stack containers (`RedisJSON`, `RediSearch`, `RedisBloom`, and `Redis Streams` consumer-group recovery via `testcontainers-go`):
* **Verification Suite:** `752 composite multi-module transactions | 0 failed | 100% stream recovery on worker crash`

## Development Rhythm

This repo is intended to grow in public. Good future commits are small, reviewable, and educational:
Expand Down
96 changes: 0 additions & 96 deletions docs/social_templates.md
View file
Open in desktop

This file was deleted.

Loading