Railway Metrics

Monitor Railway service performance with real-time resource metrics

✨ The solution you've been looking for

Verified

Tested and verified by our team

16036 Stars

Query resource usage metrics for Railway services. Use when user asks about resource usage, CPU, memory, network, disk, or service performance like "how much memory is my service using" or "is my service slow".

railway monitoring performance metrics cpu memory debugging resources

Repository

See It In Action

Interactive preview & real-world examples

Live Demo

AI Conversation Simulator

See how users interact with this skill

User Prompt

My Railway service is running slow, can you check the CPU and memory usage for the last hour?

Skill Processing

Analyzing request...

Agent Response

Real-time metrics showing CPU cores used, memory consumption in GB, with timestamps to identify performance bottlenecks

Quick Start (3 Steps)

Get up and running in minutes

Install

claude-code skill install railway-metrics

claude-code skill install railway-metrics

Config

First Trigger

@railway-metrics help

Commands

Command	Description	Required Args
@railway-metrics debug-performance-issues	Investigate service performance problems by analyzing CPU and memory usage patterns	None
@railway-metrics monitor-resource-utilization	Track resource usage across all services in an environment to optimize costs and scaling	None
@railway-metrics capacity-planning	Analyze usage trends to make informed decisions about resource limits and scaling	None

Typical Use Cases

Debug Performance Issues

Investigate service performance problems by analyzing CPU and memory usage patterns

Monitor Resource Utilization

Track resource usage across all services in an environment to optimize costs and scaling

Capacity Planning

Analyze usage trends to make informed decisions about resource limits and scaling

Overview

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:

1railway 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

 1query metrics(
 2  $environmentId: String!
 3  $serviceId: String
 4  $startDate: DateTime!
 5  $endDate: DateTime
 6  $sampleRateSeconds: Int
 7  $averagingWindowSeconds: Int
 8  $groupBy: [MetricTag!]
 9  $measurements: [MetricMeasurement!]!
10) {
11  metrics(
12    environmentId: $environmentId
13    serviceId: $serviceId
14    startDate: $startDate
15    endDate: $endDate
16    sampleRateSeconds: $sampleRateSeconds
17    averagingWindowSeconds: $averagingWindowSeconds
18    groupBy: $groupBy
19    measurements: $measurements
20  ) {
21    measurement
22    tags {
23      deploymentInstanceId
24      deploymentId
25      serviceId
26      region
27    }
28    values {
29      ts
30      value
31    }
32  }
33}

Example: Last Hour CPU and Memory

Use heredoc to avoid shell escaping issues:

 1bash <<'SCRIPT'
 2START_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")
 3ENV_ID="your-environment-id"
 4SERVICE_ID="your-service-id"
 5
 6VARS=$(jq -n \
 7  --arg env "$ENV_ID" \
 8  --arg svc "$SERVICE_ID" \
 9  --arg start "$START_DATE" \
10  '{environmentId: $env, serviceId: $svc, startDate: $start, measurements: ["CPU_USAGE", "MEMORY_USAGE_GB"]}')
11
12${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
13  'query metrics($environmentId: String!, $serviceId: String, $startDate: DateTime!, $measurements: [MetricMeasurement!]!) {
14    metrics(environmentId: $environmentId, serviceId: $serviceId, startDate: $startDate, measurements: $measurements) {
15      measurement
16      tags { deploymentId region serviceId }
17      values { ts value }
18    }
19  }' \
20  "$VARS"
21SCRIPT

Example: All Services in Environment

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

 1bash <<'SCRIPT'
 2START_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")
 3ENV_ID="your-environment-id"
 4
 5VARS=$(jq -n \
 6  --arg env "$ENV_ID" \
 7  --arg start "$START_DATE" \
 8  '{environmentId: $env, startDate: $start, measurements: ["CPU_USAGE", "MEMORY_USAGE_GB"], groupBy: ["SERVICE_ID"]}')
 9
10${CLAUDE_PLUGIN_ROOT}/skills/lib/railway-api.sh \
11  'query metrics($environmentId: String!, $startDate: DateTime!, $measurements: [MetricMeasurement!]!, $groupBy: [MetricTag!]) {
12    metrics(environmentId: $environmentId, startDate: $startDate, measurements: $measurements, groupBy: $groupBy) {
13      measurement
14      tags { serviceId region }
15      values { ts value }
16    }
17  }' \
18  "$VARS"
19SCRIPT

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

 1{
 2  "data": {
 3    "metrics": [
 4      {
 5        "measurement": "CPU_USAGE",
 6        "tags": { "deploymentId": "...", "serviceId": "...", "region": "us-west1" },
 7        "values": [
 8          { "ts": "2024-01-01T00:00:00Z", "value": 0.25 },
 9          { "ts": "2024-01-01T00:01:00Z", "value": 0.30 }
10        ]
11      }
12    ]
13  }
14}

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:

1# Safe iteration - skip nulls
2jq -r '.data.metrics[]? | select(.values != null and (.values | length) > 0) | ...'
3
4# Check if metrics exist before processing
5jq -e '.data.metrics | length > 0' response.json && echo "has metrics"