> ## 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.

# 指标、链路与服务

> 用 MoleSignal 命令行执行带迷你折线的 PromQL，浏览指标名称与标签，查找链路并画成瀑布图，汇总 APM 服务，比较两个版本，并用搜索任务执行耗时的查询。

## 查询指标

`molesignal metrics query` 执行一次 PromQL 区间查询，每个序列输出一行：它在时间窗内的最新值、最小值、最大值、一条迷你折线，以及它的标签。

```bash theme={null}
molesignal metrics query 'sum by (service) (rate(http_server_requests_total[5m]))' --since 6h
```

```text theme={null}
LAST   MIN    MAX    TREND                           SERIES
12.4   3.1    14.9   ▁▂▂▃▅▆▇█▇▆▆▅▅▆▇▇█▇▆▅▄▄▅▅▆▆▇▇▇▆   {service="checkout"}
```

时间窗默认是最近一小时，`--since`、`--from` 和 `--to` 可以修改。`-n` 限制点数，默认 `1000`。`--json` 输出每个序列及其数据点，`--csv` 把数据点按行输出。

另外四个子命令用来找查询的对象：

| 命令 | 列出 |
| - | - |
| `molesignal metrics names [文本]` | 指标名称，只列包含该文本的。 |
| `molesignal metrics labels <指标>` | 指标的标签。 |
| `molesignal metrics values <指标> <标签>` | 标签的取值，以及每个值出现的次数。 |
| `molesignal metrics series <指标>` | 指标的序列；`--match 标签=值` 缩小范围。 |

## 查找链路

```bash theme={null}
molesignal traces --service checkout --errors --since 6h
```

列表显示最新的链路，以及它们的开始时间、耗时、Span 数和服务。

| 选项 | 含义 |
| - | - |
| `--service <名称>` | 只看这个服务的链路。 |
| `--errors` | 只看有失败 Span 的链路。 |
| `--min-duration <时长>` | 只看耗时不少于该值的链路，例如 `500ms`。 |
| `--since`、`--from`、`--to` | 时间窗，默认最近一小时。 |
| `-n`、`--limit <数量>` | 链路条数，默认 `20`，最多 `200`。 |

## 画出一条链路

`molesignal traces show` 把一条链路画成瀑布图：每个 Span 一行，排在父 Span 之下，用一段条形表示它在整条链路中何时运行、耗时多久。失败的 Span 用 `!` 标出，在终端中显示为红色。

```bash theme={null}
molesignal traces show 4bf92f3577b34da6a3ce929d0e0e4736
```

```text theme={null}
checkout POST /orders          ████████████████████████████████████████  1.24s
├─ checkout SELECT orders       ███                                       98ms
└─ ! payments POST /charge         ███████████████████████████████████    1.1s
```

`--web` 在 MoleSignal 中打开这条链路，`--json` 输出它的 Span。

## 汇总服务

```bash theme={null}
molesignal services --env production --sort errors
```

列表显示每个 APM 服务的请求数、错误率、p95 延迟、健康状态和当前版本。`--sort` 按 `requests`、`errors`、`p95` 或 `name` 排序。

`molesignal services show` 汇总一个服务：先是请求、错误和延迟，再是它的接口、依赖、错误和版本：

```bash theme={null}
molesignal services show checkout --since 2h
```

## 比较两个版本

`molesignal services compare` 并排比较一个服务的两个版本，判断候选版本是变差、变好、持平，还是请求太少无法判断。带 `--fail-on-regression` 时，变差以 `1` 退出，流水线可以据此拦下发布：

```bash theme={null}
molesignal services compare checkout 2.3.9 2.4.0 --since 1h --fail-on-regression
```

## 用搜索任务执行耗时的查询

搜索任务在后台执行查询，能覆盖比即时查询更多的数据和更长的时间，并把结果保留一段时间。提交和取消搜索任务与其他变更一样经过组织的 Tool Policy，参见[事件与变更](https://docs.molesignal.com/zh-Hans/cli/changes.md#变更如何执行)。

```bash theme={null}
molesignal search-jobs submit "SELECT * FROM app_logs WHERE level = 'error'" --since 30d --wait
```

数据流取 `FROM` 后的第一个；`--stream` 可以指定另一个，`--promql` 提交 PromQL 语句，在时间窗口末尾求值，给了 `--step`（例如 `1m`）则每个步长求值一次。`--limit` 限制任务保留的行数，最多 `100000`，`--keep` 设置保留多久。`--wait` 等待任务完成。命令输出任务的 ID。

| 命令 | 作用 |
| - | - |
| `molesignal search-jobs` | 列出搜索任务及其状态、行数和语句。 |
| `molesignal search-jobs show <任务>` | 输出任务的状态、行数、时间和错误。 |
| `molesignal search-jobs results <任务>` | 写出已完成任务的结果，每行一个 JSON 对象；`--csv` 写 CSV，`-o <文件>` 写入文件。 |
| `molesignal search-jobs cancel <任务>` | 取消等待中或运行中的任务。 |

## 访问权限

指标与链路需要 `streams.query` 或 `sys.telemetry.read`，APM 与搜索任务也一样。组织的 Tool Policy 需要开启相应工具。


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