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:

bash

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

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

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

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

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

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)

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:

bash

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

railway-metrics

NPX Install

Tags

SKILL.md Content

Railway Service Metrics

When to Use

Prerequisites

MetricMeasurement Values

MetricTag Values (for groupBy)

Query

Example: Last Hour CPU and Memory

Example: All Services in Environment

Time Parameters

Output Interpretation

Composability

Error Handling

Empty/Null Metrics

No Metrics Data

Invalid Service/Environment ID

Permission Denied