如何用 Prometheus 实验性 Search API 快速检索指标名与标签值【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus当 Prometheus 实例中采集了大量指标后逐个去记指标名、标签名和标签值很不方便。Prometheus 提供了一组实验性的 Search API 端点支持对指标名、标签名和标签值做带模糊匹配和过滤的流式检索适合做自动补全或交互式检索。本文适用于运行 Prometheus 服务端server mode的场景需要先通过 feature flag 开启该功能再用 HTTP 请求调用检索端点并解析返回结果。开启 search-api feature flagSearch API 端点默认不启用属于实验性功能行为可能在未来版本中变化通过 release changelog 通知。启动 Prometheus 时用--enable-feature传入search-apiprometheus \ --config.fileprometheus.yml \ --enable-featuresearch-api--enable-feature接受逗号分隔的特性名列表如果已经启用了其他特性把search-api追加到列表中即可。还有一个相关的启动参数--web.search.max-limit默认10000它是搜索端点接受的最大limit值请求中携带更大的limit会被以 HTTP 400 拒绝。默认响应限制100会静默地被钳制到这个上限因此运维侧调小该值不会破坏不带limit的请求。将其设为0会完全移除上限官方文档明确不推荐这样做因为这样任何单一客户端都可以在一次响应中请求整个索引——尤其当端点暴露给可信网络之外的客户端时。可用的检索端点开启后Prometheus 暴露以下六个端点GET 和 POST 均可用GET /api/v1/search/metric_names POST /api/v1/search/metric_names GET /api/v1/search/label_names POST /api/v1/search/label_names GET /api/v1/search/label_values POST /api/v1/search/label_valuesmetric_names按关键字检索指标名label_names按关键字检索标签名label_values检索某个标签的标签值必须额外传label参数。这些端点返回的是流式结果content type 为application/x-ndjson换行分隔的 JSON而不是常见的单个 JSON 对象。检索指标名文档给出的自动补全场景示例curl -g http://localhost:9090/api/v1/search/metric_names?search[]http_reqsort_byscoreinclude_metadatatruelimit5search[]http_req匹配目标字符串检索指标名sort_byscore按相关性得分排序指标名端点支持alpha和score两种模式include_metadatatrue在每条结果中附带指标元数据type、helplimit5最多返回 5 条limit缺省默认是 100。命令中的-g是必需的search[]这类参数名带方括号不带-g时 curl 会因 glob 解析报错。示例假定 Prometheus 监听默认的0.0.0.0:9090如果你改了--web.listen-address把 URL 替换成实际地址。文档示例的返回输出示例结果实际值取决于你的数据{results:[{name:http_requests_total,type:counter,help:Total HTTP requests.}]} {status:success,has_more:false}检索标签名与标签值label_names端点与metric_names的参数用法一致sort_by同样支持alpha | score。检索标签值时label参数是必填的用来指定要检索哪个标签的值用match[]可以把检索范围限定到某些时间序列。文档示例在up指标内检索instance标签中包含909的值curl -g http://localhost:9090/api/v1/search/label_values?labelinstancematch[]upsearch[]909sort_byscore文档示例的返回输出示例结果{results:[{value:localhost:9090},{value:localhost:9091}]} {status:success,has_more:true}常用请求参数三个端点共享以下 URL 查询参数以官方 HTTP API 文档 为准参数说明match[]series_selector可重复用 PromQL 序列选择器圈定检索范围可选search[]string可重复匹配名字或值的搜索字符串多值之间是 OR 关系可选fuzz_thresholdnumber模糊阈值0 到 1000 为最低阈值可选fuzz_algsubsequence \| jarowinkler模糊匹配算法可选默认subsequencecase_sensitivebool是否大小写敏感可选sort_bystring排序模式可用值取决于端点metric_names/label_names/label_values均支持alpha \| scoresort_dirasc \| dsc排序方向仅在sort_byalpha时有效include_scorebool是否在每条结果中附带相关性得分可选start/endrfc3339 或 Unix 时间戳把结果限定到时间窗口可选limitnumber最多返回的结果数可选默认 100上限受--web.search.max-limit约束batch_sizenumber每个 NDJSON 批次建议的结果数可选默认 100两个需要注意的取值细节start/end圈定的时间窗口是近似的由于 Prometheus 按固定大小的 block通常每个 2 小时存储数据结果可能包含略超出该窗口的活跃序列的值。metric_names独有的include_metadata控制是否在结果中附带指标元数据。理解流式响应与验证结果Search API 的流式响应遵循如下约定零个或多个批次行每行带一个results数组可选带warnings数组流以一个trailer 行结束含status、has_more可选warnings如果在发出第一个批次之后迭代中途失败则流以一个error 行含status、errorType、error结束。也就是说验证一次请求是否成功看最后一行trailer 行的status:success表示成功出现errorType/error字段的行表示流式过程中出错。错误发生在流开始之前时返回的是普通 Prometheus JSON 错误对象加 4xx/5xx 状态码。客户端还应容忍没有 trailer 的突然 EOF例如传输失败或服务端关闭并忽略 trailer 中的未知字段以保持前向兼容。trailer 中的has_more字段只是信息性的当前版本的 API不提供分页游标。要取回更多结果只能调大limit受--web.search.max-limit约束或者用match[]收窄请求。未来版本可能会引入游标。一个便于本地验证的小技巧文档提到 OpenAPI 规格可通过/api/v1/openapi.yaml获取默认 OpenAPI 3.1?openapi_version3.2获取 3.2 版本其中包含这些端点的机器可读描述可用于生成客户端或校验请求/响应结构。限制与注意事项实验性端点必须通过--enable-featuresearch-api显式开启属于实验功能行为可能在未来版本改变。仅 server 模式--web.search.max-limit的参数说明明确标注 Use with server mode onlyagent 模式不提供该上限配置。结果上限limit超过--web.search.max-limit默认10000的请求会被 HTTP 400 拒绝默认响应限制为 100。时间窗口为近似start/end的结果可能包含略超出窗口的值。更多参数与流式契约细节参见 HTTP API 文档、feature flags 说明 以及 命令行参数参考。【免费下载链接】prometheusThe Prometheus monitoring system and time series database.项目地址: https://gitcode.com/GitHub_Trending/pr/prometheus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考