java_heap_dump

Implementation Reference

• src/heap_seance_mcp/tools.py:240-266 (handler)

  The core implementation of java_heap_dump. Uses jmap to create a heap dump, validates the file exists, and returns the result with metrics (size_bytes) and a raw_artifact_path for downstream MAT analysis.

  def java_heap_dump(pid: int, live_only: bool = True, out_file: str | None = None) -> dict[str, Any]:
      try:
          require_binary("jmap", "Install OpenJDK 17+ so jmap is available.")
          path = Path(out_file) if out_file else _artifact_dir() / f"heap-{pid}-{_timestamp()}.hprof"
          path.parent.mkdir(parents=True, exist_ok=True)
  
          mode = "live" if live_only else "all"
          dump_opt = f"-dump:{mode},format=b,file={str(path)}"
          output = ensure_success(run_command(["jmap", dump_opt, str(pid)], timeout_s=900)).stdout
      except Exception as exc:  # noqa: BLE001
          return _command_failed(exc)
  
      if not path.exists():
          return warn_result(
              evidence=[f"Heap dump command succeeded but file is missing at {path}.", output.strip()[:800]],
              metrics={"pid": pid, "requested_file": str(path)},
              confidence="low",
              next_recommended_action="Retry with explicit writable out_file and sufficient disk space.",
          )
  
      return ok_result(
          evidence=[f"Heap dump created for PID {pid}: {path}"],
          metrics={"pid": pid, "size_bytes": path.stat().st_size, "live_only": live_only},
          confidence="medium",
          next_recommended_action="Run java_mat_suspects on this heap dump.",
          raw_artifact_path=str(path),
      )

• src/heap_seance_mcp/server.py:57-59 (registration)

  Registers java_heap_dump as an MCP tool via the @mcp.tool() decorator, delegating to tools.java_heap_dump.

  @mcp.tool()
  def java_heap_dump(pid: int, live_only: bool = True, out_file: str | None = None) -> dict[str, Any]:
      return tools.java_heap_dump(pid=pid, live_only=live_only, out_file=out_file)

• src/heap_seance_mcp/workflow.py:19-28 (helper)

  Imports java_heap_dump from tools module for use in the workflow orchestration.

  from .tools import (
      java_async_alloc_profile,
      java_class_histogram,
      java_gc_snapshot,
      java_heap_dump,
      java_jfr_start,
      java_jfr_summary,
      java_list_processes,
      java_mat_suspects,
  )

• src/heap_seance_mcp/workflow.py:208-208 (helper)

  Invocation site: calls java_heap_dump(pid=resolved_pid, live_only=True) as part of the automated heap analysis workflow.

  heap_result = java_heap_dump(pid=resolved_pid, live_only=True)