Skip to content

Adder benchmarks and local profiling

This guide covers the streaming and backpressure benchmark for the Adder pipeline and the local workflow for collecting CPU, memory, and scheduler profiles. The benchmark uses synthetic input buffers and output behavior to compare pipeline behavior.

Run all commands from the repository root.

Run the event flow, Cardano filter, and event JSON benchmarks:

Terminal window
go test ./pipeline ./filter/cardano ./event -run '^$' -bench 'Benchmark(PipelineEventFlow|CardanoFilter|EventJSON)' -benchmem -benchtime=1s -count=5

The command runs three representative workloads:

  • BenchmarkPipelineEventFlow sends one event at a time through a running pipeline with zero, one, or three pass-through filters and one output. The producer waits for each event to reach the output, and the benchmark starts and stops the plugin outside the timed section. This workload models a single producer without downstream backpressure; it does not measure peak throughput with concurrent inputs.
  • BenchmarkCardanoFilter measures matching and nonmatching address and asset filters on a transaction with one output and one resolved input, plus matching and nonmatching pool filters on a block. The benchmark constructs the fixtures and configuration outside the timed section and calls the same filtering function that the plugin event loop calls.
  • BenchmarkEventJSON measures transaction event JSON marshaling and unmarshaling separately. The event includes transaction context, a block hash, a fee, a withdrawal, and CBOR bytes. The workload does not include a full decoded ledger transaction. Unmarshaling into Event leaves any fields as generic JSON values, as in a normal round trip.

Compare runs on the same machine with the same Go version and workload. Reported allocations and timings describe these workloads only; they do not identify a production bottleneck or guarantee production throughput.

Execute the following loop to compare the three input buffer capacities in a balanced order:

Terminal window
for order in 0 1 2 2 1 0; do
GOMAXPROCS=2 ADDER_BENCH_ORDER="$order" GOWORK=off go test ./pipeline -run '^$' -bench '^BenchmarkPipelineStreaming$' -benchmem -benchtime=200ms -count=1 -v
done

BenchmarkPipelineStreaming compares synthetic input buffers with capacities of 10, 256, and 2,048 event slots. The ADDER_BENCH_ORDER value controls the case order. The loop runs the three orders twice, and -v prints each order with its raw timings.

The benchmark compares these synthetic output modes for each buffer case:

  • fast_output drains continuously.
  • periodic_output_pause pauses for 100 microseconds after every 64 events to model intermittent sink backpressure.

Each operation sends and drains 4,096 block event envelopes. The benchmark reports events per second, time per operation, and allocations per 4,096-event operation. Startup and shutdown occur outside the timed section.

For streaming cases, the six runs in the command balance the three buffer orders. Compare both events per second and allocations, rather than using producer completion time alone as a measure of end to end delivery.

The benchmark does not include the following production concerns:

  • A Cardano node or network output
  • Decoding data or applying filters
  • Serializing output
  • Allocating payloads
  • Real sink latency

The pause schedule is synthetic and does not measure sink latency. Because channel creation occurs outside the timer, B/op does not include the buffer’s storage.

Larger buffers can absorb a burst, but they retain more queued events and referenced payloads while a sink falls behind. A larger buffer does not increase the capacity of a persistently slow sink. These cases isolate that tradeoff; they do not identify an optimal setting for a particular node, network, event mix, or output. Keep the runtime defaults until measurements from the intended workload justify a change.

Use a private temporary directory because profiles can contain application data and paths. Capture each profile separately so one profiler does not distort another:

Terminal window
profile_dir=$(mktemp -d)
GOWORK=off go test ./pipeline -run '^$' -bench '^BenchmarkPipelineStreaming/buffer_2048/fast_output$' -benchtime=1s -count=1 -cpuprofile="$profile_dir/cpu.out"
go tool pprof -top "$profile_dir/cpu.out"
GOWORK=off go test ./pipeline -run '^$' -bench '^BenchmarkPipelineStreaming/buffer_2048/fast_output$' -benchtime=200ms -count=1 -memprofile="$profile_dir/mem.out"
go tool pprof -alloc_space -top "$profile_dir/mem.out"
GOWORK=off go test ./pipeline -run '^$' -bench '^BenchmarkPipelineStreaming/buffer_2048/fast_output$' -benchtime=200ms -count=1 -trace="$profile_dir/trace.out"
go tool trace -pprof=sched "$profile_dir/trace.out" > "$profile_dir/sched.pprof"
go tool pprof -top "$profile_dir/sched.pprof"

The profiles provide these views:

  • The CPU profile samples active CPU work.
  • alloc_space reports cumulative allocations, not retained heap. Use -inuse_space to inspect retained heap at the capture point.
  • The memory profile includes process startup and benchmark setup.
  • The scheduler profile highlights runnable delays.

A short run can produce too few samples. Increase -benchtime only when the machine has capacity. This synthetic channel workload can be dominated by Go runtime scheduling and does not identify a bottleneck in a real Adder deployment. Collect multiple unprofiled runs and compare events per second with B/op.

Profile instrumentation changes timings. Do not use profiled runs as the throughput baseline.

Adder disables its debug listener by default and does not register HTTP pprof handlers. The commands in this guide use Go’s test profiler and open no network listener. Do not expose a profiling listener on a public interface; use this private local workflow instead of an HTTP pprof or goroutine leak listener workflow.


Doc Holiday logo

Docs authored by Doc Holiday