JVM Probe: Read Live Java Application State with NSP

The JVM probe lets your agents read live state from any running Java application on the host machine. It uses the JVM Tool Interface (JVMTI) — the same native API used by Java profilers and debuggers — to attach to a process at runtime, enumerate its loaded classes, and read field values directly from heap objects. You do not need access to the application’s source code, and you do not need to modify or restart the application.

Supported Applications

The JVM probe covers any JVM-based application. Known supported applications include:

Enterprise software: SAP ERP, Jenkins
Developer tools: IntelliJ IDEA, Eclipse
Infrastructure: Elasticsearch
Specialised GCS software: ArduPilot GCS (Java)
Any JVM application running on JDK 11 or later

How the JVM Probe Works

The JVM probe follows a three-stage process to attach and extract state.

Attach via AttachAPI — NSP loads a native JVMTI agent into the target Java process using the JVM’s AttachAPI. This does not require the JVM to have been started with any special flags and does not restart the application.
Enumerate classes and fields via JNI reflection — Once the JVMTI agent is loaded, it uses JNI (Java Native Interface) reflection to walk the class hierarchy, enumerate loaded class instances, and read field values from live heap objects. Type metadata is read directly from class files, so the probe understands the data types without needing compiled-in debug symbols.
Normalise to SSF JSON — Java objects and their field values are converted to the Substrate Schema Format using the class file type metadata, producing the same SubstrateState structure your agents receive from V8 and CLR probes.

Prerequisites

The JVM probe requires a JDK 11 or later installed on the host machine — a JRE alone is not sufficient. The AttachAPI that NSP uses to inject the JVMTI agent is part of the tools.jar / jdk.attach module, which ships only with the JDK. Verify your installation by running java -version and javac -version in a terminal; both commands must succeed.

What the Probe Reads

Once attached, the JVM probe exposes the following data in every SubstrateState:

Data Type	Description
Class instances	Live heap objects for all application-owned classes
Field values	Primitive and object field values, including nested objects
Method return values	Return values of selected accessor methods, captured on demand
Type metadata	Class name, field names, declared types — sourced from class files

Performance Characteristics

Metric	Value
Accuracy	>97%
Fast-path poll latency	~50 ms
Cold probe duration	3–90 s
Expected confidence range	`0.93 – 0.97`

Reading JVM App State

After the daemon detects a Java application and the cold probe completes, attach to it from the Python SDK using the application’s name.

import asyncio
import nelieo_nsp as nsp

async def main():
    async with nsp.NSPClient() as client:
        # Attach to a running Java application by name
        session = await client.attach("IntelliJ IDEA")

        # Read state with typed helpers
        project_name = session.get_str("project.name")
        open_files = session.get_int("editor.open_file_count")
        active_file = session.get_str("editor.active_file.path")

        print(f"Project: {project_name}")
        print(f"Open files: {open_files}")
        print(f"Active file: {active_file}")

asyncio.run(main())

You can attach to any JVM application by passing its app_name exactly as it appears in the GET /substrate/v1/apps response.

Verifying Probe Attachment

Call the apps endpoint after starting your Java application to confirm the daemon has detected and attached to it:

curl http://localhost:7842/substrate/v1/apps

{
  "total": 1,
  "apps": [
    {
      "pid": 8431,
      "app_id": "intellij-8431",
      "app_name": "IntelliJ IDEA",
      "runtime": "jvm",
      "probe_status": "active",
      "confidence": 0.95,
      "object_count": 41,
      "action_count": 8
    }
  ]
}

If probe_status is "attaching", the cold probe is still running. Wait a few seconds and try again — JVM cold probes on large applications like IntelliJ can take up to 90 seconds on the first attach.

Get Started

The Daemon

Runtime Probes

Security

Guides

Supported Applications

How the JVM Probe Works

Prerequisites

What the Probe Reads

Performance Characteristics

Reading JVM App State

Verifying Probe Attachment

​Supported Applications

​How the JVM Probe Works

​Prerequisites

​What the Probe Reads

​Performance Characteristics

​Reading JVM App State

​Verifying Probe Attachment

Supported Applications

How the JVM Probe Works

Prerequisites

What the Probe Reads

Performance Characteristics

Reading JVM App State

Verifying Probe Attachment