From b6db95bc46ba26609afdaeb61a787273cc61bf04 Mon Sep 17 00:00:00 2001 From: flashduty-bot Date: Thu, 10 Sep 2026 09:34:49 +0800 Subject: [PATCH 1/3] docs(monit): document datasource query tools on the invoke entry --- api-reference/monitors.openapi.en.json | 397 +++++++++++++++++++++++-- api-reference/monitors.openapi.zh.json | 397 +++++++++++++++++++++++-- api-reference/openapi.en.json | 397 +++++++++++++++++++++++-- api-reference/openapi.zh.json | 397 +++++++++++++++++++++++-- en/developer/cli.mdx | 4 +- en/developer/go-sdk.mdx | 2 +- zh/developer/cli.mdx | 4 +- zh/developer/go-sdk.mdx | 2 +- 8 files changed, 1514 insertions(+), 86 deletions(-) diff --git a/api-reference/monitors.openapi.en.json b/api-reference/monitors.openapi.en.json index 6b08e45e..5a89d54a 100644 --- a/api-reference/monitors.openapi.en.json +++ b/api-reference/monitors.openapi.en.json @@ -2072,18 +2072,35 @@ }, "/monit/datasource/tools/invoke": { "post": { - "description": "Execute one deterministic tool against a configured datasource. Requires all currently online routable Edge sessions in the cluster to support the v0.71.0 base invoke protocol; individual tools may require a newer implementation. No tool catalog, automatic replay, or fallback to Agent/legacy diagnose. Request body limit 128 KiB; complete success response limit 1 MiB; tool timeout at most 25 seconds.", + "description": "Execute one deterministic diagnostic or query tool against a configured datasource.", "operationId": "monit-datasource-tools-invoke", "requestBody": { "content": { "application/json": { - "example": { - "datasource_id": 10, - "params": {}, - "tool": "mysql.overview" - }, "schema": { "$ref": "#/components/schemas/DatasourceToolInvokeRequest" + }, + "examples": { + "diagnostic": { + "value": { + "datasource_id": 10, + "params": {}, + "tool": "mysql.overview" + } + }, + "query": { + "value": { + "datasource_id": 24000, + "tool": "prometheus.query", + "params": { + "expr": "sum(rate(http_requests_total[5m]))", + "execution": { + "kind": "instant", + "to_ms": 1789000000000 + } + } + } + } } } }, @@ -2093,17 +2110,6 @@ "200": { "content": { "application/json": { - "example": { - "data": { - "data": { - "version": "8.0.36" - }, - "datasource_id": 10, - "summary": "MySQL overview", - "tool": "mysql.overview" - }, - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" - }, "schema": { "allOf": [ { @@ -2118,6 +2124,45 @@ "type": "object" } ] + }, + "examples": { + "diagnostic": { + "value": { + "data": { + "data": { + "version": "8.0.36" + }, + "datasource_id": 10, + "summary": "MySQL overview", + "tool": "mysql.overview" + }, + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + } + }, + "query": { + "value": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "datasource_id": 24000, + "tool": "prometheus.query", + "data": { + "format": "explore_result.v1", + "result": { + "kind": "samples", + "samples": [ + { + "labels": { + "__name__": "up", + "instance": "10.101.214.50:7070" + }, + "value": 1 + } + ] + } + } + } + } + } } } }, @@ -2232,7 +2277,7 @@ "Monitors/Data sources" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **2,000 requests/minute**; **32 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\nUse datasource IDs from `/monit/datasource/list`. Disabled datasources return `datasource_disabled`; `alerting_enabled=false` does not block tools. Errors use non-2xx HTTP status and `error.code`, `error.message`, `error.reason`. `tool_not_supported` indicates the selected executor does not provide this tool; it is not a vendor permission error. Never retry through another Edge or the legacy diagnose endpoint automatically.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **2,000 requests/minute**; **32 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\nUse datasource IDs from `/monit/datasource/list`. Disabled datasources return `datasource_disabled`; `alerting_enabled=false` does not block tools. Errors use non-2xx HTTP status and `error.code`, `error.message`, `error.reason`. `tool_not_supported` indicates the selected executor does not provide this tool; it is not a vendor permission error. Never retry through another Edge or the legacy diagnose endpoint automatically.\n\n## Usage\n\n- Two tool families share this entry: diagnostic tools defined by the executing Edge (e.g. `mysql.overview`, `prometheus.metric_trends`) and query tools named `.query`. The tool prefix must match the datasource type.\n- Query tools require the Edge cluster to support Explore queries (protocol milestone v0.68.0); diagnostic tools require the v0.71.0 base invoke protocol. Unsupported clusters fail with `edge_upgrade_required`, `mixed_edge_versions`, or `edge_version_unknown`; never fall back to `/monit/query/data` or another endpoint automatically.\n- For query tools, `params` follows the per-datasource schema named in the `tool` field description. `expr` and `execution` are always required. `limit`/`direction` only bound raw-log retrieval, never SQL rows or scanned data. Unknown extension fields are tolerated but never executed or forwarded.\n- Query `data` is the complete Explore result: `format` is `explore_result.v1` and `result.kind` is `samples`, `frames`, or `logs`; log results keep `applied_limit` and `has_more`. Query results never synthesize `summary` or `truncated`.\n- Request body limit 128 KiB; complete success response limit 10 MiB for both families; diagnostic tool timeout at most 25 seconds.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-tools-invoke", "metadata": { "sidebarTitle": "Invoke datasource tool" @@ -4916,6 +4961,318 @@ }, "type": "object" }, + "DatasourceQueryExecution": { + "type": "object", + "additionalProperties": true, + "required": [ + "kind", + "to_ms" + ], + "properties": { + "kind": { + "type": "string", + "enum": [ + "instant", + "range", + "window" + ], + "description": "Execution mode: `instant` evaluates at a single timestamp, `range` evaluates a stepped series, and `window` evaluates one bounded time window." + }, + "from_ms": { + "type": "integer", + "format": "int64", + "description": "Window or range start as a Unix epoch timestamp in milliseconds. Required for `range` and `window`; optional for Loki and VictoriaLogs `instant`; rejected by Prometheus `instant`." + }, + "to_ms": { + "type": "integer", + "format": "int64", + "description": "Query end time as a Unix epoch timestamp in milliseconds; for `instant` it is the evaluation timestamp." + }, + "max_data_points": { + "type": "integer", + "format": "int64", + "description": "`range` only, required: maximum returned data points; the server computes the effective step from the window." + }, + "min_step_seconds": { + "type": "integer", + "format": "int64", + "description": "`range` only, optional: positive lower bound in seconds for the computed step." + } + } + }, + "PrometheusQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "prometheus.query parameters. `expr` is PromQL. `execution.kind` must be `instant` or `range`; `instant` accepts only `to_ms`." + }, + "MySQLQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "mysql.query parameters. `expr` is a single read-only SQL statement. `execution.kind` must be `window`." + }, + "PostgresQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "postgres.query parameters. `expr` is a single read-only SQL statement. `execution.kind` must be `window`." + }, + "OracleQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "oracle.query parameters. `expr` is a single read-only SQL statement. `execution.kind` must be `window`." + }, + "ClickHouseQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "clickhouse.query parameters. `expr` is a single read-only SQL statement. `execution.kind` must be `window`." + }, + "ElasticsearchQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "elasticsearch.query parameters. `expr` is a single SQL statement; Elasticsearch DSL queries are not supported. `execution.kind` must be `window`." + }, + "LokiQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "description": "Maximum raw-log entries to return (1–1000). Only bounds raw logs, not SQL rows or scanned data; omitted keeps the executor default. Explicit null is invalid." + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "Raw-log retrieval order: `latest` returns the newest entries first, `earliest` the oldest. Omitted keeps the executor default." + } + }, + "description": "loki.query parameters. `expr` is LogQL. `execution.kind` must be `instant` or `range`; `instant` keeps the full time context so `$__auto` ranges resolve. `limit` and `direction` only apply to raw-log results." + }, + "VictoriaLogsQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "description": "Maximum raw-log entries to return (1–1000). Only bounds raw logs, not SQL rows or scanned data; omitted keeps the executor default. Explicit null is invalid." + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "Raw-log retrieval order: `latest` returns the newest entries first, `earliest` the oldest. Omitted keeps the executor default." + } + }, + "description": "victorialogs.query parameters. `expr` is LogsQL. Use `window` for raw logs (`limit`/`direction` allowed) or `instant`/`range` with `from_ms` for stats queries (`limit`/`direction` rejected)." + }, + "SLSQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution", + "project", + "logstore" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "description": "Maximum raw-log entries to return (1–100). Only bounds raw logs, not SQL rows or scanned data; omitted keeps the executor default. Explicit null is invalid." + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "Raw-log retrieval order: `latest` returns the newest entries first, `earliest` the oldest. Omitted keeps the executor default." + }, + "project": { + "type": "string", + "minLength": 1, + "description": "SLS project name." + }, + "logstore": { + "type": "string", + "minLength": 1, + "description": "SLS logstore name." + }, + "powersql": { + "type": "boolean", + "description": "Whether to run the query with SLS PowerSQL. Omitted keeps the executor default; explicit null is invalid." + } + }, + "description": "sls.query parameters for Alibaba Cloud SLS. `execution.kind` must be `window`." + }, + "TencentCLSQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution", + "region", + "topic_id", + "syntax" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "description": "Maximum raw-log entries to return (1–1000). Only bounds raw logs, not SQL rows or scanned data; omitted keeps the executor default. Explicit null is invalid." + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "Raw-log retrieval order: `latest` returns the newest entries first, `earliest` the oldest. Omitted keeps the executor default." + }, + "region": { + "type": "string", + "minLength": 1, + "description": "Tencent Cloud region, e.g. `ap-guangzhou`." + }, + "topic_id": { + "type": "string", + "minLength": 1, + "description": "CLS log topic ID." + }, + "syntax": { + "type": "string", + "enum": [ + "cql", + "lucene" + ], + "description": "Search syntax: `cql` or `lucene`." + } + }, + "description": "tencent_cls.query parameters for Tencent Cloud CLS. `execution.kind` must be `window`." + }, "DatasourceToolInvokeRequest": { "properties": { "account_id": { @@ -4931,12 +5288,12 @@ }, "params": { "additionalProperties": true, - "description": "Tool-specific JSON parameters; omitted means {}. Explicit null is invalid.", + "description": "Tool-specific JSON parameters; omitted means {}. Explicit null is invalid. Query tools (`.query`) use the per-datasource params schemas named in the `tool` description.", "type": "object", "x-flashduty-raw-json": true }, "tool": { - "description": "Single tool name prefixed by the datasource type, e.g. mysql.overview. Free SQL uses /monit/query/data; mysql.query and postgres.query are unsupported.", + "description": "Single tool name prefixed by the datasource type. Diagnostic tools are defined by the executing Edge (e.g. `mysql.overview`). Query tools are `.query` where `` is one of `prometheus`, `mysql`, `postgres`, `oracle`, `clickhouse`, `elasticsearch`, `loki`, `victorialogs`, `sls`, `tencent_cls`; their `params` follow `PrometheusQueryParams`, `MySQLQueryParams`, `PostgresQueryParams`, `OracleQueryParams`, `ClickHouseQueryParams`, `ElasticsearchQueryParams`, `LokiQueryParams`, `VictoriaLogsQueryParams`, `SLSQueryParams`, or `TencentCLSQueryParams` respectively.", "maxLength": 128, "minLength": 1, "type": "string" diff --git a/api-reference/monitors.openapi.zh.json b/api-reference/monitors.openapi.zh.json index f7f21efb..9a7a5c1e 100644 --- a/api-reference/monitors.openapi.zh.json +++ b/api-reference/monitors.openapi.zh.json @@ -2072,18 +2072,35 @@ }, "/monit/datasource/tools/invoke": { "post": { - "description": "对已配置的数据源执行单个确定性工具。要求集群所有当前在线可路由 Edge 会话支持 v0.71.0 基础 invoke 协议；具体工具可能需要更新实现。不提供工具目录、自动重放或 Agent/旧 diagnose 回退。请求体上限 128 KiB，完整成功响应上限 1 MiB，工具超时最多 25 秒。", + "description": "对已配置的数据源执行单个确定性诊断或查询工具。", "operationId": "monit-datasource-tools-invoke", "requestBody": { "content": { "application/json": { - "example": { - "datasource_id": 10, - "params": {}, - "tool": "mysql.overview" - }, "schema": { "$ref": "#/components/schemas/DatasourceToolInvokeRequest" + }, + "examples": { + "diagnostic": { + "value": { + "datasource_id": 10, + "params": {}, + "tool": "mysql.overview" + } + }, + "query": { + "value": { + "datasource_id": 24000, + "tool": "prometheus.query", + "params": { + "expr": "sum(rate(http_requests_total[5m]))", + "execution": { + "kind": "instant", + "to_ms": 1789000000000 + } + } + } + } } } }, @@ -2093,17 +2110,6 @@ "200": { "content": { "application/json": { - "example": { - "data": { - "data": { - "version": "8.0.36" - }, - "datasource_id": 10, - "summary": "MySQL overview", - "tool": "mysql.overview" - }, - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" - }, "schema": { "allOf": [ { @@ -2118,6 +2124,45 @@ "type": "object" } ] + }, + "examples": { + "diagnostic": { + "value": { + "data": { + "data": { + "version": "8.0.36" + }, + "datasource_id": 10, + "summary": "MySQL overview", + "tool": "mysql.overview" + }, + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + } + }, + "query": { + "value": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "datasource_id": 24000, + "tool": "prometheus.query", + "data": { + "format": "explore_result.v1", + "result": { + "kind": "samples", + "samples": [ + { + "labels": { + "__name__": "up", + "instance": "10.101.214.50:7070" + }, + "value": 1 + } + ] + } + } + } + } + } } } }, @@ -2232,7 +2277,7 @@ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **2,000 次/分钟**；**32 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n通过 `/monit/datasource/list` 获取数据源 ID。停用数据源返回 `datasource_disabled`，`alerting_enabled=false` 不阻断工具。错误使用非 2xx HTTP 状态和 `error.code`、`error.message`、`error.reason`。`tool_not_supported` 表示选中的执行端未提供该工具，不表示厂商权限不足。禁止自动切换 Edge 或回退旧 diagnose 重试。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **2,000 次/分钟**；**32 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n通过 `/monit/datasource/list` 获取数据源 ID。停用数据源返回 `datasource_disabled`，`alerting_enabled=false` 不阻断工具。错误使用非 2xx HTTP 状态和 `error.code`、`error.message`、`error.reason`。`tool_not_supported` 表示选中的执行端未提供该工具，不表示厂商权限不足。禁止自动切换 Edge 或回退旧 diagnose 重试。\n\n## 使用说明\n\n- 本入口共用两类工具：由执行端 Edge 定义的诊断工具（如 `mysql.overview`、`prometheus.metric_trends`）和命名为 `.query` 的查询工具。工具前缀必须与数据源类型一致。\n- 查询工具要求 Edge 集群支持 Explore 查询（协议里程碑 v0.68.0）；诊断工具要求 v0.71.0 基础 invoke 协议。不支持的集群返回 `edge_upgrade_required`、`mixed_edge_versions` 或 `edge_version_unknown`；禁止自动回退 `/monit/query/data` 或其他接口。\n- 查询工具的 `params` 遵循 `tool` 字段描述中按数据源列出的专属 Schema。`expr` 和 `execution` 必填。`limit`/`direction` 只约束原始日志条数与检索方向，不代表 SQL 行数或扫描量。未知扩展字段被容忍，但不参与执行也不透传。\n- 查询结果的 `data` 是完整 Explore 结果：`format` 为 `explore_result.v1`，`result.kind` 为 `samples`、`frames` 或 `logs`；日志结果保留 `applied_limit` 和 `has_more`。查询结果不合成 `summary` 或 `truncated`。\n- 请求体上限 128 KiB；两类工具的完整成功响应上限均为 10 MiB；诊断工具超时最多 25 秒。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-tools-invoke", "metadata": { "sidebarTitle": "调用数据源工具" @@ -4916,6 +4961,318 @@ }, "type": "object" }, + "DatasourceQueryExecution": { + "type": "object", + "additionalProperties": true, + "required": [ + "kind", + "to_ms" + ], + "properties": { + "kind": { + "type": "string", + "enum": [ + "instant", + "range", + "window" + ], + "description": "执行模式：`instant` 在单个时间点求值，`range` 按步长求值时间序列，`window` 在单个有界时间窗口内求值。" + }, + "from_ms": { + "type": "integer", + "format": "int64", + "description": "窗口或范围的起始时间，Unix 毫秒时间戳。`range` 和 `window` 必填；Loki 和 VictoriaLogs 的 `instant` 可选；Prometheus 的 `instant` 拒绝该字段。" + }, + "to_ms": { + "type": "integer", + "format": "int64", + "description": "查询截止时间，Unix 毫秒时间戳；`instant` 模式下为求值时间点。" + }, + "max_data_points": { + "type": "integer", + "format": "int64", + "description": "仅 `range` 且必填：最大返回点数；服务端按时间窗口计算实际步长。" + }, + "min_step_seconds": { + "type": "integer", + "format": "int64", + "description": "仅 `range`，可选：计算步长的正数下限（秒）。" + } + } + }, + "PrometheusQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "prometheus.query 参数。`expr` 为 PromQL。`execution.kind` 取 `instant` 或 `range`；`instant` 只接受 `to_ms`。" + }, + "MySQLQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "mysql.query 参数。`expr` 为单条只读 SQL。`execution.kind` 必须为 `window`。" + }, + "PostgresQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "postgres.query 参数。`expr` 为单条只读 SQL。`execution.kind` 必须为 `window`。" + }, + "OracleQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "oracle.query 参数。`expr` 为单条只读 SQL。`execution.kind` 必须为 `window`。" + }, + "ClickHouseQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "clickhouse.query 参数。`expr` 为单条只读 SQL。`execution.kind` 必须为 `window`。" + }, + "ElasticsearchQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "elasticsearch.query 参数。`expr` 为单条 SQL 语句；不支持 Elasticsearch DSL 查询。`execution.kind` 必须为 `window`。" + }, + "LokiQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "description": "返回的原始日志最大条数（1–1000）。只约束原始日志，不代表 SQL 行数或扫描量；省略时沿用执行端默认值。显式 null 非法。" + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "原始日志检索方向：`latest` 先返回最新条目，`earliest` 先返回最旧条目。省略时沿用执行端默认值。" + } + }, + "description": "loki.query 参数。`expr` 为 LogQL。`execution.kind` 取 `instant` 或 `range`；`instant` 保留完整时间上下文以便 `$__auto` 范围解析。`limit` 和 `direction` 只作用于原始日志结果。" + }, + "VictoriaLogsQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "description": "返回的原始日志最大条数（1–1000）。只约束原始日志，不代表 SQL 行数或扫描量；省略时沿用执行端默认值。显式 null 非法。" + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "原始日志检索方向：`latest` 先返回最新条目，`earliest` 先返回最旧条目。省略时沿用执行端默认值。" + } + }, + "description": "victorialogs.query 参数。`expr` 为 LogsQL。`window` 用于原始日志（允许 `limit`/`direction`）；`instant`/`range` 统计查询必须带 `from_ms`（拒绝 `limit`/`direction`）。" + }, + "SLSQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution", + "project", + "logstore" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "description": "返回的原始日志最大条数（1–100）。只约束原始日志，不代表 SQL 行数或扫描量；省略时沿用执行端默认值。显式 null 非法。" + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "原始日志检索方向：`latest` 先返回最新条目，`earliest` 先返回最旧条目。省略时沿用执行端默认值。" + }, + "project": { + "type": "string", + "minLength": 1, + "description": "SLS Project 名称。" + }, + "logstore": { + "type": "string", + "minLength": 1, + "description": "SLS Logstore 名称。" + }, + "powersql": { + "type": "boolean", + "description": "是否以 SLS PowerSQL 执行查询。省略时沿用执行端默认值；显式 null 非法。" + } + }, + "description": "阿里云 SLS 的 sls.query 参数。`execution.kind` 必须为 `window`。" + }, + "TencentCLSQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution", + "region", + "topic_id", + "syntax" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "description": "返回的原始日志最大条数（1–1000）。只约束原始日志，不代表 SQL 行数或扫描量；省略时沿用执行端默认值。显式 null 非法。" + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "原始日志检索方向：`latest` 先返回最新条目，`earliest` 先返回最旧条目。省略时沿用执行端默认值。" + }, + "region": { + "type": "string", + "minLength": 1, + "description": "腾讯云地域，如 `ap-guangzhou`。" + }, + "topic_id": { + "type": "string", + "minLength": 1, + "description": "CLS 日志主题 ID。" + }, + "syntax": { + "type": "string", + "enum": [ + "cql", + "lucene" + ], + "description": "检索语法：`cql` 或 `lucene`。" + } + }, + "description": "腾讯云 CLS 的 tencent_cls.query 参数。`execution.kind` 必须为 `window`。" + }, "DatasourceToolInvokeRequest": { "properties": { "account_id": { @@ -4931,12 +5288,12 @@ }, "params": { "additionalProperties": true, - "description": "工具专属 JSON 参数，省略时为 {}，显式 null 非法。", + "description": "工具专属 JSON 参数；省略等同于 {}。显式 null 非法。查询工具（`.query`）使用 `tool` 描述中按数据源列出的专属参数 Schema。", "type": "object", "x-flashduty-raw-json": true }, "tool": { - "description": "以数据源类型为前缀的单个工具名，如 mysql.overview。自由 SQL 使用 /monit/query/data；不支持 mysql.query 和 postgres.query。", + "description": "以数据源类型为前缀的单个工具名。诊断工具由执行端 Edge 定义（如 `mysql.overview`）。查询工具为 `.query`，`` 取 `prometheus`、`mysql`、`postgres`、`oracle`、`clickhouse`、`elasticsearch`、`loki`、`victorialogs`、`sls`、`tencent_cls` 之一；`params` 分别遵循 `PrometheusQueryParams`、`MySQLQueryParams`、`PostgresQueryParams`、`OracleQueryParams`、`ClickHouseQueryParams`、`ElasticsearchQueryParams`、`LokiQueryParams`、`VictoriaLogsQueryParams`、`SLSQueryParams`、`TencentCLSQueryParams`。", "maxLength": 128, "minLength": 1, "type": "string" diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index f49bc257..0fb1a113 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -7536,6 +7536,318 @@ ], "type": "object" }, + "DatasourceQueryExecution": { + "type": "object", + "additionalProperties": true, + "required": [ + "kind", + "to_ms" + ], + "properties": { + "kind": { + "type": "string", + "enum": [ + "instant", + "range", + "window" + ], + "description": "Execution mode: `instant` evaluates at a single timestamp, `range` evaluates a stepped series, and `window` evaluates one bounded time window." + }, + "from_ms": { + "type": "integer", + "format": "int64", + "description": "Window or range start as a Unix epoch timestamp in milliseconds. Required for `range` and `window`; optional for Loki and VictoriaLogs `instant`; rejected by Prometheus `instant`." + }, + "to_ms": { + "type": "integer", + "format": "int64", + "description": "Query end time as a Unix epoch timestamp in milliseconds; for `instant` it is the evaluation timestamp." + }, + "max_data_points": { + "type": "integer", + "format": "int64", + "description": "`range` only, required: maximum returned data points; the server computes the effective step from the window." + }, + "min_step_seconds": { + "type": "integer", + "format": "int64", + "description": "`range` only, optional: positive lower bound in seconds for the computed step." + } + } + }, + "PrometheusQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "prometheus.query parameters. `expr` is PromQL. `execution.kind` must be `instant` or `range`; `instant` accepts only `to_ms`." + }, + "MySQLQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "mysql.query parameters. `expr` is a single read-only SQL statement. `execution.kind` must be `window`." + }, + "PostgresQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "postgres.query parameters. `expr` is a single read-only SQL statement. `execution.kind` must be `window`." + }, + "OracleQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "oracle.query parameters. `expr` is a single read-only SQL statement. `execution.kind` must be `window`." + }, + "ClickHouseQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "clickhouse.query parameters. `expr` is a single read-only SQL statement. `execution.kind` must be `window`." + }, + "ElasticsearchQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "elasticsearch.query parameters. `expr` is a single SQL statement; Elasticsearch DSL queries are not supported. `execution.kind` must be `window`." + }, + "LokiQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "description": "Maximum raw-log entries to return (1–1000). Only bounds raw logs, not SQL rows or scanned data; omitted keeps the executor default. Explicit null is invalid." + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "Raw-log retrieval order: `latest` returns the newest entries first, `earliest` the oldest. Omitted keeps the executor default." + } + }, + "description": "loki.query parameters. `expr` is LogQL. `execution.kind` must be `instant` or `range`; `instant` keeps the full time context so `$__auto` ranges resolve. `limit` and `direction` only apply to raw-log results." + }, + "VictoriaLogsQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "description": "Maximum raw-log entries to return (1–1000). Only bounds raw logs, not SQL rows or scanned data; omitted keeps the executor default. Explicit null is invalid." + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "Raw-log retrieval order: `latest` returns the newest entries first, `earliest` the oldest. Omitted keeps the executor default." + } + }, + "description": "victorialogs.query parameters. `expr` is LogsQL. Use `window` for raw logs (`limit`/`direction` allowed) or `instant`/`range` with `from_ms` for stats queries (`limit`/`direction` rejected)." + }, + "SLSQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution", + "project", + "logstore" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "description": "Maximum raw-log entries to return (1–100). Only bounds raw logs, not SQL rows or scanned data; omitted keeps the executor default. Explicit null is invalid." + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "Raw-log retrieval order: `latest` returns the newest entries first, `earliest` the oldest. Omitted keeps the executor default." + }, + "project": { + "type": "string", + "minLength": 1, + "description": "SLS project name." + }, + "logstore": { + "type": "string", + "minLength": 1, + "description": "SLS logstore name." + }, + "powersql": { + "type": "boolean", + "description": "Whether to run the query with SLS PowerSQL. Omitted keeps the executor default; explicit null is invalid." + } + }, + "description": "sls.query parameters for Alibaba Cloud SLS. `execution.kind` must be `window`." + }, + "TencentCLSQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution", + "region", + "topic_id", + "syntax" + ], + "properties": { + "expr": { + "type": "string", + "description": "Query expression evaluated by the datasource; dialect depends on the datasource type." + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "description": "Maximum raw-log entries to return (1–1000). Only bounds raw logs, not SQL rows or scanned data; omitted keeps the executor default. Explicit null is invalid." + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "Raw-log retrieval order: `latest` returns the newest entries first, `earliest` the oldest. Omitted keeps the executor default." + }, + "region": { + "type": "string", + "minLength": 1, + "description": "Tencent Cloud region, e.g. `ap-guangzhou`." + }, + "topic_id": { + "type": "string", + "minLength": 1, + "description": "CLS log topic ID." + }, + "syntax": { + "type": "string", + "enum": [ + "cql", + "lucene" + ], + "description": "Search syntax: `cql` or `lucene`." + } + }, + "description": "tencent_cls.query parameters for Tencent Cloud CLS. `execution.kind` must be `window`." + }, "DatasourceToolInvokeRequest": { "properties": { "account_id": { @@ -7551,12 +7863,12 @@ }, "params": { "additionalProperties": true, - "description": "Tool-specific JSON parameters; omitted means {}. Explicit null is invalid.", + "description": "Tool-specific JSON parameters; omitted means {}. Explicit null is invalid. Query tools (`.query`) use the per-datasource params schemas named in the `tool` description.", "type": "object", "x-flashduty-raw-json": true }, "tool": { - "description": "Single tool name prefixed by the datasource type, e.g. mysql.overview. Free SQL uses /monit/query/data; mysql.query and postgres.query are unsupported.", + "description": "Single tool name prefixed by the datasource type. Diagnostic tools are defined by the executing Edge (e.g. `mysql.overview`). Query tools are `.query` where `` is one of `prometheus`, `mysql`, `postgres`, `oracle`, `clickhouse`, `elasticsearch`, `loki`, `victorialogs`, `sls`, `tencent_cls`; their `params` follow `PrometheusQueryParams`, `MySQLQueryParams`, `PostgresQueryParams`, `OracleQueryParams`, `ClickHouseQueryParams`, `ElasticsearchQueryParams`, `LokiQueryParams`, `VictoriaLogsQueryParams`, `SLSQueryParams`, or `TencentCLSQueryParams` respectively.", "maxLength": 128, "minLength": 1, "type": "string" @@ -42073,18 +42385,35 @@ }, "/monit/datasource/tools/invoke": { "post": { - "description": "Execute one deterministic tool against a configured datasource. Requires all currently online routable Edge sessions in the cluster to support the v0.71.0 base invoke protocol; individual tools may require a newer implementation. No tool catalog, automatic replay, or fallback to Agent/legacy diagnose. Request body limit 128 KiB; complete success response limit 1 MiB; tool timeout at most 25 seconds.", + "description": "Execute one deterministic diagnostic or query tool against a configured datasource.", "operationId": "monit-datasource-tools-invoke", "requestBody": { "content": { "application/json": { - "example": { - "datasource_id": 10, - "params": {}, - "tool": "mysql.overview" - }, "schema": { "$ref": "#/components/schemas/DatasourceToolInvokeRequest" + }, + "examples": { + "diagnostic": { + "value": { + "datasource_id": 10, + "params": {}, + "tool": "mysql.overview" + } + }, + "query": { + "value": { + "datasource_id": 24000, + "tool": "prometheus.query", + "params": { + "expr": "sum(rate(http_requests_total[5m]))", + "execution": { + "kind": "instant", + "to_ms": 1789000000000 + } + } + } + } } } }, @@ -42094,17 +42423,6 @@ "200": { "content": { "application/json": { - "example": { - "data": { - "data": { - "version": "8.0.36" - }, - "datasource_id": 10, - "summary": "MySQL overview", - "tool": "mysql.overview" - }, - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" - }, "schema": { "allOf": [ { @@ -42119,6 +42437,45 @@ "type": "object" } ] + }, + "examples": { + "diagnostic": { + "value": { + "data": { + "data": { + "version": "8.0.36" + }, + "datasource_id": 10, + "summary": "MySQL overview", + "tool": "mysql.overview" + }, + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + } + }, + "query": { + "value": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "datasource_id": 24000, + "tool": "prometheus.query", + "data": { + "format": "explore_result.v1", + "result": { + "kind": "samples", + "samples": [ + { + "labels": { + "__name__": "up", + "instance": "10.101.214.50:7070" + }, + "value": 1 + } + ] + } + } + } + } + } } } }, @@ -42233,7 +42590,7 @@ "Monitors/Data sources" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **2,000 requests/minute**; **32 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\nUse datasource IDs from `/monit/datasource/list`. Disabled datasources return `datasource_disabled`; `alerting_enabled=false` does not block tools. Errors use non-2xx HTTP status and `error.code`, `error.message`, `error.reason`. `tool_not_supported` indicates the selected executor does not provide this tool; it is not a vendor permission error. Never retry through another Edge or the legacy diagnose endpoint automatically.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **2,000 requests/minute**; **32 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\nUse datasource IDs from `/monit/datasource/list`. Disabled datasources return `datasource_disabled`; `alerting_enabled=false` does not block tools. Errors use non-2xx HTTP status and `error.code`, `error.message`, `error.reason`. `tool_not_supported` indicates the selected executor does not provide this tool; it is not a vendor permission error. Never retry through another Edge or the legacy diagnose endpoint automatically.\n\n## Usage\n\n- Two tool families share this entry: diagnostic tools defined by the executing Edge (e.g. `mysql.overview`, `prometheus.metric_trends`) and query tools named `.query`. The tool prefix must match the datasource type.\n- Query tools require the Edge cluster to support Explore queries (protocol milestone v0.68.0); diagnostic tools require the v0.71.0 base invoke protocol. Unsupported clusters fail with `edge_upgrade_required`, `mixed_edge_versions`, or `edge_version_unknown`; never fall back to `/monit/query/data` or another endpoint automatically.\n- For query tools, `params` follows the per-datasource schema named in the `tool` field description. `expr` and `execution` are always required. `limit`/`direction` only bound raw-log retrieval, never SQL rows or scanned data. Unknown extension fields are tolerated but never executed or forwarded.\n- Query `data` is the complete Explore result: `format` is `explore_result.v1` and `result.kind` is `samples`, `frames`, or `logs`; log results keep `applied_limit` and `has_more`. Query results never synthesize `summary` or `truncated`.\n- Request body limit 128 KiB; complete success response limit 10 MiB for both families; diagnostic tool timeout at most 25 seconds.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-tools-invoke", "metadata": { "sidebarTitle": "Invoke datasource tool" diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 338f1325..10e38aa0 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -7536,6 +7536,318 @@ ], "type": "object" }, + "DatasourceQueryExecution": { + "type": "object", + "additionalProperties": true, + "required": [ + "kind", + "to_ms" + ], + "properties": { + "kind": { + "type": "string", + "enum": [ + "instant", + "range", + "window" + ], + "description": "执行模式：`instant` 在单个时间点求值，`range` 按步长求值时间序列，`window` 在单个有界时间窗口内求值。" + }, + "from_ms": { + "type": "integer", + "format": "int64", + "description": "窗口或范围的起始时间，Unix 毫秒时间戳。`range` 和 `window` 必填；Loki 和 VictoriaLogs 的 `instant` 可选；Prometheus 的 `instant` 拒绝该字段。" + }, + "to_ms": { + "type": "integer", + "format": "int64", + "description": "查询截止时间，Unix 毫秒时间戳；`instant` 模式下为求值时间点。" + }, + "max_data_points": { + "type": "integer", + "format": "int64", + "description": "仅 `range` 且必填：最大返回点数；服务端按时间窗口计算实际步长。" + }, + "min_step_seconds": { + "type": "integer", + "format": "int64", + "description": "仅 `range`，可选：计算步长的正数下限（秒）。" + } + } + }, + "PrometheusQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "prometheus.query 参数。`expr` 为 PromQL。`execution.kind` 取 `instant` 或 `range`；`instant` 只接受 `to_ms`。" + }, + "MySQLQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "mysql.query 参数。`expr` 为单条只读 SQL。`execution.kind` 必须为 `window`。" + }, + "PostgresQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "postgres.query 参数。`expr` 为单条只读 SQL。`execution.kind` 必须为 `window`。" + }, + "OracleQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "oracle.query 参数。`expr` 为单条只读 SQL。`execution.kind` 必须为 `window`。" + }, + "ClickHouseQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "clickhouse.query 参数。`expr` 为单条只读 SQL。`execution.kind` 必须为 `window`。" + }, + "ElasticsearchQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + } + }, + "description": "elasticsearch.query 参数。`expr` 为单条 SQL 语句；不支持 Elasticsearch DSL 查询。`execution.kind` 必须为 `window`。" + }, + "LokiQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "description": "返回的原始日志最大条数（1–1000）。只约束原始日志，不代表 SQL 行数或扫描量；省略时沿用执行端默认值。显式 null 非法。" + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "原始日志检索方向：`latest` 先返回最新条目，`earliest` 先返回最旧条目。省略时沿用执行端默认值。" + } + }, + "description": "loki.query 参数。`expr` 为 LogQL。`execution.kind` 取 `instant` 或 `range`；`instant` 保留完整时间上下文以便 `$__auto` 范围解析。`limit` 和 `direction` 只作用于原始日志结果。" + }, + "VictoriaLogsQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "description": "返回的原始日志最大条数（1–1000）。只约束原始日志，不代表 SQL 行数或扫描量；省略时沿用执行端默认值。显式 null 非法。" + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "原始日志检索方向：`latest` 先返回最新条目，`earliest` 先返回最旧条目。省略时沿用执行端默认值。" + } + }, + "description": "victorialogs.query 参数。`expr` 为 LogsQL。`window` 用于原始日志（允许 `limit`/`direction`）；`instant`/`range` 统计查询必须带 `from_ms`（拒绝 `limit`/`direction`）。" + }, + "SLSQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution", + "project", + "logstore" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "description": "返回的原始日志最大条数（1–100）。只约束原始日志，不代表 SQL 行数或扫描量；省略时沿用执行端默认值。显式 null 非法。" + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "原始日志检索方向：`latest` 先返回最新条目，`earliest` 先返回最旧条目。省略时沿用执行端默认值。" + }, + "project": { + "type": "string", + "minLength": 1, + "description": "SLS Project 名称。" + }, + "logstore": { + "type": "string", + "minLength": 1, + "description": "SLS Logstore 名称。" + }, + "powersql": { + "type": "boolean", + "description": "是否以 SLS PowerSQL 执行查询。省略时沿用执行端默认值；显式 null 非法。" + } + }, + "description": "阿里云 SLS 的 sls.query 参数。`execution.kind` 必须为 `window`。" + }, + "TencentCLSQueryParams": { + "type": "object", + "additionalProperties": true, + "required": [ + "expr", + "execution", + "region", + "topic_id", + "syntax" + ], + "properties": { + "expr": { + "type": "string", + "description": "由数据源求值的查询表达式；方言取决于数据源类型。" + }, + "execution": { + "$ref": "#/components/schemas/DatasourceQueryExecution" + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "description": "返回的原始日志最大条数（1–1000）。只约束原始日志，不代表 SQL 行数或扫描量；省略时沿用执行端默认值。显式 null 非法。" + }, + "direction": { + "type": "string", + "enum": [ + "latest", + "earliest" + ], + "description": "原始日志检索方向：`latest` 先返回最新条目，`earliest` 先返回最旧条目。省略时沿用执行端默认值。" + }, + "region": { + "type": "string", + "minLength": 1, + "description": "腾讯云地域，如 `ap-guangzhou`。" + }, + "topic_id": { + "type": "string", + "minLength": 1, + "description": "CLS 日志主题 ID。" + }, + "syntax": { + "type": "string", + "enum": [ + "cql", + "lucene" + ], + "description": "检索语法：`cql` 或 `lucene`。" + } + }, + "description": "腾讯云 CLS 的 tencent_cls.query 参数。`execution.kind` 必须为 `window`。" + }, "DatasourceToolInvokeRequest": { "properties": { "account_id": { @@ -7551,12 +7863,12 @@ }, "params": { "additionalProperties": true, - "description": "工具专属 JSON 参数，省略时为 {}，显式 null 非法。", + "description": "工具专属 JSON 参数；省略等同于 {}。显式 null 非法。查询工具（`.query`）使用 `tool` 描述中按数据源列出的专属参数 Schema。", "type": "object", "x-flashduty-raw-json": true }, "tool": { - "description": "以数据源类型为前缀的单个工具名，如 mysql.overview。自由 SQL 使用 /monit/query/data；不支持 mysql.query 和 postgres.query。", + "description": "以数据源类型为前缀的单个工具名。诊断工具由执行端 Edge 定义（如 `mysql.overview`）。查询工具为 `.query`，`` 取 `prometheus`、`mysql`、`postgres`、`oracle`、`clickhouse`、`elasticsearch`、`loki`、`victorialogs`、`sls`、`tencent_cls` 之一；`params` 分别遵循 `PrometheusQueryParams`、`MySQLQueryParams`、`PostgresQueryParams`、`OracleQueryParams`、`ClickHouseQueryParams`、`ElasticsearchQueryParams`、`LokiQueryParams`、`VictoriaLogsQueryParams`、`SLSQueryParams`、`TencentCLSQueryParams`。", "maxLength": 128, "minLength": 1, "type": "string" @@ -42073,18 +42385,35 @@ }, "/monit/datasource/tools/invoke": { "post": { - "description": "对已配置的数据源执行单个确定性工具。要求集群所有当前在线可路由 Edge 会话支持 v0.71.0 基础 invoke 协议；具体工具可能需要更新实现。不提供工具目录、自动重放或 Agent/旧 diagnose 回退。请求体上限 128 KiB，完整成功响应上限 1 MiB，工具超时最多 25 秒。", + "description": "对已配置的数据源执行单个确定性诊断或查询工具。", "operationId": "monit-datasource-tools-invoke", "requestBody": { "content": { "application/json": { - "example": { - "datasource_id": 10, - "params": {}, - "tool": "mysql.overview" - }, "schema": { "$ref": "#/components/schemas/DatasourceToolInvokeRequest" + }, + "examples": { + "diagnostic": { + "value": { + "datasource_id": 10, + "params": {}, + "tool": "mysql.overview" + } + }, + "query": { + "value": { + "datasource_id": 24000, + "tool": "prometheus.query", + "params": { + "expr": "sum(rate(http_requests_total[5m]))", + "execution": { + "kind": "instant", + "to_ms": 1789000000000 + } + } + } + } } } }, @@ -42094,17 +42423,6 @@ "200": { "content": { "application/json": { - "example": { - "data": { - "data": { - "version": "8.0.36" - }, - "datasource_id": 10, - "summary": "MySQL overview", - "tool": "mysql.overview" - }, - "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" - }, "schema": { "allOf": [ { @@ -42119,6 +42437,45 @@ "type": "object" } ] + }, + "examples": { + "diagnostic": { + "value": { + "data": { + "data": { + "version": "8.0.36" + }, + "datasource_id": 10, + "summary": "MySQL overview", + "tool": "mysql.overview" + }, + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4" + } + }, + "query": { + "value": { + "request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4", + "data": { + "datasource_id": 24000, + "tool": "prometheus.query", + "data": { + "format": "explore_result.v1", + "result": { + "kind": "samples", + "samples": [ + { + "labels": { + "__name__": "up", + "instance": "10.101.214.50:7070" + }, + "value": 1 + } + ] + } + } + } + } + } } } }, @@ -42233,7 +42590,7 @@ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **2,000 次/分钟**；**32 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n通过 `/monit/datasource/list` 获取数据源 ID。停用数据源返回 `datasource_disabled`，`alerting_enabled=false` 不阻断工具。错误使用非 2xx HTTP 状态和 `error.code`、`error.message`、`error.reason`。`tool_not_supported` 表示选中的执行端未提供该工具，不表示厂商权限不足。禁止自动切换 Edge 或回退旧 diagnose 重试。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **2,000 次/分钟**；**32 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n通过 `/monit/datasource/list` 获取数据源 ID。停用数据源返回 `datasource_disabled`，`alerting_enabled=false` 不阻断工具。错误使用非 2xx HTTP 状态和 `error.code`、`error.message`、`error.reason`。`tool_not_supported` 表示选中的执行端未提供该工具，不表示厂商权限不足。禁止自动切换 Edge 或回退旧 diagnose 重试。\n\n## 使用说明\n\n- 本入口共用两类工具：由执行端 Edge 定义的诊断工具（如 `mysql.overview`、`prometheus.metric_trends`）和命名为 `.query` 的查询工具。工具前缀必须与数据源类型一致。\n- 查询工具要求 Edge 集群支持 Explore 查询（协议里程碑 v0.68.0）；诊断工具要求 v0.71.0 基础 invoke 协议。不支持的集群返回 `edge_upgrade_required`、`mixed_edge_versions` 或 `edge_version_unknown`；禁止自动回退 `/monit/query/data` 或其他接口。\n- 查询工具的 `params` 遵循 `tool` 字段描述中按数据源列出的专属 Schema。`expr` 和 `execution` 必填。`limit`/`direction` 只约束原始日志条数与检索方向，不代表 SQL 行数或扫描量。未知扩展字段被容忍，但不参与执行也不透传。\n- 查询结果的 `data` 是完整 Explore 结果：`format` 为 `explore_result.v1`，`result.kind` 为 `samples`、`frames` 或 `logs`；日志结果保留 `applied_limit` 和 `has_more`。查询结果不合成 `summary` 或 `truncated`。\n- 请求体上限 128 KiB；两类工具的完整成功响应上限均为 10 MiB；诊断工具超时最多 25 秒。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-tools-invoke", "metadata": { "sidebarTitle": "调用数据源工具" diff --git a/en/developer/cli.mdx b/en/developer/cli.mdx index 5cf0cbee..9e07f353 100644 --- a/en/developer/cli.mdx +++ b/en/developer/cli.mdx @@ -503,9 +503,9 @@ flashduty monit datasource-tools-invoke --tool 'redis_node.slowl Semantics and limits: -- **No tool catalog, no auto-replay, no fallback**: one call runs exactly one named tool; fill parameters according to the datasource tool's contract rather than guessing from the command list. The `mysql.query` / `postgres.query` tools have been removed — free SQL stays under `monit-query data`. +- **No tool catalog, no auto-replay, no fallback**: one call runs exactly one named tool; fill parameters according to the datasource tool's contract rather than guessing from the command list. Alongside diagnostic tools, the entry also supports `.query` query tools (`prometheus`, `mysql`, `postgres`, `oracle`, `clickhouse`, `elasticsearch`, `loki`, `victorialogs`, `sls`, `tencent_cls`); the `monit-query data` entry stays unchanged. - Requires **all** currently online routable Edge sessions in the cluster to support the v0.71.0 base invoke protocol (individual tools may require a newer implementation); normal datasource queries retain their existing version compatibility. -- Request body limit 128 KiB; complete success response limit 1 MiB; tool timeout at most 25 seconds. +- Request body limit 128 KiB; complete success response limit 10 MiB; tool timeout at most 25 seconds. - The datasource must have `enabled=true`; `alerting_enabled=false` does not block diagnostics. - Response: `data` (tool-specific JSON evidence, preserved without conversion, never null, no legacy diagnose envelope), `tool`, `datasource_id`, optional `summary`, and a `truncated` object (with `reason`; its presence indicates truncation). diff --git a/en/developer/go-sdk.mdx b/en/developer/go-sdk.mdx index 9b0031d8..48db2120 100644 --- a/en/developer/go-sdk.mdx +++ b/en/developer/go-sdk.mdx @@ -186,7 +186,7 @@ Endpoints are grouped by service and hang off the client: the call convention is `client.Diagnostics.QueryData` runs a synchronous query via `POST /monit/query/data` and returns a stable `query_result.v1` structured result (`result.kind` is one of `frames`, `records`, or `samples`). This API requires monit-edge v0.65.0 or later. For log-pattern and metric-trend analysis, use `client.DataSources.ToolsInvoke` with `prometheus.metric_trends`, `loki.log_patterns`, or `victorialogs.log_patterns`. -`client.DataSources.ToolsInvoke` (`POST /monit/datasource/tools/invoke`, `monit-datasource-tools-invoke`) executes one deterministic tool against a configured datasource: `tool` is a single tool name prefixed by the datasource type (e.g. `mysql.overview`), and `params` is the tool-specific JSON parameters (omitted means `{}`; an explicit `null` is invalid). Free SQL goes through `/monit/query/data`; `mysql.query` and `postgres.query` are unsupported. It requires all currently online routable Edge sessions in the cluster to support the v0.71.0 base invoke protocol (individual tools may require a newer implementation), and there is no tool catalog, no automatic replay, and no fallback to legacy diagnose. The request body limit is 128 KiB, the complete success response limit is 1 MiB, and the tool timeout is at most 25 seconds; the response is a `DatasourceToolResult` (`data` is tool-specific JSON, never null, `summary` is optional, and a `truncated` object with `reason` indicates truncation). +`client.DataSources.ToolsInvoke` (`POST /monit/datasource/tools/invoke`, `monit-datasource-tools-invoke`) executes one deterministic tool against a configured datasource: `tool` is a single tool name prefixed by the datasource type (e.g. `mysql.overview`), and `params` is the tool-specific JSON parameters (omitted means `{}`; an explicit `null` is invalid). Alongside diagnostic tools, the entry supports `.query` query tools (`prometheus`, `mysql`, `postgres`, `oracle`, `clickhouse`, `elasticsearch`, `loki`, `victorialogs`, `sls`, `tencent_cls`); the `/monit/query/data` entry stays unchanged. It requires all currently online routable Edge sessions in the cluster to support the v0.71.0 base invoke protocol (individual tools may require a newer implementation), and there is no tool catalog, no automatic replay, and no fallback to legacy diagnose. The request body limit is 128 KiB, the complete success response limit is 10 MiB, and the tool timeout is at most 25 seconds; the response is a `DatasourceToolResult` (`data` is tool-specific JSON, never null, `summary` is optional, and a `truncated` object with `reason` indicates truncation). For `client.DataSources`, the `payload` selects a type-specific configuration block by `type_ident`. Fifteen `type_ident` values are allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, plus the new diagnostic-only types `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, and `kafka` — diagnostic-only types always have `alerting_enabled` false (which does not block non-alerting queries or tools) and reject true. Connection address rules: Redis/MongoDB diagnostic types take a single `host:port` (bracket IPv6), with no URI, userinfo, or query; `kafka` takes 1–32 unique comma-separated `host:port` bootstrap addresses (at most 4096 characters after normalization, and the payload has no broker list); for `mongodb_mongod` / `mongodb_mongos` the configuration block's `auth_source` defaults to `admin`, username and password must be configured together, and client certificates are unsupported; the Redis node configuration's `database` defaults to 0. Sensitive fields such as the diagnostic types' `password` and Kafka's `tls_key` support `${env:NAME}` references: literal values are omitted from responses (only `${env:...}` references are echoed back), omitting the fields on update preserves the stored values, and explicitly sending an empty string clears them. diff --git a/zh/developer/cli.mdx b/zh/developer/cli.mdx index 618831aa..0d21bdb6 100644 --- a/zh/developer/cli.mdx +++ b/zh/developer/cli.mdx @@ -503,9 +503,9 @@ flashduty monit datasource-tools-invoke --tool 'redis_node.slowl 语义与限制： -- **无工具目录、无自动重试、无回退**：一次调用只执行一个命名工具，参数需按各数据源工具约定填写，不要从命令行列表猜测。`mysql.query` / `postgres.query` 工具已移除——自由 SQL 请用 `monit-query data`。 +- **无工具目录、无自动重试、无回退**：一次调用只执行一个命名工具，参数需按各数据源工具约定填写，不要从命令行列表猜测。除诊断工具外，入口还支持 `.query` 查询工具（`prometheus`、`mysql`、`postgres`、`oracle`、`clickhouse`、`elasticsearch`、`loki`、`victorialogs`、`sls`、`tencent_cls`），`monit-query data` 入口保持不变。 - 要求所选集群内**全部**当前在线可路由的 Edge 会话支持 v0.71.0 基础调用协议（个别工具可能要求更新的实现）；普通数据源查询不受此版本限制。 -- 请求体 ≤128 KiB；完整成功响应 ≤1 MiB；工具超时 ≤25 秒。 +- 请求体 ≤128 KiB；完整成功响应 ≤10 MiB；工具超时 ≤25 秒。 - 需要数据源 `enabled=true`；`alerting_enabled=false` 不阻塞诊断。 - 返回值：`data`（工具特定的 JSON 证据，原样保留、永不为 null，不含旧 diagnose 信封）、`tool`、`datasource_id`、可选 `summary`，以及 `truncated` 对象（含 `reason`，存在即表示结果被截断）。 diff --git a/zh/developer/go-sdk.mdx b/zh/developer/go-sdk.mdx index 4b89d647..695db97f 100644 --- a/zh/developer/go-sdk.mdx +++ b/zh/developer/go-sdk.mdx @@ -186,7 +186,7 @@ client, err := flashduty.NewClient("YOUR_APP_KEY", `client.Diagnostics.QueryData` 通过 `POST /monit/query/data` 执行同步查询，返回稳定的 `query_result.v1` 结构化结果（`result.kind` 为 `frames` / `records` / `samples` 之一），要求 monit-edge v0.65.0 及以上版本。日志模式和指标趋势分析统一使用 `client.DataSources.ToolsInvoke`，工具名称为 `prometheus.metric_trends`、`loki.log_patterns` 或 `victorialogs.log_patterns`。 -`client.DataSources.ToolsInvoke`（`POST /monit/datasource/tools/invoke`，`monit-datasource-tools-invoke`）在某个已配置数据源上执行一个确定性工具：`tool` 名称由数据源类型前缀修饰（如 `mysql.overview`），`params` 为工具专属 JSON 参数（省略视为 `{}`，显式 `null` 非法）；自由 SQL 请走 `/monit/query/data`，`mysql.query` 与 `postgres.query` 不受支持。该接口要求集群中所有在线可路由的 Edge 会话都支持 v0.71.0 基础调用协议（单个工具可能要求更新的实现），无工具目录、无自动重放、也不会回退到旧版 diagnose。请求体上限 128 KiB，完整成功响应上限 1 MiB，单工具超时至多 25 秒；响应为 `DatasourceToolResult`（`data` 为工具专属 JSON、永不为 null，`summary` 可选，出现 `truncated` 时其 `reason` 说明截断原因）。 +`client.DataSources.ToolsInvoke`（`POST /monit/datasource/tools/invoke`，`monit-datasource-tools-invoke`）在某个已配置数据源上执行一个确定性工具：`tool` 名称由数据源类型前缀修饰（如 `mysql.overview`），`params` 为工具专属 JSON 参数（省略视为 `{}`，显式 `null` 非法）；除诊断工具外，入口支持 `.query` 查询工具（`prometheus`、`mysql`、`postgres`、`oracle`、`clickhouse`、`elasticsearch`、`loki`、`victorialogs`、`sls`、`tencent_cls`），`/monit/query/data` 入口保持不变。该接口要求集群中所有在线可路由的 Edge 会话都支持 v0.71.0 基础调用协议（单个工具可能要求更新的实现），无工具目录、无自动重放、也不会回退到旧版 diagnose。请求体上限 128 KiB，完整成功响应上限 10 MiB，单工具超时至多 25 秒；响应为 `DatasourceToolResult`（`data` 为工具专属 JSON、永不为 null，`summary` 可选，出现 `truncated` 时其 `reason` 说明截断原因）。 `client.DataSources` 的 `payload` 按 `type_ident` 选择类型专属配置块。当前允许的 `type_ident` 共 15 种：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`，以及新增的诊断专用类型 `redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka`——诊断专用类型的 `alerting_enabled` 恒为 false（不阻止非告警查询与工具调用），且拒绝传 true。连接地址规则：Redis/MongoDB 诊断类型为单个 `host:port`（IPv6 需加方括号），不接受 URI、userinfo 或 query；`kafka` 为 1–32 个以逗号分隔、互不重复的 `host:port` bootstrap 地址（规范化后至多 4096 字符，`payload` 中不再有 broker 列表）；`mongodb_mongod` / `mongodb_mongos` 的配置块中 `auth_source` 默认为 `admin`，用户名与密码必须成对配置，不支持客户端证书；Redis 节点配置的 `database` 默认为 0。诊断类型的 `password` 与 Kafka 的 `tls_key` 等敏感字段支持 `${env:NAME}` 引用：响应中字面值会被省略（仅当存储值本身就是 `${env:...}` 引用时才回显），更新时省略这些字段即保留原值，显式传空字符串则清除。 From c663e0d201f6e730d2c6e8353b2557be7dabf726 Mon Sep 17 00:00:00 2001 From: flashduty-bot Date: Thu, 10 Sep 2026 11:12:59 +0800 Subject: [PATCH 2/3] docs(monit): document the unified monit-query tool command --- en/developer/cli.mdx | 27 ++++++++++++--------------- zh/developer/cli.mdx | 27 ++++++++++++--------------- 2 files changed, 24 insertions(+), 30 deletions(-) diff --git a/en/developer/cli.mdx b/en/developer/cli.mdx index 9e07f353..9e8502f6 100644 --- a/en/developer/cli.mdx +++ b/en/developer/cli.mdx @@ -462,31 +462,28 @@ flashduty session export --include-subagents > session.ndjson | `--include-subagents` | After each `subagent_dispatch`, recursively inline that subagent's own full event stream | -### monit-query — Monitoring datasource queries +### monit-query — Unified datasource tool invocation -Query monitoring back-end datasources directly, bypassing the alert-rule layer. The `data` subcommand supports 9 datasource types (Prometheus, VictoriaLogs, Loki, MySQL, SLS, Elasticsearch, PostgreSQL, Oracle, ClickHouse). For metric trends and log patterns, use the named tools of `monit datasource-tools-invoke` below. +`monit-query` executes **a single named tool** against a configured datasource — the unified entry for both query tools (`.query`, covering `prometheus`, `mysql`, `postgres`, `oracle`, `clickhouse`, `elasticsearch`, `loki`, `victorialogs`, `sls`, `tencent_cls`) and diagnostic tools (e.g. `mysql.overview`, `redis_node.slowlog`), bypassing the alert-rule layer. The legacy `monit-query data` subcommand is retired. Get the datasource ID from the `id` field of `monit datasource-list`: ```bash -flashduty monit-query data [flags] # Structured datasource query +flashduty monit datasource-list --type prometheus --json | jq '.[] | {id, name, type_ident, address}' +flashduty monit-query --tool 'prometheus.query' \ + --params '{"expr":"sum(rate(http_requests_total[5m]))","execution":{"kind":"instant","to_ms":1789000000000}}' +flashduty monit-query --tool 'redis_node.slowlog' --params '{}' ``` -Common flags for `data`: - | Flag | Description | |------|-------------| -| `--ds-type` | Datasource type (required): `prometheus`, `victorialogs`, `loki`, `mysql`, `sls`, `elasticsearch`, `postgres`, `oracle`, `clickhouse` | -| `--ds-name` | Datasource name as configured in the console (required) | -| `--expr` | Query expression (required) | -| `--delay-seconds` | Look-back offset in seconds for point-in-time queries (default `0`) | -| `--args KEY=VALUE` | Additional arguments, repeatable (values must be strings). In raw mode (`loki` / `victorialogs`), `.start` and `.end` accept a relative duration (`15m`), `now`, a date/RFC3339 timestamp, or unix seconds/milliseconds; the CLI normalizes them to the unix-seconds form the datasource requires | - -`data` returns a stable `query_result.v1` structured result: `format` is always `query_result.v1`, and `result.kind` is one of `frames` (typed table/time-series frames), `records` (schema-flexible records, may contain nested JSON or null), or `samples` (instant samples with complete label sets) — results are no longer flattened into the legacy rows shape. +| `` | Datasource ID (positional, required, from `monit datasource-list`, min 1) | +| `--tool` | Tool name (required), prefixed by the datasource type, e.g. `prometheus.query`, `mysql.overview`, `redis_node.slowlog`; 1–128 chars | +| `--params` | Tool parameters JSON (may be omitted, meaning `{}`; pass `-` to read a larger payload from standard input; an explicit `null` is invalid) | -`rows` requires `--ds-type`, `--ds-name`, and `--expr` (query expression). Use `--args KEY=VALUE` (repeatable) for parameterized queries. **`rows` is deprecated** — use `monit-query data` instead. In raw mode (`loki` / `victorialogs`), `rows` accepts time-window arguments `--args .start=` and `--args .end=` as a relative duration, `now`, date/RFC3339, or Unix seconds or milliseconds; the CLI normalizes them to the unix-seconds form the datasource requires. +Query tools return a complete `explore_result.v1` structured result: `format` is always `explore_result.v1`, and `result.kind` is one of `samples` (instant samples with complete label sets), `frames` (typed table/time-series frames), or `logs` (raw logs with `applied_limit` and `has_more`). For the diagnostic tool response shape, see `monit datasource-tools-invoke` below. ### monit datasource-tools-invoke — Datasource diagnostics -`monit datasource-tools-invoke` executes **one deterministic read-only tool** against a configured datasource — the current path for structured datasource diagnostics (replacing `monit-query diagnose`). Get the datasource ID from the `id` field of `monit datasource-list`: +`monit datasource-tools-invoke` executes **one deterministic read-only tool** against a configured datasource — the current path for structured datasource diagnostics (replacing `monit-query diagnose`). It is equivalent to the `monit-query` command above, which is the recommended path. Get the datasource ID from the `id` field of `monit datasource-list`: ```bash flashduty monit datasource-list --type redis_node --json | jq '.[] | {id, name, type_ident, address}' @@ -503,7 +500,7 @@ flashduty monit datasource-tools-invoke --tool 'redis_node.slowl Semantics and limits: -- **No tool catalog, no auto-replay, no fallback**: one call runs exactly one named tool; fill parameters according to the datasource tool's contract rather than guessing from the command list. Alongside diagnostic tools, the entry also supports `.query` query tools (`prometheus`, `mysql`, `postgres`, `oracle`, `clickhouse`, `elasticsearch`, `loki`, `victorialogs`, `sls`, `tencent_cls`); the `monit-query data` entry stays unchanged. +- **No tool catalog, no auto-replay, no fallback**: one call runs exactly one named tool; fill parameters according to the datasource tool's contract rather than guessing from the command list. Alongside diagnostic tools, the entry also supports `.query` query tools (`prometheus`, `mysql`, `postgres`, `oracle`, `clickhouse`, `elasticsearch`, `loki`, `victorialogs`, `sls`, `tencent_cls`). - Requires **all** currently online routable Edge sessions in the cluster to support the v0.71.0 base invoke protocol (individual tools may require a newer implementation); normal datasource queries retain their existing version compatibility. - Request body limit 128 KiB; complete success response limit 10 MiB; tool timeout at most 25 seconds. - The datasource must have `enabled=true`; `alerting_enabled=false` does not block diagnostics. diff --git a/zh/developer/cli.mdx b/zh/developer/cli.mdx index 0d21bdb6..54b9ce84 100644 --- a/zh/developer/cli.mdx +++ b/zh/developer/cli.mdx @@ -462,31 +462,28 @@ flashduty session export --include-subagents > session.ndjson | `--include-subagents` | 在每条 `subagent_dispatch` 之后递归内联该子智能体自身的完整事件流 | -### monit-query — 监控数据源查询 +### monit-query — 监控数据源统一工具调用 -直接查询监控后端数据源，无需经过告警规则层。`data` 子命令支持 9 种数据源类型（Prometheus、VictoriaLogs、Loki、MySQL、SLS、Elasticsearch、PostgreSQL、Oracle、ClickHouse）。指标趋势和日志模式分析使用下文的 `monit datasource-tools-invoke` 命名工具。 +`monit-query` 对已配置的数据源执行**单个命名工具**，是查询与诊断的统一入口：查询工具（`.query`，覆盖 `prometheus`、`mysql`、`postgres`、`oracle`、`clickhouse`、`elasticsearch`、`loki`、`victorialogs`、`sls`、`tencent_cls`）与诊断工具（如 `mysql.overview`、`redis_node.slowlog`）都走它，无需经过告警规则层。旧 `monit-query data` 子命令已退役。数据源 ID 从 `monit datasource-list` 的 `id` 字段获取： ```bash -flashduty monit-query data [flags] # 结构化数据源查询 +flashduty monit datasource-list --type prometheus --json | jq '.[] | {id, name, type_ident, address}' +flashduty monit-query --tool 'prometheus.query' \ + --params '{"expr":"sum(rate(http_requests_total[5m]))","execution":{"kind":"instant","to_ms":1789000000000}}' +flashduty monit-query --tool 'redis_node.slowlog' --params '{}' ``` -`data` 常用参数： - | 参数 | 说明 | |------|------| -| `--ds-type` | 数据源类型（必填）：`prometheus`、`victorialogs`、`loki`、`mysql`、`sls`、`elasticsearch`、`postgres`、`oracle`、`clickhouse` | -| `--ds-name` | 数据源名称（必填，与控制台配置一致） | -| `--expr` | 查询表达式（必填） | -| `--delay-seconds` | 查询时间点的回溯偏移秒数，用于点对点查询（默认 `0`） | -| `--args KEY=VALUE` | 附加参数，可重复（值须为字符串）。`loki` / `victorialogs` 原始模式下，`.start` 与 `.end` 接受相对时长（`15m`）、`now`、日期/RFC3339 时间戳或 Unix 秒/毫秒，CLI 会统一归一化为数据源要求的 Unix 秒 | - -`data` 返回稳定的 `query_result.v1` 结构化结果：`format` 固定为 `query_result.v1`，`result.kind` 为 `frames`（类型化表格/时序帧）、`records`（字段灵活的记录，可含嵌套 JSON 或 null）或 `samples`（带完整标签集的即时样本）三者之一，不再把结果强制压平为旧版行结构。 +| `` | 数据源 ID（位置参数，必填，来自 `monit datasource-list`，最小 1） | +| `--tool` | 工具名（必填），以数据源类型为前缀，如 `prometheus.query`、`mysql.overview`、`redis_node.slowlog`；1–128 字符 | +| `--params` | 工具参数 JSON（可省略，省略即 `{}`；参数较长时传 `-` 从标准输入读取；显式 `null` 不合法） | -`rows` 常用参数：`--ds-type`、`--ds-name`（均必填）、`--expr`（查询表达式，必填）、`--args KEY=VALUE`（可重复）。**`rows` 已弃用**，请改用 `monit-query data`。`rows` 原始模式（`loki` / `victorialogs`）可通过 `--args .start=` 与 `--args .end=` 指定时间窗口，支持相对时长、`now`、日期/RFC3339、Unix 秒或毫秒，CLI 会统一归一化为数据源要求的 Unix 秒。 +查询工具返回完整的 `explore_result.v1` 结构化结果：`format` 固定为 `explore_result.v1`，`result.kind` 为 `samples`（带完整标签集的即时样本）、`frames`（类型化表格/时序帧）或 `logs`（原始日志，含 `applied_limit` 与 `has_more`）三者之一。诊断工具的返回结构见下文 `monit datasource-tools-invoke`。 ### monit datasource-tools-invoke — 数据源诊断工具 -`monit datasource-tools-invoke` 对已配置的数据源执行**一次确定性的只读工具调用**，是结构化数据源诊断的现行路径（取代 `monit-query diagnose`）。数据源 ID 从 `monit datasource-list` 的 `id` 字段获取： +`monit datasource-tools-invoke` 对已配置的数据源执行**一次确定性的只读工具调用**，是结构化数据源诊断的现行路径（取代 `monit-query diagnose`），与上文 `monit-query` 命令等价，`monit-query` 为推荐路径。数据源 ID 从 `monit datasource-list` 的 `id` 字段获取： ```bash flashduty monit datasource-list --type redis_node --json | jq '.[] | {id, name, type_ident, address}' @@ -503,7 +500,7 @@ flashduty monit datasource-tools-invoke --tool 'redis_node.slowl 语义与限制： -- **无工具目录、无自动重试、无回退**：一次调用只执行一个命名工具，参数需按各数据源工具约定填写，不要从命令行列表猜测。除诊断工具外，入口还支持 `.query` 查询工具（`prometheus`、`mysql`、`postgres`、`oracle`、`clickhouse`、`elasticsearch`、`loki`、`victorialogs`、`sls`、`tencent_cls`），`monit-query data` 入口保持不变。 +- **无工具目录、无自动重试、无回退**：一次调用只执行一个命名工具，参数需按各数据源工具约定填写，不要从命令行列表猜测。除诊断工具外，入口还支持 `.query` 查询工具（`prometheus`、`mysql`、`postgres`、`oracle`、`clickhouse`、`elasticsearch`、`loki`、`victorialogs`、`sls`、`tencent_cls`）。 - 要求所选集群内**全部**当前在线可路由的 Edge 会话支持 v0.71.0 基础调用协议（个别工具可能要求更新的实现）；普通数据源查询不受此版本限制。 - 请求体 ≤128 KiB；完整成功响应 ≤10 MiB；工具超时 ≤25 秒。 - 需要数据源 `enabled=true`；`alerting_enabled=false` 不阻塞诊断。 From 9ab5ca3e8919b9efbef19a4e1e8af5603cad33bd Mon Sep 17 00:00:00 2001 From: ysyneu Date: Wed, 9 Sep 2026 20:48:38 -0700 Subject: [PATCH 3/3] docs(monit): specify from_ms for every VictoriaLogs query execution 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. --- api-reference/monitors.openapi.en.json | 2 +- api-reference/monitors.openapi.zh.json | 2 +- api-reference/openapi.en.json | 2 +- api-reference/openapi.zh.json | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/api-reference/monitors.openapi.en.json b/api-reference/monitors.openapi.en.json index 5a89d54a..098234bb 100644 --- a/api-reference/monitors.openapi.en.json +++ b/api-reference/monitors.openapi.en.json @@ -4981,7 +4981,7 @@ "from_ms": { "type": "integer", "format": "int64", - "description": "Window or range start as a Unix epoch timestamp in milliseconds. Required for `range` and `window`; optional for Loki and VictoriaLogs `instant`; rejected by Prometheus `instant`." + "description": "Window or range start as a Unix epoch timestamp in milliseconds. Required for `range`, `window`, and every VictoriaLogs execution; optional for Loki `instant`; rejected by Prometheus `instant`." }, "to_ms": { "type": "integer", diff --git a/api-reference/monitors.openapi.zh.json b/api-reference/monitors.openapi.zh.json index 9a7a5c1e..5b16cdb9 100644 --- a/api-reference/monitors.openapi.zh.json +++ b/api-reference/monitors.openapi.zh.json @@ -4981,7 +4981,7 @@ "from_ms": { "type": "integer", "format": "int64", - "description": "窗口或范围的起始时间，Unix 毫秒时间戳。`range` 和 `window` 必填；Loki 和 VictoriaLogs 的 `instant` 可选；Prometheus 的 `instant` 拒绝该字段。" + "description": "窗口或范围的起始时间，Unix 毫秒时间戳。`range` 和 `window` 必填，VictoriaLogs 的任何执行类型都必填；Loki 的 `instant` 可选；Prometheus 的 `instant` 拒绝该字段。" }, "to_ms": { "type": "integer", diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 0fb1a113..fde38c6a 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -7556,7 +7556,7 @@ "from_ms": { "type": "integer", "format": "int64", - "description": "Window or range start as a Unix epoch timestamp in milliseconds. Required for `range` and `window`; optional for Loki and VictoriaLogs `instant`; rejected by Prometheus `instant`." + "description": "Window or range start as a Unix epoch timestamp in milliseconds. Required for `range`, `window`, and every VictoriaLogs execution; optional for Loki `instant`; rejected by Prometheus `instant`." }, "to_ms": { "type": "integer", diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 10e38aa0..90bc0539 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -7556,7 +7556,7 @@ "from_ms": { "type": "integer", "format": "int64", - "description": "窗口或范围的起始时间，Unix 毫秒时间戳。`range` 和 `window` 必填；Loki 和 VictoriaLogs 的 `instant` 可选；Prometheus 的 `instant` 拒绝该字段。" + "description": "窗口或范围的起始时间，Unix 毫秒时间戳。`range` 和 `window` 必填，VictoriaLogs 的任何执行类型都必填；Loki 的 `instant` 可选；Prometheus 的 `instant` 拒绝该字段。" }, "to_ms": { "type": "integer",