History歷史趨勢
Live charts from Bencher: p50 wall clock per iteration on the main branch, ubuntu-24.04 testbed, log scale. The workflow moved to that image on 2026-10-26; earlier runs stay on the ubuntu-latest testbed in Bencher. Click a chart to open the interactive view with allocation counts and per-commit details.
來自 Bencher 的即時圖表：main 分支在 ubuntu-24.04 testbed 上每次迭代的 p50 wall clock，對數軸。workflow 在 2026-10-26 改用這個 image，之前的執行仍留在 Bencher 的 ubuntu-latest testbed。點擊圖表可開啟互動頁面，查看記憶體配置次數與每個 commit 的細節。
Results量測結果
p50 is the median wall clock per iteration; Malloc the heap allocations per iteration; Instructions the CPU instructions per iteration (macOS only: Linux needs perf_event, which GitHub runners do not expose). Lower is better everywhere. On Linux the benchmark runtime interposer adds a fixed floor of 16 allocations to every benchmark, so a zero-allocation benchmark reports 16 there.
p50 是每次迭代 wall clock 的中位數；Malloc 是每次迭代的堆積配置次數；Instructions 是每次迭代的 CPU 指令數（僅 macOS：Linux 需要 perf_event，GitHub runner 不開放）。所有數字都是越低越好。Linux 上 benchmark runtime 的 interposer 會對每個 benchmark 固定多算 16 次配置，所以零配置的 benchmark 在 Linux 會顯示 16。
EventData
- Creating a raw
EventData from Data costs about 1.2 µs on macOS with 1 allocation (the internal Data copy).
- A
Codable model adds 1 allocation to box the model; encoding is deferred until .data is read, so construction cost is almost the same as the raw case.
encode-codable-payload is the full JSONEncoder().encode() path and the hot path when serialising events to the wire.EventData construction is about 3× slower on Linux for one event and 4.5–6.5× for a batch of 100. Allocation counts match, so this is the cost of swift-foundation's Data and UUID on that runner, not extra work in the SDK.
- 從
Data 建立 EventData 在 macOS 約 1.2 µs、1 次配置（內部的 Data 複製）。
- 用
Codable model 多 1 次配置來裝箱 model；編碼延後到讀取 .data 時才發生，所以建構成本跟 raw 幾乎相同。
encode-codable-payload 是完整的 JSONEncoder().encode() 路徑，也是事件送上線路時的熱路徑。EventData 建構在 Linux 上，單筆慢約 3 倍，100 筆的批次慢 4.5–6.5 倍。配置次數一致，所以差在該 runner 上 swift-foundation 的 Data 與 UUID，不是 SDK 多做了事。
Connection string parsing連線字串解析
- The strict RFC 3986 parser (PR #160) parses a single-node connection string in about 9 µs with 11 allocations on macOS. The parser measured on 2026-09-28 took about 400 µs and 1,240 allocations for the same string.
- Three seeds cost about twice as much as one node.
- Parse once at startup and reuse the
ClientSettings; there is no reason to parse in a hot path.
- 嚴格依 RFC 3986 的 parser（PR #160）解析單一節點的連線字串，在 macOS 約 9 µs、11 次配置。2026-09-28 量到的舊 parser，同一個字串要約 400 µs、1,240 次配置。
- 三個 seed 的成本約是單一節點的兩倍。
- 啟動時解析一次並重用
ClientSettings，沒有理由在熱路徑上解析。
Append request encodingAppend 請求編碼
Append/encode-request/<events>x<payload> builds the request messages of one append (requestMessages()) and serialises each to bytes, as the gRPC serializer does before writing them to the stream. The events carry raw Data payloads, so JSON encoding is not included.
Append/encode-request/<筆數>x<payload> 建出一次 append 的請求訊息（requestMessages()），再把每則序列化成 bytes，跟 gRPC serializer 寫進 stream 前做的事一樣。事件用的是原始 Data payload，所以不含 JSON 編碼。
- Each event costs about 0.9 µs and 2 allocations on macOS (about 1.2 µs on Linux), plus a fixed 4 allocations per request (6 on Linux, after the floor of 16).
- Payload size changes the time, not the allocations: copying a 64 KB payload into the serialised message adds about 1.3 µs per event on macOS (0.9 µs on Linux).
- For
Codable models add EventData/encode-codable-payload per event: JSON encoding costs about four times as much as the protobuf encoding around it.
- 每筆事件在 macOS 約 0.9 µs、2 次配置（Linux 約 1.2 µs），每個請求另有固定 4 次配置（Linux 扣掉 16 次底數後是 6 次）。
- payload 大小只影響時間、不影響配置次數：把 64 KB 的 payload 複製進序列化後的訊息，每筆在 macOS 多約 1.3 µs（Linux 0.9 µs）。
- 用
Codable model 的話，每筆再加上 EventData/encode-codable-payload：JSON 編碼的成本約是外層 protobuf 編碼的四倍。
Read response decoding讀取回應解碼
Read/decode-response/<events>x<payload> parses one serialised ReadResp per event, as the server streams them, and turns each into a Streams.ReadResponse. Read/decode-model/<events> then decodes the RecordedEvents of such a read into a three-field Codable struct with decode(to:).
Read/decode-response/<筆數>x<payload> 依 server 串流的方式，每筆事件解析一則序列化的 ReadResp，再轉成 Streams.ReadResponse。Read/decode-model/<筆數> 接著用 decode(to:) 把這些 RecordedEvent 解碼成三個欄位的 Codable struct。
- Decoding a response costs about 3.2 µs and 9 allocations per event on macOS (3.0 µs and 11 allocations on Linux): 2.4–3.6× the time and 4.5–5.5× the allocations of encoding an event for an append.
- Payload size again changes only the time: 64 KB adds about 2.4 µs per event on macOS (2.0 µs on Linux).
decode(to:) adds about 2.4 µs and 12 allocations per event on macOS (1.8 µs on Linux).- Rebuilding an aggregate from 1,000 small events therefore costs about 5.6 ms of client CPU on macOS and 4.8 ms on Linux. HTTP/2 framing and the per-element cost of the response sequence come on top; the client-stack benchmarks below measure the latter.
- 解碼一則回應，每筆在 macOS 約 3.2 µs、9 次配置（Linux 3.0 µs、11 次）：時間是 append 編碼一筆的 2.4–3.6 倍，配置次數是 4.5–5.5 倍。
- payload 大小同樣只影響時間：64 KB 每筆在 macOS 多約 2.4 µs（Linux 2.0 µs）。
decode(to:) 每筆在 macOS 再加約 2.4 µs、12 次配置（Linux 1.8 µs）。- 所以從 1,000 筆小事件重建一個 aggregate，客戶端 CPU 在 macOS 約 5.6 ms、Linux 約 4.8 ms。HTTP/2 framing 與回應序列每筆的成本另計；後者由下面的 client stack benchmark 量測。
Client stack against an in-process serverClient stack（接 in-process server）
Client/* runs a real KurrentDBClient against an in-process server (Benchmarks/OfflineBenchmarks/InProcessServer.swift), plugged in through the package-level ClientSettings.transportProvider. Node selection, the retry wrapper, the shared connection, the generated gRPC client and the response sequences run as they do against a node. The server answers from responses serialised in advance and never parses a request, but like a node it takes each request whole before answering, and it fails a call whose request does not carry the expected number of messages. There are no sockets and no HTTP/2 framing, so what is left is the cost of the client and of grpc-swift. GRPC/* makes the same calls with the generated gRPC client alone, on the same kind of connection behind the same AnyClientTransport: Client/* minus GRPC/* is what the SDK adds above that transport, whose own forwarding both include; it forwards nothing per message. Both also include one copy of every message, each way, between the in-process transport's [UInt8] and the Posix transport's bytes type, which a real connection does not make. Measured on 2026-10-26 on the code of PR #182: macOS in two runs with the same allocation counts and p50s at most 9.4% apart (the second run against the first; the tables show the first); Linux in run 40282079929 (AMD EPYC 7763, 4 vCPU, Ubuntu 26.04).
Client/* 用真的 KurrentDBClient 接 in-process server（Benchmarks/OfflineBenchmarks/InProcessServer.swift），透過 package 層級的 ClientSettings.transportProvider 接上。node 選擇、retry、共用連線、生成的 gRPC client 與回應序列都跟接真 node 時一樣在跑。server 用事先序列化好的回應作答，從不解析請求，但會像真 node 一樣先收完整個請求再回應，請求的訊息數不對就讓呼叫失敗；沒有 socket、也沒有 HTTP/2 framing，所以剩下的就是 client 與 grpc-swift 本身的成本。GRPC/* 在同樣的連線、同樣的 AnyClientTransport 後面，只用生成的 gRPC client 做同樣的呼叫：Client/* 減掉 GRPC/* 就是 SDK 在這個 transport 之上多出來的部分，transport 本身的轉發兩邊都有，而且每則訊息不會另外轉發。兩者也都包含每則訊息在 in-process transport 的 [UInt8] 與 Posix transport 的 bytes 型別之間來回各複製一次，這是真連線不會有的。量測於 2026-10-26，使用 PR #182 的程式碼：macOS 跑了兩次，配置次數相同、p50 最多相差 9.4%（第二次對第一次；表中是第一次）；Linux 為 run 40282079929（AMD EPYC 7763, 4 vCPU, Ubuntu 26.04）。
Two things these numbers do not show. Memory: the in-process transport queues messages without a limit, so the server can run ahead of a slow reader; against a node, the HTTP/2 flow-control window limits how far it can. The server's share of a deadline: requests reach the in-process server without their grpc-timeout header, so only the client's timer runs; a node runs its own on its own machine. Dropping the header copies the request metadata of a call with a deadline, which a real connection does not do.
這些數字不包含兩件事。記憶體：in-process transport 的佇列沒有上限，server 可以跑在讀得慢的一方前面；接真 node 時，HTTP/2 的 flow-control window 會限制 server 能超前多少。deadline 在 server 端的成本：請求送到 in-process server 時已拿掉 grpc-timeout header，所以只有 client 的計時 task 在跑；真 node 的計時在它自己的機器上。拿掉 header 會複製一次有 deadline 的呼叫的請求 metadata，這是真連線不會做的。
- Most of a one-event call is grpc-swift's: a one-event append takes 58 µs through the client and 52 µs with gRPC alone on macOS (142 µs and 123 µs on Linux). The SDK's per-call work adds 12 allocations to it (17 on Linux) and 22 to a one-event read (29). These are totals for one event; each further event adds its own share.
- Each further appended event costs about 2.4–2.6 µs and 10 allocations through the client on macOS, and about 2.3–2.4 µs and 9 with gRPC alone: the SDK adds 1 allocation per event on both systems, and on macOS a time within run-to-run noise.
- Each event of a buffered read costs about 6.5–6.6 µs and 15 allocations on macOS. gRPC alone costs about 4.6–4.9 µs and 14: protobuf decoding plus the in-process transport and its copy. The SDK adds about 1.6–2.0 µs and 1 allocation (about 4.0 µs and 1 on Linux).
- A lazy read costs about 2.6–2.7 µs and 2 allocations more per event than a buffered one on macOS: each element waits in the hand-off for the iterating task. That is the price of handing over one element at a time. On Linux the hand-off is the most scheduling-sensitive number: about 14 µs per event in this run, about 16 µs in run 40279300762 on an Intel Xeon Platinum 8573C.
- A default deadline adds about 12–13 µs and 19 allocations to a call on macOS (about 66 µs and 19 on Linux): grpc-swift runs every call it bounds in a task group next to a timer task. No server timer is in these numbers, since the in-process server never sees the deadline; the copy of the request metadata that the in-process connection makes to drop the header is.
- These benchmarks allocate on several concurrent tasks, so their counts depend on scheduling. On the 4-vCPU Linux runner a lazy read's count per iteration spreads over 10–11% in the runs above (each element either finds the consumer waiting or suspends in the hand-off), so its Linux Malloc is a median of two modes. Bencher records them without a threshold (see Method).
- 一筆的呼叫，成本大多來自 grpc-swift：在 macOS 上，append 一筆經過 client 要 58 µs，只用 gRPC 要 52 µs（Linux 為 142 µs 與 123 µs）。SDK 每次呼叫的工作讓這次 append 多 12 次配置（Linux 17 次），讓 read 一筆多 22 次（Linux 29 次）。這是一筆的總數，每多一筆還要再加上那一筆的成本。
- append 每多一筆，經過 client 在 macOS 約 2.4–2.6 µs、10 次配置，只用 gRPC 約 2.3–2.4 µs、9 次：兩個系統上 SDK 每筆都多 1 次配置；時間差在 macOS 上落在兩次執行之間的浮動以內。
- buffered read 每筆在 macOS 約 6.5–6.6 µs、15 次配置；只用 gRPC 約 4.6–4.9 µs、14 次：protobuf 解碼加上 in-process transport 與它的複製。SDK 每筆多約 1.6–2.0 µs、1 次配置（Linux 約 4.0 µs、1 次）。
- lazy read 每筆在 macOS 比 buffered 多約 2.6–2.7 µs、2 次配置：每個元素都要在 hand-off 等迭代的 task 來拿，這是一次只交出一個元素的代價。在 Linux 上，hand-off 是最受排程影響的數字：這次每筆約 14 µs，run 40279300762 在 Intel Xeon Platinum 8573C 上約 16 µs。
- 預設 deadline 在 macOS 讓每次呼叫多約 12–13 µs、19 次配置（Linux 約 66 µs、19 次）：grpc-swift 會把每個有期限的呼叫放進 task group，旁邊再跑一個計時用的 task。in-process server 看不到 deadline，所以這些數字不含 server 的計時；但 in-process 連線為了拿掉 header 而複製的請求 metadata 算在裡面。
- 這些 benchmark 在多個並行的 task 上配置記憶體，配置次數取決於排程。在 4 vCPU 的 Linux runner 上，lazy read 每次迭代的配置次數在上面幾次執行裡分散 10–11%（每個元素要嘛碰到 consumer 已在等，要嘛在 hand-off 裡暫停），所以 Linux 的 Malloc 是兩群數值的中位數。Bencher 只記錄、不設門檻（見量測方法）。
Method量測方法
The suite is Benchmarks/OfflineBenchmarks, built with ordo-one/benchmark in release mode. The Benchmarks workflow runs it on ubuntu-24.04 on every push to main, publishes the markdown report to the job summary, and uploads two measures per benchmark to Bencher: latency (p50 wall clock in ns, bounds p0/p90) and the p50 malloc count, as allocations or, for the client-stack benchmarks, allocations-concurrent. On a push to main two thresholds can fail the run: a t-test on latency (upper boundary 0.99 over the last 64 runs, once a benchmark has 10) when the result lands outside the band of recent history, and a percentage test on allocations (upper boundary 1% against the previous run) when the count grows by more than 1%. Allocation counts are deterministic for a given toolchain and runner image, so growth comes from a code change, a new Swift patch release or a new runner image; each alerts once, and the next run compares against the new count. The client-stack benchmarks are the exception: they allocate on several concurrent tasks, and on the 4-vCPU runner a lazy read's count per iteration spreads over about 10%, so allocations-concurrent keeps their history without a threshold and the latency test covers them.
套件是 Benchmarks/OfflineBenchmarks，用 ordo-one/benchmark 以 release 模式建置。Benchmarks workflow 每次 push 到 main 就在 ubuntu-24.04 執行，把 markdown 報表寫進 job summary，並對每個 benchmark 上傳兩個 measure 到 Bencher：latency（p50 wall clock，單位 ns，區間 p0/p90）與 p50 配置次數；配置次數一般記為 allocations，client stack 的 benchmark 記為 allocations-concurrent。push 到 main 時有兩個門檻會讓執行失敗：latency 上的 t-test（最近 64 次、上界 0.99，累積滿 10 次才開始）在結果落在歷史區間外時觸發；allocations 上的 percentage 門檻（對前一次、上界 1%）在配置次數增加超過 1% 時觸發。同一套 toolchain 與 runner image 上的配置次數是固定的，所以增加只會來自程式碼變更、新的 Swift patch 版本或新的 runner image；每種情況只會觸發一次，下一次執行就以新的次數為基準。client stack 的 benchmark 是例外：它們在多個並行的 task 上配置記憶體，在 4 vCPU 的 runner 上 lazy read 每次迭代的配置次數分散約 10%，所以 allocations-concurrent 只保留歷史、不設門檻，由 latency 的門檻把關。
How to run the suite locally on macOS or Linux, filter benchmarks and compare baselines: BENCHMARKS.md.
在 macOS 或 Linux 本機執行、篩選 benchmark 與比較 baseline 的步驟見 BENCHMARKS.md。