> ## 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 自动构建服务地图，除了正常的链路追踪之外无需额外埋点。
服务地图与 [APM](/zh-Hans/apm) 使用相同的 trace 输入，但属于不同投影。服务地图通过跨服务
父子 span 配对构建拓扑；APM 构建有界的服务、事务、依赖、错误与版本聚合。
## 服务地图如何构建
trace span 到达时，MoleSignal 会把每个 span 与对应父 span 配对。当两个 span 属于**不同
服务**时，这就是一条调用边——*父服务 → 子服务*——边的时延与错误状态取自子（被调）span。同一服务内部
的父子 span 属内部调用，不画成边。
边会按服务对累计进**一分钟的桶**，并在后台周期落库，因此地图大约在半分钟内即反映最近的流量。
### 内存模式 vs 存储模式
默认（`intake` 模式）配对在接入 span 的节点上以**内存态**完成——延迟低。多节点部署下，同一次调用的
父子 span 若落到不同节点则无法在内存配对，地图可能少算这些边（但绝不会凭空造边）。
要在跨节点下得到完整地图，把 **设置 → 通用 → 服务图数据来源** 切到 **storage（存储重算）** 模式：
由单个节点周期性从**存储里的 trace** 重建服务图——无论哪个节点接入都能看到全部 span——代价是约
1–2 分钟延迟。该设置存于数据库、运行时即时生效，无需重启。
## 需要发送什么
地图需要这样的 trace：
* 每个 span 带 **`service.name`** 资源属性（OTLP exporter 会自动设置），并且
* 存在**跨服务边界的父子 span 关系**——即一个服务里的 client span 对应另一个服务里的子 server span。
标准的 OpenTelemetry 埋点两者都会产出。把 tracer 指向任意一个
[trace 接入端点](/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
```
```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
```
`from` 与 `to` 为 Unix 纪元以来的微秒。可选的 `service` 过滤会返回指定服务作为调用任一端出现的边。每行携带
一个服务对在一分钟内的 `request_count`、`error_count` 以及 `p50_us` / `p95_us` / `p99_us`。
## 在界面里
* **Services** 页按流量排序，列出每个服务的速率、错误率和 p95。
* 打开某个服务可看到上游调用方与下游依赖。
* **拓扑**视图绘制实时图——边的粗细随流量，颜色随错误率。
从任意服务或边都能借助[跨信号关联](/zh-Hans/correlation)直接下钻到底层的 trace 与日志。
通过 HTTP 查询拓扑与原始服务图端点。
分析服务 RED 指标、事务、依赖、错误与部署。