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: ```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.