> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 服务地图

> 由 trace span 自动派生的服务间调用实时拓扑。

**服务地图**展示各服务之间如何相互调用、每条调用是否健康——请求速率、错误率和时延（即 **RED** 指标）。MoleSignal 根据已发送的 trace 自动构建服务地图，除了正常的链路追踪之外无需额外埋点。

> [!NOTE]
>
> 服务地图与 [APM](https://docs.molesignal.com/zh-Hans/apm) 使用相同的 trace 输入，但属于不同投影。服务地图通过跨服务父子 span 配对构建拓扑；APM 构建有界的服务、事务、依赖、错误与版本聚合。

## 服务地图如何构建

trace span 到达时，MoleSignal 会把每个 span 与对应父 span 配对。当两个 span 属于**不同服务**时，这就是一条调用边——*父服务 → 子服务*——边的时延与错误状态取自子（被调）span。同一服务内部的父子 span 属内部调用，不画成边。边属于调用方所在的环境（`deployment.environment.name` 或 `deployment.environment`），调用方没有环境时取被调方的环境。

边会按服务对累计进**一分钟的桶**，并在后台周期落库，因此地图大约在半分钟内即反映最近的流量。

### 内存模式 vs 存储模式

默认（`intake` 模式）配对在接入 span 的节点上以**内存态**完成——延迟低。多节点部署下，同一次调用的父子 span 若落到不同节点则无法在内存配对，地图可能少算这些边（但绝不会凭空造边）。

要在跨节点下得到完整地图，把 **设置 → 通用 → 服务图数据来源** 切到 **storage（存储重算）** 模式：由单个节点周期性从**存储里的 trace** 重建服务图——无论哪个节点接入都能看到全部 span——代价是约 1–2 分钟延迟。该设置存于数据库、运行时即时生效，无需重启。

## 需要发送什么

地图需要这样的 trace：

* 每个 span 带 **`service.name`** 资源属性（OTLP exporter 会自动设置），并且
* 存在**跨服务边界的父子 span 关系**——即一个服务里的 client span 对应另一个服务里的子 server span。

标准的 OpenTelemetry 埋点两者都会产出。把 tracer 指向任意一个 [trace 接入端点](https://docs.molesignal.com/zh-Hans/intake)，地图便会自行填充。

## 拓扑

拓扑端点把一个时间窗聚合成节点（服务）与边（调用）：

```http theme={null}
GET /api/v1/web/topology?from=2026-06-14T00:00:00Z&to=2026-06-14T01:00:00Z
Authorization: Bearer <jwt>
```

```json theme={null}
{
  "nodes": [
    { "id": "checkout", "name": "checkout", "rps": 42.0, "error_rate": 0.01, "p95_ms": 120.0, "span_count": 151200 }
  ],
  "edges": [
    { "source": "checkout", "target": "payments", "rps": 41.0, "err_rate": 0.02, "p95_ms": 95.0 }
  ]
}
```

| 字段 | 含义 |
| - | - |
| `rps` | 窗口内每秒请求数。 |
| `error_rate` / `err_rate` | 状态为 `ERROR` 的请求占比（0–1）。 |
| `p95_ms` | 窗口内各分钟中最高的 95 分位时延，单位毫秒。 |
| `span_count` | 窗口内该节点的 span 总数。 |

## 原始服务图

若想要底层逐分钟的边快照——便于把某条依赖随时间画成图——可直接查询服务图：

```http theme={null}
GET /api/v1/traces/service_graph?from=1717200000000000&to=1717286400000000&service=checkout
Authorization: Bearer <jwt>
```

`from` 与 `to` 为 Unix 纪元以来的微秒。可选的 `service` 过滤会返回指定服务作为调用任一端出现的边。每行携带一个服务对在一分钟内的 `environment`、`request_count`、`error_count` 以及 `p50_us` / `p95_us` / `p99_us`。

## 在界面里

* **应用性能 → 服务地图**绘制一个环境中的服务及其相互调用，以及它们调用的对象和发布、消费的 Topic。见 [APM 服务地图](#apm-服务地图)。
* 服务 APM 页面的**依赖**分区按 APM 服务地图的方式绘制该服务及其上下游，并列出调用它的调用；点开一条调用会打开同样的调用抽屉。
* Traces 页面的**服务图**标签绘制查询匹配的 trace 构成的地图。

所有服务地图的画法一致：节点是一个按健康状况着色的圆环，中间是它的类型图标，旁边是名称以及每秒请求数、错误率和 P95；调用画成箭头，粗细随流量，失败率达到 5% 为红色，达到 1% 为橙色。

从任意服务或边都能借助[跨信号关联](https://docs.molesignal.com/zh-Hans/correlation.md)直接下钻到底层的 trace 与日志。

## APM 服务地图

**应用性能 → 服务地图**把服务图与 APM 的投影合在一起，范围是导航卡片中选定的环境和命名空间：

| 节点 | 来源 |
| - | - |
| 服务 | 服务图，带 APM 摘要中的 RED 指标与健康状态。 |
| 数据库、缓存、外部 HTTP 或 RPC | APM 依赖中的外部调用，按调用目标汇总。 |
| 未上报数据的服务 | 调用通过 `peer.service` 指名、但自身不发送 span 的服务。 |
| Topic | 发布到某个消息目标的调用，以及从它消费的消息端点。 |

调用线的粗细随流量，颜色随失败情况。与之前同样长的一段时间相比，只在现在出现的调用标为**新增**，不再出现的调用标为**已消失**并画成虚线，连同它的节点一起显示。选中一个节点会点亮调用它的节点、它调用的节点，以及从它向下的**关键链路**：每一步都走 P95 最高的调用。地图上的卡片列出该节点的调用；点开一条调用会在抽屉中显示它随时间变化的请求数、错误和延迟，以及沿这条调用访问的内容：

* 调用服务时，显示被调服务的端点（包含所有调用方的请求）和它的错误分组；
* 调用数据库、缓存或外部端点时，显示这条调用的操作；
* 经过 Topic 时，显示消息的等待时间：从发布完成到开始消费，取自 Trace 存储中最近的消费（最多 200 次），每次消费通过 span links 找到对应的发布 span，没有 links 时取父 span。

节点超过 60 个时，地图默认把每个命名空间折叠成一个节点；选中它即可展开。**按命名空间折叠**会折叠或展开全部命名空间。地图最多绘制 400 个节点，保留最繁忙的那些。

> **[拓扑与服务图 API](https://docs.molesignal.com/zh-Hans/api/web/topology.md)**
>
> 通过 HTTP 查询拓扑与原始服务图端点。

> **[应用性能监控](https://docs.molesignal.com/zh-Hans/apm)**
>
> 维护服务目录，分析服务的端点、依赖、错误与部署。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.