开发者必看如何为 otel-desktop-viewer 贡献代码的完整教程【免费下载链接】otel-desktop-viewerotel-desktop-viewer is a CLI tool for receiving OpenTelemetry traces while working on your local machine.项目地址: https://gitcode.com/gh_mirrors/ot/otel-desktop-viewer欢迎来到 OpenTelemetry 桌面查看器的贡献指南 无论你是 Go 后端开发者、前端工程师还是想为开源项目做出贡献的初学者这篇文章将为你提供详细的 otel-desktop-viewer 贡献教程。otel-desktop-viewer 是一个强大的 CLI 工具用于在本地机器上接收和可视化 OpenTelemetry 追踪、指标和日志数据。为什么选择 otel-desktop-viewer 项目 otel-desktop-viewer 是一个基于 Go 构建的开源项目它结合了 OpenTelemetry Collector 的强大功能和现代化的 Svelte 5 前端界面。项目采用 DuckDB 作为后端存储提供出色的本地开发体验。作为一个相对年轻但功能完整的项目它非常适合想要学习现代监控工具开发、Go 后端架构和 Svelte 前端技术的开发者。准备工作与环境搭建 ⚙️必备工具清单在开始贡献之前请确保你的开发环境已准备好以下工具工具版本要求备注Go1.26查看 go.mod 确认版本Node.js npm最新稳定版用于 Svelte 前端开发CGO必须启用DuckDB 绑定需要 C 工具链Windows 用户MSYS2 UCRT64需要 GCC 编译环境克隆项目仓库首先克隆项目到本地git clone https://gitcode.com/gh_mirrors/ot/otel-desktop-viewer.git cd otel-desktop-viewer make installWindows 用户特别说明Windows 开发者需要安装 MSYS2 UCRT64 环境安装 MSYS2从 https://www.msys2.org/ 下载安装打开 MSYS2 UCRT64 终端安装必要包pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-toolchain配置环境变量将 MSYS2 添加到 PATH项目架构快速了解 ️在开始编码之前了解项目架构非常重要。otel-desktop-viewer 的核心组件包括后端架构主入口main.go 和 components.go - OpenTelemetry Collector 配置桌面导出器desktopexporter/ - 核心业务逻辑HTTP JSON-RPC 服务desktopexporter/internal/server/ - API 服务层数据存储desktopexporter/internal/store/ - DuckDB 数据存储前端架构Svelte 5 UIdesktopexporter/internal/frontend/ - 现代前端界面构建系统Vite TypeScript Tailwind/DaisyUI开发工作流详解 快速启动开发环境最简单的开始方式是使用示例数据make dev-go这个命令会启动 Go 服务器在:8000端口自动注入示例的追踪、日志和指标数据并打开嵌入式 UI。前端开发模式推荐 UI 工作如果你主要进行前端开发建议使用两个终端# 终端 1 - 后端 示例遥测数据 make dev-go # 终端 2 - Vite 热重载前端 make dev-ts然后在浏览器中打开http://localhost:3001。Vite 开发服务器会自动将/rpc请求代理到 Go 服务器的:8000端口。生产模式构建与测试要构建生产版本并运行make build ./otel-desktop-viewer如果你修改了前端代码需要运行make build-ts将前端构建到desktopexporter/internal/server/static/目录中这样独立二进制文件才能包含最新的前端代码。数据种子脚本开发过程中你可能需要生成测试数据make populate-traces # 生成追踪数据 make populate-logs # 生成日志数据 make populate-metrics # 生成指标数据这些脚本使用 scripts/seed.pl 生成 OTLP 数据。建议先运行populate-traces然后再运行populate-logs这样日志记录就能链接到实际存在的追踪UI 的日志→追踪深度链接功能需要这个。如何开始你的第一个贡献 1. 寻找合适的贡献点如果你是第一次贡献可以从以下方面入手文档改进README、ARCHITECTURE.md 或代码注释Bug 修复查看项目的 Issue 列表UI 优化前端界面改进或用户体验优化测试用例补充缺失的单元测试或集成测试2. Go 后端开发指南Go 代码主要位于desktopexporter/目录下使用any而不是interface{}运行测试make test-go或cd desktopexporter go test ./...存储和 JSON-RPC 处理器是大多数后端逻辑的所在DuckDB 模式变更需要谨慎思考 - 参考 ARCHITECTURE.md重要提示不要手动编辑 OCB 生成的收集器连接代码main.go/components.go除非你明确知道需要这样做。建议在desktopexporter/中进行修改并在更新组件时通过收集器构建器重新生成。3. 前端开发指南前端使用 Svelte 5 TypeScript代码位置desktopexporter/internal/frontend/代码格式化make format-ts类型检查make validate-ts运行测试cd desktopexporter/internal/frontend npm test在引入新的抽象之前请先匹配附近组件的现有模式。提交 Pull Request 的最佳实践 提交前的检查清单在提交 PR 之前请确保make test这个命令会运行 Go 测试和前端类型检查 - 这是代码审查前的基本要求。CI 会在Ubuntu、macOS 和 Windows上为每个拉取请求构建项目。Windows 需要 CGO MSYS2与本地开发环境相同。PR 描述要求在你的 PR 描述中请包含说明改变了什么以及为什么改变测试方法如何测试这些更改命令、UI 更改的截图相关链接如果有相关 Issue请链接它们尽量保持 PR 的专注性 - 这样更容易审查也更容易合并。Git 中的静态资源生产构建将前端输出嵌入到desktopexporter/internal/server/static/目录下。如果你的 PR 改变了 UI请包含make build-ts生成的更新静态资源以确保 CI 和发布构建匹配。常见问题与解决方案 ️问题编译时 CGO 错误解决方案确保 CGO 已启用并安装了正确的 C 编译器。Windows 用户必须使用 MSYS2 UCRT64 环境。问题前端更改未生效解决方案运行make build-ts重新构建前端然后重新运行make build。问题测试失败解决方案检查 Go 和 Node.js 版本是否符合要求。运行go version和node --version确认。问题端口冲突解决方案otel-desktop-viewer 默认使用端口 8000Web UI、4317gRPC和 4318HTTP。如果这些端口被占用可以通过命令行参数修改。代码规范与最佳实践 Go 代码规范遵循 Go 社区约定使用有意义的变量名和函数名为公共 API 添加文档注释保持函数简洁单一职责前端代码规范使用 TypeScript 类型系统遵循 Svelte 5 的最佳实践保持组件模块化和可重用使用 Tailwind CSS 实用类测试策略为复杂逻辑编写单元测试集成测试覆盖主要功能前端组件测试使用 Svelte Testing Library社区参与与行为准则 在参与贡献之前请阅读我们的 行为准则。我们希望这个项目能像应用程序本身一样平易近人。如何获得帮助不确定从哪里开始可以开一个 Issue 打个招呼小修复是很好的首次贡献社区成员很乐意帮助新贡献者许可证说明通过贡献你同意你的贡献将根据项目的 Apache 2.0 许可证 进行许可。总结与下一步 为 otel-desktop-viewer 贡献代码是一个很好的学习机会不仅能提升你的 Go 和 Svelte 技能还能深入了解 OpenTelemetry 生态系统。记住从小处着手- 从文档修复或小功能开始遵循现有模式- 查看相似功能的实现方式充分测试- 确保你的更改不会破坏现有功能寻求反馈- 不要害怕在 PR 中提出问题或寻求澄清现在你已经掌握了为 otel-desktop-viewer 贡献代码的完整指南是时候开始你的开源贡献之旅了 选择你感兴趣的任务克隆仓库开始编码吧如果你在贡献过程中遇到任何问题欢迎查看项目的 官方文档 或在 Issue 中提问。祝编码愉快【免费下载链接】otel-desktop-viewerotel-desktop-viewer is a CLI tool for receiving OpenTelemetry traces while working on your local machine.项目地址: https://gitcode.com/gh_mirrors/ot/otel-desktop-viewer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
