运维观测指标监控告警【免费下载链接】falcon-plusAn open-source and enterprise-level monitoring system.项目地址https://gitcode.com/gh_mirrors/fa/falcon-plus点击查看免费下载本文以 Open-Falconfalcon-plus聚合Aggregator模块的 API 文档为主体完整讲解「获取指定主机组下全部聚合监控项」接口的调用方式、请求约束与响应字段含义并结合仓库源码深入剖析其路由注册、分页查询、数据模型与底层聚合计算原理。读完本文你将能够通过 HTTP 接口安全地查询任意主机组的聚合配置理解numerator、denominator、step等核心字段在聚合器aggregator 模块中的真实语义并掌握该 API 在实际监控系统中的定位。接口概述该接口用于获取某个主机组HostGroup下已经创建的全部聚合监控项Aggregator列表是聚合监控功能「配置查询」侧的入口。接口定义位于仓库文档 docs/_posts/Aggregator/2017-01-01-aggreator_of_hostgroup.md请求方法GET请求路径/api/v1/hostgroup/#{hostgroup_id}/aggregators认证要求需要携带有效 Session见文档 docs/_posts/2017-01-01-authentication.md示例请求/api/v1/hostgroup/343/aggregators该路径中的#{hostgroup_id}是 URL 路径参数即主机组的数据库 ID。例如请求GET /api/v1/hostgroup/343/aggregators即表示查询 ID 为 343 的主机组下的所有聚合监控项。核心字段速查原文档对聚合项的三个关键字段给出了中文语义定义这是理解整个聚合监控体系的基础字段含义numerator分子表达式denominator分母表达式step汇报周期秒为单位聚合监控的本质就是对主机组内所有机器的某个分子指标求和再除以分母指标求和最终得到一个「集群视角」的聚合值并按step指定的周期周期性地向监控链路汇报。请求参数结合源码实现modules/api/app/controller/host/aggreator_controller.go该接口共支持三类参数参数位置是否必填说明host_group即hostgroup_idURL Path必填主机组 ID缺失或非数字时返回400pageQuery可选分页偏移量与limit同时使用limitQuery可选分页条数与page同时使用源码中通过c.DefaultQuery(page, )与c.DefaultQuery(limit, )读取可选参数再交给h.PageParser(pageTmp, limitTmp)解析见 modules/api/app/helper/pagging_parser.go。分页解析逻辑为当limit与page均被合法解析即不为-1时走带分页的 SQLSELECT * FROM cluster WHERE grp_id ? LIMIT ?,?否则未传分页参数一次返回该主机组下的全部聚合项SELECT * FROM cluster WHERE grp_id ?。路径参数从c.Params.ByName(host_group)获取若为空则直接返回400grp id is missing若无法转换为整数也会返回400。这要求调用方必须传入合法的数字型主机组 ID。响应字段解析当请求成功时接口返回HTTP 200响应体为一个 JSON 对象整体结构为「主机组名称 聚合项数组」{ hostgroup: test_group, aggregators: [ { id: 13, grp_id: 343, numerator: $(cpu.idle), denominator: 2, endpoint: testenp, metric: test.idle, tags: , ds_type: GAUGE, step: 60, creator: root }, { id: 14, grp_id: 343, numerator: $(cpu.idle), denominator: 2, endpoint: testenp, metric: test.idle, tags: , ds_type: GAUGE, step: 60, creator: root } ] }各字段含义如下字段类型说明hostgroupstring主机组名称。由首个聚合项的grp_id反查host_group表得到若无聚合项则为空字符串aggregatorsarray聚合监控项列表aggregators[].idint聚合项在cluster表中的自增主键aggregators[].grp_idint所属主机组 ID即请求路径中的hostgroup_idaggregators[].numeratorstring分子表达式如$(cpu.idle)支持加减运算、$#与比较模式aggregators[].denominatorstring分母表达式如2纯数字aggregators[].endpointstring聚合结果上报到监控链路时使用的 endpoint机器名标识aggregators[].metricstring聚合结果上报时使用的指标名aggregators[].tagsstring聚合结果携带的标签可为空字符串aggregators[].ds_typestring数据类型创建时固定为GAUGEaggregators[].stepint汇报周期单位为秒aggregators[].creatorstring创建者用户名注意响应中的hostgroup名称源码在GetAggregatorListOfGrp中通过aggregators[0].HostGroupName()反查主机组名称该方法定义在 modules/api/app/model/falcon_portal/cluster.go逻辑是依据GrpId在host_group表中查找对应的Name。若该主机组下没有任何聚合项hostgroup字段返回空字符串。认证与权限约束该接口属于受保护资源。从路由注册代码可见modules/api/app/controller/host/host_routes.gohostr : r.Group(/api/v1) hostr.Use(utils.AuthSessionMidd) hostr.GET(/hostgroup/:host_group/aggregators, GetAggregatorListOfGrp)所有/api/v1下的路由都会先经过utils.AuthSessionMidd会话认证中间件因此调用本接口必须先登录获取 Session具体认证机制参见 modules/api/app/utils/auth_middle.go 与 docs/_posts/2017-01-01-authentication.md。未携带有效会话时请求会被中间件拦截并返回未认证响应。与同组其他聚合接口相比本接口仅要求「已登录」即可查询列表而创建POST /aggregator、更新PUT /aggregator、删除DELETE /aggregator/:id聚合项时非管理员用户还必须是该主机组的创建者见 aggreator_controller.go 中的权限校验体现了「读放开、写受限」的权限设计。数据模型与存储结构聚合项在数据库中对应falcon_portal库的cluster表表结构定义见 scripts/mysql/db_schema/2_portal-db-schema.sqlGo 侧模型见 modules/api/app/model/falcon_portal/cluster.goCREATE TABLE cluster ( id INT UNSIGNED NOT NULL AUTO_INCREMENT, grp_id INT NOT NULL, numerator VARCHAR(10240) NOT NULL, denominator VARCHAR(10240) NOT NULL, endpoint VARCHAR(255) NOT NULL, metric VARCHAR(255) NOT NULL, tags VARCHAR(255) NOT NULL, ds_type VARCHAR(255) NOT NULL, step INT NOT NULL, last_update TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, creator VARCHAR(255) NOT NULL, PRIMARY KEY (id) ) ENGINEInnoDB DEFAULT CHARSETutf8 COLLATEutf8_unicode_ci;从表结构可以看出两点设计意图numerator/denominator均为VARCHAR(10240)长文本因为其内容本质上是可嵌套的指标表达式而非单一数字例如$(cpu.busy)$(cpu.idle)-$(cpu.nice)last_update字段由数据库自动维护ON UPDATE CURRENT_TIMESTAMP聚合器模块正是用它来感知配置是否发生变化详见下文。需要注意的是API 响应中的聚合项 JSON 不包含last_update字段——该字段主要服务于聚合器模块内部的配置增量识别。聚合器如何消费这些配置底层原理通过本接口查询到的聚合配置最终由独立的aggregator模块源码位于 modules/aggregator消费执行。理解这一点有助于明确各字段的真实用途1. 配置加载聚合器周期性从cluster表读取全部配置modules/aggregator/db/reader.go并支持通过配置文件中的database.ids字段按id区间切分任务从而支持聚合器多实例水平扩展。配置刷新周期由database.interval控制默认 55 秒每次刷新都会以IdLastUpdate为 key 判断配置是否变更。2. 表达式解析每个聚合项会执行WorkerRun计算modules/aggregator/cron/run.go。numerator与denominator支持三种形态纯数字如2作为常量参与运算指标表达式如$(cpu.idle)、$(cpu.busy)$(cpu.idle)-$(cpu.nice)其中$(...)内为 counter 名/-为操作符会先通过 graph 查询各机器该 counter 的最近值再逐机求和比较模式如$(cpu.busy)80表达式结果为布尔值满足条件计 1否则计 0用于统计满足条件的机器数量特殊值$#代表「有效机器数」成功查询到数据的机器个数。表达式合法性校验与解析逻辑见 modules/aggregator/cron/run.go计算函数compute与比较函数compareSum见 modules/aggregator/cron/computer.go。3. 聚合计算与上报计算过程为遍历主机组内所有机器机器列表通过 API 获取见 modules/aggregator/sdk/sdk.go对每台机器分别求出分子值与分母值最后执行numerator/denominator得到集群聚合结果。若分母为 0 或有效机器数为 0则该周期跳过计算。结果通过sender.Push(item.Endpoint, item.Metric, item.Tags, numerator/denominator, item.DsType, int64(item.Step))推送给 transfer 模块modules/aggregator/cron/run.go其中endpoint、metric、tags、ds_type、step正是本接口响应中的字段。由此可以更深刻地理解文档中的中文注释numerator是分子表达式denominator是分母表达式step既是查询最近数据的时间窗口2 倍 step也是聚合结果上报的周期秒。4. 聚合器部署配置参考聚合器模块的完整配置示例如下modules/aggregator/cfg.example.json其中database.addr指向falcon_portal库、api.plus_api指向 falcon-plus 的 API 地址、api.push_api指向 transfer 的推送接口{ debug: true, http: { enabled: true, listen: 0.0.0.0:6055 }, database: { addr: root:tcp(127.0.0.1:3306)/falcon_portal?locLocalparseTimetrue, idle: 10, ids: [1, -1], interval: 55 }, api: { connect_timeout: 500, request_timeout: 2000, plus_api: http://127.0.0.1:8080, plus_api_token: default-token-used-in-server-side, push_api: http://127.0.0.1:1988/v1/push } }相关接口一览本接口所属的聚合监控 API 组还包括路由均注册于 modules/api/app/controller/host/host_routes.go方法路径功能GET/api/v1/hostgroup/:host_group/aggregators查询主机组聚合项列表本文接口GET/api/v1/aggregator/:id按 ID 查询单个聚合项POST/api/v1/aggregator创建聚合项PUT/api/v1/aggregator更新聚合项DELETE/api/v1/aggregator/:id删除聚合项其中创建聚合项时ds_type固定为GAUGE源码见 aggreator_controller.go因此在本接口响应中看到的ds_type恒为GAUGE。如果需要查阅这些接口的完整文档可参考仓库中的 docs/doc/aggregator.html 及docs/_posts/Aggregator/目录下的系列文档。调用建议与常见问题确认主机组 ID路径参数是数字型主机组 IDgrp_id不是主机组名称若 ID 不存在或非法接口会返回400。先登录再调用该接口受AuthSessionMidd保护需携带有效 Session可先用POST /api/v1/user/login登录获取会话见 docs/_posts/User/2017-01-01-user_login.md。合理使用分页当聚合项较多时建议携带page与limit参数分页拉取避免一次返回过多数据不传分页参数时接口会返回该主机组下全部聚合项。区分「配置」与「计算结果」本接口返回的是聚合监控的配置定义分子、分母、周期等聚合项的实际计算结果由aggregator模块周期性推送到 transfer并以endpoint metric为标识存入 graph可通过 graph 查询接口查看最终的集群聚合曲线。通过本接口你可以程序化地盘点任意主机组的聚合监控配置为「配置审计」「批量巡检」或「聚合监控体系的前端展示」提供可靠的数据来源。赞分享运维观测指标监控告警【免费下载链接】falcon-plusAn open-source and enterprise-level monitoring system.项目地址https://gitcode.com/gh_mirrors/fa/falcon-plus点击查看免费下载相关推荐Open-Falcon API 实战查询模板关联主机组列表GET /api/v1/template/{template_id}/hostgroupOpen Falcon API 实战查询模板关联主机组列表GET /api/v1/template/{template_id}/hostgroup 本篇技运维观测指标监控告警falcon-plus 主机关联主机组查询 API 实战GET /api/v1/host/{host_id}/hostgroup 全解析falcon plus 主机关联主机组查询 API 实战GET /api/v1/host/{host_id}/hostgroup 全解析 本篇文章围绕 Ope运维观测指标监控告警Uncloud 服务端口发布指南使用 Caddy 实现 Ingress 与 Host 模式暴露服务Uncloud 服务端口发布指南使用 Caddy 实现 Ingress 与 Host 模式暴露服务 本文是 Uncloud 集群对外发布服务的实战指南。Unc运维观测指标监控告警上一篇终极指南spotDL命令行参数完全解析与高效使用技巧下一篇CANN-Bench性能评分机制深度解读如何科学衡量AI算子优化效果创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考