OneUptime 仪表盘变量与筛选(Dashboard Variables Filters)完整指南 📅 发布时间:2026/9/19 4:09:50 👁 浏览次数: OneUptime 仪表盘变量与筛选Dashboard Variables Filters完整指南【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptimeOneUptime 是一个开源的监控与可观测性平台monitoring and observability platform其仪表盘Dashboard允许你把一个静态面板变成可交互的模板。本文基于 App/FeatureSet/Docs/Content/es/dashboards/variables.md原文为西班牙语展开结合仓库源码前端组件、类型定义、插值引擎逐项讲解变量类型、多选、默认值、widget 引用、时间范围与自动刷新并给出源码级的实现依据。读完本文你将能独立创建一个按服务/环境/集群维度模板化的 OneUptime 仪表盘并理解变量值是如何从工具栏一路注入到每个 widget 查询中的。什么是仪表盘变量把一个面板变成模板变量Variable的核心作用是把一个面板升级为一个模板。设想你维护checkout、payments、search三个服务与其手动搭建三个几乎相同的图表面板不如在面板上添加一个service变量——观众在面板顶部的下拉菜单里选择服务名同一组图表就自动针对所选服务重新渲染。在 OneUptime 中变量在Panel → Ajustes → Variables面板 → 设置 → 变量中添加。每个变量包含名称name用于在 widget 中以{{name}}形式引用可选标签label显示在工具栏上的可读名称未设置时回退到 name见 DashboardVariable.ts 中label?: string | undefined的定义类型type决定选项从哪里来是下文四种类型之一。从源码看变量类型定义在 DashboardVariable.tsexport enum DashboardVariableType { CustomList Custom List, Query Query, TextInput Text Input, TelemetryAttribute Telemetry Attribute, ProjectLabel Project Labels, }除原文档介绍的四种类型外仓库中还存在ProjectLabel项目标签类型——它绑定监控列表Monitor Listwidget 的标签过滤与本文的 Telemetry Attribute 变量是互补的两种自动作用域机制。四种变量类型添加变量的交互入口是 DashboardVariablesModal.tsx其中 Source 下拉框提供上述类型选项。下面逐一说明。列表自定义Lista personalizada / Custom List一个静态下拉菜单选项由你手写。适用场景选项少且固定。例如environment取值为prod, staging, devregion取值为us-east-1, eu-west-1, ap-south-1。配置方式在变量的 Values 输入框中以逗号分隔填写源码中 placeholder 为prod, staging。底层在 DashboardVariableControl.tsx 中把字符串按逗号拆分并 trimconst customListOptions: Arraystring variable.customListValues ? variable.customListValues.split(,).map((v: string) v.trim()) : [];注意Custom List 变量不支持多选在 UI 中被禁用只有自定义列表可勾选 Allow multi-select见DashboardVariablesModal.tsx中多选复选框的禁用逻辑。查询Consulta / Query选项来自对你的数据执行的一次查询。适用场景选项随时间变化希望下拉菜单始终跟上数据。例如过去 24 小时出现过的每个客户 ID。查询在项目数据上执行结果直接转换为下拉选项。仓库现状重要从源码看这是legacy遗留类型——编辑器中明确标注This legacy query variable is preserved. Query option loading is not supported.见 DashboardVariablesModal.tsx且该类型在 Source 下拉中只有在已选中时才会保留显示。因此新建变量请优先使用 Telemetry Attribute 或 Custom ListQuery 变量仅作为历史兼容保留。这属于原文档未覆盖、但源码明确给出的重要细节。文本输入Entrada de texto / Text Input一个自由文本输入框观众输入什么就用什么。适用场景把面板当成搜索工具——按 IP 地址、请求 IDrequest ID或任何自由格式值过滤。约束该类型强制关闭多选isMultiSelect被置为false见 DashboardVariablesModal.tsx。渲染时表现为一个宽度约w-28的文本输入框清空即代表不设置任何过滤。遥测属性Atributo de telemetría / Telemetry Attribute选项是当前面板时间范围内某个遥测属性attribute的全部去重取值。配置设置attribute key例如service.name、host.name、k8s.cluster.name编辑器中 placeholder 即e.g. k8s.cluster.name并提供已发现属性的自动补全。数据来源下拉选项来自 logs、metrics、traces 中该属性的所有不同取值且随时间范围与数据自动更新——当你部署一个标记为service.name inventory的新服务时无需编辑面板inventory会自动出现在下拉菜单中。推荐度源码注释明确称其为最常用类型因为它与你在遥测中已经发送的标签label/tag天然对应。源码链路工具栏加载选项时调用MetricUtil.getTelemetryAttributeValues()见 DashboardVariableSelector.tsx它向后端POST /telemetry/metrics/get-attribute-values提交attributeKey可选metricName、searchText并返回values数组见 Metrics.ts。可选键的自动补全则来自getTelemetryAttributes()POST /telemetry/metrics/get-attributes。补充项目标签Project Labels仓库中第五种类型ProjectLabel用于把变量绑定到监控列表 widget 的标签过滤Bind this variable in a Monitor List widgets Label Variable setting见 DashboardVariablesModal.tsx。它需要从项目标签中选择 1~1000 个允许值labelOptions默认值必须是允许值之一或 All。虽然原文档未提及但在需要按业务标签而非遥测属性过滤监控状态时它是对 Telemetry Attribute 的有力补充。多选Selección múltiple / Multi-select每个变量都可开启多选。开启后观众可一次选择一个或多个值面板会过滤到其中任意一个即或语义。何时用想在不出面板的情况下对比 checkout 和 payments 一起。何时避免当所选值之间的数学运算没有意义时例如对平均数再取平均。源码视角变量模型用isMultiSelect?: boolean表示开关用selectedValues?: Arraystring保存当前多选值DashboardVariable.ts。多选 UI 是一个弹层popover复选框列表DashboardVariableControl.tsx未选择任何值时按钮显示 All选择 1 个显示该值选择多个显示 N selected。多选与默认值不兼容编辑器在多选开启时禁用默认值输入框——因为多选初始状态永远是 All设置一个默认值会导致面板背后悄悄加了过滤、控件却显示 All的误导状态见 DashboardVariablesModal.tsx 的注释。这一细节原文未讲但对正确使用至关重要。多选在查询中的语义在 VariableInterpolation.ts 的resolveValue()中多选只以selectedValues为准空列表即 All不产生任何过滤谓词绝不回退到defaultValue非空时注入IN (...)谓词Includes操作符服务端生成attributes[key] IN (...)。默认值Valores predeterminados每个变量都可以有一个默认值。面板先用默认值渲染直到观众手动更改。单选框工具栏下拉的取值规则是selectedValue ?? defaultValue ?? ——只有从未选择过undefined时才落到默认值显式选 All空字符串是一个真实选择不会被默认值覆盖源码注释强调这里用??而非||见 DashboardVariableControl.tsx。文本框同理清空输入框会保持为空??语义见 DashboardVariableControl.tsx。公共面板Public Dashboard默认值就是匿名访客第一眼看到的值因此应把默认值设为最受关注的服务/环境。在 widget 中使用变量任何接受过滤器的地方——指标的WHERE、列表的过滤条件、日志流中的属性匹配——都可以写{{variable_name}}。例如一个按服务过滤的图表service.name {{service}}当下拉选在checkout时图表过滤到 checkout 服务观众切到payments图表立即为 payments 重新渲染。对于 Telemetry Attribute 变量无需手工逐 widget 编辑OneUptime 知道该变量绑定的属性键attributeKey会在渲染时自动把过滤作用到所有使用同一属性的 widget 上。这是通过 VariableInterpolation.ts 的applyToAttributes()实现的收集所有type TelemetryAttribute且配置了attributeKey的变量用resolveValue()解析当前值单值→attributes[key] ...多值→attributes[key] IN (...)空/未选→删除该键上的已有过滤即恢复全量视图把结果合并进 widget 的 metric 查询配置applyToQueryConfig/applyToQueryConfigs见 VariableInterpolation.ts。这套插值引擎是所有 metric 图表、日志流等 widget 的统一入口注释中明确它是决定一个变量当前含义的唯一地方VariableInterpolation.ts。HTML widget 的特殊用法HTML widget 中同样支持{{variableName}}占位符渲染前替换为当前值换值即重渲染脚本还可以通过window.ONEUPTIME.variables.environment以及window.ONEUPTIME.startDate/endDateISO 8601拿到变量值和面板时间范围见 App/FeatureSet/Docs/Content/en/dashboards/widgets.md。变量名不匹配任何已定义变量时占位符原样保留。时间范围Rango de tiempo面板头部有一个全局时间范围每个指标 widget 都查询这个窗口。选项包括预置Presets最后一小时、24 小时、7 天、30 天、90 天取决于你的数据保留期。源码中时间范围枚举定义于 TimeRange.ts实际可选项更细Past 5 Mins、15 Mins、30 Mins、1/2/3 Hours、1/2 Days、1/2 Weeks、1/2/3 Months以及Custom。原文档列出的 1h/24h/7d/30d/90d 是其中的典型子集实际下拉以仓库枚举为准。自定义Custom手动选择开始与结束时刻。时间范围会进入面板 URL分享链接即分享时间窗口。事故incident期间特别有用——把范围固定为今天 10:00–10:30 UTC把链接贴进事故频道所有打开链接的人看到的就是同一窗口。从 DashboardView.tsx 及 VariableUrlState.ts 的代码可以进一步确认变量选择同样以?var-namevalue形式写入 URL使用变量名称而非 id因此一个名为cluster的变量在多个面板间共享链接依然有效多选用逗号分隔例如?var-clustera,b写入使用history.replaceState不产生新的历史记录也不会破坏 URL 中其他参数如认证 token打开链接时会用 URL 中的选择覆盖已保存的变量配置applyUrlToVariables实现链接即快照。刷新间隔Intervalo de actualización时间范围旁边可以选择 widget 多久重新查询一次关闭Off页面加载时查询一次。5s / 10s / 30s / 1m / 5m / 15m自动刷新。适用建议自动刷新适合挂在墙上的大屏wall screen或实时事故视图排查问题时建议关闭避免视野在观察期间不停跳动。源码实现枚举定义在 DashboardViewConfig.ts毫秒换算为5000 / 10000 / 30000 / 60000 / 300000 / 900000Off 返回null。DashboardView.tsx 中用setInterval驱动triggerRefresh()重新查询编辑模式Edit下自动刷新会被禁用避免编辑时视图不停跳动。面板的刷新间隔还会随配置保存config.refreshInterval并在加载时恢复DashboardView.tsx。组合示例服务模板化面板一个按服务模板化的面板通常包含service变量类型Telemetry Attribute绑定service.name。默认值你最关注的服务。多选关闭保证图表始终只显示一个服务。environment变量类型Custom List。默认值prod。cluster变量类型Telemetry Attribute绑定k8s.cluster.name。多选开启以便跨集群对比。引用这些变量的 widget在过滤条件中写{{service}}、{{environment}}、{{cluster}}。结果一个面板、覆盖所有服务、顶部三个下拉菜单。观众无需编辑面板即可自由切换视角公共面板访客则默认看到你配置的默认值组合。进阶要点与注意事项变量命名规范名称必须匹配^[a-zA-Z_][a-zA-Z0-9_]*$字母、数字、下划线不能以数字开头且在同一面板内不区分大小写去重编辑器会实时校验见 DashboardVariablesModal.tsx。这一约束同时保证了?var-nameURL 语法与逗号分隔不会冲突。All 是一个真实状态任何单值变量都有隐式的 All 选项空字符串。选择 All 会移除对应属性上的过滤展示跨所有取值的聚合视图。Telemetry Attribute 变量的自动作用域它按属性键匹配 widget因此为同一属性新建变量后已有 widget 无需逐个修改但这意味着面板中所有引用该属性的查询都会受此变量影响。已删除变量的占位符引用不存在变量的{{name}}会原样保留HTML widget 场景Telemetry Attribute 绑定到已删除变量时编辑界面会给出 Unavailable variable 红色告警见 TelemetryAttributeVariableDropdown.tsx。多选变量的 N selected 指示工具栏多选按钮会显示已选数量并可一键 Clear 清空回 AllDashboardVariableControl.tsx。延伸阅读Widgetswidget 详解每种 widget 如何使用过滤条件HTML widget 如何消费变量与时间范围。Compartir y Paneles Públicos分享与公共面板变量与分享链接的配合。Crear un Panel创建面板画布canvas的编辑机制。核心源码入口DashboardVariable.ts、DashboardVariableControl.tsx、VariableInterpolation.ts、VariableUrlState.ts。【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考