metrics_skill

Overview

This skill queries resource usage and performance metrics for Railway services. It returns CPU, memory, network, disk, and related measurements over a specified time range to help diagnose performance or capacity issues. Use it alongside service and deployment checks to assess health and root causes.

How this skill works

It calls the Railway metrics GraphQL endpoint with environmentId (and optional serviceId), a startDate (and optional endDate), requested measurements, and grouping tags. The response includes timestamped values per measurement and optional tags such as serviceId, deploymentId, and region. Clients typically run a small shell wrapper that builds the JSON variables and posts the GraphQL query.

When to use it

• You want current or historical CPU, memory, disk, or network usage for a service.
• You need to determine if a service is slow or under resource pressure.
• You want per-deployment or per-instance metrics by grouping tags.
• You are validating capacity needs before scaling a service.
• You need to correlate logs and deployments with resource spikes.

Best practices

• Obtain environmentId and serviceId from railway status --json before querying.
• Always set startDate in ISO 8601 format; omit endDate to use now.
• Use sensible sampleRateSeconds and averagingWindowSeconds to reduce noise (e.g., 60s sample, 300s window).
• Group by SERVICE_ID or DEPLOYMENT_INSTANCE_ID for targeted troubleshooting.
• Handle empty or null metrics safely — services without active deployments return no data.

Example use cases

• Get last hour CPU and memory for a single service to check recent spikes.
• Query all services in an environment grouped by SERVICE_ID to find the top resource consumers.
• Fetch per-instance CPU_USAGE to identify a noisy deployment instance.
• Compare MEMORY_USAGE_GB to MEMORY_LIMIT_GB to detect memory pressure before OOMs.
• Collect NETWORK_RX_GB and NETWORK_TX_GB to investigate traffic anomalies.