Java
与 Pyroscope 集成的 Java 性能分析器为 Java 应用程序的性能分析提供了全面的解决方案。它提供实时洞察，使开发人员能够有效地理解和优化其 Java 代码库。此工具对于提高应用程序响应能力、降低资源消耗以及确保 Java 环境中的最佳性能至关重要。
注意
请参阅 可用的性能分析类型，了解每种语言支持的配置文件类型列表。
开始之前
要捕获和分析性能分析数据，您需要一个托管的 Pyroscope OSS 服务器或一个托管的 具有 Grafana Cloud Profiles 的 Pyroscope 实例（需要一个免费的 Grafana Cloud 帐户）。
Pyroscope 服务器可以是用于开发的本地服务器，也可以是用于生产用途的远程服务器。
向您的应用程序添加 Java 性能分析
Java 集成以单个 jar 文件 (pyroscope.jar) 或 Maven 包的形式分发。支持的平台包括
- x64 上的 Linux
- ARM64 上的 Linux
- x64 上的 MacOS
- ARM64 上的 MacOS
访问 GitHub 发行版 页面以下载最新版本的 pyroscope.jar。
最新版本也已发布在Maven Central上。
配置 Java 客户端
您可以从应用程序代码中启动 Pyroscope，或者将其作为 javaagent 附加。
从应用程序的 Java 代码启动 Pyroscope
首先，添加 Pyroscope 依赖项
<dependency>
<groupId>io.pyroscope</groupId>
<artifactId>agent</artifactId>
<version>0.14.0</version>
</dependency>implementation("io.pyroscope:agent:0.14.0")将以下代码添加到您的应用程序中
PyroscopeAgent.start(
new Config.Builder()
.setApplicationName("ride-sharing-app-java")
.setProfilingEvent(EventType.ITIMER)
.setFormat(Format.JFR)
.setServerAddress("http://pyroscope-server:4040")
.build()
);import io.pyroscope.javaagent.PyroscopeAgent;
import io.pyroscope.javaagent.config.Config;
import io.pyroscope.javaagent.EventType;
import io.pyroscope.http.Format;
@PostConstruct
public void init() {
PyroscopeAgent.start(
new Config.Builder()
.setApplicationName("ride-sharing-app-java")
.setProfilingEvent(EventType.ITIMER)
.setFormat(Format.JFR)
.setServerAddress("http://pyroscope-server:4040")
// Optionally, if authentication is enabled, specify the API key.
// .setBasicAuthUser("<User>")
// .setBasicAuthPassword("<Password>")
// Optionally, if you'd like to set allocation threshold to register events, in bytes. '0' registers all events
// .setProfilingAlloc("0")
.build()
);
}您还可以选择替换一些 Pyroscope 组件
PyroscopeAgent.start(
new PyroscopeAgent.Options.Builder(config)
.setExporter(snapshot -> {
// Your custom export/upload logic may go here
// It is invoked every 10 seconds by default with snapshot of
// profiling data
})
.setLogger((l, msg, args) -> {
// Your custom logging may go here
// Pyroscope does not depend on any logging library
System.out.printf((msg) + "%n", args);
})
.setScheduler(profiler -> {
// Your custom profiling schedule logic may go here
})
.build()
);以 javaagent 方式启动 Pyroscope
要开始分析 Java 应用程序，请使用 pyroscope.jar javaagent 运行您的应用程序
export PYROSCOPE_APPLICATION_NAME=my.java.app
export PYROSCOPE_SERVER_ADDRESS=http://pyroscope-server:4040
java -javaagent:pyroscope.jar -jar app.jar向 Java 应用程序添加分析标签
您可以向分析数据添加动态标签。这些标签可以在 UI 中过滤数据。
动态添加标签
Pyroscope.LabelsWrapper.run(new LabelsSet("controller", "slow_controller"), () -> {
slowCode();
});您还可以向分析数据添加静态标签。
Pyroscope.setStaticLabels(Map.of("region", System.getenv("REGION")));
// or with Config.Builder if you start pyroscope with PyroscopeAgent.start
PyroscopeAgent.start(new Config.Builder()
.setLabels(mapOf("region", System.getenv("REGION")))
// ...
.build()
);配置选项
当您以 javaagent 方式启动 Pyroscope 或通过 Config.build() 获取配置时，Pyroscope 会在多个来源中搜索配置：系统属性、环境变量和 pyroscope.properties。属性键与环境变量名称相同，但小写，并且下划线 (_) 将替换为句点 (.)。例如，PYROSCOPE_FORMAT 将变为 pyroscope.format
Java 集成支持 JFR 格式以支持多个事件（JFR 是唯一支持async-profiler 中多个事件的输出格式）。有一些环境变量定义了多个事件配置的工作方式
| 标志 | 描述 |
|---|---|
PYROSCOPE_AGENT_ENABLED | 启用代理。默认值为 true。 |
PYROSCOPE_FORMAT | 设置分析器输出格式。默认值为 collapsed，但为了支持多种格式，必须将其设置为 jfr。 |
PYROSCOPE_PROFILER_EVENT | 设置分析器事件。启用 JFR 格式后，此事件指的是可能的 CPU 分析事件之一：itimer、cpu、wall。默认值为 itimer。 |
PYROSCOPE_PROFILER_ALLOC | 设置注册事件的分配阈值，以字节为单位（相当于 async-profiler 中的 --alloc=）。默认值为 "" - 空字符串，表示分配分析已禁用。将其设置为 0 将注册每个事件，从而导致大量的 CPU 和网络开销，使其不适合生产环境。我们建议将起始值设置为 512k，并根据需要进行调整。 |
PYROSCOPE_PROFILER_LOCK | 设置注册事件的锁阈值，以纳秒为单位（相当于 async-profiler 中的 --lock=）。默认值为 "" - 空字符串，表示锁分析已禁用。将其设置为 0 将注册每个事件，从而导致大量的 CPU 和网络开销，使其不适合生产环境。我们建议将起始值设置为 10ms，并根据需要进行调整。 |
PYROSCOPE_CONFIGURATION_FILE | 设置其他属性配置文件。默认值为 pyroscope.properties。 |
PYROSCOPE_BASIC_AUTH_USER | HTTP 基本身份验证用户名。默认值为 "" - 空字符串，不进行身份验证。 |
PYROSCOPE_BASIC_AUTH_PASSWORD | HTTP 基本身份验证密码。默认值为 "" - 空字符串，不进行身份验证。 |
PYROSCOPE_TENANT_ID | pyroscope 租户 ID，作为 X-Scope-OrgID http 标头传递。默认值为 "" - 空字符串，没有租户 ID。 |
PYROSCOPE_HTTP_HEADERS | 以 JSON 格式表示的额外 HTTP 标头，例如：{"X-Header": "Value"}。默认值为 {} - 没有额外标头。 |
PYROSCOPE_LABELS | 以逗号分隔的 key=value 对的形式设置静态标签。默认值为 "" - 空字符串，没有标签。 |
PYROSCOPE_LOG_LEVEL | 确定 Pyroscope 日志记录器的详细程度。可用选项包括 debug、info、warn 和 error。默认值为 info。 |
PYROSCOPE_PUSH_QUEUE_CAPACITY | 指定摄取队列的大小，该队列在网络中断期间临时存储内存中的分析数据。默认值为 8。 |
PYROSCOPE_INGEST_MAX_TRIES | 设置在摄取 API 调用失败时重试的最大次数。值为 -1 表示重试将无限期持续。默认值为 8。 |
PYROSCOPE_EXPORT_COMPRESSION_LEVEL_JFR | 设置应用于上传的 JFR 文件的 GZIP 压缩级别。此选项接受 NO_COMPRESSION、BEST_SPEED、BEST_COMPRESSION 和 DEFAULT_COMPRESSION 的值。 |
PYROSCOPE_EXPORT_COMPRESSION_LEVEL_LABELS | 与 PYROSCOPE_EXPORT_COMPRESSION_LEVEL_JFR 的操作类似，但应用于动态标签部分。默认值为 BEST_SPEED。 |
PYROSCOPE_GC_BEFORE_DUMP | 布尔值，当设置为 true 时，在转储配置文件之前执行 System.gc() 命令。此选项可能对实时分析有用，但默认情况下处于禁用状态。 |
将数据发送到 Pyroscope OSS 或 Grafana Cloud Profiles
将以下代码添加到您的应用程序中
PyroscopeAgent.start(
new Config.Builder()
.setApplicationName("test-java-app")
.setProfilingEvent(EventType.ITIMER)
.setFormat(Format.JFR)
.setServerAddress("<URL>")
// Set these if using Grafana Cloud:
.setBasicAuthUser("<User>")
.setBasicAuthPassword("<Password>")
// Optional Pyroscope tenant ID (only needed if using multi-tenancy). Not needed for Grafana cloud.
// .setTenantID("<TenantID>")
.build()
);要将 Java SDK 配置为将数据发送到 Pyroscope，请将 <URL> 占位符替换为相应的服务器 URL。这可能是 Grafana Cloud URL 或您自己的自定义 Pyroscope 服务器 URL。
如果您需要将数据发送到 Grafana Cloud，则必须配置 HTTP 基本身份验证。将 <User> 替换为您的 Grafana Cloud 堆栈用户，并将 <Password> 替换为您的 Grafana Cloud API 密钥。
如果您的 Pyroscope 服务器启用了多租户，则需要配置租户 ID。将 <TenantID> 替换为您的 Pyroscope 租户 ID。
示例配置
以下配置设置应用程序名称、Pyroscope 格式、分析间隔、事件和锁。此示例摘自 Pyroscope 存储库中提供的rideshare Dockerfile。
ENV PYROSCOPE_APPLICATION_NAME=rideshare.java.push.app
ENV PYROSCOPE_FORMAT=jfr
ENV PYROSCOPE_PROFILING_INTERVAL=10ms
ENV PYROSCOPE_PROFILER_EVENT=itimer
ENV PYROSCOPE_PROFILER_LOCK=10ms此配置摘录启用了分配和锁分析
PYROSCOPE_PROFILER_ALLOC=512k
PYROSCOPE_PROFILER_LOCK=10msJava 分析示例
查看以下资源，了解有关 Java 分析的更多信息
