针对 Java 的 Span Profiles 与 Traces to Profiles

Span Profiles 代表了性能分析方法论的重大转变，能够更深入地分析追踪和性能分析数据。传统的持续性能分析提供了固定时间间隔内的应用全局视图。相比之下，Span Profiles 对应用程序内特定的执行范围（例如单个请求或特定的追踪 Span）提供聚焦的动态分析。

这一转变提供了更细粒度的性能视图，通过将性能分析数据与追踪数据直接关联，增强了其效用，从而全面理解应用程序行为。因此，工程团队可以更高效地识别和解决性能瓶颈。

要了解有关 Span Profiles 的更多信息，请参阅结合追踪和性能分析以增强可观测性：引入 Span Profiles。

Pyroscope 集成了支持 OpenTelemetry 标准的分布式追踪系统。通过这种集成，您可以将追踪数据与性能分析数据关联起来，并查找特定代码行在追踪 Span 中的资源使用情况。

注意
目前仅支持 CPU 性能分析。
由于采样式性能分析器的工作原理，短于采样间隔的 Span 可能无法被捕获。

要使用 Span Profiles，您需要：

配置 Pyroscope 发送性能分析数据
配置客户端软件包以关联追踪与性能分析：Java
在 Grafana 或 Grafana Cloud 中配置 Tempo 数据源以发现关联的追踪与性能分析数据

开始之前

在使用 Span profiles 之前，您的应用程序必须已配置性能分析和追踪。

性能分析：您的应用程序必须已配置 Pyroscope 的 Java 客户端 SDK。请参阅Java 指南了解说明。
追踪：您的应用程序必须已配置 OpenTelemetry 追踪。请参阅OpenTelemetry 指南了解说明。

配置 otel-profiling-java 软件包

要开始为您的 Java 应用程序收集 Span Profiles，您需要将 otel-profiling-java 作为 OTel Java Agent 的扩展包含进来。

假设您有此示例应用程序 Docker 镜像

# [...]

EXPOSE 5000

CMD ["java", "-Dserver.port=5000", "-jar", "./my-app.jar" ]

通过添加 OTel Java Agent 和 Pyroscope OTel Java Agent 扩展，您可以丰富您的性能分析数据，添加 Span IDs。这使得在 Grafana Tempo 中查询特定 Span 的性能分析数据成为可能。

# [...]

EXPOSE 5000

## Add required libararies
ADD https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/download/v1.17.0/opentelemetry-javaagent.jar opentelemetry-javaagent.jar
ADD https://repo1.maven.org/maven2/io/pyroscope/otel/0.11.0/otel-0.11.0.jar pyroscope-otel.jar

ENV PYROSCOPE_APPLICATION_NAME=my-app
ENV PYROSCOPE_FORMAT=jfr
ENV PYROSCOPE_PROFILING_INTERVAL=10ms
ENV PYROSCOPE_PROFILER_EVENT=itimer
ENV PYROSCOPE_PROFILER_LOCK=10ms
ENV PYROSCOPE_PROFILER_ALLOC=512k
ENV PYROSCOPE_UPLOAD_INTERVAL=15s
ENV OTEL_JAVAAGENT_EXTENSIONS=./pyroscope-otel.jar
ENV OTEL_PYROSCOPE_ADD_PROFILE_URL=false
ENV OTEL_PYROSCOPE_ADD_PROFILE_BASELINE_URL=false
ENV OTEL_PYROSCOPE_START_PROFILING=true

## Useful for debugging
# ENV PYROSCOPE_LOG_LEVEL=debug

## Those environment variables need to be overwritten at runtime, if you are using Grafana Cloud
ENV PYROSCOPE_SERVER_ADDRESS=https://:4040
# ENV PYROSCOPE_BASIC_AUTH_USER=123     ## Grafana Cloud Username
# ENV PYROSCOPE_BASIC_AUTH_PASSWORD=glc_secret ## Grafana Cloud Password / API Token

## Add the opentelemetry java agent
CMD ["java", "-Dserver.port=5000", "-javaagent:./opentelemetry-javaagent.jar", "-jar", "./my-app.jar" ]

可用的配置选项

标志	描述	默认值
`otel.pyroscope.start.profiling`	用于启动 PyroscopeAgent 的布尔标志。如果您想手动启动 PyroscopeAgent，请将其设置为 false。	`true`
`otel.pyroscope.root.span.only`	布尔标志。启用后，追踪器将仅注解本地创建的第一个 Span（根 Span），但性能分析数据将包含所有嵌套 Span 的样本。如果追踪由多个短于 10ms 的 Span 组成且性能分析器无法正确收集和注解样本，此选项可能会有所帮助。	`true`
`otel.pyroscope.add.span.name`	布尔标志。控制是否将 Span 名称添加到性能分析标签中。	`true`

在 Grafana Tempo 中查看 Span Profiles

要在 Grafana Tempo 中查看 Span Profiles，您需要运行 Grafana 实例，并配置一个数据源以关联追踪 Span 和性能分析数据。

请参阅数据源配置文档，了解如何配置可视化以关联追踪 Span 与性能分析数据。

要使用简单配置，请遵循以下步骤

从“Data source”下拉菜单中选择一个 Pyroscope 数据源。
可选：选择要在查询中使用的任何标签。如果留空，将使用 service.name 和 service.namespace 的默认值。

您配置的标签必须存在于 Span 的属性或资源中，Trace to Profiles 的 Span 链接才会出现。您可以选择为标签配置一个新名称。例如，如果标签名称包含点号，而目标数据源不允许在标签中使用点号，则此选项非常有用。在这种情况下，您可以将 service.name 重新映射为 service_name。