Skip to content

architecture-overview.adoc

Latest commit

 

History

History
59 lines (42 loc) · 4.07 KB

architecture-overview.adoc

File metadata and controls

59 lines (42 loc) · 4.07 KB
Raw

Chronicle Logger Architecture Overview

Table of Contents

Purpose

This overview summarises how Chronicle Logger modules collaborate to capture, persist, and inspect log events. It complements the requirement catalogue (CLG-FN-001 through CLG-NF-O-003) and the decision log, offering a shared picture for maintainers and operators.

Module Topology

The repository is split into focused modules that all depend on logger-core:

  • logger-core supplies ChronicleLogWriter, ChronicleLogManager, and configuration helpers (see CLG-FN-001).

  • Binding modules (logger-slf4j for SLF4J 1.7.x, logger-slf4j-2 for SLF4J 2.x ServiceProvider, logger-logback, logger-log4j-1, logger-log4j-2, logger-jcl, logger-jul) translate framework-specific APIs into Chronicle writes (CLG-FN-003).

  • logger-tools exposes reusable readers and CLI utilities (CLG-FN-004).

  • benchmark packages JMH scenarios that observe the performance envelopes (CLG-FN-005).

Configuration Flow

Configuration enters through properties or native framework settings:

  1. Properties loaded by ChronicleLogManager via system property chronicle.logger.properties or default class-path locations.

  2. Binding-specific configuration resolves logger names to queue paths, levels, and wire types.

  3. ChronicleLogManager caches writers per path; reload recreates queues safely (CLG-NF-O-003).

The design enforces explicit queue paths and fail-fast behaviour when storage is not writable (CLG-NF-O-002, CLG-OPS-002).

Chronicle Queue Write Path

  1. Framework binding receives a log call and checks the requested level against its cached minimum.

  2. For SLF4J 2.x, discovery is via SLF4JServiceProvider; SLF4J 1.x bindings expose StaticLoggerBinder. Legacy SLF4J callers can be bridged to Log4j1 via slf4j-reload4j and to Log4j2 via log4j-slf4j2-impl, keeping old code paths functional while defaulting new usage to logger-slf4j-2.

  3. When enabled, the binding forwards the event to ChronicleLogWriter, supplying timestamp, thread name, logger name, message pattern, optional throwable, and argument array (CLG-FN-001).

  4. ChronicleLogWriter serialises the data into a Chronicle Queue using the configured wire type, avoiding heap allocation on the hot path (CLG-NF-P-001).

Tailers and readers consume the queue either within the same JVM or from external processes. ChronicleLogReader provides a stable record schema and zero-garbage consumption (CLG-NF-P-003).

Tooling and Observability

ChroniCat and ChroniTail wrap ChronicleLogReader to offer one-shot and streaming inspection of log queues. They surface warnings on unreadable paths and reuse the same decoding logic used by automated processors, including optional throwable decoding and argument preservation, ensuring identical semantics across CLI and programmatic use (CLG-FN-004).

Metrics for throughput, latency, and allocation are captured through the benchmark suite (CLG-NF-P-001). Future operational metrics follow the Ops obligation in CLG-DOC-001.

Operational Notes

  • Provision directories for each Chronicle Queue path during deployment and ensure permissions allow writer processes, satisfying CLG-NF-O-002.

  • Coordinate configuration reloads with deployment tooling so that in-flight writers are recreated without leaks (CLG-NF-O-003).

  • Use the decision log to track future changes that alter queue layout, message schema, or failover strategy (CLG-DOC-001).