Métricas de Serviço Railway

Consulte métricas de uso de recursos para serviços Railway.

Quando Usar

• Usuário pergunta "quanto de memória meu serviço está usando?"
• Usuário pergunta sobre uso de CPU, tráfego de rede, uso de disco
• Usuário quer debugar problemas de desempenho
• Usuário pergunta "meu serviço está saudável?" (combine com a skill railway-service)

Pré-requisitos

Obtenha environmentId e serviceId do projeto vinculado:

railway status --json

Extraia:

• environment.id → environmentId
• service.id → serviceId (opcional - omita para obter todos os serviços)

Valores de MetricMeasurement

Measurement	Descrição
CPU_USAGE	Uso de CPU (cores)
CPU_LIMIT	Limite de CPU (cores)
MEMORY_USAGE_GB	Uso de memória em GB
MEMORY_LIMIT_GB	Limite de memória em GB
NETWORK_RX_GB	Rede recebida em GB
NETWORK_TX_GB	Rede transmitida em GB
DISK_USAGE_GB	Uso de disco em GB
EPHEMERAL_DISK_USAGE_GB	Uso de disco efêmero em GB
BACKUP_USAGE_GB	Uso de backup em GB

Valores de MetricTag (para groupBy)

Tag	Descrição
DEPLOYMENT_ID	Agrupar por deployment
DEPLOYMENT_INSTANCE_ID	Agrupar por instância
REGION	Agrupar por região
SERVICE_ID	Agrupar por serviço

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
    }
  }
}

Exemplo: CPU e Memória da Última Hora

Use heredoc para evitar problemas com escape de shell:

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

Exemplo: Todos os Serviços no Environment

Omita serviceId e use groupBy para obter métricas de todos os serviços:

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

Parâmetros de Tempo

Parâmetro	Descrição
startDate	Obrigatório. Formato ISO 8601 (ex: 2024-01-01T00:00:00Z)
endDate	Opcional. Padrão é agora
sampleRateSeconds	Intervalo de amostragem (ex: 60 para amostras de 1 minuto)
averagingWindowSeconds	Janela de média para suavização

Dica: Para a última hora, calcule startDate como agora - 1 hora em formato ISO.

Interpretação da Saída

{
  "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 em formato ISO
• value - valor da métrica (cores para CPU, GB para memória/disco/rede)

Composição

• Obter IDs: Use a skill railway-status ou railway status --json
• Verificar saúde do serviço: Use a skill railway-service para status de deployment
• Visualizar logs: Use a skill railway-deployment se as métricas mostrarem problemas
• Escalar serviço: Use a skill railway-environment para ajustar recursos

Tratamento de Erros

Métricas Vazias/Nulas

Serviços sem deployments ativos retornam arrays de métricas vazios. Ao processar com jq, trate nulls:

# Iteração segura - pule nulls
jq -r '.data.metrics[]? | select(.values != null and (.values | length) > 0) | ...'

# Verifique se as métricas existem antes de processar
jq -e '.data.metrics | length > 0' response.json && echo "has metrics"

Sem Dados de Métricas

O serviço pode ser novo ou não ter tráfego. Verifique:

• Serviço tem deployment ativo (serviços parados não têm métricas)
• Intervalo de tempo inclui período de deployment

ID de Serviço/Environment Inválido

Verifique IDs com railway status --json.

Permissão Negada

O usuário precisa de acesso ao projeto para consultar métricas.