From d1c68d0eef9c66d63d658ca371870701c725e6b8 Mon Sep 17 00:00:00 2001 From: Ulric Qin Date: Sun, 6 Sep 2026 15:41:51 +0800 Subject: [PATCH 1/2] docs(monit): define datasource diagnostics and host-only agent tools --- api-reference/monitors.openapi.en.json | 536 +++++++++++++++++++++++-- api-reference/monitors.openapi.zh.json | 536 +++++++++++++++++++++++-- api-reference/openapi.en.json | 530 ++++++++++++++++++++++-- api-reference/openapi.zh.json | 530 ++++++++++++++++++++++-- 4 files changed, 2002 insertions(+), 130 deletions(-) diff --git a/api-reference/monitors.openapi.en.json b/api-reference/monitors.openapi.en.json index 34ae65cd..c3c6fe8f 100644 --- a/api-reference/monitors.openapi.en.json +++ b/api-reference/monitors.openapi.en.json @@ -200,12 +200,12 @@ "post": { "operationId": "monit-datasource-write-create", "summary": "Create datasource", - "description": "Create a new monitoring data source. The `payload` must include the type-specific configuration block.", + "description": "Create a new monitoring data source. The `payload` must include the type-specific configuration block. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.", "tags": [ "Monitors/Data sources" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- `type_ident` must be one of: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`.\n- `edge_cluster_name` specifies which Monitors edge cluster evaluates rules using this datasource.\n- For `elasticsearch`, set `payload.elasticsearch.deployment` to `cloud` or `self-managed`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. The one exception is `payload.tencent_cls.secret_key`, which is always masked to an empty string (an `${env:...}` reference is returned verbatim). Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- `type_ident` must be one of: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`.\n- `edge_cluster_name` specifies which Monitors edge cluster evaluates rules using this datasource.\n- For `elasticsearch`, set `payload.elasticsearch.deployment` to `cloud` or `self-managed`.\n- Every call is recorded in the account audit log. Use credential fields only for connection credentials.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-create", "metadata": { "sidebarTitle": "Create datasource" @@ -239,7 +239,8 @@ "name": "Prometheus Prod", "enabled": true, "edge_cluster_name": "default", - "updated_at": 1712000000 + "updated_at": 1712000000, + "alerting_enabled": true } } } @@ -286,12 +287,12 @@ "post": { "operationId": "monit-datasource-write-update", "summary": "Update datasource", - "description": "Update an existing data source. Supply `id` plus the fields to change.", + "description": "Update an existing data source. Supply `id` plus the fields to change. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.", "tags": [ "Monitors/Data sources" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. The one exception is `payload.tencent_cls.secret_key`, which is always masked to an empty string (an `${env:...}` reference is returned verbatim). Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Use credential fields only for connection credentials.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-update", "metadata": { "sidebarTitle": "Update datasource" @@ -325,7 +326,8 @@ "name": "Prometheus Prod v2", "enabled": true, "edge_cluster_name": "default", - "updated_at": 1712100000 + "updated_at": 1712100000, + "alerting_enabled": true } } } @@ -999,12 +1001,12 @@ "post": { "operationId": "monit-datasource-read-info", "summary": "Get datasource detail", - "description": "Retrieve full details of a single data source by its ID, including the `payload` configuration with its configured connection and authentication settings; treat the response as sensitive and avoid logging or forwarding it.", + "description": "Retrieve full details of a single data source by its ID, including the `payload` configuration with its configured connection and authentication settings; treat the response as sensitive and avoid logging or forwarding it. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.", "tags": [ "Monitors/Data sources" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. The one exception is `payload.tencent_cls.secret_key`, which is always masked to an empty string (an `${env:...}` reference is returned verbatim). Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-info", "metadata": { "sidebarTitle": "Get datasource detail" @@ -1049,7 +1051,8 @@ } }, "edge_cluster_name": "default", - "updated_at": 1712000000 + "updated_at": 1712000000, + "alerting_enabled": true } } } @@ -2151,12 +2154,12 @@ "post": { "operationId": "monit-datasource-read-list", "summary": "List datasources", - "description": "Return all data sources for the current account. Optionally filter by `type_ident`.", + "description": "Return all data sources for the current account. Optionally filter by `type_ident`. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.", "tags": [ "Monitors/Data sources" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Omit `type_ident` to return all types.\n- Sensitive credential fields (passwords, keys) are not returned in the list response.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Omit `type_ident` to return all types.\n- Sensitive credential fields (passwords, keys) are not returned in the list response.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-list", "metadata": { "sidebarTitle": "List datasources" @@ -2195,7 +2198,8 @@ "address": "http://prometheus.example.com:9090", "edge_cluster_name": "default", "updated_at": 1712000000, - "payload": null + "payload": null, + "alerting_enabled": true } ] } @@ -2513,7 +2517,7 @@ "post": { "operationId": "monit-read-query-diagnose", "summary": "Diagnose data source", - "description": "Run a synchronous diagnostic query (`log_patterns` for Loki/VictoriaLogs, `metric_trends` for Prometheus). Used by Flashduty AI SRE for log-pattern clustering and time-series trend analysis. Long-running — up to 35 s.", + "description": "Run a synchronous diagnostic query (`log_patterns` for Loki/VictoriaLogs, `metric_trends` for Prometheus). Used by Flashduty AI SRE for log-pattern clustering and time-series trend analysis. Long-running — up to 35 s.\n\nDeprecated: migrate to /monit/datasource/tools/invoke with prometheus.metric_trends, loki.log_patterns or victorialogs.log_patterns. Retained for existing consumers; the legacy request and response remain unchanged.", "tags": [ "Monitors/Diagnostics" ], @@ -2687,14 +2691,15 @@ "500": { "$ref": "#/components/responses/ServerError" } - } + }, + "deprecated": true } }, "/monit/tools/catalog": { "post": { "operationId": "monit-read-tools-catalog", "summary": "List target tool catalog", - "description": "Look up the tools that the per-target monit-agent currently exposes for a given `target_locator` (host, mysql, …). Returns each tool's name, description, and JSON-Schema `input_schema`. Pair with `/monit/tools/invoke` to drive AI-SRE tool calls.", + "description": "Look up the tools that the per-target monit-agent currently exposes for a given `target_locator` (host). Returns each tool's name, description, and JSON-Schema `input_schema`. Pair with `/monit/tools/invoke` to drive AI-SRE tool calls. Agent targets are host-only. Remote datasource evidence uses /monit/datasource/tools/invoke and datasource_id.", "tags": [ "Monitors/Diagnostics" ], @@ -2803,7 +2808,7 @@ "post": { "operationId": "monit-read-tools-invoke", "summary": "Invoke target tools", - "description": "Invoke up to 8 monit-agent tools concurrently on a single target. Results come back in the order of the input `tools` array. Long-running — individual tools have per-tool timeouts on the agent and the whole request may take tens of seconds.", + "description": "Invoke up to 8 monit-agent tools concurrently on a single target. Results come back in the order of the input `tools` array. Long-running — individual tools have per-tool timeouts on the agent and the whole request may take tens of seconds. Agent targets are host-only. Remote datasource evidence uses /monit/datasource/tools/invoke and datasource_id.", "tags": [ "Monitors/Diagnostics" ], @@ -2930,7 +2935,7 @@ "post": { "operationId": "monit-read-targets-list", "summary": "List monitored targets", - "description": "List the targets observed under the current tenant by the monit-agent route projection. Supports `target_locator` prefix search and cursor pagination. Use this to drive `target_locator` selection for `/monit/tools/catalog` and `/monit/tools/invoke`.", + "description": "List the targets observed under the current tenant by the monit-agent route projection. Supports `target_locator` prefix search and cursor pagination. Use this to drive `target_locator` selection for `/monit/tools/catalog` and `/monit/tools/invoke`. Agent targets are host-only. Remote datasource evidence uses /monit/datasource/tools/invoke and datasource_id.", "tags": [ "Monitors/Diagnostics" ], @@ -3692,6 +3697,176 @@ } } } + }, + "/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.", + "operationId": "monit-datasource-tools-invoke", + "requestBody": { + "content": { + "application/json": { + "example": { + "datasource_id": 10, + "params": {}, + "tool": "mysql.overview" + }, + "schema": { + "$ref": "#/components/schemas/DatasourceToolInvokeRequest" + } + } + }, + "required": true + }, + "responses": { + "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": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "properties": { + "data": { + "$ref": "#/components/schemas/DatasourceToolResult" + } + }, + "type": "object" + } + ] + } + } + }, + "description": "Success" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: invalid_request, tool_not_supported, datasource_error." + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: access_denied." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: datasource_not_found." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: datasource_disabled, datasource_in_use." + }, + "413": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: source_too_large, result_too_large." + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: overloaded." + }, + "499": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: canceled." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: internal." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: no_active_edge, edge_upgrade_required, mixed_edge_versions." + }, + "504": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: timeout." + } + }, + "summary": "Invoke datasource tool", + "tags": [ + "Monitors/Data sources" + ], + "x-mint": { + "content": "Use 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.", + "href": "/en/api-reference/monitors/data-sources/monit-datasource-tools-invoke", + "metadata": { + "sidebarTitle": "Invoke datasource tool" + } + } + } } }, "components": { @@ -4757,6 +4932,26 @@ "tencent_cls": { "$ref": "#/components/schemas/DSTencentCLSConfig", "description": "Tencent CLS credentials. Required when `type_ident` is `tencent_cls`." + }, + "kafka": { + "$ref": "#/components/schemas/DSKafkaConfig", + "x-flashduty-preserve-absence": true + }, + "mongodb_mongod": { + "$ref": "#/components/schemas/DSMongoDBConfig", + "x-flashduty-preserve-absence": true + }, + "mongodb_mongos": { + "$ref": "#/components/schemas/DSMongoDBConfig", + "x-flashduty-preserve-absence": true + }, + "redis_node": { + "$ref": "#/components/schemas/DSRedisNodeConfig", + "x-flashduty-preserve-absence": true + }, + "redis_sentinel": { + "$ref": "#/components/schemas/DSRedisSentinelConfig", + "x-flashduty-preserve-absence": true } } }, @@ -5003,7 +5198,8 @@ "address", "edge_cluster_name", "updated_at", - "payload" + "payload", + "alerting_enabled" ], "properties": { "id": { @@ -5018,7 +5214,7 @@ }, "type_ident": { "type": "string", - "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`." + "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。" }, "name": { "type": "string", @@ -5026,7 +5222,7 @@ }, "enabled": { "type": "boolean", - "description": "Whether the datasource is active." + "description": "Whether business execution is enabled. Disabled datasources reject business queries and tools; enabling does not change alerting_enabled." }, "note": { "type": "string", @@ -5034,7 +5230,8 @@ }, "address": { "type": "string", - "description": "Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: `host:port`. For SLS: endpoint without http/https prefix." + "description": "Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: `host:port`. For SLS: endpoint without http/https prefix. Redis/MongoDB diagnostic types: one host:port, bracket IPv6; no URI, userinfo or query. Kafka: 1–32 unique comma-separated host:port bootstrap addresses; payload has no broker list. At most 4096 characters after normalization.", + "maxLength": 4096 }, "payload": { "anyOf": [ @@ -5045,7 +5242,7 @@ "type": "null" } ], - "description": "Type-specific configuration block; must contain the key matching `type_ident`. Always `null` in `/monit/datasource/list` responses (the list query does not read the payload column); populated in create/update/info responses. For `tencent_cls`, `secret_key` is masked to an empty string unless it is an `${env:...}` reference." + "description": "Type-specific configuration block; must contain the key matching `type_ident`. Always `null` in `/monit/datasource/list` responses (the list query does not read the payload column); populated in create/update/info responses. For `tencent_cls`, `secret_key` is masked to an empty string unless it is an `${env:...}` reference. For diagnostic types, password and Kafka tls_key are omitted from responses unless they are ${env:...} references. On update, omit those fields to preserve stored secrets; explicitly send an empty string to clear. Other configuration fields retain their existing behavior." }, "edge_cluster_name": { "type": "string", @@ -5055,6 +5252,10 @@ "type": "integer", "format": "int64", "description": "Last update timestamp, Unix epoch seconds." + }, + "alerting_enabled": { + "description": "Whether alert evaluation is allowed. Alerting also requires enabled=true and an alerting-capable type. Always false for diagnostic-only types; false does not block non-alerting queries or tools.", + "type": "boolean" } } }, @@ -5064,7 +5265,7 @@ "properties": { "type": { "type": "string", - "description": "Filter by datasource type identifier. Omit to return all types. Allowed values: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`." + "description": "Datasource type identifier. Omit to return all types. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。" } } }, @@ -5092,7 +5293,7 @@ }, "type_ident": { "type": "string", - "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`." + "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。" }, "name": { "type": "string", @@ -5104,11 +5305,12 @@ }, "address": { "type": "string", - "description": "Connection address. Required for every type except `elasticsearch` with `deployment: cloud`. Prometheus/Loki/VictoriaLogs: HTTP URL; MySQL/Oracle/Postgres/ClickHouse: `host:port`; SLS: endpoint without the `http(s)://` prefix; `tencent_cls`: must be `cls.tencentcloudapi.com` or `cls.internal.tencentcloudapi.com` (requires Monitors edge >= v0.66.0)." + "description": "Connection address. Required for every type except `elasticsearch` with `deployment: cloud`. Prometheus/Loki/VictoriaLogs: HTTP URL; MySQL/Oracle/Postgres/ClickHouse: `host:port`; SLS: endpoint without the `http(s)://` prefix; `tencent_cls`: must be `cls.tencentcloudapi.com` or `cls.internal.tencentcloudapi.com` (requires Monitors edge >= v0.66.0). Redis/MongoDB diagnostic types: one host:port, bracket IPv6; no URI, userinfo or query. Kafka: 1–32 unique comma-separated host:port bootstrap addresses; payload has no broker list. At most 4096 characters after normalization.", + "maxLength": 4096 }, "payload": { "$ref": "#/components/schemas/DSPayload", - "description": "Type-specific configuration block. Must include the key matching `type_ident`." + "description": "Type-specific configuration block. Must include the key matching `type_ident`. For diagnostic types, password and Kafka tls_key are omitted from responses unless they are ${env:...} references. On update, omit those fields to preserve stored secrets; explicitly send an empty string to clear. Other configuration fields retain their existing behavior." }, "edge_cluster_name": { "type": "string", @@ -5116,7 +5318,13 @@ }, "enabled": { "type": "boolean", - "description": "Whether the datasource is enabled for rule evaluation. When omitted on create, the datasource is created disabled (`false`)." + "description": "Whether business execution is enabled. Omitted on create: true; omitted on update: preserve the current value. Explicit false disables execution; null is invalid. Does not change alerting_enabled.", + "x-flashduty-preserve-absence": true + }, + "alerting_enabled": { + "description": "Whether this datasource may evaluate alerts. Omitted on create: true for alerting types, false for diagnostic-only types; omitted on update: preserve current value. null is invalid. redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka reject true. Disabling is rejected with conflict when enabled rules reference the datasource.", + "type": "boolean", + "x-flashduty-preserve-absence": true } } }, @@ -5131,6 +5339,11 @@ "type": "string", "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request.", "example": "The specified parameter template_id is not valid." + }, + "reason": { + "description": "Optional machine-readable rejection reason, including datasource tool failures. Inspect alongside HTTP status and code.", + "type": "string", + "x-flashduty-preserve-absence": true } }, "required": [ @@ -6480,11 +6693,14 @@ }, "target_locator": { "type": "string", - "description": "Target identifier (host name, MySQL address, …). Max 256 bytes; no whitespace, control characters, or `|`." + "description": "Host name. Max 256 bytes; no whitespace, control characters or |." }, "target_kind": { "type": "string", - "description": "Optional target kind. When omitted, webapi infers it from current target routing. If the call returns `ambiguous_target_kind`, retry with a value from `target_kinds`." + "description": "Optional target kind; only host is supported. Inferred when omitted.", + "enum": [ + "host" + ] } } }, @@ -6497,7 +6713,7 @@ "properties": { "kind": { "type": "string", - "description": "Resolved target kind, e.g. `host` or `mysql`; matches the `target_kind` inferred from or given in the request." + "description": "Resolved host target kind." }, "locator": { "type": "string", @@ -6577,11 +6793,14 @@ }, "target_locator": { "type": "string", - "description": "Target identifier. Same validation rules as `/monit/tools/catalog`." + "description": "Host name. Max 256 bytes; no whitespace, control characters or |." }, "target_kind": { "type": "string", - "description": "Optional target kind; auto-inferred when omitted." + "description": "Optional target kind; only host is supported. Inferred when omitted.", + "enum": [ + "host" + ] }, "tools": { "type": "array", @@ -6617,7 +6836,7 @@ "properties": { "kind": { "type": "string", - "description": "Resolved target kind, e.g. `host` or `mysql`; matches the `target_kind` inferred from or given in the request." + "description": "Resolved host target kind." }, "locator": { "type": "string", @@ -6748,7 +6967,7 @@ "properties": { "target_kind": { "type": "string", - "description": "Target kind, e.g. `host`, `mysql`. Filtering by kind is not supported in v1." + "description": "Host target kind. Filtering by kind is not supported in v1." }, "target_locator": { "type": "string", @@ -9268,6 +9487,255 @@ "description": "True when at least one item's status read failed." } } + }, + "DSKafkaConfig": { + "description": "Diagnostic datasource connection configuration.", + "properties": { + "password": { + "description": "Authentication password; supports ${env:NAME}. Omit on update to preserve; explicitly send an empty string to clear. Literal passwords are omitted from responses.", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "sasl_mechanism": { + "default": "none", + "description": "SASL mechanism: none (default, no credentials), plain, scram-sha-256, scram-sha-512 (require username and password).", + "enum": [ + "none", + "plain", + "scram-sha-256", + "scram-sha-512" + ], + "type": "string" + }, + "timeout_ms": { + "default": 5000, + "description": "Connection timeout in milliseconds; defaults to 5000 when omitted.", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "tls_ca": { + "description": "PEM CA certificates or an ${env:NAME} reference.", + "type": "string" + }, + "tls_cert": { + "description": "PEM client certificate or ${env:NAME}; configure both tls_cert and tls_key.", + "type": "string" + }, + "tls_enabled": { + "default": false, + "description": "Whether TLS is enabled; defaults to false.", + "type": "boolean" + }, + "tls_key": { + "description": "PEM client private key or ${env:NAME}; configure both tls_cert and tls_key. Omit on update to preserve; an empty string clears it. Literal keys are omitted from responses.", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "tls_max_version": { + "description": "Maximum TLS version: 1.2 or 1.3; empty means no constraint. Must not be below the minimum.", + "type": "string" + }, + "tls_min_version": { + "description": "Minimum TLS version: 1.2 (default) or 1.3.", + "type": "string" + }, + "tls_server_name": { + "description": "Server name used for TLS SNI and certificate verification; defaults to the host from the connection address when empty.", + "type": "string" + }, + "tls_skip_verify": { + "description": "Skip server certificate verification when TLS is enabled.", + "type": "boolean" + }, + "username": { + "description": "Authentication username; an ${env:NAME} reference is supported.", + "type": "string" + } + }, + "type": "object" + }, + "DSMongoDBConfig": { + "description": "Diagnostic datasource connection configuration.", + "properties": { + "auth_source": { + "default": "admin", + "description": "Authentication database; defaults to admin. Username and password must be configured together. Client certificates are unsupported.", + "type": "string" + }, + "password": { + "description": "Authentication password; supports ${env:NAME}. Omit on update to preserve; explicitly send an empty string to clear. Literal passwords are omitted from responses.", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "timeout_ms": { + "default": 3000, + "description": "Connection timeout in milliseconds; defaults to 3000 when omitted.", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "tls_ca": { + "description": "PEM CA certificates or an ${env:NAME} reference.", + "type": "string" + }, + "tls_enabled": { + "default": false, + "description": "Whether TLS is enabled; defaults to false.", + "type": "boolean" + }, + "tls_max_version": { + "description": "Maximum TLS version: 1.2 or 1.3; empty means no constraint. Must not be below the minimum.", + "type": "string" + }, + "tls_min_version": { + "description": "Minimum TLS version: 1.2 (default) or 1.3.", + "type": "string" + }, + "tls_server_name": { + "description": "Server name used for TLS SNI and certificate verification; defaults to the host from the connection address when empty.", + "type": "string" + }, + "tls_skip_verify": { + "description": "Skip server certificate verification when TLS is enabled.", + "type": "boolean" + }, + "username": { + "description": "Authentication username; an ${env:NAME} reference is supported.", + "type": "string" + } + }, + "type": "object" + }, + "DSRedisNodeConfig": { + "description": "Diagnostic datasource connection configuration.", + "properties": { + "database": { + "default": 0, + "description": "Redis database number; defaults to 0.", + "minimum": 0, + "type": "integer" + }, + "password": { + "description": "Authentication password; supports ${env:NAME}. Omit on update to preserve; explicitly send an empty string to clear. Literal passwords are omitted from responses.", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "timeout_ms": { + "default": 3000, + "description": "Connection timeout in milliseconds; defaults to 3000 when omitted.", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "username": { + "description": "Authentication username; an ${env:NAME} reference is supported.", + "type": "string" + } + }, + "type": "object" + }, + "DSRedisSentinelConfig": { + "description": "Diagnostic datasource connection configuration.", + "properties": { + "password": { + "description": "Authentication password; supports ${env:NAME}. Omit on update to preserve; explicitly send an empty string to clear. Literal passwords are omitted from responses.", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "timeout_ms": { + "default": 3000, + "description": "Connection timeout in milliseconds; defaults to 3000 when omitted.", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "username": { + "description": "Authentication username; an ${env:NAME} reference is supported.", + "type": "string" + } + }, + "type": "object" + }, + "DatasourceToolInvokeRequest": { + "properties": { + "account_id": { + "description": "Optional consistency check; must equal the authenticated account.", + "format": "uint64", + "type": "integer" + }, + "datasource_id": { + "description": "Datasource ID from /monit/datasource/list.", + "format": "uint64", + "minimum": 1, + "type": "integer" + }, + "params": { + "additionalProperties": true, + "description": "Tool-specific JSON parameters; omitted means {}. Explicit null is invalid.", + "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.", + "maxLength": 128, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "datasource_id", + "tool" + ], + "type": "object" + }, + "DatasourceToolResult": { + "properties": { + "data": { + "description": "Tool-specific JSON evidence, preserved without conversion; never null. No nested legacy diagnose envelope.", + "not": { + "type": "null" + }, + "x-flashduty-raw-json": true + }, + "datasource_id": { + "description": "Datasource ID from /monit/datasource/list.", + "format": "uint64", + "minimum": 1, + "type": "integer" + }, + "summary": { + "description": "Optional non-empty summary.", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "tool": { + "description": "Executed tool name matching the request.", + "type": "string" + }, + "truncated": { + "$ref": "#/components/schemas/DatasourceToolTruncation", + "x-flashduty-preserve-absence": true + } + }, + "required": [ + "datasource_id", + "tool", + "data" + ], + "type": "object" + }, + "DatasourceToolTruncation": { + "properties": { + "reason": { + "description": "Why the result was truncated. Presence of this object indicates truncation.", + "type": "string" + } + }, + "required": [ + "reason" + ], + "type": "object" } } } diff --git a/api-reference/monitors.openapi.zh.json b/api-reference/monitors.openapi.zh.json index 6efc5015..8fe9096f 100644 --- a/api-reference/monitors.openapi.zh.json +++ b/api-reference/monitors.openapi.zh.json @@ -200,12 +200,12 @@ "post": { "operationId": "monit-datasource-write-create", "summary": "创建数据源", - "description": "创建新的监控数据源，`payload` 中须包含对应类型的配置块。", + "description": "创建新的监控数据源，`payload` 中须包含对应类型的配置块。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。", "tags": [ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- `type_ident` 必须为以下之一：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。\n- `edge_cluster_name` 指定使用该数据源进行规则评估的 Monitors Edge 集群。\n- 对于 `elasticsearch`，`payload.elasticsearch.deployment` 须设为 `cloud` 或 `self-managed`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。唯一例外是 `payload.tencent_cls.secret_key`：始终掩码为空字符串（`${env:...}` 引用则原样返回）。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- `type_ident` 必须为以下之一：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`、`redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka`。\n- `edge_cluster_name` 指定使用该数据源进行规则评估的 Monitors Edge 集群。\n- 对于 `elasticsearch`，`payload.elasticsearch.deployment` 须设为 `cloud` 或 `self-managed`。\n- 每次调用都会记录到账户审计日志，仅通过凭据字段配置连接凭据。\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-create", "metadata": { "sidebarTitle": "创建数据源" @@ -239,7 +239,8 @@ "name": "Prometheus Prod", "enabled": true, "edge_cluster_name": "default", - "updated_at": 1712000000 + "updated_at": 1712000000, + "alerting_enabled": true } } } @@ -286,12 +287,12 @@ "post": { "operationId": "monit-datasource-write-update", "summary": "更新数据源", - "description": "更新已有数据源，需提供 `id` 及待修改的字段。", + "description": "更新已有数据源，需提供 `id` 及待修改的字段。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。", "tags": [ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。唯一例外是 `payload.tencent_cls.secret_key`：始终掩码为空字符串（`${env:...}` 引用则原样返回）。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，仅通过凭据字段配置连接凭据。\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-update", "metadata": { "sidebarTitle": "更新数据源" @@ -325,7 +326,8 @@ "name": "Prometheus Prod v2", "enabled": true, "edge_cluster_name": "default", - "updated_at": 1712100000 + "updated_at": 1712100000, + "alerting_enabled": true } } } @@ -999,12 +1001,12 @@ "post": { "operationId": "monit-datasource-read-info", "summary": "查看数据源详情", - "description": "通过 ID 获取单个数据源的完整信息，包括 `payload` 配置及其中配置的连接与鉴权信息；请将该响应视为敏感信息，避免记录或转发。", + "description": "通过 ID 获取单个数据源的完整信息，包括 `payload` 配置及其中配置的连接与鉴权信息；请将该响应视为敏感信息，避免记录或转发。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。", "tags": [ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。唯一例外是 `payload.tencent_cls.secret_key`：始终掩码为空字符串（`${env:...}` 引用则原样返回）。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-info", "metadata": { "sidebarTitle": "查看数据源详情" @@ -1049,7 +1051,8 @@ } }, "edge_cluster_name": "default", - "updated_at": 1712000000 + "updated_at": 1712000000, + "alerting_enabled": true } } } @@ -2151,12 +2154,12 @@ "post": { "operationId": "monit-datasource-read-list", "summary": "查询数据源列表", - "description": "返回当前账户下的所有数据源，可通过 `type_ident` 过滤类型。", + "description": "返回当前账户下的所有数据源，可通过 `type_ident` 过滤类型。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。", "tags": [ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 省略 `type_ident` 可返回所有类型的数据源。\n- 列表响应中不返回敏感凭证字段（密码、密钥）。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 省略 `type_ident` 可返回所有类型的数据源。\n- 列表响应中不返回敏感凭证字段（密码、密钥）。\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-list", "metadata": { "sidebarTitle": "查询数据源列表" @@ -2195,7 +2198,8 @@ "address": "http://prometheus.example.com:9090", "edge_cluster_name": "default", "updated_at": 1712000000, - "payload": null + "payload": null, + "alerting_enabled": true } ] } @@ -2513,7 +2517,7 @@ "post": { "operationId": "monit-read-query-diagnose", "summary": "数据源诊断", - "description": "执行同步诊断查询(Loki/VictoriaLogs 使用 `log_patterns`,Prometheus 使用 `metric_trends`)。Flashduty AI SRE 用于日志模式聚类与时间序列趋势分析。长耗时——最长可达 35 秒。", + "description": "执行同步诊断查询(Loki/VictoriaLogs 使用 `log_patterns`,Prometheus 使用 `metric_trends`)。Flashduty AI SRE 用于日志模式聚类与时间序列趋势分析。长耗时——最长可达 35 秒。 已弃用：迁移到 /monit/datasource/tools/invoke 的 prometheus.metric_trends、loki.log_patterns 或 victorialogs.log_patterns。为现有消费者保留，旧请求与响应保持不变。", "tags": [ "Monitors/诊断分析" ], @@ -2687,14 +2691,15 @@ "500": { "$ref": "#/components/responses/ServerError" } - } + }, + "deprecated": true } }, "/monit/tools/catalog": { "post": { "operationId": "monit-read-tools-catalog", "summary": "查询监控对象工具能力清单", - "description": "根据 `target_locator`(host、mysql 等)查询该监控对象上 monit-agent 当前暴露的工具能力。返回每个工具的名称、描述以及 JSON-Schema `input_schema`。配合 `/monit/tools/invoke` 驱动 AI-SRE 的工具调用。", + "description": "根据 `target_locator`(host)查询该监控对象上 monit-agent 当前暴露的工具能力。返回每个工具的名称、描述以及 JSON-Schema `input_schema`。配合 `/monit/tools/invoke` 驱动 AI-SRE 的工具调用。 Agent 目标仅支持 host。远端数据源取证使用 /monit/datasource/tools/invoke 和 datasource_id。", "tags": [ "Monitors/诊断分析" ], @@ -2803,7 +2808,7 @@ "post": { "operationId": "monit-read-tools-invoke", "summary": "调用监控对象工具", - "description": "在单个监控对象上并发调用至多 8 个 monit-agent 工具。结果按入参 `tools` 数组顺序返回。长耗时——单个工具在 Agent 上有自己的超时,整体请求可能耗时数十秒。", + "description": "在单个监控对象上并发调用至多 8 个 monit-agent 工具。结果按入参 `tools` 数组顺序返回。长耗时——单个工具在 Agent 上有自己的超时,整体请求可能耗时数十秒。 Agent 目标仅支持 host。远端数据源取证使用 /monit/datasource/tools/invoke 和 datasource_id。", "tags": [ "Monitors/诊断分析" ], @@ -2930,7 +2935,7 @@ "post": { "operationId": "monit-read-targets-list", "summary": "监控对象列表", - "description": "列出当前租户下被 monit-agent 路由投影所观测到的监控对象。支持 `target_locator` 前缀搜索与游标分页。用于为 `/monit/tools/catalog` 与 `/monit/tools/invoke` 选择 `target_locator`。", + "description": "列出当前租户下被 monit-agent 路由投影所观测到的监控对象。支持 `target_locator` 前缀搜索与游标分页。用于为 `/monit/tools/catalog` 与 `/monit/tools/invoke` 选择 `target_locator`。 Agent 目标仅支持 host。远端数据源取证使用 /monit/datasource/tools/invoke 和 datasource_id。", "tags": [ "Monitors/诊断分析" ], @@ -3692,6 +3697,176 @@ } } } + }, + "/monit/datasource/tools/invoke": { + "post": { + "description": "对已配置的数据源执行单个确定性工具。要求集群所有当前在线可路由 Edge 会话支持 v0.71.0 基础 invoke 协议；具体工具可能需要更新实现。不提供工具目录、自动重放或 Agent/旧 diagnose 回退。请求体上限 128 KiB，完整成功响应上限 1 MiB，工具超时最多 25 秒。", + "operationId": "monit-datasource-tools-invoke", + "requestBody": { + "content": { + "application/json": { + "example": { + "datasource_id": 10, + "params": {}, + "tool": "mysql.overview" + }, + "schema": { + "$ref": "#/components/schemas/DatasourceToolInvokeRequest" + } + } + }, + "required": true + }, + "responses": { + "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": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "properties": { + "data": { + "$ref": "#/components/schemas/DatasourceToolResult" + } + }, + "type": "object" + } + ] + } + } + }, + "description": "成功" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：invalid_request, tool_not_supported, datasource_error." + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：access_denied." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：datasource_not_found." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：datasource_disabled, datasource_in_use." + }, + "413": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：source_too_large, result_too_large." + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：overloaded." + }, + "499": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：canceled." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：internal." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：no_active_edge, edge_upgrade_required, mixed_edge_versions." + }, + "504": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：timeout." + } + }, + "summary": "调用数据源工具", + "tags": [ + "Monitors/Data sources" + ], + "x-mint": { + "content": "通过 `/monit/datasource/list` 获取数据源 ID。停用数据源返回 `datasource_disabled`，`alerting_enabled=false` 不阻断工具。错误使用非 2xx HTTP 状态和 `error.code`、`error.message`、`error.reason`。`tool_not_supported` 表示选中的执行端未提供该工具，不表示厂商权限不足。禁止自动切换 Edge 或回退旧 diagnose 重试。", + "href": "/zh/api-reference/monitors/data-sources/monit-datasource-tools-invoke", + "metadata": { + "sidebarTitle": "调用数据源工具" + } + } + } } }, "components": { @@ -4757,6 +4932,26 @@ "tencent_cls": { "$ref": "#/components/schemas/DSTencentCLSConfig", "description": "腾讯云 CLS 凭证。`type_ident` 为 `tencent_cls` 时必填。" + }, + "kafka": { + "$ref": "#/components/schemas/DSKafkaConfig", + "x-flashduty-preserve-absence": true + }, + "mongodb_mongod": { + "$ref": "#/components/schemas/DSMongoDBConfig", + "x-flashduty-preserve-absence": true + }, + "mongodb_mongos": { + "$ref": "#/components/schemas/DSMongoDBConfig", + "x-flashduty-preserve-absence": true + }, + "redis_node": { + "$ref": "#/components/schemas/DSRedisNodeConfig", + "x-flashduty-preserve-absence": true + }, + "redis_sentinel": { + "$ref": "#/components/schemas/DSRedisSentinelConfig", + "x-flashduty-preserve-absence": true } } }, @@ -5003,7 +5198,8 @@ "address", "edge_cluster_name", "updated_at", - "payload" + "payload", + "alerting_enabled" ], "properties": { "id": { @@ -5018,7 +5214,7 @@ }, "type_ident": { "type": "string", - "description": "数据源类型标识，可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。" + "description": "数据源类型标识。支持：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。" }, "name": { "type": "string", @@ -5026,7 +5222,7 @@ }, "enabled": { "type": "boolean", - "description": "数据源是否启用。" + "description": "是否启用业务执行。停用时拒绝业务查询和工具调用；重新启用不改变 alerting_enabled。" }, "note": { "type": "string", @@ -5034,7 +5230,8 @@ }, "address": { "type": "string", - "description": "连接地址。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 http/https 前缀的 endpoint。" + "description": "连接地址。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 http/https 前缀的 endpoint。 Redis/MongoDB 诊断类型使用单个 host:port（IPv6 加方括号），不接受 URI、userinfo 或查询参数。Kafka 使用 1–32 个不重复、逗号分隔的 host:port 引导地址；payload 不含 broker 列表。规范化后最多 4096 个字符。", + "maxLength": 4096 }, "payload": { "anyOf": [ @@ -5045,7 +5242,7 @@ "type": "null" } ], - "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。`/monit/datasource/list` 响应中恒为 `null`（列表查询不读取 payload 列）；创建/更新/详情响应中会返回。对于 `tencent_cls`，`secret_key` 会被掩码为空字符串，除非其值为 `${env:...}` 引用。" + "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。`/monit/datasource/list` 响应中恒为 `null`（列表查询不读取 payload 列）；创建/更新/详情响应中会返回。对于 `tencent_cls`，`secret_key` 会被掩码为空字符串，除非其值为 `${env:...}` 引用。 诊断类型的 password 和 Kafka tls_key 在响应中省略，${env:...} 引用除外；更新时省略保留已保存的秘密，显式空字符串清除。其他配置字段保持原有行为。" }, "edge_cluster_name": { "type": "string", @@ -5055,6 +5252,10 @@ "type": "integer", "format": "int64", "description": "最后更新时间，Unix 时间戳（秒）。" + }, + "alerting_enabled": { + "description": "是否允许告警评估。告警同时要求 enabled=true 且类型支持告警。仅诊断类型固定为 false；false 不阻断非告警查询或工具。", + "type": "boolean" } } }, @@ -5064,7 +5265,7 @@ "properties": { "type": { "type": "string", - "description": "按数据源类型标识过滤，省略则返回所有类型。可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。" + "description": "数据源类型标识。省略时返回全部类型。支持：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。" } } }, @@ -5092,7 +5293,7 @@ }, "type_ident": { "type": "string", - "description": "数据源类型标识，可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。" + "description": "数据源类型标识。支持：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。" }, "name": { "type": "string", @@ -5104,11 +5305,12 @@ }, "address": { "type": "string", - "description": "连接地址。除 `elasticsearch` 的 `deployment: cloud` 部署外均为必填。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 `http(s)://` 前缀的 endpoint；`tencent_cls` 必须为 `cls.tencentcloudapi.com` 或 `cls.internal.tencentcloudapi.com`（要求 Monitors edge >= v0.66.0）。" + "description": "连接地址。除 `elasticsearch` 的 `deployment: cloud` 部署外均为必填。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 `http(s)://` 前缀的 endpoint；`tencent_cls` 必须为 `cls.tencentcloudapi.com` 或 `cls.internal.tencentcloudapi.com`（要求 Monitors edge >= v0.66.0）。 Redis/MongoDB 诊断类型使用单个 host:port（IPv6 加方括号），不接受 URI、userinfo 或查询参数。Kafka 使用 1–32 个不重复、逗号分隔的 host:port 引导地址；payload 不含 broker 列表。规范化后最多 4096 个字符。", + "maxLength": 4096 }, "payload": { "$ref": "#/components/schemas/DSPayload", - "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。" + "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。 诊断类型的 password 和 Kafka tls_key 在响应中省略，${env:...} 引用除外；更新时省略保留已保存的秘密，显式空字符串清除。其他配置字段保持原有行为。" }, "edge_cluster_name": { "type": "string", @@ -5116,7 +5318,13 @@ }, "enabled": { "type": "boolean", - "description": "数据源是否启用（参与规则评估）。创建时省略则默认禁用（`false`）。" + "description": "是否启用业务执行。创建时省略默认为 true；更新时省略保留当前值。显式 false 停用执行；null 非法。不改变 alerting_enabled。", + "x-flashduty-preserve-absence": true + }, + "alerting_enabled": { + "description": "是否允许数据源用于告警。创建时省略：支持告警的类型默认为 true，仅诊断类型默认为 false；更新时省略保留当前值。null 非法。redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka 不允许 true。有启用规则引用时，关闭用途返回冲突。", + "type": "boolean", + "x-flashduty-preserve-absence": true } } }, @@ -5131,6 +5339,11 @@ "type": "string", "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。", "example": "The specified parameter template_id is not valid." + }, + "reason": { + "description": "可选的机器可读拒绝原因，包含数据源工具错误；结合 HTTP 状态及 code 判断。", + "type": "string", + "x-flashduty-preserve-absence": true } }, "required": [ @@ -6480,11 +6693,14 @@ }, "target_locator": { "type": "string", - "description": "监控对象标识(主机名、MySQL 地址等)。最长 256 字节;不允许空白、控制字符或 `|`。" + "description": "主机名，最多 256 字节，不允许空白、控制字符或 |。" }, "target_kind": { "type": "string", - "description": "可选的 target kind。省略时 webapi 会按当前监控对象路由自动推断。若返回 `ambiguous_target_kind`，请从 `target_kinds` 中选择一个值重试。" + "description": "可选目标类型，仅支持 host，省略时推断。", + "enum": [ + "host" + ] } } }, @@ -6497,7 +6713,7 @@ "properties": { "kind": { "type": "string", - "description": "解析出的目标类型（target kind），如 `host`、`mysql`；与请求推断或指定的 `target_kind` 一致。" + "description": "解析后的 host 目标类型。" }, "locator": { "type": "string", @@ -6577,11 +6793,14 @@ }, "target_locator": { "type": "string", - "description": "监控对象标识。校验规则与 `/monit/tools/catalog` 相同。" + "description": "主机名，最多 256 字节，不允许空白、控制字符或 |。" }, "target_kind": { "type": "string", - "description": "可选的 target kind;省略时自动推断。" + "description": "可选目标类型，仅支持 host，省略时推断。", + "enum": [ + "host" + ] }, "tools": { "type": "array", @@ -6617,7 +6836,7 @@ "properties": { "kind": { "type": "string", - "description": "解析出的目标类型（target kind），如 `host`、`mysql`；与请求推断或指定的 `target_kind` 一致。" + "description": "解析后的 host 目标类型。" }, "locator": { "type": "string", @@ -6748,7 +6967,7 @@ "properties": { "target_kind": { "type": "string", - "description": "Target kind,如 `host`、`mysql`。v1 不支持按 kind 过滤。" + "description": "主机目标类型 host。v1 不支持按 kind 过滤。" }, "target_locator": { "type": "string", @@ -9268,6 +9487,255 @@ "description": "至少一个条目状态读取失败时为 true。" } } + }, + "DSKafkaConfig": { + "description": "诊断数据源连接配置。", + "properties": { + "password": { + "description": "认证密码，支持 ${env:NAME}。更新时省略保留；显式空字符串清除。响应中省略字面密码。", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "sasl_mechanism": { + "default": "none", + "description": "SASL 机制：none（默认，不接受凭据）、plain、scram-sha-256、scram-sha-512（需要用户名与密码）。", + "enum": [ + "none", + "plain", + "scram-sha-256", + "scram-sha-512" + ], + "type": "string" + }, + "timeout_ms": { + "default": 5000, + "description": "连接超时，单位毫秒；省略默认为 5000。", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "tls_ca": { + "description": "PEM CA 证书或 ${env:NAME} 引用。", + "type": "string" + }, + "tls_cert": { + "description": "PEM 客户端证书或 ${env:NAME}，须配对配置 tls_cert 与 tls_key。", + "type": "string" + }, + "tls_enabled": { + "default": false, + "description": "是否启用 TLS，默认为 false。", + "type": "boolean" + }, + "tls_key": { + "description": "PEM 客户端私钥或 ${env:NAME}，须配对配置 tls_cert 与 tls_key。 更新时省略保留，空字符串清除；响应中省略字面私钥。", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "tls_max_version": { + "description": "最高 TLS 版本：1.2 或 1.3；空值表示不限制，不能低于最低版本。", + "type": "string" + }, + "tls_min_version": { + "description": "最低 TLS 版本：1.2（默认）或 1.3。", + "type": "string" + }, + "tls_server_name": { + "description": "TLS 握手使用的 SNI / 证书校验主机名；留空时取连接地址中的主机名。", + "type": "string" + }, + "tls_skip_verify": { + "description": "启用 TLS 时是否跳过服务端证书验证。", + "type": "boolean" + }, + "username": { + "description": "认证用户名，支持 ${env:NAME} 引用。", + "type": "string" + } + }, + "type": "object" + }, + "DSMongoDBConfig": { + "description": "诊断数据源连接配置。", + "properties": { + "auth_source": { + "default": "admin", + "description": "认证数据库，默认为 admin。用户名与密码必须同时配置。不支持客户端证书。", + "type": "string" + }, + "password": { + "description": "认证密码，支持 ${env:NAME}。更新时省略保留；显式空字符串清除。响应中省略字面密码。", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "timeout_ms": { + "default": 3000, + "description": "连接超时，单位毫秒；省略默认为 3000。", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "tls_ca": { + "description": "PEM CA 证书或 ${env:NAME} 引用。", + "type": "string" + }, + "tls_enabled": { + "default": false, + "description": "是否启用 TLS，默认为 false。", + "type": "boolean" + }, + "tls_max_version": { + "description": "最高 TLS 版本：1.2 或 1.3；空值表示不限制，不能低于最低版本。", + "type": "string" + }, + "tls_min_version": { + "description": "最低 TLS 版本：1.2（默认）或 1.3。", + "type": "string" + }, + "tls_server_name": { + "description": "TLS 握手使用的 SNI / 证书校验主机名；留空时取连接地址中的主机名。", + "type": "string" + }, + "tls_skip_verify": { + "description": "启用 TLS 时是否跳过服务端证书验证。", + "type": "boolean" + }, + "username": { + "description": "认证用户名，支持 ${env:NAME} 引用。", + "type": "string" + } + }, + "type": "object" + }, + "DSRedisNodeConfig": { + "description": "诊断数据源连接配置。", + "properties": { + "database": { + "default": 0, + "description": "Redis 数据库编号，默认为 0。", + "minimum": 0, + "type": "integer" + }, + "password": { + "description": "认证密码，支持 ${env:NAME}。更新时省略保留；显式空字符串清除。响应中省略字面密码。", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "timeout_ms": { + "default": 3000, + "description": "连接超时，单位毫秒；省略默认为 3000。", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "username": { + "description": "认证用户名，支持 ${env:NAME} 引用。", + "type": "string" + } + }, + "type": "object" + }, + "DSRedisSentinelConfig": { + "description": "诊断数据源连接配置。", + "properties": { + "password": { + "description": "认证密码，支持 ${env:NAME}。更新时省略保留；显式空字符串清除。响应中省略字面密码。", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "timeout_ms": { + "default": 3000, + "description": "连接超时，单位毫秒；省略默认为 3000。", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "username": { + "description": "认证用户名，支持 ${env:NAME} 引用。", + "type": "string" + } + }, + "type": "object" + }, + "DatasourceToolInvokeRequest": { + "properties": { + "account_id": { + "description": "可选一致性检查，必须等于认证账户。", + "format": "uint64", + "type": "integer" + }, + "datasource_id": { + "description": "通过 /monit/datasource/list 获取的数据源 ID。", + "format": "uint64", + "minimum": 1, + "type": "integer" + }, + "params": { + "additionalProperties": true, + "description": "工具专属 JSON 参数，省略时为 {}，显式 null 非法。", + "type": "object", + "x-flashduty-raw-json": true + }, + "tool": { + "description": "以数据源类型为前缀的单个工具名，如 mysql.overview。自由 SQL 使用 /monit/query/data；不支持 mysql.query 和 postgres.query。", + "maxLength": 128, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "datasource_id", + "tool" + ], + "type": "object" + }, + "DatasourceToolResult": { + "properties": { + "data": { + "description": "工具专属 JSON 证据，原样保留，不为 null，不包含旧 diagnose 额外信封。", + "not": { + "type": "null" + }, + "x-flashduty-raw-json": true + }, + "datasource_id": { + "description": "通过 /monit/datasource/list 获取的数据源 ID。", + "format": "uint64", + "minimum": 1, + "type": "integer" + }, + "summary": { + "description": "可选非空摘要。", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "tool": { + "description": "执行的工具名，与请求一致。", + "type": "string" + }, + "truncated": { + "$ref": "#/components/schemas/DatasourceToolTruncation", + "x-flashduty-preserve-absence": true + } + }, + "required": [ + "datasource_id", + "tool", + "data" + ], + "type": "object" + }, + "DatasourceToolTruncation": { + "properties": { + "reason": { + "description": "结果截断原因；该对象存在即表示发生截断。", + "type": "string" + } + }, + "required": [ + "reason" + ], + "type": "object" } } } diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index e9d7c073..4eaf4ed3 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -6842,6 +6842,73 @@ }, "type": "object" }, + "DSKafkaConfig": { + "description": "Diagnostic datasource connection configuration.", + "properties": { + "password": { + "description": "Authentication password; supports ${env:NAME}. Omit on update to preserve; explicitly send an empty string to clear. Literal passwords are omitted from responses.", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "sasl_mechanism": { + "default": "none", + "description": "SASL mechanism: none (default, no credentials), plain, scram-sha-256, scram-sha-512 (require username and password).", + "enum": [ + "none", + "plain", + "scram-sha-256", + "scram-sha-512" + ], + "type": "string" + }, + "timeout_ms": { + "default": 5000, + "description": "Connection timeout in milliseconds; defaults to 5000 when omitted.", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "tls_ca": { + "description": "PEM CA certificates or an ${env:NAME} reference.", + "type": "string" + }, + "tls_cert": { + "description": "PEM client certificate or ${env:NAME}; configure both tls_cert and tls_key.", + "type": "string" + }, + "tls_enabled": { + "default": false, + "description": "Whether TLS is enabled; defaults to false.", + "type": "boolean" + }, + "tls_key": { + "description": "PEM client private key or ${env:NAME}; configure both tls_cert and tls_key. Omit on update to preserve; an empty string clears it. Literal keys are omitted from responses.", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "tls_max_version": { + "description": "Maximum TLS version: 1.2 or 1.3; empty means no constraint. Must not be below the minimum.", + "type": "string" + }, + "tls_min_version": { + "description": "Minimum TLS version: 1.2 (default) or 1.3.", + "type": "string" + }, + "tls_server_name": { + "description": "Server name used for TLS SNI and certificate verification; defaults to the host from the connection address when empty.", + "type": "string" + }, + "tls_skip_verify": { + "description": "Skip server certificate verification when TLS is enabled.", + "type": "boolean" + }, + "username": { + "description": "Authentication username; an ${env:NAME} reference is supported.", + "type": "string" + } + }, + "type": "object" + }, "DSLokiConfig": { "description": "Loki datasource configuration. TLS fields are inherited from TLSClientConfig.", "properties": { @@ -6902,6 +6969,58 @@ }, "type": "object" }, + "DSMongoDBConfig": { + "description": "Diagnostic datasource connection configuration.", + "properties": { + "auth_source": { + "default": "admin", + "description": "Authentication database; defaults to admin. Username and password must be configured together. Client certificates are unsupported.", + "type": "string" + }, + "password": { + "description": "Authentication password; supports ${env:NAME}. Omit on update to preserve; explicitly send an empty string to clear. Literal passwords are omitted from responses.", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "timeout_ms": { + "default": 3000, + "description": "Connection timeout in milliseconds; defaults to 3000 when omitted.", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "tls_ca": { + "description": "PEM CA certificates or an ${env:NAME} reference.", + "type": "string" + }, + "tls_enabled": { + "default": false, + "description": "Whether TLS is enabled; defaults to false.", + "type": "boolean" + }, + "tls_max_version": { + "description": "Maximum TLS version: 1.2 or 1.3; empty means no constraint. Must not be below the minimum.", + "type": "string" + }, + "tls_min_version": { + "description": "Minimum TLS version: 1.2 (default) or 1.3.", + "type": "string" + }, + "tls_server_name": { + "description": "Server name used for TLS SNI and certificate verification; defaults to the host from the connection address when empty.", + "type": "string" + }, + "tls_skip_verify": { + "description": "Skip server certificate verification when TLS is enabled.", + "type": "boolean" + }, + "username": { + "description": "Authentication username; an ${env:NAME} reference is supported.", + "type": "string" + } + }, + "type": "object" + }, "DSMySQLConfig": { "description": "MySQL datasource configuration. TLS fields are inherited from TLSClientConfig.", "properties": { @@ -7019,9 +7138,21 @@ "elasticsearch": { "$ref": "#/components/schemas/DSElasticSearchConfig" }, + "kafka": { + "$ref": "#/components/schemas/DSKafkaConfig", + "x-flashduty-preserve-absence": true + }, "loki": { "$ref": "#/components/schemas/DSLokiConfig" }, + "mongodb_mongod": { + "$ref": "#/components/schemas/DSMongoDBConfig", + "x-flashduty-preserve-absence": true + }, + "mongodb_mongos": { + "$ref": "#/components/schemas/DSMongoDBConfig", + "x-flashduty-preserve-absence": true + }, "mysql": { "$ref": "#/components/schemas/DSMySQLConfig" }, @@ -7034,6 +7165,14 @@ "prometheus": { "$ref": "#/components/schemas/DSPrometheusConfig" }, + "redis_node": { + "$ref": "#/components/schemas/DSRedisNodeConfig", + "x-flashduty-preserve-absence": true + }, + "redis_sentinel": { + "$ref": "#/components/schemas/DSRedisSentinelConfig", + "x-flashduty-preserve-absence": true + }, "sls": { "$ref": "#/components/schemas/DSSLSConfig" }, @@ -7161,6 +7300,56 @@ }, "type": "object" }, + "DSRedisNodeConfig": { + "description": "Diagnostic datasource connection configuration.", + "properties": { + "database": { + "default": 0, + "description": "Redis database number; defaults to 0.", + "minimum": 0, + "type": "integer" + }, + "password": { + "description": "Authentication password; supports ${env:NAME}. Omit on update to preserve; explicitly send an empty string to clear. Literal passwords are omitted from responses.", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "timeout_ms": { + "default": 3000, + "description": "Connection timeout in milliseconds; defaults to 3000 when omitted.", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "username": { + "description": "Authentication username; an ${env:NAME} reference is supported.", + "type": "string" + } + }, + "type": "object" + }, + "DSRedisSentinelConfig": { + "description": "Diagnostic datasource connection configuration.", + "properties": { + "password": { + "description": "Authentication password; supports ${env:NAME}. Omit on update to preserve; explicitly send an empty string to clear. Literal passwords are omitted from responses.", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "timeout_ms": { + "default": 3000, + "description": "Connection timeout in milliseconds; defaults to 3000 when omitted.", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "username": { + "description": "Authentication username; an ${env:NAME} reference is supported.", + "type": "string" + } + }, + "type": "object" + }, "DSSLSConfig": { "description": "Alibaba Cloud SLS datasource configuration.", "properties": { @@ -7303,15 +7492,20 @@ "type": "integer" }, "address": { - "description": "Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: `host:port`. For SLS: endpoint without http/https prefix.", + "description": "Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: `host:port`. For SLS: endpoint without http/https prefix. Redis/MongoDB diagnostic types: one host:port, bracket IPv6; no URI, userinfo or query. Kafka: 1–32 unique comma-separated host:port bootstrap addresses; payload has no broker list. At most 4096 characters after normalization.", + "maxLength": 4096, "type": "string" }, + "alerting_enabled": { + "description": "Whether alert evaluation is allowed. Alerting also requires enabled=true and an alerting-capable type. Always false for diagnostic-only types; false does not block non-alerting queries or tools.", + "type": "boolean" + }, "edge_cluster_name": { "description": "Monitors edge cluster name responsible for evaluating rules using this datasource.", "type": "string" }, "enabled": { - "description": "Whether the datasource is active.", + "description": "Whether business execution is enabled. Disabled datasources reject business queries and tools; enabling does not change alerting_enabled.", "type": "boolean" }, "id": { @@ -7336,10 +7530,10 @@ "type": "null" } ], - "description": "Type-specific configuration block; must contain the key matching `type_ident`. Always `null` in `/monit/datasource/list` responses (the list query does not read the payload column); populated in create/update/info responses. For `tencent_cls`, `secret_key` is masked to an empty string unless it is an `${env:...}` reference." + "description": "Type-specific configuration block; must contain the key matching `type_ident`. Always `null` in `/monit/datasource/list` responses (the list query does not read the payload column); populated in create/update/info responses. For `tencent_cls`, `secret_key` is masked to an empty string unless it is an `${env:...}` reference. For diagnostic types, password and Kafka tls_key are omitted from responses unless they are ${env:...} references. On update, omit those fields to preserve stored secrets; explicitly send an empty string to clear. Other configuration fields retain their existing behavior." }, "type_ident": { - "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`.", + "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。", "type": "string" }, "updated_at": { @@ -7358,7 +7552,8 @@ "address", "edge_cluster_name", "updated_at", - "payload" + "payload", + "alerting_enabled" ], "type": "object" }, @@ -7366,7 +7561,7 @@ "description": "Filter parameters for listing datasources.", "properties": { "type": { - "description": "Filter by datasource type identifier. Omit to return all types. Allowed values: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`.", + "description": "Datasource type identifier. Omit to return all types. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。", "type": "string" } }, @@ -7383,16 +7578,23 @@ "description": "Request body for creating or updating a datasource. `id` is required only for update. `address` is required for all types except Elasticsearch with `deployment=cloud`.", "properties": { "address": { - "description": "Connection address. Required for every type except `elasticsearch` with `deployment: cloud`. Prometheus/Loki/VictoriaLogs: HTTP URL; MySQL/Oracle/Postgres/ClickHouse: `host:port`; SLS: endpoint without the `http(s)://` prefix; `tencent_cls`: must be `cls.tencentcloudapi.com` or `cls.internal.tencentcloudapi.com` (requires Monitors edge >= v0.66.0).", + "description": "Connection address. Required for every type except `elasticsearch` with `deployment: cloud`. Prometheus/Loki/VictoriaLogs: HTTP URL; MySQL/Oracle/Postgres/ClickHouse: `host:port`; SLS: endpoint without the `http(s)://` prefix; `tencent_cls`: must be `cls.tencentcloudapi.com` or `cls.internal.tencentcloudapi.com` (requires Monitors edge >= v0.66.0). Redis/MongoDB diagnostic types: one host:port, bracket IPv6; no URI, userinfo or query. Kafka: 1–32 unique comma-separated host:port bootstrap addresses; payload has no broker list. At most 4096 characters after normalization.", + "maxLength": 4096, "type": "string" }, + "alerting_enabled": { + "description": "Whether this datasource may evaluate alerts. Omitted on create: true for alerting types, false for diagnostic-only types; omitted on update: preserve current value. null is invalid. redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka reject true. Disabling is rejected with conflict when enabled rules reference the datasource.", + "type": "boolean", + "x-flashduty-preserve-absence": true + }, "edge_cluster_name": { "description": "Monitors edge cluster name responsible for evaluating rules using this datasource.", "type": "string" }, "enabled": { - "description": "Whether the datasource is enabled for rule evaluation. When omitted on create, the datasource is created disabled (`false`).", - "type": "boolean" + "description": "Whether business execution is enabled. Omitted on create: true; omitted on update: preserve the current value. Explicit false disables execution; null is invalid. Does not change alerting_enabled.", + "type": "boolean", + "x-flashduty-preserve-absence": true }, "id": { "description": "Datasource ID. Required for update; omit for create.", @@ -7409,10 +7611,10 @@ }, "payload": { "$ref": "#/components/schemas/DSPayload", - "description": "Type-specific configuration block. Must include the key matching `type_ident`." + "description": "Type-specific configuration block. Must include the key matching `type_ident`. For diagnostic types, password and Kafka tls_key are omitted from responses unless they are ${env:...} references. On update, omit those fields to preserve stored secrets; explicitly send an empty string to clear. Other configuration fields retain their existing behavior." }, "type_ident": { - "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`.", + "description": "Datasource type identifier. Allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。", "type": "string" } }, @@ -7424,6 +7626,86 @@ ], "type": "object" }, + "DatasourceToolInvokeRequest": { + "properties": { + "account_id": { + "description": "Optional consistency check; must equal the authenticated account.", + "format": "uint64", + "type": "integer" + }, + "datasource_id": { + "description": "Datasource ID from /monit/datasource/list.", + "format": "uint64", + "minimum": 1, + "type": "integer" + }, + "params": { + "additionalProperties": true, + "description": "Tool-specific JSON parameters; omitted means {}. Explicit null is invalid.", + "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.", + "maxLength": 128, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "datasource_id", + "tool" + ], + "type": "object" + }, + "DatasourceToolResult": { + "properties": { + "data": { + "description": "Tool-specific JSON evidence, preserved without conversion; never null. No nested legacy diagnose envelope.", + "not": { + "type": "null" + }, + "x-flashduty-raw-json": true + }, + "datasource_id": { + "description": "Datasource ID from /monit/datasource/list.", + "format": "uint64", + "minimum": 1, + "type": "integer" + }, + "summary": { + "description": "Optional non-empty summary.", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "tool": { + "description": "Executed tool name matching the request.", + "type": "string" + }, + "truncated": { + "$ref": "#/components/schemas/DatasourceToolTruncation", + "x-flashduty-preserve-absence": true + } + }, + "required": [ + "datasource_id", + "tool", + "data" + ], + "type": "object" + }, + "DatasourceToolTruncation": { + "properties": { + "reason": { + "description": "Why the result was truncated. Presence of this object indicates truncation.", + "type": "string" + } + }, + "required": [ + "reason" + ], + "type": "object" + }, "DeleteFieldRequest": { "properties": { "field_id": { @@ -8274,6 +8556,11 @@ "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request.", "example": "The specified parameter template_id is not valid.", "type": "string" + }, + "reason": { + "description": "Optional machine-readable rejection reason, including datasource tool failures. Inspect alongside HTTP status and code.", + "type": "string", + "x-flashduty-preserve-absence": true } }, "required": [ @@ -27611,7 +27898,7 @@ "description": "ServiceMap capability and latest status of the target's host. Omitted when the reporting agent has no ServiceMap capability." }, "target_kind": { - "description": "Target kind, e.g. `host`, `mysql`. Filtering by kind is not supported in v1.", + "description": "Host target kind. Filtering by kind is not supported in v1.", "type": "string" }, "target_locator": { @@ -28574,11 +28861,14 @@ "type": "integer" }, "target_kind": { - "description": "Optional target kind. When omitted, webapi infers it from current target routing. If the call returns `ambiguous_target_kind`, retry with a value from `target_kinds`.", + "description": "Optional target kind; only host is supported. Inferred when omitted.", + "enum": [ + "host" + ], "type": "string" }, "target_locator": { - "description": "Target identifier (host name, MySQL address, …). Max 256 bytes; no whitespace, control characters, or `|`.", + "description": "Host name. Max 256 bytes; no whitespace, control characters or |.", "type": "string" } }, @@ -28623,7 +28913,7 @@ "description": "Resolved target. Omitted when `target_kind` was not supplied and the locator could not be uniquely inferred.", "properties": { "kind": { - "description": "Resolved target kind, e.g. `host` or `mysql`; matches the `target_kind` inferred from or given in the request.", + "description": "Resolved host target kind.", "type": "string" }, "locator": { @@ -28670,11 +28960,14 @@ "type": "integer" }, "target_kind": { - "description": "Optional target kind; auto-inferred when omitted.", + "description": "Optional target kind; only host is supported. Inferred when omitted.", + "enum": [ + "host" + ], "type": "string" }, "target_locator": { - "description": "Target identifier. Same validation rules as `/monit/tools/catalog`.", + "description": "Host name. Max 256 bytes; no whitespace, control characters or |.", "type": "string" }, "tools": { @@ -28799,7 +29092,7 @@ "description": "Resolved target. Omitted when `target_kind` was not supplied and the locator could not be uniquely inferred.", "properties": { "kind": { - "description": "Resolved target kind, e.g. `host` or `mysql`; matches the `target_kind` inferred from or given in the request.", + "description": "Resolved host target kind.", "type": "string" }, "locator": { @@ -43872,7 +44165,7 @@ }, "/monit/datasource/create": { "post": { - "description": "Create a new monitoring data source. The `payload` must include the type-specific configuration block.", + "description": "Create a new monitoring data source. The `payload` must include the type-specific configuration block. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.", "operationId": "monit-datasource-write-create", "requestBody": { "content": { @@ -43902,6 +44195,7 @@ "application/json": { "example": { "data": { + "alerting_enabled": true, "edge_cluster_name": "default", "enabled": true, "id": 10, @@ -43948,7 +44242,7 @@ "Monitors/Data sources" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- `type_ident` must be one of: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`.\n- `edge_cluster_name` specifies which Monitors edge cluster evaluates rules using this datasource.\n- For `elasticsearch`, set `payload.elasticsearch.deployment` to `cloud` or `self-managed`.\n- Every call is recorded in the account audit log. Don't put secrets in request fields.\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. The one exception is `payload.tencent_cls.secret_key`, which is always masked to an empty string (an `${env:...}` reference is returned verbatim). Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- `type_ident` must be one of: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`.\n- `edge_cluster_name` specifies which Monitors edge cluster evaluates rules using this datasource.\n- For `elasticsearch`, set `payload.elasticsearch.deployment` to `cloud` or `self-managed`.\n- Every call is recorded in the account audit log. Use credential fields only for connection credentials.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-create", "metadata": { "sidebarTitle": "Create datasource" @@ -44028,7 +44322,7 @@ }, "/monit/datasource/info": { "post": { - "description": "Retrieve full details of a single data source by its ID, including the `payload` configuration with its configured connection and authentication settings; treat the response as sensitive and avoid logging or forwarding it.", + "description": "Retrieve full details of a single data source by its ID, including the `payload` configuration with its configured connection and authentication settings; treat the response as sensitive and avoid logging or forwarding it. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.", "operationId": "monit-datasource-read-info", "requestBody": { "content": { @@ -44051,6 +44345,7 @@ "data": { "account_id": 10023, "address": "http://prometheus.example.com:9090", + "alerting_enabled": true, "edge_cluster_name": "default", "enabled": true, "id": 10, @@ -44106,7 +44401,7 @@ "Monitors/Data sources" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. The one exception is `payload.tencent_cls.secret_key`, which is always masked to an empty string (an `${env:...}` reference is returned verbatim). Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-info", "metadata": { "sidebarTitle": "Get datasource detail" @@ -44116,7 +44411,7 @@ }, "/monit/datasource/list": { "post": { - "description": "Return all data sources for the current account. Optionally filter by `type_ident`.", + "description": "Return all data sources for the current account. Optionally filter by `type_ident`. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.", "operationId": "monit-datasource-read-list", "requestBody": { "content": { @@ -44140,6 +44435,7 @@ { "account_id": 10023, "address": "http://prometheus.example.com:9090", + "alerting_enabled": true, "edge_cluster_name": "default", "enabled": true, "id": 10, @@ -44189,7 +44485,7 @@ "Monitors/Data sources" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Omit `type_ident` to return all types.\n- Sensitive credential fields (passwords, keys) are not returned in the list response.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Read** (`monit`) |\n\n## Usage\n\n- Omit `type_ident` to return all types.\n- Sensitive credential fields (passwords, keys) are not returned in the list response.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-read-list", "metadata": { "sidebarTitle": "List datasources" @@ -44369,9 +44665,179 @@ } } }, + "/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.", + "operationId": "monit-datasource-tools-invoke", + "requestBody": { + "content": { + "application/json": { + "example": { + "datasource_id": 10, + "params": {}, + "tool": "mysql.overview" + }, + "schema": { + "$ref": "#/components/schemas/DatasourceToolInvokeRequest" + } + } + }, + "required": true + }, + "responses": { + "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": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "properties": { + "data": { + "$ref": "#/components/schemas/DatasourceToolResult" + } + }, + "type": "object" + } + ] + } + } + }, + "description": "Success" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: invalid_request, tool_not_supported, datasource_error." + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: access_denied." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: datasource_not_found." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: datasource_disabled, datasource_in_use." + }, + "413": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: source_too_large, result_too_large." + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: overloaded." + }, + "499": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: canceled." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: internal." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: no_active_edge, edge_upgrade_required, mixed_edge_versions." + }, + "504": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "Standard HTTP error; error.reason: timeout." + } + }, + "summary": "Invoke datasource tool", + "tags": [ + "Monitors/Data sources" + ], + "x-mint": { + "content": "Use 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.", + "href": "/en/api-reference/monitors/data-sources/monit-datasource-tools-invoke", + "metadata": { + "sidebarTitle": "Invoke datasource tool" + } + } + } + }, "/monit/datasource/update": { "post": { - "description": "Update an existing data source. Supply `id` plus the fields to change.", + "description": "Update an existing data source. Supply `id` plus the fields to change. Supports diagnostic types redis_node, redis_sentinel, mongodb_mongod, mongodb_mongos and kafka; enabled and alerting_enabled are independent.", "operationId": "monit-datasource-write-update", "requestBody": { "content": { @@ -44402,6 +44868,7 @@ "application/json": { "example": { "data": { + "alerting_enabled": true, "edge_cluster_name": "default", "enabled": true, "id": 10, @@ -44448,7 +44915,7 @@ "Monitors/Data sources" ], "x-mint": { - "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Don't put secrets in request fields.\n\n## Credential fields\n\nThe `info` / `create` / `update` responses include the `payload` configuration exactly as stored — `password`, `basic_auth_password`, `api_key`, `service_token`, `access_key_secret`, `tls_key`, `tls_key_pwd` and similar fields are returned as-is, not masked. The one exception is `payload.tencent_cls.secret_key`, which is always masked to an empty string (an `${env:...}` reference is returned verbatim). Treat these responses as sensitive: avoid logging them or forwarding them to third parties.", + "content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Datasources Manage** (`monit`) |\n\n## Usage\n\n- Every call is recorded in the account audit log. Use credential fields only for connection credentials.\n\nSee the request/response schemas for all supported types and credential handling. Diagnostic-only types cannot enable alerting. On create omitted enabled defaults to true; on update omission preserves the current value. Explicit null for enabled or alerting_enabled is invalid. Diagnostic passwords and Kafka private keys are omitted from responses unless they are environment references; omit these secrets on update to preserve them, or send an empty string to clear. Other datasource credentials may be returned and must be handled as sensitive.", "href": "/en/api-reference/monitors/data-sources/monit-datasource-write-update", "metadata": { "sidebarTitle": "Update datasource" @@ -44581,7 +45048,8 @@ }, "/monit/query/diagnose": { "post": { - "description": "Run a synchronous diagnostic query (`log_patterns` for Loki/VictoriaLogs, `metric_trends` for Prometheus). Used by Flashduty AI SRE for log-pattern clustering and time-series trend analysis. Long-running — up to 35 s.", + "deprecated": true, + "description": "Run a synchronous diagnostic query (`log_patterns` for Loki/VictoriaLogs, `metric_trends` for Prometheus). Used by Flashduty AI SRE for log-pattern clustering and time-series trend analysis. Long-running — up to 35 s.\n\nDeprecated: migrate to /monit/datasource/tools/invoke with prometheus.metric_trends, loki.log_patterns or victorialogs.log_patterns. Retained for existing consumers; the legacy request and response remain unchanged.", "operationId": "monit-read-query-diagnose", "requestBody": { "content": { @@ -47202,7 +47670,7 @@ }, "/monit/targets": { "post": { - "description": "List the targets observed under the current tenant by the monit-agent route projection. Supports `target_locator` prefix search and cursor pagination. Use this to drive `target_locator` selection for `/monit/tools/catalog` and `/monit/tools/invoke`.", + "description": "List the targets observed under the current tenant by the monit-agent route projection. Supports `target_locator` prefix search and cursor pagination. Use this to drive `target_locator` selection for `/monit/tools/catalog` and `/monit/tools/invoke`. Agent targets are host-only. Remote datasource evidence uses /monit/datasource/tools/invoke and datasource_id.", "operationId": "monit-read-targets-list", "requestBody": { "content": { @@ -47286,7 +47754,7 @@ }, "/monit/tools/catalog": { "post": { - "description": "Look up the tools that the per-target monit-agent currently exposes for a given `target_locator` (host, mysql, …). Returns each tool's name, description, and JSON-Schema `input_schema`. Pair with `/monit/tools/invoke` to drive AI-SRE tool calls.", + "description": "Look up the tools that the per-target monit-agent currently exposes for a given `target_locator` (host). Returns each tool's name, description, and JSON-Schema `input_schema`. Pair with `/monit/tools/invoke` to drive AI-SRE tool calls. Agent targets are host-only. Remote datasource evidence uses /monit/datasource/tools/invoke and datasource_id.", "operationId": "monit-read-tools-catalog", "requestBody": { "content": { @@ -47395,7 +47863,7 @@ }, "/monit/tools/invoke": { "post": { - "description": "Invoke up to 8 monit-agent tools concurrently on a single target. Results come back in the order of the input `tools` array. Long-running — individual tools have per-tool timeouts on the agent and the whole request may take tens of seconds.", + "description": "Invoke up to 8 monit-agent tools concurrently on a single target. Results come back in the order of the input `tools` array. Long-running — individual tools have per-tool timeouts on the agent and the whole request may take tens of seconds. Agent targets are host-only. Remote datasource evidence uses /monit/datasource/tools/invoke and datasource_id.", "operationId": "monit-read-tools-invoke", "requestBody": { "content": { @@ -63021,4 +63489,4 @@ "name": "AI SRE/Artifacts" } ] -} \ No newline at end of file +} diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index c53b92a8..7b9f5a6a 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -6842,6 +6842,73 @@ }, "type": "object" }, + "DSKafkaConfig": { + "description": "诊断数据源连接配置。", + "properties": { + "password": { + "description": "认证密码，支持 ${env:NAME}。更新时省略保留；显式空字符串清除。响应中省略字面密码。", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "sasl_mechanism": { + "default": "none", + "description": "SASL 机制：none（默认，不接受凭据）、plain、scram-sha-256、scram-sha-512（需要用户名与密码）。", + "enum": [ + "none", + "plain", + "scram-sha-256", + "scram-sha-512" + ], + "type": "string" + }, + "timeout_ms": { + "default": 5000, + "description": "连接超时，单位毫秒；省略默认为 5000。", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "tls_ca": { + "description": "PEM CA 证书或 ${env:NAME} 引用。", + "type": "string" + }, + "tls_cert": { + "description": "PEM 客户端证书或 ${env:NAME}，须配对配置 tls_cert 与 tls_key。", + "type": "string" + }, + "tls_enabled": { + "default": false, + "description": "是否启用 TLS，默认为 false。", + "type": "boolean" + }, + "tls_key": { + "description": "PEM 客户端私钥或 ${env:NAME}，须配对配置 tls_cert 与 tls_key。 更新时省略保留，空字符串清除；响应中省略字面私钥。", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "tls_max_version": { + "description": "最高 TLS 版本：1.2 或 1.3；空值表示不限制，不能低于最低版本。", + "type": "string" + }, + "tls_min_version": { + "description": "最低 TLS 版本：1.2（默认）或 1.3。", + "type": "string" + }, + "tls_server_name": { + "description": "TLS 握手使用的 SNI / 证书校验主机名；留空时取连接地址中的主机名。", + "type": "string" + }, + "tls_skip_verify": { + "description": "启用 TLS 时是否跳过服务端证书验证。", + "type": "boolean" + }, + "username": { + "description": "认证用户名，支持 ${env:NAME} 引用。", + "type": "string" + } + }, + "type": "object" + }, "DSLokiConfig": { "description": "Loki 数据源配置，TLS 字段继承自 TLSClientConfig。", "properties": { @@ -6902,6 +6969,58 @@ }, "type": "object" }, + "DSMongoDBConfig": { + "description": "诊断数据源连接配置。", + "properties": { + "auth_source": { + "default": "admin", + "description": "认证数据库，默认为 admin。用户名与密码必须同时配置。不支持客户端证书。", + "type": "string" + }, + "password": { + "description": "认证密码，支持 ${env:NAME}。更新时省略保留；显式空字符串清除。响应中省略字面密码。", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "timeout_ms": { + "default": 3000, + "description": "连接超时，单位毫秒；省略默认为 3000。", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "tls_ca": { + "description": "PEM CA 证书或 ${env:NAME} 引用。", + "type": "string" + }, + "tls_enabled": { + "default": false, + "description": "是否启用 TLS，默认为 false。", + "type": "boolean" + }, + "tls_max_version": { + "description": "最高 TLS 版本：1.2 或 1.3；空值表示不限制，不能低于最低版本。", + "type": "string" + }, + "tls_min_version": { + "description": "最低 TLS 版本：1.2（默认）或 1.3。", + "type": "string" + }, + "tls_server_name": { + "description": "TLS 握手使用的 SNI / 证书校验主机名；留空时取连接地址中的主机名。", + "type": "string" + }, + "tls_skip_verify": { + "description": "启用 TLS 时是否跳过服务端证书验证。", + "type": "boolean" + }, + "username": { + "description": "认证用户名，支持 ${env:NAME} 引用。", + "type": "string" + } + }, + "type": "object" + }, "DSMySQLConfig": { "description": "MySQL 数据源配置，TLS 字段继承自 TLSClientConfig。", "properties": { @@ -7019,9 +7138,21 @@ "elasticsearch": { "$ref": "#/components/schemas/DSElasticSearchConfig" }, + "kafka": { + "$ref": "#/components/schemas/DSKafkaConfig", + "x-flashduty-preserve-absence": true + }, "loki": { "$ref": "#/components/schemas/DSLokiConfig" }, + "mongodb_mongod": { + "$ref": "#/components/schemas/DSMongoDBConfig", + "x-flashduty-preserve-absence": true + }, + "mongodb_mongos": { + "$ref": "#/components/schemas/DSMongoDBConfig", + "x-flashduty-preserve-absence": true + }, "mysql": { "$ref": "#/components/schemas/DSMySQLConfig" }, @@ -7034,6 +7165,14 @@ "prometheus": { "$ref": "#/components/schemas/DSPrometheusConfig" }, + "redis_node": { + "$ref": "#/components/schemas/DSRedisNodeConfig", + "x-flashduty-preserve-absence": true + }, + "redis_sentinel": { + "$ref": "#/components/schemas/DSRedisSentinelConfig", + "x-flashduty-preserve-absence": true + }, "sls": { "$ref": "#/components/schemas/DSSLSConfig" }, @@ -7161,6 +7300,56 @@ }, "type": "object" }, + "DSRedisNodeConfig": { + "description": "诊断数据源连接配置。", + "properties": { + "database": { + "default": 0, + "description": "Redis 数据库编号，默认为 0。", + "minimum": 0, + "type": "integer" + }, + "password": { + "description": "认证密码，支持 ${env:NAME}。更新时省略保留；显式空字符串清除。响应中省略字面密码。", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "timeout_ms": { + "default": 3000, + "description": "连接超时，单位毫秒；省略默认为 3000。", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "username": { + "description": "认证用户名，支持 ${env:NAME} 引用。", + "type": "string" + } + }, + "type": "object" + }, + "DSRedisSentinelConfig": { + "description": "诊断数据源连接配置。", + "properties": { + "password": { + "description": "认证密码，支持 ${env:NAME}。更新时省略保留；显式空字符串清除。响应中省略字面密码。", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "timeout_ms": { + "default": 3000, + "description": "连接超时，单位毫秒；省略默认为 3000。", + "maximum": 10000, + "minimum": 1000, + "type": "integer" + }, + "username": { + "description": "认证用户名，支持 ${env:NAME} 引用。", + "type": "string" + } + }, + "type": "object" + }, "DSSLSConfig": { "description": "阿里云日志服务（SLS）数据源配置。", "properties": { @@ -7303,15 +7492,20 @@ "type": "integer" }, "address": { - "description": "连接地址。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 http/https 前缀的 endpoint。", + "description": "连接地址。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 http/https 前缀的 endpoint。 Redis/MongoDB 诊断类型使用单个 host:port（IPv6 加方括号），不接受 URI、userinfo 或查询参数。Kafka 使用 1–32 个不重复、逗号分隔的 host:port 引导地址；payload 不含 broker 列表。规范化后最多 4096 个字符。", + "maxLength": 4096, "type": "string" }, + "alerting_enabled": { + "description": "是否允许告警评估。告警同时要求 enabled=true 且类型支持告警。仅诊断类型固定为 false；false 不阻断非告警查询或工具。", + "type": "boolean" + }, "edge_cluster_name": { "description": "负责使用该数据源评估规则的 Monitors Edge 集群名称。", "type": "string" }, "enabled": { - "description": "数据源是否启用。", + "description": "是否启用业务执行。停用时拒绝业务查询和工具调用；重新启用不改变 alerting_enabled。", "type": "boolean" }, "id": { @@ -7336,10 +7530,10 @@ "type": "null" } ], - "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。`/monit/datasource/list` 响应中恒为 `null`（列表查询不读取 payload 列）；创建/更新/详情响应中会返回。对于 `tencent_cls`，`secret_key` 会被掩码为空字符串，除非其值为 `${env:...}` 引用。" + "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。`/monit/datasource/list` 响应中恒为 `null`（列表查询不读取 payload 列）；创建/更新/详情响应中会返回。对于 `tencent_cls`，`secret_key` 会被掩码为空字符串，除非其值为 `${env:...}` 引用。 诊断类型的 password 和 Kafka tls_key 在响应中省略，${env:...} 引用除外；更新时省略保留已保存的秘密，显式空字符串清除。其他配置字段保持原有行为。" }, "type_ident": { - "description": "数据源类型标识，可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。", + "description": "数据源类型标识。支持：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。", "type": "string" }, "updated_at": { @@ -7358,7 +7552,8 @@ "address", "edge_cluster_name", "updated_at", - "payload" + "payload", + "alerting_enabled" ], "type": "object" }, @@ -7366,7 +7561,7 @@ "description": "查询数据源列表的过滤参数。", "properties": { "type": { - "description": "按数据源类型标识过滤，省略则返回所有类型。可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。", + "description": "数据源类型标识。省略时返回全部类型。支持：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。", "type": "string" } }, @@ -7383,16 +7578,23 @@ "description": "创建或更新数据源的请求体。`id` 仅在更新时必填。`address` 除 Elasticsearch `deployment=cloud` 外均为必填。", "properties": { "address": { - "description": "连接地址。除 `elasticsearch` 的 `deployment: cloud` 部署外均为必填。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 `http(s)://` 前缀的 endpoint；`tencent_cls` 必须为 `cls.tencentcloudapi.com` 或 `cls.internal.tencentcloudapi.com`（要求 Monitors edge >= v0.66.0）。", + "description": "连接地址。除 `elasticsearch` 的 `deployment: cloud` 部署外均为必填。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 `http(s)://` 前缀的 endpoint；`tencent_cls` 必须为 `cls.tencentcloudapi.com` 或 `cls.internal.tencentcloudapi.com`（要求 Monitors edge >= v0.66.0）。 Redis/MongoDB 诊断类型使用单个 host:port（IPv6 加方括号），不接受 URI、userinfo 或查询参数。Kafka 使用 1–32 个不重复、逗号分隔的 host:port 引导地址；payload 不含 broker 列表。规范化后最多 4096 个字符。", + "maxLength": 4096, "type": "string" }, + "alerting_enabled": { + "description": "是否允许数据源用于告警。创建时省略：支持告警的类型默认为 true，仅诊断类型默认为 false；更新时省略保留当前值。null 非法。redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka 不允许 true。有启用规则引用时，关闭用途返回冲突。", + "type": "boolean", + "x-flashduty-preserve-absence": true + }, "edge_cluster_name": { "description": "负责使用该数据源评估规则的 Monitors Edge 集群名称。", "type": "string" }, "enabled": { - "description": "数据源是否启用（参与规则评估）。创建时省略则默认禁用（`false`）。", - "type": "boolean" + "description": "是否启用业务执行。创建时省略默认为 true；更新时省略保留当前值。显式 false 停用执行；null 非法。不改变 alerting_enabled。", + "type": "boolean", + "x-flashduty-preserve-absence": true }, "id": { "description": "数据源 ID。更新时必填，创建时省略。", @@ -7409,10 +7611,10 @@ }, "payload": { "$ref": "#/components/schemas/DSPayload", - "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。" + "description": "类型相关配置块，必须包含与 `type_ident` 匹配的键。 诊断类型的 password 和 Kafka tls_key 在响应中省略，${env:...} 引用除外；更新时省略保留已保存的秘密，显式空字符串清除。其他配置字段保持原有行为。" }, "type_ident": { - "description": "数据源类型标识，可选值：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。", + "description": "数据源类型标识。支持：`prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`。", "type": "string" } }, @@ -7424,6 +7626,86 @@ ], "type": "object" }, + "DatasourceToolInvokeRequest": { + "properties": { + "account_id": { + "description": "可选一致性检查，必须等于认证账户。", + "format": "uint64", + "type": "integer" + }, + "datasource_id": { + "description": "通过 /monit/datasource/list 获取的数据源 ID。", + "format": "uint64", + "minimum": 1, + "type": "integer" + }, + "params": { + "additionalProperties": true, + "description": "工具专属 JSON 参数，省略时为 {}，显式 null 非法。", + "type": "object", + "x-flashduty-raw-json": true + }, + "tool": { + "description": "以数据源类型为前缀的单个工具名，如 mysql.overview。自由 SQL 使用 /monit/query/data；不支持 mysql.query 和 postgres.query。", + "maxLength": 128, + "minLength": 1, + "type": "string" + } + }, + "required": [ + "datasource_id", + "tool" + ], + "type": "object" + }, + "DatasourceToolResult": { + "properties": { + "data": { + "description": "工具专属 JSON 证据，原样保留，不为 null，不包含旧 diagnose 额外信封。", + "not": { + "type": "null" + }, + "x-flashduty-raw-json": true + }, + "datasource_id": { + "description": "通过 /monit/datasource/list 获取的数据源 ID。", + "format": "uint64", + "minimum": 1, + "type": "integer" + }, + "summary": { + "description": "可选非空摘要。", + "type": "string", + "x-flashduty-preserve-absence": true + }, + "tool": { + "description": "执行的工具名，与请求一致。", + "type": "string" + }, + "truncated": { + "$ref": "#/components/schemas/DatasourceToolTruncation", + "x-flashduty-preserve-absence": true + } + }, + "required": [ + "datasource_id", + "tool", + "data" + ], + "type": "object" + }, + "DatasourceToolTruncation": { + "properties": { + "reason": { + "description": "结果截断原因；该对象存在即表示发生截断。", + "type": "string" + } + }, + "required": [ + "reason" + ], + "type": "object" + }, "DeleteFieldRequest": { "properties": { "field_id": { @@ -8274,6 +8556,11 @@ "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。", "example": "The specified parameter template_id is not valid.", "type": "string" + }, + "reason": { + "description": "可选的机器可读拒绝原因，包含数据源工具错误；结合 HTTP 状态及 code 判断。", + "type": "string", + "x-flashduty-preserve-absence": true } }, "required": [ @@ -27611,7 +27898,7 @@ "description": "目标所在主机的服务拓扑（ServiceMap）采集能力与最新状态。上报 agent 不具备 ServiceMap 能力时不返回。" }, "target_kind": { - "description": "Target kind,如 `host`、`mysql`。v1 不支持按 kind 过滤。", + "description": "主机目标类型 host。v1 不支持按 kind 过滤。", "type": "string" }, "target_locator": { @@ -28574,11 +28861,14 @@ "type": "integer" }, "target_kind": { - "description": "可选的 target kind。省略时 webapi 会按当前监控对象路由自动推断。若返回 `ambiguous_target_kind`，请从 `target_kinds` 中选择一个值重试。", + "description": "可选目标类型，仅支持 host，省略时推断。", + "enum": [ + "host" + ], "type": "string" }, "target_locator": { - "description": "监控对象标识(主机名、MySQL 地址等)。最长 256 字节;不允许空白、控制字符或 `|`。", + "description": "主机名，最多 256 字节，不允许空白、控制字符或 |。", "type": "string" } }, @@ -28623,7 +28913,7 @@ "description": "解析出的目标。未传 `target_kind` 且无法根据 locator 唯一推断时，不输出该字段。", "properties": { "kind": { - "description": "解析出的目标类型（target kind），如 `host`、`mysql`；与请求推断或指定的 `target_kind` 一致。", + "description": "解析后的 host 目标类型。", "type": "string" }, "locator": { @@ -28670,11 +28960,14 @@ "type": "integer" }, "target_kind": { - "description": "可选的 target kind;省略时自动推断。", + "description": "可选目标类型，仅支持 host，省略时推断。", + "enum": [ + "host" + ], "type": "string" }, "target_locator": { - "description": "监控对象标识。校验规则与 `/monit/tools/catalog` 相同。", + "description": "主机名，最多 256 字节，不允许空白、控制字符或 |。", "type": "string" }, "tools": { @@ -28799,7 +29092,7 @@ "description": "解析出的目标。未传 `target_kind` 且无法根据 locator 唯一推断时，不输出该字段。", "properties": { "kind": { - "description": "解析出的目标类型（target kind），如 `host`、`mysql`；与请求推断或指定的 `target_kind` 一致。", + "description": "解析后的 host 目标类型。", "type": "string" }, "locator": { @@ -43872,7 +44165,7 @@ }, "/monit/datasource/create": { "post": { - "description": "创建新的监控数据源，`payload` 中须包含对应类型的配置块。", + "description": "创建新的监控数据源，`payload` 中须包含对应类型的配置块。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。", "operationId": "monit-datasource-write-create", "requestBody": { "content": { @@ -43902,6 +44195,7 @@ "application/json": { "example": { "data": { + "alerting_enabled": true, "edge_cluster_name": "default", "enabled": true, "id": 10, @@ -43948,7 +44242,7 @@ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- `type_ident` 必须为以下之一：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`。\n- `edge_cluster_name` 指定使用该数据源进行规则评估的 Monitors Edge 集群。\n- 对于 `elasticsearch`，`payload.elasticsearch.deployment` 须设为 `cloud` 或 `self-managed`。\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。唯一例外是 `payload.tencent_cls.secret_key`：始终掩码为空字符串（`${env:...}` 引用则原样返回）。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- `type_ident` 必须为以下之一：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`、`redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka`。\n- `edge_cluster_name` 指定使用该数据源进行规则评估的 Monitors Edge 集群。\n- 对于 `elasticsearch`，`payload.elasticsearch.deployment` 须设为 `cloud` 或 `self-managed`。\n- 每次调用都会记录到账户审计日志，仅通过凭据字段配置连接凭据。\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-create", "metadata": { "sidebarTitle": "创建数据源" @@ -44028,7 +44322,7 @@ }, "/monit/datasource/info": { "post": { - "description": "通过 ID 获取单个数据源的完整信息，包括 `payload` 配置及其中配置的连接与鉴权信息；请将该响应视为敏感信息，避免记录或转发。", + "description": "通过 ID 获取单个数据源的完整信息，包括 `payload` 配置及其中配置的连接与鉴权信息；请将该响应视为敏感信息，避免记录或转发。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。", "operationId": "monit-datasource-read-info", "requestBody": { "content": { @@ -44051,6 +44345,7 @@ "data": { "account_id": 10023, "address": "http://prometheus.example.com:9090", + "alerting_enabled": true, "edge_cluster_name": "default", "enabled": true, "id": 10, @@ -44106,7 +44401,7 @@ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。唯一例外是 `payload.tencent_cls.secret_key`：始终掩码为空字符串（`${env:...}` 引用则原样返回）。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-info", "metadata": { "sidebarTitle": "查看数据源详情" @@ -44116,7 +44411,7 @@ }, "/monit/datasource/list": { "post": { - "description": "返回当前账户下的所有数据源，可通过 `type_ident` 过滤类型。", + "description": "返回当前账户下的所有数据源，可通过 `type_ident` 过滤类型。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。", "operationId": "monit-datasource-read-list", "requestBody": { "content": { @@ -44140,6 +44435,7 @@ { "account_id": 10023, "address": "http://prometheus.example.com:9090", + "alerting_enabled": true, "edge_cluster_name": "default", "enabled": true, "id": 10, @@ -44189,7 +44485,7 @@ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 省略 `type_ident` 可返回所有类型的数据源。\n- 列表响应中不返回敏感凭证字段（密码、密钥）。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源查看**（`monit`） |\n\n## 使用说明\n\n- 省略 `type_ident` 可返回所有类型的数据源。\n- 列表响应中不返回敏感凭证字段（密码、密钥）。\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-read-list", "metadata": { "sidebarTitle": "查询数据源列表" @@ -44369,9 +44665,179 @@ } } }, + "/monit/datasource/tools/invoke": { + "post": { + "description": "对已配置的数据源执行单个确定性工具。要求集群所有当前在线可路由 Edge 会话支持 v0.71.0 基础 invoke 协议；具体工具可能需要更新实现。不提供工具目录、自动重放或 Agent/旧 diagnose 回退。请求体上限 128 KiB，完整成功响应上限 1 MiB，工具超时最多 25 秒。", + "operationId": "monit-datasource-tools-invoke", + "requestBody": { + "content": { + "application/json": { + "example": { + "datasource_id": 10, + "params": {}, + "tool": "mysql.overview" + }, + "schema": { + "$ref": "#/components/schemas/DatasourceToolInvokeRequest" + } + } + }, + "required": true + }, + "responses": { + "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": [ + { + "$ref": "#/components/schemas/SuccessEnvelope" + }, + { + "properties": { + "data": { + "$ref": "#/components/schemas/DatasourceToolResult" + } + }, + "type": "object" + } + ] + } + } + }, + "description": "成功" + }, + "400": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：invalid_request, tool_not_supported, datasource_error." + }, + "401": { + "$ref": "#/components/responses/Unauthorized" + }, + "403": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：access_denied." + }, + "404": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：datasource_not_found." + }, + "409": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：datasource_disabled, datasource_in_use." + }, + "413": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：source_too_large, result_too_large." + }, + "429": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：overloaded." + }, + "499": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：canceled." + }, + "500": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：internal." + }, + "503": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：no_active_edge, edge_upgrade_required, mixed_edge_versions." + }, + "504": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ErrorResponse" + } + } + }, + "description": "标准 HTTP 错误；error.reason：timeout." + } + }, + "summary": "调用数据源工具", + "tags": [ + "Monitors/Data sources" + ], + "x-mint": { + "content": "通过 `/monit/datasource/list` 获取数据源 ID。停用数据源返回 `datasource_disabled`，`alerting_enabled=false` 不阻断工具。错误使用非 2xx HTTP 状态和 `error.code`、`error.message`、`error.reason`。`tool_not_supported` 表示选中的执行端未提供该工具，不表示厂商权限不足。禁止自动切换 Edge 或回退旧 diagnose 重试。", + "href": "/zh/api-reference/monitors/data-sources/monit-datasource-tools-invoke", + "metadata": { + "sidebarTitle": "调用数据源工具" + } + } + } + }, "/monit/datasource/update": { "post": { - "description": "更新已有数据源，需提供 `id` 及待修改的字段。", + "description": "更新已有数据源，需提供 `id` 及待修改的字段。 支持诊断类型 redis_node、redis_sentinel、mongodb_mongod、mongodb_mongos 和 kafka；enabled 与 alerting_enabled 相互独立。", "operationId": "monit-datasource-write-update", "requestBody": { "content": { @@ -44402,6 +44868,7 @@ "application/json": { "example": { "data": { + "alerting_enabled": true, "edge_cluster_name": "default", "enabled": true, "id": 10, @@ -44448,7 +44915,7 @@ "Monitors/告警数据源" ], "x-mint": { - "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，请不要把敏感信息放在请求字段中。\n\n## 凭据字段\n\n`info` / `create` / `update` 的响应会按原样返回 `payload` 配置——`password`、`basic_auth_password`、`api_key`、`service_token`、`access_key_secret`、`tls_key`、`tls_key_pwd` 等字段均如实返回，不做脱敏。唯一例外是 `payload.tencent_cls.secret_key`：始终掩码为空字符串（`${env:...}` 引用则原样返回）。请将这些响应视为敏感信息：避免记录日志或转发给第三方。", + "content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **数据源管理**（`monit`） |\n\n## 使用说明\n\n- 每次调用都会记录到账户审计日志，仅通过凭据字段配置连接凭据。\n\n完整支持类型与凭据行为见请求/响应 Schema。仅诊断类型不能启用告警。创建时省略 enabled 默认为 true，更新时省略保留当前值；enabled 或 alerting_enabled 的显式 null 非法。诊断密码及 Kafka 私钥在响应中省略，环境变量引用除外；更新时省略秘密字段保留原值，空字符串清除。其他数据源凭据可能返回，应作为敏感数据处理。", "href": "/zh/api-reference/monitors/data-sources/monit-datasource-write-update", "metadata": { "sidebarTitle": "更新数据源" @@ -44581,7 +45048,8 @@ }, "/monit/query/diagnose": { "post": { - "description": "执行同步诊断查询(Loki/VictoriaLogs 使用 `log_patterns`,Prometheus 使用 `metric_trends`)。Flashduty AI SRE 用于日志模式聚类与时间序列趋势分析。长耗时——最长可达 35 秒。", + "deprecated": true, + "description": "执行同步诊断查询(Loki/VictoriaLogs 使用 `log_patterns`,Prometheus 使用 `metric_trends`)。Flashduty AI SRE 用于日志模式聚类与时间序列趋势分析。长耗时——最长可达 35 秒。 已弃用：迁移到 /monit/datasource/tools/invoke 的 prometheus.metric_trends、loki.log_patterns 或 victorialogs.log_patterns。为现有消费者保留，旧请求与响应保持不变。", "operationId": "monit-read-query-diagnose", "requestBody": { "content": { @@ -47202,7 +47670,7 @@ }, "/monit/targets": { "post": { - "description": "列出当前租户下被 monit-agent 路由投影所观测到的监控对象。支持 `target_locator` 前缀搜索与游标分页。用于为 `/monit/tools/catalog` 与 `/monit/tools/invoke` 选择 `target_locator`。", + "description": "列出当前租户下被 monit-agent 路由投影所观测到的监控对象。支持 `target_locator` 前缀搜索与游标分页。用于为 `/monit/tools/catalog` 与 `/monit/tools/invoke` 选择 `target_locator`。 Agent 目标仅支持 host。远端数据源取证使用 /monit/datasource/tools/invoke 和 datasource_id。", "operationId": "monit-read-targets-list", "requestBody": { "content": { @@ -47286,7 +47754,7 @@ }, "/monit/tools/catalog": { "post": { - "description": "根据 `target_locator`(host、mysql 等)查询该监控对象上 monit-agent 当前暴露的工具能力。返回每个工具的名称、描述以及 JSON-Schema `input_schema`。配合 `/monit/tools/invoke` 驱动 AI-SRE 的工具调用。", + "description": "根据 `target_locator`(host)查询该监控对象上 monit-agent 当前暴露的工具能力。返回每个工具的名称、描述以及 JSON-Schema `input_schema`。配合 `/monit/tools/invoke` 驱动 AI-SRE 的工具调用。 Agent 目标仅支持 host。远端数据源取证使用 /monit/datasource/tools/invoke 和 datasource_id。", "operationId": "monit-read-tools-catalog", "requestBody": { "content": { @@ -47395,7 +47863,7 @@ }, "/monit/tools/invoke": { "post": { - "description": "在单个监控对象上并发调用至多 8 个 monit-agent 工具。结果按入参 `tools` 数组顺序返回。长耗时——单个工具在 Agent 上有自己的超时,整体请求可能耗时数十秒。", + "description": "在单个监控对象上并发调用至多 8 个 monit-agent 工具。结果按入参 `tools` 数组顺序返回。长耗时——单个工具在 Agent 上有自己的超时,整体请求可能耗时数十秒。 Agent 目标仅支持 host。远端数据源取证使用 /monit/datasource/tools/invoke 和 datasource_id。", "operationId": "monit-read-tools-invoke", "requestBody": { "content": { @@ -63021,4 +63489,4 @@ "name": "AI SRE/产物" } ] -} \ No newline at end of file +} From 8f406e7bf738795487666f77489eff40ca64e739 Mon Sep 17 00:00:00 2001 From: ysyneu Date: Sun, 6 Sep 2026 01:33:35 -0700 Subject: [PATCH 2/2] docs(monit): use the zh nav tag for datasource tools invoke in zh specs --- api-reference/monitors.openapi.zh.json | 2 +- api-reference/openapi.zh.json | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/api-reference/monitors.openapi.zh.json b/api-reference/monitors.openapi.zh.json index 8fe9096f..783f0cdc 100644 --- a/api-reference/monitors.openapi.zh.json +++ b/api-reference/monitors.openapi.zh.json @@ -3857,7 +3857,7 @@ }, "summary": "调用数据源工具", "tags": [ - "Monitors/Data sources" + "Monitors/告警数据源" ], "x-mint": { "content": "通过 `/monit/datasource/list` 获取数据源 ID。停用数据源返回 `datasource_disabled`，`alerting_enabled=false` 不阻断工具。错误使用非 2xx HTTP 状态和 `error.code`、`error.message`、`error.reason`。`tool_not_supported` 表示选中的执行端未提供该工具，不表示厂商权限不足。禁止自动切换 Edge 或回退旧 diagnose 重试。", diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 7b9f5a6a..862ecccc 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -44824,7 +44824,7 @@ }, "summary": "调用数据源工具", "tags": [ - "Monitors/Data sources" + "Monitors/告警数据源" ], "x-mint": { "content": "通过 `/monit/datasource/list` 获取数据源 ID。停用数据源返回 `datasource_disabled`，`alerting_enabled=false` 不阻断工具。错误使用非 2xx HTTP 状态和 `error.code`、`error.message`、`error.reason`。`tool_not_supported` 表示选中的执行端未提供该工具，不表示厂商权限不足。禁止自动切换 Edge 或回退旧 diagnose 重试。",