Skip to content

project-requirements.adoc

Latest commit

 

History

History
121 lines (106 loc) · 6.25 KB

project-requirements.adoc

File metadata and controls

121 lines (106 loc) · 6.25 KB
Raw

Chronicle Logger Requirements Catalogue

Table of Contents

Scope

Chronicle Logger provides Chronicle Queue backed appenders, bridges, and tools for popular Java logging frameworks (SLF4J 1.x and 2.x, Logback, Log4J 1/2, Commons Logging, JUL). SLF4J 2.x is the default API; SLF4J 1.x remains supported via the legacy binding and explicit bridges (for example slf4j-reload4j for Log4J 1.x). Mixing API/provider versions is unsupported and must be prevented in tests and documentation. The requirements below define the contracts, quality targets, and operational obligations that all modules must meet.

Functional Requirements

ID Requirement Verification

CLG-FN-001

ChronicleLogWriter shall persist log events with timestamp, level, thread name, logger name, message pattern, throwable, and arguments without allocating on the steady-state hot path.

Unit tests assert field round trip via ChronicleLogReader; allocation profiler runs in CI on representative workloads.

CLG-FN-002

ChronicleLogManager shall load configuration from the system property chronicle.logger.properties or the documented class-path defaults, supporting per-logger overrides for path, level, wire type, and append mode.

Integration tests supply temp properties files and validate resolved settings per logger.

CLG-FN-003

Each binding (SLF4J 1.x, SLF4J 2.x, JUL, JCL, Logback, Log4J 1, Log4J 2) shall honour its native configuration entry points while delegating writes through ChronicleLogWriter. Legacy SLF4J call sites shall be serviceable via documented bridges while logger-slf4j-2 remains the default provider.

Framework-specific tests assert that configuration files enable Chronicle appenders and produce Chronicle Queue output; bridge tests assert SLF4J callers still reach Chronicle appenders.

CLG-FN-004

Logger tools (ChroniCat, ChroniTail, ChronicleLogReader) shall read binary Chronicle logs, display tail output, and stream entries to custom processors without data loss.

CLI smoke tests replay fixture queues; unit tests verify processor callbacks receive ordered entries.

CLG-FN-005

Benchmark module shall provide repeatable JMH suites covering append throughput and tail latency for key bindings with configurable message sizes.

CI benchmark job executes weekly and publishes trend reports; spot checks confirm no regressions before releases.

Non-Functional Requirements - Performance

ID Requirement Benchmark Target

CLG-NF-P-001

Steady-state append of INFO level messages through SLF4J 1.x binding shall achieve >= 1.2 million events per second on a 3.2 GHz x86-64 host with Chronicle Queue BINARY_LIGHT.

JMH Throughput benchmark in benchmark module; flagged if throughput drops by > 10 percent relative to baseline.

CLG-NF-P-002

Tail latency (99.9 percentile) for append operations with async queue roll shall remain ⇐ 750 µs under mixed INFO/WARN traffic.

Benchmark module scenario combining timed roll cycle and mixed levels.

CLG-NF-P-003

ChronicleLogReader shall consume existing queues at >= 500k events per second while remaining allocation-neutral.

Micro benchmark comparing reader performance to baseline sample queues.

Non-Functional Requirements - Security and Operability

ID Requirement Verification

CLG-NF-S-001

Bindings must never execute formatted message strings with user input on configuration load; only explicit properties may influence Chronicle Queue paths.

Static audit of configuration paths; integration tests confirm user message content is not evaluated.

CLG-NF-O-001

All modules must support JDK 8 through the current LTS release, with automated builds running mvn -q verify on each supported JDK.

CI matrix build status; release checklist captures JDK versions.

CLG-NF-O-002

Components shall emit operational warnings via standard logging channels when Chronicle Queue paths are missing or unwritable, and fail fast rather than silently downgrading.

Negative-path tests create read-only directories and assert warning plus exception semantics.

CLG-NF-O-003

Configuration reload shall be thread-safe: calling ChronicleLogManager.reload() must close and recreate writers without leaking resources.

Unit tests validate path switches and writer closure; stress tests exercise concurrent reloads with leak detectors enabled.

Test Obligations

ID Requirement

CLG-TEST-001

Maintain >= 80 percent line coverage for logger-core and each binding package, excluding generated or vendor code. Jacoco gate enforced in CI.

CLG-TEST-002

Provide regression fixtures per binding that append structured events (with throwable and argument arrays) and replay them via ChronicleLogReader to assert schema compatibility.

CLG-TEST-003

Nightly build runs mvn -q verify and the benchmark smoke profile, failing the pipeline if throughput or latency deviates beyond documented thresholds.

Documentation and Operational Obligations

ID Requirement

CLG-DOC-001

Keep architecture-overview.adoc aligned with current module structure, configuration flow, and decision references.

CLG-DOC-002

Update this requirements catalogue and cross-link new entries when decisions in decision-log.adoc change behaviour or support matrices.

CLG-OPS-001

Publish a run-book section describing log directory hygiene, retention, and recovery steps; ensure tools document command-line flags.