尧图网站建设 
可观测性云原生运维【免费下载链接】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 仓库根目录 CHANGELOG.md 为骨架系统梳理 v2.29.0 至 v2.39.1 十个版本的演进脉络告警与 Webhook、图表与查询引擎、仪表盘变量与过滤器、LLM 可观测性、MCP 服务器、采集器与存储运维、安全加固等主线能力逐一对应真实源码与配置文件给出实现依据并整理全部破坏性变更与升级前必读的配置项帮助自托管用户与集成开发者安全升级、充分使用新特性。版本概览发布节奏与文档组织方式HyperDX 的根级 CHANGELOG.md 记录所有包hyperdx/api、hyperdx/app、hyperdx/cli、hyperdx/common-utils、hyperdx/hdx-eval、hyperdx/otel-collector的跨包发布级要点。每条记录由 AI 在发版时生成并在 Release HyperDX PR 中人工复核编辑时需保留hyperdx-release-notes注释标记否则改动会在重新生成时丢失。每个包的详细变更分别记录在各自的packages/*/CHANGELOG.md中packages/api/CHANGELOG.md — 后端 API、告警任务、MCP 服务端packages/app/CHANGELOG.md — 前端应用与页面packages/cli/CHANGELOG.md — 终端 CLIhdxpackages/common-utils/CHANGELOG.md — 前后端共享工具库packages/hdx-eval/CHANGELOG.md — 评测框架packages/otel-collector/CHANGELOG.md — Go 采集器近十次发版节奏约为每周一次v2.30.1、v2.31.0、v2.32.0 密集于 2026 年 7 月到 v2.39.12026-09-19为止主线稳定。从源码结构看根 CHANGELOG 还会被前端 Whats new 功能在构建期解析渲染见 packages/app/CHANGELOG.md 中对应条目即发布说明本身就是产品内可读的内容资产。告警体系从单 Webhook 到完整告警生命周期告警是近十个版本中迭代最密集的模块能力演进几乎贯穿每一条发布主线。模板变量驱动的 Webhook 负载v2.38.0 起Generic 与 incident.io 两种 Webhook 正文是 Handlebars 模板可用的模板变量从最初的 7 个扩充到完整集合。以仓库内 docs/alert-webhook-template-variables.md 为准完整变量表如下变量类型说明{{title}}/{{body}}/{{link}}string标题、渲染后的消息体markdown、回链{{state}}/{{eventId}}string内部告警状态、本次 firing 的唯一 id{{startTime}}/{{endTime}}number评估窗口Unix 毫秒{{startTimeISO}}/{{endTimeISO}}string同一窗口的 ISO-8601 形式{{alertId}}string告警本身的稳定 id是去重的关键{{status}}stringfiring、resolved、no_data、pending、error{{alertType}}stringsearch、dashboard_chart、inline_query{{comparator}}string、、、、、!、between、outside{{threshold}}/{{thresholdMax}}number阈值between/outside时前者为下界、后者为上界{{value}}number触发或恢复告警的值{{groupKey}}string分组告警中的违约分组{{sourceQuery}}string告警实际评估的条件搜索表达式或 SQL{{teamId}}/{{note}}string所属团队、自由文本备注常放 runbook 链接所有字符串变量 JSON 转义数字变量原样输出富化变量均为可选告警不携带时渲染为空串。文档还给出了一段可直接使用的示例模板按严重程度路由、按alertId去重{ alert_id: {{alertId}}, dedup_key: {{alertId}}-{{groupKey}}, status: {{status}}, summary: {{title}}, urgency: {{#if (eq alertType \dashboard_chart\)}}low{{else}}high{{/if}}, value: {{value}}, threshold: {{threshold}}, window: { start: {{startTimeISO}}, end: {{endTimeISO}} }, runbook: {{note}}, link: {{link}} }配套的实操要点均来自 docs/alert-webhook-template-variables.md可选数字必须防缺失用{{#unless (eq thresholdMax undefined)}}而非{{#if thresholdMax}}守卫否则合法的0下界会被当作不存在v2.39.0 修正。{{/unless}}与闭合}之间需保留空格或换行否则}}}会被 Handlebars 解析为三花括号而编译失败。Send test 会填充所有变量但样例是between告警thresholdMax一定存在所以它无法暴露可选数字缺失这类模板错误——这正是上述守卫的用途。incident.io 只接受firing/resolved默认负载把 HyperDX 状态映射到二者并携带deduplication_key {{eventId}}按告警分组渠道稳定保证 incident.io 关闭它自己打开的告警。v2.39.0 进一步修复{{sourceQuery}}此前只读取图表的顶层where对按序列aggCondition定义的告警渲染为空现在会拼接图表where 序列aggCondition或保存搜索的where 固定过滤器截断至 2000 字符并刻意排除图表的 pinned filters因为 tile/内联告警并不应用它们。多渠道、连续窗口与评估历史单告警最多 10 个 Webhookv2.36.0新增channels字段贯穿 v2 外部 API、内部 API 与 MCPclickstack_save_alert旧的单一channel字段继续兼容。注意 API 更新是整体替换而非合并——只带channel的更新会把多通道告警缩减到单个 Webhook客户端应 fetch 后回传完整channels数组。连续窗口条件与 PENDING 状态v2.30.0要求条件连续 N 个窗口成立才触发削减单窗口噪声页趋势若延续即将触发时上报PENDING状态且可通过外部 API 配置。评估历史 APIv2.35.0新增GET /alerts/:id/evaluations按时间范围返回逐窗口评估历史分组告警带 per-group 明细、评估分析字段与去重后的错误信息游标分页保证有空洞的历史也能翻页终止。对应路由实现在 packages/api/src/routers/api/alerts.ts。失败评估被保留而非覆盖v2.35.0查询错误、超时、Webhook 失败按窗口逐一记录超时单独标注并附带可操作消息同一窗口的重试合并为单行窗口恢复后错误条目清除。分组告警不再卡死在 ALERT 态v2.31.0阈值不再超限后历史状态重置为 OK。通知时长只统计投递本身v2.39.0此前评估列表里的时长把构建标题、查询示例日志、渲染模板都算进去现在按目标分别计时并按目标聚合展示v2.37.0 引入可展开查看每个 Webhook 的累计时长、投递次数与失败数。分组告警示例日志每窗口只查一次v2.39.0按服务分组的告警此前对每个违约服务重复查询同一批示例行现改为每窗口一次、所有通知共享追赶补发的窗口因数据不同仍各自查询。同时示例日志行现在应用保存搜索的 pinned filtersv2.39.0保证通知中的行确实来自被计数的行集。内联告警与图表直连告警inline告警源v2.37.0 后端落地v2.38.0 贯通外部 API 与 MCP告警自身携带图表配置无需先保存搜索或建 tilebuilder 配置支持 log/trace/metric 源原始 SQL 支持 Line/Stacked Bar/Number 展示PromQL 被拒绝评估走与 tile 告警相同的路径含 group-by 与多窗口行为通知链接回图表探索器。从图表探索器直接建告警v2.39.0在/chart上构建好日志/追踪/指标查询builder 或原始 SQL即可命名并创建告警无需经过保存搜索或仪表盘 tile告警持久化自己的图表配置告警列表以图表图标展示并可回链探索器。仪表盘 tile 告警可导出 Terraformv2.39.0clickhouse_clickstack_alert新增source tile与dashboard_id/tile_idprovider 3.28.0tile 名称为空或重复时provider 的tile_idsmap 按键名索引以及被 provisioning 重写的仪表盘会 withheld。告警相关的其他改进告警自带 displayName 与 tagsv2.38.0v2.39.0 起 API 在启动时为存量告警从所监控的保存搜索/仪表盘回填命名与标签。告警列表服务端分页v2.39.0GET /alerts接受分页与过滤参数并在数据库中应用列表虚拟化v2.37.0保证数百条告警下滚动不卡。Terraform 导出v2.34.0仪表盘、保存搜索、保存搜索告警均有 Export to Terraform 按钮Team Settings 可下载整团队 import 文件地址由资源 id 而非名称推导避免重命名引发 destroy-and-recreate。Webhook 投递加固v2.31.0封禁已知坏 IP 段、投递时不跟随重定向v2.30.0 起失败投递按指数退避重试而非丢弃。图表与查询引擎公式、指标发现与性能修复公式Formulasv2.36.0 的核心特性任何 metric/log/trace 图表都能携带派生序列写作字母引用算术表达式A / (A B) * 100时间序列、表格、数字图表新增 Add Formula 行内联校验非法表达式与未知引用每公式可设别名与数字格式带序列字母徽章Show input series 开关决定单独渲染公式还是连同操作数。公式与 As Ratio 开关互斥缺失操作数按 0 计零或缺失分母渲染为缺口数字 tile 永远显示公式而非原始操作数。事件源公式内联编译进图表的单次扫描 SELECT没有每序列查询扇出。公式贯通外部 API v2、MCPsave_dashboard/patch_dashboard与 CLI写入时校验未知引用、非法语法、与asRatio混用、数字 tile 多公式等tile 告警在公式图上评估公式本身v2.36.0 修复此前阈值对着原始操作数比较的问题。Convert to SQL 支持多序列/比率/公式图表v2.36.0输出基于宏的原始 SQL 模板每序列分支一个$__sourceTable(metricType)宏。指标探索器与指标名称选择Metrics explorerv2.37.0图表编辑器的浏览控件把指标命名空间渲染为前缀层级树system→cpu→utilization跨名称与描述搜索行内展示 kind 与描述详情面板给出单位、上报服务、可下钻的标签键按.或_分词嵌套浏览标签时可把过滤器与 group-by 暂存为可移除 chips应用时按 kind 自动选择聚合gauge→avg、counter→sum、histogram→p95。指标名称选择器性能v2.39.0名称改从表的稀疏主索引流式读取约 4,900 个 gauge 指标时首选项约 30ms 而非 770ms浏览时按有数据的指标加权键入时切到全量相关性排序搜索服务器低于 24.2、Distributed 或非 MergeTree 表、主键不含MetricName时自动回退全量列举。名称完整可选v2.38.0指标下拉不再抽样超过 3000 个名称也可按名搜索精确匹配排最前列表不完整时明确提示尊重所选时间范围而非固定看最近 24 小时。目录之外的指标如近三天停止上报的也能按名选图。时间图表的行为与边界高基数序列默认封顶v2.34.0破坏性按高基数字段分组的 tile 不再试图画出每条线默认物化并渲染有界数量的序列内置 N more 悬停/钉住提示与 load all series 逃生口。外部仪表盘 API 上为三态省略默认上限0不限正整数top N依赖省略字段获取全量序列的客户端应改传0。顶层 HAVING/ORDER BY/LIMIT 作用于整体v2.36.0此前泄漏进每个序列分支现引用图表的输出列操作数别名、公式名、比率列、group-by 列、时间桶HAVING err rate 0.5正确过滤连接后的行。混合 float/integer 聚合v2.36.0所有序列值归一化为 Float64解决NO_COMMON_TYPE/Variant 报错原始 SQL 图表的全数字Variant(...)列也归类为数值。多序列指标图表单查询执行v2.35.0一个组合查询替代每序列一查浏览器合并View SQL 展示完整查询。小数值 Y 轴刻度保留小数v2.38.0绝对值 10 的刻度遵循图表 Number Format 小数位上限 2≥10 与恰为 0 的刻度保持整数CLI 终端图同步修复。Recharts 2.13 → 3.xv2.31.0缩放刷选、点击下钻、tooltip 钉住全部迁移到 Recharts 3 API图表交互面广泛改动。查询正确性修复搜索侧_与%恢复字面含义v2.34.0搜索词不再被直接插进 ILIKE 模式当作通配符。每个 URL 都被转义v2.34.0多 URL 查询不再把后续冒号编译为字段查询。开区间/排他区间/非数值边界v2.34.0Duration:[* TO 500]、{100 TO 500}、带时区的DateTime(UTC)、Date32/Nullable(Date)等均按预期处理。搜索分面查询参数内联v2.36.0约 100 个键的批量分面值查询曾超出 ClickHouse web 客户端 URL 参数预算、被代理网关拒收现内联为转义字面量参数个数恒定。仪表盘过滤器、变量与相对时间范围过滤器标记为 requiredv2.39.0仪表盘过滤器可从可选改为必选仅在某取值下才有意义的仪表盘把这一预期随身携带设置贯穿 schema、API 与应用经 API 往返不丢失。静态取值列表过滤器v2.38.0过滤器可配置固定取值集渲染为选择器而非从数据发现UI 过滤器编辑器可创建MCP 服务器也理解静态过滤器。Prometheus 标签值过滤器v2.38.0过滤器取值来自 Prometheus 标签并接受 series selectormatcher收窄来源序列。变量与广播设置v2.35.0变量进入 builder tilev2.36.0builder tile 与原始 SQL tilev2.35.0都会做变量替换SQL 编辑器自动补全并校验变量用法变量的取值查询可依赖其他变量宏参数内嵌套变量/宏也会展开v2.37.0 起变量对所有部署开放移除 feature toggle支持 Lucene 精确匹配展开、PromQL 替换与 MCP。相对时间范围v2.39.0仪表盘可保存最近一小时/最近一天这类相对窗口每次打开都锚定当前时间设置同样贯通 schema 与 API。过滤器取值按变量持久化v2.37.0下钻到搜索时展开变量值而非名称v2.37.0 修复。tile 预览可跟随仪表盘过滤器v2.39.0tile 懒加载v2.29.0tile 滚动进入视口才执行 ClickHouse 查询并缓存结果。表格 tile 按列着色与条件规则v2.32.0行点击外链v2.29.0数字 tile 背景 sparkline、As Ratio、条件颜色v2.29.0。Snap gridv2.32.0拖拽/缩放 tile 时背后绘制网格并高亮实际落点。tile 告警在公式图上评估公式、share_of_total尊重ratioModev2.36.0 修复tile 名称为空被 MCP 拒绝v2.29.0 破坏性。LLM 可观测性仪表盘betav2.38.0 引入/llmbeta 仪表盘v2.39.0 显著加速无需改动插桩直接读取已摄入的 traces 并在查询时解释。要点理解 OTel GenAI 语义约定、OpenLLMetry、OpenInference、Vercel AI SDK对早先采集的遥测追溯生效。图表维度LLM 流量、token 拆分uncached/cached/cache-write/output/reasoning、按模型的估算成本、延迟与首 token 时间、工具调用per-session 时间线含对话视图与并排 LLM span/日志搜索。成本来自内置价格目录考虑 cache-read 折扣与 cache-write 溢价自身上报的成本属性优先于估算多插桩方言并存时选一个权威报告者保证一次调用只计一次。v2.39.0 的加速tile 过滤器改用mapContains走 trace schema 的 key 索引staging 表上 LLM span 谓词从 36 秒 planning 停滞降到 7ms双键过滤从 1,306 个 granule 降到 3 个。伴随行为变化带gen_ai.system的 span 即视为 LLM span。新增按最终用户过滤v2.39.0与 session 过滤器并列下拉列出所搜范围内 LLM span 上的去重用户并作用于包括 Errors 页签关联日志事件在内的所有页签选择进入 URL 可分享。MCP 服务器工具改名、指标一等公民与批量查询v2.29.0 是 MCP 服务器的大版本所有工具从hyperdx_*重命名为clickstack_*服务器也更名为clickstack任何显式引用工具名的 Agent 配置、提示词或自动化都需要更新。随后的能力积累指标一等公民v2.29.0clickstack_list_metrics按 kind、名称模式、时间窗分页与clickstack_describe_metrickind、unit、描述、属性键、采样值clickstack_timeseries/clickstack_table接受metricType/metricName/isDelta与aggFn: increasev2.35.0 增加 summary 类指标。整仪表盘一次校验v2.35.0clickstack_query_tiles接收 dashboard ID 与可选 tile ID 列表默认所有非 markdown tile返回逐 tile 成功/失败摘要与聚合计数失败 tile 内联报告而非中断整次调用。量化分析工具v2.34.0clickstack_emerging_signals对比基线窗口与当前窗口的日志/事件模式回答发生了什么变化。其判定逻辑在 packages/api/src/mcp/tools/query/emergingSignals.ts 中实现为纯函数classifyShift基线缺失且当前份额 ≥newPatternShareFloor判为 emerging当前缺失或份额反向达到ratio倍判为 disappeared比较采用交叉相乘curShare ratio * baseShare避免除零并带 1e-9 相对容差与真实方向变化守卫防止minShareRatio: 1把稳态模板刷成新信号。读/写注解v2.35.0每个工具带 annotations客户端可区分只读查询工具与 save/patch/delete 等破坏性工具工具选择策略在连接时呈现引导 Agent 优先 builder 查询工具而非原始 SQL后者失败率约高一倍。Agent 构建 tile 的过滤器归位v2.35.0save/patch 拒绝 table/line/stacked bar/number/pie/bar tile 的 tile 级where指引使用每序列wheresearch/heatmap/event pattern 仍保留 tile 级过滤器。错误分类v2.30.0span 与hyperdx.mcp.tool.errors计数器带error_category属性ClickHouse 错误按类型与 cause chain 自动分类为 user/server。安全与互操作修复工具 schema 通过 JSON Schema draft 2020-12 校验v2.36.0修复colorRulesbetween元组序列化导致 Gemini 类客户端拒收整个工具列表的问题quantilelevel改为 string enumv2.37.0失败的 MCP 调用在 spanStatusMessage中呈现错误v2.36.0readonly2使max_execution_time真正生效v2.29.0。采集器、存储与运维遥测管道与自托管细节OTel Collector 能力OIDC bearer token 认证v2.35.0standalone 采集器可针对 OIDC 提供方发布的 JWKS 校验 OTLP 请求替代单一长期共享密钥——设置OIDC_ISSUER_URL与OIDC_AUDIENCE即可静态OTLP_AUTH_TOKEN仍可用。Bearer 头两种大小写均可v2.38.0OpAMP 管理模式与 standalone 的OTLP_AUTH_TOKEN均接受Bearer/bearer/BEARER前缀RFC 6750 客户端不再被拒。spanmetrics connector 编译进采集器v2.39.0通过CUSTOM_OTELCOL_CONFIG_FILE提供的自定义 pipeline 可直接引用spanmetricsconnector从 span 推导调用次数与时长RED指标——尤其解决datadogreceiver摄入的 Datadog Agent traces 此前无法产出 RED 指标的问题。纯增量变更默认 pipeline 不变。Datadog receiveropt-inv2.30.0设置ENABLE_DATADOG_RECEIVER后采集器在0.0.0.0:8126挂载 traces/metrics/logs pipeline启用认证时以DD-API-KEY头对团队 API key 校验。PromQL 端点v2.29.0 实验性仅当CLICKHOUSE_PROMETHEUS_METRICS_ENDPOINT设置时才声明prometheusremotewriteexporter 与metrics/promqlpipeline。trace schema 种子带文本索引v2.39.0新建 trace schema 时即建文本索引仅在建表时执行。exporter 超时可配置v2.36.0HYPERDX_OTEL_EXPORTER_TIMEOUT默认 5 秒。ClickHouse 存储与查询PromQL 走 Prometheus HTTP APIv2.39.0破坏性ClickHouse 支持的/query、/query_range代理到连接的/prometheus/api/v1/*ClickHouse 26.8 引入的prometheus_api_v1handler不再调用prometheusQuery/prometheusQueryRange表函数。自带 ClickHouse 镜像升级到 26.8自管 ClickHouse 必须升级到 26.8 并启用该 handler否则 ClickHouse 支持下的 PromQL 查询会失败。database/table参数继续转发。PromQL 代理保留 Connection host 路径前缀v2.38.0破坏性VictoriaMetricsvmselect这类带路径的 host 不再被改写但从 Prometheus UI 复制来的http://prom:9090/graph这类偶然可用的 host 会变成 404升级前请清理 host 中的多余路径。host 上的 query 参数仅作为固定 Prometheus API 参数集query、time、start、end、step、match/match[]、limit、timeout、stats的回退请求值优先curl/Terraform 直接调用传来的非 Prometheus 参数会被丢弃。每次请求关闭子列尺寸计算v2.39.0ClickHouse 26.3 默认开启allow_calculating_subcolumns_sizes_for_merge_tree_reading使 PREWHERE 规划为每个被引用的 map key 拉取 per-part 尺寸SharedMergeTree 上等于每 key×活动 part 一次 S3 GET且max_execution_time无法中断LLM 仪表盘等读 ~64 个属性键的查询可能卡住数分钟查询现在在服务器支持处发送0。per-signal TTLv2.36.0HYPERDX_OTEL_EXPORTER_LOGS_TTL、..._TRACES_TTL、..._METRICS_TTL、..._SESSIONS_TTL各自回退到HYPERDX_OTEL_EXPORTER_TABLES_TTL可让日志/追踪留半年、指标 30 天淘汰HYPERDX_OTEL_EXPORTER_RECONCILE_TABLE_TTLtrue时 migrate 工具把保留策略应用到已存在的表。Reconciliation 默认关闭且刻意保守延长保留不删数据、缩短保留不在启动时批量删除、复合策略tiering/RECOMPRESS/GROUP BYrollups与日历单位保留会被报告并跳过。指标 schema 更精简v2.30.0更高效的主键与更好的时间剪枝。服务可用性与运维MongoDB 启动重试与 /ready 探针v2.36.0初始连接失败不再不重试初始连接以封顶指数退避重试直至成功API 与 OpAMP 均暴露GET /readyMongoDB 未连接时返回 503——Kubernetes 就绪探针应指向它/health保持纯存活检查。API 日志级别默认infov2.36.0破坏性BaseClickhouseClient不再无条件打印原始 SQL查询日志改走 pino 的debug级。生产环境依赖 SQL 日志需设HYPERDX_LOG_LEVELdebug空值Compose 未设变量时的情形回退到默认值而不是让 pino 启动报错。webhook SSRF 校验v2.32.0破坏性Webhook 目标统一按 SSRF 防护检查私有/保留地址默认拦截投递到内网 host 需加入WEBHOOK_HOSTNAME_ALLOWLIST逗号分隔hostname 条目覆盖子域IPv4/IPv6 精确匹配。该白名单不绕过协议校验、Slack hostname 校验以及对所配置 ClickHouse/MongoDB host 的封禁。配置读取见 packages/api/src/config.ts。第三方令牌静态加密v2.39.0设置TOKEN_ENCRYPTION_KEY32 字节base64 或 64 位 hex后Slack bot token、OAuth access/refresh token 等以 AES-256-GCM 加密落盘不设置则维持明文存储。实现见 packages/api/src/utils/tokenEncryption.ts存储格式为v1:provider:payloadpayload 布局为iv || tag || ciphertext信封前缀作为附加认证数据AAD防止负载被换名重放解密按信封内的 provider 分发因此切换 provider 后旧行仍可读启动时以固定哨兵串做加解密自检verifyTokenEncryption密钥不可解析会直接阻断启动。已知限制信封不带 key id轮换TOKEN_ENCRYPTION_KEY会使存量行不可读v1版本字段就是为此预留。密钥生成示例openssl rand -base64 32。个人 API access key 可轮换v2.36.0Team Settings → API Agents 增加 Rotate轮换即时吊销旧 key需同步更新 MCP/AI Agent 配置、Terraform provider 与 CI 脚本浏览器会话不受影响。External API v2 列表分页v2.30.0破坏性/api/v2/alerts、/api/v2/saved-searches、/api/v2/webhooks接受limit1–1000默认 1000与offset默认 0返回meta: { total, limit, offset }按_id排序保证分页稳定并设X-Total-Count头DELETE /api/v2/alerts/:id对不存在资源改返 404。v2 外部 API 资源管理扩展v2.30.0saved-search/webhook/source 全套 CRUDwebhookheaders/queryParams只写不读避免泄露鉴权 tokenPOST /api/v2/dashboards/validate预校验负载。邀请撤销限定团队范围v2.34.0DELETE /team/invitation/:id只允许撤销本团队待处理邀请未知/越权 id 返回 404Authorization与Cookie头从 API 请求日志中脱敏。限流按 access key 键控v2.34.0此前按原始Authorization头值分桶改动Bearer前缀即可绕过配额现按键本身分桶无 key 时回退客户端 IP。token 加密计数器hyperdx.token_encryption.plaintext_reads与hyperdx.token_encryption.disabled两个指标可观测加密关闭状态使其可告警。会话回放与前端体验回放器升级 rrweb 2.1.1v2.36.0从2.0.0-alpha.8迁移到稳定版吸收多年样式表/虚拟 DOM/adopted stylesheets 修复用旧rrweb1.1.3与当前 SDK 录制的会话验证过回放保真度。超大录制事件不再丢失v2.37.0超过录制器约 950KB chunk 大小的 rrweb 事件被拆成共享同一时间戳的多个 chunk此前按时间戳排序会被 ClickHouse 打乱导致整段常是内联 CSS 的完整 DOM 快照被丢弃现在流按确定性排序、chunk 按显式索引重组、无法重建的事件在播放器中标示。存量录制无需重采即可正确回放。多行 SQL 字段自适应高度v2.39.0搜索 WHERE/SELECT/ORDER BY、图表编辑器的 SQL 与 PromQL 字段失焦不再折叠搜索栏语言切换高度一致共享同一高度表。Whats new 内嵌应用v2.37.0Help 菜单的完整 changelog 模态改为内联区块 View all releases 抽屉 未读时 Help 图标上的 sparklechangelog 构建期解析而非运行时拉取。v2.39.0 修复每次部署都闪烁提示键从NEXT_PUBLIC_APP_VERSION部署会盖入构建 id改为 changelog 中最新的发布版本仅当严格更新才提示回滚也不再全员打扰。复制调试信息v2.38.0Help 菜单 Copy debug info 一键打包前后端版本可分别部署、部署模式、用户/团队 id、启用的功能开关、URL/屏幕/视口/OS/浏览器与会话 id控制台可用window.hdx.report()取同样摘要。破坏性变更速查表升级前必读版本变更影响与处置v2.39.0ClickHouse 支持的 PromQL 走/prometheus/api/v1/*自管 ClickHouse 需 ≥26.8 并启用prometheus_api_v1handlerv2.38.0PromQL 代理保留 Connection host 路径清理 host 上多余的路径与 query 字符串v2.36.0API 日志级别默认info不再打印查询 SQL需要 SQL 日志设HYPERDX_LOG_LEVELdebugv2.35.0Terraform 导出使用团队级 import idteam_id/resource_idprovider 需 3.25.0升级后重新导出再导入v2.34.0时间图表默认限制高基数序列需要全量序列的 API 客户端把seriesLimit显式传0v2.32.0Webhook 目标按 SSRF 校验内网投递加入WEBHOOK_HOSTNAME_ALLOWLISTv2.30.0v2 列表端点分页 上限客户端读取meta.total并用offset翻页DELETE /api/v2/alerts/:id对不存在资源返 404v2.29.0MCP 工具hyperdx_*→clickstack_*更新所有显式引用工具名的 Agent 配置v2.29.0User.accessKey唯一索引升级前清理重复 access key否则启动失败v2.29.0指标序列分组区分属性作用域仅影响跨作用域搬运属性的 collector 处理器配置v2.29.0图表调色板 token 改色相命名存量仪表盘自动迁移ClickStack 的chart-1会由蓝变绿可在色相选择器重选v2.29.0MCP tile 名称必须非空空名称name: 报校验错误常用环境变量与功能开关一览变量作用备注TOKEN_ENCRYPTION_KEY第三方令牌 AES-256-GCM 静态加密32 字节base64 或 64 hex轮换会使存量行不可读WEBHOOK_HOSTNAME_ALLOWLISTWebhook 内网 host 白名单逗号分隔hostname 条目覆盖子域HYPERDX_LOG_LEVELAPI 日志级别v2.36.0 起默认infoHYPERDX_OTEL_EXPORTER_LOGS/TRACES/METRICS/SESSIONS_TTL按信号的表保留策略回退到..._TABLES_TTLHYPERDX_OTEL_EXPORTER_RECONCILE_TABLE_TTLmigrate 时应用到存量表默认关保守语义HYPERDX_OTEL_EXPORTER_TIMEOUT采集器 exporter 超时默认 5 秒OIDC_ISSUER_URL/OIDC_AUDIENCEOTLP OIDC 认证替代静态OTLP_AUTH_TOKENCUSTOM_OTELCOL_CONFIG_FILE自定义采集器 pipeline可引用spanmetricsconnectorENABLE_DATADOG_RECEIVERDatadog Agent 接入挂载在0.0.0.0:8126CLICKHOUSE_PROMETHEUS_METRICS_ENDPOINT声明 PromQL exporter/pipeline实验性NEXT_PUBLIC_ENABLE_ALERT_DETAILS告警详情页/alerts/:id默认关v2.35.0 实验性e2e 配置可见 packages/app/playwright.config.tsNEXT_PUBLIC_ENABLE_EXPONENTIAL_HISTOGRAMS指数直方图指标默认关v2.32.0 实验性INGESTION_API_KEYall-in-one 认证镜像的预共享摄入 keyv2.30.0 修复镜像名匹配升级路线与持续追踪综合来看v2.29 → v2.39 的演进主线可概括为告警从发一条消息进化为可编程、可评估、可审计的完整生命周期图表查询从会画图进化为公式、指标发现与性能可控仪表盘从静态画布进化为变量驱动、可过滤、可导出 IaC 的资源同时LLM 可观测性与 MCP Agent 集成成为两条全新产品线底层则是ClickHouse 26.x 时代的查询代理路径与存储运维现代化。升级前请按上表逐条核对破坏性变更重点检查ClickHouse 服务器版本v2.39.0 要求 ≥26.8、Prometheus Connection 的 host 写法、Webhook 是否投递内网、Terraform provider 版本以及 MCP/Agent 配置中的工具名。每个包的细粒度变更可在各 packages/*/CHANGELOG.md 中追踪产品内 Help 菜单的 Whats new 也直接渲染根级发布说明是跟进新版本最快的第一手入口。赞分享可观测性云原生运维【免费下载链接】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点击查看免费下载相关推荐nextra-theme-blog 版本演进深度解读从 2.0 到 4.6 的破坏性变更与能力图谱nextra theme blog 版本演进深度解读从 2.0 到 4.6 的破坏性变更与能力图谱 本篇技术指南以 nextra theme blog 的 C前端文档/教程EUI 2025 年度版本演进深度解读从 v99 到 v111 的关键更新、破坏性变更与升级实践指南EUI 2025 年度版本演进深度解读从 v99 到 v111 的关键更新、破坏性变更与升级实践指南 本指南基于 elastic/eui 在 2025 年度前端UI组件设计系统Monolog 变更日志全解读从 1.0 到 3.11 的版本演进、破坏性变更与关键技术点Monolog 变更日志全解读从 1.0 到 3.11 的版本演进、破坏性变更与关键技术点 导读 本文以 Monolog 项目 CHANGELOG.md ht后端上一篇G-Helper深度配置指南华硕笔记本性能调优与自动化管理下一篇VAP动画播放技术突破跨平台特效渲染的性能瓶颈创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 HyperDX 版本演进深度解读：从 v2.29 到 v2.39 的关键能力、破坏性变更与源码实现
可观测性云原生运维【免费下载链接】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 仓库根目录 CHANGELOG.md 为骨架系统梳理 v2.29.0 至 v2.39.1 十个版本的演进脉络告警与 Webhook、图表与查询引擎、仪表盘变量与过滤器、LLM 可观测性、MCP 服务器、采集器与存储运维、安全加固等主线能力逐一对应真实源码与配置文件给出实现依据并整理全部破坏性变更与升级前必读的配置项帮助自托管用户与集成开发者安全升级、充分使用新特性。版本概览发布节奏与文档组织方式HyperDX 的根级 CHANGELOG.md 记录所有包hyperdx/api、hyperdx/app、hyperdx/cli、hyperdx/common-utils、hyperdx/hdx-eval、hyperdx/otel-collector的跨包发布级要点。每条记录由 AI 在发版时生成并在 Release HyperDX PR 中人工复核编辑时需保留hyperdx-release-notes注释标记否则改动会在重新生成时丢失。每个包的详细变更分别记录在各自的packages/*/CHANGELOG.md中packages/api/CHANGELOG.md — 后端 API、告警任务、MCP 服务端packages/app/CHANGELOG.md — 前端应用与页面packages/cli/CHANGELOG.md — 终端 CLIhdxpackages/common-utils/CHANGELOG.md — 前后端共享工具库packages/hdx-eval/CHANGELOG.md — 评测框架packages/otel-collector/CHANGELOG.md — Go 采集器近十次发版节奏约为每周一次v2.30.1、v2.31.0、v2.32.0 密集于 2026 年 7 月到 v2.39.12026-09-19为止主线稳定。从源码结构看根 CHANGELOG 还会被前端 Whats new 功能在构建期解析渲染见 packages/app/CHANGELOG.md 中对应条目即发布说明本身就是产品内可读的内容资产。告警体系从单 Webhook 到完整告警生命周期告警是近十个版本中迭代最密集的模块能力演进几乎贯穿每一条发布主线。模板变量驱动的 Webhook 负载v2.38.0 起Generic 与 incident.io 两种 Webhook 正文是 Handlebars 模板可用的模板变量从最初的 7 个扩充到完整集合。以仓库内 docs/alert-webhook-template-variables.md 为准完整变量表如下变量类型说明{{title}}/{{body}}/{{link}}string标题、渲染后的消息体markdown、回链{{state}}/{{eventId}}string内部告警状态、本次 firing 的唯一 id{{startTime}}/{{endTime}}number评估窗口Unix 毫秒{{startTimeISO}}/{{endTimeISO}}string同一窗口的 ISO-8601 形式{{alertId}}string告警本身的稳定 id是去重的关键{{status}}stringfiring、resolved、no_data、pending、error{{alertType}}stringsearch、dashboard_chart、inline_query{{comparator}}string、、、、、!、between、outside{{threshold}}/{{thresholdMax}}number阈值between/outside时前者为下界、后者为上界{{value}}number触发或恢复告警的值{{groupKey}}string分组告警中的违约分组{{sourceQuery}}string告警实际评估的条件搜索表达式或 SQL{{teamId}}/{{note}}string所属团队、自由文本备注常放 runbook 链接所有字符串变量 JSON 转义数字变量原样输出富化变量均为可选告警不携带时渲染为空串。文档还给出了一段可直接使用的示例模板按严重程度路由、按alertId去重{ alert_id: {{alertId}}, dedup_key: {{alertId}}-{{groupKey}}, status: {{status}}, summary: {{title}}, urgency: {{#if (eq alertType \dashboard_chart\)}}low{{else}}high{{/if}}, value: {{value}}, threshold: {{threshold}}, window: { start: {{startTimeISO}}, end: {{endTimeISO}} }, runbook: {{note}}, link: {{link}} }配套的实操要点均来自 docs/alert-webhook-template-variables.md可选数字必须防缺失用{{#unless (eq thresholdMax undefined)}}而非{{#if thresholdMax}}守卫否则合法的0下界会被当作不存在v2.39.0 修正。{{/unless}}与闭合}之间需保留空格或换行否则}}}会被 Handlebars 解析为三花括号而编译失败。Send test 会填充所有变量但样例是between告警thresholdMax一定存在所以它无法暴露可选数字缺失这类模板错误——这正是上述守卫的用途。incident.io 只接受firing/resolved默认负载把 HyperDX 状态映射到二者并携带deduplication_key {{eventId}}按告警分组渠道稳定保证 incident.io 关闭它自己打开的告警。v2.39.0 进一步修复{{sourceQuery}}此前只读取图表的顶层where对按序列aggCondition定义的告警渲染为空现在会拼接图表where 序列aggCondition或保存搜索的where 固定过滤器截断至 2000 字符并刻意排除图表的 pinned filters因为 tile/内联告警并不应用它们。多渠道、连续窗口与评估历史单告警最多 10 个 Webhookv2.36.0新增channels字段贯穿 v2 外部 API、内部 API 与 MCPclickstack_save_alert旧的单一channel字段继续兼容。注意 API 更新是整体替换而非合并——只带channel的更新会把多通道告警缩减到单个 Webhook客户端应 fetch 后回传完整channels数组。连续窗口条件与 PENDING 状态v2.30.0要求条件连续 N 个窗口成立才触发削减单窗口噪声页趋势若延续即将触发时上报PENDING状态且可通过外部 API 配置。评估历史 APIv2.35.0新增GET /alerts/:id/evaluations按时间范围返回逐窗口评估历史分组告警带 per-group 明细、评估分析字段与去重后的错误信息游标分页保证有空洞的历史也能翻页终止。对应路由实现在 packages/api/src/routers/api/alerts.ts。失败评估被保留而非覆盖v2.35.0查询错误、超时、Webhook 失败按窗口逐一记录超时单独标注并附带可操作消息同一窗口的重试合并为单行窗口恢复后错误条目清除。分组告警不再卡死在 ALERT 态v2.31.0阈值不再超限后历史状态重置为 OK。通知时长只统计投递本身v2.39.0此前评估列表里的时长把构建标题、查询示例日志、渲染模板都算进去现在按目标分别计时并按目标聚合展示v2.37.0 引入可展开查看每个 Webhook 的累计时长、投递次数与失败数。分组告警示例日志每窗口只查一次v2.39.0按服务分组的告警此前对每个违约服务重复查询同一批示例行现改为每窗口一次、所有通知共享追赶补发的窗口因数据不同仍各自查询。同时示例日志行现在应用保存搜索的 pinned filtersv2.39.0保证通知中的行确实来自被计数的行集。内联告警与图表直连告警inline告警源v2.37.0 后端落地v2.38.0 贯通外部 API 与 MCP告警自身携带图表配置无需先保存搜索或建 tilebuilder 配置支持 log/trace/metric 源原始 SQL 支持 Line/Stacked Bar/Number 展示PromQL 被拒绝评估走与 tile 告警相同的路径含 group-by 与多窗口行为通知链接回图表探索器。从图表探索器直接建告警v2.39.0在/chart上构建好日志/追踪/指标查询builder 或原始 SQL即可命名并创建告警无需经过保存搜索或仪表盘 tile告警持久化自己的图表配置告警列表以图表图标展示并可回链探索器。仪表盘 tile 告警可导出 Terraformv2.39.0clickhouse_clickstack_alert新增source tile与dashboard_id/tile_idprovider 3.28.0tile 名称为空或重复时provider 的tile_idsmap 按键名索引以及被 provisioning 重写的仪表盘会 withheld。告警相关的其他改进告警自带 displayName 与 tagsv2.38.0v2.39.0 起 API 在启动时为存量告警从所监控的保存搜索/仪表盘回填命名与标签。告警列表服务端分页v2.39.0GET /alerts接受分页与过滤参数并在数据库中应用列表虚拟化v2.37.0保证数百条告警下滚动不卡。Terraform 导出v2.34.0仪表盘、保存搜索、保存搜索告警均有 Export to Terraform 按钮Team Settings 可下载整团队 import 文件地址由资源 id 而非名称推导避免重命名引发 destroy-and-recreate。Webhook 投递加固v2.31.0封禁已知坏 IP 段、投递时不跟随重定向v2.30.0 起失败投递按指数退避重试而非丢弃。图表与查询引擎公式、指标发现与性能修复公式Formulasv2.36.0 的核心特性任何 metric/log/trace 图表都能携带派生序列写作字母引用算术表达式A / (A B) * 100时间序列、表格、数字图表新增 Add Formula 行内联校验非法表达式与未知引用每公式可设别名与数字格式带序列字母徽章Show input series 开关决定单独渲染公式还是连同操作数。公式与 As Ratio 开关互斥缺失操作数按 0 计零或缺失分母渲染为缺口数字 tile 永远显示公式而非原始操作数。事件源公式内联编译进图表的单次扫描 SELECT没有每序列查询扇出。公式贯通外部 API v2、MCPsave_dashboard/patch_dashboard与 CLI写入时校验未知引用、非法语法、与asRatio混用、数字 tile 多公式等tile 告警在公式图上评估公式本身v2.36.0 修复此前阈值对着原始操作数比较的问题。Convert to SQL 支持多序列/比率/公式图表v2.36.0输出基于宏的原始 SQL 模板每序列分支一个$__sourceTable(metricType)宏。指标探索器与指标名称选择Metrics explorerv2.37.0图表编辑器的浏览控件把指标命名空间渲染为前缀层级树system→cpu→utilization跨名称与描述搜索行内展示 kind 与描述详情面板给出单位、上报服务、可下钻的标签键按.或_分词嵌套浏览标签时可把过滤器与 group-by 暂存为可移除 chips应用时按 kind 自动选择聚合gauge→avg、counter→sum、histogram→p95。指标名称选择器性能v2.39.0名称改从表的稀疏主索引流式读取约 4,900 个 gauge 指标时首选项约 30ms 而非 770ms浏览时按有数据的指标加权键入时切到全量相关性排序搜索服务器低于 24.2、Distributed 或非 MergeTree 表、主键不含MetricName时自动回退全量列举。名称完整可选v2.38.0指标下拉不再抽样超过 3000 个名称也可按名搜索精确匹配排最前列表不完整时明确提示尊重所选时间范围而非固定看最近 24 小时。目录之外的指标如近三天停止上报的也能按名选图。时间图表的行为与边界高基数序列默认封顶v2.34.0破坏性按高基数字段分组的 tile 不再试图画出每条线默认物化并渲染有界数量的序列内置 N more 悬停/钉住提示与 load all series 逃生口。外部仪表盘 API 上为三态省略默认上限0不限正整数top N依赖省略字段获取全量序列的客户端应改传0。顶层 HAVING/ORDER BY/LIMIT 作用于整体v2.36.0此前泄漏进每个序列分支现引用图表的输出列操作数别名、公式名、比率列、group-by 列、时间桶HAVING err rate 0.5正确过滤连接后的行。混合 float/integer 聚合v2.36.0所有序列值归一化为 Float64解决NO_COMMON_TYPE/Variant 报错原始 SQL 图表的全数字Variant(...)列也归类为数值。多序列指标图表单查询执行v2.35.0一个组合查询替代每序列一查浏览器合并View SQL 展示完整查询。小数值 Y 轴刻度保留小数v2.38.0绝对值 10 的刻度遵循图表 Number Format 小数位上限 2≥10 与恰为 0 的刻度保持整数CLI 终端图同步修复。Recharts 2.13 → 3.xv2.31.0缩放刷选、点击下钻、tooltip 钉住全部迁移到 Recharts 3 API图表交互面广泛改动。查询正确性修复搜索侧_与%恢复字面含义v2.34.0搜索词不再被直接插进 ILIKE 模式当作通配符。每个 URL 都被转义v2.34.0多 URL 查询不再把后续冒号编译为字段查询。开区间/排他区间/非数值边界v2.34.0Duration:[* TO 500]、{100 TO 500}、带时区的DateTime(UTC)、Date32/Nullable(Date)等均按预期处理。搜索分面查询参数内联v2.36.0约 100 个键的批量分面值查询曾超出 ClickHouse web 客户端 URL 参数预算、被代理网关拒收现内联为转义字面量参数个数恒定。仪表盘过滤器、变量与相对时间范围过滤器标记为 requiredv2.39.0仪表盘过滤器可从可选改为必选仅在某取值下才有意义的仪表盘把这一预期随身携带设置贯穿 schema、API 与应用经 API 往返不丢失。静态取值列表过滤器v2.38.0过滤器可配置固定取值集渲染为选择器而非从数据发现UI 过滤器编辑器可创建MCP 服务器也理解静态过滤器。Prometheus 标签值过滤器v2.38.0过滤器取值来自 Prometheus 标签并接受 series selectormatcher收窄来源序列。变量与广播设置v2.35.0变量进入 builder tilev2.36.0builder tile 与原始 SQL tilev2.35.0都会做变量替换SQL 编辑器自动补全并校验变量用法变量的取值查询可依赖其他变量宏参数内嵌套变量/宏也会展开v2.37.0 起变量对所有部署开放移除 feature toggle支持 Lucene 精确匹配展开、PromQL 替换与 MCP。相对时间范围v2.39.0仪表盘可保存最近一小时/最近一天这类相对窗口每次打开都锚定当前时间设置同样贯通 schema 与 API。过滤器取值按变量持久化v2.37.0下钻到搜索时展开变量值而非名称v2.37.0 修复。tile 预览可跟随仪表盘过滤器v2.39.0tile 懒加载v2.29.0tile 滚动进入视口才执行 ClickHouse 查询并缓存结果。表格 tile 按列着色与条件规则v2.32.0行点击外链v2.29.0数字 tile 背景 sparkline、As Ratio、条件颜色v2.29.0。Snap gridv2.32.0拖拽/缩放 tile 时背后绘制网格并高亮实际落点。tile 告警在公式图上评估公式、share_of_total尊重ratioModev2.36.0 修复tile 名称为空被 MCP 拒绝v2.29.0 破坏性。LLM 可观测性仪表盘betav2.38.0 引入/llmbeta 仪表盘v2.39.0 显著加速无需改动插桩直接读取已摄入的 traces 并在查询时解释。要点理解 OTel GenAI 语义约定、OpenLLMetry、OpenInference、Vercel AI SDK对早先采集的遥测追溯生效。图表维度LLM 流量、token 拆分uncached/cached/cache-write/output/reasoning、按模型的估算成本、延迟与首 token 时间、工具调用per-session 时间线含对话视图与并排 LLM span/日志搜索。成本来自内置价格目录考虑 cache-read 折扣与 cache-write 溢价自身上报的成本属性优先于估算多插桩方言并存时选一个权威报告者保证一次调用只计一次。v2.39.0 的加速tile 过滤器改用mapContains走 trace schema 的 key 索引staging 表上 LLM span 谓词从 36 秒 planning 停滞降到 7ms双键过滤从 1,306 个 granule 降到 3 个。伴随行为变化带gen_ai.system的 span 即视为 LLM span。新增按最终用户过滤v2.39.0与 session 过滤器并列下拉列出所搜范围内 LLM span 上的去重用户并作用于包括 Errors 页签关联日志事件在内的所有页签选择进入 URL 可分享。MCP 服务器工具改名、指标一等公民与批量查询v2.29.0 是 MCP 服务器的大版本所有工具从hyperdx_*重命名为clickstack_*服务器也更名为clickstack任何显式引用工具名的 Agent 配置、提示词或自动化都需要更新。随后的能力积累指标一等公民v2.29.0clickstack_list_metrics按 kind、名称模式、时间窗分页与clickstack_describe_metrickind、unit、描述、属性键、采样值clickstack_timeseries/clickstack_table接受metricType/metricName/isDelta与aggFn: increasev2.35.0 增加 summary 类指标。整仪表盘一次校验v2.35.0clickstack_query_tiles接收 dashboard ID 与可选 tile ID 列表默认所有非 markdown tile返回逐 tile 成功/失败摘要与聚合计数失败 tile 内联报告而非中断整次调用。量化分析工具v2.34.0clickstack_emerging_signals对比基线窗口与当前窗口的日志/事件模式回答发生了什么变化。其判定逻辑在 packages/api/src/mcp/tools/query/emergingSignals.ts 中实现为纯函数classifyShift基线缺失且当前份额 ≥newPatternShareFloor判为 emerging当前缺失或份额反向达到ratio倍判为 disappeared比较采用交叉相乘curShare ratio * baseShare避免除零并带 1e-9 相对容差与真实方向变化守卫防止minShareRatio: 1把稳态模板刷成新信号。读/写注解v2.35.0每个工具带 annotations客户端可区分只读查询工具与 save/patch/delete 等破坏性工具工具选择策略在连接时呈现引导 Agent 优先 builder 查询工具而非原始 SQL后者失败率约高一倍。Agent 构建 tile 的过滤器归位v2.35.0save/patch 拒绝 table/line/stacked bar/number/pie/bar tile 的 tile 级where指引使用每序列wheresearch/heatmap/event pattern 仍保留 tile 级过滤器。错误分类v2.30.0span 与hyperdx.mcp.tool.errors计数器带error_category属性ClickHouse 错误按类型与 cause chain 自动分类为 user/server。安全与互操作修复工具 schema 通过 JSON Schema draft 2020-12 校验v2.36.0修复colorRulesbetween元组序列化导致 Gemini 类客户端拒收整个工具列表的问题quantilelevel改为 string enumv2.37.0失败的 MCP 调用在 spanStatusMessage中呈现错误v2.36.0readonly2使max_execution_time真正生效v2.29.0。采集器、存储与运维遥测管道与自托管细节OTel Collector 能力OIDC bearer token 认证v2.35.0standalone 采集器可针对 OIDC 提供方发布的 JWKS 校验 OTLP 请求替代单一长期共享密钥——设置OIDC_ISSUER_URL与OIDC_AUDIENCE即可静态OTLP_AUTH_TOKEN仍可用。Bearer 头两种大小写均可v2.38.0OpAMP 管理模式与 standalone 的OTLP_AUTH_TOKEN均接受Bearer/bearer/BEARER前缀RFC 6750 客户端不再被拒。spanmetrics connector 编译进采集器v2.39.0通过CUSTOM_OTELCOL_CONFIG_FILE提供的自定义 pipeline 可直接引用spanmetricsconnector从 span 推导调用次数与时长RED指标——尤其解决datadogreceiver摄入的 Datadog Agent traces 此前无法产出 RED 指标的问题。纯增量变更默认 pipeline 不变。Datadog receiveropt-inv2.30.0设置ENABLE_DATADOG_RECEIVER后采集器在0.0.0.0:8126挂载 traces/metrics/logs pipeline启用认证时以DD-API-KEY头对团队 API key 校验。PromQL 端点v2.29.0 实验性仅当CLICKHOUSE_PROMETHEUS_METRICS_ENDPOINT设置时才声明prometheusremotewriteexporter 与metrics/promqlpipeline。trace schema 种子带文本索引v2.39.0新建 trace schema 时即建文本索引仅在建表时执行。exporter 超时可配置v2.36.0HYPERDX_OTEL_EXPORTER_TIMEOUT默认 5 秒。ClickHouse 存储与查询PromQL 走 Prometheus HTTP APIv2.39.0破坏性ClickHouse 支持的/query、/query_range代理到连接的/prometheus/api/v1/*ClickHouse 26.8 引入的prometheus_api_v1handler不再调用prometheusQuery/prometheusQueryRange表函数。自带 ClickHouse 镜像升级到 26.8自管 ClickHouse 必须升级到 26.8 并启用该 handler否则 ClickHouse 支持下的 PromQL 查询会失败。database/table参数继续转发。PromQL 代理保留 Connection host 路径前缀v2.38.0破坏性VictoriaMetricsvmselect这类带路径的 host 不再被改写但从 Prometheus UI 复制来的http://prom:9090/graph这类偶然可用的 host 会变成 404升级前请清理 host 中的多余路径。host 上的 query 参数仅作为固定 Prometheus API 参数集query、time、start、end、step、match/match[]、limit、timeout、stats的回退请求值优先curl/Terraform 直接调用传来的非 Prometheus 参数会被丢弃。每次请求关闭子列尺寸计算v2.39.0ClickHouse 26.3 默认开启allow_calculating_subcolumns_sizes_for_merge_tree_reading使 PREWHERE 规划为每个被引用的 map key 拉取 per-part 尺寸SharedMergeTree 上等于每 key×活动 part 一次 S3 GET且max_execution_time无法中断LLM 仪表盘等读 ~64 个属性键的查询可能卡住数分钟查询现在在服务器支持处发送0。per-signal TTLv2.36.0HYPERDX_OTEL_EXPORTER_LOGS_TTL、..._TRACES_TTL、..._METRICS_TTL、..._SESSIONS_TTL各自回退到HYPERDX_OTEL_EXPORTER_TABLES_TTL可让日志/追踪留半年、指标 30 天淘汰HYPERDX_OTEL_EXPORTER_RECONCILE_TABLE_TTLtrue时 migrate 工具把保留策略应用到已存在的表。Reconciliation 默认关闭且刻意保守延长保留不删数据、缩短保留不在启动时批量删除、复合策略tiering/RECOMPRESS/GROUP BYrollups与日历单位保留会被报告并跳过。指标 schema 更精简v2.30.0更高效的主键与更好的时间剪枝。服务可用性与运维MongoDB 启动重试与 /ready 探针v2.36.0初始连接失败不再不重试初始连接以封顶指数退避重试直至成功API 与 OpAMP 均暴露GET /readyMongoDB 未连接时返回 503——Kubernetes 就绪探针应指向它/health保持纯存活检查。API 日志级别默认infov2.36.0破坏性BaseClickhouseClient不再无条件打印原始 SQL查询日志改走 pino 的debug级。生产环境依赖 SQL 日志需设HYPERDX_LOG_LEVELdebug空值Compose 未设变量时的情形回退到默认值而不是让 pino 启动报错。webhook SSRF 校验v2.32.0破坏性Webhook 目标统一按 SSRF 防护检查私有/保留地址默认拦截投递到内网 host 需加入WEBHOOK_HOSTNAME_ALLOWLIST逗号分隔hostname 条目覆盖子域IPv4/IPv6 精确匹配。该白名单不绕过协议校验、Slack hostname 校验以及对所配置 ClickHouse/MongoDB host 的封禁。配置读取见 packages/api/src/config.ts。第三方令牌静态加密v2.39.0设置TOKEN_ENCRYPTION_KEY32 字节base64 或 64 位 hex后Slack bot token、OAuth access/refresh token 等以 AES-256-GCM 加密落盘不设置则维持明文存储。实现见 packages/api/src/utils/tokenEncryption.ts存储格式为v1:provider:payloadpayload 布局为iv || tag || ciphertext信封前缀作为附加认证数据AAD防止负载被换名重放解密按信封内的 provider 分发因此切换 provider 后旧行仍可读启动时以固定哨兵串做加解密自检verifyTokenEncryption密钥不可解析会直接阻断启动。已知限制信封不带 key id轮换TOKEN_ENCRYPTION_KEY会使存量行不可读v1版本字段就是为此预留。密钥生成示例openssl rand -base64 32。个人 API access key 可轮换v2.36.0Team Settings → API Agents 增加 Rotate轮换即时吊销旧 key需同步更新 MCP/AI Agent 配置、Terraform provider 与 CI 脚本浏览器会话不受影响。External API v2 列表分页v2.30.0破坏性/api/v2/alerts、/api/v2/saved-searches、/api/v2/webhooks接受limit1–1000默认 1000与offset默认 0返回meta: { total, limit, offset }按_id排序保证分页稳定并设X-Total-Count头DELETE /api/v2/alerts/:id对不存在资源改返 404。v2 外部 API 资源管理扩展v2.30.0saved-search/webhook/source 全套 CRUDwebhookheaders/queryParams只写不读避免泄露鉴权 tokenPOST /api/v2/dashboards/validate预校验负载。邀请撤销限定团队范围v2.34.0DELETE /team/invitation/:id只允许撤销本团队待处理邀请未知/越权 id 返回 404Authorization与Cookie头从 API 请求日志中脱敏。限流按 access key 键控v2.34.0此前按原始Authorization头值分桶改动Bearer前缀即可绕过配额现按键本身分桶无 key 时回退客户端 IP。token 加密计数器hyperdx.token_encryption.plaintext_reads与hyperdx.token_encryption.disabled两个指标可观测加密关闭状态使其可告警。会话回放与前端体验回放器升级 rrweb 2.1.1v2.36.0从2.0.0-alpha.8迁移到稳定版吸收多年样式表/虚拟 DOM/adopted stylesheets 修复用旧rrweb1.1.3与当前 SDK 录制的会话验证过回放保真度。超大录制事件不再丢失v2.37.0超过录制器约 950KB chunk 大小的 rrweb 事件被拆成共享同一时间戳的多个 chunk此前按时间戳排序会被 ClickHouse 打乱导致整段常是内联 CSS 的完整 DOM 快照被丢弃现在流按确定性排序、chunk 按显式索引重组、无法重建的事件在播放器中标示。存量录制无需重采即可正确回放。多行 SQL 字段自适应高度v2.39.0搜索 WHERE/SELECT/ORDER BY、图表编辑器的 SQL 与 PromQL 字段失焦不再折叠搜索栏语言切换高度一致共享同一高度表。Whats new 内嵌应用v2.37.0Help 菜单的完整 changelog 模态改为内联区块 View all releases 抽屉 未读时 Help 图标上的 sparklechangelog 构建期解析而非运行时拉取。v2.39.0 修复每次部署都闪烁提示键从NEXT_PUBLIC_APP_VERSION部署会盖入构建 id改为 changelog 中最新的发布版本仅当严格更新才提示回滚也不再全员打扰。复制调试信息v2.38.0Help 菜单 Copy debug info 一键打包前后端版本可分别部署、部署模式、用户/团队 id、启用的功能开关、URL/屏幕/视口/OS/浏览器与会话 id控制台可用window.hdx.report()取同样摘要。破坏性变更速查表升级前必读版本变更影响与处置v2.39.0ClickHouse 支持的 PromQL 走/prometheus/api/v1/*自管 ClickHouse 需 ≥26.8 并启用prometheus_api_v1handlerv2.38.0PromQL 代理保留 Connection host 路径清理 host 上多余的路径与 query 字符串v2.36.0API 日志级别默认info不再打印查询 SQL需要 SQL 日志设HYPERDX_LOG_LEVELdebugv2.35.0Terraform 导出使用团队级 import idteam_id/resource_idprovider 需 3.25.0升级后重新导出再导入v2.34.0时间图表默认限制高基数序列需要全量序列的 API 客户端把seriesLimit显式传0v2.32.0Webhook 目标按 SSRF 校验内网投递加入WEBHOOK_HOSTNAME_ALLOWLISTv2.30.0v2 列表端点分页 上限客户端读取meta.total并用offset翻页DELETE /api/v2/alerts/:id对不存在资源返 404v2.29.0MCP 工具hyperdx_*→clickstack_*更新所有显式引用工具名的 Agent 配置v2.29.0User.accessKey唯一索引升级前清理重复 access key否则启动失败v2.29.0指标序列分组区分属性作用域仅影响跨作用域搬运属性的 collector 处理器配置v2.29.0图表调色板 token 改色相命名存量仪表盘自动迁移ClickStack 的chart-1会由蓝变绿可在色相选择器重选v2.29.0MCP tile 名称必须非空空名称name: 报校验错误常用环境变量与功能开关一览变量作用备注TOKEN_ENCRYPTION_KEY第三方令牌 AES-256-GCM 静态加密32 字节base64 或 64 hex轮换会使存量行不可读WEBHOOK_HOSTNAME_ALLOWLISTWebhook 内网 host 白名单逗号分隔hostname 条目覆盖子域HYPERDX_LOG_LEVELAPI 日志级别v2.36.0 起默认infoHYPERDX_OTEL_EXPORTER_LOGS/TRACES/METRICS/SESSIONS_TTL按信号的表保留策略回退到..._TABLES_TTLHYPERDX_OTEL_EXPORTER_RECONCILE_TABLE_TTLmigrate 时应用到存量表默认关保守语义HYPERDX_OTEL_EXPORTER_TIMEOUT采集器 exporter 超时默认 5 秒OIDC_ISSUER_URL/OIDC_AUDIENCEOTLP OIDC 认证替代静态OTLP_AUTH_TOKENCUSTOM_OTELCOL_CONFIG_FILE自定义采集器 pipeline可引用spanmetricsconnectorENABLE_DATADOG_RECEIVERDatadog Agent 接入挂载在0.0.0.0:8126CLICKHOUSE_PROMETHEUS_METRICS_ENDPOINT声明 PromQL exporter/pipeline实验性NEXT_PUBLIC_ENABLE_ALERT_DETAILS告警详情页/alerts/:id默认关v2.35.0 实验性e2e 配置可见 packages/app/playwright.config.tsNEXT_PUBLIC_ENABLE_EXPONENTIAL_HISTOGRAMS指数直方图指标默认关v2.32.0 实验性INGESTION_API_KEYall-in-one 认证镜像的预共享摄入 keyv2.30.0 修复镜像名匹配升级路线与持续追踪综合来看v2.29 → v2.39 的演进主线可概括为告警从发一条消息进化为可编程、可评估、可审计的完整生命周期图表查询从会画图进化为公式、指标发现与性能可控仪表盘从静态画布进化为变量驱动、可过滤、可导出 IaC 的资源同时LLM 可观测性与 MCP Agent 集成成为两条全新产品线底层则是ClickHouse 26.x 时代的查询代理路径与存储运维现代化。升级前请按上表逐条核对破坏性变更重点检查ClickHouse 服务器版本v2.39.0 要求 ≥26.8、Prometheus Connection 的 host 写法、Webhook 是否投递内网、Terraform provider 版本以及 MCP/Agent 配置中的工具名。每个包的细粒度变更可在各 packages/*/CHANGELOG.md 中追踪产品内 Help 菜单的 Whats new 也直接渲染根级发布说明是跟进新版本最快的第一手入口。赞分享可观测性云原生运维【免费下载链接】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点击查看免费下载相关推荐nextra-theme-blog 版本演进深度解读从 2.0 到 4.6 的破坏性变更与能力图谱nextra theme blog 版本演进深度解读从 2.0 到 4.6 的破坏性变更与能力图谱 本篇技术指南以 nextra theme blog 的 C前端文档/教程EUI 2025 年度版本演进深度解读从 v99 到 v111 的关键更新、破坏性变更与升级实践指南EUI 2025 年度版本演进深度解读从 v99 到 v111 的关键更新、破坏性变更与升级实践指南 本指南基于 elastic/eui 在 2025 年度前端UI组件设计系统Monolog 变更日志全解读从 1.0 到 3.11 的版本演进、破坏性变更与关键技术点Monolog 变更日志全解读从 1.0 到 3.11 的版本演进、破坏性变更与关键技术点 导读 本文以 Monolog 项目 CHANGELOG.md ht后端上一篇G-Helper深度配置指南华硕笔记本性能调优与自动化管理下一篇VAP动画播放技术突破跨平台特效渲染的性能瓶颈创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考