name: railway-metrics description: 查询 Railway 服务的资源使用指标。当用户询问资源使用情况、CPU、内存、网络、磁盘或服务性能时使用，例如“我的服务使用了多少内存”或“我的服务是否变慢”。 version: 1.0.0 author: Railway license: MIT tags: [Railway, 指标, 监控, 性能, CPU, 内存, 资源, 分析] dependencies: [railway-cli] allowed-tools: Bash(railway:*)

Railway 服务指标

查询 Railway 服务的资源使用指标。

使用时机

用户询问“我的服务使用了多少内存？”
用户询问 CPU 使用率、网络流量、磁盘使用情况
用户想要调试性能问题
用户询问“我的服务是否健康？”（可结合 railway-service 技能使用）

先决条件

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

railway status --json

提取：

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

测量指标值

测量指标	描述
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）

指标标签值（用于分组）

标签	描述
DEPLOYMENT_ID	按部署分组
DEPLOYMENT_INSTANCE_ID	按实例分组
REGION	按区域分组
SERVICE_ID	按服务分组

查询

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"]}')

${CLAUDE_PLUGIN_ROOT}/skills/lib/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"]}')

${CLAUDE_PLUGIN_ROOT}/skills/lib/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	用于平滑的平均窗口

提示： 对于过去一小时，以 ISO 格式计算 startDate 为 当前时间 - 1 小时。

输出解释

{
  "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）

可组合性

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

错误处理

空/空指标

没有活动部署的服务返回空指标数组。使用 jq 处理时，处理空值：

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

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

无指标数据

服务可能为新服务或无流量。检查：

服务有活动部署（停止的服务无指标）
时间范围包括部署期间

无效的服务/环境 ID

使用 railway status --json 验证 ID。

权限被拒绝

用户需要访问项目才能查询指标。