railway-metrics

Railway Service Metrics

Query resource usage metrics for Railway services.

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)

Prerequisites

Get environmentId and serviceId from linked project:

railway status --json

Extract:

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

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

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

Query

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

Use heredoc to avoid shell escaping issues:

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 <<'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.

Output Interpretation

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

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

Error Handling

Empty/Null Metrics

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

# 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"

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

Verify IDs with railway status --json.

Permission Denied

User needs access to the project to query metrics.