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 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"]}')

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

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"]}')

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

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 status skill or railway status --json

• Check service health: Use service skill for deployment status

• View logs: Use deployment skill if metrics show issues

• Scale service: Use 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.