diff --git a/internal/cli/monit_query.go b/internal/cli/monit_query.go index 0283244..db70eb2 100644 --- a/internal/cli/monit_query.go +++ b/internal/cli/monit_query.go @@ -12,7 +12,7 @@ import ( ) func newMonitQueryCmd() *cobra.Command { - cmd := newGroupCmd("monit-query", "Probe monit-backed datasources (9 types via data; diagnose/rows support prometheus|victorialogs|loki|mysql)") + cmd := newGroupCmd("monit-query", "Probe monit-backed datasources (9 types via data; diagnose: loki|victorialogs log patterns, prometheus metric trends)") cmd.AddCommand(newMonitQueryDiagnoseCmd()) cmd.AddCommand(newMonitQueryDataCmd()) cmd.AddCommand(newMonitQueryRowsCmd()) diff --git a/skills/flashduty/SKILL.md b/skills/flashduty/SKILL.md index c215055..faf31dd 100644 --- a/skills/flashduty/SKILL.md +++ b/skills/flashduty/SKILL.md @@ -69,11 +69,15 @@ Some asks span several commands. For those the skill ships a script that fetches | post-mortem / postmortem 复盘 / 复盘报告 / 复盘模板 / post-incident review / RCA report | **`reference/postmortem.md`** | | alert / 告警 / dedup 去重 / alert fields 告警字段 / alert pipeline 告警管道 | **`reference/alert.md`** | | change / 变更 / deployment 部署 / release 发布 / correlated change 变更关联 / what changed | **`reference/change.md`** | -| monitor / 监控 / alert rule 告警规则 / datasource 数据源 / inspection 巡检 / rule config 规则配置 | **`reference/monit.md`** | +| monitor / 监控 / inspection 巡检 — unsure which Flashmonit surface | **`reference/monit.md`** (index; routes to the four below) | +| alert rule 告警规则 / rule config 规则配置 / rule folder 规则文件夹 / rule export 规则导出 | **`reference/monit-rule.md`** | +| datasource 数据源 = a system Flashmonit queries (Prometheus / Loki / SQL / SLS) / connect a datasource 连接数据源 / SLS project / logstore | **`reference/monit-datasource.md`** | +| service map 服务地图 / topology 拓扑 / service dependencies 服务依赖 / agent fleet 探针队列 | **`reference/monit-servicemap.md`** | +| store ruleset 规则集 / 规则模板库 | **`reference/monit-ruleset.md`** | | automation / 自动化 / 定时 AI SRE / scheduled AI task / daily brief / weekly report / webhook trigger / POST trigger / chat-created automation | **`reference/automation.md`** | | metric/log query / 指标查询 / 日志查询 / PromQL / LogsQL / SQL / trend 趋势 / log clustering 日志聚类 / datasource RCA 数据源排查 | **`reference/monit-query.md`** | | host diagnostics / 主机诊断 / on-box / process 进程 / load 负载 / lock 锁 / slow query 慢查询 / mysql / reachability 可达性 | **`reference/monit-agent.md`** | -| channel / 协作空间 / collaboration space / 频道 / integration 集成 / alert grouping 告警分组 | **`reference/channel.md`** | +| channel / 协作空间 / collaboration space / 频道 / integration 集成 / 告警来源 alert source / alert grouping 告警分组 | **`reference/channel.md`** | | dispatch rule 分派策略 / 分派规则 / escalation rule 升级规则 / notify layers 通知层级 / who gets paged | **`reference/escalation.md`** | | silence 静默 / 屏蔽 / inhibit 抑制 / drop rule 丢弃 / noise reduction 降噪 / maintenance silence 维护窗口静默 | **`reference/noise.md`** | | enrichment / 数据加工 / 富化 / label mapping 字段映射 / extraction 提取 / mapping schema 集成 schema | **`reference/enrichment.md`** | diff --git a/skills/flashduty/reference/monit-datasource.md b/skills/flashduty/reference/monit-datasource.md new file mode 100644 index 0000000..ae5c86d --- /dev/null +++ b/skills/flashduty/reference/monit-datasource.md @@ -0,0 +1,80 @@ +# fduty monit — datasources + +Prereq: `SKILL.md` + `reference/monit.md` read. Datasources are what every other Flashmonit surface points at: a rule evaluates one, a probe queries one. + +## Route here when + +"数据源 / 连接数据源 / SLS project / logstore" or "datasource / connect a datasource / SLS discovery" → this card, **when the datasource is something Flashmonit queries** (Prometheus, Loki, VictoriaLogs, SQL engines, SLS). + +**"Datasource" is two unrelated things in this product — check which one the user means.** This card is `POST /monit/datasource/*`: the Flashmonit config surface, i.e. the systems Flashmonit *queries*. On-call has its own, older use of the word: the top-level `datasource` group is `POST /datasource/*` and holds IM-integration plumbing (`fduty datasource im-war-room-enabled-list`, `fduty datasource im-person-try-link`), while the On-call **integrations** that *receive* alerts into a channel live in `reference/channel.md`. So 接入告警 / 集成 / 告警来源 → On-call, not here; "连一个 Prometheus / Loki / MySQL 上来查" → here. + +**Mutating:** `datasource-create`, `datasource-update`, `datasource-delete` — confirm before running. **`datasource-delete` is irreversible**; confirm the target with `datasource-info` first. + +## Intent → verb + +| want | verb | +|---|---| +| list all datasources (by type) | `datasource-list` | +| datasource detail | `datasource-info` | +| create / update a datasource | `datasource-create` / `datasource-update` | +| delete a datasource | `datasource-delete` | +| SLS project/logstore discovery | `datasource-sls-projects` / `datasource-sls-logstores` | + +## Gotchas + +- **Datasource name is not guessable.** A `can not find datasource` 400 means the name is wrong — re-run `datasource-list` and copy the exact `Name`. Never invent variants. +- **`datasource-info` (and the `datasource-create`/`datasource-update` responses) return credentials exactly as configured — nothing is masked.** The `payload` object includes whatever passwords, API keys, tokens, and similar fields were set, in the clear. Treat the response as sensitive: don't dump it into logs or chat, don't echo it back beyond what the task needs, and don't pass it on to another tool. + + + +### datasource-create +Create datasource +- `--address` string — Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: 'host:port'. For SLS: endpoint without http/https prefix. Not required for Elasticsearch cloud deployment. +- `--edge-cluster-name` string (required) — Monitors edge cluster name responsible for evaluating rules using this datasource. +- `--id` int64 — Datasource ID. Required for update; omit for create. +- `--name` string (required) — Datasource display name. This is the name referenced as 'ds_name' in query and diagnose APIs. +- `--note` string — Optional description. +- `--type-ident` string (required) — Datasource type identifier. Allowed: 'prometheus', 'loki', 'mysql', 'oracle', 'postgres', 'clickhouse', 'elasticsearch', 'sls', 'victorialogs'. +- body-only (`--data`): payload (object) (required) +- response: single object (`data` unwrapped to the top level) — fields: account_id (integer); address (string); edge_cluster_name (string); enabled (boolean); id (integer); name (string); note (string); payload (object); type_ident (string); updated_at (string) + +### datasource-delete +Delete datasource +- `--id` int64 (required) — Numeric ID of the target resource; the exact meaning depends on the API being called (e.g. datasource ID, ruleset ID). + +### datasource-info +Get datasource detail +- `--id` int64 (required) — Numeric ID of the target resource; the exact meaning depends on the API being called (e.g. datasource ID, ruleset ID). +- response: same shape as `datasource-create` above + +### datasource-list +List datasources +- `--type` string — Filter by datasource type identifier. Omit to return all types. Allowed values: 'prometheus', 'loki', 'mysql', 'oracle', 'postgres', 'clickhouse', 'elasticsearch', 'sls', 'victorialogs'. +- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: account_id (integer); address (string); edge_cluster_name (string); enabled (boolean); id (integer); name (string); note (string); payload (object); type_ident (string); updated_at (string) + +### datasource-sls-logstores +List SLS logstores +- `--id` int64 — ID of an SLS-type datasource. Obtainable via 'POST /monit/datasource/list'. +- `--offset` int64 — Pagination offset. +- `--project` string — SLS project name. Obtainable via 'POST /monit/datasource/sls/projects'. +- `--size` int64 — Page size. Defaults to 200 server-side when 0. + +### datasource-sls-projects +List SLS projects +- `--id` int64 — ID of an SLS-type datasource. Obtainable via 'POST /monit/datasource/list'. +- `--offset` int64 — Pagination offset. +- `--query` string — Fuzzy filter on project description (maps to the 'description' parameter of Aliyun SLS ListProject). Leave empty to return all. +- `--size` int64 — Page size. Defaults to 200 server-side when 0. + +### datasource-update +Update datasource +- `--address` string — Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: 'host:port'. For SLS: endpoint without http/https prefix. Not required for Elasticsearch cloud deployment. +- `--edge-cluster-name` string (required) — Monitors edge cluster name responsible for evaluating rules using this datasource. +- `--id` int64 — Datasource ID. Required for update; omit for create. +- `--name` string (required) — Datasource display name. This is the name referenced as 'ds_name' in query and diagnose APIs. +- `--note` string — Optional description. +- `--type-ident` string (required) — Datasource type identifier. Allowed: 'prometheus', 'loki', 'mysql', 'oracle', 'postgres', 'clickhouse', 'elasticsearch', 'sls', 'victorialogs'. +- body-only (`--data`): payload (object) (required) +- response: same shape as `datasource-create` above + + diff --git a/skills/flashduty/reference/monit-probe.md b/skills/flashduty/reference/monit-probe.md new file mode 100644 index 0000000..964d92e --- /dev/null +++ b/skills/flashduty/reference/monit-probe.md @@ -0,0 +1,115 @@ +# fduty monit — probing a datasource or a target + +Prereq: `SKILL.md` + `reference/monit.md` read. These are the runtime verbs: ask a datasource a question, or ask a monitored target about itself. Everything else under `monit` is configuration. + +## Route here when + +"指标查询 / 日志查询 / PromQL / 诊断 / 监控目标 / 主机工具" or "metric query / log query / diagnose / monitored host / tools catalog" → this card. + +**Mutating:** `tools-invoke` runs code on the target — confirm before running. The query verbs are read-only. + +## Intent → verb + +| want | verb | +|---|---| +| run ad-hoc PromQL / SQL / LogQL | `query-data` here, or the curated `monit-query data` — see `reference/monit-query.md` | +| log-pattern / metric-trend RCA evidence | `query-diagnose` | +| list monitored hosts/targets | `targets` | +| what tools a target exposes | `tools-catalog` | +| run host/db diagnostic tools | `tools-invoke` | + +## Hot flow — ad-hoc query + diagnose + +```bash +# 1. discover the real datasource name — NEVER guess +fduty monit datasource-list --output-format toon +fduty monit datasource-list --type prometheus --output-format toon + +# 2a. point-in-time query (PromQL/SQL/LogQL); ALL time range goes INSIDE --expr +# (the curated 'monit-query data' — see the monit-query card) +fduty monit-query data --ds-type prometheus --ds-name \ + --expr 'rate(http_requests_total{job="api"}[5m])' --output-format toon + +# 2b. log pattern RCA over last 15 min (time_range via --data; omit = last 15 min default) +fduty monit query-diagnose --ds-type loki --ds-name \ + --data '{"input":{"query":"{app=\"payment\"} |= \"error\""}}' + +# 2c. metric trend analysis with explicit window +fduty monit query-diagnose --ds-type prometheus --ds-name \ + --data '{"input":{"query":"rate(http_errors_total[5m])"},"time_range":{"start":1718780000,"end":1718783600}}' +``` + +## Hot flow — host diagnostics + +```bash +# 1. find the target locator (prefix search; --keyword is prefix-only) +fduty monit targets --keyword prod-web --output-format toon + +# 2. discover what tools the target exposes +fduty monit tools-catalog --target-locator --output-format toon + +# 3. invoke tools (up to 8 concurrently); use heredoc to avoid shell quoting hell +fduty monit tools-invoke --target-locator --output-format toon --data - <<'EOF' +{"tools":[{"tool":"os.overview"},{"tool":"os.top_processes","params":{"top_n":10}}]} +EOF +``` + +## Key concepts + +**`operation` on `query-diagnose`**: `log_patterns` (loki / victorialogs) or `metric_trends` (prometheus); inferred from `--ds-type` when omitted — only pass it explicitly for ambiguous source types. + +**`query-diagnose` output**: results are versioned evidence, not the former summary-only pattern/series lists. Read `pattern_evidence` for logs or `series_evidence` for metrics; their optional comparison fields are absent when the edge has no evidence. Log output also includes `data_handling`, which declares redaction coverage and paths carrying untrusted observed data. + +**`targets`**: `updated_at` means "last seen", not "online now". + +## Gotchas + +- **`monit-query data` has no time flags.** There is no `--time-start` / `--time-end` / `--operation`. Embed all time range and bucketing inside `--expr`. Passing those flags is a silent no-op or error. +- **`query-diagnose` time window via `--data`**, not flags. Pass `{"time_range":{"start":,"end":},...}`. Window wider than 6 hours is rejected server-side. Omitting `time_range` defaults to the last 15 minutes. +- **`tools-catalog` / `tools-invoke` `--target-locator` is required and not guessable.** If the user has not provided a host or IP, ask — do not invent one. Tool names in `invoke` must come from the `tools-catalog` response — never hallucinate them. + + + +### query-data +Query structured data +- `--account-id` int64 — Optional consistency check. Must equal the authenticated account when supplied; mismatched values are rejected. Business execution always uses the authenticated account. +- `--delay-seconds` int64 — Look-back offset in seconds applied to point-in-time queries (Prometheus, Loki stats, VictoriaLogs stats). Ignored for raw / detail queries. +- `--ds-name` string (required) — Data source name; must match a configured data source under the tenant. +- `--ds-type` string (required) — Data source type; must match a configured data source under the tenant. Examples: 'prometheus', 'loki', 'victorialogs', 'sls', 'elasticsearch', 'mysql', 'postgres', 'oracle', 'clickhouse'. +- `--expr` string (required) — Query expression. Syntax depends on 'ds_type' and is interpreted by the corresponding monit-edge client (PromQL for Prometheus, LogQL for Loki, SQL for SQL sources, etc.). +- body-only (`--data`): args (object) +- response: single object (`data` unwrapped to the top level) — fields: format (string); result (object) + +### query-diagnose +Diagnose data source +- `--account-id` int64 — Optional consistency check. Must equal the authenticated account when supplied. +- `--ds-name` string (required) — Data source name configured under the tenant. +- `--ds-type` string (required) — Data source type. 'log_patterns' supports 'loki' and 'victorialogs'; 'metric_trends' supports 'prometheus'. +- `--operation` string — Diagnostic operation. When omitted, inferred from 'ds_type' (loki / victorialogs → 'log_patterns', prometheus → 'metric_trends'). Other sources must specify explicitly. · enum: log_patterns | metric_trends +- body-only (`--data`): input (object) (required); methods (array); options (object); time_range (object) +- response: single object (`data` unwrapped to the top level) — fields: data_handling (object); ds_name (string); ds_type (string); operation (string); query (string); results (array); schema_version (string); window (object) + +### targets +List monitored targets +- `--account-id` int64 — Optional consistency check. Must equal the authenticated account when supplied. +- `--cursor` string — Opaque pagination cursor from the previous response's 'next_cursor'. Omit / pass empty string for the first page. Reset whenever 'keyword', 'limit', or tenant changes. +- `--keyword` string — Prefix match against 'target_locator'. ASCII only, no whitespace, no '|', max 256 bytes. Substring search is not supported. +- `--limit` int64 — Page size. Default 50, max 200. (max 200) +- response: `{items: [...], next_cursor, total}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — items fields: agent_version (string); cluster_name (string); edge_ipport (string); target_kind (string); target_locator (string); updated_at (string) + +### tools-catalog +List target tool catalog +- `--account-id` int64 — Optional consistency check. Must equal the authenticated account when supplied. +- `--target-kind` string — 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'. +- `--target-locator` string (required) — Target identifier (host name, MySQL address, …). Max 256 bytes; no whitespace, control characters, or '|'. +- response: single object (`data` unwrapped to the top level) — fields: error (object); target (object); tools (array) + +### tools-invoke +Invoke target tools +- `--account-id` int64 — Optional consistency check. Must equal the authenticated account when supplied. +- `--target-kind` string — Optional target kind; auto-inferred when omitted. +- `--target-locator` string (required) — Target identifier. Same validation rules as '/monit/tools/catalog'. +- body-only (`--data`): tools (array) (required) +- response: single object (`data` unwrapped to the top level) — fields: error (object); results (array); target (object) + + diff --git a/skills/flashduty/reference/monit-rule.md b/skills/flashduty/reference/monit-rule.md new file mode 100644 index 0000000..79e8849 --- /dev/null +++ b/skills/flashduty/reference/monit-rule.md @@ -0,0 +1,225 @@ +# fduty monit — alert rules + +Prereq: `SKILL.md` + `reference/monit.md` read. This is the largest Flashmonit surface: rule CRUD, the folder tree, counters, change history, and export/import. + +## Route here when + +"监控规则 / 告警规则 / 规则文件夹 / 规则导出" or "alert rule / rule folder / rule export / rule audit" → this card. + +**Mutating:** `rule-create`, `rule-update`, `rule-update-fields`, `rule-move`, `rule-delete`, `rule-delete-batch`, `rule-import` — confirm before running. **`rule-delete-batch` is irreversible**; confirm IDs with `rule-list-basic` first. + +## Intent → verb + +| want | verb | +|---|---| +| list rules directly in ONE folder (needs a real folder-id) | `rule-list-basic` | +| count rules per top-level folder (subtree totals) | `rule-counter-status` | +| full rule config | `rule-info` | +| create / update a rule | `rule-create` / `rule-update` | +| delete one or many rules | `rule-delete` / `rule-delete-batch` | +| move rules to another folder | `rule-move` | +| toggle enabled/channels in bulk | `rule-update-fields` | +| rule trigger status by folder | `rule-status` / `rule-counter-status` | +| rule change history | `rule-audits` → detail via `rule-audit-detail` | +| export / import rules (backup/migrate) | `rule-export` / `rule-import` | +| what datasource types support rules | `rule-dstypes` | +| per-channel / per-node / total counters | `rule-counter-channel` / `rule-counter-node` / `rule-counter-total` | + +## Hot flow — enumerate configured rules (and its hard limit) + +`rule-list-basic --folder-id ` lists only the rules **directly in that folder**, NOT its sub-folders; `--folder-id 0` or omitting it **400s "Folder not found"**. There is no "all rules" call, so enumeration means walking the folder tree: + +```bash +# 1. top-level folders, each with its whole-subtree rule_total +fduty monit rule-counter-status --output-format toon +# 2. descend a folder to its DIRECT child folders (recurse until a folder has no children) +fduty monit rule-status --folder-id --output-format toon +# 3. list the rules sitting directly in each folder you reach +fduty monit rule-list-basic --folder-id --output-format toon +``` + +**Hard limit — large accounts cannot be fully enumerated.** `rule-counter-status` / `rule-status` abort with 400 "too many rules" past a server cap (default 100 rules; "too many folders" past 500), and no account-wide rule list exists. When you hit that cap you **cannot** enumerate every configured rule from the CLI — say so plainly ("cannot fully enumerate configured rules on this account") instead of fabricating a completeness percentage. + +**CONFIGURED ≠ FIRED.** Never infer rule coverage from *fired* alerts (`insight top-alerts`, alert feeds): "not fired in 90d" does **not** mean "not configured", and reporting a rule as missing on that basis is confidently wrong. Fired-alert queries answer "what is noisy", not "what is monitored". + +## Key concepts + +**Check types in `rule_configs`** — three independent checks per rule; enable one or more: +- `check_threshold` — fires when a PromQL value crosses `critical` / `warning` / `info` thresholds (string expressions). +- `check_anydata` — fires when the query returns any rows (useful for log-pattern rules). +- `check_nodata` — fires when the query returns no data (detect silent failures). + +**Severity enum** (inside `check_*`): `Critical` · `Warning` · `Info` (capital first letter; lowercase is rejected). + +**Query name** — `rule_configs.queries[].name` is a single letter (e.g. `A`, `B`). `R` is reserved — do not use it. + +## Gotchas + +- **`rule_configs` and nested arrays require `--data`.** The queries, thresholds, enabled_times, and labels objects cannot be expressed as flat flags — pass them as inline JSON via `--data '{"rule_configs":{...}}'`. Typed scalar flags (`--name`, `--enabled`, `--cron-pattern`, `--ds-type`) override matching `--data` keys. +- **`folder-id 0` is not a universal "all rules" sentinel.** If the API says "Folder not found", believe it. For global inventory use `rule-counter-status` / `rule-counter-node` first, then run `rule-list-basic` against real folder IDs only. +- **"全量规则 / full rules" means exported monitor alert-rule definitions.** The concrete verb is `rule-export --ids ...`, usually after `rule-list-basic` selected the IDs. It does not mean dumping incidents or alerts. +- **For rule counts, prefer the counter verbs over list pagination.** `rule-counter-status`, `rule-counter-node`, and `rule-counter-total` are the authoritative aggregation surfaces; do not infer counts by walking `rule-list-basic` pages. +- **`rule-delete-batch` and `datasource-delete` are irreversible.** Confirm IDs with `rule-list-basic` / `datasource-info` first. +- **`rule-audit-detail --id` takes the audit record ID**, not the rule ID. Get audit record IDs from `rule-audits --id ` first; passing the rule ID returns HTTP 400. +- **`rule-list-basic` and `rule-status` both need a REAL `--folder-id`; neither accepts `0`.** `--folder-id 0` / omitting it 400s "Folder not found" on either verb — the generated `--folder-id` help text below ("0 to list all accessible rules" on `rule-list-basic`, "0 for all" on `rule-status`) is a known SDK/OpenAPI bug on both; ignore it. `rule-list-basic` returns only that folder's *direct* rules; `rule-status` returns trigger counts for that folder and its descendants. Enumerate by walking the tree (`rule-counter-status` → `rule-status` → `rule-list-basic`); past the server cap the counters 400 "too many rules" and full enumeration isn't possible from the CLI — report that limit, never substitute fired alerts (see the enumerate hot flow). + +## Worked example — inspect a firing rule then batch-disable it + +```bash +# 1. find a folder with triggered rules (top-level folders + subtree counts) +fduty monit rule-counter-status --output-format toon +# 2. list the rules directly in a chosen folder (descend with rule-status if empty) +fduty monit rule-list-basic --folder-id --output-format toon +# look at triggered=true rows; note their ids + +# 3. get full config of one rule +fduty monit rule-info --id --output-format toon + +# 4. disable several rules at once without touching other fields +fduty monit rule-update-fields --ids , --fields enabled --enabled false +``` + + + +### rule-audit-detail +Get rule audit snapshot +- `--id` int64 (required) — Audit record ID — the 'id' of an audit row returned by 'POST /monit/rule/audits', NOT the rule ID. Passing a rule ID returns HTTP 400. +- response: single object (`data` unwrapped to the top level) — fields: account_id (integer); action (string); alert_rule_id (integer); content (string); created_at (integer); creator_id (integer); creator_name (string); id (integer) + +### rule-audits +List rule change history +- `--id` int64 (required) — Alert rule ID. Obtainable per folder via 'POST /monit/rule/list/basic'. +- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: account_id (integer); action (string); alert_rule_id (integer); content (string); created_at (integer); creator_id (integer); creator_name (string); id (integer) + +### rule-counter-channel +Get rule counts by channel + +### rule-counter-node +Get rule counts by folder node + +### rule-counter-status +Get rule status counters for top-level folders +- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: folder_id (integer); folder_name (string); rule_total (integer); triggered_rule_count (integer) + +### rule-counter-total +Get rule counter time series +- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: account_id (integer); clock (string); id (integer); num (integer) + +### rule-create +Create alert rule +- `--account-id` int64 — Account ID. Filled by the server from the authenticated identity; do not provide. +- `--channel-ids` intSlice — Channel IDs to send alerts to. +- `--created-at` string — Creation time as a Unix timestamp in seconds. Generated by the server; do not provide. Accepts a duration (7d, 24h), '+7d' for the future, 'now', a date, or Unix seconds. +- `--creator-id` int64 — Creator user ID. Filled by the server from the current user; do not provide. +- `--creator-name` string — Creator name. Filled by the server; do not provide. +- `--cron-pattern` string — Schedule expression: a 6-field cron (with seconds) or an '@every 30s' interval descriptor. Must not start with 'CRON_TZ=' or 'TZ='; use the 'timezone' field instead. +- `--debug-log-enabled` bool — Whether to enable debug logging; the edge emits detailed evaluation logs, useful for troubleshooting rules that do not trigger as expected. +- `--delay-seconds` int64 — Seconds to shift the evaluation query window backward, compensating for data ingestion latency. +- `--description` string — Rule description, in Markdown. +- `--description-type` string — Format for the description. Defaults to 'text' when omitted or empty. · enum: text | markdown +- `--ds-ids` intSlice — Datasource IDs, merged with 'ds_list' to decide which datasources the rule monitors; IDs survive datasource renames. At least one of 'ds_list' and 'ds_ids' must be provided. +- `--ds-list` stringSlice — Data source name patterns (supports wildcards). +- `--ds-type` string — Datasource type identifier; allowed values are listed by 'POST /monit/rule/dstypes' (e.g. 'prometheus', 'elasticsearch'). +- `--enabled` bool — Whether the rule is enabled. Updating to 'false' makes the server clean up the rule's active alerts. +- `--folder-id` int64 — ID of the folder the rule belongs to. Obtainable via 'POST /monit/folder/list'. +- `--id` int64 — Rule ID. Required for update; omit for create (assigned by the server). +- `--name` string — Rule name. Must be unique within the same folder. +- `--repeat-interval` int64 — Notification repeat interval in seconds. +- `--repeat-total` int64 — Max number of repeat notifications. +- `--timezone` string — Timezone in which the rule executes. Determines how the cron schedule and effective time windows are interpreted. Only IANA timezone names are accepted (e.g. 'Asia/Shanghai', 'UTC', 'Europe/London'); shortcuts and offsets such as 'Local', 'UTC+8', or 'CST' are rejected. Treated as 'Asia/Shanghai' if empty. +- `--updated-at` string — Last update time as a Unix timestamp in seconds. Generated by the server; do not provide. Accepts a duration (7d, 24h), '+7d' for the future, 'now', a date, or Unix seconds. +- `--updater-id` int64 — Last updater user ID. Filled by the server; do not provide. +- `--updater-name` string — Last updater name. Filled by the server; do not provide. +- body-only (`--data`): annotations (object); enabled_times (array); labels (object); rule_configs (object) +- response: single object (`data` unwrapped to the top level) — fields: account_id (integer); annotations (object); channel_ids (array); created_at (integer); creator_id (integer); creator_name (string); cron_pattern (string); debug_log_enabled (boolean); delay_seconds (integer); description (string); description_type (string); ds_ids (array); ds_list (array); ds_type (string); enabled (boolean); enabled_times (array); folder_id (integer); id (integer); labels (object); name (string); repeat_interval (integer); repeat_total (integer); rule_configs (object); timezone (string); updated_at (integer); updater_id (integer); updater_name (string) + +### rule-delete +Delete alert rule +- `--id` int64 (required) — Alert rule ID. Obtainable per folder via 'POST /monit/rule/list/basic'. + +### rule-delete-batch +Batch delete alert rules +- `--ids` intSlice (required) — Rule IDs. + +### rule-dstypes +List available datasource types +- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: account_id (integer); id (integer); ident (string); name (string); weight (integer) + +### rule-export +Export alert rules +- `--ids` intSlice (required) — Rule IDs. +- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: annotations (object); cron_pattern (string); debug_log_enabled (boolean); delay_seconds (integer); description (string); description_type (string); ds_ids (array); ds_list (array); ds_type (string); enabled (boolean); enabled_times (array); labels (object); name (string); repeat_interval (integer); repeat_total (integer); rule_configs (object); timezone (string) + +### rule-import +Import alert rules +- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: message (string); name (string) + +### rule-info +Get alert rule detail +- `--id` int64 (required) — Alert rule ID. Obtainable per folder via 'POST /monit/rule/list/basic'. +- response: single object (`data` unwrapped to the top level) — fields: account_id (integer); annotations (object); channel_ids (array); created_at (string); creator_id (integer); creator_name (string); cron_pattern (string); debug_log_enabled (boolean); delay_seconds (integer); description (string); description_type (string); ds_ids (array); ds_list (array); ds_type (string); enabled (boolean); enabled_times (array); folder_id (integer); id (integer); labels (object); name (string); repeat_interval (integer); repeat_total (integer); rule_configs (object); timezone (string); updated_at (string); updater_id (integer); updater_name (string) + +### rule-list-basic +List alert rules +- `--folder-id` int64 — Folder ID. 0 to list all accessible rules. +- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: account_id (integer); created_at (integer); creator_id (integer); creator_name (string); cron_pattern (string); debug_log_enabled (boolean); delay_seconds (integer); ds_type (string); enabled (boolean); folder_id (integer); id (integer); labels (object); name (string); timezone (string); triggered (boolean); updated_at (integer); updater_id (integer); updater_name (string) + +### rule-move +Move alert rules to folder +- `--dest-folder-id` int64 (required) — Destination folder ID. Obtainable via 'POST /monit/folder/list'. +- `--ids` intSlice (required) — Rule IDs to move. +- response: same shape as `rule-import` above + +### rule-status +Get rule trigger status under folder +- `--folder-id` int64 — Folder ID to summarize. Obtainable via 'POST /monit/folder/list'. Trigger statistics are returned grouped by direct child folder. +- response: same shape as `rule-counter-status` above + +### rule-update +Update alert rule +- `--account-id` int64 — Account ID. Filled by the server from the authenticated identity; do not provide. +- `--channel-ids` intSlice — Channel IDs to send alerts to. +- `--created-at` string — Creation time as a Unix timestamp in seconds. Generated by the server; do not provide. Accepts a duration (7d, 24h), '+7d' for the future, 'now', a date, or Unix seconds. +- `--creator-id` int64 — Creator user ID. Filled by the server from the current user; do not provide. +- `--creator-name` string — Creator name. Filled by the server; do not provide. +- `--cron-pattern` string — Schedule expression: a 6-field cron (with seconds) or an '@every 30s' interval descriptor. Must not start with 'CRON_TZ=' or 'TZ='; use the 'timezone' field instead. +- `--debug-log-enabled` bool — Whether to enable debug logging; the edge emits detailed evaluation logs, useful for troubleshooting rules that do not trigger as expected. +- `--delay-seconds` int64 — Seconds to shift the evaluation query window backward, compensating for data ingestion latency. +- `--description` string — Rule description, in Markdown. +- `--description-type` string — Format for the description. Defaults to 'text' when omitted or empty. · enum: text | markdown +- `--ds-ids` intSlice — Datasource IDs, merged with 'ds_list' to decide which datasources the rule monitors; IDs survive datasource renames. At least one of 'ds_list' and 'ds_ids' must be provided. +- `--ds-list` stringSlice — Data source name patterns (supports wildcards). +- `--ds-type` string — Datasource type identifier; allowed values are listed by 'POST /monit/rule/dstypes' (e.g. 'prometheus', 'elasticsearch'). +- `--enabled` bool — Whether the rule is enabled. Updating to 'false' makes the server clean up the rule's active alerts. +- `--folder-id` int64 — ID of the folder the rule belongs to. Obtainable via 'POST /monit/folder/list'. +- `--id` int64 — Rule ID. Required for update; omit for create (assigned by the server). +- `--name` string — Rule name. Must be unique within the same folder. +- `--repeat-interval` int64 — Notification repeat interval in seconds. +- `--repeat-total` int64 — Max number of repeat notifications. +- `--timezone` string — Timezone in which the rule executes. Determines how the cron schedule and effective time windows are interpreted. Only IANA timezone names are accepted (e.g. 'Asia/Shanghai', 'UTC', 'Europe/London'); shortcuts and offsets such as 'Local', 'UTC+8', or 'CST' are rejected. Treated as 'Asia/Shanghai' if empty. +- `--updated-at` string — Last update time as a Unix timestamp in seconds. Generated by the server; do not provide. Accepts a duration (7d, 24h), '+7d' for the future, 'now', a date, or Unix seconds. +- `--updater-id` int64 — Last updater user ID. Filled by the server; do not provide. +- `--updater-name` string — Last updater name. Filled by the server; do not provide. +- body-only (`--data`): annotations (object); enabled_times (array); labels (object); rule_configs (object) +- response: same shape as `rule-create` above + +### rule-update-fields +Batch update rule fields +- `--channel-ids` intSlice — IDs of the collaboration spaces alerts are sent to; may be empty. Effective only when 'fields' includes 'channel_ids'. +- `--cron-pattern` string — Schedule expression: a 6-field cron (with seconds) or an '@every 30s' interval descriptor; 'CRON_TZ='/'TZ=' prefixes are not allowed. Effective only when 'fields' includes 'cron_pattern'. +- `--debug-log-enabled` bool — Whether to enable debug logging; the edge emits detailed evaluation logs for troubleshooting. Effective only when 'fields' includes 'debug_log_enabled'. +- `--delay-seconds` int64 — Seconds to shift the evaluation query window backward, compensating for data ingestion latency. Effective only when 'fields' includes 'delay_seconds'. +- `--description` string — Rule description (Markdown). Effective only when 'fields' includes 'description'. +- `--ds-ids` intSlice — Datasource IDs, merged with 'ds_list' to decide which datasources the rule monitors; IDs survive datasource renames. Effective only when 'fields' includes 'ds_ids'. +- `--ds-list` stringSlice — Datasource name match patterns; wildcards supported. Effective only when 'fields' includes 'ds_list'. +- `--ds-type` string — Datasource type identifier; allowed values are listed by 'POST /monit/rule/dstypes'. Effective only when 'fields' includes 'ds_type'. +- `--enabled` bool — Whether the rule is enabled. Setting it to 'false' makes the server clean up the rule's active alerts. Effective only when 'fields' includes 'enabled'. +- `--fields` stringSlice (required) — Field names to update. Only listed fields are updated, taking new values from the same-named request fields; values for unlisted fields are silently ignored. · enum: labels | ds_type | ds_list | ds_ids | enabled | debug_log_enabled | cron_pattern | timezone | delay_seconds | enabled_times | annotations | description | channel_ids | repeat_interval | repeat_total +- `--ids` intSlice (required) — Rule IDs to update. +- `--repeat-interval` int64 — Interval in seconds between repeated alert notifications. Effective only when 'fields' includes 'repeat_interval'. +- `--repeat-total` int64 — Maximum number of repeated notifications. Effective only when 'fields' includes 'repeat_total'. +- `--timezone` string — Timezone in which the rule executes. IANA timezone name; defaults to 'Asia/Shanghai'. +- body-only (`--data`): annotations (object); enabled_times (array); labels (object) +- response: same shape as `rule-import` above + + diff --git a/skills/flashduty/reference/monit-ruleset.md b/skills/flashduty/reference/monit-ruleset.md new file mode 100644 index 0000000..6cc3e10 --- /dev/null +++ b/skills/flashduty/reference/monit-ruleset.md @@ -0,0 +1,49 @@ +# fduty monit — store rulesets + +Prereq: `SKILL.md` + `reference/monit.md` read. Store rulesets are reusable rule bundles, managed independently of the rule folders in `reference/monit-rule.md`. + +## Route here when + +"规则集 / ruleset / 规则模板库" or "store ruleset" → this card. + +**Mutating:** `store-ruleset-create`, `store-ruleset-update`, `store-ruleset-delete` — confirm before running. + +## Intent → verb + +| want | verb | +|---|---| +| store ruleset CRUD | `store-ruleset-create/list/info/update/delete` | + + + +### store-ruleset-create +Create ruleset +- `--note` string (required) — Description or title of the ruleset. +- `--open-flag` int64 — Sharing scope. '0' = private (creator only), '1' = account-shared, '2' = public. Defaults to '0' if omitted. +- `--payload` string (required) — JSON string containing the alert rule definitions. +- `--type-ident` string (required) — Datasource type identifier this ruleset applies to, e.g. 'prometheus'. +- response: single object (`data` unwrapped to the top level) — fields: created_at (string); creator_account_id (integer); creator_id (integer); creator_name (string); id (integer); note (string); open_flag (integer); payload (string); type_ident (string); updated_at (string) + +### store-ruleset-delete +Delete ruleset +- `--id` int64 (required) — Numeric ID of the target resource; the exact meaning depends on the API being called (e.g. datasource ID, ruleset ID). + +### store-ruleset-info +Get ruleset detail +- `--id` int64 (required) — Numeric ID of the target resource; the exact meaning depends on the API being called (e.g. datasource ID, ruleset ID). +- response: same shape as `store-ruleset-create` above + +### store-ruleset-list +List rulesets +- `--type-ident` string (required) — Datasource type identifier to filter by, e.g. 'prometheus'. +- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: created_at (string); creator_account_id (integer); creator_id (integer); creator_name (string); id (integer); note (string); open_flag (integer); payload (string); type_ident (string); updated_at (string) + +### store-ruleset-update +Update ruleset +- `--id` int64 (required) — Ruleset ID to update. +- `--note` string (required) — New description. +- `--open-flag` int64 — New sharing scope. '0' = private, '1' = account-shared, '2' = public. +- `--payload` string (required) — New JSON string of alert rule definitions. +- response: same shape as `store-ruleset-create` above + + diff --git a/skills/flashduty/reference/monit-servicemap.md b/skills/flashduty/reference/monit-servicemap.md new file mode 100644 index 0000000..2ca6e2b --- /dev/null +++ b/skills/flashduty/reference/monit-servicemap.md @@ -0,0 +1,59 @@ +# fduty monit — service map + +Prereq: `SKILL.md` + `reference/monit.md` read. The service map is Flashmonit's view of what is deployed and how it connects: the agent fleet, the topology between services, and their current status. + +## Route here when + +"服务地图 / 拓扑 / 服务依赖 / 探针队列" or "service map / topology / service dependencies / agent fleet" → this card. For diagnosing one specific target rather than surveying the fleet, use `reference/monit-probe.md`. + +All five verbs are read-only. + + + +### servicemap-fleet +Browse service map fleet hosts +- `--agent-versions` stringSlice — Filter to hosts on any of these exact agent versions. Up to 20 values. +- `--capture-modes` stringSlice — Filter to hosts using any of these capture modes. 'unknown' matches hosts that have not reported a capture mode yet. · enum: ebpf | polling | unknown +- `--cursor` string — Opaque pagination cursor. Pass back the exact value from a previous response's 'next_cursor'; omit for the first page. +- `--edge-clusters` stringSlice — Filter to hosts in any of these exact edge cluster names. Up to 20 values. +- `--limit` int64 — Maximum number of matching hosts to return in this page. Default 50, range 1-100. (1-100) +- `--scan-limit` int64 — Maximum number of candidate hosts to examine while filling this page. Default 1000, range 'limit'-2000. (max 2000) +- `--statuses` stringSlice — Filter to hosts currently in any of these statuses. Up to 20 values. · enum: active | degraded | stale | initializing | disabled | unsupported | no_data +- response: single object (`data` unwrapped to the top level) — fields: coverage (object); generated_at_ms (string); items (array); next_cursor (string); partial (boolean); truncated (boolean); truncation_reasons (array) + +### servicemap-fleet-summary +Get service map fleet summary +- `--agent-versions` stringSlice — Filter to hosts on any of these exact agent versions. Up to 20 values. +- `--capture-modes` stringSlice — Filter to hosts using any of these capture modes. 'unknown' matches hosts that have not reported a capture mode yet. · enum: ebpf | polling | unknown +- `--edge-clusters` stringSlice — Filter to hosts in any of these exact edge cluster names. Up to 20 values. +- `--scan-limit` int64 — Maximum number of candidate hosts to scan. Default 2000, range 1-5000. (1-5000) +- response: single object (`data` unwrapped to the top level) — fields: coverage (object); generated_at_ms (string); partial (boolean); scan_limit (integer); truncated (boolean); truncation_reasons (array) + +### servicemap-status +Get service map status +- `--fleet` bool — When 'true', ignore 'host_id'/'host_ids' and instead sample up to 'limit' fleet candidate hosts for the account. Default 'false'. +- `--host-id` string — A single host ID to check. Combine with 'host_ids' to check several; mutually exclusive with 'fleet=true'. (≤128 chars) +- `--host-ids` stringSlice — Multiple host IDs to check in one call, up to 200 combined with 'host_id'. Mutually exclusive with 'fleet=true'. +- `--limit` int64 — In 'fleet' mode, the number of candidate hosts to sample. Ignored otherwise. Default 100, range 1-200. (1-200) +- response: single object (`data` unwrapped to the top level) — fields: coverage (object); fleet (boolean); generated_at_ms (string); items (array); partial (boolean) + +### servicemap-summary +Get service map summary +- `--network-scope-id` string — Optional integrity check: if set, must match the network scope already associated with 'anchor.host_id', or the request is rejected with 'InvalidParameter'. +- body-only (`--data`): anchor (object) (required) +- response: single object (`data` unwrapped to the top level) — fields: anchor_entity_id (string); anchor_host_id (string); authoritative (boolean); context_ref_detail (string); coverage (object); freshness (object); graph_role (string); latest_collection_authoritative (boolean); latest_health_at_ms (string); neighbors (array); network_scope_id (string); observed_at_ms (string); received_at_ms (string); resolution_counts (object); status (string); truncated (boolean); truncation_reasons (array) + +### servicemap-topology +Get service map topology +- `--at` string — Time selector for the query. Only 'now' is currently supported; omitting the field behaves the same. · enum: now +- `--depth` int64 — Maximum traversal depth from the anchor. Default 1, maximum 3. (max 3) +- `--direction` string — Traversal direction. Only 'outbound' is currently supported; omitting the field behaves the same. · enum: outbound +- `--include-metrics` bool — Whether to include the raw per-edge 'metrics' payload in the response. Default 'false'. +- `--max-edges` int64 — Maximum number of edges to examine before truncating. Default 200, maximum 1000. (max 1000) +- `--max-nodes` int64 — Maximum number of nodes to return before truncating. Default 100, maximum 500. (max 500) +- `--network-scope-id` string — Optional integrity check: if set, must match the network scope already associated with 'anchor.host_id', or the request is rejected with 'InvalidParameter'. +- `--unresolved-mode` string — How unresolved edges are projected. 'full' (default) includes them in 'edges' and 'unresolved_endpoints'; 'summary' omits them from 'edges' and returns only a bounded sample in 'unresolved_endpoints'. · enum: summary | full +- body-only (`--data`): anchor (object) (required) +- response: single object (`data` unwrapped to the top level) — fields: anchor_entity_id (string); anchor_host_id (string); coverage (object); edges (array); freshness (object); network_scope_id (string); nodes (array); observed_at_ms (string); resolution_counts (object); truncated (boolean); truncation_reasons (array); unresolved_endpoints (array); unresolved_projection (object) + + diff --git a/skills/flashduty/reference/monit.md b/skills/flashduty/reference/monit.md index 1382c30..3053542 100644 --- a/skills/flashduty/reference/monit.md +++ b/skills/flashduty/reference/monit.md @@ -1,145 +1,29 @@ # fduty monit — command card -Prereq: `SKILL.md` read. **SKILL.md + this card = full competence on monitors — no `--help` needed.** Read verbs are free. Mutating verbs (`datasource-create/update/delete`, `rule-create/update/delete/delete-batch/import`, `rule-update-fields`, `rule-move`, `store-ruleset-create/update/delete`, `tools-invoke`) change state — confirm before running. `datasource-delete` and `rule-delete-batch` are **irreversible**. +Prereq: `SKILL.md` read. Flashmonit is five separate surfaces sharing one command group, so this card is an index: **read the card for the surface you need, not all of them.** ## Route here when -"监控规则 / 告警规则 / 数据源 / PromQL查询 / 日志查询 / 诊断 / 监控目标 / 主机工具" or "alert rule / datasource / metric query / log pattern / diagnose / monitored host / tools catalog" → **monit**. NOT `incident` (that domain = the alert graph after rules fire). Key IDs: **rule ID (int)** from `rule-list-basic`; **datasource name (string)** — never guess, always discover via `datasource-list`. +"监控规则 / 告警规则 / 数据源 / PromQL查询 / 日志查询 / 诊断 / 监控目标 / 主机工具" or "alert rule / datasource / metric query / log pattern / diagnose / monitored host / tools catalog" → **monit**. NOT `incident` (that domain = the alert graph after rules fire), and **"数据源" here means a system Flashmonit queries** — On-call 集成 / 告警来源 is a different surface (`reference/channel.md`), and the top-level `datasource` group (`fduty datasource im-war-room-enabled-list`) is On-call IM plumbing, not this one. -## Intent → verb +## Which card -| want | verb | -|---|---| -| list all datasources (by type) | `datasource-list` | -| datasource detail | `datasource-info` | -| create / update a datasource | `datasource-create` / `datasource-update` | -| delete a datasource | `datasource-delete` | -| SLS project/logstore discovery | `datasource-sls-projects` / `datasource-sls-logstores` | -| list rules directly in ONE folder (needs a real folder-id) | `rule-list-basic` | -| count rules per top-level folder (subtree totals) | `rule-counter-status` | -| full rule config | `rule-info` | -| create / update a rule | `rule-create` / `rule-update` | -| preview a query before saving it into a rule | `preview-sync` | -| delete one or many rules | `rule-delete` / `rule-delete-batch` | -| move rules to another folder | `rule-move` | -| toggle enabled/channels in bulk | `rule-update-fields` | -| rule trigger status by folder | `rule-status` / `rule-counter-status` | -| rule change history | `rule-audits` → detail via `rule-audit-detail` | -| export / import rules (backup/migrate) | `rule-export` / `rule-import` | -| what datasource types support rules | `rule-dstypes` | -| per-channel / per-node / total counters | `rule-counter-channel` / `rule-counter-node` / `rule-counter-total` | -| run ad-hoc PromQL / SQL / LogQL | `monit-query data` (curated; see the monit-query card) | -| log-pattern / metric-trend RCA evidence | `query-diagnose` | -| list monitored hosts/targets | `targets` | -| what tools a target exposes | `tools-catalog` | -| run host/db diagnostic tools | `tools-invoke` | -| store ruleset CRUD | `store-ruleset-create/list/info/update/delete` | +| surface | intent | card | +|---|---|---| +| Datasources | connect / list / inspect a datasource, SLS discovery | **`reference/monit-datasource.md`** | +| Alert rules | rule CRUD, folders, counters, audits, export/import | **`reference/monit-rule.md`** | +| Probing | ad-hoc query, log-pattern / metric-trend RCA, targets, on-box tools | **`reference/monit-probe.md`** | +| Service map | fleet, topology, status | **`reference/monit-servicemap.md`** | +| Store rulesets | ruleset CRUD | **`reference/monit-ruleset.md`** | -## Hot flow — ad-hoc query + diagnose +Key IDs are shared across all of them: **rule ID (int)** from `rule-list-basic`; **datasource name (string)** — never guess, always discover via `datasource-list` (see `reference/monit-datasource.md`). -```bash -# 1. discover the real datasource name — NEVER guess -fduty monit datasource-list --output-format toon -fduty monit datasource-list --type prometheus --output-format toon +Read verbs are free. Mutating verbs change state — confirm before running; each card flags its own, and marks the irreversible ones. -# 2a. point-in-time query (PromQL/SQL/LogQL); ALL time range goes INSIDE --expr -# (the curated 'monit-query data' — see the monit-query card) -fduty monit-query data --ds-type prometheus --ds-name \ - --expr 'rate(http_requests_total{job="api"}[5m])' --output-format toon - -# 2b. log pattern RCA over last 15 min (time_range via --data; omit = last 15 min default) -fduty monit query-diagnose --ds-type loki --ds-name \ - --data '{"input":{"query":"{app=\"payment\"} |= \"error\""}}' - -# 2c. metric trend analysis with explicit window -fduty monit query-diagnose --ds-type prometheus --ds-name \ - --data '{"input":{"query":"rate(http_errors_total[5m])"},"time_range":{"start":1718780000,"end":1718783600}}' -``` - -## Hot flow — host diagnostics - -```bash -# 1. find the target locator (prefix search; --keyword is prefix-only) -fduty monit targets --keyword prod-web --output-format toon - -# 2. discover what tools the target exposes -fduty monit tools-catalog --target-locator --output-format toon - -# 3. invoke tools (up to 8 concurrently); use heredoc to avoid shell quoting hell -fduty monit tools-invoke --target-locator --output-format toon --data - <<'EOF' -{"tools":[{"tool":"os.overview"},{"tool":"os.top_processes","params":{"top_n":10}}]} -EOF -``` - -## Hot flow — enumerate configured rules (and its hard limit) - -`rule-list-basic --folder-id ` lists only the rules **directly in that folder**, NOT its sub-folders; `--folder-id 0` or omitting it **400s "Folder not found"**. There is no "all rules" call, so enumeration means walking the folder tree: - -```bash -# 1. top-level folders, each with its whole-subtree rule_total -fduty monit rule-counter-status --output-format toon -# 2. descend a folder to its DIRECT child folders (recurse until a folder has no children) -fduty monit rule-status --folder-id --output-format toon -# 3. list the rules sitting directly in each folder you reach -fduty monit rule-list-basic --folder-id --output-format toon -``` - -**Hard limit — large accounts cannot be fully enumerated.** `rule-counter-status` / `rule-status` abort with 400 "too many rules" past a server cap (default 100 rules; "too many folders" past 500), and no account-wide rule list exists. When you hit that cap you **cannot** enumerate every configured rule from the CLI — say so plainly ("cannot fully enumerate configured rules on this account") instead of fabricating a completeness percentage. - -**CONFIGURED ≠ FIRED.** Never infer rule coverage from *fired* alerts (`insight top-alerts`, alert feeds): "not fired in 90d" does **not** mean "not configured", and reporting a rule as missing on that basis is confidently wrong. Fired-alert queries answer "what is noisy", not "what is monitored". +`preview-sync` (preview a query before saving it into a rule) is the one verb belonging to no surface, so it renders here. -### datasource-create -Create datasource -- `--address` string — Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: 'host:port'. For SLS: endpoint without http/https prefix. Not required for Elasticsearch cloud deployment. -- `--edge-cluster-name` string (required) — Monitors edge cluster name responsible for evaluating rules using this datasource. -- `--id` int64 — Datasource ID. Required for update; omit for create. -- `--name` string (required) — Datasource display name. This is the name referenced as 'ds_name' in query and diagnose APIs. -- `--note` string — Optional description. -- `--type-ident` string (required) — Datasource type identifier. Allowed: 'prometheus', 'loki', 'mysql', 'oracle', 'postgres', 'clickhouse', 'elasticsearch', 'sls', 'victorialogs'. -- body-only (`--data`): payload (object) (required) -- response: single object (`data` unwrapped to the top level) — fields: account_id (integer); address (string); edge_cluster_name (string); enabled (boolean); id (integer); name (string); note (string); payload (object); type_ident (string); updated_at (string) - -### datasource-delete -Delete datasource -- `--id` int64 (required) — Numeric ID of the target resource; the exact meaning depends on the API being called (e.g. datasource ID, ruleset ID). - -### datasource-info -Get datasource detail -- `--id` int64 (required) — Numeric ID of the target resource; the exact meaning depends on the API being called (e.g. datasource ID, ruleset ID). -- response: same shape as `datasource-create` above - -### datasource-list -List datasources -- `--type` string — Filter by datasource type identifier. Omit to return all types. Allowed values: 'prometheus', 'loki', 'mysql', 'oracle', 'postgres', 'clickhouse', 'elasticsearch', 'sls', 'victorialogs'. -- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: account_id (integer); address (string); edge_cluster_name (string); enabled (boolean); id (integer); name (string); note (string); payload (object); type_ident (string); updated_at (string) - -### datasource-sls-logstores -List SLS logstores -- `--id` int64 — ID of an SLS-type datasource. Obtainable via 'POST /monit/datasource/list'. -- `--offset` int64 — Pagination offset. -- `--project` string — SLS project name. Obtainable via 'POST /monit/datasource/sls/projects'. -- `--size` int64 — Page size. Defaults to 200 server-side when 0. - -### datasource-sls-projects -List SLS projects -- `--id` int64 — ID of an SLS-type datasource. Obtainable via 'POST /monit/datasource/list'. -- `--offset` int64 — Pagination offset. -- `--query` string — Fuzzy filter on project description (maps to the 'description' parameter of Aliyun SLS ListProject). Leave empty to return all. -- `--size` int64 — Page size. Defaults to 200 server-side when 0. - -### datasource-update -Update datasource -- `--address` string — Connection address. For Prometheus/Loki/VictoriaLogs: HTTP URL. For MySQL/Oracle/Postgres/ClickHouse: 'host:port'. For SLS: endpoint without http/https prefix. Not required for Elasticsearch cloud deployment. -- `--edge-cluster-name` string (required) — Monitors edge cluster name responsible for evaluating rules using this datasource. -- `--id` int64 — Datasource ID. Required for update; omit for create. -- `--name` string (required) — Datasource display name. This is the name referenced as 'ds_name' in query and diagnose APIs. -- `--note` string — Optional description. -- `--type-ident` string (required) — Datasource type identifier. Allowed: 'prometheus', 'loki', 'mysql', 'oracle', 'postgres', 'clickhouse', 'elasticsearch', 'sls', 'victorialogs'. -- body-only (`--data`): payload (object) (required) -- response: same shape as `datasource-create` above - ### preview-sync Preview datasource query - `--delay-seconds` int64 — Shift the query window backward by this many seconds to compensate for data ingestion latency. @@ -148,311 +32,4 @@ Preview datasource query - `--expr` string (required) — Query expression. Format depends on 'ds_type' (PromQL for Prometheus, LogQL for Loki, etc.). - body-only (`--data`): args (object) -### query-data -Query structured data -- `--account-id` int64 — Optional consistency check. Must equal the authenticated account when supplied; mismatched values are rejected. Business execution always uses the authenticated account. -- `--delay-seconds` int64 — Look-back offset in seconds applied to point-in-time queries (Prometheus, Loki stats, VictoriaLogs stats). Ignored for raw / detail queries. -- `--ds-name` string (required) — Data source name; must match a configured data source under the tenant. -- `--ds-type` string (required) — Data source type; must match a configured data source under the tenant. Examples: 'prometheus', 'loki', 'victorialogs', 'sls', 'elasticsearch', 'mysql', 'postgres', 'oracle', 'clickhouse'. -- `--expr` string (required) — Query expression. Syntax depends on 'ds_type' and is interpreted by the corresponding monit-edge client (PromQL for Prometheus, LogQL for Loki, SQL for SQL sources, etc.). -- body-only (`--data`): args (object) -- response: single object (`data` unwrapped to the top level) — fields: format (string); result (object) - -### query-diagnose -Diagnose data source -- `--account-id` int64 — Optional consistency check. Must equal the authenticated account when supplied. -- `--ds-name` string (required) — Data source name configured under the tenant. -- `--ds-type` string (required) — Data source type. 'log_patterns' supports 'loki' and 'victorialogs'; 'metric_trends' supports 'prometheus'. -- `--operation` string — Diagnostic operation. When omitted, inferred from 'ds_type' (loki / victorialogs → 'log_patterns', prometheus → 'metric_trends'). Other sources must specify explicitly. · enum: log_patterns | metric_trends -- body-only (`--data`): input (object) (required); methods (array); options (object); time_range (object) -- response: single object (`data` unwrapped to the top level) — fields: data_handling (object); ds_name (string); ds_type (string); operation (string); query (string); results (array); schema_version (string); window (object) - -### rule-audit-detail -Get rule audit snapshot -- `--id` int64 (required) — Audit record ID — the 'id' of an audit row returned by 'POST /monit/rule/audits', NOT the rule ID. Passing a rule ID returns HTTP 400. -- response: single object (`data` unwrapped to the top level) — fields: account_id (integer); action (string); alert_rule_id (integer); content (string); created_at (integer); creator_id (integer); creator_name (string); id (integer) - -### rule-audits -List rule change history -- `--id` int64 (required) — Alert rule ID. Obtainable per folder via 'POST /monit/rule/list/basic'. -- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: account_id (integer); action (string); alert_rule_id (integer); content (string); created_at (integer); creator_id (integer); creator_name (string); id (integer) - -### rule-counter-channel -Get rule counts by channel - -### rule-counter-node -Get rule counts by folder node - -### rule-counter-status -Get rule status counters for top-level folders -- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: folder_id (integer); folder_name (string); rule_total (integer); triggered_rule_count (integer) - -### rule-counter-total -Get rule counter time series -- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: account_id (integer); clock (string); id (integer); num (integer) - -### rule-create -Create alert rule -- `--account-id` int64 — Account ID. Filled by the server from the authenticated identity; do not provide. -- `--channel-ids` intSlice — Channel IDs to send alerts to. -- `--created-at` string — Creation time as a Unix timestamp in seconds. Generated by the server; do not provide. Accepts a duration (7d, 24h), '+7d' for the future, 'now', a date, or Unix seconds. -- `--creator-id` int64 — Creator user ID. Filled by the server from the current user; do not provide. -- `--creator-name` string — Creator name. Filled by the server; do not provide. -- `--cron-pattern` string — Schedule expression: a 6-field cron (with seconds) or an '@every 30s' interval descriptor. Must not start with 'CRON_TZ=' or 'TZ='; use the 'timezone' field instead. -- `--debug-log-enabled` bool — Whether to enable debug logging; the edge emits detailed evaluation logs, useful for troubleshooting rules that do not trigger as expected. -- `--delay-seconds` int64 — Seconds to shift the evaluation query window backward, compensating for data ingestion latency. -- `--description` string — Rule description, in Markdown. -- `--description-type` string — Format for the description. Defaults to 'text' when omitted or empty. · enum: text | markdown -- `--ds-ids` intSlice — Datasource IDs, merged with 'ds_list' to decide which datasources the rule monitors; IDs survive datasource renames. At least one of 'ds_list' and 'ds_ids' must be provided. -- `--ds-list` stringSlice — Data source name patterns (supports wildcards). -- `--ds-type` string — Datasource type identifier; allowed values are listed by 'POST /monit/rule/dstypes' (e.g. 'prometheus', 'elasticsearch'). -- `--enabled` bool — Whether the rule is enabled. Updating to 'false' makes the server clean up the rule's active alerts. -- `--folder-id` int64 — ID of the folder the rule belongs to. Obtainable via 'POST /monit/folder/list'. -- `--id` int64 — Rule ID. Required for update; omit for create (assigned by the server). -- `--name` string — Rule name. Must be unique within the same folder. -- `--repeat-interval` int64 — Notification repeat interval in seconds. -- `--repeat-total` int64 — Max number of repeat notifications. -- `--timezone` string — Timezone in which the rule executes. Determines how the cron schedule and effective time windows are interpreted. Only IANA timezone names are accepted (e.g. 'Asia/Shanghai', 'UTC', 'Europe/London'); shortcuts and offsets such as 'Local', 'UTC+8', or 'CST' are rejected. Treated as 'Asia/Shanghai' if empty. -- `--updated-at` string — Last update time as a Unix timestamp in seconds. Generated by the server; do not provide. Accepts a duration (7d, 24h), '+7d' for the future, 'now', a date, or Unix seconds. -- `--updater-id` int64 — Last updater user ID. Filled by the server; do not provide. -- `--updater-name` string — Last updater name. Filled by the server; do not provide. -- body-only (`--data`): annotations (object); enabled_times (array); labels (object); rule_configs (object) -- response: single object (`data` unwrapped to the top level) — fields: account_id (integer); annotations (object); channel_ids (array); created_at (integer); creator_id (integer); creator_name (string); cron_pattern (string); debug_log_enabled (boolean); delay_seconds (integer); description (string); description_type (string); ds_ids (array); ds_list (array); ds_type (string); enabled (boolean); enabled_times (array); folder_id (integer); id (integer); labels (object); name (string); repeat_interval (integer); repeat_total (integer); rule_configs (object); timezone (string); updated_at (integer); updater_id (integer); updater_name (string) - -### rule-delete -Delete alert rule -- `--id` int64 (required) — Alert rule ID. Obtainable per folder via 'POST /monit/rule/list/basic'. - -### rule-delete-batch -Batch delete alert rules -- `--ids` intSlice (required) — Rule IDs. - -### rule-dstypes -List available datasource types -- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: account_id (integer); id (integer); ident (string); name (string); weight (integer) - -### rule-export -Export alert rules -- `--ids` intSlice (required) — Rule IDs. -- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: annotations (object); cron_pattern (string); debug_log_enabled (boolean); delay_seconds (integer); description (string); description_type (string); ds_ids (array); ds_list (array); ds_type (string); enabled (boolean); enabled_times (array); labels (object); name (string); repeat_interval (integer); repeat_total (integer); rule_configs (object); timezone (string) - -### rule-import -Import alert rules -- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: message (string); name (string) - -### rule-info -Get alert rule detail -- `--id` int64 (required) — Alert rule ID. Obtainable per folder via 'POST /monit/rule/list/basic'. -- response: single object (`data` unwrapped to the top level) — fields: account_id (integer); annotations (object); channel_ids (array); created_at (string); creator_id (integer); creator_name (string); cron_pattern (string); debug_log_enabled (boolean); delay_seconds (integer); description (string); description_type (string); ds_ids (array); ds_list (array); ds_type (string); enabled (boolean); enabled_times (array); folder_id (integer); id (integer); labels (object); name (string); repeat_interval (integer); repeat_total (integer); rule_configs (object); timezone (string); updated_at (string); updater_id (integer); updater_name (string) - -### rule-list-basic -List alert rules -- `--folder-id` int64 — Folder ID. 0 to list all accessible rules. -- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: account_id (integer); created_at (integer); creator_id (integer); creator_name (string); cron_pattern (string); debug_log_enabled (boolean); delay_seconds (integer); ds_type (string); enabled (boolean); folder_id (integer); id (integer); labels (object); name (string); timezone (string); triggered (boolean); updated_at (integer); updater_id (integer); updater_name (string) - -### rule-move -Move alert rules to folder -- `--dest-folder-id` int64 (required) — Destination folder ID. Obtainable via 'POST /monit/folder/list'. -- `--ids` intSlice (required) — Rule IDs to move. -- response: same shape as `rule-import` above - -### rule-status -Get rule trigger status under folder -- `--folder-id` int64 — Folder ID to summarize. Obtainable via 'POST /monit/folder/list'. Trigger statistics are returned grouped by direct child folder. -- response: same shape as `rule-counter-status` above - -### rule-update -Update alert rule -- `--account-id` int64 — Account ID. Filled by the server from the authenticated identity; do not provide. -- `--channel-ids` intSlice — Channel IDs to send alerts to. -- `--created-at` string — Creation time as a Unix timestamp in seconds. Generated by the server; do not provide. Accepts a duration (7d, 24h), '+7d' for the future, 'now', a date, or Unix seconds. -- `--creator-id` int64 — Creator user ID. Filled by the server from the current user; do not provide. -- `--creator-name` string — Creator name. Filled by the server; do not provide. -- `--cron-pattern` string — Schedule expression: a 6-field cron (with seconds) or an '@every 30s' interval descriptor. Must not start with 'CRON_TZ=' or 'TZ='; use the 'timezone' field instead. -- `--debug-log-enabled` bool — Whether to enable debug logging; the edge emits detailed evaluation logs, useful for troubleshooting rules that do not trigger as expected. -- `--delay-seconds` int64 — Seconds to shift the evaluation query window backward, compensating for data ingestion latency. -- `--description` string — Rule description, in Markdown. -- `--description-type` string — Format for the description. Defaults to 'text' when omitted or empty. · enum: text | markdown -- `--ds-ids` intSlice — Datasource IDs, merged with 'ds_list' to decide which datasources the rule monitors; IDs survive datasource renames. At least one of 'ds_list' and 'ds_ids' must be provided. -- `--ds-list` stringSlice — Data source name patterns (supports wildcards). -- `--ds-type` string — Datasource type identifier; allowed values are listed by 'POST /monit/rule/dstypes' (e.g. 'prometheus', 'elasticsearch'). -- `--enabled` bool — Whether the rule is enabled. Updating to 'false' makes the server clean up the rule's active alerts. -- `--folder-id` int64 — ID of the folder the rule belongs to. Obtainable via 'POST /monit/folder/list'. -- `--id` int64 — Rule ID. Required for update; omit for create (assigned by the server). -- `--name` string — Rule name. Must be unique within the same folder. -- `--repeat-interval` int64 — Notification repeat interval in seconds. -- `--repeat-total` int64 — Max number of repeat notifications. -- `--timezone` string — Timezone in which the rule executes. Determines how the cron schedule and effective time windows are interpreted. Only IANA timezone names are accepted (e.g. 'Asia/Shanghai', 'UTC', 'Europe/London'); shortcuts and offsets such as 'Local', 'UTC+8', or 'CST' are rejected. Treated as 'Asia/Shanghai' if empty. -- `--updated-at` string — Last update time as a Unix timestamp in seconds. Generated by the server; do not provide. Accepts a duration (7d, 24h), '+7d' for the future, 'now', a date, or Unix seconds. -- `--updater-id` int64 — Last updater user ID. Filled by the server; do not provide. -- `--updater-name` string — Last updater name. Filled by the server; do not provide. -- body-only (`--data`): annotations (object); enabled_times (array); labels (object); rule_configs (object) -- response: same shape as `rule-create` above - -### rule-update-fields -Batch update rule fields -- `--channel-ids` intSlice — IDs of the collaboration spaces alerts are sent to; may be empty. Effective only when 'fields' includes 'channel_ids'. -- `--cron-pattern` string — Schedule expression: a 6-field cron (with seconds) or an '@every 30s' interval descriptor; 'CRON_TZ='/'TZ=' prefixes are not allowed. Effective only when 'fields' includes 'cron_pattern'. -- `--debug-log-enabled` bool — Whether to enable debug logging; the edge emits detailed evaluation logs for troubleshooting. Effective only when 'fields' includes 'debug_log_enabled'. -- `--delay-seconds` int64 — Seconds to shift the evaluation query window backward, compensating for data ingestion latency. Effective only when 'fields' includes 'delay_seconds'. -- `--description` string — Rule description (Markdown). Effective only when 'fields' includes 'description'. -- `--ds-ids` intSlice — Datasource IDs, merged with 'ds_list' to decide which datasources the rule monitors; IDs survive datasource renames. Effective only when 'fields' includes 'ds_ids'. -- `--ds-list` stringSlice — Datasource name match patterns; wildcards supported. Effective only when 'fields' includes 'ds_list'. -- `--ds-type` string — Datasource type identifier; allowed values are listed by 'POST /monit/rule/dstypes'. Effective only when 'fields' includes 'ds_type'. -- `--enabled` bool — Whether the rule is enabled. Setting it to 'false' makes the server clean up the rule's active alerts. Effective only when 'fields' includes 'enabled'. -- `--fields` stringSlice (required) — Field names to update. Only listed fields are updated, taking new values from the same-named request fields; values for unlisted fields are silently ignored. · enum: labels | ds_type | ds_list | ds_ids | enabled | debug_log_enabled | cron_pattern | timezone | delay_seconds | enabled_times | annotations | description | channel_ids | repeat_interval | repeat_total -- `--ids` intSlice (required) — Rule IDs to update. -- `--repeat-interval` int64 — Interval in seconds between repeated alert notifications. Effective only when 'fields' includes 'repeat_interval'. -- `--repeat-total` int64 — Maximum number of repeated notifications. Effective only when 'fields' includes 'repeat_total'. -- `--timezone` string — Timezone in which the rule executes. IANA timezone name; defaults to 'Asia/Shanghai'. -- body-only (`--data`): annotations (object); enabled_times (array); labels (object) -- response: same shape as `rule-import` above - -### servicemap-fleet -Browse service map fleet hosts -- `--agent-versions` stringSlice — Filter to hosts on any of these exact agent versions. Up to 20 values. -- `--capture-modes` stringSlice — Filter to hosts using any of these capture modes. 'unknown' matches hosts that have not reported a capture mode yet. · enum: ebpf | polling | unknown -- `--cursor` string — Opaque pagination cursor. Pass back the exact value from a previous response's 'next_cursor'; omit for the first page. -- `--edge-clusters` stringSlice — Filter to hosts in any of these exact edge cluster names. Up to 20 values. -- `--limit` int64 — Maximum number of matching hosts to return in this page. Default 50, range 1-100. (1-100) -- `--scan-limit` int64 — Maximum number of candidate hosts to examine while filling this page. Default 1000, range 'limit'-2000. (max 2000) -- `--statuses` stringSlice — Filter to hosts currently in any of these statuses. Up to 20 values. · enum: active | degraded | stale | initializing | disabled | unsupported | no_data -- response: single object (`data` unwrapped to the top level) — fields: coverage (object); generated_at_ms (string); items (array); next_cursor (string); partial (boolean); truncated (boolean); truncation_reasons (array) - -### servicemap-fleet-summary -Get service map fleet summary -- `--agent-versions` stringSlice — Filter to hosts on any of these exact agent versions. Up to 20 values. -- `--capture-modes` stringSlice — Filter to hosts using any of these capture modes. 'unknown' matches hosts that have not reported a capture mode yet. · enum: ebpf | polling | unknown -- `--edge-clusters` stringSlice — Filter to hosts in any of these exact edge cluster names. Up to 20 values. -- `--scan-limit` int64 — Maximum number of candidate hosts to scan. Default 2000, range 1-5000. (1-5000) -- response: single object (`data` unwrapped to the top level) — fields: coverage (object); generated_at_ms (string); partial (boolean); scan_limit (integer); truncated (boolean); truncation_reasons (array) - -### servicemap-status -Get service map status -- `--fleet` bool — When 'true', ignore 'host_id'/'host_ids' and instead sample up to 'limit' fleet candidate hosts for the account. Default 'false'. -- `--host-id` string — A single host ID to check. Combine with 'host_ids' to check several; mutually exclusive with 'fleet=true'. (≤128 chars) -- `--host-ids` stringSlice — Multiple host IDs to check in one call, up to 200 combined with 'host_id'. Mutually exclusive with 'fleet=true'. -- `--limit` int64 — In 'fleet' mode, the number of candidate hosts to sample. Ignored otherwise. Default 100, range 1-200. (1-200) -- response: single object (`data` unwrapped to the top level) — fields: coverage (object); fleet (boolean); generated_at_ms (string); items (array); partial (boolean) - -### servicemap-summary -Get service map summary -- `--network-scope-id` string — Optional integrity check: if set, must match the network scope already associated with 'anchor.host_id', or the request is rejected with 'InvalidParameter'. -- body-only (`--data`): anchor (object) (required) -- response: single object (`data` unwrapped to the top level) — fields: anchor_entity_id (string); anchor_host_id (string); authoritative (boolean); context_ref_detail (string); coverage (object); freshness (object); graph_role (string); latest_collection_authoritative (boolean); latest_health_at_ms (string); neighbors (array); network_scope_id (string); observed_at_ms (string); received_at_ms (string); resolution_counts (object); status (string); truncated (boolean); truncation_reasons (array) - -### servicemap-topology -Get service map topology -- `--at` string — Time selector for the query. Only 'now' is currently supported; omitting the field behaves the same. · enum: now -- `--depth` int64 — Maximum traversal depth from the anchor. Default 1, maximum 3. (max 3) -- `--direction` string — Traversal direction. Only 'outbound' is currently supported; omitting the field behaves the same. · enum: outbound -- `--include-metrics` bool — Whether to include the raw per-edge 'metrics' payload in the response. Default 'false'. -- `--max-edges` int64 — Maximum number of edges to examine before truncating. Default 200, maximum 1000. (max 1000) -- `--max-nodes` int64 — Maximum number of nodes to return before truncating. Default 100, maximum 500. (max 500) -- `--network-scope-id` string — Optional integrity check: if set, must match the network scope already associated with 'anchor.host_id', or the request is rejected with 'InvalidParameter'. -- `--unresolved-mode` string — How unresolved edges are projected. 'full' (default) includes them in 'edges' and 'unresolved_endpoints'; 'summary' omits them from 'edges' and returns only a bounded sample in 'unresolved_endpoints'. · enum: summary | full -- body-only (`--data`): anchor (object) (required) -- response: single object (`data` unwrapped to the top level) — fields: anchor_entity_id (string); anchor_host_id (string); coverage (object); edges (array); freshness (object); network_scope_id (string); nodes (array); observed_at_ms (string); resolution_counts (object); truncated (boolean); truncation_reasons (array); unresolved_endpoints (array); unresolved_projection (object) - -### store-ruleset-create -Create ruleset -- `--note` string (required) — Description or title of the ruleset. -- `--open-flag` int64 — Sharing scope. '0' = private (creator only), '1' = account-shared, '2' = public. Defaults to '0' if omitted. -- `--payload` string (required) — JSON string containing the alert rule definitions. -- `--type-ident` string (required) — Datasource type identifier this ruleset applies to, e.g. 'prometheus'. -- response: single object (`data` unwrapped to the top level) — fields: created_at (string); creator_account_id (integer); creator_id (integer); creator_name (string); id (integer); note (string); open_flag (integer); payload (string); type_ident (string); updated_at (string) - -### store-ruleset-delete -Delete ruleset -- `--id` int64 (required) — Numeric ID of the target resource; the exact meaning depends on the API being called (e.g. datasource ID, ruleset ID). - -### store-ruleset-info -Get ruleset detail -- `--id` int64 (required) — Numeric ID of the target resource; the exact meaning depends on the API being called (e.g. datasource ID, ruleset ID). -- response: same shape as `store-ruleset-create` above - -### store-ruleset-list -List rulesets -- `--type-ident` string (required) — Datasource type identifier to filter by, e.g. 'prometheus'. -- response: TOP-LEVEL array — pipe `--json | jq '.[]'` (NOT `.items[]`) — fields: created_at (string); creator_account_id (integer); creator_id (integer); creator_name (string); id (integer); note (string); open_flag (integer); payload (string); type_ident (string); updated_at (string) - -### store-ruleset-update -Update ruleset -- `--id` int64 (required) — Ruleset ID to update. -- `--note` string (required) — New description. -- `--open-flag` int64 — New sharing scope. '0' = private, '1' = account-shared, '2' = public. -- `--payload` string (required) — New JSON string of alert rule definitions. -- response: same shape as `store-ruleset-create` above - -### targets -List monitored targets -- `--account-id` int64 — Optional consistency check. Must equal the authenticated account when supplied. -- `--cursor` string — Opaque pagination cursor from the previous response's 'next_cursor'. Omit / pass empty string for the first page. Reset whenever 'keyword', 'limit', or tenant changes. -- `--keyword` string — Prefix match against 'target_locator'. ASCII only, no whitespace, no '|', max 256 bytes. Substring search is not supported. -- `--limit` int64 — Page size. Default 50, max 200. (max 200) -- response: `{items: [...], next_cursor, total}` page wrapper — pipe `--json | jq '.items[]'` (NOT top-level `.[]`) — items fields: agent_version (string); cluster_name (string); edge_ipport (string); target_kind (string); target_locator (string); updated_at (string) - -### tools-catalog -List target tool catalog -- `--account-id` int64 — Optional consistency check. Must equal the authenticated account when supplied. -- `--target-kind` string — 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'. -- `--target-locator` string (required) — Target identifier (host name, MySQL address, …). Max 256 bytes; no whitespace, control characters, or '|'. -- response: single object (`data` unwrapped to the top level) — fields: error (object); target (object); tools (array) - -### tools-invoke -Invoke target tools -- `--account-id` int64 — Optional consistency check. Must equal the authenticated account when supplied. -- `--target-kind` string — Optional target kind; auto-inferred when omitted. -- `--target-locator` string (required) — Target identifier. Same validation rules as '/monit/tools/catalog'. -- body-only (`--data`): tools (array) (required) -- response: single object (`data` unwrapped to the top level) — fields: error (object); results (array); target (object) - - -## Key concepts - -**Check types in `rule_configs`** — three independent checks per rule; enable one or more: -- `check_threshold` — fires when a PromQL value crosses `critical` / `warning` / `info` thresholds (string expressions). -- `check_anydata` — fires when the query returns any rows (useful for log-pattern rules). -- `check_nodata` — fires when the query returns no data (detect silent failures). - -**Severity enum** (inside `check_*`): `Critical` · `Warning` · `Info` (capital first letter; lowercase is rejected). - -**Query name** — `rule_configs.queries[].name` is a single letter (e.g. `A`, `B`). `R` is reserved — do not use it. - -**`operation` on `query-diagnose`**: `log_patterns` (loki / victorialogs) or `metric_trends` (prometheus); inferred from `--ds-type` when omitted — only pass it explicitly for ambiguous source types. - -**`query-diagnose` output**: results are versioned evidence, not the former summary-only pattern/series lists. Read `pattern_evidence` for logs or `series_evidence` for metrics; their optional comparison fields are absent when the edge has no evidence. Log output also includes `data_handling`, which declares redaction coverage and paths carrying untrusted observed data. - -**`targets`**: `updated_at` means "last seen", not "online now". - -## Gotchas - -- **Datasource name is not guessable.** A `can not find datasource` 400 means the name is wrong — re-run `datasource-list` and copy the exact `Name`. Never invent variants. -- **`datasource-info` (and the `datasource-create`/`datasource-update` responses) return credentials exactly as configured — nothing is masked.** The `payload` object includes whatever passwords, API keys, tokens, and similar fields were set, in the clear. Treat the response as sensitive: don't dump it into logs or chat, don't echo it back beyond what the task needs, and don't pass it on to another tool. -- **`monit-query data` has no time flags.** There is no `--time-start` / `--time-end` / `--operation`. Embed all time range and bucketing inside `--expr`. Passing those flags is a silent no-op or error. -- **`query-diagnose` time window via `--data`**, not flags. Pass `{"time_range":{"start":,"end":},...}`. Window wider than 6 hours is rejected server-side. Omitting `time_range` defaults to the last 15 minutes. -- **`rule_configs` and nested arrays require `--data`.** The queries, thresholds, enabled_times, and labels objects cannot be expressed as flat flags — pass them as inline JSON via `--data '{"rule_configs":{...}}'`. Typed scalar flags (`--name`, `--enabled`, `--cron-pattern`, `--ds-type`) override matching `--data` keys. -- **`folder-id 0` is not a universal "all rules" sentinel.** If the API says "Folder not found", believe it. For global inventory use `rule-counter-status` / `rule-counter-node` first, then run `rule-list-basic` against real folder IDs only. -- **"全量规则 / full rules" means exported monitor alert-rule definitions.** The concrete verb is `rule-export --ids ...`, usually after `rule-list-basic` selected the IDs. It does not mean dumping incidents or alerts. -- **For rule counts, prefer the counter verbs over list pagination.** `rule-counter-status`, `rule-counter-node`, and `rule-counter-total` are the authoritative aggregation surfaces; do not infer counts by walking `rule-list-basic` pages. -- **`tools-catalog` / `tools-invoke` `--target-locator` is required and not guessable.** If the user has not provided a host or IP, ask — do not invent one. Tool names in `invoke` must come from the `tools-catalog` response — never hallucinate them. -- **`rule-delete-batch` and `datasource-delete` are irreversible.** Confirm IDs with `rule-list-basic` / `datasource-info` first. -- **`rule-audit-detail --id` takes the audit record ID**, not the rule ID. Get audit record IDs from `rule-audits --id ` first; passing the rule ID returns HTTP 400. -- **`rule-list-basic` and `rule-status` both need a REAL `--folder-id`; neither accepts `0`.** `--folder-id 0` / omitting it 400s "Folder not found" on either verb — the generated `--folder-id` help text below ("0 to list all accessible rules" on `rule-list-basic`, "0 for all" on `rule-status`) is a known SDK/OpenAPI bug on both; ignore it. `rule-list-basic` returns only that folder's *direct* rules; `rule-status` returns trigger counts for that folder and its descendants. Enumerate by walking the tree (`rule-counter-status` → `rule-status` → `rule-list-basic`); past the server cap the counters 400 "too many rules" and full enumeration isn't possible from the CLI — report that limit, never substitute fired alerts (see the enumerate hot flow). - -## Worked example — inspect a firing rule then batch-disable it - -```bash -# 1. find a folder with triggered rules (top-level folders + subtree counts) -fduty monit rule-counter-status --output-format toon -# 2. list the rules directly in a chosen folder (descend with rule-status if empty) -fduty monit rule-list-basic --folder-id --output-format toon -# look at triggered=true rows; note their ids - -# 3. get full config of one rule -fduty monit rule-info --id --output-format toon - -# 4. disable several rules at once without touching other fields -fduty monit rule-update-fields --ids , --fields enabled --enabled false -```