The-Utopia-Studio/metrics

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.