Skip to content

docs(api): daily audit 2026-09-16 — repair the investigation_targets drill-down contract, cap the Automation rule list page size #405

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ysyneu merged 1 commit into from
Sep 16, 2026
Merged

docs(api): daily audit 2026-09-16 — repair the investigation_targets drill-down contract, cap the Automation rule list page size #405

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 94 additions & 17 deletions api-reference/monitors.openapi.en.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
},
Expand Down Expand Up @@ -6223,22 +6224,32 @@
},
"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",
"description": "Configuration for the `dashboard` kind; required when `kind` is `dashboard`."
}
},
"required": [
"kind"
"kind",
"time_range"
]
},
"DashboardInvestigationTarget": {
Expand All @@ -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"
]
}
}
Expand Down
111 changes: 94 additions & 17 deletions api-reference/monitors.openapi.zh.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5923,6 +5923,7 @@
"items": {
"$ref": "#/components/schemas/InvestigationTarget"
},
"maxItems": 20,
"description": "告警事件详情页关联的排障入口列表，最多 20 项，不允许重复。更新接口中该字段按 presence 处理：省略时保留原配置，传 `[]` 清空。",
"x-flashduty-preserve-absence": true
},
Expand Down Expand Up @@ -6223,22 +6224,32 @@
},
"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",
"description": "`dashboard` 类型的入口配置；`kind` 为 `dashboard` 时必填。"
}
},
"required": [
"kind"
"kind",
"time_range"
]
},
"DashboardInvestigationTarget": {
Expand All @@ -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"
]
}
}
Expand Down
Loading
Loading