HyperDX 架构深度解析：从 OpenTelemetry 采集到 ClickHouse 查询的完整体系

可观测性云原生运维【免费下载链接】hyperdxResolve production issues, fast. An open source observability platform unifying session replays, logs, metrics, traces and errors powered by ClickHouse and OpenTelemetry.项目地址https://gitcode.com/gh_mirrors/hy/hyperdx点击查看免费下载导读本文基于 HyperDX 官方架构文档agent_docs/architecture.md系统拆解这套开源可观测性平台的端到端体系从 OpenTelemetry Collector 的数据采集到 ClickHouse 的主数据存储、MongoDB 的元数据管理再到 API 包中一包多应用的后端形态内部 API、外部 API v2、MCP 服务器、OpAMP 服务器与后台任务。阅读本文后你将掌握 HyperDX 的核心服务划分、数据流动链路、多租户模型设计以及如何通过源码路径定位每个组件的实现细节为二次开发与自托管部署建立完整的架构认知。核心服务总览五大组件构成平台骨架HyperDX 由五个核心服务协同工作覆盖从数据采集、存储到用户交互的完整链路组件位置职责HyperDX UIpackages/appNext.js 前端为用户提供查询、仪表盘、告警等交互界面HyperDX APIpackages/apiNode.js/Express 后端处理查询请求与业务逻辑OpenTelemetry Collectordocker/otel-collector接收并处理遥测数据logs、metrics、traces、sessionsClickHousedocker/clickhouse所有遥测数据的主存储logs、metrics、tracesMongoDBpackages/api/migrations/mongo元数据存储用户、仪表盘、告警、已保存搜索这种ClickHouse 存遥测、MongoDB 存元数据的双存储设计是 HyperDX 架构的基石高基数、时间序列型遥测数据交给列式存储 ClickHouse 高效聚合而低频访问的关系型元数据则放在文档型数据库 MongoDB 中便于灵活的 schema 演进。从技术栈文档agent_docs/tech_stack.md可以看到各层的具体选型前端使用 Next.js 16 TypeScript Mantine UI Jotai/TanStack Query后端使用 Node.js 22 Express Mongoose Passport.js Zod 校验API 自身还通过hyperdx/node-opentelemetry实现自埋点观测。端到端数据流从业务应用到可观测面板HyperDX 的数据流是一条清晰的单向管道见 agent_docs/architecture.md应用发送遥测数据业务应用通过 OpenTelemetry SDK/Agent 将 logs、metrics、traces 发送给 OTel CollectorOTLP 协议gRPC:4317/ HTTP:4318Collector 处理并转发OTel Collector 完成接收、处理路由、批处理等后将数据写入 ClickHouse用户经 UI 查询用户在 UI 上的查询请求打到 APIAPI 再查询 ClickHouse 取回数据配置/元数据存 MongoDB团队、用户、仪表盘、告警等配置信息持久化在 MongoDB 中。一个值得关注的细节是Collector 的处理器processors:列表被刻意放在引导配置 docker/otel-collector/config.yaml 中声明而非由 OpAMP 远程配置下发。这一设计见opampController.ts中的注释与 PR #2351保证了用户可以通过CUSTOM_OTELCOL_CONFIG_FILE自定义处理器例如替换memory_limiter的limit_percentage与limit_mib避免远程配置覆盖本地定制。MongoDB 元数据层团队级多租户与模型规范所有 MongoDB 模型都遵循一致的模式约定packages/api/src/models团队级多租户大多数实体归属于某个team数据访问天然按团队隔离ObjectId 引用相关实体之间使用 ObjectId 建立引用关系便于 Mongoose populate审计时间戳模型普遍包含创建/更新时间戳Zod schema 校验使用 Zod 进行入参校验前后端共享校验逻辑。关键模型一览全部位于 packages/api/src/models模型文件说明Teamteam.ts多租户组织单元承载 apiKey、collectorAuthenticationEnforced等关键字段Useruser.ts团队成员包含认证信息Passport local strategySourcesource.tsClickHouse 数据源配置定义遥测 schema 映射Connectionconnection.ts数据库连接设置SavedSearchsavedSearch.ts已保存的查询与过滤器Dashboarddashboard.ts自定义仪表盘配置Alertalert.ts带阈值的监控告警Schema 变更通过版本化迁移管理见 packages/api/migrations/mongoMongo 迁移与 packages/api/migrations/chClickHouse 迁移。前端架构Pages Components Hooks 分层前端packages/app遵循清晰的目录分层Pages页面层packages/app/pages —— Next.js 路由页面包括搜索search/index.tsx、仪表盘dashboards/index.tsx、告警alerts/index.tsx、trace 详情trace/[traceId].tsx、sessions 回放sessions.tsx等Components组件层packages/app/src/components —— 可复用组件例如图表组件DBTimeChart.tsx、DBTableChart.tsx、搜索过滤器DBSearchPageFilters.tsx、侧边面板DBRowSidePanel.tsx等API 通信自定义 hooks 封装 TanStack Query例如 useChartConfig.tsx、useDashboardFilters.tsx状态管理全局客户端状态用 Jotai服务端状态用 TanStack Query过滤器等 URL 参数直接由路由承载详见 agent_docs/tech_stack.md。图表可视化采用 Recharts 与 uPlotSQL/JSON 编辑器使用 CodeMirror图标统一使用tabler/icons-react。后端架构API 包中的一包多应用packages/api并不仅仅是一个 Express 服务而是承载了多个各具路由、认证与限流策略的独立应用。这一点在 api-app.ts 中体现得淋漓尽致主应用挂载内部路由session 认证、/mcpAccess Key 认证、/api/v2外部 API与 OpAMP 子应用等。整体目录结构分为routers路由、controllers业务逻辑、middleware认证/CORS/错误处理、services可复用业务逻辑四层。内部 API面向 Web 前端的会话认证接口内部 APIpackages/api/src/routers/api是 Web 前端packages/app消费的主 API采用Passport.js 会话认证local strategy express-sessionsession 存储于 MongoDB见 api-app.ts 中 MongoStore 配置cookie 有效期 30 天。标准分层结构Routerssrc/routers/api/ —— 领域路由包括alerts.ts、dashboards.ts、sources.ts、savedSearch.ts、webhooks.ts、clickhouseProxy.ts、prometheus.ts、iac.ts等Controllerssrc/controllers/ —— 业务逻辑与路由解耦如alerts.ts、dashboard.ts、sources.ts、timeseriesEngine.tsMiddlewaresrc/middleware/ —— 认证auth.ts、CORScors.ts、错误处理error.ts、校验validation.tsServicessrc/tasks/ 与 OpAMP 下的agentService.ts等提供可复用业务逻辑。从 api-app.ts 可以看到内部路由的挂载方式/ai、/alerts、/dashboards、/me、/team、/webhooks、/connections、/sources、/saved-search、/favorites、/pinned-filters、/clickhouse-proxy、/iac均通过isUserAuthenticated中间件保护PromQL 路由/v1/prometheus仅在IS_PROMQL_ENABLED时挂载。外部 API v2基于 Access Key 的公共 REST API外部 API v2src/routers/external-api/v2面向程序化访问认证方式与内部 API 完全不同使用Personal API Access KeyvalidateUserAccessKey中间件并限流至100 req/min每 API Key 每分钟 100 次窗口 60 秒见 index.ts 中rateLimiter配置启用标准RateLimit-*响应头。路由资源alerts.ts、charts.ts、dashboards.ts、sources.ts、webhooks.ts以及connections.ts、savedSearches.ts、search.ts、team.ts。OpenAPI 规范规范文件为 packages/api/openapi.json通过yarn docgen自动生成并用yarn lint:openapiSpectral校验。开发规范要求新增或修改外部 API 端点后必须运行yarn docgen重新生成 OpenAPI 规范再运行yarn lint:openapi校验scripts/ci/check-openapi-sync.sh 由make ci-lint及 CI 调用若提交的规范文件过期则 CI 失败swaggerOptionssrc/utils/swagger.ts也是 docgen 的输入规范文件被列入.prettierignore因为其格式由 docgen 独占管理测试位于 src/routers/external-api/tests如v2.int.test.ts、alerts.int.test.ts等集成测试。Swagger UI 仅在非生产环境且ENABLE_SWAGGER true时启用路径为/api/v2/docs。MCP 服务器让 AI 助手直接查询可观测性数据MCPModel Context Protocol。关键实现入口src/mcp/app.tsExpress 中间件与 src/mcp/mcpServer.ts服务器工厂createServer(context)无状态传输设计每次 POST 创建全新的 server/transportsessionIdGenerator: undefined因此不提供 GETSSE 流与 DELETE会话终止按 Streamable HTTP 规范返回 405SDK 客户端会将 405 视为未提供、继续OPTIONS 交由全局 CORS 中间件处理见 app.ts 中的 issue #2686 注释上下文注入从req.user提取teamId、userId构造McpContext并通过setTraceAttributes写入mcp.team.id、mcp.user.idspan 属性实现租户隔离与可观测工具集tools/ 下按领域划分 ——alerts/、dashboards/、query/、savedSearches/、sources/、trace/每个目录包含工具定义与处理器提示词prompts/dashboards/ —— 为 AI 助手提供上下文提示测试src/mcp/tests覆盖 alerts、dashboards、query、savedSearches、tracing调试yarn dev:mcp启动 MCP Inspector 进行交互式测试。从 mcpServer.ts 可以看到服务器内置了工具选择策略指令SERVER_INSTRUCTIONS默认优先使用 builder 查询工具更可靠、输出结构化图表数据原始 SQLclickstack_sql是最后手段推荐发现流程为clickstack_list_sources → clickstack_describe_source → query。用户侧接入配置详见根目录 MCP.md支持 Claude Code、Codex CLI、OpenCode、Cursor 等客户端端点均为your-hyperdx-url/api/mcp认证头为Authorization: Bearer your-personal-access-key。OpAMP 服务器为受管 Collector 下发远程配置OpAMPOpen Agent Management Protocol服务器以 HTTP 协议为受监督的 OpenTelemetry Collector 提供配置。监督器supervisor定期向/v1/opamp上报状态服务器在需要时返回更新的配置。关键实现入口src/opamp/app.ts —— Express 子应用使用express.raw({ type: application/x-protobuf, limit: 10mb })解析 protobuf 请求体额外提供/health存活探针与/ready就绪探针依赖 MongoDB 连接状态避免 Mongo 未就绪时 500 导致 Collector 崩溃循环见 issue #2966控制器controllers/opampController.ts —— 配置推导逻辑核心buildOtelCollectorConfig(teams)基于团队文档与 ingestion API key 动态生成 Collector 配置服务services/agentService.ts —— Agent 管理processAgentStatus、agentAcceptsRemoteConfig模型models/agent.ts —— Agent 状态持久化Protoproto/ —— OpAMP 与 anyvalue 的 Protocol Buffer 定义。配置推导机制值得深入理解buildOtelCollectorConfig根据teams[0]?.collectorAuthenticationEnforced决定是否启用bearertokenauth扩展对 OTLP receiver 做认证bearerTokenVariants会同时接受裸 token 与Bearer/bearer/BEARER前缀形式对应 RFC 6750 客户端习惯。生成配置中的典型管线包括otlp/hyperdxreceivergRPC0.0.0.0:4317、HTTP0.0.0.0:4318、clickhouse/clickhouse/rrwebexporter端点、数据库、TTL 等均通过${env:...}环境变量注入如CLICKHOUSE_ENDPOINT、HYPERDX_OTEL_EXPORTER_TABLES_TTL默认 TTL 720h、超时 5s、routing/logsconnector 将 rrweb 会话事件路由到独立表hyperdx_sessions。此外还可选启用datadogreceiverENABLE_DATADOG_RECEIVER开关监听:8126与 PromQL 的prometheusremotewriteexporterIS_PROMQL_ENABLED开关。OpAMP 控制器还以低基数outcome枚举processed / unsupported_media_type / error埋点hyperdx.opamp.messages、hyperdx.opamp.remote_configs计数器并将 Agent 的instanceUid、健康状态、能力标志、远程配置哈希等作为 span 属性写入便于单 trace 内切片定位某个 Agent。后台任务脱离请求/响应周期的 Cron 驱动任务后台任务src/tasks/运行在请求/响应周期之外。开发环境通过yarn dev-task运行生产环境由外部触发如 Cron。任务清单任务说明checkAlerts/告警评估开发环境每分钟运行一次provisionDashboards/从配置文件预置仪表盘usageStats.ts用量统计采集由USAGE_STATS_ENABLED控制见 api-app.tspingPongTask.ts健康检查任务metrics.ts任务执行指标耗时、成功/失败计数器注意后台任务不会在 Vercel preview 部署中运行详见 agent_docs/development.md。数据与查询模式ClickHouse 集成查询构建使用 packages/common-utils共享 TypeScript 工具包安全构建查询其中包含查询解析queryParser.ts、SQL 格式化sqlFormatter.ts、宏macros.ts等工具避免手工拼接 SQL 的注入风险Schema 灵活性通过Source配置支持多种遥测 schema 映射logs、traces、metrics、sessions、promql 等ClickHouse schema 由 docker/clickhouse 下的迁移脚本docker/otel-collector/schema/seed初始化例如00002_otel_logs.sql、00003_otel_metrics.sql、00004_hyperdx_sessions.sql、00005_otel_traces.sql以及对应的 rollup 表。MongoDB 模式多租户所有查询均按 team 上下文过滤validateUserAccessKey、isUserAuthenticated中间件与各模型中的team字段双重保障关系使用 ObjectId 引用 适当 populate索引为查询性能设置战略性索引迁移版本化迁移管理 schema 变更见 packages/api/migrations/mongo。安全要求不可妥协的基线架构文档明确列出的安全基线agent_docs/architecture.md服务端校验始终在后端进行校验与消毒Zod schemas 在 packages/api/src/utils/zod.ts 等统一封装外部请求体均经校验团队隔离所有数据访问必须按 team 上下文过滤防止跨租户越权API 认证受保护路由必须使用认证中间件内部 API 用isUserAuthenticated会话认证外部 API 与 MCP 用validateUserAccessKeyAccess Key 认证密钥管理绝不提交密钥到仓库使用.env文件如EXPRESS_SESSION_SECRET、MONGO_URI、CLICKHOUSE_USER/PASSWORD等配置项均通过环境变量注入。这些要求在实际代码中得到严格落实外部 API v2 与 MCP 在 index.ts 与 app.ts 中均在路由层统一挂载认证中间件与限流器OpAMP 端点的认证则通过为 OTLP receiver 附加bearertokenauth扩展完成且仅在所有团队存在 apiKey 且collectorAuthenticationEnforced为真时才启用。小结一张架构地图总结 HyperDX 的架构要点可以用一句话概括OpenTelemetry 负责采集ClickHouse 负责遥测存储与聚合MongoDB 负责元数据与多租户Express API 包以一包多应用形态对外提供会话式内部 API、Access Key 式外部 API、面向 AI 的 MCP 端点、面向受管 Collector 的 OpAMP 端点以及 Cron 驱动的后台任务。理解这张地图后无论是定位某个查询链路UI → API → ClickHouse、排查告警评估流程checkAlerts任务还是为 AI 助手接入数据查询MCP你都能沿着本文给出的源码路径快速直达实现核心。进一步深入可参考仓库根目录的 CLAUDE.md、LOCAL.md本地开发与 DEPLOY.md自托管部署以及架构配套文档 agent_docs/tech_stack.md、agent_docs/development.md 与 agent_docs/observability.md。赞分享可观测性云原生运维【免费下载链接】hyperdxResolve production issues, fast. An open source observability platform unifying session replays, logs, metrics, traces and errors powered by ClickHouse and OpenTelemetry.项目地址https://gitcode.com/gh_mirrors/hy/hyperdx点击查看免费下载相关推荐AgentOps v4 API 迁移指南从 Supabase 到 ClickHouse 的 OpenTelemetry 查询架构AgentOps v4 API 迁移指南从 Supabase 到 ClickHouse 的 OpenTelemetry 查询架构 AgentOps 正在将其数人工智能大模型LLMOps可观测性AI 评测Agent TracesParca架构深度解析从数据采集到存储查询的全链路设计Parca架构深度解析从数据采集到存储查询的全链路设计 Parca是一个开源的持续性能分析工具专门用于分析CPU和内存使用情况能够精确到代码行号并在时间维可观测性性能分析基于 Meshery Catalog 的 ClickHouse OpenTelemetry HyperDX 可观测性架构设计解析基于 Meshery Catalog 的 ClickHouse OpenTelemetry HyperDX 可观测性架构设计解析 本篇技术指南围绕 Me云原生微服务运维DevOps上一篇Gitalk生态系统周边工具与插件推荐下一篇Nancy框架终极指南10个让.NET Web开发更简单的革命性技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考