Build a Java Application Agent Using the JVM Probe

NSP’s JVM probe uses the standard JVMTI (JVM Tool Interface) — the same mechanism used by production profilers such as YourKit and JProfiler — to attach to running Java processes without restarting them. Once attached, you can read live field values and invoke methods from Python. This guide uses ArduPilot GCS (a Java-based ground control station) as the primary example, but the same patterns work for any supported JVM application.

How the JVMTI Probe Works

When the NSP daemon detects a JVM process, it uses the standard JVM Attach API to load a JVMTI agent into the running JVM. From that point on, the agent runs on a JVM thread — the target JVM is never paused. Field reads use JNI reflection (GetFieldID → GetObjectField) and method calls use CallObjectMethod. Results flow back to the daemon over a local socket.

The first time the JVMTI probe attaches to a JVM process it must enumerate all loaded classes, which takes 30–90 seconds (the “cold probe”). Subsequent daemon restarts reuse the persisted schema registry and attach in under 5 seconds.

Prerequisites

Java App Running

The target JVM application must already be running. The daemon scans for new processes every 5 seconds.

NSP Daemon Running

Run axon-daemon.exe run or start the Windows Service. The daemon and target JVM must run as the same OS user for the attach to succeed.

SDK Installed

pip install nelieo-nsp

No App Changes

You do not need to modify, recompile, or restart the Java application.

Supported Applications

The JVMTI probe works with any JVM process, but NSP ships built-in semantic mappings for these applications:

Application	Package Prefix	Notes
ArduPilot GCS	`com.ardupilot`	Full MAVLink telemetry state
Eclipse IDE	`org.eclipse`	Project and editor state
IntelliJ IDEA	`com.intellij`	Project / open file state
Jenkins	`hudson`, `jenkins`	Build pipeline and job state
Apache Kafka	`org.apache.kafka`	Topic and consumer group state
Elasticsearch	`org.elasticsearch`	Index and cluster health state
Spring Boot apps	`com.yourapp`	Via field/method introspection

For apps not on this list, NSP still attaches and extracts state — you’ll just use session.jvm.read_field() and session.jvm.invoke() directly rather than relying on pre-built semantic mappings.

Step 1 — Verify Detection

import asyncio
import nelieo_nsp as nsp

async def main():
    async with nsp.NSPClient(api_key="sk_nsp_...") as client:
        apps = await client.list_apps()
        for app in apps:
            print(f"{app.app_name} | runtime={app.runtime} | conf={app.confidence:.2f}")

asyncio.run(main())
# ArduPilot GCS | runtime=jvm | conf=0.95

If you see conf=0.40 and the runtime is jvm, the cold probe is still in progress. Wait 30–90 seconds and list again.

Step 2 — Connect and Read Normalized State

Use wait_for_app to handle the cold probe window gracefully:

import asyncio
import nelieo_nsp as nsp

async def main():
    async with nsp.NSPClient(api_key="sk_nsp_...") as client:
        session = await client.wait_for_app("ArduPilot GCS", timeout=120.0)
        print(f"Connected. Confidence: {session.confidence:.2f}")

        # Normalized SSF state — standard typed accessors
        alt   = session.get_float("flight.altitude_m")
        mode  = session.get_str("flight.mode")
        armed = session.get_bool("flight.is_armed")
        sats  = session.get_int("flight.gps.satellites")
        lat   = session.get_float("flight.gps.latitude")
        lon   = session.get_float("flight.gps.longitude")

        print(f"Position: ({lat:.6f}, {lon:.6f})  Alt: {alt:.1f}m")
        print(f"Mode: {mode}  Armed: {armed}  Satellites: {sats}")

asyncio.run(main())

Step 3 — Read Java Fields Directly via `session.jvm`

session.jvm is a JVMSessionProxy that lets you bypass the normalized state and read fields or call methods directly on live Java objects:

Read a field
Invoke a method

# Read a field from a specific class
heading = await session.jvm.read_field("com.ardupilot.GCS", "heading")
gs      = await session.jvm.read_field("com.ardupilot.GCS", "groundspeed")
mode    = await session.jvm.read_field("com.ardupilot.GCS", "flightMode")

print(f"Heading: {heading}°  GS: {gs:.1f}m/s  Mode: {mode}")

# Parameterless method
status = await session.jvm.invoke("com.ardupilot.GCS", "getStatusText")
print(f"Status: {status}")  # "OK: 3D GPS Fix"

# Method with arguments — Python types auto-coerced to JVM types
await session.jvm.invoke("com.ardupilot.GCS", "setMode", ["GUIDED"])

# Method with multiple doubles
await session.jvm.invoke(
    "com.ardupilot.WaypointManager",
    "addWaypoint",
    [34.0522, -118.2437, 50.0],  # lat (double), lon (double), alt (double)
)

Step 4 — Set a Flight Mode

# Set mode via JVM invoke
await session.jvm.invoke("com.ardupilot.GCS", "setMode", ["GUIDED"])

# Wait for the state to reflect the change
await session.wait_for(
    lambda s: s.get_str("flight.mode") == "GUIDED",
    timeout=10.0,
)
print("Mode set to GUIDED ✓")

Step 5 — Manage Waypoints

# Add a waypoint (lat, lon, alt_m)
await session.jvm.invoke(
    "com.ardupilot.WaypointManager",
    "addWaypoint",
    [34.0522, -118.2437, 50.0],
)

# Confirm the waypoint was registered
count = await session.jvm.invoke(
    "com.ardupilot.WaypointManager",
    "getWaypointCount",
)
print(f"Total waypoints: {count}")

Step 6 — Arm and Take Off

# Arm via NSP action — reversible, no verify required
result = await session.execute(
    "arm_motors",
    parameters={},
    verify=True,
    verify_expression="flight.is_armed == true",
    verify_timeout_ms=15000,
)
print(f"Armed: {result.success}")

# Take off to 50 m — irreversible; always use verify
result = await session.execute(
    "take_off",
    parameters={"altitude_m": 50.0},
    verify=True,
    verify_expression="flight.altitude_m > 45.0",
    verify_timeout_ms=30000,
)
print(f"Airborne: {result.success}")

Step 7 — Stream Telemetry

async def stream_telemetry():
    async with nsp.NSPClient(api_key="sk_nsp_...") as client:
        session = await client.wait_for_app("ArduPilot GCS", timeout=120.0)

        print("Streaming telemetry (Ctrl+C to stop)...")
        async with session.watch(auto_refresh_on_event=True) as stream:
            async for event in stream:
                if not any(k.startswith("flight.") for k in event.changed_keys):
                    continue

                alt  = session.get_float("flight.altitude_m")
                mode = session.get_str("flight.mode")
                batt = session.get_float("flight.battery_remaining")
                lat  = session.get_float("flight.gps.latitude")
                lon  = session.get_float("flight.gps.longitude")

                print(
                    f"[{event.captured_at}] "
                    f"Pos=({lat:.4f},{lon:.4f})  "
                    f"Alt={alt:.1f}m  Mode={mode}  Batt={batt:.0f}%"
                )

                # Safety: command RTL on critical battery
                if batt < 15.0:
                    print("⚠️  Critical battery — commanding RTL")
                    await session.jvm.invoke("com.ardupilot.GCS", "setMode", ["RTL"])

asyncio.run(stream_telemetry())

JVM Proxy Method Reference

session.jvm.read_field(class_name, field_name)

Reads a field value from the first matching instance of class_name in the JVM heap. Uses JNI GetFieldID → GetObjectField internally.

value = await session.jvm.read_field("com.ardupilot.GCS", "altitude")
# Returns: bool | int | float | str | None

session.jvm.invoke(class_name, method_name, args=[])

Invokes a method on the first matching instance of class_name. Arguments are auto-coerced from Python to JVM types. Returns the method’s return value coerced back to Python.

result = await session.jvm.invoke("com.ardupilot.GCS", "getStatusText")
# Returns: str | int | float | bool | None

JVM Error Reference

Error Code	Meaning	Fix
`jvm_not_attached`	JVMTI agent not loaded yet	Wait for cold probe to complete (up to 90s)
`jvm_class_not_found`	Class is not loaded in this JVM	Verify the fully-qualified class name
`jvm_method_not_found`	Method name or signature mismatch	Check the exact method name, including overloads
`jvm_invoke_timeout`	Method didn’t return within `timeout_ms`	Increase timeout or check for blocked JVM threads
`jvm_type_error`	Python argument can’t coerce to target JVM type	Check the table below

Python → JVM Type Coercion

Python Type	JVM Type
`bool`	`boolean` / `Boolean`
`int`	`int`, `long`, `short`, `byte`
`float`	`double`, `float`
`str`	`String`
`list`	`List<T>`, `T[]`
`dict`	`Map<String, Object>`
`None`	`null`

Get Started

The Daemon

Runtime Probes

Security

Guides

How the JVMTI Probe Works

Prerequisites

Java App Running

NSP Daemon Running

SDK Installed

No App Changes

Supported Applications

Step 1 — Verify Detection

Step 2 — Connect and Read Normalized State

Step 3 — Read Java Fields Directly via `session.jvm`

Step 4 — Set a Flight Mode

Step 5 — Manage Waypoints

Step 6 — Arm and Take Off

Step 7 — Stream Telemetry

JVM Proxy Method Reference

JVM Error Reference

Python → JVM Type Coercion

​How the JVMTI Probe Works

​Prerequisites

Java App Running

NSP Daemon Running

SDK Installed

No App Changes

​Supported Applications

​Step 1 — Verify Detection

​Step 2 — Connect and Read Normalized State

​Step 3 — Read Java Fields Directly via session.jvm

​Step 4 — Set a Flight Mode

​Step 5 — Manage Waypoints

​Step 6 — Arm and Take Off

​Step 7 — Stream Telemetry

​JVM Proxy Method Reference

​JVM Error Reference

​Python → JVM Type Coercion

How the JVMTI Probe Works

Prerequisites

Supported Applications

Step 1 — Verify Detection

Step 2 — Connect and Read Normalized State

Step 3 — Read Java Fields Directly via `session.jvm`

Step 4 — Set a Flight Mode

Step 5 — Manage Waypoints

Step 6 — Arm and Take Off

Step 7 — Stream Telemetry

JVM Proxy Method Reference

JVM Error Reference

Python → JVM Type Coercion