jattach

README

jattach

JVM Dynamic Attach utility

The utility to send commands to a JVM process via Dynamic Attach mechanism.

All-in-one jmap + jstack + jcmd + jinfo functionality in a single tiny program.
No installed JDK required, works with just JRE. Supports Linux containers.

This is the lightweight native version of HotSpot Attach API
https://docs.oracle.com/javase/8/docs/jdk/api/attach/spec/

Supported commands:

• load : load agent library
• properties : print system properties
• agentProperties : print agent properties
• datadump : show heap and thread summary
• threaddump : dump all stack traces (like jstack)
• dumpheap : dump heap (like jmap)
• inspectheap : heap histogram (like jmap -histo)
• setflag : modify manageable VM flag
• printflag : print VM flag
• jcmd : execute jcmd command

Download

Binaries are available on the Releases page.

On some platforms, you can also install jattach with a package manager.

Examples

Load native agent

$ jattach <pid> load <.so-path> { true | false } [ options ]

Where true means that the path is absolute, false -- the path is relative.

options are passed to the agent.

Load Java agent

Java agents are loaded by the special built-in native agent named instrument, which takes .jar path and its arguments as a single options string.

$ jattach <pid> load instrument false "javaagent.jar=arguments"

List available jcmd commands

$ jattach <pid> jcmd help -all

Installation

Debian, Ubuntu

On Debian and Ubuntu, you can install jattach from the official repository:

# apt install jattach

Alpine Linux

On Alpine Linux, you can install jattach package from the edge/community repository:

# apk add --no-cache jattach --repository http://dl-cdn.alpinelinux.org/alpine/edge/community/

Archlinux

jattach package can be installed from AUR using one of AUR helpers, e.g., yay:

# yay -S jattach

FreeBSD

On FreeBSD, you can use the following command to install jattach:

# pkg install jattach

Documentation

Overview

Package jattach provides Go bindings for the jattach utility, which allows sending commands to running JVM processes via the Dynamic Attach mechanism.

This package wraps the native C implementation of jattach using CGo, providing a type-safe, idiomatic Go API for interacting with Java Virtual Machines.

Supported platforms: Linux, macOS, and Windows on amd64, arm64, and 386 architectures.

Example usage:

// Get thread dump
output, err := jattach.ThreadDump(12345)
if err != nil {
	log.Fatal(err)
}
fmt.Println(output)

// Load Java agent
err = jattach.LoadAgent(12345, "/path/to/agent.jar", "options", false)
if err != nil {
	log.Fatal(err)
}

For more information about jattach commands, see: https://github.com/jattach/jattach

Index

• func Attach(pid int, cmd Command, args ...string) (int, error)
• func AttachWithOutput(pid int, cmd Command, args ...string) (string, int, error)
• func ExecuteJcmd(pid int, jcmdArgs ...string) (string, error)
• func GetAgentProperties(pid int) (string, error)
• func GetHeapHistogram(pid int) (string, error)
• func GetSystemProperties(pid int) (string, error)
• func GetThreadDump(pid int) (string, error)
• func HeapDump(pid int, filepath string) error
• func LoadAgent(pid int, agentPath string, options string, absolute bool) error
• func PrintVMFlag(pid int, flagName string) (string, error)
• func SetVMFlag(pid int, flagName string, value string) error
• type Command

Examples

• Attach
• AttachWithOutput
• ExecuteJcmd
• GetHeapHistogram
• GetSystemProperties
• GetThreadDump
• HeapDump
• LoadAgent

Functions

func Attach

func Attach(pid int, cmd Command, args ...string) (int, error)

Attach sends a command to a JVM process. The command output is printed to stdout, errors to stderr. Returns the exit code from the JVM command.

Example

ExampleAttach demonstrates low-level attach with custom command.

package main

import (
	"fmt"
	"log"

	jattach "github.com/vlsi/jattach/v2"
)

func main() {
	pid := 12345 // Replace with actual JVM PID

	// Execute a command and print output to stdout
	exitCode, err := jattach.Attach(pid, jattach.Properties)
	if err != nil {
		log.Fatal(err)
	}

	if exitCode != 0 {
		fmt.Printf("Command failed with exit code %d\n", exitCode)
	}
}

func AttachWithOutput

func AttachWithOutput(pid int, cmd Command, args ...string) (string, int, error)

AttachWithOutput sends a command to a JVM process and captures the output. Unlike Attach, this function captures both stdout and stderr from the C code via a pipe passed directly as file descriptors. Returns the captured output, exit code, and any error.

Example

ExampleAttachWithOutput demonstrates capturing command output.

package main

import (
	"fmt"
	"log"

	jattach "github.com/vlsi/jattach/v2"
)

func main() {
	pid := 12345 // Replace with actual JVM PID

	// Execute command and capture output
	output, exitCode, err := jattach.AttachWithOutput(pid, jattach.Jcmd, "VM.flags")
	if err != nil {
		log.Fatal(err)
	}

	if exitCode != 0 {
		fmt.Printf("Command failed with exit code %d\n", exitCode)
		return
	}

	fmt.Println(output)
}

func ExecuteJcmd

func ExecuteJcmd(pid int, jcmdArgs ...string) (string, error)

ExecuteJcmd executes an arbitrary jcmd command on the target JVM. The jcmdArgs are passed directly to jcmd.

Example:

output, err := jattach.ExecuteJcmd(12345, "VM.flags", "-all")

Example

ExampleExecuteJcmd demonstrates how to execute a jcmd command.

package main

import (
	"fmt"
	"log"

	jattach "github.com/vlsi/jattach/v2"
)

func main() {
	pid := 12345 // Replace with actual JVM PID

	// Get VM version
	output, err := jattach.ExecuteJcmd(pid, "VM.version")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(output)
}

func GetAgentProperties

func GetAgentProperties(pid int) (string, error)

GetAgentProperties retrieves agent properties from the target JVM.

func GetHeapHistogram

func GetHeapHistogram(pid int) (string, error)

GetHeapHistogram retrieves a heap histogram from the target JVM. This is equivalent to running jmap -histo.

Example

ExampleGetHeapHistogram demonstrates how to get a heap histogram.

package main

import (
	"fmt"
	"log"

	jattach "github.com/vlsi/jattach/v2"
)

func main() {
	pid := 12345 // Replace with actual JVM PID

	histogram, err := jattach.GetHeapHistogram(pid)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(histogram)
}

func GetSystemProperties

func GetSystemProperties(pid int) (string, error)

GetSystemProperties retrieves all system properties from the target JVM.

Example

ExampleGetSystemProperties demonstrates how to retrieve system properties.

package main

import (
	"fmt"
	"log"

	jattach "github.com/vlsi/jattach/v2"
)

func main() {
	pid := 12345 // Replace with actual JVM PID

	props, err := jattach.GetSystemProperties(pid)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(props)
}

func GetThreadDump

func GetThreadDump(pid int) (string, error)

GetThreadDump retrieves a thread dump from the target JVM. This is equivalent to running jstack.

Example

ExampleGetThreadDump demonstrates how to get a thread dump from a JVM process.

package main

import (
	"fmt"
	"log"

	jattach "github.com/vlsi/jattach/v2"
)

func main() {
	pid := 12345 // Replace with actual JVM PID

	output, err := jattach.GetThreadDump(pid)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(output)
}

func HeapDump

func HeapDump(pid int, filepath string) error

HeapDump creates a heap dump file at the specified path. The filepath should be accessible by the target JVM process.

Example

ExampleHeapDump demonstrates how to create a heap dump.

package main

import (
	"fmt"
	"log"

	jattach "github.com/vlsi/jattach/v2"
)

func main() {
	pid := 12345 // Replace with actual JVM PID

	err := jattach.HeapDump(pid, "/tmp/heapdump.hprof")
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Heap dump created at /tmp/heapdump.hprof")
}

func LoadAgent

func LoadAgent(pid int, agentPath string, options string, absolute bool) error

LoadAgent loads a native agent (.so) or Java agent (.jar) into the target JVM.

Parameters:

• pid: Process ID of the target JVM
• agentPath: Path to the agent file (must be accessible by the target JVM)
• options: Agent options string (can be empty)
• absolute: If true, agentPath is treated as absolute; if false, relative to JVM working directory

Example

ExampleLoadAgent demonstrates how to load a Java agent.

package main

import (
	"fmt"
	"log"

	jattach "github.com/vlsi/jattach/v2"
)

func main() {
	pid := 12345 // Replace with actual JVM PID

	// Load agent with absolute path
	err := jattach.LoadAgent(pid, "/path/to/agent.jar", "option1,option2", true)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println("Agent loaded successfully")
}

func PrintVMFlag

func PrintVMFlag(pid int, flagName string) (string, error)

PrintVMFlag prints the value of a VM flag.

func SetVMFlag

func SetVMFlag(pid int, flagName string, value string) error

SetVMFlag sets a manageable VM flag to a new value.

Types

type Command

type Command string

Command represents a JVM attach command type.

const (
	// Load loads a native or Java agent into the target JVM
	Load Command = "load"

	// ThreadDump prints all stack traces (equivalent to jstack)
	ThreadDump Command = "threaddump"

	// DumpHeap dumps the heap (equivalent to jmap)
	DumpHeap Command = "dumpheap"

	// InspectHeap prints heap histogram (equivalent to jmap -histo)
	InspectHeap Command = "inspectheap"

	// DataDump shows heap and thread summary
	DataDump Command = "datadump"

	// Properties prints system properties
	Properties Command = "properties"

	// AgentProperties prints agent properties
	AgentProperties Command = "agentProperties"

	// SetFlag modifies a manageable VM flag
	SetFlag Command = "setflag"

	// PrintFlag prints a VM flag value
	PrintFlag Command = "printflag"

	// Jcmd executes an arbitrary jcmd command
	Jcmd Command = "jcmd"
)

Supported JVM attach commands