Skip to main content
Glama
Sign In
ej-technologies

JProfiler

by ej-technologies
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

attached_action

Perform point-in-time actions on a connected JVM—thread and monitor dumps, heap dumps, MBean snapshots—to diagnose stalls, deadlocks, or memory issues.

Instructions

Perform a point-in-time action on the connected JVM: thread and monitor dumps, heap marking and heap dumps, MBean snapshots, and starting or stopping subsystem recording. Requires a recording session started with attach or prepare_profiling. The action names and parameters are the same as for the actions of recordingConfig.triggers.

Input Schema

NameRequiredDescriptionDefault
cpuNoOptional for 'startRecording'/'stopRecording': include CPU recording.
labelNoOptional for 'mbeanSnapshot' and 'threadDump': label shown in the mbean.snapshots resp. threads.dumps dataset. In triggers the default is a name derived from the event.
actionYesThe action to perform on the attached JVM. 'threadDump': the current state and stack trace of every thread, grouped like in the JProfiler thread dumps view - use it when the app is slow but CPU usage is low, and take two dumps to find threads stuck at the same stack trace. 'monitorDump': the currently held and waited-on monitors with the involved threads and stack traces, plus deadlock detection over the current wait/own graph - deadlocks never appear in recorded monitor history because deadlocked events never finish, this dump is the way to find them, and no monitor recording is needed for it; attach-mode dumps show java.util.concurrent locks only, not intrinsic (synchronized) monitors. 'markHeap': mark all current heap objects as old, objects allocated afterwards count as new in heap dumps taken later in this session (generation argument of the heap datasets) - use it to bracket an operation of interest. 'mbeanSnapshot': capture the current JMX MBean attribute values into the session snapshot, for exploration usually unfiltered. 'heapDump': take a heap dump that becomes part of the session snapshot while the recording keeps running - expensive on large heaps, use create_heap_dump instead to stop the recording and analyze the heap immediately. 'startRecording'/'stopRecording': start or stop the recording of subsystems in this session, at least one of 'cpu', 'allocations', 'monitors', 'probes', 'complexity' is required - this does not end the session, use check_status with stopRecording for that. Dumps and snapshots taken by these actions become part of the session snapshot and are served by the threads.dumps, monitor.current, mbean.snapshots and heap.* datasets after the recording is stopped. For captures at events or from JVM start, configure actions with the same names in recordingConfig.triggers of attach or prepare_profiling.
filterNoOptional for 'mbeanSnapshot': regular expression matched against the domain and each property value of the MBean object names: "java.lang|com.mycompany.*" captures all MBeans in those domains, "Memory" the java.lang:type=Memory MBean. Without a filter all MBeans are captured, the right choice for exploration.
fullGcNoOptional for 'heapDump': run a full GC before the dump so only live objects are captured. Default true.
probesNoOptional for 'startRecording'/'stopRecording': probe names to start or stop, e.g. ["jdbc"], "custom:<fully qualified probe class name>" for custom probes of the profiled application, or "script:<name>" for a script probe defined in recordingConfig.advanced.scriptProbes.
monitorsNoOptional for 'startRecording'/'stopRecording': include monitor recording.
complexityNoOptional for 'startRecording'/'stopRecording': include complexity recording - requires recordingConfig.advanced.complexityMethods in the same session. Use it to bound the measurement window, for example scoped to a method with a methodInvocation trigger, or to exclude a warmup phase.
allocationsNoOptional for 'startRecording'/'stopRecording': include allocation recording.
includeVirtualThreadsNoOptional for 'threadDump': take a virtual thread dump that includes all virtual threads and the thread container hierarchy in addition to the platform threads. Default false (platform threads only). Virtual threads require JDK 21+.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv16.3.0

TDQS

A4.4/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full behavioral burden and does so well: it discloses the recording-session prerequisite, that dumps and snapshots become part of the session snapshot and are served by datasets after recording stops, and that startRecording/stopRecording does not end the session. The action-level details further explain expensive operations, attach-mode limitations, default full GC behavior, and virtual-thread requirements.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The main description is three front-loaded sentences with no wasted text: it names the capability, states the prerequisite, and gives the trigger-related cross-reference. The extensive action detail lives in the schema where it belongs.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a ten-parameter tool with no annotations and no output schema, the definition is largely complete: it explains the session prerequisite, where captured data goes, and how recording start/stop differs from ending a session. Minor gaps remain around error behavior and explicit return mechanics, but the core operational context is present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all ten parameters in detail, including action-specific meanings and defaults. The main description adds a useful cross-reference that action names and parameters match recordingConfig.triggers, but does not independently add syntax or semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: perform a point-in-time action on the connected JVM, and enumerates the action families (thread/monitor dumps, heap marking/dumps, MBean snapshots, subsystem recording). It also distinguishes this from the recording workflow by requiring a session started with attach or prepare_profiling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description clearly states the prerequisite: a recording session started with attach or prepare_profiling. The action parameter schema supplies explicit context for each action, including alternatives such as create_heap_dump for immediate heap analysis and check_status with stopRecording to end the session, though the main description itself does not broadly compare this tool to siblings like query or load_snapshot.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools