当前位置：首页 > news >正文

Pyroscope Java 接入最佳实践

news 2026/7/9 21:04:20

Pyroscope

Pyroscope 是 Grafana 开源的持续性能分析平台，旨在帮助用户从应用程序中获取性能洞察，以优化资源使用，如 CPU、内存和 I/O 操作。将 Pyroscope 数据上报到观测云，使用户能够全面了解应用程序的行为，并能够深入到特定服务中进行更精确的根源分析。Pyroscope 为 OpenTelemetry 补全了 Profiling 能力，同时，可以实现 Profiling 与 Tracing 的关联。

核心功能

持续性能分析：通过持续分析应用程序的性能，帮助团队快速识别性能瓶颈并优化应用程序。
低开销和高效压缩：确保在生产环境中进行性能分析时对应用程序的性能影响最小。
多语言支持：客户端 SDK 支持多种编程语言，包括 Go、Java、Python、Ruby、PHP 和 .NET。
灵活的部署方式：支持在多种环境中部署，包括 Kubernetes 等。

使用场景

主动优化：通过持续监控减少资源消耗，提高应用程序性能，预防延迟问题。
快速响应：在发生性能问题时，能够快速定位并解决，例如调试 CPU、内存或 I/O 瓶颈。

支持类型

Pyroscope 支持采集以下数据类型：

CPU 使用情况
内存使用情况
I/O 操作
调用栈（Call Stacks）
分配的内存（Heap & Allocation）
协程或线程的使用情况
函数级性能数据

接入观测云

实现说明

OpenTelemtry 链路与 pyroscope profiling 数据关联实现原理，主要是通过给 profiling 和 tracing 注入 runtime_id 标签。

主机部署

开启 opentelemetry 及 pyroscope 采集器

进入 DataKit 安装目录下，执行以下命令：

# 开启opentelemetry cd /usr/local/datakit/conf.d/ cp samples/opentelemetry.conf.sample opentelemetry.conf # 开启pyroscope cd /usr/local/datakit/conf.d/ cp samples/pyroscope.conf.sample pyroscope.conf

重启 DataKit

datakit service -R

接入 JAVA 应用

pyroscope-java 是基于 async-profiler 的增强版本。
pyroscope-otel 是基于 pyroscope-java 封装的 OpenTelemetry 版本，意在与 OpenTelemetry APM 进行融合。

下载依赖

pyroscope-otel 下载地址： https://repo1.maven.org/maven2/io/pyroscope/otel/0.11.0/otel-0.11.0.jar，重命名为 pyroscope-otel.jar
opentelemetry-java 下载地址： https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases
Agent 代码仓库：https://github.com/grafana/otel-profiling-java/releases

启动参数

java 应用启动命令如下，供参考。

注意： UUID 为注入的随机id ，用于关联trace 与 profile 的关联id 赋值，需要确保UUID 能正常被应用。

Shell UUID=$(uuidgen) \ # 实例维度的uuid，保证实例的唯一性 OTEL_SERVICE_NAME="springboot-server" \ OTEL_RESOURCE_ATTRIBUTES="runtime_id=$UUID,service.name=springboot-server,service.version=1.3.55,service.env=dev" \ OTEL_JAVAAGENT_EXTENSIONS=./pyroscope-otel.jar \ OTEL_TRACES_EXPORTER=otlp \ OTEL_EXPORTER_OTLP_PROTOCOL="grpc" \ OTEL_EXPORTER_OTLP_ENDPOINT="http://datakit-service.datakit:4317" \ # PYROSCOPE 配置 PYROSCOPE_APPLICATION_NAME="springboot-server" \ OTEL_PYROSCOPE_START_PROFILING=true \ PYROSCOPE_FORMAT="jfr" \ PYROSCOPE_PROFILER_EVENT="cpu" \ PYROSCOPE_LABELS="runtime_id=$UUID,service=springboot-server,version=1.3.55,env=dev" \ PYROSCOPE_UPLOAD_INTERVAL="10s" \ PYROSCOPE_JAVA_STACK_DEPTH_MAX=512 \ PYROSCOPE_PROFILING_INTERVAL="10ms" \ PYROSCOPE_PROFILER_ALLOC=512k \ PYROSCOPE_ALLOC_LIVE=true \ PYROSCOPE_SERVER_ADDRESS="http://datakit-service.datakit:9529" \ java -javaagent:opentelemetry-javaagent.jar -jar springboot-server.jar

按照实际业务需求选择合适的参数：

opentelemetry-java 相关参数参考 OpenTelemetry 官方文档。
pyroscope 相关参数参考 Pyroscope 官方文档，部分参数说明如下：

配置说明

Flag	Description
PYROSCOPE_AGENT_ENABLED	启用代理。默认值为true。
PYROSCOPE_SERVER_ADDRESS	上报地址
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 Basic身份验证用户名。默认值为空字符串（""），表示无身份验证。
PYROSCOPE_BASIC_AUTH_PASSWORD	HTTP Basic身份验证密码。默认值为空字符串（""），表示无身份验证。
PYROSCOPE_TENANT_ID	pyroscope租户ID，作为X-Scope-OrgID HTTP头传递。默认值为空字符串（""），表示无租户ID。
PYROSCOPE_HTTP_HEADERS	额外的HTTP头（以JSON格式），例如：{"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()命令。此选项可能对实时分析有用，但默认情况下是禁用的。