metrics

サービスメトリクス

Railway サービスのリソース使用量メトリクスをクエリします。

使用するタイミング

• ユーザーが「サービスのメモリ使用量はどれくらいですか？」と尋ねた場合
• CPU 使用率、ネットワークトラフィック、ディスク使用量について尋ねた場合
• パフォーマンスの問題をデバッグしたい場合
• 「サービスは正常に動作していますか？」と尋ねた場合（service スキルと組み合わせます）

前提条件

リンクされたプロジェクトから environmentId と serviceId を取得します。

railway status --json

以下を抽出します。

• environment.id → environmentId
• service.id → serviceId（省略すると、すべてのサービスを取得します）

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	サービスごとにグループ化

クエリ

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

例：直近 1 時間の CPU とメモリ

シェルのエスケープ処理の問題を避けるには、heredoc を使用します。

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	サンプル間隔（例：1 分間隔のサンプルなら 60）
averagingWindowSeconds	平滑化に使用する平均化ウィンドウ

ヒント： 直近 1 時間のデータを取得するには、ISO 形式で now - 1 hour として startDate を計算します。

出力の解釈

{
  "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 を取得する：status スキルまたは railway status --json を使用します
• サービスの状態を確認する：デプロイ状態の確認には service スキルを使用します
• ログを表示する：メトリクスに問題がある場合は deployment スキルを使用します
• サービスをスケーリングする：リソースの調整には 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／環境 ID が無効

railway status --json で ID を確認してください。

アクセス許可が拒否された

メトリクスをクエリするには、ユーザーにプロジェクトへのアクセス権が必要です。