diff --git a/docs.json b/docs.json index 89988a56..bc8e045d 100644 --- a/docs.json +++ b/docs.json @@ -558,7 +558,8 @@ "zh/monitors/targets/overview", "zh/monitors/targets/install-agent", "zh/monitors/targets/configure-targets", - "zh/monitors/targets/reload-and-verify" + "zh/monitors/targets/reload-and-verify", + "zh/monitors/targets/servicemap" ] }, { @@ -1823,7 +1824,8 @@ "en/monitors/targets/overview", "en/monitors/targets/install-agent", "en/monitors/targets/configure-targets", - "en/monitors/targets/reload-and-verify" + "en/monitors/targets/reload-and-verify", + "en/monitors/targets/servicemap" ] }, { diff --git a/en/ai-sre/artifacts.mdx b/en/ai-sre/artifacts.mdx index 999ce200..941f2bef 100644 --- a/en/ai-sre/artifacts.mdx +++ b/en/ai-sre/artifacts.mdx @@ -1,7 +1,7 @@ --- title: Artifacts -description: The artifact gallery collects web pages and reports that AI SRE sessions produce with the present_files tool and publish with the publish_artifact tool (for example, /insight reports). Search, filter or change scope, rename, share, download, and delete them here. -keywords: ["AI SRE", "Artifacts", "present_files", "publish_artifact", "insight report", "artifact gallery"] +description: The artifact gallery collects files that AI SRE sessions produce with the present_files tool and publish with the publish_artifact tool — web pages, reports, images, PDFs, source code, data files, and more (for example, /insight reports). Search, filter or change scope, rename, share (account-only or a public link), download, and delete them here. +keywords: ["AI SRE", "Artifacts", "present_files", "publish_artifact", "insight report", "artifact gallery", "public link", "share"] sidebarTitle: Artifacts --- @@ -13,7 +13,18 @@ sidebarTitle: Artifacts --- -An artifact is a file AI SRE produces in a session with the `present_files` tool and then publishes to the artifact gallery with the `publish_artifact` tool — typically a self-contained HTML report or page. For example, the operational insight report generated by typing `/insight` in a session is an artifact. +An artifact is a file AI SRE produces in a session with the `present_files` tool and then publishes to the artifact gallery with the `publish_artifact` tool. The most typical case is a self-contained HTML report or page — for example, the operational insight report generated by typing `/insight` in a session — but publishable types go well beyond that: + +| Category | Common extensions | +|---|---| +| Web pages & documents | `.html` `.htm` `.md` `.markdown` `.txt` `.log` | +| Data & config | `.csv` `.tsv` `.json` `.yaml` `.yml` `.xml` `.toml` `.ini` | +| Images | `.png` `.jpg` `.jpeg` `.gif` `.svg` `.webp` | +| PDF | `.pdf` | +| Source code | `.py` `.go` `.js` `.mjs` `.ts` `.jsx` `.tsx` `.java` `.c` `.h` `.cpp` `.cs` `.rb` `.rs` `.php` `.sh` `.sql` `.kt` `.swift` `.scala` `.css` `.vue` `.svelte` `.proto` `.tf` `.hcl`, and more | +| Archives | `.zip` `.tar` `.gz` `.tgz` | + +Files outside the publishable range don't show a "Publish to artifact gallery" button in the session. A published artifact initially inherits its source session's scope: artifacts from a personal session belong to their creator ("Personal"); artifacts from a session bound to a team belong to that team and can be shared with other account members. Users with edit permission can change the scope later. @@ -36,8 +47,8 @@ The artifact gallery has no entry point for manually uploading or creating files Each card shows: -- A kind icon in the preview area: a code icon when the content type or file name is HTML, otherwise a document icon; -- The title (up to two lines, truncated beyond that); +- A kind icon in the preview area: determined by file extension and content type — images, PDF, HTML, Markdown, tables (CSV / TSV), JSON, archives, and source code each get a dedicated icon, falling back to a generic file icon when the type can't be recognized; +- The title (single line, truncated beyond that; hover to see the full title); - An "Edited …" relative timestamp — just now / N minutes ago / N hours ago / N days ago, or a specific date beyond 30 days; - A scope badge in the bottom right: team artifacts show the team name (highlighted green); personal artifacts show the creator's name (gray). @@ -77,7 +88,7 @@ The detail page route is `/ai-sre/artifacts/:artifactId`. The top toolbar offers - **Title**: if you have edit permission, click the title to edit it inline (no separate form) — press Enter to save, Esc to cancel; - **Creator**: shown below the title as "Artifact by [creator]"; -- **Share**: copies the link to the artifact's detail page; +- **Share**: opens the share panel, where you can choose between "Account only" and "Public link" visibility — see [Share an artifact](#share-an-artifact) below; - **Delete**: shown only when you have edit permission; requires confirmation; - **More actions**: this menu appears only when at least one of the following is available — - **Open session**: shown when you still have access to the artifact's source session; opens that session's full conversation (messages, tool calls, artifact history); @@ -86,6 +97,37 @@ The detail page route is `/ai-sre/artifacts/:artifactId`. The top toolbar offers The body renders the artifact according to its actual content type (for example, an HTML report renders inline as a page). +## Share an artifact + +--- + +The **Share** button in the detail page toolbar opens the share panel. **Manage permission** at the top lists who can manage sharing for this artifact (the creator is labeled "Owner"; team artifacts also list team members). **Visibility** below offers two modes: + +| Mode | Who can open it | Content | +|---|---|---| +| Account only | Members signed in to the same account | Viewable once signed in; content is **always the latest version** | +| Public link | Anyone with the link, **no sign-in required** | Shows a **content snapshot** taken the moment the link was generated; it doesn't automatically sync after the artifact is updated | + +### Public link + +After you choose **Public link**, the panel first shows a content preview and a risk notice; the link only takes effect once you click **Generate public link**: + + +Once you generate a public link, anyone who gets the link can view this artifact, and the link can be forwarded further. Don't share secrets, personal information, or unauthorized third-party content. + + +On success, the link is copied to your clipboard automatically (a "Public link generated and copied to clipboard" toast appears). The public link takes the form `https:///share/artifact/` — it's identified by the artifact's own ID and carries no token; anonymous access is served entirely by the CDN, without going through any endpoint that requires sign-in. + +| Action | Description | +|---|---| +| Generate public link | Copies the artifact's current content as a public snapshot and enables the link | +| Update snapshot | Appears only when the artifact's content has changed since the snapshot was taken (an "Artifact content has changed — update the snapshot to sync the latest content" notice). Clicking it overwrites the snapshot with the latest content; **the link itself stays the same** | +| Revoke public link | Turns off public access; the link stops working immediately | + + +Artifacts larger than **16 MiB** can't generate a public link — you'll see a notice that the artifact exceeds the size limit. You can still share it using "Account only" mode. + + ## Permissions --- diff --git a/en/ai-sre/environments.mdx b/en/ai-sre/environments.mdx index d11a7998..8dd9f9cd 100644 --- a/en/ai-sre/environments.mdx +++ b/en/ai-sre/environments.mdx @@ -254,8 +254,20 @@ After the Runner starts, it continuously sends heartbeats. List statuses mean: |---|---| | Pending | The Environment exists, but the Runner has never connected. | | Online | The Runner is currently connected, heartbeat is healthy, and it can accept work. | +| Degraded | The Runner is still connected and its heartbeat is healthy, but its executor can't keep up — tasks are queuing up or taking too long to return. **You can keep using it, but responses will be slower**. | | Offline | The Runner connected before, but its heartbeat is currently lost. | +`degraded` is computed **in real time** and isn't persisted: it's re-evaluated from current signals on every read, so it never needs to be manually cleared. It's driven by two kinds of signal — + +- newer Runner versions report their own executor health probe and backlog count in the heartbeat, and degraded is judged directly from those; +- older Runner versions that don't report these metrics use a fallback rule instead: **3 consecutive** task timeouts against the same Environment mark it degraded (only timeouts longer than 20 seconds count, so a caller's own short timeout isn't misjudged). + +Recovery is automatic too: for newer Runner versions, the status returns to `Online` as soon as the heartbeat is healthy again (probe passes and no backlog); for older Runner versions, any single successful task resets the counter, or it recovers automatically after 30 minutes of sustained quiet. + + +When you see `Degraded`, first check CPU, memory, and disk load on the Runner's host, and whether a long-running task is monopolizing the executor. It doesn't block the session, but staying in this state for a while means that host can't keep up with its current task volume. + + The backend compares Runner versions during heartbeats. When a newer version is available, the Runner receives an upgrade notification and downloads, verifies, and replaces itself. Re-running the install command also upgrades manually. Uninstall commands are also in the setup guide, and differ by installation method: @@ -380,7 +392,7 @@ The environment selector at the bottom of the chat input decides where a new ses |---|---| | **Auto** | The default for new sessions. Uses an online Runner the current member can use; otherwise falls back to the cloud Sandbox. | | **Cloud Sandbox · Default** | Forces the system-managed cloud Sandbox and ignores self-hosted Runners. | -| **Self-hosted Environment** | Lists Runners the current member can use. Offline, never-connected, or team-mismatched Runners cannot be selected. | +| **Self-hosted Environment** | Lists Runners the current member can use. Offline, never-connected, or team-mismatched Runners cannot be selected; Runners in **Degraded** status **remain selectable**, and selecting one shows a "Degraded — you can continue, but responses may be slower" notice. | Environment selection is locked once per session: the Environment determined when the session sends its first message is recorded and reused for all later turns. Changing the selector afterward does not change that session. To switch environments, start a new session. diff --git a/en/ai-sre/insight.mdx b/en/ai-sre/insight.mdx index 42181099..01282317 100644 --- a/en/ai-sre/insight.mdx +++ b/en/ai-sre/insight.mdx @@ -58,7 +58,7 @@ Understanding how the report is put together helps you see where the numbers com - AI SRE first lists the sessions within scope for the last 30 days (up to 200 by default), covering **all four entry kinds** — web, IM, API, and scheduled; IM is a primary AI SRE entry point, so IM-originated sessions are analyzed alongside web. After exporting their full records, it keeps the sessions with **real signal**: **≥ 2 user-message turns OR ≥ 3 tool calls** (either one qualifies — `INSIGHT_MIN_MSGS` / `INSIGHT_MIN_CALLS`). The tool-call arm matters: it lets autonomous runs kicked off by an alert or a schedule — which may have zero human turns yet a dozen tool calls of real investigation — into the report, instead of being silently dropped by a user-turns-only filter. The quantitative overview also renders an **entry mix** line (`entry_mix`) showing where these sessions came from. + AI SRE first lists the sessions within scope for the last 30 days (up to 200 by default), covering **all four entry kinds** — web, IM, API, and automation; IM is a primary AI SRE entry point, so IM-originated sessions are analyzed alongside web. After exporting their full records, it keeps the sessions with **real signal**: **≥ 2 user-message turns OR ≥ 3 tool calls** (either one qualifies — `INSIGHT_MIN_MSGS` / `INSIGHT_MIN_CALLS`). The tool-call arm matters: it lets autonomous runs kicked off by an alert or a schedule — which may have zero human turns yet a dozen tool calls of real investigation — into the report, instead of being silently dropped by a user-turns-only filter. The quantitative overview also renders an **entry mix** line (`entry_mix`) showing where these sessions came from. The report's quantitative overview — session count, your turn count, tool call count, average turns, daily activity, tool and skill distribution, entry mix, model distribution, and outcome distribution — is computed deterministically across all sessions by program logic, not estimated by the model, so it is reliable and always present even when no friction is found. @@ -91,7 +91,7 @@ Computed deterministically by program logic, not estimated by the model; the mod | Activity | Per-day session activity bar chart, with start and end dates labeled | | Tool distribution | Ranking of tools the agent relied on most (top ~6) | | Skill distribution | Ranking of skills invoked during sessions; shows "No skills invoked" if none were called | -| Entry mix | Where the sessions came from, formatted as `web (60) · IM (25) · scheduled (5)` (`entry_mix`) | +| Entry mix | Where the sessions came from, formatted as `web (60) · IM (25) · automation (5)` (`entry_mix`) | | Model distribution | How many sessions used each model, formatted as `model name (N sessions)` | | Outcome distribution | Count of completed / incomplete / errored sessions (zero values omitted) | diff --git a/en/ai-sre/knowledge.mdx b/en/ai-sre/knowledge.mdx index 3cc25af6..b76046c4 100644 --- a/en/ai-sre/knowledge.mdx +++ b/en/ai-sre/knowledge.mdx @@ -60,7 +60,7 @@ After reading `DUTY.md`, the agent decides which `@references` to expand based o | Constraint | Value | Notes | | --- | --- | --- | -| Allowed extensions | `.md` `.yaml` `.yml` `.json` `.txt` `.sh` | Other extensions are rejected | +| File content | Plain text (UTF-8) | Validated by **content**, not extension: a file saves as long as it contains no NUL bytes and decodes as valid UTF-8. So `.py`, `.sql`, and even an extension-less `Dockerfile` can be uploaded alongside `.md` `.yaml` `.json` `.txt` `.sh`; conversely, a file with a `.txt` extension but binary content is rejected | | Per-file size limit | 1 MiB | Files exceeding this cannot be saved | | Per-pack size limit | 5 MiB | The usage bar in the console reflects this quota | | File count limit | 100 | No new files can be added once the limit is reached | @@ -88,7 +88,7 @@ Go to the **Knowledges** management page to create, edit, enable/disable, or del -**Document distillation**: Knowledge files only support the plain-text formats listed in the table above. If you upload a document in a format that can't be stored directly — PDF, Word, Excel, PowerPoint, or HTML — the console notes that the format can't be used by the agent directly and offers a **Go to chat for analysis** entry. Clicking it starts a new AI SRE session with the document carried in as an attachment; the agent reads the document and distills it into a Markdown knowledge file, which is saved into the current Knowledge Pack after your confirmation. +**Document distillation**: Knowledge files only accept plain-text content (see the table above). If you upload a document that can't be stored directly — `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.html`, `.htm` — the console notes that the format can't be used by the agent directly and offers a **Go to chat for analysis** entry. Clicking it starts a new AI SRE session with the document carried in as an attachment; the agent reads the document and distills it into a Markdown knowledge file, which is saved into the current Knowledge Pack after your confirmation. Legacy Office binary formats (`.doc`, `.xls`, `.ppt`) are outside the conversion range and get rejected outright as binary files — save them as `.docx` / `.xlsx` / `.pptx` first, then upload. **Reference consistency checks**: when you save a file, any `@reference` pointing to a file that does not exist in the pack returns a non-blocking unresolved-reference warning (the save still completes). When you delete a file that is still referenced by other files, a still-referenced conflict prompt appears first — you can choose to **force delete**. diff --git a/en/ai-sre/sessions.mdx b/en/ai-sre/sessions.mdx index 7238f977..7e5e7258 100644 --- a/en/ai-sre/sessions.mdx +++ b/en/ai-sre/sessions.mdx @@ -69,14 +69,16 @@ The chat page header provides share controls, shown only when you have manage pe |---|---| | Who can share | Members with manage permission on the session — the creator of a personal session, or the creator / account owner / admin / team members of a team session | | Who can open it | Members who hold the link and are signed in to the **same account**; the link does not work across accounts or for anonymous visitors | -| What link holders see | The session opens in **read-only** mode with a "This is a read-only shared session" notice: they can inspect the full context (messages, tool calls, artifacts), but the composer is replaced by the notice — they cannot continue the conversation or modify the original session | +| What link holders see | The session opens in **read-only** mode with a "This is a read-only shared session" notice: they can inspect the full context (messages, tool calls, artifacts), and can also open a Subagent dispatch chip to view the child session's execution details (also read-only); but the composer is replaced by the notice — they cannot continue the conversation or modify the original session | | How to keep working | Link holders can click **Fork into a new session** to derive their own session and continue from there | | How to revoke | Once sharing is enabled, a **Remove share** button appears in the header; clicking it invalidates the link immediately (a "Share removed" toast appears). Re-enabling sharing later generates a new link — the old link is not restored | Sharing mainly changes the visibility of **personal sessions**: a team session is already readable by any member of the same account who has the session ID (see the table above), whereas a personal session is visible only to its creator by default — a share link is the only way for other members of the account to open it. -Incognito sessions and Subagent sessions cannot be shared. +Incognito sessions cannot be shared. + +Subagent / A2A child sessions can't have sharing enabled on their own either — sharing can only be enabled on the **root session**. But once you share the root session, link holders can open a Subagent dispatch chip in the read-only view and view the corresponding child session's execution details, also read-only; child sessions are view-only and don't offer **Fork into a new session**. Revoking the root session's share also invalidates access to its child sessions. ### Per-Session Actions @@ -117,7 +119,7 @@ Type a message in the input box at the bottom and press Enter to send. The input - Click the plus button at the lower left of the input box to choose files, or paste images directly. Supported formats include images, PDFs, text / Markdown / CSV, and Office documents (Word / Excel / PowerPoint), up to **20 MB** per file. A single message can carry at most **9 attachments**, and the total size of all attachments in one message cannot exceed **50 MB**; exceeding either limit shows a corresponding message. Screenshots can be pasted directly into the chat. + Click the plus button at the lower left of the input box to choose files, or paste images directly. Supported formats include images, PDFs, text / Markdown / CSV / HTML, and Office documents (Word / Excel / PowerPoint), up to **20 MB** per file. HTML files are read as plain text and rendered in the sandbox — any scripts inside them are not executed. A single message can carry at most **9 attachments**, and the total size of all attachments in one message cannot exceed **50 MB**; exceeding either limit shows a corresponding message. Screenshots can be pasted directly into the chat. When you enter AI SRE from an incident, alert, monitor rule, or host page, the related object is embedded into the input box as a **reference capsule** — a small inline tag indicating the kind of object referenced — an incident, alert event, alert, monitor rule, host, or on-call analytics — that travels with the message so the agent can start its analysis from that object directly. Click the capsule to open the referenced object in a new tab, or click its close button to remove the reference before sending. A single message can carry multiple references. Besides objects carried in automatically from a related page, you can also type `@` directly in any session's input box to trigger an incident search dropdown (supporting fuzzy keyword search and a list of recent incidents); selecting one inserts the same kind of reference capsule — a standalone entry point available at any time. @@ -234,6 +236,8 @@ Forking is useful when you want to try another path from the same investigation You can fork only from a **completed** turn in a top-level session. If the source session is still running, the selected turn has not settled, or the target is a Subagent child session, AI SRE rejects the fork. +If the forked portion of the conversation dispatched any Subagent or A2A tasks, those dispatch chips are copied over to the new session along with their respective child sessions — opening one still shows the execution details, and it never points at an original task you don't have access to. But **copied-over dispatches always show as "Interrupted"** — even if that dispatch completed normally in the original session: the new session has no executor picking up that dispatch, so it can't be continued or replayed. If you need to rerun it, just start a fresh dispatch in the new session. + Forking clears temporary state that only belongs to an in-progress run, such as active-turn caches, pending mount state, frontend state that has not been persisted, and current-turn counters. Persisted history, tool calls, and reusable compaction state are retained; team and environment binding are written to the new session based on your choice in the fork dialog. The forked session has its own context, so later messages, compaction, and run results do not write back to the source session. ### Session Feedback diff --git a/en/changelog/changelog.mdx b/en/changelog/changelog.mdx index 56b7ac85..215d7d76 100644 --- a/en/changelog/changelog.mdx +++ b/en/changelog/changelog.mdx @@ -4,6 +4,39 @@ description: "This page documents important updates and feature releases for Fla keywords: ["Changelog", "Product Release", "Feature Updates", "Flashduty", "Version History"] --- + + +### Artifacts can now be shared with a public link + +The artifact gallery adds a **public link**. Sharing an artifact used to require the recipient to sign in to the same Flashduty account; now you can generate a sign-in-free link and send an investigation write-up or inspection report straight to a customer, an external partner, or a colleague who doesn't have an account yet. + +- The share panel offers two visibility modes, **Account only** and **Public link**; the default is still account-only +- A public link shows a **content snapshot** taken when the link was generated and does not sync automatically. When the artifact changes, click **Update snapshot** to sync it — the link itself stays the same +- **Revoke public link** at any time; the link stops working immediately +- Artifacts larger than 16 MiB cannot generate a public link + +Before generating, you're warned that anyone with the link can view the artifact and that the link may be forwarded further — don't share secrets, personal information, or unauthorized third-party content. + +Publishable artifact types are also no longer limited to HTML and Markdown: images, PDFs, data files such as CSV / JSON / YAML, common source files, and archives can all be published to the gallery. + +See [Artifacts](/en/ai-sre/artifacts). + +### ServiceMap (Beta) + +**ServiceMap** automatically builds a dependency topology among hosts, processes, containers, and workloads from the real network connections `monit-agent` observes through eBPF. It doesn't rely on manual configuration or a static architecture diagram — it shows who a machine is actually talking to right now. + +- Filter the topology canvas by resolution status (Confirmed / Candidate / Unresolved), adjust the hop range, and double-click a node to enter focus mode +- Node and dependency detail panels expose identity, runtime, resolution, and observation fields, so you can judge whether a dependency is trustworthy +- Unresolved endpoints are grouped by reason, with filtering and CSV export +- The ServiceMap host list filters by Agent version, Edge cluster, capture mode, and status +- Query info reports capture mode, evidence freshness, and truncation reasons, so you can tell whether the current topology is complete + +ServiceMap is in beta and relies on `monit-agent`'s eBPF observation — topology data appears only after the Agent supports and enables ServiceMap. + +See [ServiceMap](/en/monitors/targets/servicemap). + + + ### AI SRE Open to All Accounts diff --git a/en/monitors/quickstart/quickstart.mdx b/en/monitors/quickstart/quickstart.mdx index 784c1a91..db16cf01 100644 --- a/en/monitors/quickstart/quickstart.mdx +++ b/en/monitors/quickstart/quickstart.mdx @@ -79,7 +79,11 @@ There may be many alert rules. Monitors provides a tree-structured grouping for ![Data source selection](https://docs-cdn.flashcat.cloud/imges/mon/9971af45b4bc19bfe807898bf1bf10a0.png) -Monitors supports a single rule applying to multiple data sources with two binding methods: +First choose a **data source type**. Only types that **already have at least one configured data source** are listed here — types with none don't appear, so you can't end up picking a type with no data sources to query. When you're editing an existing rule, its current type always stays visible, even if all the data sources under that type have since been deleted. + +If the list is empty (showing "No data sources available"), your account hasn't configured any data sources yet — click **Go to Data Source Management** to create one first. If only the selected type has none, the page shows "The current data source type has no available data sources. Create one or switch type." If the type list fails to load, a **Reload** button appears. + +After choosing a type, Monitors supports a single rule applying to multiple data sources with two binding methods: - **Wildcard by name**: Match data sources by name using wildcards. `*` matches all data sources; `db-*` matches all data sources starting with `db-`. Stores name strings, so renaming a data source affects matching. - **Exact match by ID**: Select specific data sources from a dropdown by ID. Unaffected by data source renames. diff --git a/en/monitors/targets/servicemap.mdx b/en/monitors/targets/servicemap.mdx new file mode 100644 index 00000000..9d9af284 --- /dev/null +++ b/en/monitors/targets/servicemap.mdx @@ -0,0 +1,206 @@ +--- +title: "ServiceMap" +description: "A service dependency topology automatically generated from real-time eBPF connection evidence, so you can confirm who a host or service is actually communicating with right now" +keywords: ["ServiceMap", "service dependency topology", "eBPF", "dependency graph", "monitoring objects"] +sidebarTitle: "ServiceMap" +--- + + + **Beta**: ServiceMap is in beta — its behavior and interface may still change. It relies on `monit-agent`'s eBPF observation: if the Agent is too old, the runtime doesn't support it, or ServiceMap isn't enabled, the host shows as "Unsupported" or "Disabled" and has no topology data. + + +ServiceMap automatically builds a dependency topology among hosts, processes, containers, and workloads, based on the real network connections that `monit-agent` observes through eBPF. It doesn't depend on any manual configuration or static architecture diagram — it shows who this machine is actually communicating with right now, not who the documentation says it should be communicating with. + +**Entry point**: the monitoring object page (the "Topology" button on each row in the object list, or the "ServiceMap Hosts" button in the toolbar). + +## Overview + +Every dependency (edge) in the topology comes from a real connection the Agent observed: a source entity (a process, container, or workload) issued a `connect` to a target endpoint (`ip:port/protocol`). ServiceMap's resolver tries to match this target endpoint to a known listener within the same network scope, turning a "connection" into a "service dependency": + +- If the endpoint matches exactly one listener, the dependency is marked **Confirmed**. +- If the endpoint matches multiple possible listeners, it's marked **Candidate**, and you need to use context to determine the actual counterpart. +- If the endpoint doesn't match any listener, it's marked **Unresolved**, and by default it doesn't enter the topology canvas (this keeps noise such as external addresses and short-lived connections from obscuring real dependencies). + +During troubleshooting, use ServiceMap to quickly confirm who this host or service currently depends on and is depended on by, and to gauge the blast radius of a change or anomaly, without having to log in to the host and check connections one by one. When you click "AI Analysis" in the monitoring object list, if the host's ServiceMap topology is available and you have permission to view it, the system automatically includes a summary of the current topology as context for AI-SRE — you don't need to attach it manually. + + +Viewing ServiceMap requires the `MonitServiceMapVisit` permission. Without it, the topology drawer shows "ServiceMap Read permission is required to view the current topology", but the object list and host list themselves remain usable. + + +## How to open ServiceMap + +On the monitoring object page (`/monit/targets`), there are two entry points: + +- **The "Topology" button in the object list**: when a row meets all of the following conditions, a "Topology" link appears in the action column; clicking it opens the host's current topology directly. + - `host_id` exists and has a valid format; + - the object reports the `servicemap` capability with no error code; + - `graph_available` is true (a readable graph currently exists); + - the ServiceMap status is one of **Healthy**, **Degraded**, or **Stale**. +- **The "ServiceMap Hosts" button in the toolbar**: opens the account-wide ServiceMap host list (see "Host list" below), where you can filter by Agent version, Edge cluster, collection mode, and status before opening a specific host's topology; the same rule above applies. + +The topology drawer that opens contains two tabs: **Topology** (the visual canvas) and **Data Details** (query info + a dependency details table). The title bar shows whether the current graph is "live" or "stale", the collection mode, and the observation time. + +## Topology canvas + +### Resolution status filters + +Above the canvas is a row of buttons corresponding to dependency resolution status, each with a count badge: + +| Button | Meaning | +|---|---| +| **Confirmed** | Dependencies resolved to a single counterpart service. Click to toggle the visibility of confirmed dependency nodes/edges on the canvas. | +| **Candidate** | Dependencies with multiple possible counterparts that haven't been uniquely determined yet. Click to toggle visibility the same way. | +| **Unresolved** (red) | Clicking it doesn't toggle canvas visibility — it opens the "Unresolved Endpoint Groups" drawer instead (see below). Unresolved endpoints don't enter the canvas by default. The button is disabled when the count is 0. | + +If a dependency's resolution status is neither "Confirmed" nor "Candidate/Unresolved" (abnormal data where the backend returns a confirmed status but the candidate count isn't 1), an extra **Unknown N** label appears in the toolbar as a hint; these edges are rendered as gray dash-dot lines on the canvas. + +### Hop range and focus mode + +- When you're not in focus mode, the left side of the toolbar shows a "Range" selector with **1 hop / 2 hops / 3 hops**. Selecting a range triggers a new backend query — it's not a pure frontend filter. The more hops, the more nodes and edges are loaded, and the more likely the query hits its cap. A single query returns at most 100 nodes and 200 edges by default. +- **Double-click any node** to enter focus mode: the canvas keeps only the local dependency graph expanded upstream and downstream from that node. Entering focus mode always resets the upstream hop count to 1; the downstream hop count keeps the value you last set (starting at 1 hop). Upstream and downstream hop counts can each be adjusted independently from 0 to 3. Upstream edges represent callers that depend on you; downstream edges represent what you depend on. +- You can also use the search box in the top-right corner of the canvas (search by name, ID, container, or workload) to locate and focus a node directly. +- Click "Exit Focus" or press Esc to exit focus mode and return to the overall topology within the current hop range. + +### Canvas controls and interaction + +- The bottom-left corner provides **zoom in / zoom out**, the current zoom percentage, and a toggle to **show/hide the minimap**. +- **Fit to canvas** scales the entire graph to the visible area; **Re-layout** rearranges node positions using a new random seed (useful for separating heavily overlapping nodes). +- When you hover over a node, the nodes/edges directly connected to it stay highlighted while the rest of the graph fades. Edges **originating from** that node (its downstream dependencies) additionally show metric labels, such as `↑ 12.3 KB/s` / `↓ 4.1 KB/s` (send/receive rate), `✕ 3` (connection failures within the observation window), and `↻ 2` (retransmission count), or `● 5` (current active connection count) when no meaningful rate data is available. Rates are shown only when the window's metrics are complete. +- Clicking a node or edge opens a details panel on the right (see below); the panel width is resizable by dragging. Clicking an empty area of the canvas clears the current selection. +- A set of stat cards is always visible in the top-left corner of the canvas: **Services** (node count), **Confirmed Dependencies**, and **Dependencies Checked** (the total number of dependencies actually examined by this query, including confirmed, candidate, and unresolved). +- When the query is truncated (hits the node/edge cap), a banner appears above the canvas reading "Checked N dependencies, reached the query limit", with a "Focus Service" button that lets you search for and focus directly on the service you care about, narrowing the scope for another look. + +Node shape and edge color are the first-level signals for judging dependency trustworthiness: + +| Visual | Meaning | +|---|---| +| Circle node | A known entity (process / container / workload) | +| Circle node + question mark icon | Candidate node: one possible counterpart entity for a "candidate" dependency | +| Diamond node | A target endpoint not yet merged into an entity: an endpoint node expanded from a candidate dependency, or an unresolved endpoint temporarily located through the "Unresolved Endpoints" panel | +| Green solid line | Confirmed dependency | +| Orange dashed line (animated) | Candidate dependency; connects from the endpoint diamond node to each of multiple candidate entities | +| Red dash-dot line | Unresolved dependency; appears only temporarily when you actively "Locate Source" | +| Gray dash-dot line | Unknown (data marked confirmed by the backend but with an abnormal candidate count) | + +## Node details + +Clicking an entity or candidate node opens a details panel on the right, showing information in three groups: + +| Group | Field | Description | +|---|---|---| +| Identity | Display Name | The name shown for this entity on the page | +| | Type | The entity type (e.g., `process_workload`, `container`) | +| | Entity ID | The entity's unique identifier | +| | Host ID | The identifier of the host the entity resides on | +| Runtime | Executable | The executable file name for this entity | +| | Systemd Unit | The systemd service unit for this entity (if any) | +| | Container | The container name (if the entity runs inside a container) | +| | Image | The image repository and version, in `repository:version` format | +| | Workload | The Kubernetes namespace/workload name, in `namespace/workload_name` format | +| | Instance Count | The number of instances merged into this entity | +| Observation | First Observed | When this entity was first observed | +| | Last Observed | When this entity was most recently observed | +| | Entity Identity | The raw identity (JSON) returned by the backend, for precise troubleshooting | + +Hovering over the right side of any row reveals a copy button so you can copy the field's raw value directly. There's also a "View upstream/downstream only" button at the top of the panel that lets you enter focus mode on this node directly from the details panel. + +## Dependency details + +Clicking an edge (or a candidate/endpoint node) shows this dependency's information in three groups in the details panel: + +| Group | Field | Description | +|---|---|---| +| Identity | Edge ID | The dependency's unique identifier | +| | Source Entity ID | The ID of the source entity that initiated the connection | +| | Source NetNS ID | The network namespace ID of the source entity | +| | Target Endpoint | The target endpoint, in `ip:port/protocol` format | +| | Evidence | How this dependency was observed (free text, e.g., `connect`, meaning the connection was observed through a connect system call) | +| Resolution | Resolution Status | The raw resolution status, such as `resolved` / `ambiguous` / `unresolved` | +| | Resolution Reason | The reason returned by the resolver | +| | Candidate Count | The number of possible counterpart services the resolver found for this endpoint; the dependency is marked as candidate when this is greater than 1 | +| | Candidates Truncated | "Yes" when the candidate list exceeds the return limit, meaning only a partial candidate list was returned | +| | Match Type | How the candidate was matched (e.g., `exact` for exact match, `wildcard` for wildcard match) | +| | Confidence | The confidence score for this candidate | +| | Listener ID | The identifier of the candidate counterpart's actual listener | +| Observation | First Observed | When this dependency was first observed | +| | Last Observed | When this dependency was most recently observed | + +To judge whether a dependency is trustworthy, look first at **Resolution Status** and **Candidate Count**: a dependency is judged confirmed only when the candidate count is 1; when the candidate count is greater than 1, it's a candidate dependency, and you need to use **Match Type** and **Confidence** together to determine which candidate is more likely to be the real counterpart. + +## Data Details tab + +The "Data Details" tab in the topology drawer provides a table view that doesn't depend on canvas interaction; the tab itself shows a count badge for confirmed dependencies, and has two parts: + +**Query Info**: shows this query's Host ID, Network Scope, observation time, direction and depth, hosts covered, and more (see the field descriptions in the next section, "How to judge whether a topology is trustworthy"). + +**Dependency Details**: lists only confirmed and candidate dependencies (not unresolved ones); each row includes the source, target, protocol/port, confidence (High / Medium / Low), and last observed time. Confidence is graded by the highest confidence value among the dependency's candidates: 0.85 or above is High, 0.5 or above is Medium, and the rest is Low. + +## Unresolved endpoints + +Unresolved endpoints are dependencies whose target endpoint doesn't match any known listener. They don't enter the topology canvas by default; instead, they're shown grouped by reason in a separate "Unresolved Endpoint Groups" drawer. + +To open it, click the "Unresolved" filter button at the top of the canvas. The first time you open it, if the current topology query used summary mode (group counts only, no specific endpoint list), a supplementary query is automatically issued to load the full list. + +Known group reasons and their meanings: + +| Reason | Description | +|---|---| +| `no_current_listener` | No current listener was found | +| `listener_address_family_unknown` | The listener's address family is uncertain | +| `invalid_endpoint` | The endpoint information is invalid | + +When the backend returns a reason without preset copy, it's shown with a generic "Unresolved" label, and the raw reason string is still displayed alongside it. + +Within a group, you can: + +- Use the search box in the top-left corner to filter records within the current group by target endpoint or source service; +- Click the "Locate Source" icon on a row to close the drawer and temporarily highlight this unresolved dependency's source entity and target endpoint on the canvas (this corresponds to the "Locating unresolved endpoint" banner on the canvas; click "Exit Locate" or press Esc to exit); +- Click "Export CSV" in the top-right corner to export all unresolved endpoints (not limited to the currently selected group); the CSV columns, in order, are: **Target Endpoint**, **Source Service**, **Source Entity ID**, **Resolution Reason**. + +## Host list + +Opened from the "ServiceMap Hosts" button in the toolbar, this shows all hosts under the account that report the ServiceMap capability, independent of any single host's topology view. + +**Filters**: Agent version (multi-value input, confirm with Enter, up to 20), Edge cluster (multi-value input, confirm with Enter, up to 20), collection mode (multi-select: eBPF / Polling / Unknown). + +**Status distribution**: a set of stat cards showing the host count for each of the seven statuses — "Healthy / Degraded / Stale / Initializing / Disabled / Unsupported / No Data" — in a fixed order. Click a card to filter the list below by that status (click again, or click "Clear Status Filter", to cancel). Above the cards is scan coverage info: "Scanned N (cap M), matched X, classified Y successfully, Z failed", along with the time the counts were generated. If this count is a bounded scan (it hit the scan cap) or some hosts' status failed to load, the page shows "Represents this bounded scan only" or "Counts incomplete" respectively. + +What each status means: + +| Status | Meaning | +|---|---| +| Healthy | The current topology is fresh and usable for analysis | +| Degraded | Collection is still running, but the current evidence is incomplete or not authoritative | +| Stale | The last trustworthy topology is past the freshness window | +| Initializing | The Agent is generating its first usable snapshot | +| Disabled | The Agent hasn't enabled ServiceMap | +| Unsupported | The current Agent or runtime environment doesn't support ServiceMap | +| No Data | The capability was discovered, but no usable current topology exists yet | + + +The monitoring object list and host list may also show two additional display states: **Not Reported** (the Agent hasn't reported the ServiceMap capability, which can't be directly interpreted as unsupported) and **Status Unavailable** (the ServiceMap status can't be read temporarily, but the monitoring object itself remains usable). Neither of these is a formal ServiceMap status value — they're just fallback displays for the status column itself. + + +**Host list**: lists Host ID, Agent version, Edge cluster (the name of the `monitedge` cluster the host's Agent connects through), ServiceMap status, collection mode, and topology observation time. Rows that meet the conditions in "How to open ServiceMap" above show a "Topology" action button that opens the host's topology directly. + +The list uses cursor-based pagination and loads on demand, so the exact total is unknown until all matching results have loaded: the bottom shows either "N hosts loaded" (more can be loaded) or "N hosts total" (this is the complete result set). If this browse hits the scan boundary or some hosts' status is unavailable, a banner above the list reads "Host list reached the scan boundary or some statuses are unavailable — keep paging or narrow the filters". + +## How to judge whether a topology is trustworthy + +A topology is generated from connection evidence within a recent observation window — it's not a live snapshot, and it isn't guaranteed to be complete. After opening any host's topology, you can gauge how trustworthy it is by looking at the "Query Info" section of the "Data Details" tab, together with the topology drawer's title bar and the banner above the canvas: + +| Field | Description | +|---|---| +| Network Scope | The network scope identifier; endpoint resolution only happens within the same scope. Scopes are automatically divided by Edge cluster by default, with no manual configuration needed. | +| Collection Mode | The collection method that produced this topology's evidence, e.g., `ebpf` kernel observation; it can also be `polling` or `hybrid`. | +| Freshness | `fresh` means the evidence is within the observation window and can be treated as live; any other status means this graph is stale — the drawer's title bar shows a "Stale" label with an added note: "Use the observation time and coverage together to judge this; don't treat a stale graph as a live dependency." | +| Hosts Covered | The number of hosts actually loaded by this topology query. | +| Network Inventory | The state of the listening-endpoint inventory projection, which affects the completeness of endpoint resolution (e.g., whether this projection is fully available). | +| Kubernetes Enrichment | The state of Kubernetes metadata enrichment, which affects whether container and workload information is complete. | +| Query Limits | The list of truncation reasons triggered by this query — **its presence alone means this graph is incomplete** (e.g., it hit the node or edge cap). | + + +When the topology has degraded or incomplete evidence (`degraded_hosts` is greater than 0, or a degradation reason exists), the drawer shows an added note: "The current topology includes degraded or incomplete evidence." When the query itself times out or is rate-limited, it shows "Please retry later or reduce the depth" and "Please retry later" respectively. None of these are errors — they're reminders that the dependencies you're seeing right now may be incomplete; consider narrowing the hop range or retrying later. + + +In short: if **Freshness isn't `fresh`**, the **Query Limits list isn't empty**, or a **degraded/incomplete evidence notice appears**, this topology can't be treated as a live, complete set of dependencies for drawing conclusions directly — confirm further using the observation time. diff --git a/en/rum/error-tracking/error-aggregation.mdx b/en/rum/error-tracking/error-aggregation.mdx index 1ba7af90..c13d78aa 100644 --- a/en/rum/error-tracking/error-aggregation.mdx +++ b/en/rum/error-tracking/error-aggregation.mdx @@ -147,6 +147,8 @@ Custom fingerprints take priority over default fingerprints. In the Flashduty platform, navigate to "Error Tracking" to view the grouped Issue list. +You can also jump there directly from the application list: the **Issue** count on an application card is clickable, and clicking it opens that application's error tracking list scoped to match the card — the last 24 hours, status "all" — while clearing any filters left over from a previous visit, so the list count matches the count on the card. + Each Issue contains: | Content | Description | diff --git a/zh/ai-sre/artifacts.mdx b/zh/ai-sre/artifacts.mdx index fd780b22..01b9ff59 100644 --- a/zh/ai-sre/artifacts.mdx +++ b/zh/ai-sre/artifacts.mdx @@ -1,7 +1,7 @@ --- title: 产物 -description: 产物库集中呈现 AI SRE 会话中用 present_files 工具产出、再经 publish_artifact 工具发布的网页与报告（例如 /insight 报告），支持搜索、按范围筛选与修改范围、重命名、分享、下载和删除。 -keywords: ["AI SRE", "产物", "Artifacts", "present_files", "publish_artifact", "insight 报告", "产物库"] +description: 产物库集中呈现 AI SRE 会话中用 present_files 工具产出、再经 publish_artifact 工具发布的文件（网页、报告、图片、PDF、源码与数据文件等，例如 /insight 报告），支持搜索、按范围筛选与修改范围、重命名、分享（账户内或公开链接）、下载和删除。 +keywords: ["AI SRE", "产物", "Artifacts", "present_files", "publish_artifact", "insight 报告", "产物库", "公开链接", "分享"] sidebarTitle: 产物 --- @@ -13,7 +13,18 @@ sidebarTitle: 产物 --- -产物（Artifact）是 AI SRE 在会话中用 `present_files` 工具产出、再经 `publish_artifact` 工具发布到产物库的文件——通常是一份自包含的 HTML 报告或页面。例如在会话里输入 `/insight` 生成的运营洞察报告，就是一种产物。 +产物（Artifact）是 AI SRE 在会话中用 `present_files` 工具产出、再经 `publish_artifact` 工具发布到产物库的文件。最典型的是一份自包含的 HTML 报告或页面——例如在会话里输入 `/insight` 生成的运营洞察报告——但可发布的类型不止于此： + +| 类别 | 常见扩展名 | +|---|---| +| 网页与文档 | `.html` `.htm` `.md` `.markdown` `.txt` `.log` | +| 数据与配置 | `.csv` `.tsv` `.json` `.yaml` `.yml` `.xml` `.toml` `.ini` | +| 图片 | `.png` `.jpg` `.jpeg` `.gif` `.svg` `.webp` | +| PDF | `.pdf` | +| 源码 | `.py` `.go` `.js` `.mjs` `.ts` `.jsx` `.tsx` `.java` `.c` `.h` `.cpp` `.cs` `.rb` `.rs` `.php` `.sh` `.sql` `.kt` `.swift` `.scala` `.css` `.vue` `.svelte` `.proto` `.tf` `.hcl` 等 | +| 压缩包 | `.zip` `.tar` `.gz` `.tgz` | + +不在可发布范围内的文件，会话中不会出现「发布到产物库」按钮。 发布后的产物初始继承来源会话的作用域：来自个人会话的产物归创建者「个人」所有；来自绑定了团队的会话的产物归该「团队」所有，可分享给账户内的其它成员查看。拥有编辑权限时，之后还可以修改产物范围。 @@ -36,8 +47,8 @@ sidebarTitle: 产物 每张卡片展示： -- 顶部预览区的类型图标：内容类型或文件名为 HTML 时显示代码图标，其余显示文档图标； -- 标题（最长两行，超出省略）； +- 顶部预览区的类型图标：按文件扩展名与内容类型区分，图片、PDF、HTML、Markdown、表格（CSV / TSV）、JSON、压缩包、源码各有专属图标，无法识别时回退为通用文件图标； +- 标题（单行显示，超出省略；鼠标悬停可看到完整标题）； - 「编辑于 …」相对时间——刚刚 / N 分钟前 / N 小时前 / N 天前，超过 30 天则显示具体日期； - 右下角的作用域徽标：团队产物显示团队名称（绿色高亮），个人产物显示创建者姓名（灰色）。 @@ -77,7 +88,7 @@ Agent 会先向你确认目标读者、内容/数据来源、交互与视觉风 - **标题**：对有编辑权限的产物可直接点击标题进行行内编辑（无需跳转到独立表单），按 Enter 保存、Esc 取消； - **创建者**：标题下方显示「〈创建者〉创建的产物」； -- **分享**：复制该产物详情页的链接； +- **分享**：打开分享面板，可选择「仅账户内」或「公开链接」两种可见范围，详见下文 [分享产物](#分享产物)； - **删除**：仅在你有编辑权限时显示，删除前需二次确认； - **更多操作**：只有以下至少一项可用时才会出现这个菜单—— - **打开会话**：仅当产物的来源会话你仍有权限访问时出现，点击跳转到该会话的完整对话（消息、工具调用、产物历史）； @@ -86,6 +97,37 @@ Agent 会先向你确认目标读者、内容/数据来源、交互与视觉风 正文区域按产物的实际内容类型渲染（例如 HTML 报告会直接内联展示为页面）。 +## 分享产物 + +--- + +详情页工具栏的 **分享** 按钮会打开分享面板。面板顶部的 **管理权限** 列出谁可以管理这个产物的分享（创建者标记为「所有者」，团队产物还会列出团队成员）；下方的 **可见权限** 提供两种模式： + +| 模式 | 谁能打开 | 内容 | +|---|---|---| +| 仅账户内 | 登录同一账户的成员 | 账号内成员登录后可查看，内容**始终为最新版本** | +| 公开链接 | 任何拿到链接的人，**无需登录** | 展示的是生成链接那一刻的**内容快照**，产物更新后不会自动同步 | + +### 公开链接 + +选择 **公开链接** 后，面板会先展示一段内容预览和风险提示，再由你点击 **生成公开链接** 才真正生效： + + +生成公开链接后，任何拿到链接的人都可以查看此产物，链接也可能被继续转发。请勿分享密钥、个人信息或未经授权的第三方内容。 + + +生成成功后链接会自动复制到剪贴板（提示「公开链接已生成，已复制到剪贴板」）。公开链接的形式为 `https://<控制台域名>/share/artifact/<产物 ID>`——它以产物自身的 ID 为标识，不携带令牌；匿名访问完全由 CDN 提供，不经过任何需要登录的接口。 + +| 操作 | 说明 | +|---|---| +| 生成公开链接 | 把产物当前内容复制为一份公开快照并启用链接 | +| 更新快照 | 仅当检测到产物内容已更新时出现（提示「识别到产物内容有更新，可更新快照以同步最新内容」）。点击后用最新内容覆盖快照，**链接保持不变** | +| 撤销公开链接 | 关闭公开访问，链接立即失效 | + + +超过 **16 MiB** 的产物无法生成公开链接，会提示该产物体积超限。此时仍可使用「仅账户内」模式分享。 + + ## 权限 --- diff --git a/zh/ai-sre/environments.mdx b/zh/ai-sre/environments.mdx index 4c231715..f5a41c02 100644 --- a/zh/ai-sre/environments.mdx +++ b/zh/ai-sre/environments.mdx @@ -254,8 +254,20 @@ Runner 启动后会持续发送心跳。列表状态含义如下： |---|---| | 等待中（pending） | Environment 已创建，但 Runner 从未连接过。 | | 在线（online） | Runner 当前已连接，心跳正常，可承接任务。 | +| 性能下降（degraded） | Runner 仍然连接着、心跳也正常，但它的执行器跟不上——任务排队积压或迟迟不返回。**可以继续使用，只是响应会变慢**。 | | 离线（offline） | Runner 曾连接过，但当前心跳已断。 | +`degraded` 是一个**实时计算**的状态，不会被持久化：每次读取时根据当前信号重新判定，因此不需要手动清除。它由两类信号触发—— + +- 较新版本的 Runner 会在心跳里上报自身执行器的健康探针与积压任务数，据此直接判定； +- 不上报这些指标的旧版本 Runner，则采用回退规则：针对同一个 Environment **连续 3 次**任务超时即标记为性能下降（只有超过 20 秒的超时才计数，避免调用方自己设置的短超时被误判）。 + +恢复同样是自动的：新版本 Runner 的心跳恢复正常（探针通过且无积压）即回到 `在线`；旧版本 Runner 只要有任意一次任务成功就会重置计数，或在持续安静 30 分钟后自动恢复。 + + +看到 `性能下降` 时，先检查 Runner 所在主机的 CPU、内存与磁盘负载，以及是否有长时间占用执行器的任务。它不阻断会话，但持续处于该状态说明这台主机已经吃不消当前的任务量。 + + Runner 版本由服务端在心跳中比对。发现新版本时，Runner 会收到升级通知并自行下载、校验、替换。手动重跑安装命令也可升级。 卸载命令也在接入指引里，按安装方式不同： @@ -380,7 +392,7 @@ permission: |---|---| | **自动** | 新会话默认值。优先使用当前成员可用的在线 Runner，否则回退到云端 Sandbox。 | | **云端 Sandbox · 默认** | 强制使用系统托管的云端 Sandbox，忽略自托管 Runner。 | -| **自托管 Environment** | 列出当前成员可使用的 Runner。离线、从未连接或团队权限不匹配的 Runner 不可选。 | +| **自托管 Environment** | 列出当前成员可使用的 Runner。离线、从未连接或团队权限不匹配的 Runner 不可选；处于 **性能下降（degraded）** 的 Runner **仍然可选**，选中后会提示「性能下降 — 可继续使用，响应可能变慢」。 | 环境选择对一条会话是一次性锁定的：会话首次发送消息时确定的运行环境会被记录，后续轮次始终沿用，不会因为您之后切换选择器而改变。要换环境，请新建会话。 diff --git a/zh/ai-sre/insight.mdx b/zh/ai-sre/insight.mdx index 00210b6a..e2575044 100644 --- a/zh/ai-sre/insight.mdx +++ b/zh/ai-sre/insight.mdx @@ -58,7 +58,7 @@ sidebarTitle: 使用洞察 - AI SRE 先列出范围内近 30 天的会话（默认最多 200 个），覆盖**全部四种入口**——网页（web）、IM、API、定时（scheduled）；IM 是 AI SRE 的主要入口之一，因此 IM 触发的会话也会一并纳入分析。导出完整记录后，保留**有真实信号**的会话：**用户消息 ≥ 2 轮，或工具调用 ≥ 3 次**（二者满足其一即可，对应 `INSIGHT_MIN_MSGS` / `INSIGHT_MIN_CALLS`）。「工具调用」这一条很关键——它让那些由告警或定时触发的自主会话（可能没有任何人工轮次，却做了十几次工具调用的真实排查）也能进入报告，而不会被「只看人工轮数」的旧规则误删。报告还会在量化总览里给出一行**会话来源**（`entry_mix`），让您看到这些会话分别来自哪些入口。 + AI SRE 先列出范围内近 30 天的会话（默认最多 200 个），覆盖**全部四种入口**——网页（web）、IM、API、自动化（automation）；IM 是 AI SRE 的主要入口之一，因此 IM 触发的会话也会一并纳入分析。导出完整记录后，保留**有真实信号**的会话：**用户消息 ≥ 2 轮，或工具调用 ≥ 3 次**（二者满足其一即可，对应 `INSIGHT_MIN_MSGS` / `INSIGHT_MIN_CALLS`）。「工具调用」这一条很关键——它让那些由告警或定时触发的自主会话（可能没有任何人工轮次，却做了十几次工具调用的真实排查）也能进入报告，而不会被「只看人工轮数」的旧规则误删。报告还会在量化总览里给出一行**会话来源**（`entry_mix`），让您看到这些会话分别来自哪些入口。 报告的量化总览——会话数、您的轮数、工具调用数、平均轮数、按天的活跃度、工具与 Skill 分布、会话来源、模型分布、结果分布——由程序在所有会话上确定性地统计得出，而非由模型估计，因此可靠且始终存在，即便没发现任何摩擦也照常呈现。 @@ -91,7 +91,7 @@ sidebarTitle: 使用洞察 | 活跃度 | 按天的会话活跃柱状图，标出起止日期 | | 工具分布 | Agent 最常依赖的工具排行（取前 ~6 项） | | Skill 分布 | 会话中调用过的 Skill 排行；若没有调用过任何 Skill，则显示「未调用任何 Skill」 | -| 会话来源 | 这些会话分别来自哪些入口，形如 `web（60）· IM（25）· scheduled（5）`（`entry_mix`） | +| 会话来源 | 这些会话分别来自哪些入口，形如 `web（60）· IM（25）· automation（5）`（`entry_mix`） | | 模型分布 | 各模型各被多少个会话使用，形如 `模型名（N 个会话）` | | 结果分布 | 完成 / 未完成 / 出错的会话数（某项为 0 时省略） | diff --git a/zh/ai-sre/knowledge.mdx b/zh/ai-sre/knowledge.mdx index dc705a2e..1b82a7b6 100644 --- a/zh/ai-sre/knowledge.mdx +++ b/zh/ai-sre/knowledge.mdx @@ -60,7 +60,7 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 | 约束 | 取值 | 说明 | | --- | --- | --- | -| 允许的扩展名 | `.md` `.yaml` `.yml` `.json` `.txt` `.sh` | 其它扩展名会被拒绝 | +| 文件内容 | 纯文本（UTF-8） | 按**内容**校验而非扩展名：文件不含 NUL 字节且能按 UTF-8 解码即可保存。因此 `.md` `.yaml` `.json` `.txt` `.sh` 之外的 `.py` `.sql`，乃至没有扩展名的 `Dockerfile` 都可以上传；反之，扩展名是 `.txt` 但内容为二进制的文件会被拒绝 | | 单文件上限 | 1 MiB | 超出无法保存 | | 单个 Pack 上限 | 5 MiB | 控制台用量条按此额度显示 | | 文件数量上限 | 100 | 达到上限后无法新增文件 | @@ -88,7 +88,7 @@ Agent 读取 `DUTY.md` 后，会根据当前故障判断需要展开哪些 `@引 -**文档提炼入库**：知识文件仅支持上表列出的纯文本格式。如果上传 PDF / Word / Excel / PPT / HTML 等无法直接入库的文档，控制台会提示该格式无法被 AI 直接使用，并提供 **转到对话分析** 入口。点击后系统会新开一个 AI SRE 会话，把该文档作为附件带入；Agent 阅读文档后将其提炼为 Markdown 知识文件，经您确认后再保存进当前知识库。 +**文档提炼入库**：知识文件只接受纯文本内容（见上表）。如果上传 `.pdf`、`.docx`、`.xlsx`、`.pptx`、`.html`、`.htm` 这类无法直接入库的文档，控制台会提示该格式无法被 AI 直接使用，并提供 **转到对话分析** 入口。点击后系统会新开一个 AI SRE 会话，把该文档作为附件带入；Agent 阅读文档后将其提炼为 Markdown 知识文件，经您确认后再保存进当前知识库。旧版 Office 二进制格式（`.doc`、`.xls`、`.ppt`）不在转换范围内，会被当作二进制文件直接拒绝——请先另存为 `.docx` / `.xlsx` / `.pptx` 再上传。 **引用一致性检查**：保存文件时，如果其中的 `@引用` 指向一个 Pack 内不存在的文件，会给出非阻断的「引用未解析」警告（不影响保存）。删除一个仍被其它文件引用的文件时，会先提示「仍被引用」冲突，您可以选择 **强制删除**。 diff --git a/zh/ai-sre/sessions.mdx b/zh/ai-sre/sessions.mdx index f7953594..43b9b4b4 100644 --- a/zh/ai-sre/sessions.mdx +++ b/zh/ai-sre/sessions.mdx @@ -69,14 +69,16 @@ sidebarTitle: 控制台 |---|---| | 谁能分享 | 对会话有管理权限的成员——个人会话的创建者，或团队会话的创建者 / 账户 Owner / 管理员 / 团队成员 | | 谁能打开 | 持有链接、且登录了**同一账户**的成员；链接不跨账户，也不支持匿名访问 | -| 持链接者看到什么 | 会话以**只读**模式打开，对话区提示「这是一个只读分享会话」：可查看完整上下文（消息、工具调用、产物），但输入框被只读提示替换，不能继续对话或修改原会话 | +| 持链接者看到什么 | 会话以**只读**模式打开，对话区提示「这是一个只读分享会话」：可查看完整上下文（消息、工具调用、产物），也可以点开 Subagent 派发卡片查看子会话的执行详情（同样只读）；但输入框被只读提示替换，不能继续对话或修改原会话 | | 如何继续排查 | 持链接者可点击 **Fork 为新会话**，把会话派生为自己的新会话后继续处理 | | 如何撤销 | 分享开启后头部出现 **取消分享** 按钮，点击后链接立即失效（提示「分享已取消」）；之后重新开启分享会生成新链接，旧链接不会恢复可用 | 分享主要改变**个人会话**的可见性：团队会话本来就允许同账户成员凭会话 ID 读取（见上表），而个人会话默认只有创建者可见，分享链接是同账户其他成员打开它的唯一方式。 -隐身（incognito）会话与 Subagent 子会话不支持分享。 +隐身（incognito）会话不支持分享。 + +Subagent / A2A 子会话本身也不能单独开启分享——分享只能在**根会话**上开启。但当你分享了根会话后，持链接者在只读视图里点开 Subagent 派发卡片时，可以一并只读查看对应的子会话执行详情；子会话是纯查看的，不提供 **Fork 为新会话**。撤销根会话的分享后，子会话的访问同时失效。 ### 单条会话操作 @@ -117,7 +119,7 @@ sidebarTitle: 控制台 - 点击输入框左下角的加号按钮选择文件，或直接粘贴图片。支持图片、PDF、文本 / Markdown / CSV，以及 Office 文档（Word / Excel / PowerPoint），单个文件最大 **20MB**。单条消息最多上传 **9 个文件**，且全部附件总大小不超过 **50MB**；超出文件数或总大小上限时会分别给出提示。截图可直接在对话中粘贴。 + 点击输入框左下角的加号按钮选择文件，或直接粘贴图片。支持图片、PDF、文本 / Markdown / CSV / HTML，以及 Office 文档（Word / Excel / PowerPoint），单个文件最大 **20MB**。HTML 文件按纯文本读取，并在沙箱中渲染，不会执行其中的脚本。单条消息最多上传 **9 个文件**，且全部附件总大小不超过 **50MB**；超出文件数或总大小上限时会分别给出提示。截图可直接在对话中粘贴。 从故障、告警、监控规则或主机等页面进入 AI SRE 时，相关对象会作为**引用胶囊**自动嵌入输入框——它是一枚内联的小标签，标明所引用对象的类型——故障、告警事件、告警、监控规则、主机或告警分析——并随消息一起发送给 Agent，让它直接基于该对象开始分析。点击胶囊可在新标签页打开对应对象；点击胶囊上的关闭按钮即可在发送前移除引用。一条消息可携带多个引用。除了从相关页面自动携带引用外，也可以在任意会话的输入框里直接输入 `@` 触发故障搜索下拉（支持关键词模糊匹配与近期故障列表），选中后插入与自动携带相同的引用胶囊——这是一个随时可用的独立引用入口。 @@ -234,6 +236,8 @@ Fork 适合在同一段排查上下文上尝试另一条路线：新会话保留 只能从**已经完成**的主会话回合 Fork。源会话仍在运行、所选回合尚未完成，或目标是 Subagent 子会话时，系统会拒绝 Fork。 +如果被 Fork 的这段对话里派发过 Subagent 或 A2A 任务，那些派发卡片会连同各自的子会话一起复制到新会话下，点开仍能查看执行详情，不会指向你无权访问的原始任务。但**复制过来的派发一律显示为「已中断」**——即使原会话里那次派发早已正常完成也一样：新会话没有承接该派发的执行者，无法继续或重放它。需要重跑时，在新会话里重新发起一次派发即可。 + Fork 会话会清理只属于运行中的临时状态，例如当前回合缓存、待挂载状态、未持久化的前端状态与本轮计数；已经持久化在历史中的消息、工具调用、可复用的压缩状态会保留，团队与环境绑定则按您在派生对话框中的选择写入新会话。Fork 后的新会话拥有独立的上下文，之后的消息、压缩与运行结果都不会写回原会话。 ### 会话反馈 diff --git a/zh/changelog/changelog.mdx b/zh/changelog/changelog.mdx index c91235c3..b989946a 100644 --- a/zh/changelog/changelog.mdx +++ b/zh/changelog/changelog.mdx @@ -4,6 +4,39 @@ description: "本页面记录 Flashduty 产品的重要更新和功能发布" keywords: ["更新日志", "产品发布", "功能更新", "Flashduty", "版本记录"] --- + + +### 产物支持公开链接 + +产物库新增**公开链接**。过去分享一份产物，对方必须登录同一个 Flashduty 账户；现在可以生成一条免登录的链接，把排障结论或巡检报告直接发给客户、外部协作方，或还没有账户的同事。 + +- 分享面板提供 **仅账户内** 与 **公开链接** 两种可见范围，默认仍是仅账户内 +- 公开链接展示的是生成那一刻的**内容快照**，产物更新后不会自动同步；检测到内容有变化时可点击 **更新快照** 同步，链接保持不变 +- 随时可 **撤销公开链接**，撤销后链接立即失效 +- 超过 16 MiB 的产物不支持生成公开链接 + +生成前会提示风险：任何拿到链接的人都可以查看，链接也可能被继续转发，请勿分享密钥、个人信息或未经授权的第三方内容。 + +同时，可发布为产物的文件类型不再限于 HTML 与 Markdown——图片、PDF，CSV / JSON / YAML 等数据文件，常见源码文件和压缩包都可以发布到产物库。 + +详见 [产物](/zh/ai-sre/artifacts)。 + +### ServiceMap 服务地图（Beta） + +**ServiceMap** 根据 `monit-agent` 通过 eBPF 观测到的真实网络连接，自动构建主机、进程、容器与工作负载之间的依赖拓扑。它不依赖手工配置或静态架构图，展示的是此刻这台机器实际在和谁通信。 + +- 拓扑画布支持按解析状态（已确认 / 候选 / 未解析）筛选、调整跳数范围，双击节点进入聚焦模式 +- 节点与依赖详情面板给出身份、运行时、解析与观测字段，可据此判断一条依赖是否可信 +- 未解析端点按原因分组，支持过滤与导出 CSV +- ServiceMap 主机列表可按 Agent 版本、Edge 集群、采集模式与状态筛选 +- 查询信息给出采集模式、证据新鲜度与截断原因，用于判断当前拓扑是否完整可信 + +ServiceMap 处于 Beta 阶段，依赖 `monit-agent` 的 eBPF 观测能力，需要 Agent 支持并启用后才会有拓扑数据。 + +详见 [ServiceMap](/zh/monitors/targets/servicemap)。 + + + ### AI SRE 全量开放公测 diff --git a/zh/monitors/quickstart/quickstart.mdx b/zh/monitors/quickstart/quickstart.mdx index 5d368daf..1d370dd4 100644 --- a/zh/monitors/quickstart/quickstart.mdx +++ b/zh/monitors/quickstart/quickstart.mdx @@ -80,7 +80,11 @@ keywords: ["入门指南", "monitedge", "数据源", "告警规则", "快速开 ![数据源选择](https://docs-cdn.flashcat.cloud/imges/mon/9971af45b4bc19bfe807898bf1bf10a0.png) -Monitors 支持一个规则生效到多个数据源，提供两种绑定方式： +先选择 **数据源类型**。这里只会列出**已经配置过至少一个数据源**的类型——没有配置过的类型不会出现，避免你选中一个查不到任何数据源的类型。编辑一条已有规则时，它当前使用的类型始终可见，即使该类型下的数据源后来被删光了。 + +如果列表为空（提示「暂无可用数据源」），说明当前账户还没有配置任何数据源，可以点击 **前往数据源管理页面** 先创建；如果只是当前选中的类型没有可用数据源，页面会提示「当前数据源类型暂无可用数据源，请先创建数据源或切换类型」。类型列表加载失败时会显示 **重新加载** 按钮。 + +选定类型后，Monitors 支持一个规则生效到多个数据源，提供两种绑定方式： - **名称通配**：通过通配符匹配数据源名称。`*` 匹配所有数据源，`db-*` 匹配所有以 `db-` 开头的数据源。存储的是名称字符串，数据源改名会影响匹配。 - **精确匹配**：从下拉列表中按 ID 选择具体数据源，不受数据源改名影响。 diff --git a/zh/monitors/targets/servicemap.mdx b/zh/monitors/targets/servicemap.mdx new file mode 100644 index 00000000..432c7680 --- /dev/null +++ b/zh/monitors/targets/servicemap.mdx @@ -0,0 +1,206 @@ +--- +title: "ServiceMap（服务地图）" +description: "基于 eBPF 实时连接证据自动生成的服务依赖拓扑，帮你确认某台主机或服务当前真实在和谁通信" +keywords: ["ServiceMap", "服务地图", "服务依赖拓扑", "eBPF", "依赖关系", "监控对象"] +sidebarTitle: "ServiceMap" +--- + + + **Beta 功能**：ServiceMap 处于 Beta 阶段，功能与界面可能继续调整。它依赖 `monit-agent` 的 eBPF 观测能力——Agent 版本过低、运行环境不支持或未启用 ServiceMap 时，主机会显示为「不支持」或「未启用」，没有拓扑数据。 + + +ServiceMap 根据 `monit-agent` 通过 eBPF 观测到的真实网络连接，自动构建主机、进程、容器和工作负载之间的依赖拓扑。它不依赖任何手工配置或静态架构图，展示的是"此刻这台机器实际在和谁通信"，而不是"文档里写的应该和谁通信"。 + +**入口**：监控对象页面（对象列表里每一行的"拓扑"按钮，或工具栏的"ServiceMap 主机"按钮）。 + +## 概述 + +拓扑里的每一条依赖（边）来自 Agent 观测到的一次真实连接：源实体（进程、容器或工作负载）向某个目标端点（`ip:port/protocol`）发起了 `connect`。ServiceMap 的解析器会尝试把这个目标端点匹配到同一网络作用域内的某个已知监听者，从而把一条"连接"变成一条"服务依赖"： + +- 如果端点唯一匹配到一个监听者，这条依赖标记为**已确认**。 +- 如果端点匹配到多个可能的监听者，标记为**候选**，需要你结合上下文判断真正的对端。 +- 如果端点没有匹配到任何监听者，标记为**未解析**，默认不进入拓扑画布（避免外部地址、短暂连接等噪音掩盖真实依赖）。 + +在故障排查时，ServiceMap 用来快速确认"这台主机 / 这个服务当前的直接依赖和被依赖方是谁"，判断变更或异常的影响半径，而不需要临时登录主机逐个排查连接。在监控对象列表中点击"AI分析"时，如果该主机的 ServiceMap 拓扑可用且你有权限查看，系统会自动把当前拓扑摘要作为上下文一并提供给 AI-SRE，不需要手动附加。 + + +查看 ServiceMap 需要 `MonitServiceMapVisit` 权限。没有该权限时，拓扑抽屉会提示"需要 ServiceMap Read 权限才能查看当前拓扑"，对象列表和主机列表本身仍可正常使用。 + + +## 如何打开 ServiceMap + +在监控对象页面（`/monit/targets`），有两个入口： + +- **对象列表里的"拓扑"按钮**：当某一行满足以下全部条件时，操作列会出现"拓扑"链接，点击后直接打开该主机的当前拓扑。 + - `host_id` 存在且格式合法； + - 该对象上报了 `servicemap` 能力且没有错误码； + - `graph_available` 为真（当前有可读取的图）； + - ServiceMap 状态为**正常**、**降级**或**已过期**三者之一。 +- **工具栏的"ServiceMap 主机"按钮**：打开全账号范围的 ServiceMap 主机列表（见下文"主机列表"），可以按 Agent 版本、Edge 集群、采集模式、状态筛选后再进入某一台主机的拓扑，同样受上面这条规则约束。 + +打开后的拓扑抽屉包含两个标签页：**拓扑**（可视化画布）和**数据详情**（查询信息 + 依赖明细表格），标题栏会显示当前图是"实时"还是"已过期"、采集模式，以及观测时间。 + +## 拓扑画布 + +### 解析状态筛选 + +画布上方是一组按钮，对应依赖的解析状态，每个按钮都带数量角标： + +| 按钮 | 含义 | +|---|---| +| **已确认** | 已解析到唯一对端服务的依赖。点击可切换画布中已确认依赖节点/连线的显示与隐藏。 | +| **候选** | 存在多个可能对端、尚未唯一确定的依赖。点击同样可切换显示与隐藏。 | +| **未解析**（红色） | 点击不是切换画布可见性，而是打开"未解析端点分组"抽屉（见下文）。未解析端点默认不进入画布。数量为 0 时按钮禁用。 | + +如果某条依赖的解析状态既不是"已确认"也不是"候选/未解析"（后端返回状态为已确认，但候选数量并不等于 1 的异常数据），工具栏会额外出现一个**未知 N** 的标签作为提示，这类连线在画布中以灰色点划线呈现。 + +### 跳数与聚焦模式 + +- 未进入聚焦模式时，工具栏左侧是"范围"选择器，可选 **1 跳 / 2 跳 / 3 跳**。这是一次新的后端查询（不是纯前端过滤）：跳数越大，加载的节点和边越多，也更容易触发查询上限。单次查询默认最多返回 100 个节点、200 条边。 +- **双击任意节点**进入聚焦模式：画布只保留以该节点为中心、按上下游方向展开的局部依赖图。进入聚焦时上游跳数固定重置为 1 跳，下游跳数保留你上次设置的值（初始为 1 跳）；上游、下游跳数可以分别独立调整为 0～3 跳。上游边代表调用你的一方，下游边代表你依赖的一方。 +- 也可以用画布右上角的搜索框（按名称、ID、容器或工作负载搜索）直接定位并聚焦某个节点。 +- 点击"退出聚焦"或按 Esc 可退出聚焦，回到当前跳数范围内的整体拓扑。 + +### 画布控制与交互 + +- 左下角提供**放大 / 缩小**、当前缩放百分比，以及**显示/隐藏小地图**。 +- **适应画布**把整张图缩放到可见范围；**重新布局**用新的随机种子重新排列节点位置（用于拆开重叠严重的节点）。 +- 悬停在某个节点上时，与它直接相连的节点/连线保持高亮，其余整体变淡；从该节点**发出**的连线（它的下游依赖）会额外显示指标标签，例如 `↑ 12.3 KB/s` / `↓ 4.1 KB/s`（发送/接收速率）、`✕ 3`（观测窗口内的连接失败次数）、`↻ 2`（重传次数），或在没有明显速率数据时显示 `● 5`（当前活跃连接数）。速率只在该窗口指标完整时才展示。 +- 单击节点或连线会在右侧打开详情面板（见下文），面板宽度可拖拽调整；单击画布空白处清除选中。 +- 画布左上角常驻一组统计卡片：**服务**（节点数）、**已确认依赖**、**已检查依赖**（本次查询实际检查过的依赖总数，含已确认/候选/未解析）。 +- 当本次查询触发截断（达到节点/边上限）时，画布上方会出现"已检查 N 条依赖，达到查询上限"的提示条，附带"聚焦服务"按钮，方便你直接搜索并聚焦到关心的服务，缩小范围重新查看。 + +节点形状和连线颜色是判断依赖可信度的第一层信号： + +| 视觉表现 | 含义 | +|---|---| +| 圆形节点 | 已知实体（进程 / 容器 / 工作负载） | +| 圆形节点 + 问号图标 | 候选节点：某条"候选"依赖的一个可能对端实体 | +| 菱形节点 | 尚未归并为实体的目标端点：候选依赖展开出的端点节点，或通过"未解析端点"面板临时定位的未解析端点 | +| 绿色实线 | 已确认依赖 | +| 橙色虚线（带动画） | 候选依赖，会从端点菱形节点分别连向多个候选实体 | +| 红色点划线 | 未解析依赖，仅在你主动"定位来源"时临时出现 | +| 灰色点划线 | 未知（后端标记为已确认但候选数量异常的数据） | + +## 节点详情 + +单击一个实体或候选节点，右侧详情面板会按三组展示信息： + +| 分组 | 字段 | 说明 | +|---|---|---| +| 身份 | 显示名称 | 该实体在页面上展示的名称 | +| | 类型 | 实体类型（如 `process_workload`、`container`） | +| | Entity ID | 实体的唯一标识 | +| | Host ID | 实体所在主机的标识 | +| 运行时 | 可执行文件 | 该实体对应的可执行文件名 | +| | Systemd Unit | 该实体对应的 systemd 服务单元（如有） | +| | 容器 | 容器名称（如实体运行在容器内） | +| | 镜像 | 镜像仓库和版本，格式为 `repository:version` | +| | 工作负载 | Kubernetes 命名空间/工作负载名称，格式为 `namespace/workload_name` | +| | 实例数 | 归并到该实体下的实例数量 | +| 观测 | 首次观测 | 该实体首次被观测到的时间 | +| | 最近观测 | 该实体最近一次被观测到的时间 | +| | 实体身份 | 后端返回的原始身份标识（JSON），用于精确排查 | + +每一行右侧悬停会出现复制按钮，可以直接复制该字段的原始值。面板顶部还有一个"只看它的上下游"按钮，可以从详情面板直接对该节点发起聚焦。 + +## 依赖详情 + +单击一条连线（或一个候选/端点节点），详情面板会展示这条依赖的三组信息： + +| 分组 | 字段 | 说明 | +|---|---|---| +| 标识 | Edge ID | 该依赖的唯一标识 | +| | 源 Entity ID | 发起连接的源实体 ID | +| | 源 NetNS ID | 源实体所在的网络命名空间 ID | +| | 目标端点 | 目标端点，格式为 `ip:port/protocol` | +| | 证据 | 该依赖被观测到的方式（自由文本，例如 `connect`，表示通过一次 connect 系统调用观测到该连接） | +| 解析 | 解析状态 | `resolved` / `ambiguous` / `unresolved` 等原始解析状态 | +| | 解析原因 | 解析器返回的原因说明 | +| | 候选数量 | 解析器为该端点找到的可能对端服务数量，大于 1 时依赖标记为候选 | +| | 候选被截断 | 候选列表超过返回上限时为"是"，此时只返回了部分候选 | +| | 匹配类型 | 候选的匹配方式（如 `exact` 精确匹配、`wildcard` 通配匹配） | +| | 置信度 | 该候选的置信度数值 | +| | Listener ID | 候选对端实际监听器的标识 | +| 观测 | 首次观测 | 该依赖首次被观测到的时间 | +| | 最近观测 | 该依赖最近一次被观测到的时间 | + +判断一条依赖是否可信，优先看**解析状态**和**候选数量**：候选数量为 1 才会被判定为已确认；候选数量大于 1 时属于候选依赖，需要结合**匹配类型**和**置信度**判断哪个候选更可能是真实对端。 + +## 数据详情标签页 + +拓扑抽屉的"数据详情"标签页提供一个不依赖画布交互的表格视图，标签本身会显示已确认依赖的数量角标，包含两部分： + +**查询信息**：展示本次查询的 Host ID、Network Scope、观测时间、方向与深度、覆盖主机数等（字段含义详见下一节"如何判断拓扑是否可信"）。 + +**依赖明细**：仅列出已确认和候选依赖（不含未解析），每行包含来源、目标、协议端口、置信度（高 / 中 / 低）、最近观测时间。置信度按该依赖候选中的最高置信度值分级：不低于 0.85 为高，不低于 0.5 为中，其余为低。 + +## 未解析端点 + +未解析端点指目标端点没有匹配到任何已知监听者的依赖。它们默认不进入拓扑画布，而是通过独立的"未解析端点分组"抽屉按原因分组展示。 + +打开方式：点击画布顶部的"未解析"筛选按钮。首次打开时，如果当前拓扑查询使用的是摘要模式（只有分组计数、没有具体端点列表），会自动发起一次补充查询加载完整列表。 + +已知的分组原因及说明： + +| 原因 | 说明 | +|---|---| +| `no_current_listener` | 未发现当前监听器 | +| `listener_address_family_unknown` | 监听地址族不确定 | +| `invalid_endpoint` | 端点信息无效 | + +后端返回其他未预置文案的原因时，会用通用的"未解析"标签展示，原始原因字符串仍会一并显示。 + +在某个分组内，你可以： + +- 用左上角的搜索框按目标端点或来源服务过滤当前分组内的记录； +- 点击某一行的"定位来源"图标，关闭抽屉并在画布上临时高亮这条未解析依赖的来源实体和目标端点（对应画布上的"正在定位未解析端点"提示条，点击"退出定位"或按 Esc 退出）； +- 点击右上角"导出 CSV"，导出全部未解析端点（不限于当前选中分组），CSV 列依次为：**目标端点**、**来源服务**、**源 Entity ID**、**解析原因**。 + +## 主机列表 + +从工具栏的"ServiceMap 主机"按钮打开，展示账号下所有上报了 ServiceMap 能力的主机，独立于单台主机的拓扑视图。 + +**筛选条件**：Agent 版本（多值输入，回车确认，最多 20 个）、Edge 集群（多值输入，回车确认，最多 20 个）、采集模式（多选：eBPF / Polling / 未知）。 + +**状态分布**：一组统计卡片，按固定顺序展示"正常 / 降级 / 已过期 / 初始化中 / 未启用 / 不支持 / 暂无数据"七种状态各自的主机数，点击某个卡片即可按该状态筛选下方列表（再点击一次或点"清除状态筛选"取消）。卡片上方展示扫描覆盖信息："扫描 N 台（上限 M），匹配 X 台，成功分类 Y 台，失败 Z 台"，以及计数生成时间。如果本次统计是有界扫描（达到扫描上限）或部分主机状态读取失败，会分别提示"仅代表本次有界扫描"或"计数不完整"。 + +各状态的含义： + +| 状态 | 含义 | +|---|---| +| 正常 | 当前拓扑新鲜且可用于分析 | +| 降级 | 采集仍在运行，但当前证据不完整或不是 authoritative | +| 已过期 | 最后可信拓扑已超过新鲜度窗口 | +| 初始化中 | Agent 正在生成首个可用快照 | +| 未启用 | 该 Agent 未启用 ServiceMap | +| 不支持 | 当前 Agent 或运行环境不支持 ServiceMap | +| 暂无数据 | 已发现能力，但还没有可用的当前拓扑 | + + +监控对象列表和主机列表还可能出现两种额外的展示态：**未上报**（Agent 未上报 ServiceMap 能力，不能直接判断为不支持）和**状态不可用**（ServiceMap 状态暂时无法读取，监控对象本身仍可用）。这两种不是 ServiceMap 状态的正式取值，只是状态列自身的容错展示。 + + +**主机列表**：列出 Host ID、Agent 版本、Edge 集群（即接入该主机 Agent 的 monitedge 集群名）、ServiceMap 状态、采集模式、拓扑观测时间；满足前文"如何打开 ServiceMap"条件的行会出现"拓扑"操作按钮，点击直接打开该主机的拓扑。 + +列表采用游标分页、按需加载，因此在加载完所有匹配结果之前无法知道精确总数：底部会显示"已加载 N 台主机"（还有更多可加载）或"共 N 台主机"（已经是全部结果）。如果本次浏览达到扫描边界或部分主机状态不可用，列表上方会提示"主机列表达到扫描边界或部分状态不可用，请继续翻页或收窄筛选"。 + +## 如何判断拓扑是否可信 + +拓扑是根据近期观测窗口内的连接证据生成的，不是实时快照，也不保证完整。打开任意一台主机的拓扑后，可以从"数据详情"标签页的"查询信息"区块（以及拓扑抽屉标题栏、画布顶部提示条）综合判断这份拓扑有多可信： + +| 字段 | 说明 | +|---|---| +| Network Scope | 网络作用域标识，端点解析只在同一作用域内进行。默认按 Edge 集群自动划分作用域，无需手动配置。 | +| 采集模式 | 产生这份拓扑证据的采集方式，例如 `ebpf` 内核观测；也可能是 `polling` 或 `hybrid`。 | +| 新鲜度 | `fresh` 表示证据在观测窗口内、可视为实时；其他状态说明这份图已经过期，抽屉标题栏会显示"已过期"标签，并额外提示"请结合观测时间和 coverage 判断，不要将过期图当作实时依赖"。 | +| 覆盖主机 | 本次拓扑查询实际加载的主机数量。 | +| Network Inventory | 监听端点清单投影的状态，影响端点解析的完整性（例如该投影是否完整可用）。 | +| Kubernetes Enrichment | Kubernetes 元数据富化状态，影响容器与工作负载信息是否完整。 | +| 查询限制 | 本次查询触发的截断原因列表，**出现即说明这份图不完整**（例如达到节点或边数上限）。 | + + +当拓扑存在降级或不完整证据时（`degraded_hosts` 大于 0，或存在降级原因），抽屉会额外提示"当前拓扑包含降级或不完整证据"；查询本身超时或被限流时，会分别提示"请稍后重试或降低深度"和"请稍后重试"。这些都不是错误，而是提醒你此时看到的依赖关系可能不完整，建议缩小跳数范围或稍后重试。 + + +简单来说：**新鲜度不是 `fresh`**、**查询限制列表不为空**、或**降级/不完整证据提示出现**，都说明当前这份拓扑不能当作实时、完整的依赖关系直接下结论，需要结合观测时间进一步确认。 diff --git a/zh/rum/error-tracking/error-aggregation.mdx b/zh/rum/error-tracking/error-aggregation.mdx index 0ce46af3..d96f008a 100644 --- a/zh/rum/error-tracking/error-aggregation.mdx +++ b/zh/rum/error-tracking/error-aggregation.mdx @@ -148,6 +148,8 @@ Flashduty 默认启用异常聚合，无需额外配置即可开始工作。Brow 在 Flashduty 平台，导航至「异常追踪」，查看聚合后的 Issue 列表。 +也可以从应用列表直达：应用卡片上的 **Issue** 数字可以点击，点击后跳转到该应用的异常追踪列表，并自动锁定与卡片一致的口径——最近 24 小时、状态为「全部」，同时清除上次遗留的筛选条件，因此列表里的条数与卡片上的数字一致。 + 每个 Issue 包含： | 内容 | 说明 |