Skip to content

Legatium banner

Legatium

Legatium logs one structured adapter_* line per outbound HTTP exchange — named after the Roman legatus, the envoy a service sends to a foreign party, and the record of what came of it. Two auto-configured Spring Boot twins with identical fields and identical configuration: a RestClient/RestTemplate interceptor and a WebClient filter. No starter, no forced transitives. The sibling project Limesium records the inbound crossings with the same design.

Module Client Root package
legatium-restclient-logging RestClient / RestTemplate (blocking interceptor) eu.inqudium.legatium.restclient.logging
legatium-webclient-logging WebClient (reactive filter) eu.inqudium.legatium.webclient.logging

Features

  • Exactly one line per call. Emitted when the exchange is truly over — the response closed (RestClient) or its body terminated (WebClient) — so status, headers, body and duration are final; the outcome (success / failure / timeout, plus cancelled on the reactive stack) is decoupled from the log level.
  • A stable field contract. The adapter_* wire names are a contract with the log index: each field owns its JSON shape, a badly typed value drops that field with a warning but never the event, and the Elasticsearch component template ships with the project — kept in lockstep with the code by contract tests.
  • Identity that joins. A traced call (a traceparent on the outgoing request, put there by the host's tracing) takes its request id from the trace id and goes out untouched; a traceless call gets an X-Correlation-Id sent along so the peer can quote it. The identity rides the MDC as an additive overlay beside an inbound request's own keys.
  • Passive body capture, logged by outcome. Bodies are captured by a bounded tee as they flow — nothing is replayed or withheld from the application — and logged never, on-failure or always per direction; on-failure keeps the volume at the lines a body is wanted for. Logged header values are masked by default to a stable length:hash fingerprint (keyed on request), plaintext being an explicit allowlist.
  • Twin symmetry as an invariant. Both modules expose the same fields and the same adapter-logging.* properties; the shared reference configuration is contract-tested against both twins.
  • A library, not a platform. Auto-configured Spring Boot modules with no starter and no forced logging transitives; the host application brings the client engine and the Logback binding.

Quick start

legatium-restclient-logging on Maven Central legatium-webclient-logging on Maven Central

The badges show the current release on Maven Central — use that version where the snippets say .... Add the module matching your client — the interceptor or filter attaches itself to every client Boot builds:

<dependency>
    <groupId>eu.inqudium</groupId>
    <artifactId>legatium-restclient-logging</artifactId>
    <version>...</version>
</dependency>

or, for WebClient:

<dependency>
    <groupId>eu.inqudium</groupId>
    <artifactId>legatium-webclient-logging</artifactId>
    <version>...</version>
</dependency>

Every adapter-logging.* key, with its default, is documented in the configuration reference — copy the block and change only what you need.

Documentation

  • Common guide — everything that is one contract for both twins, written once: prerequisites, dependency, beans, the exchange line and the logging backend, index mapping, configuration, fields, meters, trace correlation, scope and fail-open guarantees, the shared code.
  • RestClient guide — the long-form guide of the reference implementation: architecture, integration, configuration, metrics.
  • WebClient guide — the twin's guide, including the deliberate stack differences.
  • Elasticsearch mapping — the ready-made component template for the adapter_* fields.
  • Test evidence — the generated inventory of the test suite: every test sentence plus its rationale, grouped by module and component.
  • Coverage report — the JaCoCo reports of the run that built this site.
  • API reference — RestClient and WebClient, generated with Dokka.

Project