Skip to content

docs(monit): document datasource query tools on the invoke entry - #380

Merged
ysyneu merged 3 commits into
mainfrom
docs/monit-datasource-query-tools
Sep 10, 2026
Merged

docs(monit): document datasource query tools on the invoke entry#380
ysyneu merged 3 commits into
mainfrom
docs/monit-datasource-query-tools

Conversation

@UlricQin

@UlricQin UlricQin commented Sep 10, 2026

Copy link
Copy Markdown
Member

变更摘要

  • Operation 描述更新monit-datasource-tools-invoke 的 description 收敛为单句(诊断或查询工具),细节下沉到 x-mint.content 新增的 Usage / 使用说明小节(工具族划分、协议里程碑门槛、params 约定、Explore 结果形态、统一大小/超时边界)。
  • 新增 11 个 SchemaDatasourceQueryExecution(instant/range/window 三种执行模式,公开 Schema 不含保留字段 step_seconds)+ 10 种数据源的 <Type>QueryParams(prometheus、mysql、postgres、oracle、clickhouse、elasticsearch、loki、victorialogs、sls、tencent_cls),覆盖 limit/direction 日志选项、SLS project/logstore/powersql、CLS region/topic_id/syntax 及各自的 kind 约束。
  • 字段描述更新tool / params 描述替换过时的 "mysql.query/postgres.query unsupported" 表述,改为按数据源列出查询工具及对应 params Schema。
  • Examples:请求与 200 响应均由单 example 改为 examples 命名映射,新增 query 示例(prometheus.query instant,完整 explore_result.v1 结果信封)。
  • 限制更新:完整成功响应上限 1 MiB → 10 MiB(查询/诊断统一);413 响应描述未含大小数值,保持不变。
  • 开发者文档同步zh/en/developer/cli.mdxzh/en/developer/go-sdk.mdxdatasource-tools-invoke / ToolsInvoke 段落同步更新查询工具表述与 10 MiB 上限。
  • 四个 OpenAPI JSON(monitors 与 consolidated、en/zh)结构完全一致,仅文案语言不同。

追加:统一 monit-query 命令(c663e0d)

  • zh/en/developer/cli.mdxmonit-query 章节整体改写为统一 tool 调用形态(无子命令):fduty monit-query <datasource-id> --tool '<name>' [--params '<json>'];查询工具与诊断工具都走它,旧 monit-query data 子命令退役(含原 rows 弃用段落一并移除)。
  • 结果形态说明由 query_result.v1 同步为 explore_result.v1(samples/frames/logs);章节内不再出现 /monit/query/data
  • monit datasource-tools-invoke 章节保留(命令仍存在),注明与 monit-query 等价、后者为推荐路径。
  • /monit/query/data 暂不从公开 OpenAPI 下线(等客户迁移),spec 改动保持不变;go-sdk.mdx 的 QueryData 段落保留不动。

契约来源

字段级权威为 monit-webapi PR #119(已上线):types/datasource_query_tools.gologic/datasource_query_tools.gopkg/exploreprotocol/validate.govalidateHTTPExecution)。

验证

  • 四个 JSON 均可 json.load 解析。
  • en/zh 结构一致性断言通过:paths/components 键集、operation 结构、11 个新 Schema 的 required/enum/properties 完全一致(仅 description/summary 文案不同;tags、x-mint.href、sidebarTitle 为既有本地化差异)。
  • python3 scripts/lint_openapi.py 退出码 0(12 个 spec 文件无违规)。
  • mint broken-links 通过(no broken links found)。
  • git diff --stat 符合预期:4 个 JSON + 4 个 mdx。

后续依赖

go-flashduty SDK 将 sync 本 spec(新增 Schema 与字段描述以本文档为准)。

flashduty-bot and others added 3 commits September 10, 2026 09:34
The DatasourceQueryExecution field note said from_ms was optional for
VictoriaLogs instant executions. The invoke entry requires from_ms for
every VictoriaLogs kind, and the VictoriaLogsQueryParams description
already says so; make the field note agree.
@ysyneu
ysyneu merged commit ac0c1db into main Sep 10, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants