第 3 章 配置 Java 应用程序
要启用 Cryostat 收集、存储和分析 Java Flight Recorder (JFR)数据,有关 Java 虚拟机(JVM)上运行的目标应用程序的数据,您必须配置应用程序,以便 Cryostat 可以检测并连接到它们。
您可以使用以下方法配置应用程序:
- Cryostat 代理
您可以使用 Cryostat 代理组件检测和连接,后者作为 Java Instrumentation Agent 实现,并充当 JVM 上运行的应用程序的插件。
Cryostat 代理提供了一个 HTTP API,Cryostat 服务器可用作应用程序 JMX 端口的替代选择。通过将正确配置的 Cryostat 代理附加到您部署的工作负载应用程序中,您可以使用完整的 Cryostat 功能集,而无需目标应用程序公开 JMX 端口。
与 JMX 端口相比,Cryostat 代理的 HTTP API 可以提供以下优点:
- 由于 API 面区域减少,安全性更高
- 由于 Cryostat 代理的双角色作为 Cryostat 发现插件,部署灵活性
如需更多信息 ,请参阅使用 Cryostat 代理。
- 远程 Java 管理扩展(JMX)连接
您可以配置目标应用程序以允许 Java 管理扩展(JMX)连接。这种类型的配置使用 OpenShift Service 检测和 JMX 进行连接。
JMX 是 JVM 上的标准功能,您可以使用它监控和管理 JVM 上运行的目标应用程序。要使 Cryostat 使用 JMX,您必须在启动 JVM 时启用和配置 JMX,因为 Cryostat 需要目标应用程序来公开 JMX 端口。
Cryostat 通过此 JMX 端口与目标应用程序通信,以启动和停止 JFR 记录并通过网络拉取 JFR 数据,启用 Cryostat 存储和分析这个 JFR 数据。远程监控需要安全性,以确保未授权的人员无法访问应用程序。Cryostat 会提示您输入您的凭证,然后 Cryostat 可以访问任何应用程序的 JFR 记录。
如需更多信息,请参阅配置应用程序以使用 JMX 连接。
- Cryostat 代理和 JMX 混合
您可以将目标应用程序配置为使用混合方法,其中使用 Cryostat 代理和 JMX。使用此方法,您可以使用 Cryostat 代理来检测目标应用程序和 JMX 来公开 JFR 数据到 Cryostat,从而获得更大的灵活性。
例如,您可以使用代理来检测应用程序,而无需依赖特定的端口号,并使用 JMX 连接根据需要启动和停止 JFR flight 记录。
如果 Cryostat 代理检测到也会在应用程序上配置 JMX,代理会将自身发布到带有代理 HTTP API 定义和 JMX URL 定义的 Cryostat 服务器。在这种情况下,您可以使用您喜欢的任何配置选项。
如需更多信息,请参阅配置应用程序以使用 Cryostat 代理和 JMX 连接。
3.1. 使用 Cryostat 代理
Cryostat 代理作为 Java Instrumentation Agent 实施,该代理充当 JVM 上运行的应用程序的插件。Cryostat 代理提供了一个 HTTP API,它提供比 JMX 端口更大的部署灵活性,因为代理的双角色作为发现插件。您可以将目标应用程序配置为使用代理的 HTTP API 来通过 Cryostat 检测和连接。
3.1.1. Cryostat 代理功能
Red Hat build of Cryostat 提供了 Cryostat 代理的不同发行版,并支持部署和使用代理的不同方法。请考虑以下信息,以帮助您确定 Cryostat 代理部署的类型以及最适合您的需求的用例。
3.1.1.1. 自动或手动配置 Cryostat 代理
您可以使用 Cryostat Operator 自动配置 Cryostat 代理。或者,如果您愿意,您可以选择手动配置 Cryostat 代理。
由于红帽目前正在调查的已知问题,在 Cryostat 4.0 中无法进行手动配置。红帽计划在以后的发行版本中解决这个问题。如果您希望应用程序使用 4.0 发行版中的 Cryostat 代理,则必须允许 Cryostat Operator 自动配置 Cryostat 代理。
自动配置代理
从 Cryostat 4.0 开始,您可以使用 Cryostat Operator 自动配置 Cryostat 代理。要启用此功能,您可以在应用程序部署中添加 cryostat.io/name
和 cryostat.io/namespace
标签来识别 pod 应使用哪个 Cryostat 实例。当 Cryostat Operator 检测到应用程序部署具有 cryostat.io/name
和 cryostat.io/namespace
标签时,Operator 会将包含代理 JAR 文件的卷挂载到此应用程序。
作为此自动配置功能的一部分,Cryostat 使用一个 变异准入 Webhook,在创建时修改 pod 来注入 Cryostat 代理。Webhook 还会配置代理来自动连接到所选 Cryostat 实例。在这种情况下,只有包含所需 cryostat.io/name
和 cryostat.io/namespace
标签的 pod 调用 Webhook,这有助于简化带有任意 pod 的 Cryostat 代理的设置。另外,Operator 仅在 Cryostat 实例的目标命名空间列表中的应用程序部署中指定了这些标签。否则,Operator 不会将应用程序配置为与这个 Cryostat 实例通信。
Webhook 使用基于 container 的 Cryostat 代理(cryostat-agent-init
)来自动配置和将代理注入所选 pod。Webhook 使用 cryostat-agent-init
容器镜像不再需要用户从 Red Hat Maven 存储库下载代理 JAR 文件。
有关允许 Cryostat Operator 自动配置代理的更多信息,请参阅通过 Cryostat Operator 启用代理配置。
手动配置代理
作为自动配置功能的替代选择,您可以选择手动配置 Cryostat 代理(如果您愿意)。但是,与 Cryostat Operator 自动配置相比,手动配置会造成更多时间开销,以及错误配置的可能性。在 Cryostat 4.0 之前,手动配置方法是唯一可用于配置 Cryostat 代理的方法。
本节仅用于信息。由于红帽目前正在调查的已知问题,在 Cryostat 4.0 中无法进行手动配置。如果您希望应用程序使用 4.0 发行版中的 Cryostat 代理,则必须允许 Cryostat Operator 自动配置 Cryostat 代理。
对于代理配置,Red Hat build of Cryostat 4.0 分发了 Cryostat 代理的 JAR 文件的两个不同变体:
一个一体化的"shaded" JAR 文件,该文件是自包含的,包括代理代码及其所有依赖项
此"shaded" JAR 文件提供了在现有应用程序中包括的最方便的 Cryostat 代理形式,因为您只需要包含一个额外的代理 JAR 文件。这是类似代理和工具的常见分发模式。在 Cryostat 2.4 之前,"shaded" JAR 文件是 Cryostat 代理的唯一可用发行版。"shaded" JAR 文件名采用 cry
ostat-agent-0.5 的形式。X .redhat-
分别代表代理版本和构建号。xxxxx
-shaded.jar包含没有依赖项的代理代码的标准 JAR 文件
如果您知道代理和工作负载应用程序之间存在依赖关系冲突,则这种类型的 JAR 文件很有用。如果您打算应用自己的策略,以提供每个依赖项的正确版本以满足代理和应用程序的要求,您可以使用独立 JAR 文件。标准 JAR 文件名采用 cry
ostat-agent-0.5 格式。X.redhat-xxxxx.jar
,其中0.5.X
和xxxxx
代表代理版本和构建号。
如果要手动配置 Cryostat 代理,则一体化"shaded" JAR 文件是部署代理的首选方法。除非打算应用自己的策略来解决手动配置代理和工作负载应用之间的任何依赖关系冲突,否则请不要使用标准 JAR 文件。
这些代理 JAR 文件可从 Red Hat Maven Repository 下载。
3.1.1.2. JVM 的静态或动态附件
根据您的要求,Cryostat 代理可以使用静态或动态方法附加到 JVM。
JVM 的静态附件
静态附加意味着您的工作负载应用的 JVM 会在 JVM 启动时加载并初始化 Cryostat 代理。
无论 Cryostat Operator 会自动配置代理还是手动配置代理,都支持 JVM 的静态附件。如果您希望 Cryostat Operator 自动配置代理,静态附加是代理附加到 JVM 的唯一方法。
如果使用 Cryostat Operator 自动配置代理,Operator 会处理所有配置任务,OpenShift Container Platform 会自动重新部署应用程序。
如需更多信息,请参阅配置应用程序以使用 Cryostat 代理。
JVM 的动态附加
动态附加意味着 Cryostat 代理可以动态地附加到已在运行的应用 JVM,而无需应用程序重启。
对 JVM 的动态附加需要您手动配置代理。Cryostat Operator 自动配置的代理不支持动态附加方法。
这个动态附加功能有以下要求:
-
您必须确保代理的 JAR 文件被复制到 JVM 的文件系统中(例如,使用
oc cp
命令)。 -
您必须能够在同一主机上或同一应用程序(例如,使用
oc exec
命令)将代理作为单独的进程运行。
动态附加功能支持临时一次性性能分析或故障排除工作流,您可能不需要在每次 JVM 启动时附加代理。动态附加还适合于无法或不想为附加代理的唯一目的重新配置应用程序的情况。由于代理可以在不需要应用重启的情况下附加到正在运行的 JVM,因此这也意味着没有应用停机时间。
如需更多信息,请参阅 启动 Cryostat 代理作为对 JVM 的动态附加的独立进程。
3.1.1.3. 在工作负载应用程序中包括代理 JAR 文件的选项
将代理 JAR 文件包含在工作负载应用中的选项会因您使用代理自动还是手动配置,还是对 JVM 进行动态附加而有所不同。
用于自动配置代理
如果您希望 Cryostat Operator 自动配置代理,Operator 将使用
cryostat-agent-init
容器将包含代理 JAR 文件的卷挂载到相关的应用程序。在这种情况下,应用程序部署必须包含cryostat.io/name
和cryostat.io/namespace
标签,以识别 pod 应使用的 Cryostat 实例。用于手动配置 JVM 的动态附件的代理配置
对于正在运行的 JVM 的动态一次性连接,您可以使用
oc cp
命令将代理的 JAR 文件复制到 JVM 的文件系统中。
3.1.1.4. 代理配置属性
本节仅用于信息。由于红帽目前正在调查的已知问题,在 Cryostat 4.0 中无法进行手动配置。如果您希望应用程序使用 4.0 发行版中的 Cryostat 代理,则必须允许 Cryostat Operator 自动配置 Cryostat 代理。
如果您选择手动配置代理,您可以以两种方式之一为 Cryostat 代理指定配置属性:
-
在应用上使用 JVM 系统属性标志(例如,
-Dcryostat.agent.api.writes-enabled=true
)。 -
通过将所有字母大写字母组成并将任何标点替换为下划线(例如,
CRYOSTAT_AGENT_API_WRITES_ENABLED=true
)来使用环境变量。
如果使用 Cryostat Operator 自动配置代理,Operator 会配置相关属性。
所需的代理属性
如果要手动配置代理,您必须配置以下属性,以便 Cryostat 代理能够成功运行:
|
这将指定 Cryostat 代理向(即内部 OpenShift Service 对象)公告自己(如 |
|
这将指定 Cryostat 代理实例或应用程序本身的 URL 位置。Cryostat 使用此 URL 执行健康检查并从代理请求数据。您可以使用 OpenShift/Kubernetes Downward API 将此属性设置为如 |
|
这指定了一个标头值,Cryostat 代理可以在对 Cryostat 服务器的 API 请求中包含(例如, 注意
此属性优先于 |
|
这指定了与 注意
如果您为 有效的授权类型如下:
此属性默认设置为 |
|
这指定了与 注意
如果您为 请考虑以下指南:
默认情况下,此属性设置为 |
可选代理属性
根据您的设置要求,如果您要手动配置代理,您也可以配置以下代理属性:
|
这表明 Cryostat 代理是否允许写操作。这默认设置为 注意
即使此属性设置为 |
| 这将指定代理用来绑定其 HTTP API 的 HTTP 端口号(默认为 9977)。如果这与应用程序或其他工具代理使用的现有端口冲突,您必须指定不同的端口号。 |
|
这指定了一个标签,用于标识此 Cryostat 代理实例附加到哪个应用程序(默认情况下,cry |
前面的列表只描述了 Cryostat 代理的可用配置属性的子集。有关代理属性的完整列表,请参阅 代理属性。
3.1.2. 将应用程序配置为使用 Cryostat 代理
您可以将目标应用程序配置为使用 Cryostat 代理(实施为 Java Instrumentation Agent),以便 Cryostat 可以检测这些应用程序,收集数据,并将此数据发送到 Cryostat 进行分析。
Cryostat 代理支持以下配置用例:
3.1.2.1. 通过 Cryostat Operator 启用代理自动配置
如果要允许 Cryostat Operator 自动配置代理,您必须在应用程序部署中添加某些标签。
流程
在 appllication 部署中,添加
cryostat.io/name
和cryostat.io/namespace
标签。Example
apiVersion: apps/v1 kind: Deployment ... spec: ... template: metadata: labels: ... cryostat.io/namespace: <namespace> cryostat.io/name: <namespace>
apiVersion: apps/v1 kind: Deployment ... spec: ... template: metadata: labels: ... cryostat.io/namespace: <namespace> cryostat.io/name: <namespace>
Copy to Clipboard Copied! 在前面的示例中,将 <
;namespace&
gt; 替换为您的 Cryostat 实例的安装命名空间,并将 <name
> 替换为 Cryostat CR 的名称。默认情况下,代理的回调服务器绑定到容器端口 9977。如果要为 Cryostat 代理的回调服务器指定不同的端口号,请在应用程序部署中添加
cryostat.io/callback-port
标签。Example
apiVersion: apps/v1 kind: Deployment ... spec: ... template: metadata: labels: ... cryostat.io/namespace: <namespace> cryostat.io/name: <namespace> cryostat.io/callback-port: <port>
apiVersion: apps/v1 kind: Deployment ... spec: ... template: metadata: labels: ... cryostat.io/namespace: <namespace> cryostat.io/name: <namespace> cryostat.io/callback-port: <port>
Copy to Clipboard Copied! 在前面的示例中,将
<
;port> 替换为您希望代理的回调服务器绑定到的端口号。如果要指定代理应注入的容器,请在应用程序部署中添加
cryostat.io/container
标签。Example
apiVersion: apps/v1 kind: Deployment ... spec: ... template: metadata: labels: ... cryostat.io/namespace: <namespace> cryostat.io/name: <namespace> cryostat.io/callback-port: <port> cryostat.io/container: <container>
apiVersion: apps/v1 kind: Deployment ... spec: ... template: metadata: labels: ... cryostat.io/namespace: <namespace> cryostat.io/name: <namespace> cryostat.io/callback-port: <port> cryostat.io/container: <container>
Copy to Clipboard Copied! 在前面的示例中,将 &
lt;container
> 替换为相关容器的名称。注意如果同一 pod 中有多个容器运行,则只能选择一个容器进行代理注入。在多容器 pod 中,如果您只有一个 Java 容器,您要注入代理,此功能很有用。如果没有包括此标签,则 mutation Webhook 会将代理注入第一个容器镜像。
如果您希望注入的代理对 pod 具有只读访问权限,请在应用程序部署中将
cryostat.io/read-only
标签设置为true
。Example
apiVersion: apps/v1 kind: Deployment ... spec: ... template: metadata: labels: ... cryostat.io/namespace: <namespace> cryostat.io/name: <namespace> cryostat.io/callback-port: <port> cryostat.io/container: <container> cryostat.io/read-only: true
apiVersion: apps/v1 kind: Deployment ... spec: ... template: metadata: labels: ... cryostat.io/namespace: <namespace> cryostat.io/name: <namespace> cryostat.io/callback-port: <port> cryostat.io/container: <container> cryostat.io/read-only: true
Copy to Clipboard Copied! 注意此功能可让您更好地控制注入的代理的安全性。
默认情况下,Cryostat 代理禁用日志记录。如果要启用代理日志记录,请在应用程序部署中添加
cryostat.io/log-level
标签。有效值为:
trace
、debug
、info
、warn
、error
或off
。默认值为off
。Example
apiVersion: apps/v1 kind: Deployment ... spec: ... template: metadata: labels: ... cryostat.io/namespace: <namespace> cryostat.io/name: <namespace> cryostat.io/callback-port: <port> cryostat.io/container: <container> cryostat.io/read-only: true cryostat.io/log-level: debug
apiVersion: apps/v1 kind: Deployment ... spec: ... template: metadata: labels: ... cryostat.io/namespace: <namespace> cryostat.io/name: <namespace> cryostat.io/callback-port: <port> cryostat.io/container: <container> cryostat.io/read-only: true cryostat.io/log-level: debug
Copy to Clipboard Copied! 注意此功能可让您更好地控制您要用于代理日志记录的适当级别,这对于故障排除或调试代理配置非常有用。
当您启用代理日志记录时,这些代理日志可能会与主机应用程序的日志消息混淆。根据您设置的日志记录级别,代理日志最终可能会触发其他警报系统来检查警告或错误级别信息。
当 Cryostat Operator 检测到应用程序部署具有 cryostat.io/name
和 cryostat.io/namespace
标签时,Operator 会使用 cryostat-agent-init
容器将包含代理 JAR 文件的卷挂载到此应用程序。在这种情况下,Operator 仅在 Cryostat 实例的目标命名空间列表中的应用程序部署中指定了这些标签。否则,Operator 不会将应用程序配置为与这个 Cryostat 实例通信。
3.1.2.2. 启动 Cryostat 代理作为到 JVM 动态附加的独立进程
如果您希望 Cryostat 代理动态附加到已在运行的应用程序 JVM,您可以将代理作为独立 Java 进程启动。
只有在您想要使用动态附加功能时,这个过程才相关,这允许 Cryostat 代理附加到临时一次性运行的 JVM。如果您希望工作负载的 JVM 在 JVM 启动时加载和初始化 Cryostat 代理,请参阅启用代理配置。
先决条件
使用
oc cp
命令将代理的 JAR 文件复制到 JVM 的文件系统。注意可以从 Red Hat Maven 存储库 下载最新的"shaded" JAR 文件。"shaded" JAR 文件名采用 cry
ostat-agent-0.5 的形式。X .redhat-
分别代表代理版本和构建号。xxxxx
-shaded.jar
流程
输入以下命令:
java -jar target/<agent_jar_file> <pid>
$ java -jar target/<agent_jar_file> <pid>
Copy to Clipboard Copied! 在前面的命令中,将 < ;agent_jar_file > 替换为代理的 JAR 文件名,并将 <pid > 替换为您要附加到的 JVM 的进程 ID (PID)。
例如:
java -jar target/cryostat-agent-0.5.0.redhat-00001-shaded.jar 1234
$ java -jar target/cryostat-agent-0.5.0.redhat-00001-shaded.jar 1234
Copy to Clipboard Copied! 注意前面的示例仅显示了说明,可能不会反映"shaded" JAR 文件的最新可用版本和构建。
运行上述命令时,代理进程使用其附加提供程序来查找指定的 PID。如果找到指定的 PID,代理进程会附加到此 PID,并尝试将代理的 JAR 文件加载到此 JVM 中,然后引导到正常的代理启动进程。
基于 PID 值的代理启动行为
根据 PID 值,请考虑以下代理启动行为准则:
- 如果您指定了无效的 PID,代理将无法成功启动。
-
如果您将通配符星号(
*
)指定为 PID 值,代理的 JAR 文件将尝试引导到它找到的每个 JVM。 -
如果将
0
指定为 PID 值,或者没有指定任何 PID 值,代理会检查是否只有一个 candidate JVM 可用。如果只有一个 JVM 可用,代理会尝试引导到此 JVM。如果多个 JVM 或没有 JVM 可用,代理将无法成功启动。
late-binding 配置选项
当将 Cryostat 代理作为独立进程启动时,您也可以使用命令行选项在代理启动程序中指定额外的 late-binding 配置选项。
例如:
java -jar target/cryostat-agent-0.5.0.redhat-00001-shaded.jar \ -Dcryostat.agent.baseuri=<cryostat_server_url> \ -Dcryostat.agent.callback=<cryostat_agent_url> \ -Dcryostat.agent.authorization=Bearer <authorization_value> \ --smartTrigger=[ProcessCpuLoad>0.2]~profile \ @/deployment/app/moreAgentArgs \ 1234
$ java -jar target/cryostat-agent-0.5.0.redhat-00001-shaded.jar \
-Dcryostat.agent.baseuri=<cryostat_server_url> \
-Dcryostat.agent.callback=<cryostat_agent_url> \
-Dcryostat.agent.authorization=Bearer <authorization_value> \
--smartTrigger=[ProcessCpuLoad>0.2]~profile \
@/deployment/app/moreAgentArgs \
1234
有关可用选项及其行为的信息,请运行 java -jar target/ <filename>.jar -h
help 命令,其中 & lt;filename > 代表您复制的"shaded"代理 JAR 文件的名称。
如上例中所示,当将 Cryostat 代理作为独立进程启动时,请确保在 the-jar < path_to_jarfile> 参数后 为任何 late-
binding 配置选项指定 -D
标志。-D
标志的位置在此非常重要:
-
如果您在 <
path_to_jarfile>参数之前为系统属性指定
标志,则在独立启动程序 JVM 进程上设置此属性。当将代理作为独立进程启动时,这可能会导致意外的问题。-
D -
如果您在 /jar <
path_to_jarfile> 参数后为系统属性指定
标志,则这些属性将作为参数传递到代理启动程序。当启动程序将代理引导到主机 JVM 中时,代理会在代理启动时将这些属性应用到 JVM。-
D
如上例所示,请确保将任何所需的代理属性(如 cryostat.agent.baseuri
、cryostat.agent.callback
)和 cryostat.agent.authorization
指定为代理启动程序的配置选项。有关配置属性的更多信息,请参阅 代理配置属性。