railway-metrics

Railway 服务指标

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

适用场景

• 用户询问“我的服务用了多少内存？”
• 用户询问 CPU 使用率、网络流量、磁盘使用情况
• 用户想要调试性能问题
• 用户询问“我的服务运行正常吗？”（结合 railway-service 技能）

前置条件

从关联的项目中获取 environmentId 和 serviceId：

railway status --json

提取：

• environment.id → environmentId
• service.id → serviceId（可选——省略即可获取所有服务）

MetricMeasurement 值

Measurement	Description
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）

Tag	Description
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

时间参数

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

**提示：**查询过去一小时的数据时，将 startDate 设为 now - 1 hour 对应的 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）

组合使用

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

错误处理

指标为空／为 Null

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

# Safe iteration - skip nulls
jq -r '.data.metrics[]? | select(.values != null and (.values | length) > 0) | ...'

# Check if metrics exist before processing
jq -e '.data.metrics | length > 0' response.json && echo "has metrics"

没有指标数据

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

• 服务是否有活动部署（已停止的服务没有指标）
• 时间范围是否包含部署时段

服务／环境 ID 无效

使用 railway status --json 验证 ID。

权限被拒绝

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