diff --git a/api-reference/monitors.openapi.en.json b/api-reference/monitors.openapi.en.json index 145d7dab..bb59ed9f 100644 --- a/api-reference/monitors.openapi.en.json +++ b/api-reference/monitors.openapi.en.json @@ -5923,6 +5923,7 @@ "items": { "$ref": "#/components/schemas/InvestigationTarget" }, + "maxItems": 20, "description": "Drill-down entries linked from the alert event detail page; at most 20 items, duplicates rejected. On update the field is presence-based: omit it to keep the current value, pass `[]` to clear.", "x-flashduty-preserve-absence": true }, @@ -6223,14 +6224,23 @@ }, "InvestigationTarget": { "type": "object", - "description": "Drill-down entry linked to alert events. A deliberately closed tagged union: new kinds require explicit server support.", + "description": "Alert-event drill-down entry. A deliberately closed tagged union: new kinds require explicit server support, and unknown fields inside a target are rejected.", "properties": { "kind": { "type": "string", "enum": [ - "dashboard" + "dashboard", + "query" ], - "description": "Entry type; currently only `dashboard` is supported." + "description": "Entry kind: `dashboard` opens a dashboard panel, `query` opens an Explore query. It decides whether `dashboard` or `query` must be supplied; supplying the other one is rejected." + }, + "time_range": { + "$ref": "#/components/schemas/InvestigationTimeRange", + "description": "Window around the event time, required on every saved entry. A zero-length window is rejected; defaults belong to the editor." + }, + "query": { + "$ref": "#/components/schemas/QueryInvestigationTarget", + "description": "Configuration for the `query` kind; required when `kind` is `query`, and rejected when `kind` is `dashboard`." }, "dashboard": { "$ref": "#/components/schemas/DashboardInvestigationTarget", @@ -6238,7 +6248,8 @@ } }, "required": [ - "kind" + "kind", + "time_range" ] }, "DashboardInvestigationTarget": { @@ -6253,37 +6264,103 @@ "type": "string", "description": "Panel ID inside the dashboard; must be a canonical UUIDv7. Optional." }, - "variable_bindings": { + "variables": { "type": "object", "additionalProperties": { - "$ref": "#/components/schemas/InvestigationVariableBinding" + "type": "string" }, - "description": "Dashboard variable bindings, keyed by dashboard variable name." + "description": "Dashboard variable values, keyed by variable name. Values may reference event labels through `{{ }}` templates; defaults to an empty object." + } + }, + "required": [ + "dashboard_id", + "variables" + ] + }, + "InvestigationTimeRange": { + "type": "object", + "description": "Window around the alert event time, expressed as two offsets. Both directions must be non-negative and at least one must be greater than zero, so an entry never resolves to an empty window.", + "properties": { + "before_seconds": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740, + "description": "Seconds to look back from the event time." + }, + "after_seconds": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740, + "description": "Seconds to look forward from the event time, so behaviour after the event stays visible." } }, "required": [ - "dashboard_id" + "before_seconds", + "after_seconds" ] }, - "InvestigationVariableBinding": { + "QueryInvestigationTarget": { "type": "object", - "description": "Binding between a dashboard variable and alert event data.", + "description": "Explore query used by a `query` drill-down entry. The expression may reference event labels through `{{ }}` templates, while `args` values may not.", "properties": { - "source": { + "datasource_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "description": "Data source the query runs against." + }, + "query": { + "$ref": "#/components/schemas/DashboardQuery", + "description": "Query payload." + } + }, + "required": [ + "datasource_id", + "query" + ] + }, + "DashboardQuery": { + "type": "object", + "description": "Query payload shared by dashboards and drill-down entries.", + "properties": { + "mode": { "type": "string", "enum": [ - "event_label" + "instant", + "range", + "window" ], - "description": "Where the bound value comes from; currently only `event_label` (the alert event's label value) is supported." + "description": "Evaluation mode: `instant` evaluates at a single timestamp, `range` evaluates a stepped series, `window` returns raw rows inside a time window." }, - "key": { + "expr": { "type": "string", - "description": "Alert event label name; must follow Prometheus label naming rules and must not be a reserved label." + "description": "Query expression in the target data source's language. May reference event labels through `{{ }}` templates." + }, + "args": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Named query arguments; defaults to an empty object. Values are passed through verbatim and must not contain `{{ }}` templates." + }, + "min_step_seconds": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 1, + "maximum": 9007199254740, + "description": "Minimum step, in seconds. Only accepted when `mode` is `range`, and must be greater than zero; omit or pass null to let the server decide." } }, "required": [ - "source", - "key" + "mode", + "expr", + "args" ] } } diff --git a/api-reference/monitors.openapi.zh.json b/api-reference/monitors.openapi.zh.json index 4cea844d..d5aa2d4d 100644 --- a/api-reference/monitors.openapi.zh.json +++ b/api-reference/monitors.openapi.zh.json @@ -5923,6 +5923,7 @@ "items": { "$ref": "#/components/schemas/InvestigationTarget" }, + "maxItems": 20, "description": "告警事件详情页关联的排障入口列表,最多 20 项,不允许重复。更新接口中该字段按 presence 处理:省略时保留原配置,传 `[]` 清空。", "x-flashduty-preserve-absence": true }, @@ -6223,14 +6224,23 @@ }, "InvestigationTarget": { "type": "object", - "description": "告警事件的关联排障入口,为封闭的 tagged union:新增类型需服务端显式支持。", + "description": "告警事件的关联排障入口,为封闭的 tagged union:新增类型需服务端显式支持,入口内出现未知字段会被拒绝。", "properties": { "kind": { "type": "string", "enum": [ - "dashboard" + "dashboard", + "query" ], - "description": "排障入口类型,目前仅支持 `dashboard`。" + "description": "入口类型:`dashboard` 打开仪表盘面板,`query` 打开 Explore 查询。它决定必须提供 `dashboard` 还是 `query`,提供另一个会被拒绝。" + }, + "time_range": { + "$ref": "#/components/schemas/InvestigationTimeRange", + "description": "事件时间前后的取数窗口,每个已保存的入口都必填。长度为 0 的窗口会被拒绝;默认值由前端编辑器提供。" + }, + "query": { + "$ref": "#/components/schemas/QueryInvestigationTarget", + "description": "`query` 类型的入口配置;`kind` 为 `query` 时必填,`kind` 为 `dashboard` 时不允许出现。" }, "dashboard": { "$ref": "#/components/schemas/DashboardInvestigationTarget", @@ -6238,7 +6248,8 @@ } }, "required": [ - "kind" + "kind", + "time_range" ] }, "DashboardInvestigationTarget": { @@ -6253,37 +6264,103 @@ "type": "string", "description": "仪表盘内目标面板 ID,须为规范的 UUIDv7;可选。" }, - "variable_bindings": { + "variables": { "type": "object", "additionalProperties": { - "$ref": "#/components/schemas/InvestigationVariableBinding" + "type": "string" }, - "description": "仪表盘变量绑定,键为仪表盘变量名。" + "description": "仪表盘变量取值,键为变量名。值可通过 `{{ }}` 模板引用事件标签;默认空对象。" + } + }, + "required": [ + "dashboard_id", + "variables" + ] + }, + "InvestigationTimeRange": { + "type": "object", + "description": "以两个偏移量表示告警事件时间前后的取数窗口。两个方向都必须非负,且至少一个大于 0,因此入口不会解析出空窗口。", + "properties": { + "before_seconds": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740, + "description": "相对事件时间向前回溯的秒数。" + }, + "after_seconds": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740, + "description": "相对事件时间向后延伸的秒数,用于保留事件发生后的表现。" } }, "required": [ - "dashboard_id" + "before_seconds", + "after_seconds" ] }, - "InvestigationVariableBinding": { + "QueryInvestigationTarget": { "type": "object", - "description": "仪表盘变量与告警事件数据的绑定。", + "description": "`query` 类型入口使用的 Explore 查询。表达式可通过 `{{ }}` 模板引用事件标签,`args` 的值不允许包含模板。", "properties": { - "source": { + "datasource_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "description": "查询所用的数据源。" + }, + "query": { + "$ref": "#/components/schemas/DashboardQuery", + "description": "查询内容。" + } + }, + "required": [ + "datasource_id", + "query" + ] + }, + "DashboardQuery": { + "type": "object", + "description": "仪表盘与排障入口共用的查询内容。", + "properties": { + "mode": { "type": "string", "enum": [ - "event_label" + "instant", + "range", + "window" ], - "description": "绑定值来源,目前仅支持 `event_label`(取告警事件的标签值)。" + "description": "求值模式:`instant` 在单个时间点求值,`range` 求值一条按步长采样的曲线,`window` 返回时间窗口内的原始数据。" }, - "key": { + "expr": { "type": "string", - "description": "告警事件标签名,须符合 Prometheus 标签命名规则,且不能使用保留标签。" + "description": "目标数据源语法下的查询表达式,可通过 `{{ }}` 模板引用事件标签。" + }, + "args": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "命名查询参数,默认空对象。值按原样透传,不允许包含 `{{ }}` 模板。" + }, + "min_step_seconds": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 1, + "maximum": 9007199254740, + "description": "最小步长(秒)。仅在 `mode` 为 `range` 时可用,且必须大于 0;省略或传 null 由服务端决定。" } }, "required": [ - "source", - "key" + "mode", + "expr", + "args" ] } } diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 6f739801..9dd1b6dc 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -3494,7 +3494,8 @@ }, "limit": { "default": 20, - "description": "Page size.", + "description": "Page size. Values below 1 fall back to 20; values above 200 are capped at 200.", + "maximum": 200, "type": "integer" }, "p": { @@ -28641,6 +28642,7 @@ "items": { "$ref": "#/components/schemas/InvestigationTarget" }, + "maxItems": 20, "description": "Drill-down entries linked from the alert event detail page; at most 20 items, duplicates rejected. On update the field is presence-based: omit it to keep the current value, pass `[]` to clear.", "x-flashduty-preserve-absence": true }, @@ -28941,14 +28943,23 @@ }, "InvestigationTarget": { "type": "object", - "description": "Drill-down entry linked to alert events. A deliberately closed tagged union: new kinds require explicit server support.", + "description": "Alert-event drill-down entry. A deliberately closed tagged union: new kinds require explicit server support, and unknown fields inside a target are rejected.", "properties": { "kind": { "type": "string", "enum": [ - "dashboard" + "dashboard", + "query" ], - "description": "Entry type; currently only `dashboard` is supported." + "description": "Entry kind: `dashboard` opens a dashboard panel, `query` opens an Explore query. It decides whether `dashboard` or `query` must be supplied; supplying the other one is rejected." + }, + "time_range": { + "$ref": "#/components/schemas/InvestigationTimeRange", + "description": "Window around the event time, required on every saved entry. A zero-length window is rejected; defaults belong to the editor." + }, + "query": { + "$ref": "#/components/schemas/QueryInvestigationTarget", + "description": "Configuration for the `query` kind; required when `kind` is `query`, and rejected when `kind` is `dashboard`." }, "dashboard": { "$ref": "#/components/schemas/DashboardInvestigationTarget", @@ -28956,7 +28967,8 @@ } }, "required": [ - "kind" + "kind", + "time_range" ] }, "DashboardInvestigationTarget": { @@ -28971,37 +28983,103 @@ "type": "string", "description": "Panel ID inside the dashboard; must be a canonical UUIDv7. Optional." }, - "variable_bindings": { + "variables": { "type": "object", "additionalProperties": { - "$ref": "#/components/schemas/InvestigationVariableBinding" + "type": "string" }, - "description": "Dashboard variable bindings, keyed by dashboard variable name." + "description": "Dashboard variable values, keyed by variable name. Values may reference event labels through `{{ }}` templates; defaults to an empty object." } }, "required": [ - "dashboard_id" + "dashboard_id", + "variables" ] }, - "InvestigationVariableBinding": { + "InvestigationTimeRange": { "type": "object", - "description": "Binding between a dashboard variable and alert event data.", + "description": "Window around the alert event time, expressed as two offsets. Both directions must be non-negative and at least one must be greater than zero, so an entry never resolves to an empty window.", "properties": { - "source": { + "before_seconds": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740, + "description": "Seconds to look back from the event time." + }, + "after_seconds": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740, + "description": "Seconds to look forward from the event time, so behaviour after the event stays visible." + } + }, + "required": [ + "before_seconds", + "after_seconds" + ] + }, + "QueryInvestigationTarget": { + "type": "object", + "description": "Explore query used by a `query` drill-down entry. The expression may reference event labels through `{{ }}` templates, while `args` values may not.", + "properties": { + "datasource_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "description": "Data source the query runs against." + }, + "query": { + "$ref": "#/components/schemas/DashboardQuery", + "description": "Query payload." + } + }, + "required": [ + "datasource_id", + "query" + ] + }, + "DashboardQuery": { + "type": "object", + "description": "Query payload shared by dashboards and drill-down entries.", + "properties": { + "mode": { "type": "string", "enum": [ - "event_label" + "instant", + "range", + "window" ], - "description": "Where the bound value comes from; currently only `event_label` (the alert event's label value) is supported." + "description": "Evaluation mode: `instant` evaluates at a single timestamp, `range` evaluates a stepped series, `window` returns raw rows inside a time window." }, - "key": { + "expr": { "type": "string", - "description": "Alert event label name; must follow Prometheus label naming rules and must not be a reserved label." + "description": "Query expression in the target data source's language. May reference event labels through `{{ }}` templates." + }, + "args": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "Named query arguments; defaults to an empty object. Values are passed through verbatim and must not contain `{{ }}` templates." + }, + "min_step_seconds": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 1, + "maximum": 9007199254740, + "description": "Minimum step, in seconds. Only accepted when `mode` is `range`, and must be greater than zero; omit or pass null to let the server decide." } }, "required": [ - "source", - "key" + "mode", + "expr", + "args" ] }, "MemberNotifyRequest": { diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 401b058d..bf27ecab 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -3494,7 +3494,8 @@ }, "limit": { "default": 20, - "description": "每页数量。", + "description": "每页数量。小于 1 时回退为 20,大于 200 时按 200 处理。", + "maximum": 200, "type": "integer" }, "p": { @@ -28641,6 +28642,7 @@ "items": { "$ref": "#/components/schemas/InvestigationTarget" }, + "maxItems": 20, "description": "告警事件详情页关联的排障入口列表,最多 20 项,不允许重复。更新接口中该字段按 presence 处理:省略时保留原配置,传 `[]` 清空。", "x-flashduty-preserve-absence": true }, @@ -28941,14 +28943,23 @@ }, "InvestigationTarget": { "type": "object", - "description": "告警事件的关联排障入口,为封闭的 tagged union:新增类型需服务端显式支持。", + "description": "告警事件的关联排障入口,为封闭的 tagged union:新增类型需服务端显式支持,入口内出现未知字段会被拒绝。", "properties": { "kind": { "type": "string", "enum": [ - "dashboard" + "dashboard", + "query" ], - "description": "排障入口类型,目前仅支持 `dashboard`。" + "description": "入口类型:`dashboard` 打开仪表盘面板,`query` 打开 Explore 查询。它决定必须提供 `dashboard` 还是 `query`,提供另一个会被拒绝。" + }, + "time_range": { + "$ref": "#/components/schemas/InvestigationTimeRange", + "description": "事件时间前后的取数窗口,每个已保存的入口都必填。长度为 0 的窗口会被拒绝;默认值由前端编辑器提供。" + }, + "query": { + "$ref": "#/components/schemas/QueryInvestigationTarget", + "description": "`query` 类型的入口配置;`kind` 为 `query` 时必填,`kind` 为 `dashboard` 时不允许出现。" }, "dashboard": { "$ref": "#/components/schemas/DashboardInvestigationTarget", @@ -28956,7 +28967,8 @@ } }, "required": [ - "kind" + "kind", + "time_range" ] }, "DashboardInvestigationTarget": { @@ -28971,37 +28983,103 @@ "type": "string", "description": "仪表盘内目标面板 ID,须为规范的 UUIDv7;可选。" }, - "variable_bindings": { + "variables": { "type": "object", "additionalProperties": { - "$ref": "#/components/schemas/InvestigationVariableBinding" + "type": "string" }, - "description": "仪表盘变量绑定,键为仪表盘变量名。" + "description": "仪表盘变量取值,键为变量名。值可通过 `{{ }}` 模板引用事件标签;默认空对象。" } }, "required": [ - "dashboard_id" + "dashboard_id", + "variables" ] }, - "InvestigationVariableBinding": { + "InvestigationTimeRange": { "type": "object", - "description": "仪表盘变量与告警事件数据的绑定。", + "description": "以两个偏移量表示告警事件时间前后的取数窗口。两个方向都必须非负,且至少一个大于 0,因此入口不会解析出空窗口。", "properties": { - "source": { + "before_seconds": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740, + "description": "相对事件时间向前回溯的秒数。" + }, + "after_seconds": { + "type": "integer", + "format": "int64", + "minimum": 0, + "maximum": 9007199254740, + "description": "相对事件时间向后延伸的秒数,用于保留事件发生后的表现。" + } + }, + "required": [ + "before_seconds", + "after_seconds" + ] + }, + "QueryInvestigationTarget": { + "type": "object", + "description": "`query` 类型入口使用的 Explore 查询。表达式可通过 `{{ }}` 模板引用事件标签,`args` 的值不允许包含模板。", + "properties": { + "datasource_id": { + "type": "integer", + "format": "int64", + "minimum": 1, + "maximum": 9007199254740991, + "description": "查询所用的数据源。" + }, + "query": { + "$ref": "#/components/schemas/DashboardQuery", + "description": "查询内容。" + } + }, + "required": [ + "datasource_id", + "query" + ] + }, + "DashboardQuery": { + "type": "object", + "description": "仪表盘与排障入口共用的查询内容。", + "properties": { + "mode": { "type": "string", "enum": [ - "event_label" + "instant", + "range", + "window" ], - "description": "绑定值来源,目前仅支持 `event_label`(取告警事件的标签值)。" + "description": "求值模式:`instant` 在单个时间点求值,`range` 求值一条按步长采样的曲线,`window` 返回时间窗口内的原始数据。" }, - "key": { + "expr": { "type": "string", - "description": "告警事件标签名,须符合 Prometheus 标签命名规则,且不能使用保留标签。" + "description": "目标数据源语法下的查询表达式,可通过 `{{ }}` 模板引用事件标签。" + }, + "args": { + "type": "object", + "additionalProperties": { + "type": "string" + }, + "description": "命名查询参数,默认空对象。值按原样透传,不允许包含 `{{ }}` 模板。" + }, + "min_step_seconds": { + "type": [ + "integer", + "null" + ], + "format": "int64", + "minimum": 1, + "maximum": 9007199254740, + "description": "最小步长(秒)。仅在 `mode` 为 `range` 时可用,且必须大于 0;省略或传 null 由服务端决定。" } }, "required": [ - "source", - "key" + "mode", + "expr", + "args" ] }, "MemberNotifyRequest": { diff --git a/api-reference/safari.openapi.en.json b/api-reference/safari.openapi.en.json index 8c513b5e..f47afcc5 100644 --- a/api-reference/safari.openapi.en.json +++ b/api-reference/safari.openapi.en.json @@ -5816,7 +5816,8 @@ "limit": { "type": "integer", "default": 20, - "description": "Page size." + "description": "Page size. Values below 1 fall back to 20; values above 200 are capped at 200.", + "maximum": 200 }, "scope": { "type": "string", diff --git a/api-reference/safari.openapi.zh.json b/api-reference/safari.openapi.zh.json index be93ac17..98bd246b 100644 --- a/api-reference/safari.openapi.zh.json +++ b/api-reference/safari.openapi.zh.json @@ -5816,7 +5816,8 @@ "limit": { "type": "integer", "default": 20, - "description": "每页数量。" + "description": "每页数量。小于 1 时回退为 20,大于 200 时按 200 处理。", + "maximum": 200 }, "scope": { "type": "string",