From ae376b22727537397ab4de0ba70393754f54eb05 Mon Sep 17 00:00:00 2001 From: Flashduty AI-SRE Date: Mon, 7 Sep 2026 08:41:01 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20doc-review=202026-09-07=20=E2=80=94=20C?= =?UTF-8?q?LI/SSO/monitors/go-sdk/changelog=20drift=20fixes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Findings (26): 3 high, 19 medium, 4 low — diff window 2026-09-04T08:13:40Z..2026-09-07. - cli.mdx: safari artifacts command family, monit datasource-tools-invoke, datasource --alerting-enabled/--enabled, monit-agent host-only, insight --fields, 16KiB output bound, status-page draft-create - sso: new role-team-sync page (SAML2.0/OIDC/CAS claim-name sync) + docs.json + configure-sso links - monitors: 10→15 datasource types, enabled/alerting_enabled split, datasource tools + Edge v0.71.0 - on-call: war-room chats excluded from group-chat pickers; analytics timezone row - rum: adoption panel labels (采用情况) - ai-sre: sessions task-panel third entry point - api-catalog/go-sdk: tools-invoke row, client.Artifacts, DraftCreate, 5-type contract, Reason field, count refreshes (337→349/348/354) - changelog: SSO sync + Monit datasource diagnostics entries --- docs.json | 6 +- en/ai-sre/sessions.mdx | 5 +- en/changelog/changelog.mdx | 31 +++ en/developer/cli.mdx | 177 ++++++++++++++++-- en/developer/go-sdk.mdx | 19 +- en/developer/overview.mdx | 2 +- en/home.mdx | 2 +- en/monitors/data-sources/data-sources.mdx | 78 +++++++- en/monitors/targets/overview.mdx | 35 ++++ en/on-call/advanced/war-room.mdx | 4 + en/on-call/analytics/insights.mdx | 3 +- en/on-call/channel/escalation-rule.mdx | 2 +- en/on-call/configuration/schedule.mdx | 2 +- en/on-call/integration/sso/role-team-sync.mdx | 97 ++++++++++ en/openapi/api-catalog.mdx | 5 +- en/platform/configure-sso.mdx | 9 +- en/rum/quickstart/app-management.mdx | 2 +- zh/ai-sre/sessions.mdx | 5 +- zh/changelog/changelog.mdx | 31 +++ zh/developer/cli.mdx | 177 ++++++++++++++++-- zh/developer/go-sdk.mdx | 19 +- zh/developer/overview.mdx | 2 +- zh/home.mdx | 2 +- zh/monitors/data-sources/data-sources.mdx | 78 +++++++- zh/monitors/targets/overview.mdx | 35 ++++ zh/on-call/advanced/war-room.mdx | 4 + zh/on-call/analytics/insights.mdx | 3 +- zh/on-call/channel/escalation-rule.mdx | 2 +- zh/on-call/configuration/schedule.mdx | 2 +- zh/on-call/integration/sso/role-team-sync.mdx | 97 ++++++++++ zh/openapi/api-catalog.mdx | 5 +- zh/platform/configure-sso.mdx | 9 +- zh/rum/quickstart/app-management.mdx | 2 +- 33 files changed, 878 insertions(+), 74 deletions(-) create mode 100644 en/on-call/integration/sso/role-team-sync.mdx create mode 100644 zh/on-call/integration/sso/role-team-sync.mdx diff --git a/docs.json b/docs.json index ebdda8fd..3f22ff3d 100644 --- a/docs.json +++ b/docs.json @@ -1752,7 +1752,8 @@ "pages": [ "zh/on-call/integration/sso/authing", "zh/on-call/integration/sso/keycloak", - "zh/on-call/integration/sso/openldap" + "zh/on-call/integration/sso/openldap", + "zh/on-call/integration/sso/role-team-sync" ] }, { @@ -3162,7 +3163,8 @@ "pages": [ "en/on-call/integration/sso/authing", "en/on-call/integration/sso/keycloak", - "en/on-call/integration/sso/openldap" + "en/on-call/integration/sso/openldap", + "en/on-call/integration/sso/role-team-sync" ] }, { diff --git a/en/ai-sre/sessions.mdx b/en/ai-sre/sessions.mdx index 2703cdc6..32ee55eb 100644 --- a/en/ai-sre/sessions.mdx +++ b/en/ai-sre/sessions.mdx @@ -226,10 +226,11 @@ Beyond subagents, the agent can push time-consuming work into the background. Ta | shell | The `bash` tool with `run_in_background` | A long one-shot command (build, batch job, data pull); only its completion needs reporting | | monitor | The `monitor` tool | A standing watcher task: watches a condition until it hits or reaches its deadline, and the script's output flows back to the agent as event batches; a one-shot delayed action (e.g. "check again in half an hour") is done with a monitor plus `sleep` | -A unified **Tasks** panel on the right side of the session tracks every task of the session, grouped into **Needs you / Running / Finished**. There are two entry points: +A unified **Tasks** panel on the right side of the session tracks every task of the session, grouped into **Needs you / Running / Finished**. There are three entry points: - **The tasks button in the chat header**: carries a count badge for "needs you + running" tasks, capped at `9+`; the badge is red when any task needs you (awaiting authorization / awaiting input), and blue when tasks are only running. - **The generation status row while a turn is running**: shows the live task count (e.g. "3 tasks · 1 agent needs you"); clicking it opens the same task panel. +- **The tool row that started a monitor / background bash**: the tool row in the conversation that started a `monitor` or a background command (`bash` with `run_in_background`) — when it is the only tool in its group, that group's header — is itself that task's handle in the transcript: its trailing external-link icon marks it clickable, the tooltip reads **Open task detail**, and clicking it opens that task's detail panel directly. Such rows no longer expand into raw Input/Output (a background bash row used to show only the command, with no status or output). In a read-only shared session the detail opens in read-only mode as well. Task details differ by kind: clicking an **agent** task opens the child session's execution transcript (see above); clicking a **shell / monitor** task opens its own event-timeline detail, which includes the status (a running task also shows how many seconds ago its last liveness probe landed — probing happens roughly every 30 seconds), run duration, event count, output bytes, the monitor's deadline (standing tasks with no deadline show "Persistent"), the exit code, the full command, and the event timeline in order. **The stop button lives in the detail header** — **Stop task** for shell / monitor tasks and **Stop Subagent** for subagents — and interrupts only that task, without affecting the main session. @@ -238,7 +239,7 @@ How this surfaces in the conversation stream: - A tool line that starts a background command reads **Started background command**; when a turn mixes foreground and background commands, the collapsed tool group counts each category separately (e.g. `Ran 1 command, started 1 background command`). - Each time a monitor's condition hits, a 🔭 system line is inlined into the conversation: the first line shows the monitor's description plus a first-line summary of that output batch, and clicking it expands the full batch in place. - When a task ends, a terminal line appears with the end state and a result summary, plus the exit code and a note when the task envelope carries them. -- The `monitor` tool line itself does not expand into input / output — the bookkeeping it returns (task ID, output file, deadline, and so on) is presented more completely in the task panel's detail. +- The `monitor` tool line itself does not expand into input / output — clicking it opens the corresponding task's detail panel, where the bookkeeping it returns (task ID, output file, deadline, and so on) is presented more completely. Two status indicators related to background tasks: diff --git a/en/changelog/changelog.mdx b/en/changelog/changelog.mdx index 54e35a31..52979c68 100644 --- a/en/changelog/changelog.mdx +++ b/en/changelog/changelog.mdx @@ -4,6 +4,37 @@ description: "This page documents important updates and feature releases for Fla keywords: ["Changelog", "Product Release", "Feature Updates", "Flashduty", "Version History"] --- + + +### SSO sync configuration: role and team sync + +The SSO settings page for SAML2.0 / OIDC / CAS gains a **Sync Configuration** section that syncs a member's roles and teams at login based on fields returned by the identity provider (IdP): + +- **Sync roles / Sync teams toggles**: enable role or team sync independently; at login, the member's current roles and teams are overwritten with the matching result +- **Role field / Team field**: the claim names carrying the role and team names returned by the IdP (e.g. `roles` / `teams`); the value may be a string or a string array, matched by name **exactly** (case-sensitive) +- **Default roles / Default teams**: when no returned name matches any role or team, the configured defaults are assigned at login; if nothing matches and no defaults are configured, they are cleared +- **Protocol differences**: LDAP is unchanged — it still maps Group DN to roles/teams; this sync configuration applies only to SAML2.0 / OIDC / CAS + +See [Role and Team Sync](/en/on-call/integration/sso/role-team-sync). + + + + + +### Monit datasource diagnostics and new datasource types + +Monit datasources gain **datasource diagnostics**: run structured read-only named-tool inspections against a configured datasource: + +- **Datasource diagnostic tool**: invokes exactly one deterministic tool per datasource ID (e.g. `mysql.lock_contention`, `postgres.activity`, `redis_node.slowlog`, `kafka.consumer_lag`, `elasticsearch.cat`, `prometheus.metric_trends`, `loki.log_patterns`, `victorialogs.log_patterns`); there is no tool catalog, and the datasource must have `enabled=true` (`alerting_enabled=false` does not block diagnostics) +- **Version requirement**: all routable online Edge sessions in the selected cluster must support the **v0.71.0** baseline protocol, otherwise errors such as `edge_upgrade_required` / `mixed_edge_versions` / `no_active_edge` / `tool_not_supported` are returned +- **Legacy tools removed**: `mysql.query` / `postgres.query` are gone — use the query API for free-form SQL +- **Five new diagnostic-only datasource types**: Redis (Node / Sentinel), MongoDB (Mongod / Mongos), and Kafka — for diagnostics only, they never evaluate alerts; address formats are a single `host:port` (bracket IPv6) or 1–32 unique comma-separated Kafka bootstrap addresses +- **Switch semantics split**: `alerting_enabled` (whether the datasource may evaluate alerts; always false for diagnostic-only types, and disabling it is rejected with a conflict while enabled rules reference the datasource) is now independent of `enabled` (business execution, on by default at creation) + +See [Data Sources](/en/monitors/data-sources/data-sources) and [Monitoring Targets](/en/monitors/targets/overview). + + + ### AI SRE: background tasks and task panel diff --git a/en/developer/cli.mdx b/en/developer/cli.mdx index 18107baa..1d407ace 100644 --- a/en/developer/cli.mdx +++ b/en/developer/cli.mdx @@ -264,8 +264,23 @@ flashduty status-page list # List st flashduty status-page change-active-list # List active status page events flashduty status-page change-create [flags] # Create a status page event flashduty status-page change-timeline-create [flags] # Append a timeline update +flashduty status-page draft-create [flags] # Create a status page event draft (reviewed by a human, then published from the console) ``` +#### Event drafts (draft-create) + +`draft-create` stores a status page event draft (incident or maintenance) so a human can review and publish it from the console — the draft itself is never published publicly: + +```bash +flashduty status-page draft-create \ + --source 'ai_sre:sess_xxx' \ + --data '{"draft":{"page_id":5750613685214,"type":"incident","name":"Web Console Degraded Performance","message":"We are investigating degraded performance affecting the web console.","status":"investigating","affected_components":[{"component_id":"01KC3GAZ6ZJE40H55GM31RPWZE","status":"degraded"}]}}' +``` + +- `--source`: opaque marker of the drafting origin (e.g. `ai_sre:sess_xxx`), up to 64 characters. +- The `draft` object in `--data` (required, stored verbatim, up to 64 KB serialized). Required fields: `page_id`, `type` (`incident` or `maintenance`), `name`, `message`; optional `change_id` (append an update to an existing event when > 0), `status`, `affected_components`, and `start_time`/`end_time` (Unix epoch seconds, new maintenance only). +- The response returns `draft_id` (matching `draft_[A-Za-z0-9]{22}`) and `created_at`; the console review link carries `draft_id`. + #### Migrate from Atlassian Statuspage Migration jobs run asynchronously. Poll progress with `migration-status` after kicking off a job: @@ -290,7 +305,7 @@ flashduty status-page migrate-email-subscribers \ flashduty status-page migration-cancel ``` -Other available subcommands: `change-delete`, `change-info`, `change-list`, `change-timeline-delete`, `change-timeline-update`, `change-update`, `component-upsert`, `component-delete`, `section-upsert`, `section-delete`, `info`, `subscriber-list`, `subscriber-import`, `subscriber-export`, `template-list`, `template-upsert`, `template-delete`. +Other available subcommands: `draft-create`, `change-delete`, `change-info`, `change-list`, `change-timeline-delete`, `change-timeline-update`, `change-update`, `component-upsert`, `component-delete`, `section-upsert`, `section-delete`, `info`, `subscriber-list`, `subscriber-import`, `subscriber-export`, `template-list`, `template-upsert`, `template-delete`. ### rum — RUM applications and session replay @@ -429,7 +444,7 @@ Common flags for `session list`: | `--since` | Keep only sessions updated within the window (client-side filter), e.g. `30d`, `24h`, `2026-05-01` | - | | `--limit` | Max sessions to fetch | `200` | | `--page` | Start page (1-based) | `1` | -| `--output-format` | Output format: `jsonl` (default, one session object per line, pipe straight to `jq`), `json` (full envelope), `toon` (compact) | `jsonl` | +| `--output-format` | Output format: `jsonl` (default, one session object per line, pipe straight to `jq`), `json` (full envelope; subject to the 16 KiB output bound — see "Output formats"), `toon` (compact) | `jsonl` | The server endpoint `/safari/session/list` caps each page at 100 rows; when `--limit` exceeds that, the CLI paginates automatically — no manual paging required. The API has no time-window filter, so `--since` is applied client-side against each session's `updated_at` after fetching. @@ -446,38 +461,39 @@ flashduty session export --include-subagents > session.ndjson |------|-------------| | `--include-subagents` | After each `subagent_dispatch`, recursively inline that subagent's own full event stream | -### monit-agent — On-box host/database diagnostics +### monit-agent — Host diagnostics -Run live diagnostics on a target host or data source through flashmonit agents, without needing a shell login on the target machine. +Run live diagnostics on a **host** through flashmonit agents, without needing a shell login on the target machine. For database/middleware diagnosis use `monit datasource-tools-invoke` (see below) — database service endpoints are not agent targets. ```bash -flashduty monit-agent catalog --target-locator # List available diagnostic tools for a target +flashduty monit-agent catalog --target-locator # List diagnostic tools available for a host flashduty monit-agent invoke --target-locator --data '' # Run up to 8 tools concurrently ``` -Both subcommands require `--target-locator` (internal IP, hostname, or data-source name). `--target-kind` is optional (`host`, `mysql`, `redis`, etc.) and is inferred automatically when omitted. +- `--target-locator` (required): a registered host's **internal IP or hostname**. +- `--target-kind`: accepts `host` only; omit it to use host routing. Any other value (e.g. `mysql`, `redis`) is rejected: `monit-agent supports host targets only; use monit datasource-tools-invoke for datasource diagnostics`. -`invoke` accepts a `--data` JSON payload listing the tools to run, up to 8 concurrently: +`invoke` takes a `--data` JSON payload listing the tools to run (`params` is optional and defaults to `{}`), up to 8 concurrently; `--target-locator` / `--target-kind` override matching keys in `--data`: ```bash flashduty monit-agent invoke --target-locator '10.0.0.1' \ --data '{"tools":[{"tool":"os.overview"},{"tool":"os.top_processes","params":{"top_n":10}}]}' ``` -For SQL parameters containing quotes or commas, pass `--data -` and supply the body via a stdin heredoc to avoid shell-quoting issues: +For params JSON containing quotes or commas, pass `--data -` and supply the body via a stdin heredoc to avoid shell-quoting issues: ```bash -flashduty monit-agent invoke --target-locator 'db-host' --data - <<'FDUTY' -{"tools":[{"tool":"mysql.query","params":{"sql":"SELECT a, b FROM t WHERE s='RUNNING'","max_rows":50}}]} +flashduty monit-agent invoke --target-locator 'web-01' --data - <<'FDUTY' +{"tools":[{"tool":"os.overview"}]} FDUTY ``` ### monit-query — Monitoring datasource queries -Probe monitoring back-end datasources directly, bypassing the alert-rule layer. The `data` subcommand supports 9 datasource types (Prometheus, VictoriaLogs, Loki, MySQL, SLS, Elasticsearch, PostgreSQL, Oracle, ClickHouse); `diagnose` supports `prometheus` (metric trends), `victorialogs`, and `loki` (log patterns). +Probe monitoring back-end datasources directly, bypassing the alert-rule layer. The `data` subcommand supports 9 datasource types (Prometheus, VictoriaLogs, Loki, MySQL, SLS, Elasticsearch, PostgreSQL, Oracle, ClickHouse); `diagnose` is a **legacy** interface (its log_patterns / metric_trends evidence has moved to `monit datasource-tools-invoke`) supporting `prometheus` (metric trends), `victorialogs`, and `loki` (log patterns). ```bash -flashduty monit-query diagnose [flags] # Pre-clustered RCA findings (log patterns or metric trends) +flashduty monit-query diagnose [flags] # Legacy: pre-clustered RCA findings (log patterns or metric trends; prefer monit datasource-tools-invoke) flashduty monit-query data [flags] # Structured datasource query ``` @@ -492,6 +508,8 @@ Common flags for `diagnose`: | `--time-end` | Window end (default `now`); same formats as `--time-start`; the window is capped at 6h | | `--operation` | `log_patterns` (`loki` / `victorialogs`) or `metric_trends` (`prometheus`); inferred from `--ds-type` when omitted | +`diagnose` is a legacy interface (the equivalent of the SDK's deprecated `QueryDiagnose`): for new scenarios use the `prometheus.metric_trends`, `loki.log_patterns`, and `victorialogs.log_patterns` tools of `monit datasource-tools-invoke`, below. + Common flags for `data`: | Flag | Description | @@ -506,7 +524,34 @@ Common flags for `data`: `rows` requires `--ds-type`, `--ds-name`, and `--expr` (query expression). Use `--args KEY=VALUE` (repeatable) for parameterized queries. **`rows` is deprecated** — use `monit-query data` instead. In raw mode (`loki` / `victorialogs`), `rows` accepts time-window arguments `--args .start=` and `--args .end=` in the same formats as `diagnose`'s `--time-start`/`--time-end` (relative duration, `now`, date/RFC3339, unix seconds or milliseconds); the CLI normalizes them to the unix-seconds form the datasource requires. -### monit — Alert-expression preview +### monit datasource-tools-invoke — Datasource diagnostics + +`monit datasource-tools-invoke` executes **one deterministic read-only tool** against a configured datasource — the current path for structured datasource diagnostics (replacing `monit-query diagnose` and the agent's diagnostic role). Get the datasource ID from the `id` field of `monit datasource-list`: + +```bash +flashduty monit datasource-list --type redis_node --json | jq '.[] | {id, name, type_ident, address}' +flashduty monit datasource-tools-invoke --tool 'redis_node.slowlog' \ + --data '{"params":{}}' +``` + +| Flag | Description | +|------|-------------| +| `--datasource-id` | Datasource ID (required, from `monit datasource-list`, min 1) | +| `--tool` | Tool name (required), prefixed by the datasource type, e.g. `mysql.overview`, `postgres.activity`, `redis_node.slowlog`, `kafka.consumer_lag`, `elasticsearch.cat`, `prometheus.metric_trends`, `loki.log_patterns`, `victorialogs.log_patterns`; 1–128 chars | +| `--data` | Tool parameters JSON (`{"params":{...}}`; may be omitted, meaning `{}`; an explicit `null` is invalid) | +| `--account-id` | Optional consistency check; must equal the authenticated account | + +Semantics and limits: + +- **No tool catalog, no auto-replay, no fallback**: one call runs exactly one named tool; fill parameters according to the datasource tool's contract rather than guessing from the command list. The `mysql.query` / `postgres.query` tools have been removed — free SQL stays under `monit-query data`. +- Requires **all** currently online routable Edge sessions in the cluster to support the v0.71.0 base invoke protocol (individual tools may require a newer implementation); normal datasource queries retain their existing version compatibility. +- Request body limit 128 KiB; complete success response limit 1 MiB; tool timeout at most 25 seconds. +- The datasource must have `enabled=true`; `alerting_enabled=false` does not block diagnostics. +- Response: `data` (tool-specific JSON evidence, preserved without conversion, never null, no legacy diagnose envelope), `tool`, `datasource_id`, optional `summary`, and a `truncated` object (with `reason`; its presence indicates truncation). + +Errors are returned as-is; common codes: `edge_upgrade_required` (Edge too old), `mixed_edge_versions` (mixed Edge versions in the cluster), `no_active_edge` (no routable online Edge), `tool_not_supported` (tool unavailable), `invalid_request` (fix the parameters), `source_too_large` / `result_too_large` (narrow the request). On Edge version issues, do not rotate Edges or fall back to the Agent/legacy diagnose. + +### monit — Datasource and alert-expression preview If you want to validate a datasource expression before saving a rule, use `preview-sync` to execute a synchronous preview request and inspect the raw result. @@ -524,6 +569,41 @@ Common flags: | `--delay-seconds` | Shift the query window backward by a few seconds to compensate for ingestion latency | | `--data` | Add datasource-specific parameters such as `args` | +#### Datasource management (datasource-*) + +The `monit datasource-*` command family manages monitoring datasources (provided by the OpenAPI-generated commands): + +```bash +flashduty monit datasource-list [--type ] # List datasources (--type filters by type; omit for all) +flashduty monit datasource-info --id # Get one datasource +flashduty monit datasource-create [flags] # Create a datasource (payload via --data) +flashduty monit datasource-update [flags] # Update a datasource (--id required) +flashduty monit datasource-delete --id # Delete a datasource (referencing rules are not blocked; the datasource leaves their monitoring scope and their open alerts are closed) +``` + +Core fields for `datasource-create` / `datasource-update`: + +| Flag | Description | +|------|-------------| +| `--name` | Datasource display name (required); the `ds_name` referenced by query/diagnose APIs | +| `--type-ident` | Datasource type identifier (required): `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, plus 5 **diagnostic-only** types: `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka` | +| `--address` | Connection address. Required for every type except `elasticsearch` with `deployment: cloud`. Prometheus/Loki/VictoriaLogs: HTTP URL; MySQL/Oracle/Postgres/ClickHouse: `host:port`; SLS: endpoint without the `http(s)://` prefix. **Redis/MongoDB diagnostic types**: one `host:port`, bracket IPv6; no URI, userinfo or query. **Kafka**: 1–32 unique comma-separated `host:port` bootstrap addresses (no broker list in the payload). At most 4096 characters after normalization | +| `--edge-cluster-name` | Monitors edge cluster name responsible for evaluating rules using this datasource (required) | +| `--note` | Optional description | +| `--enabled` | **Business execution** switch. Omitted on create: `true`; omitted on update: preserve the current value. Explicit `false` disables execution (disabled datasources reject business queries and tools); `null` is invalid. **Does not change `alerting_enabled`** | +| `--alerting-enabled` | Whether this datasource may evaluate alerts. Omitted on create: `true` for alerting types, `false` for diagnostic-only types; omitted on update: preserve the current value; `null` is invalid. The 5 diagnostic types reject `true`; disabling is rejected with a conflict when enabled rules reference the datasource | +| `--data` | The `payload` configuration block (required), whose key must match `type_ident`, e.g. `{"payload":{"redis_node":{"database":0,"password":"..."}}}` | + +`enabled` and `alerting_enabled` are independent: alert evaluation requires both `enabled=true` and an alerting-capable type; `alerting_enabled=false` does not block non-alerting queries or tools, and `monit datasource-list` always reports `alerting_enabled=false` for diagnostic-only types. + +**Diagnostic-type payloads and secret handling**: + +- `redis_node`: `database` (Redis database number, default 0), `username` / `password`, `timeout_ms` (default 3000, range 1000–10000). +- `redis_sentinel`: `username` / `password`, `timeout_ms` (default 3000). +- `mongodb_mongod` / `mongodb_mongos`: `auth_source` (authentication database, defaults to `admin`; username and password must be configured together), `username` / `password`, `timeout_ms` (default 3000), TLS fields; client certificates are unsupported. +- `kafka`: `sasl_mechanism` (`none` default / `plain` / `scram-sha-256` / `scram-sha-512`, the latter three require username and password), `username` / `password`, `timeout_ms` (default 5000), TLS fields (`tls_min_version` defaults to 1.2, max 1.3). +- Passwords and `kafka.tls_key` support `${env:NAME}` references (resolved on the edge); literal values are omitted from responses, only `${env:...}` references are echoed. **On update, omit those fields to preserve stored secrets; explicitly send an empty string to clear**. + ### monit servicemap — Service topology (Beta) The `monit servicemap-*` command family accesses the ServiceMap capability; see [Service Map](/en/monitors/targets/servicemap) for the UI workflow. @@ -587,11 +667,36 @@ Common `create` flags: **Timezone semantics**: `--at` and `--cron-expr` are interpreted as local wall-clock time in the **rule's timezone**, which defaults at creation to the caller's member timezone, falling back to the account timezone when the member has none. Pass the user's local time directly — do **not** convert it to UTC. Neither `create` nor `update` has a `--timezone` flag: to pin a different timezone at creation, use the generated command `flashduty safari automation-rule-create --timezone`; a created rule's timezone cannot be changed via `update`. +### insight — Insight queries + +The `insight` command family queries aggregated incident metrics over a time window (response times, notification counts, and so on): + +```bash +flashduty insight incidents [flags] # List incidents with performance metrics (MTTA, MTTR, notifications) +flashduty insight top-alerts [flags] # Query top alert sources grouped by a label +flashduty insight incident-export [flags] # Export the filtered incident list as CSV (redirect to a file) +``` + +Common flags for `insight incidents`: + +| Flag | Description | Default | +|------|-------------|---------| +| `--since` / `--until` | Time window (same human-friendly formats as `incident list`) | `7d` / `now` | +| `--limit` | Max results (capped at 100) | `20` | +| `--page` | Page number | `1` | +| `--fields` | Field projection for `json`/`toon` output (comma-separated, e.g. `incident_id,title,severity`); ignored in table mode; at least one field required | default compact projection | + +In `json`/`toon` mode the rows default to the compact fields `incident_id`, `title`, `severity`, `channel_name`, `seconds_to_ack`, `seconds_to_close`, `notifications` (a stderr note announces the default projection and that `--fields` can change it); output is bounded at 16 KiB — overflowing rows are dropped or shortened, with all notes on stderr (see "Field projections for structured output" under "Output formats" below). + +`insight top-alerts`: `--label` is required (`check` or `resource`), `--since`/`--until` as above, `--limit` defaults to `10` (top-K), returning the alert count and event count per label value. + +`insight incident-export`: writes the filtered incident list as a CSV of header row plus data rows (redirect to a file; `--start-time`/`--end-time` take Unix seconds). The export endpoint returns a one-shot CSV and caps its row count server-side, so the command verifies the CSV data-row count against the `incident-list` total for the same filter after writing: on a shortfall the CSV is still written (a `rows=N` line goes to stderr) and the command exits non-zero stating written vs total — narrow the time window and retry. + ### Full command coverage -Beyond the curated commands above, the CLI now provides **full coverage** of the Flashduty OpenAPI through a spec-driven code generator. The current OpenAPI contains **337 API operations**, and the CLI generates corresponding resource-organized commands for 336 of them (`session-read-export` is provided by the hand-written `session export` / `safari session-export` commands). In addition to the On-call domain (incident, incident-trigger-subscription, change, channel, field, status-page, template, and more), it also covers: +Beyond the curated commands above, the CLI now provides **full coverage** of the Flashduty OpenAPI through a spec-driven code generator. The current OpenAPI contains **348 API operations**, and the CLI generates resource-organized commands for **345** of them; the remaining operations (e.g. `session-read-export`) are provided by hand-written commands (`session export` / `safari session-export`). In addition to the On-call domain (incident, incident-trigger-subscription, change, channel, field, status-page, template, and more), it also covers: -- **AI SRE (`safari`)**: a2a-agents, automations, knowledge, mcp-servers, sessions, skills, and more +- **AI SRE (`safari`)**: a2a-agents, artifacts, automations, knowledge, mcp-servers, sessions, skills, and more - **Alerting & noise reduction**: alert, alert-event, enrichment (alert-rules, rule-sets), route - **On-call & scheduling**: calendar, schedule - **Platform administration**: account, member, person, team, role (roles-permissions), audit (audit-logs) @@ -636,6 +741,31 @@ Common flags: `knowledge-file-put` requires `--content-b64` to be the Base64 encoding of valid UTF-8 text; `--content-type` is inferred from the file extension when omitted. `knowledge-file-delete` refuses to remove a file still referenced by other pack files unless `--force` is passed, in which case the referrers are returned as warnings. +#### artifacts — AI SRE artifact gallery + +The `safari artifact-*` command family manages **artifacts** produced by AI SRE sessions — publishing to the gallery, sharing, and signed downloads. See [Artifacts](/en/ai-sre/artifacts) for the console workflow: + +```bash +flashduty safari artifact-gallery-list [flags] # List artifacts (--scope all|personal|team, --query title search, --orderby created_at|updated_at, --limit default 20 cap 100, --page, --team-ids, --asc) +flashduty safari artifact-gallery-get # Get artifact detail (including public-share state) +flashduty safari artifact-gallery-publish-from-file --title # Publish a session-produced file (pf_ prefix) as an artifact +flashduty safari artifact-gallery-file-state [...] # Check which files already have a live artifact (at most 50 per call) +flashduty safari artifact-gallery-update [flags] # Rename (--title) or transfer scope (--team-id: 0 = personal, positive = team) +flashduty safari artifact-gallery-delete # Remove from the gallery (the source file stays with its session) +flashduty safari artifact-sign [--share-token ] # Create short-lived signed URLs (download/preview, valid 5 minutes) +flashduty safari artifact-stream --t [--mode download|preview] # Download or preview file bytes with a signed token (any other --mode falls back to download) +flashduty safari artifact-gallery-share-enable # Enable anonymous public sharing, returns public_url +flashduty safari artifact-gallery-share-revoke # Revoke public sharing (the link stops resolving immediately) +flashduty safari artifact-gallery-share-sync # Refresh the public snapshot with the latest content +``` + +Public-sharing and signing semantics: + +- `public_url` is a console `/share/artifact/` page served **entirely from the CDN**; it exists only while sharing is on, and anyone with the link can view the content without logging in. +- The public snapshot is materialized from the artifact's current `file_id`: when `share_enabled=true` and the response's `share_file_id` differs from `file_id`, the public snapshot is stale — call `artifact-gallery-share-sync` to refresh it before referencing it externally. +- The `artifact-sign` token is bound to the calling account and person and is valid for 5 minutes (response `expires_in`); `download_url` / `preview_url` are relative paths (`/safari/artifact/stream?...`) — prepend the API base (`https://api.flashcat.cloud`). +- An artifact's initial scope inherits from its source session (personal-session artifacts belong to the creator; team-bound session artifacts belong to the team); `can_edit` tells whether the caller may rename/transfer/delete/share it (the creator, any member of the owning team, or a manager of the source session). + ### Utility commands ```bash @@ -676,7 +806,7 @@ Showing 2 results (page 1, total 2). -Machine-parseable. Except for the commands with default compact fields listed below, it returns the command's full response data; table-column truncation does not apply to JSON. Ideal for scripts and CI/CD pipelines. +Machine-parseable. Except for the commands with default compact fields listed below, it returns the command's full response data; table-column truncation does not apply to JSON. Ideal for scripts and CI/CD pipelines. Note that generated commands' **list-shaped** responses are bounded at 16 KiB in `json` mode too (see "Generated-command output bound" below). ```bash flashduty incident list --json | jq '.[].title' @@ -684,7 +814,7 @@ flashduty incident list --json | jq '.[].title' -TOON (Token-Oriented Object Notation) drops the per-row field names that JSON repeats for homogeneous arrays, cutting token usage substantially on list output and making it well suited to AI agents. Commands with default compact fields listed below emit their field projections and are size-bounded. +TOON (Token-Oriented Object Notation) drops the per-row field names that JSON repeats for homogeneous arrays, cutting token usage substantially on list output and making it well suited to AI agents. Commands with default compact fields listed below emit their field projections and are size-bounded; generated commands' list-shaped output is bounded at 16 KiB as well (see "Generated-command output bound" below). ```bash flashduty incident list --output-format toon @@ -700,6 +830,16 @@ Table view with no column truncation — useful for copy-paste or wide terminals +#### Generated-command output bound + +Generated commands (the ones covering the OpenAPI through the code generator, such as `safari session-list`, `monit datasource-list`, `safari a2a-agent-list`) apply the same 16 KiB bound to **list-shaped** responses in `json`/`toon` mode, mirroring the curated commands' behavior, with every note going only to stderr and stdout left untouched: + +1. **The whole page overflows**: only the leading rows that fit are emitted, with every value intact, and a stderr note reports how many of the N/M rows were emitted. +2. **A single row alone overflows the budget**: that row's string values are shortened and end with `...`; a stderr note names the clipped fields. Identifier fields (keys ending in `_id` or `_key`) are never shortened. +3. **A row cannot be reduced enough to fit**: the command fails and names the largest fields (up to 3, with their byte sizes); lower `--limit` or reduce the output fields and retry. + +**Detail-shaped single objects** (e.g. `safari session-get`) are never bounded or shortened — a shortened id or status would pass for a real value, so these responses print untouched. Generated commands mostly have no `--fields`; for complete JSON lower `--limit` and page through with `--page` (e.g. `flashduty safari session-list --limit 20 --page 2`), or narrow the filter. + ### Field projections for structured output The following commands support `--fields` with `json` or `toon` output. Supply comma-separated top-level response fields; an unknown field fails immediately, and table output ignores this flag. @@ -711,6 +851,7 @@ The following commands support `--fields` with `json` or `toon` output. Supply c | `flashduty incident detail ` | Returns full detail when `--fields` is omitted; otherwise returns only the selected fields | 8 KiB for projections only | | `flashduty alert-event list` | `event_id`, `alert_id`, `event_severity`, `event_status`, `event_time`, `title` | 16 KiB | | `flashduty channel escalate-rule-list ` | `rule_id`, `rule_name`, `status`, `priority`, `filters` | 16 KiB | +| `flashduty insight incidents` | `incident_id`, `title`, `severity`, `channel_name`, `seconds_to_ack`, `seconds_to_close`, `notifications` | 16 KiB | For example, export only an incident ID, title, and progress: @@ -718,7 +859,7 @@ For example, export only an incident ID, title, and progress: flashduty incident list --json --fields incident_id,title,progress ``` -When a list projection (`incident list`, `incident similar`, `alert-event list`, `channel escalate-rule-list`) exceeds its 16 KiB limit, the CLI handles it in three tiers, with every note going to stderr and stdout left untouched: +When a list projection (`incident list`, `incident similar`, `alert-event list`, `channel escalate-rule-list`, `insight incidents`) exceeds its 16 KiB limit, the CLI handles it in three tiers, with every note going to stderr and stdout left untouched: 1. **Whole page overflows**: only the leading rows that fit are emitted, with every value left intact (no truncation), and a stderr note reports how many of the rows were emitted while the rest were not; narrow `--fields` or lower `--limit` to fit more rows per page. 2. **A single row alone overflows the budget**: that row's string values are shortened and end with `...`, and a stderr note names the clipped fields — matching or filtering on a shortened field will miss, so narrow `--fields` or `--limit` for untruncated values. Identifier fields (keys ending in `_id` or `_key`) are never shortened at any tier. diff --git a/en/developer/go-sdk.mdx b/en/developer/go-sdk.mdx index 81cb2853..f08e95d4 100644 --- a/en/developer/go-sdk.mdx +++ b/en/developer/go-sdk.mdx @@ -1,7 +1,7 @@ --- title: Flashduty Go SDK sidebarTitle: Go SDK -description: "go-flashduty is the official open-source Go SDK for Flashduty — a typed, strictly 1:1 wrapper over the Open API currently covering all 337 API operations across 39 services." +description: "go-flashduty is the official open-source Go SDK for Flashduty — a typed, strictly 1:1 wrapper over the Open API currently covering all 349 API operations across 39 services." keywords: ["Go SDK", "go-flashduty", "Open API", "Golang", "client"] --- @@ -11,7 +11,7 @@ keywords: ["Go SDK", "go-flashduty", "Open API", "Golang", "client"] `go-flashduty` is the official open-source Go client for Flashduty, covering every REST endpoint of the Flashduty Open API. It follows the same design as [go-github](https://github.com/google/go-github) — service groups, typed requests and responses, a composable transport layer — and stays strictly 1:1 with the OpenAPI spec: each method maps to exactly one HTTP call, returns `(*T, *Response, error)`, and performs no implicit cross-endpoint aggregation or enrichment. -The SDK currently covers **337 API operations** across **39 services**, all generated from the Flashduty OpenAPI spec, covered by unit tests, and end-to-end verified against the live API. +The SDK currently covers **349 API operations** across **39 services**, all generated from the Flashduty OpenAPI spec, covered by unit tests, and end-to-end verified against the live API. The SDK is deliberately "thin." Consumer-side logic such as short-ID resolution and cross-endpoint orchestration belongs in the caller (CLI / MCP), not stuffed into the SDK or shoehorned into an endpoint. This keeps the SDK strictly one-to-one with the API — predictable, generatable, and verifiable. @@ -164,6 +164,7 @@ Endpoints are grouped by service and hang off the client: the call convention is | `client.ServiceMap` | Service map (ServiceMap) | | `client.Analytics` | Analytics | | `client.A2aAgents` | A2A Agents | +| `client.Artifacts` | AI SRE artifacts | | `client.Automations` | AI SRE automations | | `client.Knowledge` | AI SRE knowledge base (knowledge packs and files) | | `client.McpServers` | MCP Servers | @@ -179,9 +180,19 @@ Endpoints are grouped by service and hang off the client: the call convention is | `client.SessionReplay` | RUM session replay | | `client.Sourcemaps` | RUM sourcemaps | +`client.StatusPages.DraftCreate` (`POST /status-page/draft/create`) stores a status page event draft for a human to review and publish from the console; it is never directly visible to the public: `draft` is arbitrary JSON stored verbatim, up to 64 KB serialized, with `page_id`, `type` (`incident` or `maintenance`), `name`, and `message` validated; `change_id` (> 0 appends an update to an existing event), `status`, and `affected_components` are optional, and for a new maintenance you can set `start_time` / `end_time` (Unix seconds) for the window. The request-level `source` is an opaque marker of the drafting origin (up to 64 characters, e.g. `ai_sre:sess_xxx`); the response returns a `draft_id` matching `draft_[A-Za-z0-9]{22}`, which the console review link carries. + `client.Knowledge` covers the 9 operations under `/safari/knowledge/*`: on the pack side `PackReadGet` (get the account pack), `PackReadList` (list packs), `PackWriteEnsure` (ensure a pack exists), `PackWriteUpdate` (change a pack's scope), and `PackWriteDelete` (delete a pack); on the file side `FileReadGet`, `FileReadList`, `FileWritePut` (upload/overwrite), and `FileWriteDelete`. Exported types include `KnowledgePackItem`, `KnowledgeFileItem`, `KnowledgeWarning`, and the various `Knowledge*Request` / `Knowledge*Response` structs. -`client.Diagnostics` (diagnostics) provides datasource query methods: `QueryData` runs a synchronous query via `POST /monit/query/data` and returns a stable `query_result.v1` structured result (`format` is always `query_result.v1`; `result.kind` is one of `frames` / `records` / `samples`). This API requires monit-edge v0.65.0 or later. `QueryDiagnose` (`POST /monit/query/diagnose`) runs pre-clustered RCA analysis (log patterns or metric trends) and can take up to 35 seconds. +`client.Artifacts` (AI SRE artifacts) covers the 11 operations under `/safari/artifact/*`: on the gallery read side `ReadGet` (get a single published artifact by ID), `ReadList` (list artifacts visible to the caller, with title substring search and `scope` (`all` / `personal` / `team`) plus `team_ids` filtering), and `ReadGetFileState` (probe up to 50 presented-file IDs (`pf_` prefix) in one call for ones that already have a live published artifact); on the file side `ReadSign` (issue short-lived download/preview URLs for a presented file, valid 5 minutes, `expires_in` is fixed at 300) and `ReadStream` (download or preview the file's bytes with a signed token — the success body is a file, not a JSON envelope, with the raw bytes on `Response.Raw`); on the write side `WritePublish` (publish a session-produced file to the gallery), `WriteUpdate` (rename the artifact or transfer it between personal and team scope), and `WriteDelete` (detach it from the gallery; the source file stays with its session); public sharing `WriteShareEnable` (turn on anonymous public sharing and return the public link — anyone with the link can view it, no login required), `WriteShareRevoke` (turn sharing off; the link stops resolving immediately), and `WriteShareSync` (refresh the public snapshot with the latest content — when `share_enabled` is true and `share_file_id` differs from `file_id`, the snapshot is stale and calling this refreshes it). Exported types include `PublishedArtifactItem`, `ArtifactShareState`, `SignedUrLs`, and the various `Artifact*Request` / `Artifact*Response` structs. + +`client.Diagnostics` (diagnostics) provides datasource query methods: `QueryData` runs a synchronous query via `POST /monit/query/data` and returns a stable `query_result.v1` structured result (`format` is always `query_result.v1`; `result.kind` is one of `frames` / `records` / `samples`). This API requires monit-edge v0.65.0 or later. `QueryDiagnose` (`POST /monit/query/diagnose`) runs pre-clustered RCA analysis (log patterns or metric trends) and can take up to 35 seconds — **but it is deprecated**: migrate to `client.DataSources.ToolsInvoke` using the `prometheus.metric_trends`, `loki.log_patterns`, or `victorialogs.log_patterns` tools. It is retained for existing consumers; the legacy request and response remain unchanged. + +`client.DataSources.ToolsInvoke` (`POST /monit/datasource/tools/invoke`, `monit-datasource-tools-invoke`) executes one deterministic tool against a configured datasource: `tool` is a single tool name prefixed by the datasource type (e.g. `mysql.overview`), and `params` is the tool-specific JSON parameters (omitted means `{}`; an explicit `null` is invalid). Free SQL goes through `/monit/query/data`; `mysql.query` and `postgres.query` are unsupported. It requires all currently online routable Edge sessions in the cluster to support the v0.71.0 base invoke protocol (individual tools may require a newer implementation), and there is no tool catalog, no automatic replay, and no fallback to Agent or legacy diagnose. The request body limit is 128 KiB, the complete success response limit is 1 MiB, and the tool timeout is at most 25 seconds; the response is a `DatasourceToolResult` (`data` is tool-specific JSON, never null, `summary` is optional, and a `truncated` object with `reason` indicates truncation). + +For `client.DataSources`, the `payload` selects a type-specific configuration block by `type_ident`. Fifteen `type_ident` values are allowed: `prometheus`, `loki`, `mysql`, `oracle`, `postgres`, `clickhouse`, `elasticsearch`, `sls`, `tencent_cls`, `victorialogs`, plus the new diagnostic-only types `redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, and `kafka` — diagnostic-only types always have `alerting_enabled` false (which does not block non-alerting queries or tools) and reject true. Connection address rules: Redis/MongoDB diagnostic types take a single `host:port` (bracket IPv6), with no URI, userinfo, or query; `kafka` takes 1–32 unique comma-separated `host:port` bootstrap addresses (at most 4096 characters after normalization, and the payload has no broker list); for `mongodb_mongod` / `mongodb_mongos` the configuration block's `auth_source` defaults to `admin`, username and password must be configured together, and client certificates are unsupported; the Redis node configuration's `database` defaults to 0. Sensitive fields such as the diagnostic types' `password` and Kafka's `tls_key` support `${env:NAME}` references: literal values are omitted from responses (only `${env:...}` references are echoed back), omitting the fields on update preserves the stored values, and explicitly sending an empty string clears them. + +`enabled` and `alerting_enabled` are independent: `enabled` (whether business execution is enabled) defaults to true on create; `alerting_enabled` (whether alert evaluation is allowed; alerting also requires `enabled` true and an alerting-capable type) defaults to true for alerting types and false for diagnostic-only types on create. On update, omitting either preserves the current value and an explicit `null` is invalid; disabling (`enabled` false) is rejected with a conflict when enabled rules reference the datasource. Also note that `payload` is always `null` in `/monit/datasource/list` responses (the list query does not read the payload column); it is populated in create/update/info responses. All identifiers, service field names, and method names match the generated code. For exactly which methods each service has and their request and response types, rely on `services_gen.go` and the per-service files, plus the [Open API reference](/en/openapi/introduction). @@ -259,7 +270,7 @@ for page := 0; page < 100; page++ { --- -An unsuccessful call returned by the Flashduty API — whether the envelope carries an error or the HTTP status is non-2xx — returns `*ErrorResponse`. It has `Code`, `Message`, and `RequestID` fields; when troubleshooting, give `RequestID` to the support team to pinpoint the request. +An unsuccessful call returned by the Flashduty API — whether the envelope carries an error or the HTTP status is non-2xx — returns `*ErrorResponse`. It has `Code`, `Message`, an optional `Reason`, and `RequestID` fields; when troubleshooting, give `RequestID` to the support team to pinpoint the request. `Reason` carries the server-supplied optional cause (the envelope's `DutyError` has the same field, JSON `reason`,omitempty); when non-empty it is also appended to the end of the error string, as `, reason X`. When the API returns 429, the error is promoted to `*RateLimitError`: it embeds `*ErrorResponse` (so `errors.As` for `*ErrorResponse` still matches) and additionally carries a `RetryAfter` hint. diff --git a/en/developer/overview.mdx b/en/developer/overview.mdx index f9937eff..0bbccd39 100644 --- a/en/developer/overview.mdx +++ b/en/developer/overview.mdx @@ -58,7 +58,7 @@ See the [Command-line tool](/en/developer/cli) guide for the full installation m ## Go SDK -go-flashduty is the official Go SDK for Flashduty. Built in the go-github style, it provides a typed wrapper over the Flashduty OpenAPI covering 337 API operations across 39 services, so you can call them directly from Go with full type safety and autocompletion. +go-flashduty is the official Go SDK for Flashduty. Built in the go-github style, it provides a typed wrapper over the Flashduty OpenAPI covering 349 API operations across 39 services, so you can call them directly from Go with full type safety and autocompletion. The module is `github.com/flashcatcloud/go-flashduty` and requires Go 1.24+. Install with one command: diff --git a/en/home.mdx b/en/home.mdx index 5caa4fda..cade4420 100644 --- a/en/home.mdx +++ b/en/home.mdx @@ -162,7 +162,7 @@ Integrate Flashduty through Open API and Webhooks for automation and custom deve Authentication, request specs, error handling - All 337 endpoints organized by module + All 354 endpoints organized by module Traditional and cursor pagination diff --git a/en/monitors/data-sources/data-sources.mdx b/en/monitors/data-sources/data-sources.mdx index 8e7ce0f3..83b18ff6 100644 --- a/en/monitors/data-sources/data-sources.mdx +++ b/en/monitors/data-sources/data-sources.mdx @@ -1,7 +1,7 @@ --- title: "Data source management" -description: "Configure and manage data sources for Monitors, including Prometheus, Elasticsearch, Loki, ClickHouse, MySQL, Oracle, PostgreSQL, Aliyun SLS, Tencent CLS, and VictoriaLogs" -keywords: ["data source", "Prometheus", "Elasticsearch", "Loki", "ClickHouse", "MySQL", "Oracle", "PostgreSQL", "SLS", "Tencent CLS", "VictoriaLogs"] +description: "Configure and manage data sources for Monitors, including Prometheus, Elasticsearch, Loki, ClickHouse, MySQL, Oracle, PostgreSQL, Aliyun SLS, Tencent CLS, VictoriaLogs, Redis, MongoDB, and Kafka" +keywords: ["data source", "Prometheus", "Elasticsearch", "Loki", "ClickHouse", "MySQL", "Oracle", "PostgreSQL", "SLS", "Tencent CLS", "VictoriaLogs", "Redis", "MongoDB", "Kafka", "datasource tool"] --- Data sources are where the alert engine queries data. You need to configure data sources first so the alert engine can read data from them for anomaly detection. @@ -10,7 +10,7 @@ Data sources are where the alert engine queries data. You need to configure data ## Supported data source types -Monitors supports the following 10 data source types: +Monitors supports the following 15 data source types: | Type | Description | |------|-------------| @@ -24,6 +24,13 @@ Monitors supports the following 10 data source types: | **Aliyun SLS** | Alibaba Cloud Log Service | | **Tencent CLS** | Tencent Cloud Log Service | | **VictoriaLogs** | Log database, a logging solution from the VictoriaMetrics ecosystem | +| **Redis Node** (`redis_node`) | Standalone Redis, diagnostic-only | +| **Redis Sentinel** (`redis_sentinel`) | Redis Sentinel cluster, diagnostic-only | +| **MongoDB Mongod** (`mongodb_mongod`) | Standalone MongoDB, diagnostic-only | +| **MongoDB Mongos** (`mongodb_mongos`) | MongoDB sharded cluster router, diagnostic-only | +| **Kafka** (`kafka`) | Apache Kafka cluster, diagnostic-only | + +Of these, the 5 **diagnostic-only types** — Redis Node, Redis Sentinel, MongoDB (mongod/mongos) and Kafka — are used for database and middleware diagnostics (see [Host diagnostics and data source diagnostics](/en/monitors/targets/overview#host-diagnostics-and-data-source-diagnostics)) and cannot evaluate alerts: `alerting_enabled` cannot be enabled (always `false`), so they cannot participate in alert rule queries and evaluation. Connection address requirements are covered in [Data source type configuration](#data-source-type-configuration). ## Data source list @@ -73,6 +80,20 @@ Alert rules support two methods for binding data sources. Both can be used toget Wildcard by name stores name strings — if a data source is renamed, existing wildcard rules may no longer match. Exact match by ID stores the data source ID and is unaffected by renames. If stability is a priority, prefer exact match. +## Enabled and alert evaluation switches + +Data sources have two independent switches, controlling business execution and alert evaluation respectively: + +| Switch | Field | Meaning | +|--------|-------|---------| +| **Enabled** | `enabled` | Whether business execution is enabled. When disabled, the data source rejects business queries and datasource tools, but `alerting_enabled` is unchanged | +| **Alert evaluation** | `alerting_enabled` | Whether the data source may participate in alert rule queries and evaluation. Alert evaluation also requires `enabled=true` and an alerting-capable type; `false` does not block non-alerting queries and datasource tools | + +- **Create defaults**: `enabled` defaults to `true`; `alerting_enabled` defaults to `true` for alerting-capable types and `false` for diagnostic-only types. +- **Update behavior**: omitting either field preserves the current value; an explicit `null` is invalid. +- **Diagnostic-only types** (`redis_node`, `redis_sentinel`, `mongodb_mongod`, `mongodb_mongos`, `kafka`) reject `alerting_enabled=true`. +- **Conflict protection**: when enabled alert rules reference the data source, disabling `alerting_enabled` is rejected with a conflict (HTTP 409); handle the referencing rules first. In addition, alert evaluation in practice requires the data source to be `enabled=true`. + ## Data source type configuration ### Prometheus @@ -245,6 +266,57 @@ The region picker, shared by rule queries and the connection test, offers a list Alert rules of the Tencent CLS type can bind exactly one data source and do not support name patterns. When creating a rule, the data source picker is single-select and the name-pattern input is hidden; an invalid configuration is rejected on save with "This data source type can bind only one data source" or "This data source type does not support name patterns. Clear them and pick one data source." See [Tencent CLS alert rules](/en/monitors/alert-rules/tencent-cls). +### Redis Node / Redis Sentinel + +`redis_node` (standalone Redis) and `redis_sentinel` (Redis Sentinel cluster) are diagnostic-only types and cannot evaluate alerts. The connection address is a single `host:port` (e.g., `localhost:6379`, `localhost:26379`); IPv6 addresses must be bracketed (e.g., `[::1]:6379`). URIs, userinfo, and query parameters are not accepted, and `${env:}` references are not supported in the address. Addresses are limited to 4096 characters after normalization. + +| Config Item | Description | +|-------------|-------------| +| **Connection address** | Single `host:port`; bracket IPv6; no URI, userinfo, or query parameters | +| **Username** | Optional; supports `${env:NAME}` environment variable references | +| **Password** | Optional; supports `${env:NAME}` references; literal password is not echoed after saving | +| **Database number** (Redis Node only) | Redis DB number; defaults to `0` | +| **Timeout (milliseconds)** | Connection timeout; defaults to `3000`; range 1000–10000 | + +### MongoDB (mongod / mongos) + +`mongodb_mongod` (standalone MongoDB) and `mongodb_mongos` (MongoDB sharded cluster router) are diagnostic-only types and cannot evaluate alerts. The connection address is a single `host:port` (e.g., `localhost:27017`); IPv6 addresses must be bracketed. URIs, userinfo, and query parameters are not accepted, and `${env:}` references are not supported in the address. Addresses are limited to 4096 characters after normalization. + +| Config Item | Description | Default | +|-------------|-------------|---------| +| **Connection address** | Single `host:port`; bracket IPv6; no URI, userinfo, or query parameters | - | +| **Username / Password** | Authentication credentials; must be configured together; supports `${env:NAME}` references; literal password is not echoed after saving | - | +| **Authentication database** | Database used for authentication | `admin` | +| **Timeout (milliseconds)** | Connection timeout | `3000` | +| **TLS** | Whether TLS is enabled | Disabled | +| **CA certificate** | PEM CA certificates or an `${env:NAME}` reference | - | +| **Minimum / Maximum TLS version** | TLS 1.2 (default) or 1.3; the maximum must not be below the minimum | 1.2 / no constraint | +| **Server name** | SNI / certificate hostname for the TLS handshake; defaults to the hostname in the connection address | - | +| **Skip server certificate verification** | Skip server certificate verification when TLS is enabled | No | + +MongoDB does not support client certificate authentication (mTLS). + +### Kafka + +`kafka` is a diagnostic-only type and cannot evaluate alerts. The connection address holds 1–32 unique comma-separated `host:port` bootstrap addresses (e.g., `broker1:9092,broker2:9092`); the broker list lives in the connection address only — the payload does not contain a broker list. IPv6 addresses must be bracketed. URIs, userinfo, and query parameters are not accepted, and `${env:}` references are not supported in the address. Addresses are limited to 4096 characters after normalization. + +| Config Item | Description | Default | +|-------------|-------------|---------| +| **Connection address** | 1–32 unique `host:port` addresses, comma-separated | - | +| **SASL mechanism** | `none` (credentials not accepted), `plain`, `scram-sha-256`, `scram-sha-512` (the last three require username and password) | `none` | +| **Username / Password** | SASL credentials; supports `${env:NAME}` references; literal password is not echoed after saving | - | +| **Timeout (milliseconds)** | Connection timeout | `5000` | +| **TLS** | Whether TLS is enabled | Disabled | +| **CA certificate** | PEM CA certificates or an `${env:NAME}` reference | - | +| **Client certificate / key** | PEM format; must be configured as a pair; the literal key is not echoed after saving; supports `${env:NAME}` references | - | +| **Minimum / Maximum TLS version** | TLS 1.2 (default) or 1.3; the maximum must not be below the minimum | 1.2 / no constraint | +| **Server name** | SNI / certificate hostname for the TLS handshake; defaults to the hostname in the connection address | - | +| **Skip server certificate verification** | Skip server certificate verification when TLS is enabled | No | + +### Credential save semantics + +As with Tencent CLS, these 5 diagnostic types treat passwords (and the Kafka client private key) as write-only fields: after saving, neither the list nor the detail returns the literal value. Values saved as `${env:}` references are not secrets and are shown as-is. When updating, omitting the field preserves the saved value; sending an explicit empty string clears it. + ## Reference credentials locally in Edge With Edge `v0.46.0` or later, you can use environment variable references in supported data-source connection fields instead of placing credentials directly in the data-source configuration. Edge resolves each reference in its local process; the resolved credential is never written back to the synced data-source configuration, debug output, or API payloads. diff --git a/en/monitors/targets/overview.mdx b/en/monitors/targets/overview.mdx index 31da1fec..c69bc450 100644 --- a/en/monitors/targets/overview.mdx +++ b/en/monitors/targets/overview.mdx @@ -43,6 +43,41 @@ flowchart TD The Agent provides five host tools: `os.overview`, `os.top_processes`, `shell.exec`, `net.tcp_ping`, and `http.get`. The available set depends on the Agent version and local policy. TCP/HTTP probes provide connectivity evidence from the host; data source diagnostics inspect database internals. +Agent host tools act on the host only: `tools-catalog` and `tools-invoke` support only the `host` target kind, and database service endpoints are not Agent targets. For database and middleware diagnostics, use the **datasource tools** instead (see below), executed by the Edge that can reach the data source. Datasource tool invocation requires the data source `enabled=true`; `alerting_enabled=false` does not block diagnostics. + +### Datasource tools + +Every configured data source provides a set of named diagnostic tools, prefixed by the data source type, for example: + +| Data source type | Example tools | +|------------------|---------------| +| MySQL | `mysql.overview`, `mysql.lock_contention` | +| PostgreSQL | `postgres.activity` | +| Redis | `redis_node.slowlog` | +| Kafka | `kafka.consumer_lag` | +| Elasticsearch | `elasticsearch.cat` | +| Prometheus | `prometheus.metric_trends` | +| Loki / VictoriaLogs | `loki.log_patterns`, `victorialogs.log_patterns` | + +- **One call invokes one named tool**, targeted by data source ID (`datasource_id`). The same connection address configured as multiple data source IDs means different credentials or configurations and must remain separate. +- **No tool catalog**: tool names and parameters come from the type-specific reference — do not guess parameters. The `mysql.query` and `postgres.query` tools have been removed; use data source queries (monit-query Data) for free-form SQL. +- **Version gate**: all currently online routable Edge sessions in the selected cluster must support the v0.71.0 base invoke protocol; individual tools may require a newer implementation. See the error reasons below when the gate is not met. +- **No automatic fallback**: the endpoint provides no tool catalog, automatic replay, or fallback to Agent or the legacy diagnose flow. On version-related errors, upgrade Edge rather than restarting or rotating Edges. Request body limit 128 KiB; complete success response limit 1 MiB; tool timeout at most 25 seconds. + +Errors are returned via `error.reason`: + +| reason | Meaning | +|--------|---------| +| `edge_upgrade_required` | Edge version below v0.71.0; upgrade the Edges in the cluster | +| `mixed_edge_versions` | Mixed Edge versions in the cluster with some instances outdated; upgrade them uniformly | +| `no_active_edge` | No online routable Edge session in the cluster | +| `tool_not_supported` | The tool is not supported by the current implementation | +| `invalid_request` | Invalid request parameters; fix the parameters and retry | +| `source_too_large` | Request body exceeds 128 KiB; narrow the request | +| `result_too_large` | Result exceeds 1 MiB; narrow the request | +| `datasource_disabled` | The data source is disabled (`enabled=false`) | +| `datasource_not_found` | The data source does not exist | + The Agent also provides host topology collection and reporting for [ServiceMap](/en/monitors/targets/servicemap). diff --git a/en/on-call/advanced/war-room.mdx b/en/on-call/advanced/war-room.mdx index 703bd8d9..ae3518f1 100644 --- a/en/on-call/advanced/war-room.mdx +++ b/en/on-call/advanced/war-room.mdx @@ -109,6 +109,10 @@ Flashduty On-call War Room is an automated collaboration feature designed for in + +**Platform-created war room chats cannot be used as standing notification targets.** Every chat carries an origin mark: `origin=system` means the platform created it (today, that is only war rooms), distinguishing it from human-created chats. Accordingly, the group-chat pickers in escalation rules' **IM app groups** (Feishu/DingTalk, Slack, and Microsoft Teams group chats) and in schedule handoff notifications' **group chat channels** (Feishu/DingTalk and Slack) automatically exclude war rooms — the Feishu/DingTalk and Slack pickers even read "Select … group chat (war rooms excluded)". A war room is born with an incident and dies with it: configuring one as a standing notification target points the configuration at a group that is bound to disappear. If a saved chat ID no longer resolves (war room dissolved, bot removed from the group, group deleted), the picker shows that target as **Chat unavailable**, with a remove button to clear it. + + ### Mobile App The Flashduty App supports the full war room lifecycle, sharing the same war room capabilities as the console and IM apps. Key mobile behaviors: diff --git a/en/on-call/analytics/insights.mdx b/en/on-call/analytics/insights.mdx index ba9aa119..368d16ca 100644 --- a/en/on-call/analytics/insights.mdx +++ b/en/on-call/analytics/insights.mdx @@ -36,7 +36,8 @@ When customizing filter conditions, the system remembers your selections. Even a | Channel | Select channel names to query, supports multiple selection. Dashboard data updates based on selected channels | | Severity | Select severity levels to query, supports multiple selection. Dashboard data updates based on selected severity levels | | Time Range | Select time range to query. Supports this week, last two weeks, this month, last month, and custom time ranges, querying up to the last **2 years (720 days)** of data (the exact limit depends on your plan) | -| Data Interval | Supports day, week, and month dimensions. Defaults to hourly queries, but when time range exceeds 31 days, daily preview is not available | +| Data Interval | Supports day, week, and month dimensions. Defaults to hourly queries, but when time range exceeds 31 days, daily preview is not available. Day/week/month bucketing follows the viewer's effective time zone (personal time zone preferred, falling back to the organization's) | +| Time Zone | Dashboard times, day/week/month aggregation, and queries are all displayed and counted in the viewer's effective time zone (personal time zone preferred, falling back to the organization's). The filter bar shows the current effective time zone on the right, with the tooltip "Times are shown and bucketed in your local timezone." | | Sorting | Team, channel, and individual dimension dashboards support ascending and descending order. Defaults to showing TOP 10 data; expand to show more | ## Time Period Segmentation diff --git a/en/on-call/channel/escalation-rule.mdx b/en/on-call/channel/escalation-rule.mdx index 2a2a531a..42623085 100644 --- a/en/on-call/channel/escalation-rule.mdx +++ b/en/on-call/channel/escalation-rule.mdx @@ -75,7 +75,7 @@ Determines how users are reached. Send to instant messaging groups, with support for @ mentioning relevant personnel. - - **IM App Groups**: Supports Feishu/Lark, Dingtalk, WeCom, Slack, and Microsoft Teams groups (WeCom is only available for existing configurations and cannot be selected when creating new rules), requires completing [IM Integration](/en/on-call/integration/instant-messaging/lark) first + - **IM App Groups**: Supports Feishu/Lark, Dingtalk, WeCom, Slack, and Microsoft Teams groups (WeCom is only available for existing configurations and cannot be selected when creating new rules), requires completing [IM Integration](/en/on-call/integration/instant-messaging/lark) first. The group-chat picker automatically excludes platform-created chats such as war rooms (placeholder: "Select … group chat (war rooms excluded)"); stale targets render as **Chat unavailable** and can be removed - **Group Bots**: Supports Feishu/Lark, Dingtalk, WeCom, Slack, Telegram, Zoom, and other Webhook bots. Telegram requires configuring a Webhook notification address and Chat IDs, Zoom requires configuring a Webhook address and Verify Token, and supports enabling @ mention functionality. See [Notification Channel Configuration](/en/on-call/configuration/notifications) diff --git a/en/on-call/configuration/schedule.mdx b/en/on-call/configuration/schedule.mdx index 9251e64c..dbedbbb3 100644 --- a/en/on-call/configuration/schedule.mdx +++ b/en/on-call/configuration/schedule.mdx @@ -64,7 +64,7 @@ Understanding these concepts before configuration will help you better plan your - **Follow personal preference**: Each responder receives notifications via their personally configured channels - **Follow unified settings**: Administrators select notification channels (SMS, email, and integrated IM apps) - **Group Chat Channels**: Send notifications to group chats, supporting the following platforms: - - Feishu app, DingTalk app, Slack app (select chat groups via integrated IM apps) + - Feishu app, DingTalk app, Slack app (select chat groups via integrated IM apps; the picker automatically excludes platform-created chats such as war rooms, and stale targets render as **Chat unavailable** and can be removed) - WeCom bot, DingTalk bot, Feishu bot (send via webhook URL) - Slack bot, Telegram bot, Zoom bot diff --git a/en/on-call/integration/sso/role-team-sync.mdx b/en/on-call/integration/sso/role-team-sync.mdx new file mode 100644 index 00000000..4d3823c6 --- /dev/null +++ b/en/on-call/integration/sso/role-team-sync.mdx @@ -0,0 +1,97 @@ +--- +title: "Role and Team Sync" +description: "For SAML2.0, OIDC, and CAS, member roles and teams are synced by exactly matching the role/team names returned by the identity provider (claim/attribute names); default roles/teams apply when no name matches" +keywords: ["SSO", "single sign-on", "role sync", "team sync", "sync configuration", "claim"] +--- + +In the **Platform Management → Single Sign-On** settings page, the **Sync Configuration** section decides how members get their Flashduty roles and teams when they sign in via SSO: + +- **SAML2.0 / OIDC / CAS**: matching by the **role names / team names** returned by the identity provider (claim / attribute names); when no name matches, the configured **default roles / default teams** apply. +- **LDAP**: does not use name matching; instead it matches the user's **LDAP Group** DN against mapping rules. See [LDAP Role and Team Synchronization](/en/platform/configure-sso#ldap-role-and-team-synchronization). + +Sync runs on **every SSO sign-in**. This page describes the sync configuration and matching rules for SAML2.0 / OIDC / CAS. + +## Sync Configuration Fields + +The **Sync Configuration** section contains the following fields: + +| Field | Description | +| --- | --- | +| Sync Roles (`sync_role_enabled`) | Switch. When on, roles are synced by name; when off, sign-in never changes a member's roles | +| Sync Teams (`sync_team_enabled`) | Switch. When on, teams are synced by name; when off, sign-in never changes a member's teams | +| Role Field (`roles`) | The name of the claim / attribute that carries the **role names** returned by the identity provider, e.g. `roles`. Accepts a string or an array of strings; names are matched exactly | +| Team Field (`teams`) | The name of the claim / attribute that carries the **team names** returned by the identity provider, e.g. `teams`. Accepts a string or an array of strings; names are matched exactly | +| Default Roles (`default_role_ids`) | Multi-select of roles (the dropdown lists enabled roles only). Applied when none of the returned role names matches an eligible role | +| Default Teams (`default_team_ids`) | Multi-select of teams. Applied when none of the returned team names matches a team | + + +If the **Role Field / Team Field is left empty**, no name ever matches: when the corresponding sync switch is on, that dimension falls straight into the default roles / default teams branch at sign-in. With no eligible defaults configured, the result is empty (see [When Sync Takes Effect and Overwrite Semantics](#when-sync-takes-effect-and-overwrite-semantics)). + + +## Matching Rules + +Role/team name matching happens on the Flashduty server, with these rules: + +### Name normalization + +- The claim / attribute value can be a **single string or an array of strings**; non-string elements in an array are ignored. +- Each name is trimmed of leading/trailing whitespace; empty names and duplicates are removed. Deduplication is **case-sensitive** — `Ops` and `ops` are two different names. +- Matching is **exact and case-sensitive**: `Ops` does not match `ops`. + +### Role matching + +- The preset roles `Admin`, `Responder`, and `Viewer` are **always** eligible (no enabled-state requirement). +- Custom roles must be **enabled** to match; a disabled role with the same name is never hit. +- When one name hits several roles, the role with the **smallest role_id** wins (e.g. if the account has several roles named `Ops`, the smallest ID is used). +- Names that match no role are **skipped** (the server logs a warning); other names are still resolved. + +### Team matching + +- Only **non-deleted** teams are matched. +- Also exact and case-sensitive; duplicate team names resolve to the **smallest team_id**. +- Unmatched team names are skipped as well. + +### Default roles / default teams fallback + +- Defaults apply only when the dimension's resolution result is **empty** (no name matched at all); roles and teams fall back **independently** of each other. +- Default roles: the preset roles (`Admin` / `Responder` / `Viewer`) are always eligible; a custom default role must **exist and be enabled**, otherwise it is skipped with a warning logged. +- Default teams: must **exist and not be deleted**, otherwise they are skipped. +- The resolved role IDs / team IDs are deduplicated and sorted in ascending order. + +## Where Each Protocol Reads the Names + +| Protocol | Source of role/team names | +| --- | --- | +| SAML2.0 | Attributes of the SAML assertion; the attribute name is what you configure in the Role/Team Field, e.g. `roles` | +| OIDC | Claims of the ID Token; the claim name is what you configure in the Role/Team Field. When sync is enabled and the ID Token does not carry that claim, Flashduty additionally calls the **UserInfo** endpoint and merges its attributes with the ID Token claims before matching | +| CAS | Attributes of the CAS `/serviceValidate` response; the attribute name is what you configure in the Role/Team Field | +| LDAP | Does not use claim names: matches Group DN against the mapping rules (`role_team_mapping`), with default-role fallback. See [LDAP Role and Team Synchronization](/en/platform/configure-sso#ldap-role-and-team-synchronization) | + +## Protocol Switching and Field Retention + +When saving the SSO configuration, the console discards sync fields that do not belong to the current protocol (so switching protocols leaves no stale config behind): + +- **LDAP**: keeps the Group field, the Group DN mapping rules (`role_team_mapping`), and the default roles; `roles`, `teams`, and `default_team_ids` are not saved. +- **SAML2.0 / OIDC / CAS**: keeps `roles`, `teams`, `default_role_ids`, and `default_team_ids`; `group` and the mapping rules are not saved. + +## When Sync Takes Effect and Overwrite Semantics + +- Sync runs on **every SSO sign-in**: the server resolves role IDs and team IDs from the claim names first, then writes them to the member. +- The write is **overwrite mode**: the resolved result at sign-in becomes the member's final roles/teams; it is not merged with existing roles/teams. +- If sync is on but the resolution result is empty (no name matched and no eligible default role/team), the member's roles or teams in that dimension are **cleared**. +- When both sync switches are off, sign-in never changes a member's roles or teams. + + + + Overall configuration guide for every protocol + + + Configuring Flashduty SSO via Authing + + + Configuring Flashduty SSO via Keycloak + + + Configuring Flashduty SSO via OpenLDAP + + diff --git a/en/openapi/api-catalog.mdx b/en/openapi/api-catalog.mdx index d1a8e44c..e56186e6 100644 --- a/en/openapi/api-catalog.mdx +++ b/en/openapi/api-catalog.mdx @@ -3,7 +3,7 @@ title: "API Catalog" description: "Complete list of Flashduty Open API endpoints, organized by product module with links to detailed documentation" --- -Flashduty Open API provides **353** endpoints covering five major modules: On-call, Monitors, RUM, AI SRE, and Platform. All endpoints use unified authentication and request specifications. See [Quick Start](/en/openapi/introduction) for details. +Flashduty Open API provides **354** endpoints covering five major modules: On-call, Monitors, RUM, AI SRE, and Platform. All endpoints use unified authentication and request specifications. See [Quick Start](/en/openapi/introduction) for details. All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated via APP Key through query string. @@ -271,7 +271,7 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated vi - + ### Alert rules @@ -304,6 +304,7 @@ All endpoint URLs use `https://api.flashcat.cloud` as the base, authenticated vi | POST | [`/monit/datasource/create`](/en/api-reference/monitors/data-sources/monit-datasource-write-create) | Create datasource | | POST | [`/monit/datasource/update`](/en/api-reference/monitors/data-sources/monit-datasource-write-update) | Update datasource | | POST | [`/monit/datasource/delete`](/en/api-reference/monitors/data-sources/monit-datasource-write-delete) | Delete datasource | +| POST | [`/monit/datasource/tools/invoke`](/en/api-reference/monitors/data-sources/monit-datasource-tools-invoke) | Invoke datasource tool | | POST | [`/monit/datasource/sls/projects`](/en/api-reference/monitors/data-sources/monit-datasource-read-sls-projects) | List SLS projects | | POST | [`/monit/datasource/sls/logstores`](/en/api-reference/monitors/data-sources/monit-datasource-read-sls-logstores) | List SLS logstores | diff --git a/en/platform/configure-sso.mdx b/en/platform/configure-sso.mdx index ad57cfcf..e4779587 100644 --- a/en/platform/configure-sso.mdx +++ b/en/platform/configure-sso.mdx @@ -84,6 +84,10 @@ Scopes is a required field. The default values `openid`, `profile`, `email`, `ph | SSO-only login (`force_sso`) | Enabled by default. When on, every member of this account can sign in only via SSO; password and verification-code sign-in are rejected. See [SSO-only login](#sso-only-login) below | | Flashduty Service Provider Info | **Redirect URL**: Identity provider callback address | + +**Role and team sync**: For SAML2.0 / OIDC / CAS, the **Sync Configuration** section of the settings page syncs roles/teams by the **role/team names** returned by the identity provider (claim / attribute names) — names are matched exactly (case-sensitive), and when no name matches, the configured **default roles / default teams** apply. LDAP instead uses Group DN mapping rules; the two mechanisms differ. See [Role and Team Sync](/en/on-call/integration/sso/role-team-sync) for the matching rules, per-protocol name sources, and when sync takes effect. + + ## Configuring LDAP Protocol --- @@ -246,7 +250,10 @@ Before modifying, ensure you have checked your email integration configuration a --- - + + + SAML2.0/OIDC/CAS sync roles and teams by name, with default config fallback + Configure Flashduty SSO single sign-on through Authing diff --git a/en/rum/quickstart/app-management.mdx b/en/rum/quickstart/app-management.mdx index 8b553a12..ee084936 100644 --- a/en/rum/quickstart/app-management.mdx +++ b/en/rum/quickstart/app-management.mdx @@ -338,7 +338,7 @@ For reference, the protocol semantics: besides the default values, a configurati - Change history keeps the most recent 50 versions; older versions are cleaned up automatically and cannot be rolled back to. Each entry shows who made the change and the change note (if one was left). You can revert any retained version to make it the current configuration; a revert also produces a new version. - A new version produced by a revert carries a content-equivalence label: if its configuration content is identical to an earlier version in the history, the history list marks it as equivalent to the earliest version with that content — a version-number jump does not mean the configuration content changed. -- The rollout panel reports the version distribution and adoption progress across recently arrived sampled sessions, distinguishing *waiting for new sessions*, *rolling out*, and *fully switched*, as well as sessions that *never received a configuration* or *did not report a version* (SDK too old or config never fetched), so you can confirm the release actually landed. When fewer than 20 sampled sessions fall in the window, the panel shows the actual session counts only and does not estimate shares (shares are extrapolated from the sample rate, which is meaningless with too few samples). +- The rollout panel shows **adoption** and rollout progress across recently arrived sampled sessions, with status labels *waiting for new sessions* (just published, no session has started under the current version yet), *in effect* (some sessions have switched), *recent sessions switched* (every session that arrived in the window is on the current version), *no configuration received* (none of the recent sessions reported a configuration version — usually the SDK has remote configuration disabled or is too old), *no data* (no new sessions in the window), and *no adoption detected* (published for over about 8 hours and still not on the current version); slices that did not report a configuration version are labeled *not reported* (SDK too old or config never fetched). Clicking **View details** opens the event explorer on this batch of sampled sessions. When fewer than 20 sampled sessions fall in the window, the panel shows the actual session counts only and does not estimate shares (shares are extrapolated from the sample rate, which is meaningless with too few samples). ## Delete Application diff --git a/zh/ai-sre/sessions.mdx b/zh/ai-sre/sessions.mdx index b92d19b3..6e5375c3 100644 --- a/zh/ai-sre/sessions.mdx +++ b/zh/ai-sre/sessions.mdx @@ -226,10 +226,11 @@ Agent 委派子任务时，对话中会出现一行可点击的**派发引用** | shell | `bash` 工具加 `run_in_background` 发起 | 一次性长命令（构建、批处理、数据拉取等），只需在结束时回报结果 | | monitor | `monitor` 工具发起 | 监视器常驻任务：watch 一个条件直到命中或到达截止时间，脚本输出会作为事件分批回流给 Agent；一次性的延迟工作（如「半小时后检查一次」）用 monitor 加 `sleep` 实现 | -会话右侧提供统一的 **任务** 面板，集中跟踪本会话的所有任务，按 **需要你 / 运行中 / 已结束** 三组展示。打开入口有两个： +会话右侧提供统一的 **任务** 面板，集中跟踪本会话的所有任务，按 **需要你 / 运行中 / 已结束** 三组展示。打开入口有三个： - **聊天页头部的任务按钮**：带数量角标，数字为「需要你 + 运行中」的任务数，超过 9 显示 `9+`；有任务需要您处理（等待授权 / 等待输入）时角标为红色，仅为运行中时角标为蓝色。 - **回合进行中的生成状态行**：显示「N 个任务 · X 需要你」，点击同样打开任务面板。 +- **发起 monitor / 后台 bash 的工具行**：对话流中发起 `monitor` 或后台命令（`bash` 加 `run_in_background`）的工具行——单独成组时即该工具组的头部——本身就是该任务在对话中的句柄：行尾以外链图标标示可点击，悬停提示 **打开任务详情**，点击直接打开该任务的任务详情面板。这类行不再展开原始输入 / 输出（后台 bash 行展开后原本只有命令本身，没有状态与输出）。只读分享会话中打开的任务详情同样为只读。 任务详情按类型区分：点击 **agent** 任务打开子会话的执行转录（见上文）；点击 **shell / monitor** 任务打开它的事件时间线详情，包含状态（运行中的任务还会显示最近一次探活距今的秒数，探活约每 30 秒一次）、运行时长、事件数、输出字节数、monitor 的截止时间（无截止的常驻任务显示「常驻」）、退出码、完整命令，以及按序排列的事件时间线。**停止按钮位于详情头部**——shell / monitor 任务为 **停止任务**，子代理为 **停止子代理**，只中断该任务，不影响主会话。 @@ -238,7 +239,7 @@ Agent 委派子任务时，对话中会出现一行可点击的**派发引用** - 发起后台命令的工具行显示 **Started background command**；同一回合前后台命令混合时，折叠的工具组按类别分别计数（如 `Ran 1 command, started 1 background command`）。 - monitor 每次命中条件，对话流中内联出现一条 🔭 系统行：首行显示监视器描述与该批输出的首行摘要，点击就地展开整批输出。 - 任务结束时对话流出现一条终止行，包含结束状态与结果摘要，以及退出码和备注（任务信封携带时）。 -- monitor 工具行本身不展开输入 / 输出——它返回的登记信息（任务 ID、输出文件、截止时间等）在任务面板详情中有更完整的呈现。 +- monitor 工具行本身不展开输入 / 输出——点击该行会打开对应任务的任务详情面板，它返回的登记信息（任务 ID、输出文件、截止时间等）在详情中有更完整的呈现。 与后台任务相关的两个状态指示： diff --git a/zh/changelog/changelog.mdx b/zh/changelog/changelog.mdx index 13d2572f..6bf9a1c8 100644 --- a/zh/changelog/changelog.mdx +++ b/zh/changelog/changelog.mdx @@ -4,6 +4,37 @@ description: "本页面记录 Flashduty 产品的重要更新和功能发布" keywords: ["更新日志", "产品发布", "功能更新", "Flashduty", "版本记录"] --- + + +### SSO 同步配置：角色与团队同步 + +SAML2.0 / OIDC / CAS 协议的 SSO 设置页新增**同步配置**区块，登录时可按身份提供商（IdP）返回的字段自动同步成员的角色与团队： + +- **同步角色 / 同步团队开关**：分别控制是否启用角色、团队同步，登录时按匹配结果覆盖成员当前的角色与团队 +- **角色字段 / 团队字段**：填写 IdP 返回角色、团队名称的声明字段名（如 `roles` / `teams`），取值支持字符串或字符串数组，按名称**精确匹配**（区分大小写） +- **默认角色 / 默认团队**：当返回的名称未匹配到任何角色或团队时，登录时回落分配配置的默认角色/团队；未匹配且未配置默认值时清空 +- **协议差异**：LDAP 协议保持不变，仍使用 Group DN 到角色/团队的映射规则；本同步配置仅适用于 SAML2.0 / OIDC / CAS + +详见 [角色与团队同步](/zh/on-call/integration/sso/role-team-sync)。 + + + + + +### Monit 数据源诊断与新增数据源类型 + +监控（Monit）数据源新增**数据源诊断**能力，可对已配置的数据源执行只读的命名工具巡检： + +- **数据源诊断工具**：按数据源 ID 一次调用一个确定性工具（如 `mysql.lock_contention`、`postgres.activity`、`redis_node.slowlog`、`kafka.consumer_lag`、`elasticsearch.cat`、`prometheus.metric_trends`、`loki.log_patterns`、`victorialogs.log_patterns`）；无工具目录，需 `enabled=true`（`alerting_enabled=false` 不影响诊断） +- **版本要求**：所选 Edge 集群内所有可路由的在线 Edge 会话需支持 **v0.71.0** 基线协议，否则返回 `edge_upgrade_required` / `mixed_edge_versions` / `no_active_edge` / `tool_not_supported` 等错误 +- **旧工具下线**：`mysql.query` / `postgres.query` 已移除，自由 SQL 请使用数据查询接口 +- **新增 5 种诊断型数据源类型**：Redis（Node / Sentinel）、MongoDB（Mongod / Mongos）、Kafka——仅用于诊断，不参与告警规则评估；地址格式为单个 `host:port`（IPv6 用方括号）或 1–32 个去重逗号分隔的 Kafka 引导地址 +- **开关语义拆分**：`alerting_enabled`（是否可评估告警，诊断型类型固定为 false，存在引用它的启用规则时关闭会被拒绝）与 `enabled`（业务执行，创建时默认开启）相互独立 + +详见 [数据源](/zh/monitors/data-sources/data-sources) 与 [监控目标](/zh/monitors/targets/overview)。 + + + ### AI SRE：后台任务与任务面板 diff --git a/zh/developer/cli.mdx b/zh/developer/cli.mdx index 135b496d..0d28246c 100644 --- a/zh/developer/cli.mdx +++ b/zh/developer/cli.mdx @@ -264,8 +264,23 @@ flashduty status-page list # 列出 flashduty status-page change-active-list # 列出活跃的变更事件 flashduty status-page change-create [flags] # 创建状态页事件 flashduty status-page change-timeline-create [flags] # 追加时间线更新 +flashduty status-page draft-create [flags] # 创建状态页事件草稿（人工审阅后从控制台发布） ``` +#### 事件草稿（draft-create） + +`draft-create` 保存一份状态页事件草稿（故障事件或维护窗口），供人工在控制台审阅后发布——草稿本身不会对外发布： + +```bash +flashduty status-page draft-create \ + --source 'ai_sre:sess_xxx' \ + --data '{"draft":{"page_id":5750613685214,"type":"incident","name":"Web Console Degraded Performance","message":"We are investigating degraded performance affecting the web console.","status":"investigating","affected_components":[{"component_id":"01KC3GAZ6ZJE40H55GM31RPWZE","status":"degraded"}]}}' +``` + +- `--source`：起草来源的不透明标记（如 `ai_sre:sess_xxx`），最多 64 字符。 +- `--data` 中的 `draft` 对象（必填，序列化后最多 64 KB，原样存储）。必填字段：`page_id`、`type`（`incident` 或 `maintenance`）、`name`、`message`；可选 `change_id`（大于 0 时表示向已有事件追加更新）、`status`、`affected_components`、`start_time`/`end_time`（Unix 秒，仅新建维护窗口使用）。 +- 响应返回 `draft_id`（形如 `draft_[A-Za-z0-9]{22}`）与 `created_at`，控制台审阅链接携带 `draft_id`。 + #### 从 Atlassian Statuspage 迁移 迁移任务为异步执行，需通过 `migration-status` 轮询进度： @@ -290,7 +305,7 @@ flashduty status-page migrate-email-subscribers \ flashduty status-page migration-cancel ``` -其他可用子命令：`change-delete`、`change-info`、`change-list`、`change-timeline-delete`、`change-timeline-update`、`change-update`、`component-upsert`、`component-delete`、`section-upsert`、`section-delete`、`info`、`subscriber-list`、`subscriber-import`、`subscriber-export`、`template-list`、`template-upsert`、`template-delete`。 +其他可用子命令：`draft-create`、`change-delete`、`change-info`、`change-list`、`change-timeline-delete`、`change-timeline-update`、`change-update`、`component-upsert`、`component-delete`、`section-upsert`、`section-delete`、`info`、`subscriber-list`、`subscriber-import`、`subscriber-export`、`template-list`、`template-upsert`、`template-delete`。 ### rum — RUM 应用与会话回放 @@ -429,7 +444,7 @@ flashduty session export # 以 NDJSON 流式导出单个会话 | `--since` | 仅保留在该时间窗口内有更新的会话（客户端过滤），如 `30d`、`24h`、`2026-05-01` | - | | `--limit` | 最多拉取的会话数 | `200` | | `--page` | 起始页码（1 开始） | `1` | -| `--output-format` | 输出格式：`jsonl`（默认，每行一个会话对象，可直接管道给 `jq`）、`json`（完整信封）、`toon`（紧凑编码） | `jsonl` | +| `--output-format` | 输出格式：`jsonl`（默认，每行一个会话对象，可直接管道给 `jq`）、`json`（完整信封；受 16 KiB 输出上限约束，见「输出格式」）、`toon`（紧凑编码） | `jsonl` | 服务端 `/safari/session/list` 单页上限为 100 条，超出 `--limit` 时 CLI 会自动向服务端翻页拉取，无需手动分页。API 本身没有时间窗口过滤，`--since` 是在拉取后于客户端按会话的 `updated_at` 进行过滤的。 @@ -446,38 +461,39 @@ flashduty session export --include-subagents > session.ndjson |------|------| | `--include-subagents` | 在每条 `subagent_dispatch` 之后递归内联该子智能体自身的完整事件流 | -### monit-agent — 主机/数据库在线诊断 +### monit-agent — 主机在线诊断 -通过 flashmonit 代理对目标主机或数据源执行在线诊断，无需登录目标机器。 +通过 flashmonit 代理对**主机**执行在线诊断，无需登录目标机器。数据库/中间件诊断请改用 `monit datasource-tools-invoke`（见下文），数据库服务端点不是 Agent 目标。 ```bash -flashduty monit-agent catalog --target-locator # 列出该目标可用的诊断工具 +flashduty monit-agent catalog --target-locator # 列出该主机可用的诊断工具 flashduty monit-agent invoke --target-locator --data '' # 并发执行最多 8 个诊断工具 ``` -`catalog` 和 `invoke` 均需要 `--target-locator`（内网 IP、主机名或数据源名称）。`--target-kind` 可选（`host`、`mysql`、`redis` 等），不填时由代理自动推断。 +- `--target-locator`（必填）：**已注册主机的内网 IP 或主机名**。 +- `--target-kind`：仅接受 `host`，省略时按主机路由；传入其它取值（如 `mysql`、`redis`）会被拒绝：`monit-agent supports host targets only; use monit datasource-tools-invoke for datasource diagnostics`。 -`invoke` 通过 `--data` 指定要运行的工具列表，最多 8 个并发： +`invoke` 通过 `--data` 指定要运行的工具列表（`params` 可省略，默认 `{}`），最多 8 个并发；`--target-locator` / `--target-kind` 会覆盖 `--data` 中的同名字段： ```bash flashduty monit-agent invoke --target-locator '10.0.0.1' \ --data '{"tools":[{"tool":"os.overview"},{"tool":"os.top_processes","params":{"top_n":10}}]}' ``` -对于包含引号或逗号的 SQL 参数，推荐用 heredoc 通过 stdin 传入（`--data -`）： +对于包含引号或逗号的参数 JSON，推荐用 heredoc 通过 stdin 传入（`--data -`）： ```bash -flashduty monit-agent invoke --target-locator 'db-host' --data - <<'FDUTY' -{"tools":[{"tool":"mysql.query","params":{"sql":"SELECT a, b FROM t WHERE s='RUNNING'","max_rows":50}}]} +flashduty monit-agent invoke --target-locator 'web-01' --data - <<'FDUTY' +{"tools":[{"tool":"os.overview"}]} FDUTY ``` ### monit-query — 监控数据源查询 -直接探测监控后端数据源，无需经过告警规则层。`data` 子命令支持 9 种数据源类型（Prometheus、VictoriaLogs、Loki、MySQL、SLS、Elasticsearch、PostgreSQL、Oracle、ClickHouse）；`diagnose` 支持 `prometheus`（指标趋势）、`victorialogs` 和 `loki`（日志模式）。 +直接探测监控后端数据源，无需经过告警规则层。`data` 子命令支持 9 种数据源类型（Prometheus、VictoriaLogs、Loki、MySQL、SLS、Elasticsearch、PostgreSQL、Oracle、ClickHouse）；`diagnose` 为**遗留接口**（log_patterns / metric_trends 证据已迁移到 `monit datasource-tools-invoke`），支持 `prometheus`（指标趋势）、`victorialogs` 和 `loki`（日志模式）。 ```bash -flashduty monit-query diagnose [flags] # 预聚合 RCA 分析（日志模式或指标趋势） +flashduty monit-query diagnose [flags] # 遗留接口：预聚合 RCA 分析（日志模式或指标趋势；新场景请用 monit datasource-tools-invoke） flashduty monit-query data [flags] # 结构化数据源查询 ``` @@ -492,6 +508,8 @@ flashduty monit-query data [flags] # 结构化数据源查询 | `--time-end` | 窗口截止时间（默认 `now`），格式与 `--time-start` 相同；时间窗口最长 6 小时 | | `--operation` | `log_patterns`（`loki` / `victorialogs`）或 `metric_trends`（`prometheus`）；省略时根据 `--ds-type` 自动推断 | +`diagnose` 是遗留接口（等价于 SDK 中已弃用的 `QueryDiagnose`）：新场景请改用 `monit datasource-tools-invoke` 的 `prometheus.metric_trends`、`loki.log_patterns`、`victorialogs.log_patterns` 工具，见下文。 + `data` 常用参数： | 参数 | 说明 | @@ -506,7 +524,34 @@ flashduty monit-query data [flags] # 结构化数据源查询 `rows` 常用参数：`--ds-type`、`--ds-name`（均必填）、`--expr`（查询表达式，必填）、`--args KEY=VALUE`（可重复）。**`rows` 已弃用**，请改用 `monit-query data`。`rows` 原始模式（`loki` / `victorialogs`）可通过 `--args .start=` 与 `--args .end=` 指定时间窗口，取值格式与 `diagnose` 的 `--time-start`/`--time-end` 相同（相对时长、`now`、日期/RFC3339、Unix 秒或毫秒），CLI 会统一归一化为数据源要求的 Unix 秒。 -### monit — 监控规则表达式预览 +### monit datasource-tools-invoke — 数据源诊断工具 + +`monit datasource-tools-invoke` 对已配置的数据源执行**一次确定性的只读工具调用**，是结构化数据源诊断的现行路径（取代 `monit-query diagnose` 与 Agent 的诊断角色）。数据源 ID 从 `monit datasource-list` 的 `id` 字段获取： + +```bash +flashduty monit datasource-list --type redis_node --json | jq '.[] | {id, name, type_ident, address}' +flashduty monit datasource-tools-invoke --tool 'redis_node.slowlog' \ + --data '{"params":{}}' +``` + +| 参数 | 说明 | +|------|------| +| `--datasource-id` | 数据源 ID（必填，来自 `monit datasource-list`，最小 1） | +| `--tool` | 工具名（必填），以数据源类型为前缀，如 `mysql.overview`、`postgres.activity`、`redis_node.slowlog`、`kafka.consumer_lag`、`elasticsearch.cat`、`prometheus.metric_trends`、`loki.log_patterns`、`victorialogs.log_patterns`；1–128 字符 | +| `--data` | 工具参数 JSON（`{"params":{...}}`，可省略，省略即 `{}`；显式 `null` 不合法） | +| `--account-id` | 可选一致性校验，必须等于当前认证账户 | + +语义与限制： + +- **无工具目录、无自动重试、无回退**：一次调用只执行一个命名工具，参数需按各数据源工具约定填写，不要从命令行列表猜测。`mysql.query` / `postgres.query` 工具已移除——自由 SQL 请用 `monit-query data`。 +- 要求所选集群内**全部**当前在线可路由的 Edge 会话支持 v0.71.0 基础调用协议（个别工具可能要求更新的实现）；普通数据源查询不受此版本限制。 +- 请求体 ≤128 KiB；完整成功响应 ≤1 MiB；工具超时 ≤25 秒。 +- 需要数据源 `enabled=true`；`alerting_enabled=false` 不阻塞诊断。 +- 返回值：`data`（工具特定的 JSON 证据，原样保留、永不为 null，不含旧 diagnose 信封）、`tool`、`datasource_id`、可选 `summary`，以及 `truncated` 对象（含 `reason`，存在即表示结果被截断）。 + +错误按原样返回，常见错误码：`edge_upgrade_required`（Edge 版本过低）、`mixed_edge_versions`（集群内 Edge 版本混合）、`no_active_edge`（无可用在线 Edge）、`tool_not_supported`（工具不支持）、`invalid_request`（修正参数）、`source_too_large` / `result_too_large`（收窄请求范围）。出现 Edge 版本问题时不要轮换 Edge 或回退到 Agent/旧 diagnose。 + +### monit — 监控数据源与规则表达式预览 如果你想在保存规则前直接验证某条数据源表达式，可以使用 `preview-sync` 走一条同步预览请求，拿到原始结果。 @@ -524,6 +569,41 @@ flashduty monit preview-sync [flags] | `--delay-seconds` | 将查询窗口整体向前平移若干秒，用于补偿采集延迟 | | `--data` | 可补充 `args` 等数据源特定参数 | +#### 数据源管理（datasource-*） + +`monit datasource-*` 命令族管理监控数据源（由 OpenAPI 生成命令提供）： + +```bash +flashduty monit datasource-list [--type ] # 列出数据源（--type 按类型过滤，省略返回全部） +flashduty monit datasource-info --id # 查看单个数据源 +flashduty monit datasource-create [flags] # 创建数据源（payload 经 --data 传入） +flashduty monit datasource-update [flags] # 更新数据源（--id 必填） +flashduty monit datasource-delete --id # 删除数据源（引用它的告警规则不被阻断，规则自动移出监控范围并关闭相关告警） +``` + +`datasource-create` / `datasource-update` 核心字段： + +| 参数 | 说明 | +|------|------| +| `--name` | 数据源显示名（必填）；查询/诊断 API 中的 `ds_name` 引用该名称 | +| `--type-ident` | 数据源类型（必填）：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`，以及 5 个**仅诊断**类型：`redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka` | +| `--address` | 连接地址。除 `elasticsearch` 且 `deployment: cloud` 外必填。Prometheus/Loki/VictoriaLogs 为 HTTP URL；MySQL/Oracle/Postgres/ClickHouse 为 `host:port`；SLS 为不含 `http(s)://` 前缀的 endpoint。**Redis/MongoDB 诊断类型**：单个 `host:port`，IPv6 需加方括号，不接受 URI/userinfo/query；**Kafka**：1–32 个逗号分隔的唯一 `host:port` bootstrap 地址（payload 中不含 broker 列表）。规范化后最多 4096 字符 | +| `--edge-cluster-name` | 负责用该数据源评估规则的 Edge 集群名（必填） | +| `--note` | 可选备注 | +| `--enabled` | **业务执行**开关。创建时省略默认 `true`；更新时省略保留当前值；显式 `false` 停用（停用后业务查询与工具被拒绝）；`null` 不合法。**不影响 `alerting_enabled`** | +| `--alerting-enabled` | 是否允许该数据源评估告警。创建时省略：告警类类型默认 `true`，仅诊断类型默认 `false`；更新时省略保留当前值；`null` 不合法。5 个诊断类型拒绝 `true`；已有启用规则引用该数据源时关闭会以冲突错误拒绝 | +| `--data` | `payload` 配置块（必填），必须包含与 `type_ident` 同名的键，如 `{"payload":{"redis_node":{"database":0,"password":"..."}}}` | + +`enabled` 与 `alerting_enabled` 相互独立：告警评估同时要求 `enabled=true` 与类型支持告警；`alerting_enabled=false` 不阻塞非告警查询与诊断工具，`monit datasource-list` 返回的 `alerting_enabled` 对仅诊断类型恒为 `false`。 + +**诊断类型 payload 与密钥处理**： + +- `redis_node`：`database`（Redis 库号，默认 0）、`username` / `password`、`timeout_ms`（默认 3000，范围 1000–10000）。 +- `redis_sentinel`：`username` / `password`、`timeout_ms`（默认 3000）。 +- `mongodb_mongod` / `mongodb_mongos`：`auth_source`（认证库，默认 `admin`；用户名与密码须成对配置）、`username` / `password`、`timeout_ms`（默认 3000）、TLS 字段；不支持客户端证书。 +- `kafka`：`sasl_mechanism`（`none` 默认 / `plain` / `scram-sha-256` / `scram-sha-512`，后三者需用户名与密码）、`username` / `password`、`timeout_ms`（默认 5000）、TLS 字段（`tls_min_version` 默认 1.2，最高 1.3）。 +- 密码与 `kafka.tls_key` 支持 `${env:NAME}` 引用（在 Edge 上解析）；字面值不会出现在响应中，仅 `${env:...}` 引用会回显。**更新时省略这些字段以保留已存密钥，显式传空字符串表示清除**。 + ### monit servicemap — 服务拓扑（Beta） `monit servicemap-*` 命令族访问服务拓扑（ServiceMap）能力，页面操作见[服务拓扑](/zh/monitors/targets/servicemap)。 @@ -587,11 +667,36 @@ flashduty automation fire # 经 HTTP POST 触发器触 **时区语义**：`--at` 与 `--cron-expr` 均按**规则时区**的本地挂钟时间理解——规则时区在创建时默认为调用者的成员时区，成员未设置时回退到账户时区。请直接传用户的本地时间，**不要**预先换算成 UTC。CLI 的 `create` / `update` 都没有 `--timezone` 参数：创建时如需固定其它时区，请改用生成命令 `flashduty safari automation-rule-create --timezone`；已创建规则的时区在 `update` 中不可更改。 +### insight — 洞察查询 + +`insight` 命令族按时间窗口查询聚合的故障指标（响应时间、通知数等）： + +```bash +flashduty insight incidents [flags] # 列出带性能指标的故障（MTTA、MTTR、通知数） +flashduty insight top-alerts [flags] # 按标签维度统计最吵的告警来源 +flashduty insight incident-export [flags] # 导出筛选后的故障列表为 CSV（重定向到文件） +``` + +`insight incidents` 常用参数： + +| 参数 | 说明 | 默认值 | +|------|------|--------| +| `--since` / `--until` | 时间窗口（与 `incident list` 相同的人性化格式） | `7d` / `now` | +| `--limit` | 最大结果数（上限 100） | `20` | +| `--page` | 页码 | `1` | +| `--fields` | `json`/`toon` 输出时的字段投影（逗号分隔，如 `incident_id,title,severity`）；表格模式忽略；至少指定一个字段 | 默认紧凑投影 | + +`json`/`toon` 模式默认按紧凑字段投影：`incident_id`、`title`、`severity`、`channel_name`、`seconds_to_ack`、`seconds_to_close`、`notifications`（默认投影时 stderr 会提示可用 `--fields` 更换），输出受 16 KiB 上限约束，超出时行会被丢弃或单行截短，提示只写 stderr（详见下文「输出格式」的「结构化输出的字段投影」）。 + +`insight top-alerts`：`--label` 必填（`check` 或 `resource`），`--since`/`--until` 同前，`--limit` 默认 `10`（Top-K），返回每个标签值的告警数与事件数。 + +`insight incident-export`：按当前筛选条件输出一行 CSV（重定向到文件；`--start-time`/`--end-time` 为 Unix 秒）。导出端点单次返回且服务端会静默截断行数，因此命令写完后会核对 CSV 数据行数与同筛选条件 `incident-list` 的总数：不足时 CSV 仍会写出（stderr 打印 `rows=N`），并以非零退出码提示实际写出 vs 总数——请收窄时间窗口后重试。 + ### 全量命令覆盖 -除上述精选命令外，CLI 现已通过 spec 驱动的代码生成实现对 Flashduty OpenAPI 的**全量覆盖**。当前 OpenAPI 含 **337 个 API 操作**，CLI 为其中 336 个操作生成对应命令（`session-read-export` 以手工实现的 `session export` / `safari session-export` 命令提供），并按资源组织为顶层命令组。除 On-call 域（incident、incident-trigger-subscription、change、channel、field、status-page、template 等）外，还覆盖了： +除上述精选命令外，CLI 现已通过 spec 驱动的代码生成实现对 Flashduty OpenAPI 的**全量覆盖**。当前 OpenAPI 含 **348 个 API 操作**，CLI 为其中 **345 个** 生成对应命令，其余操作（如 `session-read-export`）以手工实现命令提供（`session export` / `safari session-export`），并按资源组织为顶层命令组。除 On-call 域（incident、incident-trigger-subscription、change、channel、field、status-page、template 等）外，还覆盖了： -- **AI SRE（`safari`）**：a2a-agents、automations、knowledge、mcp-servers、sessions、skills 等 +- **AI SRE（`safari`）**：a2a-agents、artifacts、automations、knowledge、mcp-servers、sessions、skills 等 - **告警与降噪**：alert、alert-event、enrichment（alert-rules、rule-sets）、route - **On-call 与日程**：calendar、schedule - **平台管理**：account、member、person、team、role（roles-permissions）、audit（audit-logs） @@ -636,6 +741,31 @@ flashduty safari knowledge-file-delete --rel-path [--force] # 删除知 `knowledge-file-put` 的 `--content-b64` 必须是合法 UTF-8 文本的 Base64 编码，`--content-type` 省略时按文件扩展名推断。`knowledge-file-delete` 默认在文件仍被其他知识文件引用时阻止删除；加 `--force` 可强制执行，此时引用方会以警告形式返回。 +#### artifacts — AI SRE 产物库 + +`safari artifact-*` 命令族管理 AI SRE 会话产出的**产物**（Artifact）——发布到产物库、共享与签名下载，产品功能见[产物](/zh/ai-sre/artifacts)： + +```bash +flashduty safari artifact-gallery-list [flags] # 列出产物（--scope all|personal|team、--query 标题搜索、--orderby created_at|updated_at、--limit 默认 20 上限 100、--page、--team-ids、--asc） +flashduty safari artifact-gallery-get # 查看产物详情（含公开分享状态） +flashduty safari artifact-gallery-publish-from-file --title # 将会话内产出的文件（pf_ 前缀）发布为产物 +flashduty safari artifact-gallery-file-state [...] # 检查哪些文件已存在活跃产物（单次最多 50 个） +flashduty safari artifact-gallery-update [flags] # 重命名（--title）或转移范围（--team-id：0 转个人，正数转团队） +flashduty safari artifact-gallery-delete # 从产物库移除（源文件仍留在会话中） +flashduty safari artifact-sign [--share-token ] # 为文件生成短时签名 URL（下载/预览，5 分钟有效） +flashduty safari artifact-stream --t [--mode download|preview] # 用签名 token 下载或预览文件字节（--mode 其它取值回退到 download） +flashduty safari artifact-gallery-share-enable # 开启匿名公开分享，返回 public_url +flashduty safari artifact-gallery-share-revoke # 关闭公开分享（链接立即不可访问） +flashduty safari artifact-gallery-share-sync # 用最新内容刷新公开快照 +``` + +公开分享与签名语义： + +- `public_url` 是控制台 `/share/artifact/` 页面，**完全由 CDN 提供**；仅在分享期间存在，任何拿到链接的人无需登录即可查看。 +- 公开快照按产物当前的 `file_id` 物化：当 `share_enabled=true` 且响应中 `share_file_id` 与 `file_id` 不一致时，公开快照已过期——调用 `artifact-gallery-share-sync` 刷新后再对外引用。 +- `artifact-sign` 的签名 token 绑定调用账户与成员，有效期 5 分钟（响应 `expires_in`）；`download_url` / `preview_url` 是相对路径（`/safari/artifact/stream?...`），使用时需拼接 API base（`https://api.flashcat.cloud`）。 +- 产物初始作用域继承来源会话（个人会话的产物归创建者个人，绑定团队的会话的产物归团队）；`can_edit` 决定调用者能否重命名/转移/删除/分享（创建者、所属团队成员或源会话管理者）。 + ### 工具命令 ```bash @@ -676,7 +806,7 @@ Showing 2 results (page 1, total 2). -机器可解析。除下方列出的默认紧凑字段命令外，返回命令的完整响应数据；表格列截断不适用于 JSON。适合脚本、CI/CD 流水线消费。 +机器可解析。除下方列出的默认紧凑字段命令外，返回命令的完整响应数据；表格列截断不适用于 JSON。适合脚本、CI/CD 流水线消费。注意生成命令的**列表形态**响应在 `json` 模式下同样受 16 KiB 上限约束（见下方「生成命令的输出上限」）。 ```bash flashduty incident list --json | jq '.[].title' @@ -684,7 +814,7 @@ flashduty incident list --json | jq '.[].title' -TOON（Token-Oriented Object Notation）对同构数组省去了 JSON 中每行重复的字段名，列表输出可显著减少 token 消耗，更适合喂给 AI / 智能体消费。下方列出的默认紧凑字段命令会按其字段投影输出，并受大小限制。 +TOON（Token-Oriented Object Notation）对同构数组省去了 JSON 中每行重复的字段名，列表输出可显著减少 token 消耗，更适合喂给 AI / 智能体消费。下方列出的默认紧凑字段命令会按其字段投影输出，并受大小限制；生成命令的列表形态输出同样受 16 KiB 上限约束（见下方「生成命令的输出上限」）。 ```bash flashduty incident list --output-format toon @@ -700,6 +830,16 @@ TOON 不能直接用 `jq` 解析；需要管道给 `jq` 时请改用 `--json`。 +#### 生成命令的输出上限 + +由 OpenAPI 代码生成提供覆盖的生成命令（如 `safari session-list`、`monit datasource-list`、`safari a2a-agent-list` 等），其 `json` / `toon` 输出对**列表形态**的响应同样按 16 KiB 上限处理（与精选命令的两级行为一致，提示只写 stderr、不改写 stdout）： + +1. **整页超限**：只输出能完整放下的前几行，每个值保持原样，stderr 提示实际输出了 N/M 行、其余行未输出。 +2. **单行本身超限**：该行的字符串值以 `...` 截短，stderr 点名被截字段；标识符字段（以 `_id` / `_key` 结尾）不会被截短。 +3. **行无法缩减到上限以内**：命令报错并点名字节数最大的字段（最多 3 个），请调低 `--limit` 或减少输出字段后重试。 + +**明细形态的单个对象**（如 `safari session-get` 的详情）不做截断、原样输出——截短后的值无法与真实短值区分，因此这类响应不受上限约束。生成命令大多没有 `--fields`，需要完整 JSON 时请通过 `--limit` 调小每页数量、配合 `--page` 分页逐页拉取（如 `flashduty safari session-list --limit 20 --page 2`），或按需收窄筛选条件。 + ### 结构化输出的字段投影 以下命令在 `json` 或 `toon` 输出时支持 `--fields`。用逗号分隔顶层响应字段；未知字段会直接报错，表格输出会忽略此参数。 @@ -711,6 +851,7 @@ TOON 不能直接用 `jq` 解析；需要管道给 `jq` 时请改用 `--json`。 | `flashduty incident detail ` | 不指定 `--fields` 时返回完整详情；指定后只返回所选字段 | 仅投影输出为 8 KiB | | `flashduty alert-event list` | `event_id`、`alert_id`、`event_severity`、`event_status`、`event_time`、`title` | 16 KiB | | `flashduty channel escalate-rule-list ` | `rule_id`、`rule_name`、`status`、`priority`、`filters` | 16 KiB | +| `flashduty insight incidents` | `incident_id`、`title`、`severity`、`channel_name`、`seconds_to_ack`、`seconds_to_close`、`notifications` | 16 KiB | 例如，只导出故障编号、标题和处理进度： @@ -718,7 +859,7 @@ TOON 不能直接用 `jq` 解析；需要管道给 `jq` 时请改用 `--json`。 flashduty incident list --json --fields incident_id,title,progress ``` -列表投影（`incident list`、`incident similar`、`alert-event list`、`channel escalate-rule-list`）超过 16 KiB 上限时，CLI 按三级行为处理，所有提示只写 stderr、不改写 stdout： +列表投影（`incident list`、`incident similar`、`alert-event list`、`channel escalate-rule-list`、`insight incidents`）超过 16 KiB 上限时，CLI 按三级行为处理，所有提示只写 stderr、不改写 stdout： 1. **整页超限**：只输出能完整放下的前 N 行，每个值保持原样、不再截短，stderr 提示实际输出了 N/M 行、其余行未输出；收窄 `--fields` 或调低 `--limit` 可让每页容纳更多行。 2. **单行本身超预算**：截短该行的字符串值并以 `...` 标记，stderr 点名被截短的字段；在被截短过的字段上匹配或过滤会漏数据，需要原始值时请收窄 `--fields` 或 `--limit`。标识符字段（以 `_id` 或 `_key` 结尾）在任何一级都不会被截短。 diff --git a/zh/developer/go-sdk.mdx b/zh/developer/go-sdk.mdx index 3800145a..9dea4759 100644 --- a/zh/developer/go-sdk.mdx +++ b/zh/developer/go-sdk.mdx @@ -1,7 +1,7 @@ --- title: Flashduty Go SDK sidebarTitle: Go SDK -description: "go-flashduty 是 Flashduty 官方开源的 Go SDK，与 Open API 严格 1:1 的类型化封装，当前覆盖全部 337 个 API 操作、39 个服务。" +description: "go-flashduty 是 Flashduty 官方开源的 Go SDK，与 Open API 严格 1:1 的类型化封装，当前覆盖全部 349 个 API 操作、39 个服务。" keywords: ["Go SDK", "go-flashduty", "Open API", "Golang", "客户端"] --- @@ -11,7 +11,7 @@ keywords: ["Go SDK", "go-flashduty", "Open API", "Golang", "客户端"] `go-flashduty` 是 Flashduty 官方开源的 Go 客户端，覆盖 Flashduty Open API 的每一个 REST 接口。它采用与 [go-github](https://github.com/google/go-github) 一致的设计风格——服务分组、类型化请求与响应、可组合传输层——并与 OpenAPI 规范保持严格 1:1：每个方法对应且仅对应一次 HTTP 调用，返回 `(*T, *Response, error)`，不做任何跨接口的隐式聚合或增强。 -SDK 当前覆盖 **337 个 API 操作**、**39 个服务**，全部由 Flashduty OpenAPI 规范生成，经单元测试覆盖，并针对线上 API 做过端到端验证。 +SDK 当前覆盖 **349 个 API 操作**、**39 个服务**，全部由 Flashduty OpenAPI 规范生成，经单元测试覆盖，并针对线上 API 做过端到端验证。 SDK 故意保持"薄"。诸如短 ID 解析、跨接口编排等消费侧逻辑应放在调用方（CLI / MCP）中，而不是塞进 SDK 或滥用某个接口。这样 SDK 始终与 API 一一对应,可预测、可生成、可校验。 @@ -164,6 +164,7 @@ client, err := flashduty.NewClient("YOUR_APP_KEY", | `client.ServiceMap` | 服务拓扑（ServiceMap） | | `client.Analytics` | 分析 | | `client.A2aAgents` | A2A Agents | +| `client.Artifacts` | AI SRE 产物 | | `client.Automations` | AI SRE 自动化 | | `client.Knowledge` | AI SRE 知识库（知识包与知识文件） | | `client.McpServers` | MCP Servers | @@ -179,9 +180,19 @@ client, err := flashduty.NewClient("YOUR_APP_KEY", | `client.SessionReplay` | RUM 会话回放 | | `client.Sourcemaps` | RUM Sourcemap | +`client.StatusPages.DraftCreate`（`POST /status-page/draft/create`）把一次状态页事件草稿存下来，供人工在控制台审阅后发布，不会直接对外可见：`draft` 为任意 JSON，按原文存储、序列化后不超过 64 KB，其中 `page_id`、`type`（`incident` 或 `maintenance`）、`name`、`message` 会被校验；`change_id`（> 0 时表示追加到已有事件的一次更新）、`status`、`affected_components` 可选，新建 maintenance 时可用 `start_time` / `end_time`（Unix 秒）指定窗口。请求上的 `source` 是草稿来源标记（≤ 64 字符，如 `ai_sre:sess_xxx`）；响应返回 `draft_id`（匹配 `draft_[A-Za-z0-9]{22}`），控制台的审阅链接即携带它。 + `client.Knowledge` 对应 `/safari/knowledge/*` 的 9 个 API 操作：知识包侧为 `PackReadGet`（获取账户知识包）、`PackReadList`（列出知识包）、`PackWriteEnsure`（确保知识包存在）、`PackWriteUpdate`（变更知识包作用域）、`PackWriteDelete`（删除知识包）；知识文件侧为 `FileReadGet`、`FileReadList`、`FileWritePut`（上传/覆盖）、`FileWriteDelete`。相关导出类型包括 `KnowledgePackItem`、`KnowledgeFileItem`、`KnowledgeWarning` 以及各 `Knowledge*Request` / `Knowledge*Response`。 -`client.Diagnostics`（诊断）提供数据源查询方法：`QueryData` 通过 `POST /monit/query/data` 执行同步查询，返回稳定的 `query_result.v1` 结构化结果（`format` 固定为 `query_result.v1`，`result.kind` 为 `frames` / `records` / `samples` 之一），该接口要求 monit-edge v0.65.0 及以上版本；`QueryDiagnose`（`POST /monit/query/diagnose`）用于预聚合 RCA 分析（日志模式或指标趋势），最长运行 35 秒。 +`client.Artifacts`（AI SRE 产物）对应 `/safari/artifact/*` 的 11 个 API 操作：画廊读取侧 `ReadGet`（按 ID 获取单个已发布产物）、`ReadList`（分页列出调用方可见的产物，支持标题子串搜索、`scope`（`all` / `personal` / `team`）与 `team_ids` 过滤）、`ReadGetFileState`（批量探测会话展示文件（`pf_` 前缀）是否已有上线产物，单次至多 50 个 ID）；文件侧 `ReadSign`（为展示文件签发短期有效的下载/预览 URL，有效期 5 分钟，`expires_in` 固定 300 秒）与 `ReadStream`（凭签名 token 下载或预览文件，成功响应体是文件而非 JSON 信封，原始字节放在 `Response.Raw`）；写入侧 `WritePublish`（把会话产生的文件发布为画廊产物）、`WriteUpdate`（重命名或转移个人/团队作用域）、`WriteDelete`（从画廊移除，源文件仍保留在会话中）；公开分享 `WriteShareEnable`（开启匿名公开分享并返回公开链接，任何人凭链接即可查看、无需登录）、`WriteShareRevoke`（关闭分享，链接立即失效）、`WriteShareSync`（把公开快照刷新为最新内容——当 `share_enabled` 为 true 且 `share_file_id` 与 `file_id` 不一致时表示快照已过期，调用它刷新）。相关导出类型包括 `PublishedArtifactItem`、`ArtifactShareState`、`SignedUrLs` 以及各 `Artifact*Request` / `Artifact*Response`。 + +`client.Diagnostics`（诊断）提供数据源查询方法：`QueryData` 通过 `POST /monit/query/data` 执行同步查询，返回稳定的 `query_result.v1` 结构化结果（`format` 固定为 `query_result.v1`，`result.kind` 为 `frames` / `records` / `samples` 之一），该接口要求 monit-edge v0.65.0 及以上版本；`QueryDiagnose`（`POST /monit/query/diagnose`）用于预聚合 RCA 分析（日志模式或指标趋势），最长运行 35 秒，**但已弃用**——请迁移到 `client.DataSources.ToolsInvoke` 并使用 `prometheus.metric_trends`、`loki.log_patterns` 或 `victorialogs.log_patterns` 工具；该接口为既有调用方保留，旧请求与响应格式不变。 + +`client.DataSources.ToolsInvoke`（`POST /monit/datasource/tools/invoke`，`monit-datasource-tools-invoke`）在某个已配置数据源上执行一个确定性工具：`tool` 名称由数据源类型前缀修饰（如 `mysql.overview`），`params` 为工具专属 JSON 参数（省略视为 `{}`，显式 `null` 非法）；自由 SQL 请走 `/monit/query/data`，`mysql.query` 与 `postgres.query` 不受支持。该接口要求集群中所有在线可路由的 Edge 会话都支持 v0.71.0 基础调用协议（单个工具可能要求更新的实现），无工具目录、无自动重放、也不会回退到 Agent 或旧版 diagnose。请求体上限 128 KiB，完整成功响应上限 1 MiB，单工具超时至多 25 秒；响应为 `DatasourceToolResult`（`data` 为工具专属 JSON、永不为 null，`summary` 可选，出现 `truncated` 时其 `reason` 说明截断原因）。 + +`client.DataSources` 的 `payload` 按 `type_ident` 选择类型专属配置块。当前允许的 `type_ident` 共 15 种：`prometheus`、`loki`、`mysql`、`oracle`、`postgres`、`clickhouse`、`elasticsearch`、`sls`、`tencent_cls`、`victorialogs`，以及新增的诊断专用类型 `redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka`——诊断专用类型的 `alerting_enabled` 恒为 false（不阻止非告警查询与工具调用），且拒绝传 true。连接地址规则：Redis/MongoDB 诊断类型为单个 `host:port`（IPv6 需加方括号），不接受 URI、userinfo 或 query；`kafka` 为 1–32 个以逗号分隔、互不重复的 `host:port` bootstrap 地址（规范化后至多 4096 字符，`payload` 中不再有 broker 列表）；`mongodb_mongod` / `mongodb_mongos` 的配置块中 `auth_source` 默认为 `admin`，用户名与密码必须成对配置，不支持客户端证书；Redis 节点配置的 `database` 默认为 0。诊断类型的 `password` 与 Kafka 的 `tls_key` 等敏感字段支持 `${env:NAME}` 引用：响应中字面值会被省略（仅当存储值本身就是 `${env:...}` 引用时才回显），更新时省略这些字段即保留原值，显式传空字符串则清除。 + +`enabled` 与 `alerting_enabled` 相互独立：`enabled`（业务执行开关）创建时默认 true，`alerting_enabled`（是否允许参与告警评估；告警还要求 `enabled` 为 true 且类型支持告警）创建时对告警类型默认 true、对诊断专用类型默认 false；二者更新时省略均保留当前值，显式传 `null` 非法；当有启用的告警规则引用该数据源时，将其 `enabled` 置为 false 会以 conflict 拒绝。另外 `/monit/datasource/list` 响应中 `payload` 恒为 `null`（列表查询不读 payload 列），create/update/info 响应中才会填充。 所有标识符、服务字段名与方法名均与生成代码保持一致。具体每个服务有哪些方法、请求与响应类型,请以 `services_gen.go` 与各服务文件,以及 [Open API 参考](/zh/openapi/introduction) 为准。 @@ -259,7 +270,7 @@ for page := 0; page < 100; page++ { --- -Flashduty API 返回的未成功调用——无论是信封中携带了错误,还是 HTTP 状态非 2xx——都会返回 `*ErrorResponse`。它带有 `Code`、`Message` 与 `RequestID` 字段,排障时把 `RequestID` 提供给支持团队即可定位。 +Flashduty API 返回的未成功调用——无论是信封中携带了错误,还是 HTTP 状态非 2xx——都会返回 `*ErrorResponse`。它带有 `Code`、`Message`、可选的 `Reason` 与 `RequestID` 字段,排障时把 `RequestID` 提供给支持团队即可定位。`Reason` 携带服务端给出的可选原因（信封内的 `DutyError` 同样带有该字段，JSON 字段为 `reason`,omitempty）；非空时它也会被追加到错误字符串末尾,形如 `, reason X`。 当 API 返回 429 时,错误被提升为 `*RateLimitError`：它内嵌 `*ErrorResponse`（所以 `errors.As` 取 `*ErrorResponse` 仍然成立),并额外带上 `RetryAfter` 提示。 diff --git a/zh/developer/overview.mdx b/zh/developer/overview.mdx index 35c46340..25c24eaf 100644 --- a/zh/developer/overview.mdx +++ b/zh/developer/overview.mdx @@ -58,7 +58,7 @@ curl -sSL https://static.flashcat.cloud/flashduty-cli/install.sh | sh ## Go SDK -go-flashduty 是 Flashduty 官方的 Go SDK，采用 go-github 风格的设计，对 Flashduty OpenAPI 进行类型化封装，覆盖 337 个 API 操作、39 个服务。您可以在 Go 程序中直接调用，享受完整的类型安全和自动补全。 +go-flashduty 是 Flashduty 官方的 Go SDK，采用 go-github 风格的设计，对 Flashduty OpenAPI 进行类型化封装，覆盖 349 个 API 操作、39 个服务。您可以在 Go 程序中直接调用，享受完整的类型安全和自动补全。 模块为 `github.com/flashcatcloud/go-flashduty`，要求 Go 1.24+，一行命令安装： diff --git a/zh/home.mdx b/zh/home.mdx index a524a67b..4c677f2e 100644 --- a/zh/home.mdx +++ b/zh/home.mdx @@ -163,7 +163,7 @@ Real User Monitoring（真实用户监控）帮助您了解真实用户如何体 认证方式、请求规范、错误处理 - 全部 337 个接口，按模块分类 + 全部 354 个接口，按模块分类 传统分页与游标分页机制 diff --git a/zh/monitors/data-sources/data-sources.mdx b/zh/monitors/data-sources/data-sources.mdx index 0cf11bd9..2f31218f 100644 --- a/zh/monitors/data-sources/data-sources.mdx +++ b/zh/monitors/data-sources/data-sources.mdx @@ -1,7 +1,7 @@ --- title: "数据源管理" -description: "配置和管理 Monitors 的数据源，包括 Prometheus、Elasticsearch、Loki、ClickHouse、MySQL、Oracle、PostgreSQL、Aliyun SLS、Tencent CLS、VictoriaLogs 等类型" -keywords: ["数据源", "Prometheus", "Elasticsearch", "Loki", "ClickHouse", "MySQL", "Oracle", "PostgreSQL", "SLS", "Tencent CLS", "VictoriaLogs"] +description: "配置和管理 Monitors 的数据源，包括 Prometheus、Elasticsearch、Loki、ClickHouse、MySQL、Oracle、PostgreSQL、Aliyun SLS、Tencent CLS、VictoriaLogs、Redis、MongoDB、Kafka 等类型" +keywords: ["数据源", "Prometheus", "Elasticsearch", "Loki", "ClickHouse", "MySQL", "Oracle", "PostgreSQL", "SLS", "Tencent CLS", "VictoriaLogs", "Redis", "MongoDB", "Kafka", "数据源工具"] --- 数据源是告警引擎查询数据的来源。你需要先配置数据源，告警引擎才能从中读取数据进行异常判定。 @@ -10,7 +10,7 @@ keywords: ["数据源", "Prometheus", "Elasticsearch", "Loki", "ClickHouse", "My ## 支持的数据源类型 -Monitors 支持以下 10 种数据源类型： +Monitors 支持以下 15 种数据源类型： | 类型 | 说明 | |------|------| @@ -24,6 +24,13 @@ Monitors 支持以下 10 种数据源类型： | **Aliyun SLS** | 阿里云日志服务 | | **Tencent CLS** | 腾讯云日志服务 | | **VictoriaLogs** | 日志数据库，VictoriaMetrics 生态的日志解决方案 | +| **Redis Node**（`redis_node`） | Redis 单节点，仅诊断类型 | +| **Redis Sentinel**（`redis_sentinel`） | Redis Sentinel 集群，仅诊断类型 | +| **MongoDB Mongod**（`mongodb_mongod`） | MongoDB 单节点，仅诊断类型 | +| **MongoDB Mongos**（`mongodb_mongos`） | MongoDB 分片集群路由，仅诊断类型 | +| **Kafka**（`kafka`） | Apache Kafka 集群，仅诊断类型 | + +其中 Redis Node、Redis Sentinel、MongoDB（mongod/mongos）与 Kafka 这 5 种**仅诊断类型**用于数据库与中间件诊断（详见[主机诊断与数据源诊断](/zh/monitors/targets/overview#主机诊断与数据源诊断)），不能用于告警评估：它们不允许开启 `alerting_enabled`（恒为 `false`），无法参与告警规则的查询与评估。连接地址等配置要求见[各数据源类型配置](#各数据源类型配置)。 ## 数据源列表 @@ -73,6 +80,20 @@ Monitors 支持以下 10 种数据源类型： 名称通配方式存储的是名称字符串，如果数据源改名，已有的通配规则可能不再匹配。精确匹配方式存储的是数据源 ID，不受改名影响。如果对稳定性要求高，建议优先使用精确匹配。 +## 启用与告警评估开关 + +数据源有两个相互独立的开关，分别控制业务执行与告警评估： + +| 开关 | 字段 | 含义 | +|------|------|------| +| **启用** | `enabled` | 是否开启业务执行。关闭后数据源不接受业务查询与数据源工具调用，但不会改变 `alerting_enabled` | +| **允许告警评估** | `alerting_enabled` | 是否允许该数据源参与告警规则的查询与评估。告警评估同时要求 `enabled=true` 且数据源类型支持告警；`false` 不会阻断非告警查询与数据源工具 | + +- **创建时的默认值**：`enabled` 默认为 `true`；`alerting_enabled` 对支持告警的类型默认为 `true`，对仅诊断类型默认为 `false`。 +- **更新时的行为**：两个字段省略时均保留当前值；显式传入 `null` 非法。 +- **仅诊断类型**（`redis_node`、`redis_sentinel`、`mongodb_mongod`、`mongodb_mongos`、`kafka`）不允许设置 `alerting_enabled=true`。 +- **冲突保护**：存在启用中的告警规则引用该数据源时，关闭 `alerting_enabled` 会被拒绝并返回冲突（HTTP 409），需要先处理引用该数据源的告警规则。实际执行告警评估时，数据源还必须处于 `enabled=true` 状态。 + ## 各数据源类型配置 ### Prometheus @@ -245,6 +266,57 @@ SecretKey 为只写字段：保存后列表与详情均不返回字面量密钥 Tencent CLS 类型的告警规则只能精确绑定一个数据源，不支持名称通配。创建规则时数据源选择为单选、名称通配输入被隐藏；配置非法时保存会提示「该数据源类型只能绑定一个数据源」或「该数据源类型不支持名称通配，请清空后重新选择」。详见 [Tencent CLS 告警规则](/zh/monitors/alert-rules/tencent-cls)。 +### Redis Node / Redis Sentinel + +`redis_node`（Redis 单节点）与 `redis_sentinel`（Redis Sentinel 集群）是仅诊断类型，不支持告警评估。连接地址为单个 `host:port`（如 `localhost:6379`、`localhost:26379`），IPv6 地址需加方括号（如 `[::1]:6379`）；不接受 URI、userinfo 或查询参数，连接地址中也不支持 `${env:}` 引用。地址规范化后最多 4096 个字符。 + +| 配置项 | 说明 | +|--------|------| +| **连接地址** | 单个 `host:port`；IPv6 加方括号；不接受 URI、userinfo 或查询参数 | +| **用户名** | 可选；支持 `${env:NAME}` 环境变量引用 | +| **密码** | 可选；支持 `${env:NAME}` 引用；保存后不回显字面密码 | +| **数据库编号**（仅 Redis Node） | Redis DB 编号，默认 `0` | +| **超时时间（毫秒）** | 连接超时，默认 `3000`，范围 1000–10000 | + +### MongoDB（mongod / mongos） + +`mongodb_mongod`（MongoDB 单节点）与 `mongodb_mongos`（MongoDB 分片集群路由）是仅诊断类型，不支持告警评估。连接地址为单个 `host:port`（如 `localhost:27017`），IPv6 地址需加方括号；不接受 URI、userinfo 或查询参数，连接地址中也不支持 `${env:}` 引用。地址规范化后最多 4096 个字符。 + +| 配置项 | 说明 | 默认值 | +|--------|------|--------| +| **连接地址** | 单个 `host:port`；IPv6 加方括号；不接受 URI、userinfo 或查询参数 | - | +| **用户名 / 密码** | 认证凭据，必须同时配置；支持 `${env:NAME}` 引用；密码保存后不回显字面值 | - | +| **认证数据库** | 认证所用数据库 | `admin` | +| **超时时间（毫秒）** | 连接超时 | `3000` | +| **TLS** | 是否启用 TLS | 关闭 | +| **CA 证书** | PEM 格式 CA 证书或 `${env:NAME}` 引用 | - | +| **最低 / 最高 TLS 版本** | TLS 1.2（默认）或 1.3；最高版本不能低于最低版本 | 1.2 / 不限制 | +| **服务端名称** | TLS 握手 SNI / 证书校验主机名；留空取连接地址中的主机名 | - | +| **跳过服务端证书校验** | 启用 TLS 时是否不校验服务端证书 | 否 | + +MongoDB 不支持客户端证书认证（mTLS）。 + +### Kafka + +`kafka` 是仅诊断类型，不支持告警评估。连接地址为 1–32 个不重复、逗号分隔的 `host:port` 引导地址（如 `broker1:9092,broker2:9092`），broker 列表只写在连接地址中，payload 不包含 broker 列表；IPv6 地址需加方括号；不接受 URI、userinfo 或查询参数，连接地址中也不支持 `${env:}` 引用。地址规范化后最多 4096 个字符。 + +| 配置项 | 说明 | 默认值 | +|--------|------|--------| +| **连接地址** | 1–32 个不重复的 `host:port`，逗号分隔 | - | +| **SASL 机制** | `none`（不接受凭据）、`plain`、`scram-sha-256`、`scram-sha-512`（后三者需要用户名与密码） | `none` | +| **用户名 / 密码** | SASL 认证凭据；支持 `${env:NAME}` 引用；密码保存后不回显字面值 | - | +| **超时时间（毫秒）** | 连接超时 | `5000` | +| **TLS** | 是否启用 TLS | 关闭 | +| **CA 证书** | PEM 格式 CA 证书或 `${env:NAME}` 引用 | - | +| **客户端证书 / 私钥** | PEM 格式，必须成对配置；私钥保存后不回显字面值，支持 `${env:NAME}` 引用 | - | +| **最低 / 最高 TLS 版本** | TLS 1.2（默认）或 1.3；最高版本不能低于最低版本 | 1.2 / 不限制 | +| **服务端名称** | TLS 握手 SNI / 证书校验主机名；留空取连接地址中的主机名 | - | +| **跳过服务端证书校验** | 启用 TLS 时是否不校验服务端证书 | 否 | + +### 凭据的保存语义 + +以上 5 种诊断类型与 Tencent CLS 一致：密码（以及 Kafka 的客户端私钥）为只写字段，保存后列表与详情均不返回字面值；以 `${env:}` 引用保存的值不是秘密，会正常回显。更新时省略该字段表示保持原值，显式传空字符串表示清除。 + ## 在 Edge 本地引用凭据 使用 `v0.46.0` 或更高版本的 Edge 时，你可以在受支持的数据源连接字段中使用环境变量引用，而不必将凭据直接写入数据源配置。Edge 会在本地进程中解析引用值；解析后的凭据不会回写到同步的数据源配置、调试输出或 API 载荷中。 diff --git a/zh/monitors/targets/overview.mdx b/zh/monitors/targets/overview.mdx index d5456d8f..7cee848d 100644 --- a/zh/monitors/targets/overview.mdx +++ b/zh/monitors/targets/overview.mdx @@ -43,6 +43,41 @@ flowchart TD Agent 提供 `os.overview`、`os.top_processes`、`shell.exec`、`net.tcp_ping` 和 `http.get` 五个主机工具，实际可用集合受 Agent 版本与本地策略控制。TCP/HTTP 探测提供主机视角的连通性证据，数据库内部状态由数据源诊断获取。 +Agent 主机工具只作用于主机本身：`tools-catalog` 与 `tools-invoke` 的目标类型仅支持 `host`，数据库服务端点不是 Agent 目标。数据库与中间件的诊断需要改用**数据源工具**（见下文），由能访问数据源的 Edge 执行。数据源工具调用要求数据源 `enabled=true`；`alerting_enabled=false` 不影响诊断。 + +### 数据源工具 + +每个已配置的数据源提供一组命名诊断工具，工具名以数据源类型为前缀，例如： + +| 数据源类型 | 工具示例 | +|------------|----------| +| MySQL | `mysql.overview`、`mysql.lock_contention` | +| PostgreSQL | `postgres.activity` | +| Redis | `redis_node.slowlog` | +| Kafka | `kafka.consumer_lag` | +| Elasticsearch | `elasticsearch.cat` | +| Prometheus | `prometheus.metric_trends` | +| Loki / VictoriaLogs | `loki.log_patterns`、`victorialogs.log_patterns` | + +- **一次调用执行一个命名工具**，通过数据源 ID（`datasource_id`）指定目标。同一个连接地址配置成多个数据源 ID 表示不同的凭据或配置，必须保持独立。 +- **没有工具目录**：各类型的工具名称与参数由类型相关参考提供，不要猜测参数。`mysql.query`、`postgres.query` 工具已移除，自由 SQL 查询请使用数据源查询（monit-query 的 Data）能力。 +- **版本门禁**：要求所选集群内**所有当前在线可路由的 Edge 会话**支持 v0.71.0 基础 invoke 协议，具体工具可能要求更新的实现。不满足时错误原因见表。 +- **没有自动回退**：接口不提供工具目录、自动重放，也不会回退到 Agent 或旧的 diagnose 流程；出现版本类错误时应升级 Edge，而不是重启或轮换 Edge。请求体上限 128 KiB，完整成功响应上限 1 MiB，单次工具执行超时最多 25 秒。 + +错误通过 `error.reason` 返回： + +| reason | 含义 | +|--------|------| +| `edge_upgrade_required` | Edge 版本低于 v0.71.0，需升级集群内的 Edge | +| `mixed_edge_versions` | 集群内 Edge 版本混杂，部分实例过旧，需统一升级 | +| `no_active_edge` | 集群内没有在线可路由的 Edge 会话 | +| `tool_not_supported` | 该工具不被当前实现支持 | +| `invalid_request` | 请求参数错误，需修正参数后重试 | +| `source_too_large` | 请求体超过 128 KiB，需要缩小查询范围 | +| `result_too_large` | 结果超过 1 MiB，需要缩小查询范围 | +| `datasource_disabled` | 数据源未启用（`enabled=false`） | +| `datasource_not_found` | 数据源不存在 | + Agent 同时提供 [ServiceMap](/zh/monitors/targets/servicemap) 的主机拓扑采集与上报能力。 diff --git a/zh/on-call/advanced/war-room.mdx b/zh/on-call/advanced/war-room.mdx index a4c49d52..fc8dec54 100644 --- a/zh/on-call/advanced/war-room.mdx +++ b/zh/on-call/advanced/war-room.mdx @@ -110,6 +110,10 @@ Flashduty On-call 作战室（War Room）是专为故障应急响应设计的自 + +**平台创建的作战室群聊不能作为常驻通知目标。** 系统会给每个群聊标注来源：`origin=system` 表示这是平台创建的群聊（目前只有故障作战室），与人工创建的群聊区分开。因此，分派策略的 **IM 应用群**（飞书/钉钉、Slack、Microsoft Teams 群聊）与值班计划换班通知的 **群聊渠道**（飞书/钉钉、Slack 群聊）选择器会自动排除作战室——飞书/钉钉与 Slack 选择器的提示文案为「请选择…群聊（不含故障作战室）」。作战室随故障生、随故障关，如果把它配置为常驻通知目标，这条配置指向的群聊注定会消失；若此前已保存的群聊 ID 已失效（作战室已解散、机器人被移出群、群聊已删除），选择器会把该目标显示为 **群聊不存在**，并可通过移除按钮清掉。 + + ### 移动端 App Flashduty App 已支持完整的作战室生命周期，与控制台、IM 应用共享同一套作战室能力。移动端行为要点如下： diff --git a/zh/on-call/analytics/insights.mdx b/zh/on-call/analytics/insights.mdx index a5179819..e330cedf 100644 --- a/zh/on-call/analytics/insights.mdx +++ b/zh/on-call/analytics/insights.mdx @@ -37,7 +37,8 @@ keywords: ["分析看板", "数据分析", "故障统计", "报表导出", "运 | 协作空间 | 选择需要查询的协作空间名称，支持多选，选中后会按选中的协作空间更新仪表盘中的数据 | | 严重程度 | 选择需要查询的严重程度，支持多选，选中后会按选中的严重程度更新仪表盘中的数据 | | 时间范围 | 选择需要查询的时间范围，支持按本周、最近两周、本月、上个月以及自定义时间的维度进行查询，最长支持查询最近 **2 年（720 天）** 的数据（具体上限以您的订阅版本为准） | -| 数据间隔 | 支持天、周、月的维度进行查询，默认按小时进行查询，但查询的时间范围大于 31 天时，无法以天的维度进行预览 | +| 数据间隔 | 支持天、周、月的维度进行查询，默认按小时进行查询，但查询的时间范围大于 31 天时，无法以天的维度进行预览；天 / 周 / 月的分桶按查看者的生效时区（个人时区优先，回退组织时区）划分 | +| 时区 | 看板中的时间、日 / 周 / 月聚合与查询均按查看者的生效时区（个人时区优先，回退组织时区）展示与统计。筛选栏右侧显示当前生效时区标识，悬停提示「时间按你所在时区展示与统计」 | | 排序 | 团队、协作空间和个人维度的仪表盘可以选择倒排和正排，默认只显示 TOP 10 的数据，单独放大后可以展示更多 | ## 按小时拆分 diff --git a/zh/on-call/channel/escalation-rule.mdx b/zh/on-call/channel/escalation-rule.mdx index b3514544..672a0cdd 100644 --- a/zh/on-call/channel/escalation-rule.mdx +++ b/zh/on-call/channel/escalation-rule.mdx @@ -76,7 +76,7 @@ src="https://download.flashcat.cloud/flashduty/video/escalate-rule.mp4" 发送到即时通讯软件的群组中，支持 @ 提到相关人员。 - - **IM 应用群**：支持飞书、钉钉、企业微信、Slack、Microsoft Teams 群（其中企业微信仅存量配置可用，新建策略不可选），需先完成 [IM 集成](/zh/on-call/integration/instant-messaging/lark) + - **IM 应用群**：支持飞书、钉钉、企业微信、Slack、Microsoft Teams 群（其中企业微信仅存量配置可用，新建策略不可选），需先完成 [IM 集成](/zh/on-call/integration/instant-messaging/lark)。群聊选择器会自动排除平台创建的群聊（如故障作战室，提示「请选择…群聊（不含故障作战室）」），已失效的群聊目标显示为「群聊不存在」并可移除 - **群机器人**：支持飞书、钉钉、企业微信、Slack、Telegram、Zoom 等 Webhook 机器人。其中 Telegram 需要配置 Webhook 通知地址和群聊 ID（Chat Ids），Zoom 需要配置 Webhook 地址和 Verify Token，并支持开启 @ 提醒功能。详见 [通知渠道配置](/zh/on-call/configuration/notifications) diff --git a/zh/on-call/configuration/schedule.mdx b/zh/on-call/configuration/schedule.mdx index 0bc69a8f..09148d63 100644 --- a/zh/on-call/configuration/schedule.mdx +++ b/zh/on-call/configuration/schedule.mdx @@ -65,7 +65,7 @@ Flashduty On-call 提供极具灵活性的值班编排能力，支持按天、 - **遵循个人偏好**：每个值班人员按各自在个人账户中配置的通知渠道接收通知 - **遵循统一设置**：由管理员统一选择通知渠道（短信、邮件，以及已集成的 IM 应用） - **群聊渠道**：将通知发送到群聊中，支持以下平台： - - 飞书应用、钉钉应用、Slack 应用（通过已集成的 IM 应用选择群聊） + - 飞书应用、钉钉应用、Slack 应用（通过已集成的 IM 应用选择群聊；选择器会自动排除故障作战室等平台创建的群聊，已失效的群聊显示「群聊不存在」并可移除） - 企业微信机器人、钉钉机器人、飞书机器人（通过 Webhook 地址发送） - Slack 机器人、Telegram 机器人、Zoom 机器人 diff --git a/zh/on-call/integration/sso/role-team-sync.mdx b/zh/on-call/integration/sso/role-team-sync.mdx new file mode 100644 index 00000000..85e73a33 --- /dev/null +++ b/zh/on-call/integration/sso/role-team-sync.mdx @@ -0,0 +1,97 @@ +--- +title: "角色与团队同步" +description: "SAML2.0、OIDC、CAS 协议下，按身份提供商返回的角色/团队名称（claim/属性名）自动同步成员角色与团队；名称未匹配时使用默认角色/默认团队兜底" +keywords: ["SSO", "单点登录", "角色同步", "团队同步", "同步配置", "claim"] +--- + +在 **平台管理 → 单点登录** 的设置页面中，「同步配置」分区决定成员通过 SSO 登录时如何获得 Flashduty 中的角色与团队： + +- **SAML2.0 / OIDC / CAS**：按身份提供商返回的**角色名称 / 团队名称**进行匹配（claim / 属性名方式），名称未匹配时使用**默认角色 / 默认团队**兜底。 +- **LDAP**：不使用名称匹配，而是按用户所属 **LDAP Group** 的 DN 与映射规则匹配，详见 [LDAP 角色和团队同步](/zh/platform/configure-sso#ldap-角色和团队同步)。 + +同步在成员**每次通过 SSO 登录**时触发。本文描述 SAML2.0 / OIDC / CAS 协议的同步配置与匹配规则。 + +## 同步配置字段 + +「同步配置」分区包含以下字段： + +| 字段 | 说明 | +| --- | --- | +| 同步角色（`sync_role_enabled`） | 开关。开启后按名称同步角色；关闭时成员登录不会改动角色 | +| 同步团队（`sync_team_enabled`） | 开关。开启后按名称同步团队；关闭时成员登录不会改动团队 | +| 角色字段（`roles`） | 身份提供商返回的**角色名称**所在的 claim / 属性名，如 `roles`。支持字符串或字符串数组；按名称精确匹配 | +| 团队字段（`teams`） | 身份提供商返回的**团队名称**所在的 claim / 属性名，如 `teams`。支持字符串或字符串数组；按名称精确匹配 | +| 默认角色（`default_role_ids`） | 多选角色（下拉仅列出启用状态的角色）。当返回的角色名称未匹配到任何可用角色时，将同步这些默认角色 | +| 默认团队（`default_team_ids`） | 多选团队。当返回的团队名称未匹配到任何团队时，将同步这些默认团队 | + + +**角色字段 / 团队字段留空**时不会匹配任何名称：若对应的同步开关已开启，登录时该维度直接进入默认角色 / 默认团队分支；没有配置合格默认值时结果为空（见下方 [生效时机与覆盖语义](#生效时机与覆盖语义)）。 + + +## 匹配规则 + +角色/团队名称的匹配在 Flashduty 服务端完成，规则如下： + +### 名称来源与归一化 + +- claim / 属性值支持**单个字符串或字符串数组**；数组中的非字符串元素会被忽略。 +- 每个名称去除首尾空格；空名称与重复名称会被去除。去重**区分大小写**——`Ops` 与 `ops` 是两个不同的名称。 +- 匹配为**精确匹配、区分大小写**：`Ops` 不会匹配 `ops`。 + +### 角色匹配 + +- 预设角色 `Admin`、`Responder`、`Viewer` **始终**可匹配（不要求启用状态）。 +- 自定义角色必须处于**启用**状态才会被匹配；已禁用角色即使名称相同也不会命中。 +- 同一名称命中多个角色时，取 **role_id 最小**的角色（例如账户中存在多个名为 `Ops` 的角色时，命中最小 ID 的那个）。 +- 未匹配到任何角色的名称会被**跳过**（服务端记录告警日志），不影响其他名称的匹配结果。 + +### 团队匹配 + +- 仅匹配**未删除**的团队。 +- 同样精确匹配、区分大小写；同名团队取 **team_id 最小**者。 +- 未匹配的团队名称同样跳过。 + +### 默认角色 / 默认团队兜底 + +- 仅当该维度的解析结果为**空**（一个名称都没匹配上）时才应用默认值；角色与团队**各自独立**判断，互不影响。 +- 默认角色：预设角色（`Admin` / `Responder` / `Viewer`）始终可用；自定义默认角色必须**存在且处于启用状态**，否则跳过并记录告警日志。 +- 默认团队：必须**存在且未被删除**，否则跳过。 +- 最终解析出的角色 ID / 团队 ID 会去重并按 ID 升序排列。 + +## 各协议取值来源 + +| 协议 | 角色/团队名称的取值来源 | +| --- | --- | +| SAML2.0 | SAML 断言（Assertion）中的属性，属性名即「角色字段 / 团队字段」配置的名称，如 `roles` | +| OIDC | ID Token 中的 claim，claim 名即「角色字段 / 团队字段」配置的名称。当同步已开启而 ID Token 未携带该 claim 时，Flashduty 会额外请求 **UserInfo** 端点，并将其返回的属性与 ID Token 的 claim 合并后进行匹配 | +| CAS | CAS `/serviceValidate` 响应中的属性（attributes），属性名即「角色字段 / 团队字段」配置的名称 | +| LDAP | 不使用 claim 名称：按 Group DN 与「映射规则」（`role_team_mapping`）匹配，并支持默认角色兜底，详见 [LDAP 角色和团队同步](/zh/platform/configure-sso#ldap-角色和团队同步) | + +## 协议切换与字段保留 + +保存 SSO 配置时，控制台会丢弃不属于当前协议的同步字段（避免切换协议后残留无用配置）： + +- **LDAP**：保留 Group 字段、Group DN 映射规则（`role_team_mapping`）与默认角色；`roles`、`teams`、`default_team_ids` 不会被保存。 +- **SAML2.0 / OIDC / CAS**：保留 `roles`、`teams`、`default_role_ids`、`default_team_ids`；`group` 与映射规则不会被保存。 + +## 生效时机与覆盖语义 + +- 同步在成员**每次通过 SSO 登录**时执行：服务端先用 claim 名称解析出角色 ID 与团队 ID，再写入该成员。 +- 写入为**覆盖式**：登录时的解析结果就是该成员当前的最终角色/团队，不会与已有角色/团队合并。 +- 若同步开启但解析结果为空（名称全部未匹配，且没有合格的默认角色/默认团队），成员对应的角色或团队会被**清空**。 +- 两个同步开关都关闭时，登录不会改动成员的角色与团队。 + + + + 各协议接入的整体配置指引 + + + 通过 Authing 配置 Flashduty SSO 单点登录 + + + 通过 Keycloak 配置 Flashduty SSO 单点登录 + + + 通过 OpenLDAP 配置 Flashduty SSO 单点登录 + + diff --git a/zh/openapi/api-catalog.mdx b/zh/openapi/api-catalog.mdx index 1d2466a6..e39982b1 100644 --- a/zh/openapi/api-catalog.mdx +++ b/zh/openapi/api-catalog.mdx @@ -3,7 +3,7 @@ title: "API 目录" description: "Flashduty Open API 接口完整列表，按产品模块组织并链接到详细文档" --- -Flashduty Open API 提供 **353** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。 +Flashduty Open API 提供 **354** 个接口，覆盖 On-call、Monitors、RUM、AI SRE 和平台五个主要模块。所有接口使用统一认证方式和请求规范。详情参见[快速开始](/zh/openapi/introduction)。 所有接口 URL 均以 `https://api.flashcat.cloud` 为 base，通过 query string 中的 APP Key 认证。 @@ -271,7 +271,7 @@ Flashduty Open API 提供 **353** 个接口，覆盖 On-call、Monitors、RUM、 - + ### 告警规则 @@ -304,6 +304,7 @@ Flashduty Open API 提供 **353** 个接口，覆盖 On-call、Monitors、RUM、 | POST | [`/monit/datasource/create`](/zh/api-reference/monitors/data-sources/monit-datasource-write-create) | 创建数据源 | | POST | [`/monit/datasource/update`](/zh/api-reference/monitors/data-sources/monit-datasource-write-update) | 更新数据源 | | POST | [`/monit/datasource/delete`](/zh/api-reference/monitors/data-sources/monit-datasource-write-delete) | 删除数据源 | +| POST | [`/monit/datasource/tools/invoke`](/zh/api-reference/monitors/data-sources/monit-datasource-tools-invoke) | 调用数据源工具 | | POST | [`/monit/datasource/sls/projects`](/zh/api-reference/monitors/data-sources/monit-datasource-read-sls-projects) | 查询 SLS 项目列表 | | POST | [`/monit/datasource/sls/logstores`](/zh/api-reference/monitors/data-sources/monit-datasource-read-sls-logstores) | 查询 SLS 日志库列表 | diff --git a/zh/platform/configure-sso.mdx b/zh/platform/configure-sso.mdx index 08da24d5..471f615f 100644 --- a/zh/platform/configure-sso.mdx +++ b/zh/platform/configure-sso.mdx @@ -85,6 +85,10 @@ Scopes 为必填字段。默认值 `openid`、`profile`、`email`、`phone` 是 | 成员仅支持 SSO 登录（`force_sso`） | 默认开启。开启后，账户内所有成员仅能通过 SSO 登录，密码与验证码登录将被拒绝。详见下文 [强制 SSO 登录](#强制-sso-登录) | | Flashduty 服务提供商信息 | **Redirect URL**：身份提供商回调地址 | + +**角色与团队同步**：SAML2.0 / OIDC / CAS 协议在设置页的「同步配置」分区中，按身份提供商返回的**角色/团队名称**（claim / 属性名）进行同步——名称精确匹配（区分大小写），未匹配到任何名称时使用「默认角色 / 默认团队」兜底；LDAP 协议则使用 Group DN 映射规则，两者机制不同。匹配规则、各协议取值来源与生效时机详见 [角色与团队同步](/zh/on-call/integration/sso/role-team-sync)。 + + ## 配置 LDAP 协议 --- @@ -247,7 +251,10 @@ This account requires SSO login. Password/code login is disabled. --- - + + + SAML2.0/OIDC/CAS 按名称同步角色与团队，未匹配时使用默认配置 + 通过 Authing 配置 Flashduty SSO 单点登录 diff --git a/zh/rum/quickstart/app-management.mdx b/zh/rum/quickstart/app-management.mdx index f4922fcd..48a2d5eb 100644 --- a/zh/rum/quickstart/app-management.mdx +++ b/zh/rum/quickstart/app-management.mdx @@ -339,7 +339,7 @@ Link 集成会从当前事件上下文中提取变量并替换到 URL 模板中 - 变更历史保留最近 50 个版本，更早的版本将自动清理且无法回滚。每条历史展示操作人与变更说明（如填写）。你可以将任一保留中的历史版本回滚为当前配置，回滚同样会生成新版本。 - 回滚产生的新版本带内容等价标注：若其配置内容与历史上某个更早版本完全相同，历史列表会标注该版本与那个最早相同内容的版本等价——版本号跳变不代表配置内容发生了变化。 -- 发布面板按最近到达的采样会话展示版本分布与采用进度，并区分「等待新会话」「逐步生效中」「已全部切换」，以及「未接收到配置」「未上报版本」（SDK 版本过低或尚未拉取过配置）的会话，帮助你确认这一版是否真正铺开。窗口内采样会话少于 20 条时，面板只展示实际会话数、不估算占比（占比由采样率放大估算，样本过少时结果没有意义）。 +- 发布面板按最近到达的采样会话展示**采用情况**与采用进度，状态标签为「等待新会话」（刚发布，尚无会话按当前版本开始）、「生效中」（部分会话已切换）、「最近会话已切换」（窗口内到达的会话均已在当前版本）、「未收到配置」（最近会话均未上报配置版本，常见为 SDK 未开启远程配置或版本过低）、「暂无数据」（窗口内暂无新会话）、「未检测到生效」（发布已超过约 8 小时仍未切到当前版本）；进度条中未上报配置版本的会话段标为「未上报」（SDK 版本过低或尚未拉取过配置）。点击**查看明细**可跳转到事件浏览器查看这批样本会话。窗口内采样会话少于 20 条时，面板只展示实际会话数、不估算占比（占比由采样率放大估算，样本过少时结果没有意义）。 ## 删除应用