JVM Pulse for VS Code

JVM Pulse monitors and diagnoses local Java applications inside VS Code. It provides live CPU, heap, thread, class-loading and garbage-collection metrics, plus JFR, heap analysis, automatic root-cause analysis, optimization recommendations, and before/after comparisons.

Current features

• Automatic discovery and live monitoring of local JVM processes
• CPU, heap, thread, class-loading, GC and uptime dashboards with zoomable charts
• Local JMX connection with a loopback-only Attach Agent fallback and one-time authentication token
• JVM configuration, launch argument and garbage-collector inspection
• Top CPU threads, object histogram, JFR hotspots and allocation analysis
• Heap dump dominators, retained sizes and GC-root ownership paths
• Local health findings, root-cause guidance and optimization recommendations
• Persistent Before/After metrics and dashboard screenshots
• Local Quick analysis with material-change thresholds, confidence and Markdown export
• Optional OpenAI root-cause analysis using summarized JVM evidence and explicitly selected screenshots
• Screenshot history, open, download, zoom and confirmed deletion
• Automated unit, UI contract, persistence, OpenAI mock, Java API and VS Code host tests

Requirements

• Windows 10 or newer
• A full JDK 21 or newer; a JRE is not sufficient
• VS Code and the monitored JVM must run as the same Windows user and at the same privilege level

Verify the JDK from a terminal:

java -version
jps -l

Install

1. Open VS Code.
2. Press Ctrl+Shift+P.
3. Run Extensions: Install from VSIX....
4. Select the jvm-pulse-*.vsix file.
5. Run Developer: Reload Window when installation finishes.

Publishing to the VS Code Marketplace is not required for local installation.

Open JVM Pulse

Click JVM Pulse in the VS Code status bar, or open the Command Palette and run JVM Pulse: Open Monitor.

You can also use:

• Windows/Linux: Ctrl+Alt+J
• macOS: Cmd+Alt+J

The extension starts its local backend automatically and selects an available loopback port. To restart it, run JVM Pulse: Restart Backend. To use the standalone browser view, run JVM Pulse: Open in Browser.

Monitor a JVM

1. Start the Java application you want to inspect.
2. Open JVM Pulse.
3. Select the application and PID from the application list at the top.
4. Use Dashboard for live CPU, heap, thread, GC, class and uptime information.
5. Use Configuration to inspect the runtime, JVM version, heap limits, garbage collector and JVM arguments.

The target normally needs no java.rmi.server.hostname setting. JVM Pulse tries the standard local JMX connector first. If that address is unreachable, it automatically loads a loopback-only Attach Agent protected by a one-time token. The Agent closes its listener after disconnection and 30 seconds of inactivity.

JFR analysis

1. Open Diagnostics.
2. Under Flight Recorder, select a recording duration.
3. Click Start and reproduce the slow or CPU-intensive operation.
4. Wait for the recording to reach STOPPED.
5. Click Analyze next to the recording.

The results show hot methods, CPU sample share, call stacks, allocation hotspots, source locations and optimization hints. You can also download the original .jfr recording.

Heap analysis

For a quick view, click Analyze under Object histogram. This can briefly pause the target JVM.

For retained-memory analysis:

1. Open Diagnostics.
2. Find Memory dominators.
3. Click Capture & analyze.
4. Review retained sizes, instance counts, GC-root ownership information and optimization hints.

Heap capture can pause the target and requires free disk space close to the target's used heap size.

Root-cause analysis and recommendations

Open Analysis after collecting at least a few live samples. Click Analyze now to refresh JVM configuration, thread CPU and metric evidence. JVM Pulse correlates CPU, heap growth, allocation pressure, GC activity, thread counts, histograms, JFR results and heap dominators to produce prioritized findings and optimization recommendations.

Collecting JFR and heap evidence before analysis produces more useful results.

Before/after comparison

1. Run a representative workload before making a change.
2. Open Analysis and click Save before. JVM Pulse saves both the metric evidence and a dashboard screenshot locally, then immediately displays the image with Open and Download actions.
3. Apply the code or JVM configuration change.
4. Restart the target if needed and reproduce the same workload.
5. Click Compare now. JVM Pulse captures the after screenshot and displays both images side by side.
6. Click Quick analysis for an immediate local summary of material CPU, heap, allocation and GC changes. It analyzes the fixed After snapshot saved by Compare now when available, reports confidence from sample count and duration, and explains which signals drove the verdict. Absolute, metric-specific thresholds prevent a near-zero baseline from inflating small changes. This analysis does not use an API key or send data externally.
7. Use the 30-second collection guide to keep the After window representative, then click Export report to save the local result as Markdown.

The comparison reports changes in average and peak CPU, heap usage, allocation rate, GC pause share, GC frequency and thread count. Click an image to open the built-in zoom viewer, which supports zoom in/out, reset, mouse-wheel zoom and full scrolling. The Before and After images can also be opened in VS Code or downloaded as JPEG files. JVM Pulse stores one latest Before/After pair per application identity. Saving a new Before replaces the previous pair; running Compare again replaces only the previous After. Screenshots stay local unless you explicitly select them for an AI request. Use the same workload and observation period for a meaningful comparison.

Quick analysis confidence is based on the sample count, observation duration and balance between the Before and After windows:

• High: both windows contain at least 30 samples, cover at least 25 seconds and have comparable durations
• Medium: both windows contain at least 10 samples, cover at least 8 seconds and are reasonably balanced
• Low: the comparison is short, sparse or has substantially different observation windows

Baselines are stored persistently in VS Code extension storage and matched by application identity rather than PID, so they remain available after the JVM or VS Code restarts. Open History to view the saved Before or After screenshot, or delete the complete pair. The jvmPulse.maxHistory setting limits application pairs to 5 by default and 25 maximum.

AI analysis

AI analysis uses the selected provider's Responses API or Chat Completions API to correlate summarized metrics, threads, JFR hotspots, heap dominators and before/after evidence. Raw .jfr and .hprof files are not uploaded. Saved Before and After screenshots are optional: they are sent only when you explicitly select their checkboxes, with a maximum of two compressed JPEG images per analysis.

Configure an AI provider

From the JVM Pulse Analysis page, click AI settings beside Analyze with AI. The configuration form opens directly inside the monitor, where you can edit and save all provider fields without leaving the page.

The same form is also available from the Command Palette:

1. In VS Code, press Ctrl+Shift+P.
2. Run JVM Pulse: Configure AI Provider.
3. In the configuration window, select OpenAI, DeepSeek, OpenRouter, Azure OpenAI, Ollama, LM Studio or another OpenAI-compatible service.
4. Edit the Base URL, model/deployment, API protocol and Azure API version when applicable.
5. Optionally enter or remove the selected provider's API Key, then click Save configuration. Leaving the Key blank preserves the existing saved key.

Keys are stored separately for each provider in VS Code SecretStorage, not in settings or source files. Existing OpenAI keys are migrated automatically. Running the Set command again replaces only the current provider's key. Use JVM Pulse: Clear AI Provider API Key to remove it.

Default endpoints:

• OpenAI: https://api.openai.com/v1 using the Responses API
• DeepSeek: https://api.deepseek.com using Chat Completions
• OpenRouter: https://openrouter.ai/api/v1 using Chat Completions
• Ollama: http://127.0.0.1:11434/v1
• LM Studio: http://127.0.0.1:1234/v1
• Azure OpenAI: your resource endpoint, deployment name and API version
• Compatible: a custom Base URL exposing either /chat/completions or /responses; select the matching API protocol in AI settings

Ollama, LM Studio and compatible local servers can run without a key. Gemini and Claude native protocols are not yet supported; they require dedicated adapters. They may be used only through an OpenAI-compatible gateway.

Add and select models

Each provider can retain multiple model names. To add one without replacing your draft with a saved model:

1. Open AI settings.
2. Select the provider.
3. Click Add new model.
4. Enter the exact model ID required by that provider, then click Save configuration.

While a new model name is being entered, background configuration refreshes do not replace it. Use Saved models to load an existing model, or use the model selector beside Analyze with AI to switch the active saved model. Model IDs are provider-defined; for example, a custom gateway may use a different name from the official OpenAI model ID.

For Other OpenAI-compatible, select the protocol supported by the custom server:

• Chat Completions API sends POST {Base URL}/chat/completions.
• Responses API sends POST {Base URL}/responses and supports Responses-only models when the gateway exposes them.

Enter the service root as the Base URL. Do not append /responses or /chat/completions, because JVM Pulse adds the selected endpoint path.

Run AI analysis

1. Collect live metrics and, when relevant, JFR or heap evidence.
2. Optionally create a before/after comparison.
3. Open Analysis.
4. Optionally select Before screenshot and/or After screenshot. The checkboxes are disabled until those images exist and are unchecked by default.
5. Click Analyze with AI.
6. Review the summary, root-cause hypotheses, confidence, supporting evidence, recommendations and expected impact.

AI output should be treated as diagnostic guidance. Confirm recommendations with repeatable measurements before changing production systems. OpenAI API usage is billed separately from ChatGPT subscriptions.

Settings

• jvmPulse.javaHome: path to a full JDK 21+ installation
• jvmPulse.port: backend port; 0 selects an available port automatically
• jvmPulse.openOnStartup: automatically open the monitor after VS Code starts
• jvmPulse.aiProvider: selected AI provider
• jvmPulse.aiBaseUrl: optional provider Base URL override
• jvmPulse.aiProtocol: chat-completions or responses for custom OpenAI-compatible services
• jvmPulse.aiModel: model name or Azure deployment name
• jvmPulse.azureApiVersion: Azure OpenAI API version
• jvmPulse.maxHistory: maximum persistent baseline and screenshot records
• jvmPulse.comparisonSensitivity: Quick analysis threshold multiplier from 0.5 (more sensitive) to 3 (less sensitive)

Automated verification

• npm test: run analysis, screenshot UI contract, persistence, multi-provider AI mock and Java API tests
• npm run test:reports: generate reports/tests.json, reports/tests.junit.xml and reports/tests.html
• npm run test:vscode: run 2 extension activation, command and configuration tests in the official VS Code Electron host; results are written to reports/vscode.junit.xml
• npm run verify:marketplace: run tests, reports, dependency audit, production build and VSIX file-list validation

Current limitations

• Each application identity stores one latest Before/After pair; repeated historical trend charts are not yet supported.
• The extension monitors JVMs in the same local Windows process namespace. Docker, remote hosts and WSL require a future remote connection mode.
• Heap dumps can pause the target JVM and require sufficient local disk space.
• AI findings are diagnostic hypotheses and should be verified with repeatable measurements before production changes.

Example JDK path:

C:\Program Files\Eclipse Adoptium\jdk-21.0.9.10-hotspot

Troubleshooting

No JVM applications are listed

• Confirm jps -l shows the application.
• Run VS Code and the target JVM as the same user.
• Do not run one process as Administrator and the other as a standard user.
• Docker and WSL JVMs are not in the same local process namespace as Windows VS Code.

JDK 21 cannot be found

Set jvmPulse.javaHome in VS Code settings, then run JVM Pulse: Restart Backend.

The monitor does not open

Open View → Output, select JVM Pulse, and review the backend error. Then confirm:

java -version
jps -l

AI analysis fails

• Run JVM Pulse: Set OpenAI API Key and enter a current key.
• Confirm the API account has billing or available credits.
• Check jvmPulse.aiModel if the configured model is unavailable to the API project.
• Ensure VS Code can access https://api.openai.com through the firewall or proxy.

If the message is fetch failed, the request did not complete. It does not confirm that the Base URL is correct. Check that the service is running and reachable from the VS Code Extension Host, then verify DNS, port, firewall/proxy and HTTPS certificate trust. Also confirm that the selected protocol matches the server endpoint and that the Base URL does not already end in /responses or /chat/completions.

For a custom OpenAI-compatible service, test basic connectivity from PowerShell:

Invoke-RestMethod `
  -Uri "https://example.com/v1/models" `
  -Headers @{ Authorization = "Bearer YOUR_API_KEY" }

• 401 or 403: the server is reachable, but the key or permissions are incorrect.
• 404: the Base URL or endpoint path is probably incorrect.
• Connection, DNS or certificate error: resolve network or TLS access before retrying the analysis.
• model not found: the endpoint is reachable, but the model ID is unavailable to that account or gateway.

Development

The server directory contains the packaged output of the sibling JVM-Pulse Java project. Refresh it after changing the backend:

.\build-server.ps1
npm.cmd install
npm.cmd run check
npm.cmd run compile

Press F5 to open an Extension Development Host, then click the JVM Pulse status-bar button in that new window.

Build a VSIX with:

npm.cmd run build:server
npx.cmd @vscode/vsce package --no-dependencies