davila7

railway-metrics

@davila7/railway-metrics
davila7
17,001
1497 forks
Updated 1/18/2026
View on GitHub

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

Installation

$skills install @davila7/railway-metrics
Claude Code
Cursor
Copilot
Codex
Antigravity

Details

Repositorydavila7/claude-code-templates
Pathcli-tool/components/skills/railway/metrics/SKILL.md
Branchmain
Scoped Name@davila7/railway-metrics

Usage

After installing, this skill will be available to your AI coding assistant.

Verify installation:

skills list

Skill Instructions

name: railway-metrics description: 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". version: 1.0.0 author: Railway license: MIT tags: [Railway, Metrics, Monitoring, Performance, CPU, Memory, Resources, Analytics] dependencies: [railway-cli] allowed-tools: Bash(railway:*)

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:

railway status --json

Extract:

  • environment.id → environmentId
  • service.id → serviceId (optional - omit to get all services)

MetricMeasurement Values

MeasurementDescription
CPU_USAGECPU usage (cores)
CPU_LIMITCPU limit (cores)
MEMORY_USAGE_GBMemory usage in GB
MEMORY_LIMIT_GBMemory limit in GB
NETWORK_RX_GBNetwork received in GB
NETWORK_TX_GBNetwork transmitted in GB
DISK_USAGE_GBDisk usage in GB
EPHEMERAL_DISK_USAGE_GBEphemeral disk usage in GB
BACKUP_USAGE_GBBackup usage in GB

MetricTag Values (for groupBy)

TagDescription
DEPLOYMENT_IDGroup by deployment
DEPLOYMENT_INSTANCE_IDGroup by instance
REGIONGroup by region
SERVICE_IDGroup 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"]}')

${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 <<'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

ParameterDescription
startDateRequired. ISO 8601 format (e.g., 2024-01-01T00:00:00Z)
endDateOptional. Defaults to now
sampleRateSecondsSample interval (e.g., 60 for 1-minute samples)
averagingWindowSecondsAveraging 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 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:

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

More by davila7

View all
agile-product-owner
17,041

Agile product ownership toolkit for Senior Product Owner including INVEST-compliant user story generation, sprint planning, backlog management, and velocity tracking. Use for story writing, sprint planning, stakeholder communication, and agile ceremonies.

content-creator
17,041

Create SEO-optimized marketing content with consistent brand voice. Includes brand voice analyzer, SEO optimizer, content frameworks, and social media templates. Use when writing blog posts, creating social media content, analyzing brand voice, optimizing SEO, planning content calendars, or when user mentions content creation, brand voice, SEO optimization, social media marketing, or content strategy.

dspy
17,041

Build complex AI systems with declarative programming, optimize prompts automatically, create modular RAG systems and agents with DSPy - Stanford NLP's framework for systematic LM programming

marketing-demand-acquisition
17,041

Multi-channel demand generation, paid media optimization, SEO strategy, and partnership programs for Series A+ startups. Includes CAC calculator, channel playbooks, HubSpot integration, and international expansion tactics. Use when planning demand generation campaigns, optimizing paid media, building SEO strategies, establishing partnerships, or when user mentions demand gen, paid ads, LinkedIn ads, Google ads, CAC, acquisition, lead generation, or pipeline generation.