JProfiler帮助文档

分析 JVM

要分析一个 JVM，JProfiler 的分析代理必须被加载到该 JVM 中。这可以通过两种不同的方式实现：在启动脚本中指定 -agentpath VM 参数，或者使用 attach API 将代理加载到已在运行的 JVM 中。

JProfiler 支持这两种模式。添加 VM 参数是首选的分析方式，集成向导、IDE 插件以及从 JProfiler 内部启动 JVM 的会话配置均采用此方式。 Attach 既支持本地方式，也支持通过 SSH 进行远程操作。

-agentpath VM 参数

了解加载分析代理的 VM 参数是如何构成的很有帮助。-agentpath 是 JVM 提供的一个通用 VM 参数，用于加载任何使用 JVMTI 接口的原生库。由于分析接口 JVMTI 是一个原生接口，分析代理必须是一个原生库。这意味着您只能在明确支持的平台上进行分析。 32 位和 64 位 JVM 也需要不同的原生库。而 Java 代理则使用 -javaagent VM 参数加载，只能访问有限的功能集。

在 -agentpath: 之后，附加原生库的完整路径名。还有一个等效的参数 -agentlib:，您只需指定平台相关的库名，但这样您必须确保该库包含在库路径中。在库路径之后，您可以添加一个等号并向代理传递选项，选项之间用逗号分隔。例如，在 Linux 上，完整参数可能如下所示：

-agentpath:/opt/.jprofiler16/bin/linux-x64/libjprofilerti.so=port=8849,nowait

第一个等号将路径名与参数分隔开，第二个等号是参数 port=8849 的一部分。这个常用参数定义了分析代理监听来自 JProfiler GUI 连接的端口。8849 实际上是默认端口，因此您也可以省略该参数。但如果您想在同一台机器上分析多个 JVM，则必须分配不同的端口。 IDE 插件和本地启动的会话会自动分配此端口，而对于集成向导，您必须明确选择端口。

第二个参数 nowait 告知分析代理不要在启动时阻塞 JVM，也不要等待 JProfiler GUI 连接。启动时阻塞是默认行为，因为分析代理不是通过命令行参数接收其配置文件设置，而是从 JProfiler GUI 或配置文件中获取。命令行参数仅用于引导分析代理，告知其如何启动以及传递调试标志。

在某些情况下，需要在启动时设置配置文件设置，这可能需要一些手动操作才能实现。

默认情况下，JProfiler 代理将通信 socket 绑定到回环接口。您可以添加选项 address=[IP address] 以选择特定接口，或使用 address=0.0.0.0 将通信 socket 绑定到所有可用的网络接口。如果您希望从 Docker 容器中发布分析端口，这可能是必要的。

本地启动的会话

与 IDE 中的"运行配置"类似，您可以直接在 JProfiler 中配置本地启动的会话。您指定类路径、主类、工作目录、VM 参数和启动参数，JProfiler 会为您启动该会话。 JProfiler 附带的所有演示会话都是本地启动的会话。

一种特殊的启动模式是"Web Start"，您选择 JNLP 文件的 URL，JProfiler 将启动一个 JVM 来对其进行分析。此功能支持 OpenWebStart，不支持 Java 9 之前的 Oracle JRE 中的旧版 WebStart。

本地启动的会话可以通过转换向导转换为独立会话，方法是从主菜单调用 Session→Conversion Wizards。Convert Application Session to Remote 只需创建一个启动脚本并将 -agentpath VM 参数插入到 Java 调用中。 Convert Application Session to Offline 为离线分析创建启动脚本，这意味着配置在启动时加载，不需要 JProfiler GUI。 Convert Application Session to Redistributed Session 执行相同的操作，但会在其旁边创建一个 jprofiler_redist 目录，其中包含分析代理和配置文件，以便您可以将其发送到未安装 JProfiler 的其他机器上。

如果您自己开发被分析的应用程序，请考虑使用 IDE 集成而不是启动会话。这样会更方便，并为您提供更好的源代码导航。如果您不是自己开发该应用程序，但已有启动脚本，请考虑使用远程集成向导。它会告诉您需要添加到 Java 调用中的确切 VM 参数。

集成向导

JProfiler 的集成向导处理许多知名的第三方容器，这些容器具有可以通过编程方式修改以包含额外 VM 参数的启动脚本或配置文件。对于某些产品，可以生成通过参数或环境变量传递 VM 参数的启动脚本。

在所有情况下，您都必须找到第三方产品中的某个特定文件，以便 JProfiler 具有执行修改所需的上下文。某些通用向导只会给出您需要执行的操作说明，以便启用分析。

每个集成向导的第一步是选择在本地机器还是远程机器上进行分析。对于本地机器，您需要提供的信息较少，因为 JProfiler 已经知道平台、JProfiler 的安装位置以及其配置文件的位置。

一个重要的决定是上面讨论的"启动模式"。默认情况下，配置文件设置在启动时从 JProfiler UI 传输，但您也可以告知分析代理让 JVM 立即启动。在后一种情况下，配置文件设置可以在 JProfiler GUI 连接后应用。

但是，您也可以指定一个包含配置文件设置的配置文件，这样效率更高。这在 Config synchronization 步骤中完成。这种情况下的主要问题是，每次在本地编辑配置文件设置时，都必须将配置文件与远程端同步。最优雅的方式是在 Remote address 步骤中通过 SSH 连接到远程机器，这样配置文件就可以通过 SSH 自动传输。

在集成向导结束时，将创建一个会话，该会话开始分析，并且在非通用情况下，还会启动第三方产品，例如应用服务器。

外部启动脚本由会话配置对话框的 Application settings 选项卡上的 Execute start script 和 Execute stop script 选项处理，可以通过选中 Open browser with URL 复选框来显示 URL。这也是您可以更改远程机器地址和配置同步选项的地方。

集成向导都处理被分析 JVM 在远程机器上运行的情况。但是，当需要修改配置文件或启动脚本时，您必须将其复制到本地机器，并将修改后的版本传回远程机器。直接在远程机器上运行命令行工具 jpintegrate 并让其就地执行修改可能更为方便。 jpintegrate 需要完整安装 JProfiler，并且与 JProfiler GUI 具有相同的 JRE 要求。

当启动远程分析会话时发生错误，请参阅故障排除指南，其中提供了可用于解决问题的步骤清单。

IDE 集成

分析应用程序最便捷的方式是通过 IDE 集成。如果您通常在开发过程中从 IDE 启动应用程序， IDE 已经拥有所有必要信息，JProfiler 插件可以直接添加用于分析的 VM 参数，在必要时启动 JProfiler，并将被分析的 JVM 连接到 JProfiler 主窗口。

所有 IDE 集成都包含在 JProfiler 安装目录的 integrations 目录中。原则上，该目录中的归档文件可以通过各 IDE 的插件安装机制手动安装。但是，安装 IDE 集成的首选方式是从主菜单调用 Session→IDE integrations。

从 IDE 启动的分析会话不会在 JProfiler 中获得自己的会话条目，因为此类会话无法从 JProfiler GUI 启动。配置文件设置根据 IDE 中的设置，按项目或按运行配置持久化。

当连接到 IDE 时，JProfiler 会在工具栏中显示一个窗口切换器，方便您跳回 IDE 中的关联窗口。所有 Show Source 操作现在会直接在 IDE 中显示源代码，而不是在 JProfiler 的内置源代码查看器中显示。

IDE 集成在后续章节中有详细讨论。

用于 AI 代理的 MCP 服务器

JProfiler 包含一个 MCP 服务器，允许 AI 编码代理（例如 Claude Code、Gemini CLI 或 Junie）使用 JProfiler 的分析和分析功能。AI 代理可以启动并分析 Java 进程，attach 到本地运行的 JVM 或 Docker 容器中的 JVM，创建堆转储并分析现有快照。MCP 集成通过从主菜单调用 Session→AI Agent Integrations 进行设置。

Attach 模式

您不一定需要事先决定是否要分析某个 JVM。借助 JProfiler 的 attach 功能，您可以选择一个正在运行的 JVM 并动态加载分析代理。虽然 attach 模式很方便，但它有一些您应该注意的缺点：

您必须从正在运行的 JVM 列表中识别出您想要分析的 JVM。如果同一台机器上运行了很多 JVM，这有时会比较棘手。
存在额外的开销，因为可能需要重新定义许多类以添加插桩。
JProfiler 中的某些功能在 attach 模式下不可用。这主要是因为 JVMTI 的某些功能只能在 JVM 初始化时开启，在 JVM 生命周期的后期阶段不可用。
某些功能需要对大量类进行插桩。在类加载时进行插桩开销较低，而在类已加载后再添加插桩则开销较高。此类功能在使用 attach 模式时默认禁用。
Attach 功能支持 OpenJDK JVM、版本 6 或更高版本的 Oracle JVM、较新的 OpenJ9 JVM （8u281+、11.0.11+ 或 Java 17+）或基于此类版本的 IBM JVM。VM 参数 -XX:+PerfDisableSharedMem 和 -XX:+DisableAttachMechanism 不得为该 JVM 指定。

JProfiler 启动中心中的 Quick Attach 选项卡列出了所有可以被分析的 JVM。列表条目的背景颜色指示分析代理是否已加载、JProfiler GUI 当前是否已连接，或者是否已配置离线分析。

当您启动分析会话时，可以在会话设置对话框中配置配置文件设置。当您反复分析同一进程时，您不希望一遍又一遍地重新输入相同的配置，因此，当您关闭使用 quick attach 功能创建的会话时，可以保存一个持久会话。下次您想分析此进程时，从 Start Session 选项卡而不是 Quick Attach 选项卡启动已保存的会话。您仍然需要选择一个正在运行的 JVM，但配置文件设置与您之前已配置的相同。

Attach 到本地服务

JVM 中的 attach API 要求调用进程与您想要 attach 的进程以相同用户身份运行，因此 JProfiler 显示的 JVM 列表仅限于当前用户。由不同用户启动的进程大多是服务。 Attach 到服务的方式在 Windows、Linux 和基于 Unix 的平台上有所不同。

在 Windows 上，attach 对话框有一个 Show Services 按钮，可列出所有本地运行的服务。JProfiler 启动桥接可执行文件，以便能够 attach 到这些进程，无论它们以哪个用户身份运行。

在 Linux 上，JProfiler 支持通过大多数 Linux 发行版中包含的 PolicyKit 直接在 UI 中切换用户。通过在 attach 对话框中单击 Switch user，您可以输入不同的用户名并通过系统密码对话框进行身份验证。

在包括 macOS 在内的基于 Unix 的平台上，您可以使用 su 或 sudo 以不同用户身份执行命令行工具 jpenable，具体取决于您的 Unix 变体或 Linux 发行版。在 macOS 和基于 Debian 的 Linux 发行版（如 Ubuntu）上，使用 sudo。

使用 sudo，调用

sudo -u userName jpenable

使用 su，所需的命令行为

su userName -c jpenable

jpenable 将让您选择 JVM 并告知您分析代理正在监听的端口。之后，您可以使用 JProfiler UI 中的本地会话进行连接，或使用直接连接到 jpenable 给出端口的 SSH 连接。

Attach 到远程机器上的 JVM

分析中最复杂的设置是远程分析——JProfiler GUI 在您的本地机器上运行，而被分析的 JVM 在另一台机器上运行。对于将 -agentpath VM 参数传递给被分析 JVM 的设置，您必须在远程机器上安装 JProfiler，并在本地机器上设置远程会话。使用 JProfiler 中的远程 attach 功能，则不需要进行此类修改。您只需要 SSH 凭据即可登录远程机器。

SSH 连接使 JProfiler 能够上传在 "安装 JProfiler" 帮助主题中讨论的代理包，并在远程机器上执行其中包含的命令行工具。您不需要在本地机器上设置 SSH，JProfiler 附带了自己的实现。在最简单的设置中，您只需定义主机、用户名和身份验证。

通过 SSH 连接，JProfiler 可以自动发现正在运行的 JVM，或连接到分析代理已在监听的特定端口。对于后一种情况，您可以如上所述在远程机器上使用 jpenable 或 jpintegrate，为分析准备特定的 JVM。然后，SSH 远程 attach 可以配置为直接连接到已配置的分析端口。

自动发现将列出远程机器上以 SSH 登录用户身份启动的所有 JVM。在大多数情况下，这不会是启动您想要分析的服务的用户。由于启动服务的用户通常不允许进行 SSH 连接， JProfiler 添加了一个 Switch User 超链接，让您可以使用 sudo 或 su 切换到该用户。

在复杂的网络拓扑中，您有时无法直接连接到远程机器。在这种情况下，您可以在 GUI 中告知 JProfiler 使用多跳 SSH 隧道进行连接。在 SSH 隧道末端，您可以建立一个直接的网络连接，通常连接到"127.0.0.1"。

对于其他身份验证机制，您可以使用 OpenSSH 隧道模式。您输入主机名的方式与使用 OpenSSH 可执行文件时在命令行上输入的方式相同。这也可以是 OpenSSH 配置文件中配置的别名。除主机名外，还可以选择性地指定端口和用户名。在 Windows 上，仅支持 Microsoft 内置的 OpenSSH 客户端。

SSH 选项文本字段接受您在命令行上指定的 OpenSSH 可执行文件的任意附加参数。当您按照教程中的说明操作时，这特别有用，例如如何通过 AWS Session Manager 隧道传输 SSH 连接。

HPROF 快照只能针对以 SSH 登录用户身份启动的 JVM 进行。这是因为 HPROF 快照需要一个中间文件，该文件以启动 JVM 的用户的访问权限写入。出于安全原因，无法将文件权限转移给 SSH 登录用户以供下载。完整分析会话不存在此限制。

Attach 到在 Docker 容器中运行的 JVM

Docker 容器通常没有安装 SSH 服务器，虽然您可以在 Docker 容器中使用 jpenable，但除非您在 Dockerfile 中指定了分析端口，否则该端口将无法从外部访问。

在 JProfiler 中，您可以通过在 quick attach 对话框中选择 Docker 容器， attach 到在 Windows 或 macOS 上本地 Docker Desktop 安装中运行的 JVM。默认情况下，JProfiler 会自动检测 docker 可执行文件的路径。或者，您可以在通用设置对话框的"External tools"选项卡上进行配置。

选择容器后，将显示在 Docker 容器内运行的所有 JVM。当您选择一个 JVM 时， JProfiler 将使用 Docker 命令自动在所选容器中安装分析代理，为分析准备 JVM，并将分析协议隧道传输到外部。

对于远程 Docker 安装，您可以使用 SSH 远程 attach 功能，然后选择远程机器上的 Docker 容器。如果登录用户不在 docker 组中，您可以先按上述方式切换用户。

使用远程 attach 对话框中的 Select container 超链接，您可以选择一个正在运行的 Docker 容器并显示其中运行的所有 JVM。

Attach 到在 Kubernetes 集群上运行的 JVM

要分析在 Kubernetes 集群上运行的 JVM，JProfiler 使用 kubectl 命令行工具，既用于发现 Pod 和容器，也用于连接到容器、列出其 JVM，最终连接到所选的 JVM。

kubectl 命令行工具可能在您的本地计算机上可用，或者在您可以通过 SSH 访问的远程机器上可用。JProfiler 直接支持这两种场景。对于本地安装，JProfiler 将尝试自动检测 kubectl 的路径，但您可以在通用设置对话框的"External tools"选项卡上配置明确的路径。

JProfiler 在一个三级树形结构中列出所有检测到的容器。顶层是命名空间节点，包含检测到的 Pod 的子节点。叶节点是容器本身，必须选择其中一个才能继续选择正在运行的 JVM。

kubectl 可能需要额外的命令行身份验证选项才能连接到 Kubernetes 集群。这些选项可以在容器选择对话框顶部输入。由于这些选项可能是敏感信息，只有在您明确选中复选框以在重启后记住它们时，才会将其保存到磁盘。取消选中此复选框将立即清除之前保存的所有信息。

设置正在运行的 JVM 的显示名称

在 JVM 选择表中，显示的进程名称是被分析 JVM 的主类及其参数。对于由 exe4j 或 install4j 生成的启动器，将显示可执行文件名称。

如果您希望自己设置显示名称，例如，因为您有几个具有相同主类的进程，否则无法区分，您可以设置 VM 参数 -Djprofiler.displayName=[name]。如果名称包含空格，请使用单引号： -Djprofiler.displayName='My name with spaces'，如有必要，请用双引号将整个 VM 参数括起来。除 -Djprofiler.displayName 外，JProfiler 还识别 -Dvisualvm.display.name。