---
docStatus: current
---

# 资源用量与容量分析

按环境或 Slot 查询实际 CPU、内存、CPU 限流和请求表现，用历史时序分析压测容量。

`debug status` 展示运行状态、健康、配额和实例诊断。评估容量余量时，使用独立的指标查询获取实际用量，
并把指标窗口与压测的并发、吞吐、延迟和错误对齐。

## 数据来源与口径

Runtime 从 Linux cgroup 采集 Slot 容器数据，从 `/proc` 采集业务进程及可观察到的子进程数据。
OpenResty 记录业务请求状态码和耗时，固定 `/healthz` 请求不计入请求指标。结构化记录经平台采集到 SLS，
由 Observability 查询与聚合。开发者无需进入容器、配置云凭据或自行指定 Kubernetes 资源。

| 范围   | 可查询指标                                                                                                                                                             |
| ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 环境   | `cpuUsageCores`、`memoryRssBytes`、`threads`、`processes`                                                                                                            |
| 环境请求 | `requestRate`、`httpErrorRatio`、`requestDurationP95Ms`、`requestDurationP99Ms`                                                                                      |
| Slot | `cpuUsageCores`、`cpuLimitCores`、`cpuThrottledPeriodRatio`、`cpuThrottledSecondsRate`、`memoryUsageBytes`、`memoryWorkingSetBytes`、`memoryLimitBytes`、`oomKillsTotal` |

一个 Slot 可以运行多个环境。容器的 CPU 配额、内存配额与 CPU 限流属于整个 Slot，不能标成某个环境的
独立限额或限流。进程 RSS 可能重复计算共享页，不能替代容器 working set。进程采样可能遗漏短于采样间隔、
且未被观察到的子进程；需要精确分析短任务时，使用相应的应用观测或性能分析工具。

CPU 用量由累计 CPU 时间的差分除以单调时钟间隔计算，单位为核；例如 `0.1` 核等于 `100m`。
限流周期比例是窗口内“被限流周期增量 / CPU 周期增量”，与被限流时长速率分开返回；时长速率可能大于 1。
OOM kill 来自内核对应计数；无法读取时保留缺失状态，不把内存申请失败次数当成 OOM kill。

`httpErrorRatio` 统计 HTTP 4xx、5xx 占比；HTTP 200 中的 CModel 业务失败需要结合业务日志分析。
P95/P99 按时间桶汇总所有授权目标的耗时分布，再按请求计数加权计算经验分位数（nearest-rank），不平均各部署的 P95/P99。请求指标汇总所选环境的 Endpoint；不采集请求正文或凭据。

## 查询命令

先用本机帮助确认命令是否存在：

```bash
baijimu workspace hosted-service debug metrics --help
```

以下 ID 变量来自本次工作区、项目、环境和 Slot 记录。时间变量使用 **Unix 毫秒**，查询范围为
`[startTime, endTime)`；这与日志命令的 RFC3339 参数不同。`stepSeconds` 是返回时间桶宽度，原始采样周期
由 Runtime 配置，资源时序返回实际 `sampleIntervalSeconds`。

查询环境进程与请求表现：

```bash
baijimu workspace hosted-service debug metrics \
  --workspace-id "$WORKSPACE_ID" \
  --project-id "$PROJECT_ID" \
  --environment-id "$ENVIRONMENT_ID" \
  --start-time "$START_TIME_MS" \
  --end-time "$END_TIME_MS" \
  --step-seconds 60 \
  --metric cpuUsageCores,memoryRssBytes,requestRate,httpErrorRatio,requestDurationP95Ms,requestDurationP99Ms \
  --json
```

查询 Slot 的实际用量、配额与限流：

```bash
baijimu workspace hosted-service debug metrics \
  --workspace-id "$WORKSPACE_ID" \
  --slot-id "$SLOT_ID" \
  --start-time "$START_TIME_MS" \
  --end-time "$END_TIME_MS" \
  --step-seconds 60 \
  --metric cpuUsageCores,cpuLimitCores,memoryWorkingSetBytes,memoryLimitBytes,cpuThrottledPeriodRatio,cpuThrottledSecondsRate,oomKillsTotal \
  --json
```

`--metric` 可重复，也可用逗号分隔。必须且只能选择 `projectId + environmentId` 或 `slotId`，不能传物理
部署、Pod、主机或原始 SQL。时间窗口上限沿用平台配置；单次最多返回 10000 个时间桶，超过时增大粒度或拆分窗口。

## Partner API

```text
POST /partner/v1/observability-service/api/hosted-service/metrics/query
```

请求参数：

| 参数                          | 类型    | 要求                  |
| --------------------------- | ----- | ------------------- |
| `workspaceId`               | 正整数   | 必填，且符合凭据的工作区约束      |
| `projectId`、`environmentId` | 正整数   | 环境查询时同时提供           |
| `slotId`                    | 正整数   | Slot 查询时提供，与环境选择器互斥 |
| `startTime`、`endTime`       | 整数    | Unix 毫秒，结束时间晚于开始时间  |
| `stepSeconds`               | 正整数   | 返回时间桶宽度，单位秒         |
| `metrics`                   | 字符串数组 | 上述正式指标名称，非空且不能重复    |

通过正式 Partner HTTP API 发送同一请求；`metrics-query.json` 保存上述 JSON 参数。API 地址来自当前环境，访问凭据 通过公开授权流程取得并覆盖目标工作区：

```bash
curl --request POST "$BAIJIMU_API_BASE_URL/partner/v1/observability-service/api/hosted-service/metrics/query" \
  --header "Authorization: Bearer $BAIJIMU_ACCESS_TOKEN" \
  --header "X-Workspace-Id: $WORKSPACE_ID" \
  --header 'Content-Type: application/json' --data-binary @metrics-query.json
```

## 权限

API 客户端遵循平台公开认证流程。平台验证调用者并由 Hosted Owner 校验实际资源归属：

- 环境查询要求 Hosted Project 所有者身份或工作区管理权限。
- Slot 聚合查询要求目标工作区管理权限，因为它可能包含多个项目的资源消耗。
- 服务业务 consumer token、渠道身份和 AgentExecution 凭据不授予此管理查询能力。

指标查询只读，不授予终端、容器、集群、业务配置或密钥权限。

## 读取结果与缺失数据

CModel `errorCode == "0"` 表示查询成功。`data.targets` 解释时间窗口内的历史部署归属，`data.series`
返回指标时序。资源时序按物理运行和采样实例分别返回，部署切换时不会把先后运行的实例相加为一次用量峰值。
请求时序按环境汇总实际请求。

| 字段                                 | 含义                                                     |
| ---------------------------------- | ------------------------------------------------------ |
| `metric`、`unit`                    | 指标名称与明确单位                                              |
| `source`、`instanceId`              | 资源时序的部署归属与采样实例；环境请求汇总时为空                               |
| `sampleIntervalSeconds`            | 原始资源采样周期；请求指标为事件统计                                     |
| `firstSampleTime`、`lastSampleTime` | 实际读取到的样本时间，可能包含窗口前的 CPU 差分基线                           |
| `points[].timestamp`               | 从查询开始时间对齐的时间桶起点，Unix 毫秒                                |
| `points[].value`、`peak`            | 资源桶内平均值与采样峰值；速率使用时间加权平均。请求指标返回桶内统计结果，`peak` 等于 `value` |
| `points[].sampleCount`             | 参与计算的实际样本或请求数                                          |
| `status`、`missingReason`           | 可用性及缺失原因                                               |

`available` 表示有可用数据，`partial` 表示存在采集错误或采样间断，`unsupported` 表示该资源没有所请求
指标的独立口径，`noSamples` 表示未取得可计算样本。没有数据的桶不会补零。`data.complete` 只有在所请求
时序均可用时才为 `true`；它不证明平台之外的业务请求或未观测到的短任务也已覆盖。

CPU 差分读取窗口前最多一个正式采样周期上限的历史数据作基线；计数器重置、PID 复用、时钟异常和长采样
间断不会被拼成异常峰值。旧 Runtime 没有产生样本的历史时段无法补采，需要先由平台升级运行时，再查询
新采集的窗口。

授权被拒绝、数据源失败、查询未完成或范围解析失败均返回非零 `errorCode`，不能显示成“用量为零”。
错误数据中的 `message` 与 `retryable` 用于区分参数问题和可重试的查询失败。资源样本与请求耗时分布行各有 100000 行预算，数据源查询也有超时限制，
超限时缩短窗口；不要把单次受限查询当作全量导出。

## 评估压测容量

记录同一时间窗口的并发数、吞吐、P95/P99、错误率、环境 CPU/RSS，以及 Slot CPU/working set/限流。
配额减去实际用量只能说明对应资源的观测余量，不能单独证明还能增加多少并发。连接池、队列、锁等待与下游
限制需要应用主动暴露或结合日志分析。查询命令不会自动执行压测或改变配额。