Skip to content

project-requirements.adoc

Latest commit

 

History

History
198 lines (146 loc) · 9.75 KB

project-requirements.adoc

File metadata and controls

198 lines (146 loc) · 9.75 KB
Raw

Chronicle JLBH - Software Requirements Specification

Table of Contents
Abstract

Chronicle JLBH is an open-source Java library, released under the Apache Licence 2.0, that provides a high-resolution latency benchmark harness. It allows developers to measure, analyse and regress-test latency behaviour of critical code paths "in context" rather than via isolated micro-benchmarks. Key features include compensation for co-ordinated omission, configurable throughput modelling, additional probes, optional operating-system jitter tracking, and serialisation of results for CI dashboards.

1. Introduction

1.1 Purpose

This document specifies functional and non-functional requirements for Chronicle JLBH, ensuring that contributors and integrators share a common understanding of the product’s goals and constraints.

1.2 Scope

The harness targets low-latency Java applications (trading systems, micro-services, real-time analytics) that must quantify latencies at extreme percentiles under realistic load patterns.

1.3 Definitions, Acronyms and Abbreviations

Term Definition

JLBH

Java Latency Benchmark Harness - the library under specification.

Co-ordinated Omission

Measurement error whereby pauses/back-pressure hide worst-case latencies.

Probe

A named histogram that records an additional timing within the benchmark workflow.

OS Jitter

Kernel or scheduler-induced timing variance measured by a background thread.

CI

Continuous Integration environment (e.g. GitHub Actions, TeamCity).

1.4 References

1.5 Overview

Sections 2-5 describe the product context, interfaces, detailed system features, and quality attributes. Section 6 captures licensing, whilst Section 7 presents the glossary.

2. Overall Description

2.1 Product Perspective

JLBH is delivered as a Maven artefact (net.openhft:jlbh) and depends on Chronicle Core for low-level utilities. It may be embedded in unit tests, standalone mains, or invoked as an EventLoop handler.

2.2 Product Functions

  • Generate high-resolution histograms (>=35 bits) of end-to-end sample latencies.

  • Optionally compensate for co-ordinated omission by adjusting the synthetic start time.

  • Model load via configurable throughput(int, TimeUnit) and *LatencyDistributor*s.

  • Provide additional named probes via addProbe(String).

  • Record OS-level jitter and present it as a separate probe.

  • Output run summaries to PrintStream and expose structured results via JLBHResult.

  • Serialise the final run to CSV (JLBHResultSerializer).

  • Integrate with CI (TeamCity helper emits ##teamcity statistics lines).

  • Allow execution from any thread or installation onto a Chronicle MediumEventLoop.

2.3 User Classes and Characteristics

Actor Description Technical Expertise

Performance Engineer

Designs latency benchmarks and analyses histograms.

Advanced Java & performance tuning.

Developer

Adds JLBH tests to codebase, evaluates pull-request regressions.

Intermediate Java.

CI System

Runs automated latency regression suite, ingests CSV or TeamCity stats.

N/A (automation).

2.4 Operating Environment

  • Java 11 LTS and later; Java 17 recommended for current builds.

  • Linux x86-64 (primary), other POSIX OSes supported; macOS usable but CI baselines exclude it.

  • Typical CPU affinity facilities available via OpenHFT Affinity library.

2.5 Design and Implementation Constraints

  • Single-threaded harness execution; benchmarked code may span threads.

  • Measurements rely on System.nanoTime() precision; hardware timers must be invariant.

  • JVM must be started with -XX:+UnlockDiagnosticVMOptions -XX:+DebugNonSafepoints when using async-profiler concurrently.

  • Library is released under the Apache Licence 2.0; contributions must comply with CLA policy.

2.6 Assumptions and Dependencies

  • SUT jars are available on the same JVM classpath.

  • Benchmark host clocks are monotonic and not subjected to aggressive power-saving states.

  • CI agents provision exclusive CPU cores to minimise jitter.

3. External Interface Requirements

3.1 Public API

  • JLBHOptions - builder for benchmark parameters (throughput, warm-up, runs, etc.).

  • JLBHTask - user-defined callback with lifecycle methods init, run, warmedUp, runComplete, complete.

  • JLBH - orchestrator class with start() and eventLoopHandler(EventLoop) entry points.

  • JLBHResult - immutable projection of measured data.

  • JLBHResultSerializer - CSV writer for analytics pipelines.

3.2 User Interface

CLI usage is demonstrated in ExampleJLBHMain and test fixtures; no dedicated GUI is provided.

3.3 Hardware Interfaces

None. The harness interacts with OS timers and CPU affinity via JNI where available.

3.4 Software Interfaces

  • Build tool: Apache Maven (pom.xml defines BOM imports).

  • Logging: SLF4J (test scope).

  • Testing: JUnit 4 for unit and integration tests.

  • CI Metrics: TeamCity service messages.

4. System Features

4.1 FN-001 Latency Sampling

Description: Collect nanosecond deltas from user code via sample(long) or sampleNanos(long). Stimulus/Response: Upon each iteration, JLBHTask.run calls jlbh.sample(…​); histogram updates occur; run summary printed at completion. Priority: Essential.

4.2 FN-002 Coordinated-Omission Compensation

Ensures that queue back-log does not under-represent tail latency. Enabled by default; opt-out via accountForCoordinatedOmission(false).

4.3 FN-003 Additional Probes

Developers may time sub-stages (e.g., serialisation, network round-trip) through addProbe(String) and record them independently.

4.4 FN-004 OS Jitter Tracking

A background thread measures scheduling gaps exceeding a configured threshold (recordJitterGreaterThanNs). Monitoring is enabled by default and can be disabled via recordOSJitter(false). Results are summarised alongside core latencies.

4.5 FN-005 CSV Serialisation

Post-run, results can be persisted for offline analysis (result.csv by default).

4.6 FN-006 Event Loop Integration

eventLoopHandler(EventLoop) allows benchmarks to operate inside Chronicle threading framework, avoiding extra threads.

5. Non-Functional Requirements

5.1 NF-P-001 Performance

  • Overhead per sample must remain below 100 ns when no additional probes are active.

  • Histogram generation must support >=200 M iterations without heap pressure.

5.2 NF-R-001 Reliability

  • Harness must abort gracefully on thread interruptions or sample time-outs (timeout(long)).

  • Immutable result objects ensure thread-safe publication to external consumers.

5.3 NF-UX-001 Usability

  • Fluent builder API; sensible defaults provide a runnable benchmark in ≤10 LOC.

  • ASCII table outputs are human-readable and CI-friendly.

5.4 NF-O-001 Portability

  • Pure-Java codebase; no native compilation steps.

  • JDK-specific optimisations (e.g., Zing support) are runtime-detected.

5.5 NF-O-002 Maintainability

  • 80 %+ unit-test line coverage with deterministic fixtures.

  • Code adheres to Chronicle parent POM style and SonarCloud quality gates.

5.6 NF-S-001 Security

No executable deserialisation; harness operates in-process. Users remain responsible for securing benchmarked code.

6. Licensing

The project is released under the Apache Licence 2.0 (see LICENSE.adoc). Downstream consumers must preserve licence notices and may include JLBH in commercial or OSS products, subject to the terms therein.

7. Glossary

Co-ordinated Omission

Statistical artefact causing under-reporting of worst-case latency.

Histogram

Data structure that records frequency counts in logarithmic buckets, enabling percentile extraction.

Percentile

Value below which a given percentage of observations fall (e.g., 99th percentile).

8. Appendix A - Example Minimal Benchmark

public class NothingBenchmark implements JLBHTask {
    private JLBH jlbh;
    public void init(JLBH jlbh) { this.jlbh = jlbh; }
    public void run(long startTimeNS) {
        jlbh.sample(System.nanoTime() - startTimeNS);
    }
    public static void main(String[] args) {
        new JLBH(new JLBHOptions()
                 .throughput(1_000_000)
                 .iterations(10_000)
                 .jlbhTask(new NothingBenchmark()))
                 .start();
    }
}

9. Appendix B - Footnotes