metrics

用途

该技能用于查询 Railway 服务的资源使用指标，帮助回答资源占用、CPU、内存、网络、磁盘或服务性能相关的问题。典型触发场景包括：用户询问“我的服务用了多少内存？”、询问 CPU 使用率、网络流量、磁盘使用情况、调试性能问题，或询问“我的服务是否健康？”（可与 service 技能结合使用）。

主要能力

支持查询以下指标（MetricMeasurement）：

CPU_USAGE：CPU 使用量（核）
CPU_LIMIT：CPU 限制（核）
MEMORY_USAGE_GB：内存使用量（GB）
MEMORY_LIMIT_GB：内存限制（GB）
NETWORK_RX_GB：网络接收量（GB）
NETWORK_TX_GB：网络发送量（GB）
DISK_USAGE_GB：磁盘使用量（GB）
EPHEMERAL_DISK_USAGE_GB：临时磁盘使用量（GB）
BACKUP_USAGE_GB：备份使用量（GB）

支持按以下标签（MetricTag）分组（groupBy）：

DEPLOYMENT_ID：按部署分组
DEPLOYMENT_INSTANCE_ID：按实例分组
REGION：按区域分组
SERVICE_ID：按服务分组

使用方式

前置条件

从已链接的项目中获取 environmentId 和 serviceId：

railway status --json

提取：

environment.id → environmentId
service.id → serviceId（可选，省略则获取所有服务）

查询结构

query metrics(
  $environmentId: String!
  $serviceId: String
  $startDate: DateTime!
  $endDate: DateTime
  $sampleRateSeconds: Int
  $averagingWindowSeconds: Int
  $groupBy: [MetricTag!]
  $measurements: [MetricMeasurement!]!
) {
  metrics(
    environmentId: $environmentId
    serviceId: $serviceId
    startDate: $startDate
    endDate: $endDate
    sampleRateSeconds: $sampleRateSeconds
    averagingWindowSeconds: $averagingWindowSeconds
    groupBy: $groupBy
    measurements: $measurements
  ) {
    measurement
    tags {
      deploymentInstanceId
      deploymentId
      serviceId
      region
    }
    values {
      ts
      value
    }
  }
}

示例：最近一小时的 CPU 与内存

使用 heredoc 避免 shell 转义问题：

bash <<'SCRIPT'
START_DATE=$(date -u -v-1H +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -d "1 hour ago" +"%Y-%m-%dT%H:%M:%SZ")
ENV_ID="your-environment-id"
SERVICE_ID="your-service-id"

VARS=$(jq -n \
  --arg env "$ENV_ID" \
  --arg svc "$SERVICE_ID" \
  --arg start "$START_DATE" \
  '{environmentId: $env, serviceId: $svc, startDate: $start, measurements: ["CPU_USAGE", "MEMORY_USAGE_GB"]}')

scripts/railway-api.sh \
  'query metrics($environmentId: String!, $serviceId: String, $startDate: DateTime!, $measurements: [MetricMeasurement!]!) {
    metrics(environmentId: $environmentId, serviceId: $serviceId, startDate: $startDate, measurements: $measurements) {
      measurement
      tags { deploymentId region serviceId }
      values { ts value }
    }
  }' \
  "$VARS"
SCRIPT

示例：环境中所有服务

省略 serviceId 并使用 groupBy 获取所有服务的指标：

bash <<'SCRIPT'
START_DATE=$(date -u -v-1H +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -u -d "1 hour ago" +"%Y-%m-%dT%H:%M:%SZ")
ENV_ID="your-environment-id"

VARS=$(jq -n \
  --arg env "$ENV_ID" \
  --arg start "$START_DATE" \
  '{environmentId: $env, startDate: $start, measurements: ["CPU_USAGE", "MEMORY_USAGE_GB"], groupBy: ["SERVICE_ID"]}')

scripts/railway-api.sh \
  'query metrics($environmentId: String!, $startDate: DateTime!, $measurements: [MetricMeasurement!]!, $groupBy: [MetricTag!]) {
    metrics(environmentId: $environmentId, startDate: $startDate, measurements: $measurements, groupBy: $groupBy) {
      measurement
      tags { serviceId region }
      values { ts value }
    }
  }' \
  "$VARS"
SCRIPT

时间参数

startDate：必填。ISO 8601 格式（例如 2024-01-01T00:00:00Z）
endDate：可选。默认为当前时间
sampleRateSeconds：采样间隔（例如 60 表示 1 分钟采样）
averagingWindowSeconds：用于平滑的平均窗口

提示：若要查询最近一小时，将 startDate 计算为当前时间减 1 小时的 ISO 格式。

输出解读

{
  "data": {
    "metrics": [
      {
        "measurement": "CPU_USAGE",
        "tags": { "deploymentId": "...", "serviceId": "...", "region": "us-west1" },
        "values": [
          { "ts": "2024-01-01T00:00:00Z", "value": 0.25 },
          { "ts": "2024-01-01T00:01:00Z", "value": 0.30 }
        ]
      }
    ]
  }
}

ts：ISO 格式的时间戳
value：指标值（CPU 为核数，内存/磁盘/网络为 GB）

适用场景

查看服务资源占用（内存、CPU、网络、磁盘）
调试性能问题
结合 service 技能判断服务健康度
按部署、实例、区域或服务维度分析指标

组合使用

获取 ID：使用 status 技能或 railway status --json
检查服务健康：使用 service 技能查看部署状态
查看日志：若指标显示问题，使用 deployment 技能
扩缩服务：使用 environment 技能调整资源

限制与错误处理

空/Null 指标

没有活跃部署的服务会返回空指标数组。使用 jq 处理时需处理 null：

# 安全迭代 - 跳过 null
jq -r '.data.metrics[]? | select(.values != null and (.values | length) > 0) | ...'

# 处理前检查指标是否存在
jq -e '.data.metrics | length > 0' response.json && echo "has metrics"

无指标数据

服务可能是新建的或没有流量。检查：

服务有活跃部署（已停止的服务没有指标）
时间范围包含部署期间

无效的服务/环境 ID

使用 railway status --json 验证 ID。

权限被拒绝

用户需要拥有该项目的访问权限才能查询指标。