railway-metrics

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Railway Service Metrics

Railway服务指标查询

Query resource usage metrics for Railway services.

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

When to Use

适用场景

User asks "how much memory is my service using?"
User asks about CPU usage, network traffic, disk usage
User wants to debug performance issues
User asks "is my service healthy?" (combine with railway-service skill)

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

Prerequisites

前置条件

Get environmentId and serviceId from linked project:

bash

railway status --json

Extract:

```
environment.id
```
→ environmentId
```
service.id
```
→ serviceId (optional - omit to get all services)

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

bash

railway status --json

提取以下信息：

```
environment.id
```
→ environmentId
```
service.id
```
→ serviceId（可选 - 留空可获取所有服务的指标）

MetricMeasurement Values

指标项说明

Measurement	Description
CPU_USAGE	CPU usage (cores)
CPU_LIMIT	CPU limit (cores)
MEMORY_USAGE_GB	Memory usage in GB
MEMORY_LIMIT_GB	Memory limit in GB
NETWORK_RX_GB	Network received in GB
NETWORK_TX_GB	Network transmitted in GB
DISK_USAGE_GB	Disk usage in GB
EPHEMERAL_DISK_USAGE_GB	Ephemeral disk usage in GB
BACKUP_USAGE_GB	Backup usage in GB

指标类型	描述
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 Values (for groupBy)

分组标签说明

Tag	Description
DEPLOYMENT_ID	Group by deployment
DEPLOYMENT_INSTANCE_ID	Group by instance
REGION	Group by region
SERVICE_ID	Group by service

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

Query

查询语句

graphql

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
    }
  }
}

graphql

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
    }
  }
}

Example: Last Hour CPU and Memory

示例：查询过去一小时的CPU和内存指标

Use heredoc to avoid shell escaping issues:

bash

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

使用here-doc语法避免Shell转义问题：

bash

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

Example: All Services in Environment

示例：查询环境中所有服务的指标

Omit serviceId and use groupBy to get metrics for all services:

bash

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

省略serviceId并使用groupBy参数，即可获取所有服务的指标：

bash

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

Time Parameters

时间参数说明

Parameter	Description
startDate	Required. ISO 8601 format (e.g., `2024-01-01T00:00:00Z` )
endDate	Optional. Defaults to now
sampleRateSeconds	Sample interval (e.g., 60 for 1-minute samples)
averagingWindowSeconds	Averaging window for smoothing

Tip: For last hour, calculate startDate as

now - 1 hour

in ISO format.

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

提示：查询过去一小时的指标时，可将startDate计算为

当前时间 - 1小时

的ISO格式。

Output Interpretation

输出解读

json

{
  "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
```
- timestamp in ISO format
```
value
```
- metric value (cores for CPU, GB for memory/disk/network)

json

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

Composability

组合使用

Get IDs: Use railway-status skill or
```
railway status --json
```
Check service health: Use railway-service skill for deployment status
View logs: Use railway-deployment skill if metrics show issues
Scale service: Use railway-environment skill to adjust resources

获取ID：使用railway-status技能或
```
railway status --json
```
命令
检查服务健康状态：使用railway-service技能查询部署状态
查看日志：若指标显示异常，可使用railway-deployment技能查看日志
扩容服务：使用railway-environment技能调整资源配置

Error Handling

错误处理

Empty/Null Metrics

指标为空/Null

Services without active deployments return empty metrics arrays. When processing with jq, handle nulls:

bash

undefined

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

bash

undefined

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"

undefined

jq -e '.data.metrics | length > 0' response.json && echo "存在指标"

undefined

No Metrics Data

无指标数据

Service may be new or have no traffic. Check:

Service has active deployment (stopped services have no metrics)
Time range includes deployment period

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

服务是否有活跃部署（已停止的服务无指标数据）
时间范围是否包含部署运行时段

Invalid Service/Environment ID

无效的服务/环境ID

Verify IDs with

railway status --json

使用

railway status --json

命令验证ID的正确性。

Permission Denied

权限不足

User needs access to the project to query metrics.

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