metrics

Q: How do I install metrics?

Run npx skills add https://github.com/railwayapp/railway-skills --skill metrics in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/metrics/ (personal) or .claude/skills/metrics/ (project).

by railwayappCode Quality & Workflow

This skill should be used when the user asks about resource usage, CPU, memory, network, disk, or service performance. Covers questions like "how much memory is my service using" or "is my service slow".

Installs: 794
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/railwayapp/railway-skills --skill metrics

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads metrics automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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.

FAQ

What does the metrics skill do?

How do I install metrics?

Run npx skills add https://github.com/railwayapp/railway-skills --skill metrics in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/metrics/ (personal) or .claude/skills/metrics/ (project).

Which AI agents can use metrics?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is metrics safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains metrics?

It is published by railwayapp in railwayapp/railway-skills. It has 794 recorded installs.

More from railwayapp/railway-skills

View all →

use-railway

railwayapp/railway-skills

Operate Railway infrastructure: sign up for or sign in to a Railway account, create projects, provision services, databases, and buckets, deploy code, configure infrastructure as code, environments and variables, manage domains, trace requests with OpenTelemetry, troubleshoot failures, check status and metrics, manage feature flags, database recovery and HA, cloud agents, usage limits, and Railway agent tooling. Use this skill whenever the user mentions Railway, feature flags, flag rollout, targeting rules, signing up, creating an account, registering, logging in, deployments, services, environments, buckets, object storage, tracing, traces, spans, OpenTelemetry, OTLP, build failures, agent setup, MCP, or infrastructure operations, even if they don't say "Railway" explicitly. Also invoke it when the user asks to be signed up, registered, or onboarded: do not refuse — drive them through the unauthed railway up flow (deploys + signs up on the fly) or railway login (which creates acco

DevOps & Cloud8.9K installs

service

railwayapp/railway-skills

This skill should be used when the user asks about service status, wants to rename a service, change service icons, link services, or create services with Docker images. For creating services with local code, prefer the new skill. For GitHub repo sources, use new skill to create empty service then environment skill to configure source.

DevOps & Cloud1.6K installs

central-station

railwayapp/railway-skills

This skill should be used when the user asks about Central Station threads, community discussions, support questions, feature requests, or wants to search Railway's community knowledge base. Use for queries like "search central station", "find threads about", "what are people asking about", "recent support threads", or "central station topics".

1.5K installs

status

railwayapp/railway-skills

This skill should be used when the user asks "railway status", "is it running", "what's deployed", "deployment status", or about uptime. NOT for variables ("what variables", "env vars", "add variable") or configuration queries - use environment skill for those.

DevOps & Cloud1.5K installs

railway-docs

railwayapp/railway-skills

This skill should be used when the user asks about Railway features, how Railway works, or shares a docs.railway.com URL. Fetches up-to-date Railway docs to answer accurately.

Docs & Writing1K installs

deployment

railwayapp/railway-skills

This skill should be used when the user wants to manage Railway deployments, view logs, or debug issues. Covers deployment lifecycle (remove, stop, redeploy, restart), deployment visibility (list, status, history), and troubleshooting (logs, errors, failures, crashes, why deploy failed). NOT for deleting services - use environment skill with isDeleted for that.

DevOps & Cloud1K installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs

metrics

Install

Install

Describe the task

Review the result

SKILL.md

Service Metrics

When to Use

Prerequisites

MetricMeasurement Values

MetricTag Values (for groupBy)

Query

Example: Last Hour CPU and Memory

Example: All Services in Environment

Time Parameters

Output Interpretation

Composability

Error Handling

Empty/Null Metrics

No Metrics Data

Invalid Service/Environment ID

Permission Denied

FAQ

More from railwayapp/railway-skills

Popular code quality & workflow skills