Skip to content

Commit 9551173

Browse files
authored
feat: linkify Java stack traces in text documents (#1654) (#1657)
* feat: linkify Java stack traces in text documents (#1654) Add a DocumentLinkProvider that makes Java stack frames clickable in untitled documents and .log files, so a trace pasted from a log/CI/bug report can be navigated to source without an active debug session. Reuses the session-independent resolveSourceUri backend; frames are resolved lazily on click, with a source-scheme allowlist and length/ReDoS guards. Also adds an optional 'Java: Analyze Stack Trace' command that opens a scratch document prefilled from the clipboard. * feat(telemetry): track stack-trace console reach, clicks, and command usage Add three content-free telemetry events (with __GDPR__ annotations) forming an adoption funnel: provideJavaStackTraceLinks (reach, deduped once per document), navigateToJavaStackFrame (click engagement, with documentSource + resolution outcome), and analyzeJavaStackTrace (command entry usage, with prefilledFromClipboard). All dimensions are categorical; the pasted trace text is never recorded. Also bound clipboard scanning length. * refactor(telemetry): keep a single click event, drop reach + command events Simplify to one usage signal (navigateToJavaStackFrame with a documentSource dimension), mirroring the existing handleJavaTerminalLink pattern. Drop the per-document reach event (and its WeakSet) and the manual command event - command invocations are already auto-instrumented by instrumentOperationAsVsCodeCommand. * feat: activate on Java workspaces so stack-trace linkify is on by default Add workspaceContains:**/*.java so the passive DocumentLinkProvider is registered as soon as a Java project is opened - without waiting for the user to open a .java file or run a command. This matches exactly the scope where resolveSourceUri can resolve frames to source, so the feature is automatic wherever it can deliver value. * fix: only linkify once the Java language server reaches Standard mode Frame resolution (resolveSourceUri) requires a fully-loaded workspace, so registering the document link provider before jdtls is ready produces links that cannot resolve. Defer provider registration until ServerMode.STANDARD via redhat.java's onDidServerModeChange, mirroring initializeCodeLensProvider. Commands stay registered immediately. * refactor(telemetry): drop the documentSource dimension, keep a bare click count The single navigateToJavaStackFrame event is enough to measure adoption; the documentSource breakdown is not needed. Remove the dimension, the IStackFrameLinkArgs field, and the categorizeDocumentSource helper. * refactor: scope stack-trace linkify to untitled documents only Drop the `log` language and `**/*.log` selectors so linkification only targets pasted traces in untitled (scratch) documents. A `.log` opened without a Java project can't resolve frames anyway, so scanning them (or every plaintext file) adds no value. Keeps the feature narrow to the two intended paste flows: a new tab and the Analyze Stack Trace command. * refactor: gate palette command on javaLSReady, share frame parser, harden navigate - Add a commandPalette when-clause (javaLSReady) to java.debug.analyzeStackTrace so it only shows once the Java language server is ready - matching where the linkify provider actually registers, and avoiding a dead-end scratch doc in non-Java windows. - Extract the duplicated frame regex + parsing into stackFrameParser.ts, shared by the terminal and document link providers so matching stays identical. The helper builds a fresh RegExp per call, preserving the terminal provider's no-shared-stateful-RegExp contract. - Wrap resolveSourceUri/navigation in navigateToStackFrame in try/catch (and await the navigation) so a not-ready/restarting language server can't surface an unhandled rejection. * fix: address stack trace review feedback Cap clipboard prefill content, clarify command registration readiness, and add regression coverage for shared stack frame parsing. * fix: harden stack trace command links Encode command URI arguments as an array and validate navigation command inputs before resolving source locations. * refactor: clarify stack frame validation Use local values for command argument narrowing and make the parser example reflect its required leading whitespace. * fix: reject invalid stack frame line numbers Validate parsed line numbers centrally so all stack trace link surfaces reject non-positive and unsafe values. * fix: streamline stack trace initialization Defer clipboard parsing to the bounded document link provider and dispose the one-shot server mode listener after registration. * feat: linkify stack traces in log files Preserve complete clipboard content and bound document link scans by total characters and lines so saved log files can be handled safely.
1 parent 6322dc0 commit 9551173

7 files changed

Lines changed: 376 additions & 10 deletions

‎package.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@
3939
],
4040
"activationEvents": [
4141
"onLanguage:java",
42+
"workspaceContains:**/*.java",
4243
"onDebugInitialConfigurations",
4344
"onDebugResolve:java",
4445
"onCommand:JavaDebug.SpecifyProgramArgs",
@@ -151,6 +152,11 @@
151152
{
152153
"command": "java.debug.variables.manualExpandLazyVariables",
153154
"title": "Manual Expand Lazy Variables"
155+
},
156+
{
157+
"command": "java.debug.analyzeStackTrace",
158+
"title": "Analyze Stack Trace",
159+
"category": "Java"
154160
}
155161
],
156162
"menus": {
@@ -233,6 +239,10 @@
233239
}
234240
],
235241
"commandPalette": [
242+
{
243+
"command": "java.debug.analyzeStackTrace",
244+
"when": "javaLSReady"
245+
},
236246
{
237247
"command": "java.debug.hotCodeReplace",
238248
"when": "false"

‎src/extension.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ import { pickJavaProcess } from "./processPicker";
2626
import { IProgressReporter } from "./progressAPI";
2727
import { progressProvider } from "./progressImpl";
2828
import { JavaTerminalLinkProvder } from "./terminalLinkProvider";
29+
import { registerStackTraceLinkProvider } from "./stackTraceLinkProvider";
2930
import { initializeThreadOperations } from "./threadOperations";
3031
import * as utility from "./utility";
3132
import { registerBreakpointCommands } from "./breakpointCommands";
@@ -54,6 +55,7 @@ function initializeExtension(_operationId: string, context: vscode.ExtensionCont
5455
registerBreakpointCommands(context);
5556
registerVariableMenuCommands(context);
5657
context.subscriptions.push(vscode.window.registerTerminalLinkProvider(new JavaTerminalLinkProvder()));
58+
registerStackTraceLinkProvider(context);
5759
context.subscriptions.push(vscode.debug.registerDebugConfigurationProvider("java", new JavaDebugConfigurationProvider()));
5860
context.subscriptions.push(vscode.debug.registerDebugAdapterDescriptorFactory("java", new JavaDebugAdapterDescriptorFactory()));
5961
context.subscriptions.push(instrumentOperationAsVsCodeCommand("JavaDebug.SpecifyProgramArgs", async () => {

‎src/stackFrameParser.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
// Copyright (c) Microsoft Corporation. All rights reserved.
2+
// Licensed under the MIT license.
3+
4+
// The single source of truth for parsing a Java stack frame, shared by the terminal link provider
5+
// and the document (stack-trace) link provider so the matching stays identical across surfaces.
6+
7+
export interface IParsedStackFrame {
8+
// The `com.foo.Bar.baz(Bar.java:42)` text handed to `resolveSourceUri` for source resolution.
9+
stackTrace: string;
10+
// The fully-qualified method (`com.foo.Bar.baz`), used for the class-name quick-pick fallback.
11+
methodName: string;
12+
// The positive, safe 1-based source line number parsed from the frame.
13+
lineNumber: number;
14+
// Offset of the frame within the input line (points at the class name, past the leading `at `).
15+
startIndex: number;
16+
// Length of the linkifiable frame text (equals `stackTrace.length`).
17+
length: number;
18+
}
19+
20+
/**
21+
* Parses the first Java stack frame (e.g. `\tat module/com.foo.Bar.baz(Bar.java:42)`) out of a line,
22+
* or returns undefined when none is present.
23+
*
24+
* A fresh `RegExp` is created per call on purpose: provider callbacks can overlap asynchronously,
25+
* so a shared stateful `RegExp` (were a `g`/`y` flag ever added) could corrupt `lastIndex`.
26+
*/
27+
export function parseJavaStackFrame(line: string): IParsedStackFrame | undefined {
28+
// Group 2: optional module prefix, group 3: fully-qualified method, group 5: `File.java:line`.
29+
const regex = /(\sat\s+)([\w$.]+\/)?(([\w$]+\.)+[<\w$>]+)\(([\w-$]+\.java:\d+)\)/;
30+
const result = regex.exec(line);
31+
if (!result || !result.length) {
32+
return undefined;
33+
}
34+
35+
const stackTrace = `${result[2] || ""}${result[3]}(${result[5]})`;
36+
const lineNumber = Number(result[5].split(":")[1]);
37+
if (!Number.isSafeInteger(lineNumber) || lineNumber <= 0) {
38+
return undefined;
39+
}
40+
41+
return {
42+
stackTrace,
43+
methodName: result[3],
44+
lineNumber,
45+
startIndex: result.index + result[1].length,
46+
length: stackTrace.length,
47+
};
48+
}

‎src/stackTraceLinkProvider.ts‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
// Copyright (c) Microsoft Corporation. All rights reserved.
2+
// Licensed under the MIT license.
3+
4+
import { CancellationToken, commands, DocumentLink, DocumentLinkProvider, DocumentSelector,
5+
env, ExtensionContext, languages, Position, ProviderResult, Range, TextDocument, Uri,
6+
window, workspace } from "vscode";
7+
import { instrumentOperationAsVsCodeCommand, sendInfo } from "vscode-extension-telemetry-wrapper";
8+
import { resolveSourceUri } from "./languageServerPlugin";
9+
import { parseJavaStackFrame } from "./stackFrameParser";
10+
import { getJavaExtensionAPI, isJavaExtEnabled, ServerMode } from "./utility";
11+
12+
const ANALYZE_STACK_TRACE_COMMAND = "java.debug.analyzeStackTrace";
13+
const NAVIGATE_TO_STACK_FRAME_COMMAND = "_java.debug.navigateToStackFrame";
14+
15+
// Linkify stack traces in scratch documents and .log files. Other plaintext documents stay
16+
// excluded so the extension does not passively scan unrelated files.
17+
const STACK_TRACE_DOCUMENT_SELECTOR: DocumentSelector = [
18+
{ scheme: "untitled" },
19+
{ pattern: "**/*.log" },
20+
];
21+
22+
// Bound the work performed for large documents and pathological input. The per-line cap mitigates
23+
// ReDoS in the nested-quantifier regex; the document budgets keep large logs from being fully scanned.
24+
const MAX_SCANNED_LINE_LENGTH = 1000;
25+
const MAX_SCANNED_LINES_PER_DOCUMENT = 10000;
26+
const MAX_SCANNED_CHARACTERS_PER_DOCUMENT = 1000000;
27+
const MAX_LINKS_PER_DOCUMENT = 2000;
28+
29+
// Only resolve to source locations the language server is expected to return.
30+
const ALLOWED_SOURCE_SCHEMES = new Set<string>(["file", "jdt"]);
31+
32+
interface IStackFrameLinkArgs {
33+
stackTrace: string;
34+
methodName: string;
35+
lineNumber: number;
36+
}
37+
38+
function isStackFrameLinkArgs(args: unknown): args is IStackFrameLinkArgs {
39+
if (typeof args !== "object" || args === null) {
40+
return false;
41+
}
42+
43+
const stackTrace = "stackTrace" in args ? args.stackTrace : undefined;
44+
const methodName = "methodName" in args ? args.methodName : undefined;
45+
const lineNumber = "lineNumber" in args ? args.lineNumber : undefined;
46+
if (typeof stackTrace !== "string" || typeof methodName !== "string" || typeof lineNumber !== "number"
47+
|| stackTrace.length === 0 || stackTrace.length > MAX_SCANNED_LINE_LENGTH
48+
|| !Number.isSafeInteger(lineNumber) || lineNumber <= 0) {
49+
return false;
50+
}
51+
52+
const frame = parseJavaStackFrame(` at ${stackTrace}`);
53+
return frame?.stackTrace === stackTrace
54+
&& frame.methodName === methodName
55+
&& frame.lineNumber === lineNumber;
56+
}
57+
58+
/**
59+
* Linkifies Java stack frames pasted into untitled (scratch) documents, so that each frame can be
60+
* clicked to jump to the corresponding source line - without requiring an active debug session.
61+
* Resolution reuses the session-independent `resolveSourceUri` backend and is performed lazily,
62+
* only when a link is clicked.
63+
*/
64+
export class JavaStackTraceLinkProvider implements DocumentLinkProvider {
65+
public provideDocumentLinks(document: TextDocument, token: CancellationToken): ProviderResult<DocumentLink[]> {
66+
const links: DocumentLink[] = [];
67+
let scannedCharacters = 0;
68+
const linesToScan = Math.min(document.lineCount, MAX_SCANNED_LINES_PER_DOCUMENT);
69+
for (let i = 0; i < linesToScan; i++) {
70+
if (token.isCancellationRequested || links.length >= MAX_LINKS_PER_DOCUMENT) {
71+
break;
72+
}
73+
74+
const lineText = document.lineAt(i).text;
75+
const lineScanCost = lineText.length + 1;
76+
if (scannedCharacters + lineScanCost > MAX_SCANNED_CHARACTERS_PER_DOCUMENT) {
77+
break;
78+
}
79+
scannedCharacters += lineScanCost;
80+
81+
if (lineText.length > MAX_SCANNED_LINE_LENGTH) {
82+
continue;
83+
}
84+
85+
const frame = parseJavaStackFrame(lineText);
86+
if (!frame) {
87+
continue;
88+
}
89+
90+
const range = new Range(
91+
new Position(i, frame.startIndex),
92+
new Position(i, frame.startIndex + frame.length),
93+
);
94+
95+
const args: IStackFrameLinkArgs = {
96+
stackTrace: frame.stackTrace,
97+
methodName: frame.methodName,
98+
lineNumber: frame.lineNumber,
99+
};
100+
const target = Uri.parse(`command:${NAVIGATE_TO_STACK_FRAME_COMMAND}?${encodeURIComponent(JSON.stringify([args]))}`);
101+
links.push(new DocumentLink(range, target));
102+
}
103+
104+
return links;
105+
}
106+
}
107+
108+
/**
109+
* Resolves a stack frame to its source location and navigates to it. Mirrors the behavior of the
110+
* terminal link provider: jump to the resolved source line, or fall back to a symbol quick pick.
111+
*/
112+
async function navigateToStackFrame(args: unknown): Promise<void> {
113+
if (!isStackFrameLinkArgs(args)) {
114+
return;
115+
}
116+
117+
// Content-free telemetry: a single usage signal (click count), mirroring the terminal link
118+
// provider. No dimensions - the pasted text is never recorded.
119+
/* __GDPR__
120+
"navigateToJavaStackFrame" : {
121+
"owner": "vscode-java-debug",
122+
"comment": "Emitted when a user clicks a linkified Java stack frame; measures feature usage.",
123+
"operationName": { "classification": "SystemMetaData", "purpose": "FeatureInsight" }
124+
}
125+
*/
126+
sendInfo("", { operationName: "navigateToJavaStackFrame" });
127+
128+
try {
129+
const uri = await resolveSourceUri(args.stackTrace);
130+
if (uri) {
131+
const parsed = Uri.parse(uri);
132+
if (!ALLOWED_SOURCE_SCHEMES.has(parsed.scheme)) {
133+
return;
134+
}
135+
const targetLine = Math.max(args.lineNumber - 1, 0);
136+
await window.showTextDocument(parsed, {
137+
preserveFocus: true,
138+
selection: new Range(new Position(targetLine, 0), new Position(targetLine, 0)),
139+
});
140+
} else {
141+
// No source found: open the symbol quick pick scoped to the class name.
142+
const fullyQualifiedName = args.methodName.substring(0, args.methodName.lastIndexOf("."));
143+
const className = fullyQualifiedName.substring(fullyQualifiedName.lastIndexOf(".") + 1);
144+
await commands.executeCommand("workbench.action.quickOpen", "#" + className);
145+
}
146+
} catch {
147+
// The internal navigate command is always registered, but resolving a frame needs the Java
148+
// language server in Standard mode. If it isn't (e.g. server restarting/downgraded) or the
149+
// resolved document fails to open, fail quietly instead of surfacing an unhandled rejection.
150+
}
151+
}
152+
153+
/**
154+
* Opens a scratch document prefilled with the clipboard content. The document link provider scans
155+
* a bounded portion after the document opens and makes any stack frames clickable.
156+
*/
157+
async function analyzeStackTrace(): Promise<void> {
158+
// The command itself is auto-instrumented via instrumentOperationAsVsCodeCommand, so no
159+
// manual telemetry is needed here to track invocations.
160+
const clipboardContent = await env.clipboard.readText();
161+
const document = await workspace.openTextDocument({ language: "log", content: clipboardContent });
162+
await window.showTextDocument(document);
163+
}
164+
165+
export function registerStackTraceLinkProvider(context: ExtensionContext): void {
166+
// Register handlers immediately for programmatic invocations and existing command links.
167+
// Palette visibility and creation of new links are gated on language-server readiness elsewhere.
168+
context.subscriptions.push(
169+
commands.registerCommand(NAVIGATE_TO_STACK_FRAME_COMMAND, navigateToStackFrame),
170+
instrumentOperationAsVsCodeCommand(ANALYZE_STACK_TRACE_COMMAND, analyzeStackTrace),
171+
);
172+
173+
// Linkifying a frame is only meaningful once the Java language server is in Standard mode,
174+
// because resolving a frame to source (resolveSourceUri) requires a fully-loaded workspace.
175+
// Defer registering the link provider until then, mirroring the run/debug CodeLens provider.
176+
registerLinkProviderWhenReady(context);
177+
}
178+
179+
function registerLinkProviderWhenReady(context: ExtensionContext): void {
180+
// Without the Java language server, frames cannot be resolved to source - nothing to linkify.
181+
if (!isJavaExtEnabled()) {
182+
return;
183+
}
184+
185+
const doRegister = () => context.subscriptions.push(
186+
languages.registerDocumentLinkProvider(STACK_TRACE_DOCUMENT_SELECTOR, new JavaStackTraceLinkProvider()),
187+
);
188+
189+
getJavaExtensionAPI().then((api) => {
190+
if (!api) {
191+
return;
192+
}
193+
194+
if (api.serverMode === ServerMode.LIGHTWEIGHT || api.serverMode === ServerMode.HYBRID) {
195+
let registered = false;
196+
const serverModeListener = api.onDidServerModeChange((mode: string) => {
197+
if (mode === ServerMode.STANDARD && !registered) {
198+
registered = true;
199+
serverModeListener.dispose();
200+
doRegister();
201+
}
202+
});
203+
context.subscriptions.push(serverModeListener);
204+
} else {
205+
// Already in Standard mode.
206+
doRegister();
207+
}
208+
});
209+
}

‎src/terminalLinkProvider.ts‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ import { CancellationToken, commands, Position, ProviderResult, Range, TerminalL
55
TerminalLinkProvider, Uri, window } from "vscode";
66
import { sendInfo } from "vscode-extension-telemetry-wrapper";
77
import { resolveSourceUri } from "./languageServerPlugin";
8+
import { parseJavaStackFrame } from "./stackFrameParser";
89

910
export class JavaTerminalLinkProvder implements TerminalLinkProvider<IJavaTerminalLink> {
1011
/**
@@ -17,17 +18,14 @@ export class JavaTerminalLinkProvder implements TerminalLinkProvider<IJavaTermin
1718
*/
1819
public provideTerminalLinks(context: TerminalLinkContext, _token: CancellationToken): ProviderResult<IJavaTerminalLink[]> {
1920
const isDebuggerTerminal: boolean = context.terminal.name.startsWith("Run:") || context.terminal.name.startsWith("Debug:");
20-
const regex = new RegExp("(\\sat\\s+)([\\w$\\.]+\\/)?(([\\w$]+\\.)+[<\\w$>]+)\\(([\\w-$]+\\.java:\\d+)\\)");
21-
const result: RegExpExecArray | null = regex.exec(context.line);
22-
if (result && result.length) {
23-
const stackTrace = `${result[2] || ""}${result[3]}(${result[5]})`;
24-
const sourceLineNumber = Number(result[5].split(":")[1]);
21+
const frame = parseJavaStackFrame(context.line);
22+
if (frame) {
2523
return [{
26-
startIndex: result.index + result[1].length,
27-
length: stackTrace.length,
28-
methodName: result[3],
29-
stackTrace,
30-
lineNumber: sourceLineNumber,
24+
startIndex: frame.startIndex,
25+
length: frame.length,
26+
methodName: frame.methodName,
27+
stackTrace: frame.stackTrace,
28+
lineNumber: frame.lineNumber,
3129
isDebuggerTerminal,
3230
}];
3331
}

‎test/stackFrameParser.test.ts‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
// Copyright (c) Microsoft Corporation. All rights reserved.
2+
// Licensed under the MIT license.
3+
4+
import * as assert from "assert";
5+
6+
import { parseJavaStackFrame } from "../src/stackFrameParser";
7+
8+
suite("parseJavaStackFrame", () => {
9+
test("parses a tab-indented stack frame", () => {
10+
const stackTrace = "com.example.App.main(App.java:42)";
11+
12+
assert.deepStrictEqual(parseJavaStackFrame(`\tat ${stackTrace}`), {
13+
stackTrace,
14+
methodName: "com.example.App.main",
15+
lineNumber: 42,
16+
startIndex: 4,
17+
length: stackTrace.length,
18+
});
19+
});
20+
21+
test("preserves a module prefix", () => {
22+
const stackTrace = "java.base/java.util.ArrayList.forEach(ArrayList.java:1511)";
23+
24+
assert.deepStrictEqual(parseJavaStackFrame(`\tat ${stackTrace}`), {
25+
stackTrace,
26+
methodName: "java.util.ArrayList.forEach",
27+
lineNumber: 1511,
28+
startIndex: 4,
29+
length: stackTrace.length,
30+
});
31+
});
32+
33+
test("calculates the link range within prefixed output", () => {
34+
const stackTrace = "com.example.Worker.run(Worker.java:7)";
35+
const line = `[stderr] \tat ${stackTrace} ~[app.jar:1.0]`;
36+
const frame = parseJavaStackFrame(line);
37+
38+
assert.ok(frame);
39+
assert.strictEqual(frame.startIndex, line.indexOf(stackTrace));
40+
assert.strictEqual(frame.length, stackTrace.length);
41+
assert.strictEqual(line.substring(frame.startIndex, frame.startIndex + frame.length), stackTrace);
42+
});
43+
44+
test("rejects non-positive and unsafe line numbers", () => {
45+
assert.strictEqual(parseJavaStackFrame("\tat com.example.App.main(App.java:0)"), undefined);
46+
assert.strictEqual(parseJavaStackFrame("\tat com.example.App.main(App.java:9007199254740992)"), undefined);
47+
});
48+
});

0 commit comments

Comments
 (0)