Grafana Pyroscope 贡献指南从 PR 工作流、构建到测试的完整实战解析【免费下载链接】pyroscopeContinuous Profiling Platform. Debug performance issues down to a single line of code项目地址: https://gitcode.com/GitHub_Trending/py/pyroscope本文以 Grafana Pyroscope 仓库的官方贡献文档 docs/internal/contributing/README.md 为核心脉络结合仓库根目录 Makefile、go.mod、pkg/pyroscope/modules.go 等构建与运行源码完整讲解向 Pyroscope 提交代码的标准工作流PR 规范与签名提交要求、本地工具链准备、代码格式化标准、前端/后端/镜像的多种构建方式、单元测试运行、依赖管理以及文档站点的本地预览。读完本文你将掌握一套可直接执行的 Pyroscope 本地开发与验证流程并理解每个 make 目标背后的实现细节能够顺利地把第一个补丁推进到可合并状态。一、仓库与文档概览Grafana Pyroscope 是一个持续性能分析平台Continuous Profiling Platform定位为调试性能问题直至单行代码级别。仓库采用 Go 为主体的后端cmd/、pkg/与 React Vite TypeScript 编写的前端ui/组合并附带独立的 API 模块api/与符号解析库lidia/。本文关联的贡献文档位于 docs/internal/contributing/README.md它面向所有希望向项目提交代码的开发者覆盖了从「提出 PR」到「构建产物」「跑通测试」「更新依赖」「预览文档」的完整开发闭环。下文将逐节展开并在每一节补充仓库源码级的实现细节作为佐证。二、标准 PR 工作流Pyroscope 遵循标准的 GitHub Pull Request 工作流开发者 fork 仓库、创建分支、提交变更、发起 PR由维护者评审后合并。文档建议随时可以创建 Draft PR。无论工作处于何种完成度都可以提前创建草稿 PR用于向维护者求助或展示开发思路。在功能完成之前PR 应满足以下要求组织良好的提交工作应组织为一个或多个 commit每个 commit 的提交信息应描述该提交所做的全部变更且更侧重说明「为什么改」why而非「改了什么」what——代码差异diff本身已经能说明 what提交信息应补充决策背景。提交之间循序渐进每个 commit 都应朝最终目标推进不要遗留后来被推翻的回退或错误修复。配套测试新功能必须有对应的单元测试修复 bug 的提交应有能捕获该 bug 的测试用例。同步生成产物如果改动涉及 flag、配置项或 protobuf 定义必须运行make generate并提交生成的文件。关于第 4 点从根目录 Makefile 可以看到generate目标的真实执行内容它会先通过go install拉取buf、protoc-gen-go、protoc-gen-go-vtproto、protoc-gen-openapiv2、protoc-gen-grpc-gateway、protoc-gen-connect-go、protoc-gen-connect-go-mux、gomodifytags、protoc-gen-connect-openapi等代码生成工具随后清空并重新生成api/openapiv2/gen/、api/gen/删除并重新生成pkg/下所有*.pb.go与*.connect*.go文件再运行./tools/add-parquet-tags.sh添加 parquet 标签最后用 tools/doc-generator 重新生成参考配置文档 docs/sources/configure-server/reference-configuration-parameters/index.md 与示例配置 cmd/pyroscope/pyroscope.yaml并运行 tools/api-docs-generator 更新 API 文档。也就是说任何涉及 API 契约protobuf或配置结构的改动都应当让make generate重新产出对应的 Go 桩代码、OpenAPI 定义、配置文档与示例确保「源码—生成代码—文档」三者始终一致。三、签名提交要求Signed Commits自 2026 年 6 月 22 日起Grafana Labs 旗下所有仓库含 Pyroscope都要求 PR 使用签名提交signed commits。未签名的提交与 PR 将被拒绝并关闭——包括由 Agent 代写的 PR。因此在实际操作中需要在本地配置 GPG/SSH 签名密钥并通过git commit -S或全局配置commit.gpgsign true对每次提交进行签名。建议在提交前检查签名验证状态确保 PR 头部显示「Verified」标记。这一要求属于仓库的硬性门槛即使功能实现正确签名缺失也会直接导致 PR 被拒。四、本地环境要求与工具链自动下载运行 make 目标所需的本地环境非常精简只需要两个基础依赖Go版本要求见 go.mod。当前仓库的 go.mod 声明go 1.26.0并指定toolchain go1.26.8贡献文档描述的最低要求为 1.25。Docker用于前端构建与文档构建等依赖容器环境的任务。除此之外的所有工具buf、golangci-lint、gotestsum、helm、goreleaser、kind、tk、jb等都会在首次使用时自动下载到$(pwd)/.tmp/bin目录不需要手工安装。这一点可以从根目录 Makefile 的BIN : $(CURDIR)/.tmp/bin以及各类$(BIN)/xxx目标例如 Makefile 中go install github.com/bufbuild/buf/cmd/bufv1.31.0、github.com/golangci/golangci-lint/v2/cmd/golangci-lintv2.2.2得到印证每个工具都有对应的「若缺失则自动安装」规则且版本号被显式固定保证所有贡献者使用一致的版本。如果贡献者需要引入一个新的 CLI 工具官方建议遵循同样的模式在 Makefile 中新增一个$(BIN)/xxx目标让工具随目标自动下载到.tmp/bin。五、代码格式化与 lintPyroscope 使用golangci-lint统一格式化 Go 文件并整理 import 顺序。关键的约定是goimports 以-local github.com/grafana/pyroscope参数运行将Grafana Pyroscope 内部 import单独分为一组所有 import 尽量保持三组顺序标准库→第三方包→Grafana Pyroscope 内部包goimports 会自动修正顺序但会保留组内已有的空行因此不要在 import 组内引入多余空行。运行make lint即可检查格式是否正确。在根目录 Makefile 中lint目标实际聚合了四类检查lint: go/lint helm/lint buf/lint goreleaser/lint其中go/lintMakefile会对仓库根模块、api模块、lidia模块分别执行golangci-lint run ./...与go vet ./...helm/lint会校验 operations/pyroscope/helm/pyroscope 与 operations/monitoring/helm/pyroscope-monitoring 两个 Helm Chartbuf/lint检查 api/ 与 pkg/ 下的 protobuf 定义goreleaser/lint则校验发布配置。此外make fmtMakefile可以自动修复一部分 lint 问题它对 git 托管的*.go文件执行gofmt -s运行golangci-lint run --fix并用buf format -w格式化 protobuf 文件、用tk fmt格式化 jsonnet。六、构建 Grafana Pyroscope贡献文档提供了三个不同粒度的构建入口分别适用于不同场景。6.1 生产构建make build执行完整的生产构建前端 后端make build该目标Makefile等价于frontend/buildgo/bin先用make frontend/build在 Docker 中构建 Web UI因此要求 Docker 正在运行再编译 Go 二进制并将前端资源嵌入其中。frontend/buildMakefile实际执行docker build -f cmd/pyroscope/frontend.Dockerfile --outputui/dist .从 cmd/pyroscope/frontend.Dockerfile 可以看到构建细节基于node:24镜像通过 Yarncorepack 启用执行yarn install --immutable与yarn build构建产物输出到ui/dist/最后由scratch阶段把dist目录导出到宿主机供 Go 侧以embed方式打包。6.2 后端开发构建make build-dev如果只改后端、不需要嵌入式 UI可以使用无需 Docker 的开发构建完全跳过前端make build-dev其实现Makefile是build-dev: $(MAKE) EMBEDASSETS go/bin即通过清空EMBEDASSETS构建标签来跳过前端资源的嵌入。6.3 底层目标make go/binmake go/bin只编译 Go 二进制Pyroscope 主程序与 cmd/profilecli 工具。默认情况下它带有embedassets构建标签根目录 Makefile 中EMBEDASSETS ? embedassets编译时使用-tags netgo $(EMBEDASSETS)见 Makefile因此要求ui/dist/已经存在——需要先用make frontend/build构建一次或者直接使用make build/make build-dev。否则会报错pattern dist: no matching files found其编译参数还体现了发布侧的要求GOAMD64v2、CGO_ENABLED0、-extldflags -static并注入分支、版本、revision、构建日期等构建信息Makefile。七、运行单元测试运行完整单元测试套件make go/test其实现Makefile使用gotestsum作为测试运行器关键行为包括对根模块运行go list ./...并排除/test/integration包集成测试走独立的make go/test-integration因为api与lidia是独立 Go module见 api/go.mod、lidia/go.mod会分别在各自目录下再跑一遍测试默认开启--rerun-fails2失败的测试自动重跑最多两次以过滤偶发失败默认测试参数为-race -coverMakefile即开启竞态检测与覆盖率统计。八、构建 Docker 镜像构建 Pyroscope 的 Docker 镜像make docker-image/pyroscope/build该目标Makefile会先构建前端frontend/build再以GOOSlinux编译 Go 二进制最后通过docker buildx build --load产出镜像。因此如果目标平台与当前开发机不一致需要显式传入正确的GOOS与GOARCH环境变量amd64 构建make GOOSlinux GOARCHamd64 docker-image/pyroscope/buildarm64 构建make IMAGE_PLATFORMlinux/arm64 GOOSlinux GOARCHarm64 docker-image/pyroscope/build这里IMAGE_PLATFORM在 Makefile 中默认由linux/$(GOARCH)推导Makefile所以构建 arm64 镜像时需要同时覆盖GOARCH与IMAGE_PLATFORM。仓库还提供了docker-image/pyroscope/build-multiarch、build-debug、push、push-multiarch等衍生目标Makefile其中-debug系列会额外安装 Delve 调试器dlv到镜像中。8.1 在本地运行构建出的镜像本地运行示例时把 docker-compose 文件中image: grafana/pyroscope替换为本次构建产出的本地镜像标签make docker-image/pyroscope/build会打印该标签例如grafana/pyroscope:main-470125e1-WIPpyroscope: image: grafana/pyroscope:main-470125e1-WIP ports: - 4040:4040仓库中 examples/ 目录下的各类示例如 examples/base-url/docker-compose.yml都遵循这一模式替换镜像标签后即可用 docker compose 拉起本地环境进行验证。九、一键体验完整链路嵌入式 Grafana 与 Profiles Drilldown为快速验证整个技术栈可以用单一命令启动「Pyroscope 服务端 嵌入式 Grafana」go run ./cmd/pyroscope --target all,embedded-grafana这会启动 Pyroscope 主服务监听:4040与嵌入式 Grafana监听:4041。其中embedded-grafana是 Pyroscope 的运行时模块之一可以从 pkg/pyroscope/modules.go 的模块常量表中看到它的定义EmbeddedGrafana string embedded-grafana其实现位于 pkg/embedded/grafana/assets.go、grafana.go及对应测试。通过--target参数可以按需组合all、api、distributor、ingester、querier、store-gateway、compactor、metastore、segment-writer、query-backend等二十余个模块这也是 Pyroscope 支持单二进制部署与微服务化部署的机制基础。十、前端开发需要特别说明的是Pyroscope 自带的前端应用目前已不在活跃开发状态。虽然它提供的 UI 可用且稳定但官方推荐使用 Grafana 的Profiles Drilldown应用来查看与分析 profiling 数据该应用在较新版本的 Grafana 中已预装。如果确实需要改动前端代码可以按以下步骤进行。前端位于 ui/ 目录是一个依赖极简的重写版本React Vite TypeScript取代了旧的public/appUI权威的前端指南见 ui/CLAUDE.md 与 ui/DESIGN.md。前端使用Yarn 4Berry作为包管理器其package.json位于ui/目录而非仓库根目录。从 ui/package.json 可以看到依赖仅包含react、react-dom、xyflow/react、tinycolor2、leeoniya/ufuzzy等少量包且通过packageManager: yarn4.13.0锁定 Yarn 版本。以开发模式运行前端cd ui yarn install yarn devVite 开发服务器会监听http://localhost:5173并将 API 请求代理到http://localhost:4040上的 Pyroscope 服务端。因此需要另开一个终端先启动后端go run ./cmd/pyroscope此外ui/package.json 还提供了buildtsc -b vite build、type-check、lint、test基于 Node 内置 test runner、e2ePlaywright等脚本配合 playwright.config.ts 可进行端到端测试。十一、依赖管理项目使用Go modules管理外部依赖但不提交vendor/目录。仓库是一个多模块工程根模块之外api/、lidia/以及 examples/ 下的部分示例目录各自拥有独立的go.mod根目录 Makefile 中的GO_MOD_PATHS变量列出了全部受管模块。添加或更新依赖使用go get# 选取最新的 tagged release go get example.com/some/module/pkg # 选取指定版本 go get example.com/some/module/pkgvX.Y.Z随后整理go.mod与go.summake go/modgo/mod目标Makefile会遍历GO_MOD_PATHS中列出的所有子模块对每个模块依次执行go mod download、go mod verify与go mod tidy保证根模块与所有子模块的依赖文件同步。最后在提交 PR 前务必提交go.mod与go.sum的变更。十二、文档站点本地构建Grafana Pyroscope 的文档会被编译并发布到 grafana.com 网站。要在本地启动文档站点make docs/docs命令运行后会打印如何访问本地站点的指引。从根目录 Makefile 可以看到docs/%目标会委派给docs子目录的 Makefiledocs/%: $(MAKE) -C docs $*于是make docs/docs等价于在 docs/ 下执行make docs。而 docs/docs.mk 中定义的docs目标会拉取grafana/docs-base:latest容器镜像默认PULLtrue可通过PULLfalse跳过然后调用 docs/make-docs 脚本在容器中启动 Hugo 服务器默认发布端口为3002可通过DOCS_HOST_PORT覆盖。项目列表由 docs/variables.mk 中的PROJECTS变量提供内容以「pyroscope」为项目名挂载当前仓库的 docs/sources/ 目录。需要提醒的是如果在 GitHub 网页上直接浏览仓库内的文档页面很可能看到失效链接或页面。这是预期现象文档是为 Hugo 站点构建设计的依赖站点级的重定向机制除非确实影响站点构建否则无需修复这些链接。若想校验文档中 relref 链接的完整性可以在 docs/ 目录运行make test——它会以HUGO_REFLINKSERRORLEVELERROR的严格模式在grafana/docs-base:latest容器内执行 Hugo 构建将链接错误升级为构建失败。十三、常见问题与自检清单围绕上述流程实际贡献时最常踩的坑可以归纳为场景处理方式依据改动涉及 protobuf / 配置 / flag运行make generate并提交生成文件贡献文档 Workflow 小节 Makefile本地没有安装 buf、golangci-lint 等工具无需手工安装首次运行 make 目标会自动下载到.tmp/binMakefilemake go/bin报pattern dist: no matching files found先执行make frontend/build生成ui/dist/或改用make build-devMakefile只改后端不想等前端构建使用make build-dev跳过前端、不嵌入资源Makefile提交未签名导致 PR 被拒配置 GPG/SSH 签名并启用git commit -S贡献文档 Signed Commits 小节导入顺序不合规按「标准库 → 第三方 → 内部github.com/grafana/pyroscope」三组排列跑make lint校验贡献文档 Formatting 小节 Makefile新增/升级依赖go get后运行make go/mod提交go.mod、go.sum贡献文档 Dependency management 小节 Makefile想要快速端到端验证go run ./cmd/pyroscope --target all,embedded-grafanaPyroscope:4040Grafana:4041贡献文档 pkg/pyroscope/modules.go结语从这份贡献指南可以看出Grafana Pyroscope 的工程化程度相当高所有辅助工具通过 Makefile 自动下载并锁定版本生成代码、配置文档与 protobuf 定义由make generate统一驱动测试、lint、构建、文档各有明确的 make 入口且api、lidia等子模块被作为独立 Go module 分别验证。对贡献者而言只要遵循「签名提交 → 规范 commit → 配套测试 → 必要时make generate→make lint/make go/test通过」这条主线就能以较低的门槛提交出符合项目标准的高质量补丁。【免费下载链接】pyroscopeContinuous Profiling Platform. Debug performance issues down to a single line of code项目地址: https://gitcode.com/GitHub_Trending/py/pyroscope创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考