This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/docs by this push:
new 72f0776fbf TODO-362: redesign NG RestClient debug logging onto
RichLogger
72f0776fbf is described below
commit 72f0776fbf5625cc3d5b497aad1ded7533b57a4e
Author: James Bognar <[email protected]>
AuthorDate: Sat Aug 15 15:13:45 2026 -0400
TODO-362: redesign NG RestClient debug logging onto RichLogger
Drive NG client debug via JUL logger level only (INFO=basic, FINE=+headers,
FINEST=+bodies) on RichLogger. Add RestClientDebugFormatter +
BasicRestClientDebugFormatter and a RestClientDebugPipeline for tier
resolution/emission. Add
RestClient.Builder.debugLoggerName(String)/debugFormatter(...) with default
logger name RestClient.class.getName(); wire RestRequest/RestResponse to emit
bounded request/response capture through RichLogger. Remove legacy
RestLogger/RestLogEntry/RestLogLevel [...]
---
pages/release-notes/10.0.0.md | 2 +
.../topics/13.10.RestClientLoggingAndDebugging.md | 51 +++++++++++++++++++++-
2 files changed, 52 insertions(+), 1 deletion(-)
diff --git a/pages/release-notes/10.0.0.md b/pages/release-notes/10.0.0.md
index e9381d0a60..bfd1c5dd13 100644
--- a/pages/release-notes/10.0.0.md
+++ b/pages/release-notes/10.0.0.md
@@ -1177,6 +1177,8 @@ See
[juneau-rest-server-mcp](/docs/topics/JuneauRestServerMcp#resource-templates
- **REST debug/logging system fully redesigned (`juneau-rest-server`) (hard
break, no deprecation shim).** The entire multi-signal debug/logging mechanism
has been replaced by a single JUL-logger-level-driven model (see New Features
above). Removed with no replacement annotation, attribute, or config key:
`@Rest(debug=...)` / `@RestOp(debug=...)`, the nested `@Debug` annotation and
its `value()`/`on()`/`format()`/`level()`/`config()` members,
`debugDefault`/`debugEnablement`/`debugOn`; t [...]
+- **Next-generation `RestClient` debug logging redesigned around JUL levels +
`RichLogger` (hard break, no shim).** The NG client
(`org.apache.juneau.rest.client.RestClient`) removes `RestLogger`,
`RestLogEntry`, `RestLogLevelResolver`, `BasicRestLogger`, builder
`logger(...)`, and per-request `RestRequest.debug()`. Replacement is
single-signal, level-driven debug on the configured logger name: `INFO`
(basic), `FINE` (headers), `FINEST` (headers + bounded bodies). New builder
entry point [...]
+
- **`Marshaller` instance API kept as `read`/`write`; static `of`/`to`
shortcuts reintroduced on concrete classes (TODO-225).** An interim plan to
rename the top-level convenience methods on `Marshaller`, `CharMarshaller`, and
`StreamMarshaller` to `to`/`of` was **not** carried through — the instance
methods remain `read`/`write`, and `to`/`of` ship instead as **static**
shortcuts on the concrete marshaller classes (e.g. `Json`, `Xml`, `Protobuf`),
delegating to each class's `DEFAULT` instance:
- **Instance (unchanged names):** `Marshaller.read(Object, Class<T>)` /
`read(Object, Type, Type...)`; `Marshaller.write(Object, Object)`.
`CharMarshaller` adds a `String`-based `read(String, ...)` and a
`String`-returning `write(Object)`; `StreamMarshaller` adds a `byte[]`-based
`read(byte[], ...)` and a `byte[]`-returning `write(Object)`.
- **Static shortcuts (new, on each concrete class):** `Xxx.to(input, type,
...)` parses via `Xxx.DEFAULT.read(...)`; `Xxx.of(object)` serializes via
`Xxx.DEFAULT.write(...)` — e.g. `Json.to(json, MyBean.class)` /
`Json.of(myBean)`.
diff --git a/pages/topics/13.10.RestClientLoggingAndDebugging.md
b/pages/topics/13.10.RestClientLoggingAndDebugging.md
index 5ad050ada9..6867025f01 100644
--- a/pages/topics/13.10.RestClientLoggingAndDebugging.md
+++ b/pages/topics/13.10.RestClientLoggingAndDebugging.md
@@ -63,4 +63,53 @@ Additionally, the following method is also provided for
enabling debug mode:
Enabling debug mode has the following effects:
-- <a
href="/site/apidocs/org/apache/juneau/rest/client/classic/RestClient.Builder.html#logToConsole()"
target="_blank">RestClient.Builder.logToConsole()</a> is called.
\ No newline at end of file
+- <a
href="/site/apidocs/org/apache/juneau/rest/client/classic/RestClient.Builder.html#logToConsole()"
target="_blank">RestClient.Builder.logToConsole()</a> is called.
+Classic REST client logging/debug APIs are unchanged and remain available
through the classic builder:
+
+<tree>
+<node-0><java-class><a
href="/site/apidocs/org/apache/juneau/rest/client/classic/RestClient.Builder.html"
target="_blank">org.apache.juneau.rest.client.classic.RestClient.Builder</a></java-class></node-0>
+<node-1><java-method><a
href="/site/apidocs/org/apache/juneau/rest/client/classic/RestClient.Builder.html#logger(java.util.logging.Logger)"
target="_blank">logger(Logger)</a></java-method></node-1>
+<node-1><java-method><a
href="/site/apidocs/org/apache/juneau/rest/client/classic/RestClient.Builder.html#logToConsole()"
target="_blank">logToConsole()</a></java-method></node-1>
+<node-1><java-method><a
href="/site/apidocs/org/apache/juneau/rest/client/classic/RestClient.Builder.html#logRequests(org.apache.juneau.DetailLevel,java.util.logging.Level,java.util.function.BiPredicate)"
target="_blank">logRequests(DetailLevel,Level,BiPredicate)</a></java-method></node-1>
+<node-1><java-method><a
href="/site/apidocs/org/apache/juneau/rest/client/classic/RestClient.Builder.html#debug()"
target="_blank">debug()</a></java-method></node-1>
+</tree>
+
+## Next-generation REST client (NG)
+
+The next-generation client (`org.apache.juneau.rest.client.RestClient`) uses
JUL-level-driven debug logging through `RichLogger`.
+
+<tree>
+<node-0><java-class><a
href="/site/apidocs/org/apache/juneau/rest/client/RestClient.Builder.html"
target="_blank">org.apache.juneau.rest.client.RestClient.Builder</a></java-class></node-0>
+<node-1><java-method><a
href="/site/apidocs/org/apache/juneau/rest/client/RestClient.Builder.html#debugLoggerName(java.lang.String)"
target="_blank">debugLoggerName(String)</a></java-method></node-1>
+<node-1><java-method><a
href="/site/apidocs/org/apache/juneau/rest/client/RestClient.Builder.html#debugFormatter(org.apache.juneau.rest.client.RestClientDebugFormatter)"
target="_blank">debugFormatter(RestClientDebugFormatter)</a></java-method></node-1>
+<node-0><java-class><a
href="/site/apidocs/org/apache/juneau/rest/client/RestClientDebugFormatter.html"
target="_blank">RestClientDebugFormatter</a></java-class></node-0>
+<node-1><java-class><a
href="/site/apidocs/org/apache/juneau/rest/client/BasicRestClientDebugFormatter.html"
target="_blank">BasicRestClientDebugFormatter</a></java-class></node-1>
+</tree>
+
+Default logger name: `RestClient.class.getName()`.
+
+Debug detail is controlled solely by the resolved JUL logger level:
+
+- `INFO`: basic summary line.
+- `FINE`: basic + request/response headers.
+- `FINEST`: basic + headers + bounded request/response body capture.
+
+`BasicRestClientDebugFormatter` redacts sensitive headers using the shared
redaction utility and captures bodies up to a configurable cap (`bodyCap()`).
+
+For tests, capture emitted records directly via
`RichLogger.captureEvents(...)`:
+
+```java
+var logger = RichLogger.getLogger("my.client.debug");
+logger.setLevel(Level.FINEST);
+
+try (var capture = logger.captureEvents(Level.FINEST);
+ var client = RestClient.builder()
+ .debugLoggerName("my.client.debug")
+ .debugFormatter(new BasicRestClientDebugFormatter().bodyCap(8 * 1024))
+ .build();
+ var res =
client.post("http://localhost/bean";).bodyString("{\"x\":1}").run()) {
+ res.body().asString();
+ var record = capture.last();
+ // assert on record.getLevel() and record.getMessage()
+}
+```
\ No newline at end of file
