即时性能分析工具Pyroscope

https://pyroscope.io/docs/installing-pyroscope-overview/

https://pyroscope.io/blog/

目前支持的语言

• Go
• Python
• eBPF
• Java
• Ruby
• Rust
• PHP
• .NET
• NodeJS

分析go性能

安装Pyroscope server

window暂不支持server

二进制

window管理员运行终端

下载地址：https://github.com/pyroscope-io/pyroscope/releases

1

./pyroscope server --api-bind-addr=:5002 --adhoc-data-path /root/.local/share/pyroscope

docker

1

docker run -it -p 4040:4040 pyroscope/pyroscope:latest server

docker-compose

1
2
3
4
5
6
7
8

---
services:
  pyroscope:
    image: "pyroscope/pyroscope:latest"
    ports:
      - "4040:4040"
    command:
      - "server"

在Go里面安装agent

https://github.com/pyroscope-io/pyroscope/tree/main/examples/golang-push

push模式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

package main

import (
	"context"
	"os"
	"runtime/pprof"

	"github.com/pyroscope-io/client/pyroscope"
)

//go:noinline
func work(n int) {
	// revive:disable:empty-block this is fine because this is a example app, not real production code
	for i := 0; i < n; i++ {
	}
	// revive:enable:empty-block
}

func fastFunction(c context.Context) {
	pyroscope.TagWrapper(c, pyroscope.Labels("function", "fast"), func(c context.Context) {
		work(20000000)
	})
}

func slowFunction(c context.Context) {
	// standard pprof.Do wrappers work as well
	pprof.Do(c, pprof.Labels("function", "slow"), func(c context.Context) {
		work(80000000)
	})
}

func main() {
	serverAddress := os.Getenv("PYROSCOPE_SERVER_ADDRESS")
	if serverAddress == "" {
		serverAddress = "http://localhost:4040"
	}
	pyroscope.Start(pyroscope.Config{
		ApplicationName: "test.golang.app",
		ServerAddress:   serverAddress,
		Logger:          pyroscope.StandardLogger,
	})
	pyroscope.TagWrapper(context.Background(), pyroscope.Labels("foo", "bar"), func(c context.Context) {
		for {
			fastFunction(c)
			slowFunction(c)
		}
	})
}

1

go run test.go

pull模式

https://pyroscope.io/docs/golang-pull-mode/

https://pyroscope.io/docs/server-configuration/

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

package main

import (
	"log"
	"math"
	"math/rand"
	"net/http"
	_ "net/http/pprof"
)

func isPrime(n int64) bool {
	for i := int64(2); i <= n; i++ {
		if i*i > n {
			return true
		}
		if n%i == 0 {
			return false
		}
	}
	return false
}

func slow(n int64) int64 {
	sum := int64(0)
	for i := int64(1); i <= n; i++ {
		sum += i
	}
	return sum
}

func fast(n int64) int64 {
	sum := int64(0)
	root := int64(math.Sqrt(float64(n)))
	for a := int64(1); a <= n; a += root {
		b := a + root - 1
		if n < b {
			b = n
		}
		sum += (b - a + 1) * (a + b) / 2
	}
	return sum
}

func run() {
	base := rand.Int63n(1000000) + 1
	for i := int64(0); i < 40000000; i++ {
		n := rand.Int63n(10000) + 1
		if isPrime(base + i) {
			slow(n)
		} else {
			fast(n)
		}
	}
}

func main() {
	go func() {
		log.Println(http.ListenAndServe(":6060", nil))
	}()
	run()
}

/etc/pyroscope/server.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

mkdir -p /etc/pyroscope/
vi /etc/pyroscope/server.yml


---
# A list of scrape configurations.
scrape-configs:
  # The job name assigned to scraped profiles by default.
  - job-name: pyroscope

    # The list of profiles to be scraped from the targets.
    enabled-profiles: [cpu, mem]

    # List of labeled statically configured targets for this job.
    static-configs:
      - application: test.app.www
        spy-name: gospy
        targets:
          - 127.0.0.1:6060
        labels:
          env: dev

启动go程序

1

go run test.go

启动pyroscope server

1

./pyroscope server --api-bind-addr=:5002 --adhoc-data-path /root/.local/share/pyroscope --config /etc/pyroscope/server.yml

dhoc profiling 使用方式

https://github.com/pyroscope-io/pyroscope/tree/main/examples/adhoc

不需要Pyroscope server，在本地进行性能测试产生数据。

push模式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

package main

import (
	"context"
	"os"
	"runtime/pprof"

	"github.com/pyroscope-io/client/pyroscope"
)

//go:noinline
func work(n int) {
	// revive:disable:empty-block this is fine because this is a example app, not real production code
	for i := 0; i < n; i++ {
	}
	// revive:enable:empty-block
}

func fastFunction(c context.Context) {
	pyroscope.TagWrapper(c, pyroscope.Labels("function", "fast"), func(c context.Context) {
		work(20000000)
	})
}

func slowFunction(c context.Context) {
	// standard pprof.Do wrappers work as well
	pprof.Do(c, pprof.Labels("function", "slow"), func(c context.Context) {
		work(80000000)
	})
}

func main() {
	serverAddress := os.Getenv("PYROSCOPE_SERVER_ADDRESS")
	if serverAddress == "" {
		serverAddress = "http://localhost:4040"
	}
	pyroscope.Start(pyroscope.Config{
		ApplicationName: "test.golang.app",
		ServerAddress:   serverAddress,
		Logger:          pyroscope.StandardLogger,
	})
	pyroscope.TagWrapper(context.Background(), pyroscope.Labels("foo", "bar"), func(c context.Context) {
		for {
			fastFunction(c)
			slowFunction(c)
		}
	})
}

1
2

# pyroscope adhoc --data-path ./ --output-format pprof --push go run test.go
pyroscope adhoc --output-format pprof --data-path ./ go run test.go

pull模式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

package main

import (
	"log"
	"math"
	"math/rand"
	"net/http"
	_ "net/http/pprof"
)

func isPrime(n int64) bool {
	for i := int64(2); i <= n; i++ {
		if i*i > n {
			return true
		}
		if n%i == 0 {
			return false
		}
	}
	return false
}

func slow(n int64) int64 {
	sum := int64(0)
	for i := int64(1); i <= n; i++ {
		sum += i
	}
	return sum
}

func fast(n int64) int64 {
	sum := int64(0)
	root := int64(math.Sqrt(float64(n)))
	for a := int64(1); a <= n; a += root {
		b := a + root - 1
		if n < b {
			b = n
		}
		sum += (b - a + 1) * (a + b) / 2
	}
	return sum
}

func run() {
	base := rand.Int63n(1000000) + 1
	for i := int64(0); i < 40000000; i++ {
		n := rand.Int63n(10000) + 1
		if isPrime(base + i) {
			slow(n)
		} else {
			fast(n)
		}
	}
}

func main() {
	go func() {
		log.Println(http.ListenAndServe(":6060", nil))
	}()
	run()
}

1
2
3

# go run test.go &
# pyroscope adhoc --url localhost:6060
pyroscope adhoc  --application-name wangyangyang.app --data-path ./ --output-format pprof --url localhost:6060 go run test.go

执行完毕后，你可以看到在同一层目录多了很多 HTML 文件，而这些文件就可以分享给其他同事参考，先相当方便来当作团队协作的工具。

除了点开 HTML 文件之外，大家也可以用 pyroscope CLI 在本机端打开 Server 服务，此時 Server服务回去读取家目录內 ~/.pyroscope/pyroscope/ 位置，里面存放每次生成的 Profiling JSON 格式数据。打开http://localhost:4040可以查看

Server配置

有 3 种方式来配置 pyroscope。配置优先级按以下顺序评估：

• 命令行参数

• 环境变量

• 配置文件

命令行参数

这是配置 pyroscope 的最简单方法。对于命令行参数和默认值的列表，运行pyroscope server -help：

环境变量

环境变量必须具有PYROSCOPE_ 前缀并采用 UPPER_SNAKE_CASE 格式，例如：

1

PYROSCOPE_API_BIND_ADDR=:9999 pyroscope server

配置文件

配置文件以 YAML 格式存储。默认配置文件路径位于：

• /etc/pyroscope/server.yml on Linux
• /usr/local/etc/pyroscope/server.yml on Intel macOS
• /opt/homebrew/etc/pyroscope/server.yml on M1 macOS

windows不支持server

您可以使用 -config <path> 参数覆盖默认配置文件，例如：

1

pyroscope server -config my-custom-config.yml

或环境变量：

1

PYROSCOPE_CONFIG=/tmp/pyroscope-server.yml pyroscope server

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70

---
# Disables analytics.
analytics-opt-out: "false"

# Log level: debug|info|warn|error.
log-level: "info"

# Log level: debug|info|warn|error.
badger-log-level: "error"

# Directory where pyroscope stores profiling data.
storage-path: "/var/lib/pyroscope"

# Port for the HTTP server used for data ingestion and web UI.
api-bind-addr: ":4040"

# Base URL for when the server is behind a reverse proxy with a different path.
base-url: ""

# Percentage of memory at which cache evictions start.
cache-evict-threshold: "0.25"

# Percentage of cache that is evicted per eviction run.
cache-evict-volume: "0.33"

# Database configuration. By default, Pyroscope Server uses embedded sqlite3 database.
database:
  # Indicates the database type. Supported DB engines: sqlite3.
  type: "sqlite3"
  # Database connection string. Specific to the engine.
  url: "/var/lib/pyroscope/pyroscope.db"

# Indicates whether value log files should be truncated to delete corrupt data, if any.
badger-no-truncate: "false"

# Disables /debug/pprof route.
disable-pprof-endpoint: "false"

# Max number of nodes used when saving profiles to disk.
max-nodes-serialization: "2048"

# Max number of nodes used to display data on the frontend.
max-nodes-render: "8192"

# Please don't use, this will soon be deprecated.
hide-applications: []

# Sets the maximum amount of time the profiling data is stored for. Data before this threshold is deleted. Disabled by default.
retention: "0s"

# Sets the maximum amount of time profile exemplars are stored for. Data before this threshold is deleted. Disabled by default.
exemplars-retention: "0s"

# Specifies how long the profiling data is stored per aggregation level. Disabled by default.
retention-levels: {}
# 0: 720h  # 30 days
# 1: 2160h # 90 days

# Metrics export rules.
metrics-export-rules: {}

# A list of scrape configurations.
scrape-configs: []

# Location of TLS Certificate file (.crt).
tls-certificate-file: ""

# Location of TLS Private key file (.key).
tls-key-file: ""

Agent配置

有 3 种配置 Pyroscope 代理的方法。配置优先级按以下顺序评估：

• 命令行参数

• 环境变量

• 配置文件

根据 Pyroscope 代理的运行方式，配置选项会有所不同

• pyroscope exec
• pyroscope connect
• pyroscope agent
• pyroscope adhoc

命令行参数

配置文件以 YAML 格式存储。您可以使用 -config <path> 参数指定配置文件位置，例如：

1

pyroscope agent -config /tmp/my-config.yml {args}

或者一个环境变量，例如：

1

PYROSCOPE_CONFIG=/tmp/my-config.yml pyroscope exec {args}

环境变量

环境变量必须具有 PYROSCOPE_ 前缀并采用 UPPER_SNAKE_CASE 格式，例如：

1

PYROSCOPE_API_BIND_ADDR=:9999 pyroscope server

pyroscope exec

该命令生成一个新进程并附加配置的探查器。一旦 pyroscope exec 退出，子进程也会退出，反之亦然。此命令可用于测试、作为 docker 入口点或作为 systemd 服务单元命令。

命令行参数

1

my.awesome.app{env=staging,region=us-west-1}

环境变量

环境变量必须具有 PYROSCOPE_ 前缀并采用 UPPER_SNAKE_CASE 格式，例如：

1

PYROSCOPE_APPLICATION_NAME=my.awesome.app

pyroscope connect

该命令将探查器附加到 PID 或操作系统指定的已运行进程（例如，ebpf 集成）。

命令行参数

参数与 pyroscope exec 相同，只是 pyroscope connect 需要指定 -pid：

1

my.awesome.app{env=staging,region=us-west-1}

环境变量

环境变量必须具有 PYROSCOPE_ 前缀并采用 UPPER_SNAKE_CASE 格式，例如：

1

PYROSCOPE_APPLICATION_NAME=my.awesome.app

pyroscope agent

该命令持续跟踪配置的目标并将分析器附加到它们。此命令主要应该在诸如 systemd 或 Windows 服务控制管理器之类的服务管理器的上下文中运行，或者在事先不知道目标应用程序时运行。

命令行参数

配置文件选项

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

---
# Log file path.
log-file-path: ""

# Log level: debug|info|warn|error.
log-level: "info"

# Disables logging from pyroscope.
no-logging: "false"

# Address of the pyroscope server.
server-address: "http://localhost:4040"

# Authorization token used to upload profiling data.
auth-token: ""

# Number of upload threads.
upstream-threads: "4"

# Profile upload timeout.
upstream-request-timeout: "10s"

# List of targets to be profiled.
targets: []

# Tag key value pairs.
tags: {}

目标描述要分析的应用程序。目前唯一支持的类型是系统服务。 请注意，不能使用命令行参数的同时使用环境变量指定目标。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

---
# Name of the system service to be profiled.
service-name: ""

# Name of the profiler you want to use. Supported ones are: pyspy, rbspy, phpspy, dotnetspy, ebpfspy.
spy-name: ""

# Application name used when uploading profiling data.
application-name: ""

# Sample rate for the profiler in Hz. 100 means reading 100 times per second.
sample-rate: "100"

# Makes pyroscope keep track of and profile subprocesses of the main process.
detect-subprocesses: "true"

# Enables blocking mode for pyspy.
pyspy-blocking: "false"

# Enables blocking mode for rbspy.
rbspy-blocking: "false"

1

my.awesome.app{env=staging,region=us-west-1}

环境变量

环境变量必须具有 PYROSCOPE_ 前缀并采用 UPPER_SNAKE_CASE 格式，例如：

1

PYROSCOPE_APPLICATION_NAME=my.awesome.app

示例

此示例显示了如何分析名称为 MyService 的系统服务：

1
2
3
4
5
6
7

---
log-level: "debug"
server-address: http://pyroscope-server:4040
targets:
 - application-name: my.dotnet.svc
   spy-name: dotnetspy
   service-name: MyService

pyroscope adhoc

此命令将分析数据保存到文件中，而不是将其发送到服务器。它以两种方式生成这些文件：

• Pyroscope 默认以本机格式和数据目录存储分析数据。然后，这些配置文件可用于使用 pyroscope UI（“Adhoc Profiling”部分）进行分析，这需要一个正在运行的 pyroscope 服务器。可以使用 --no-json-output 禁用此输出。
• Pyroscope 还以外部格式生成分析数据。根据生成的配置文件的数量，pyroscope 将在运行 pyroscope 的目录中生成文件或目录。当前支持的格式是独立的 HTML（然后可以共享或直接在浏览器中打开进行分析）、pprof 或折叠（最后两种可以共享并与 pyroscope UI 或其他工具一起使用）。标志 --output-format 用于指定此格式。

pyroscope adhoc 对于测试短期程序（脚本、基准等）很有用，它还可以轻松共享分析结果。

有多种方法可以收集分析数据（它支持所有代理模式），但并非所有方法都适用于所有语言。使用它的最佳方式取决于几个因素：语言支持什么，分析进程如何启动，以及分析进程如何提供分析数据。

不同的支持方式是：

• exec: 这是 pyroscope exec 的 adhoc 版本，pyroscope 为分析的程序创建不同的进程，并使用 spy 直接收集分析数据。但它仅适用于spy可用的语言。当提供spy（使用--spy-name）或自动检测到spy时，这是默认设置。
• connect: 这是 pyroscope connect 的临时版本。它与 exec 类似，但它监视一个通过 --pid 标志指示的 arlaedy 正在运行的进程。
• push: Pyroscope 为分析程序创建一个不同的进程，并启动一个带有采集数据端点的 HTTP 服务器。使用其 HTTP API 分析已经与 Pyroscope 集成的程序很有用。当没有检测到spy并且没有提供 --url 标志时，默认使用推送模式。它也可以用 --push 标志覆盖默认的执行模式。
• pull: 这是拉模式的临时版本，pyroscope 会定期连接到指定的 URL，通过 --url 尝试以任何支持的格式检索分析数据。参数是可选的，如果提供，它们用于在轮询 URL 之前启动新进程。

命令行参数

环境变量

环境变量必须具有 PYROSCOPE_ 前缀并采用 UPPER_SNAKE_CASE 格式，例如：

1

PYROSCOPE_APPLICATION_NAME=my.awesome.app

示例

adhoc examples

admin配置

删除应用

要删除应用程序

1

$ pyroscope admin app delete $APP_NAME

系统将要求您确认该应用名称：

1
2
3
4

> Are you sure you want to delete the app 'myapp'? This action can not be reversed.
> Type 'myapp' to confirm (without quotes).
myapp
> Deleted app 'myapp'.

如果您希望跳过该验证，可以使用 --force 标志：

1
2

$ pyroscope admin app delete myapp --force
> Deleted app 'myapp'.

默认情况下，使用 30 分钟的超时。您可以通过传递 --timeout 标志来覆盖该行为。

1
2

$ pyroscope admin app delete myapp --force --timeout=10s
> Deleted app 'myapp'.

警告

在执行该操作时，数据库将被锁定以进行写入，这意味着可能会删除大量分析数据，具体取决于命令运行所需的时间（尽管我们尝试最小化它持有锁定的时间）。

FlameQL

本文档介绍了 FlameQL，这是一种 Pyroscope 查询语言，使用户能够探索分析数据。

概念

数据模型

Pyroscope 存储与应用程序关联的分析数据。一个应用程序可能有多种不同的配置文件类型，例如：cpu、alloc_space、inuse_space 等。通常，分析器报告通过程序采样收集的数据，因此每个样本描述一个程序调用堆栈，以及在一个位置，例如源文件/行或函数名。

每个样本也由元数据描述，允许用户查询和聚合收集的分析数据。在 pyroscope 中，我们使用标签为收集的样本设置任意键值。如果您熟悉 Prometheus，您可能会将其视为标签。标签是数据结构的可选部分；当涉及到查询时，它们变得非常有用。

给定一个应用程序名称和一个标签集，使用以下符号标识完全限定名称：

1

<application_name>[{[<tag_key>=<tag_value>[,<tag_key>=<tag_value>]]}]

例如，标记为区域 us-west-1 和 env staging 的 my-awesome-app 应用程序实例的 CPU 配置文件的完全限定名称采用以下形式：

1

my.awesome.app.cpu{env=staging,region=us-west-1}

约束

标签键可能包含 ASCII 字母、数字和 _。应用程序名称可能包含 ASCII 字母、数字、_、- 和 ..

保留的标签键

以下密钥保留供内部使用，不应使用：

• __name__

查询表达式语言

FlameQL 中的查询表示如下：

1

<application_name>[{[<tag_matcher>[,<tag_matcher>]]}]

在最简单的形式中，仅指定应用程序名称。例如，考虑最简单的查询：

1

my.awesome.app

这样的查询将返回 my.awesome.app 的所有实例的聚合数据。到目前为止，只有 sum 聚合可用 - 生成的配置文件将是所有找到的配置文件的合并

可以通过在花括号 ({}) 中附加一个逗号分隔的标签匹配器列表来过滤要聚合的实例——标签匹配器是指定条件以根据相关标签包含或排除维度的表达式。

支持的操作符：

• = 必须完全等于提供的字符串
• =~ 必须正则表达式匹配提供的字符串
• != 不能等于提供的字符串
• !~ 不得与提供的字符串进行正则表达式匹配

示例

无论标签如何，所有应用程序实例：

1

my.awesome.app.cpu

无论标签如何，所有应用程序实例：

1

my.awesome.app.cpu{}

带有 env=staging 标记的应用程序实例：

1

my.awesome.app.cpu{env="staging"}

未使用 env=staging 标记的应用程序实例：

1

my.awesome.app.cpu{env!="staging"}

使用 env=staging AND region=us-west-1 标记的应用程序实例：

1

my.awesome.app.cpu{env="staging",region="us-west-1"}

未使用 env=staging 标记且区域标记值等于 us-west-1 或 eu-west-1 的应用程序实例：

1

my.awesome.app.cpu{env!="staging",region=~"us-west-1|eu-west-1"}

带有以 us 开头且不包含 west 的标签区域的应用程序实例：

1

my.awesome.app.cpu{region=~"us.*",region!~".*west.*"}