docs: add SwingBridge guide for logging and identifying logs per user by taefi · Pull Request #5807 · vaadin/docs

taefi · 2026-07-13T12:37:36Z

Description

Adds a new SwingBridge documentation page, Logging & Identifying Logs per User (tools/modernization-toolkit/swing-bridge/logging.adoc, navigation slot 5), documenting the per-session log attribution features shipped in vaadin/vaadin-swing-bridge#239, vaadin/vaadin-swing-bridge#240, and vaadin/vaadin-swing-bridge#241.

The page is written for readers without deep Vaadin knowledge and structured as an integration ladder, from zero cooperation to the interop APIs:

Quick Setup — the two copy-paste steps (JVM flag + pattern token) with the expected log output.
Choosing an Integration Level — a five-rung ladder table (automatic console prefixing → configuration-only file tagging → one-line identity → log context API → interop cooperation), each rung linking to its section.
What Gets Tagged, and How — console prefixing vs. file/structured logs, with Log4j2 (%X{swingSession}, async-safety explained), Logback, and JUL configuration blocks; every snippet labeled with the codebase it belongs to (Vaadin application vs. Swing application).
Publishing the User Identity — both authentication placements as separate scenarios: login inside the Swing application (property one-liner → SwingBridgeLogContext → zero-change reflection observer) and login extracted to Vaadin with host-side navigation (setLogIdentity and its per-(session, application) keying), plus bespoke logging subsystems via the typed interop (@ExposedMethod initLogIdentity) and the both-sides case.
Support Workflow — showing the run ID in the application and reportIncident.
Old and New Logging Frameworks Together — where a Swing application's log statements actually go (class-loader shadowing, Log4j 1.x bridging, "the app's own log file won't exist" expectation-setting), Spring Boot's Logback vs. SwingBridge's Log4j2, the multiple-SLF4J-providers pitfall and the slf4j.provider pin, and a coverage-expectations table.
Desktop Builds Are Unaffected and a symptom-based Troubleshooting list.

Supporting changes:

configuration.adoc: two new system-property rows (swingbridge.consoleLogPrefix, swingbridge.log.user) cross-linking the new page.
installation-from-scratch.adoc: the template's log4j-slf4j2-impl exclusion is now explained and linked to the new page's trade-off discussion (previously the exclusion appeared with no rationale, and it directly affects where embedded applications' log output ends up).
Vale vocabulary: accepts appender(s), Splunk, and interop — the latter clears 13 pre-existing spelling errors across the existing interop section. The new page lints at 0 Vale errors.

github-actions · 2026-07-13T12:50:25Z

Preview Deployment

This PR has been deployed for preview.

URL: https://docs-preview-pr-5807.fly.dev

Changed pages

Added content is highlighted in green; removed content is marked in red on each page.

tools/modernization-toolkit/swing-bridge/configuration — modified, +12/-0 lines
tools/modernization-toolkit/swing-bridge/installation-from-scratch — modified, +5/-0 lines
tools/modernization-toolkit/swing-bridge/logging — added, +468/-0 lines

Built from 43c7f29

New page (order 5) covering per-session log attribution: quick setup, an integration-level ladder from zero cooperation to the interop APIs, console prefixing and the Log4j2/Logback/JUL adapters, publishing the user identity for both A&A placements (login inside Swing vs. extracted to Vaadin), the reportIncident support workflow, and a section on old and new logging frameworks coexisting (Log4j 1.x bridging, guest config shadowing, Spring Boot Logback vs. Log4j2, SLF4J provider pinning). Also: configuration.adoc gains the swingbridge.consoleLogPrefix and swingbridge.log.user rows; installation-from-scratch.adoc explains its log4j-slf4j2-impl exclusion and links the trade-offs; the Vale vocabulary accepts appender(s), Splunk, and interop (clears 13 pre-existing spelling errors in the interop section).

…ation 'User Identification' reads like authentication; the page is about attributing log output to the user who produced it. Renames the page title, SEO title, heading, and the cross-reference labels in configuration.adoc and installation-from-scratch.adoc.

… attribution Restructure the SwingBridge logging page so someone who knows Swing and core Java, but is new to Vaadin/SwingBridge, can get from nothing to tagged logs quickly: - Turn "Quick Setup" into an explicit Step 1 / Step 2 / Step 3 path, leading with the single JVM flag that needs no Swing-app changes. - Retitle the identity section to the task ("Adding the User's Name to the Logs") and lead with the one-line, no-dependency option (System.setProperty("swingbridge.log.user", name) after login); give the who-publishes subsections clearer, task-oriented headings. - Document the new opt-in, swingbridge.includeUserInLogs, which puts the user's name on every line ([swing:<runId>|<user>]) and via the %swingUser / %X{swingUser} tokens; note it is off by default because the name is personal data. Add the Log4j2/Logback/JUL token usage and a configuration.adoc row and a troubleshooting entry.

The logging page is long; add an "on this page" table of contents so readers don't lose track. Two complementary aids: - :toc: — the DSP right-rail contents list, auto-built from the section headings (same mechanism as flow/advanced/downloads.adoc). - An "In this article" jump-list near the top linking the nine top-level sections, for in-body navigation. Also mark the feature's availability with a plain-text note under the title ("Available since SwingBridge 1.3."). The DSP since-badge macro has no precedent for a tool version (only Vaadin/Hilla platform coordinates), so a text note states it unambiguously without risking a broken badge.

HerbertsVaadin

Read through it, seems ok, several formatting issues.
Can ask AI to correct these.
Not sure if the content is valid, as I'm unfamiliar with the topic, but seemed to make sense.
Please check also the "Vale" errors.

HerbertsVaadin · 2026-08-17T09:13:44Z

+= Logging & Identifying Logs per User
+:toc:
+
+_Available since SwingBridge 1.3._


I don't think version is necessary, to show. If something is not available, the customer should make sure they upgrade first.

Version 1.3.0 is still in alpha, we only published it for a specific (potential) customer who asked for this feature. Our latest version is still 1.2.2.

HerbertsVaadin · 2026-08-17T09:21:25Z

+
+_Available since SwingBridge 1.3._
+
+On the desktop, one Swing application serves one user, so its log file belongs to that user. With SwingBridge, many users run the same application inside a single server JVM, and everything they produce — log statements, stack traces, `System.out` output — lands interleaved in one server log. When a user reports a problem, support needs to follow *that user's* trail through the log.


I'd recommend replacing all m-dashes (—) with regular (-) dashes, so its does not look as AI has written all of this.

Also, no reason to put emphasis on *that user's* . Again, something AI like to overdo.

HerbertsVaadin · 2026-08-17T09:25:25Z

+
+[source]
+----
+[swing:7f3k2a] Loading customer list for account 4711


For some reason the word "for" gets different coloring here. Consider switching the source language to something else.

HerbertsVaadin · 2026-08-17T09:28:32Z

+-Dswingbridge.consoleLogPrefix=true
+----
+
+Every line an embedded Swing application writes to `System.out` or `System.err` — including `exception.printStackTrace()` and the console output of whatever logging framework it uses — is now prefixed with its run ID:


This sentence runs a bit awkward, with two dashes,
replace them with commas:

Every line an embedded Swing application writes to System.out or System.err, including exception.printStackTrace() and the console output of whatever logging framework it uses, is now prefixed with its run ID:

HerbertsVaadin · 2026-08-17T09:30:14Z

+
+File lines now carry the run ID in the `%X{swingSession}` column. Other frameworks are covered too — see <<swing-bridge.logging.channels.files,Log Files and Structured Logs>>.
+
+At each application start, SwingBridge also logs one *correlation line* that ties the run ID to the session and (once known) the user:


Please remove "correlation line" emphasis here.

HerbertsVaadin · 2026-08-17T12:52:56Z

+
+The practical upshot: tag the *server's* appender patterns (see <<swing-bridge.logging.channels.files,above>>), and every framework generation inside the Swing application is covered.
+
+In the rare setup where the server deliberately excludes Log4j2 and the Swing application runs its own logging context, the adapters still work — reference them from the *application's* configuration file instead, or add the forwarding appender to stream its events into the server log, attributed:


No need to emphasize "application's"

HerbertsVaadin · 2026-08-17T12:53:25Z

+[[swing-bridge.logging.frameworks.slf4j]]
+=== SLF4J, Spring Boot, and Provider Selection
+
+SLF4J is a facade: at startup it picks one *provider* (binding) that decides where all SLF4J log statements go. Two pitfalls in SwingBridge deployments:


no need to emphasize "provider"

HerbertsVaadin · 2026-08-17T12:55:07Z

+
+*Spring Boot defaults to Logback, SwingBridge brings Log4j2.* Running both backends splits your logs in two. The <<installation-from-scratch#,Installation from Scratch>> template resolves the clash in Logback's favor: it excludes `log4j-slf4j2-impl` from `swing-bridge-flow`, so SLF4J traffic (Spring, SwingBridge itself) goes to Logback. That setup works with the <<swing-bridge.logging.channels.files,Logback adapters>> — with one caveat: a Swing application calling Log4j APIs directly still logs through Log4j2's own default configuration, which writes to the console only (prefixed, but absent from your Logback-managed files).
+
+To get *everything* — Spring, SwingBridge, and every Swing application — into one set of tagged appenders, standardize on Log4j2 instead: keep `swing-bridge-flow`'s binding (remove the template's exclusion), and exclude Logback in the Vaadin application's `pom.xml`:


Formatting broken here

HerbertsVaadin · 2026-08-17T12:57:34Z

+|Feed `SwingBridgeLogContext.runId()` / `userName()` into it
+|===
+
+One structural limit applies everywhere: output produced on *shared* JVM threads that don't belong to any application instance — for example, `ForkJoinPool.commonPool()` — can't be attributed to a user.


Replace dashes with commas please.

HerbertsVaadin · 2026-08-17T12:59:45Z

+Check that the JVM was started with `-Dswingbridge.consoleLogPrefix=true`. The flag is off by default.
+
+`%X{swingSession}` stays empty on lines you expected to be tagged::
+The line was probably logged on a server thread (correlation lines, HTTP request handling) — those are intentionally untagged. If *application* lines stay empty, verify the deployment runs Log4j2 2.13.2 or later; on older versions use `%swingSession` with synchronous appenders.


remove emphasis from "application" please

taefi · 2026-08-17T15:30:44Z

Thanks Herbert! Will fix the issues.

- Replace em-dashes with commas, colons, or parentheses throughout - Remove gratuitous inline emphasis, keeping bold only for run-in headings - Simplify the per-line user name paragraph as suggested - Use [source,text] for plain output blocks so they are not syntax-colored - Fix a broken code span: a backtick followed by "'s" does not close the span, so the rest of the sentence rendered as monospace Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

taefi changed the title ~~docs: add SwingBridge logging and user identification guide~~ docs: add SwingBridge guide for logging and identifying logs per user Jul 13, 2026

taefi added 3 commits July 17, 2026 14:50

taefi force-pushed the swing-bridge-logging branch from e6ba3bb to bf084ff Compare July 17, 2026 11:55

taefi requested a review from eftunv July 17, 2026 11:59

HerbertsVaadin requested changes Aug 17, 2026

View reviewed changes

taefi and others added 2 commits August 18, 2026 11:03

Merge branch 'main' into swing-bridge-logging

bbf942e


		_Available since SwingBridge 1.3._

		On the desktop, one Swing application serves one user, so its log file belongs to that user. With SwingBridge, many users run the same application inside a single server JVM, and everything they produce — log statements, stack traces, `System.out` output — lands interleaved in one server log. When a user reports a problem, support needs to follow that user's trail through the log.


		File lines now carry the run ID in the `%X{swingSession}` column. Other frameworks are covered too — see <<swing-bridge.logging.channels.files,Log Files and Structured Logs>>.

		At each application start, SwingBridge also logs one correlation line that ties the run ID to the session and (once known) the user:


		The practical upshot: tag the server's appender patterns (see <<swing-bridge.logging.channels.files,above>>), and every framework generation inside the Swing application is covered.

		In the rare setup where the server deliberately excludes Log4j2 and the Swing application runs its own logging context, the adapters still work — reference them from the application's configuration file instead, or add the forwarding appender to stream its events into the server log, attributed:


		Spring Boot defaults to Logback, SwingBridge brings Log4j2. Running both backends splits your logs in two. The <<installation-from-scratch#,Installation from Scratch>> template resolves the clash in Logback's favor: it excludes `log4j-slf4j2-impl` from `swing-bridge-flow`, so SLF4J traffic (Spring, SwingBridge itself) goes to Logback. That setup works with the <<swing-bridge.logging.channels.files,Logback adapters>> — with one caveat: a Swing application calling Log4j APIs directly still logs through Log4j2's own default configuration, which writes to the console only (prefixed, but absent from your Logback-managed files).

		To get everything — Spring, SwingBridge, and every Swing application — into one set of tagged appenders, standardize on Log4j2 instead: keep `swing-bridge-flow`'s binding (remove the template's exclusion), and exclude Logback in the Vaadin application's `pom.xml`:

Uh oh!

Conversation

taefi commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Uh oh!

github-actions Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview Deployment

Changed pages

Uh oh!

HerbertsVaadin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

taefi commented Aug 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

taefi commented Jul 13, 2026 •

edited

Loading

github-actions Bot commented Jul 13, 2026 •

edited

Loading