Skills
skills/adaptationio/skrillz/railway-logs

railway-logs

SKILL.md

Railway Logs

Access and analyze Railway logs for debugging and monitoring applications.

Overview

Railway provides comprehensive logging across the deployment lifecycle:

  • Build Logs: Build process output and compilation
  • Deploy Logs: Deployment lifecycle and health checks
  • Runtime Logs: Application stdout/stderr output
  • HTTP Logs: Request metadata (status, path, IP, timing)

All logs support filtering, search, and can be exported to external systems for long-term retention.

Keywords: Railway logs, build logs, deploy logs, runtime logs, HTTP logs, log filtering, log search, debugging, monitoring, observability

When to Use This Skill

  • Debugging deployment failures
  • Investigating runtime errors
  • Monitoring application behavior
  • Analyzing HTTP request patterns
  • Filtering logs for specific events
  • Exporting logs to external systems (Datadog, Axiom, BetterStack)
  • Understanding build/deploy process
  • Troubleshooting performance issues

Prerequisites: Link Project First

Important: CLI logs require a linked project with Account Token:

# 1. Set Account Token (NOT project token)
export RAILWAY_API_TOKEN=<your-account-token>

# 2. Link project/environment/service
railway link -p <PROJECT_ID> -e <ENVIRONMENT_ID> -s <SERVICE_ID>

# Example:
railway link -p f8fff4f1-1541-4a47-b509-0c30b9459275 \
             -e 3aa108f4-781d-433c-9eee-875c3dbe903d \
             -s 4b879f5f-5e42-4804-a67c-2a1ff2475cb3

# 3. Verify link
railway status

See cli-commands.md for complete reference.

Operations

Operation 1: View Build Logs

Access build process logs to debug compilation and dependency issues.

CLI Commands:

# Stream build logs (live)
railway logs --build

# Last 100 lines of build logs
railway logs --build --lines 100

# Build logs for specific deployment
railway logs --build <DEPLOYMENT_ID>

# Export build logs to file
railway logs --build --lines 500 > build-logs.txt

Dashboard Access:

  1. Navigate to Railway Dashboard → Your Service
  2. Click Deployments tab
  3. Select deployment
  4. View Build Logs section

What to Look For:

  • ✅ Dependency installation success
  • ✅ Build steps completion
  • ⚠️ Warning messages (may indicate future issues)
  • ❌ Build failures and error messages
  • 📊 Build time (optimization opportunities)

Common Issues:

Issue Solution
Dependencies not installing Check package.json/requirements.txt
Build timeout Optimize build process or increase timeout
Missing build command Set in Railway dashboard or railway.json
Cache issues Force rebuild without cache

See Also: railway-troubleshooting for cache busting

Operation 2: View Deploy Logs

Monitor deployment lifecycle and health check status.

CLI Commands:

# Stream deployment logs (live)
railway logs --deployment

# Last N lines of deploy logs
railway logs --deployment --lines 200

# Specific deployment by ID
railway logs --deployment <DEPLOYMENT_ID>

# Export deploy logs
railway logs --deployment --lines 500 > deploy-logs.txt

Dashboard Access:

  1. Railway Dashboard → Service → Deployments
  2. Select deployment
  3. View Deploy Logs section

Deployment Phases:

  1. Building - Compiling code
  2. Publishing - Creating container image
  3. Deploying - Rolling out to infrastructure
  4. Health Checking - Verifying service health
  5. Active - Deployment live

Health Check Debugging:

# View health check failures
railway logs --deployment | grep "health check"

# Common health check issues:
# - Port not exposed correctly
# - Application not binding to 0.0.0.0
# - Health endpoint not responding
# - Application crashing during startup

Troubleshooting:

  • Health check failing? Verify PORT environment variable
  • Deployment stuck? Check for blocking startup processes
  • Rollback occurring? Check health check configuration

Operation 3: View Runtime Logs

Access application stdout/stderr for debugging runtime behavior.

CLI Commands:

# Stream runtime logs (live, Ctrl+C to stop)
railway logs

# Last N lines (stops streaming)
railway logs --lines 500

# Stream different service/environment
railway logs --service backend --environment production

# Filter with Railway syntax
railway logs --filter "@level:error"
railway logs --lines 100 --filter "timeout"

# Pipe to grep for local filtering
railway logs | grep ERROR

# JSON output for parsing
railway logs --json | jq 'select(.level == "error")'

Dashboard Access:

  1. Railway Dashboard → Service → Observability
  2. Click Logs tab
  3. Real-time log stream with filtering

Structured Logging Best Practices:

Railway supports structured JSON logging. Output JSON on a single line:

// Node.js Example
console.log(JSON.stringify({
  level: 'error',
  message: 'Database connection failed',
  error: err.message,
  timestamp: new Date().toISOString(),
  userId: req.user?.id
}));

# Python Example
import json
import logging

logging.basicConfig(format='%(message)s')
logger = logging.getLogger()

logger.error(json.dumps({
    'level': 'error',
    'message': 'Database connection failed',
    'error': str(e),
    'timestamp': datetime.utcnow().isoformat(),
    'user_id': user_id
}))

Supported Log Levels:

  • debug - Detailed diagnostic information
  • info - General informational messages
  • warn - Warning messages (potential issues)
  • error - Error messages (failures)

Benefits:

  • All JSON fields are searchable in Railway dashboard
  • Better filtering and analysis
  • Integration with log aggregation tools

Operation 4: View HTTP Logs

Analyze HTTP request patterns and debug API issues.

Dashboard Access:

  1. Railway Dashboard → Service → Observability
  2. Click HTTP tab
  3. View request metadata

Available Metadata:

  • HTTP method (GET, POST, etc.)
  • Request path
  • Status code
  • Response time (ms)
  • Client IP address
  • User agent
  • Timestamp

Filtering HTTP Logs:

# Filter by status code
@httpStatus:500

# Filter by path
@path:"/api/users"

# Combine filters
@httpStatus:500 AND @path:"/api"

Use Cases:

  • Identify slow endpoints (high response time)
  • Find error patterns (500, 404 status codes)
  • Analyze traffic patterns
  • Debug API issues
  • Monitor rate limits

Performance Analysis:

# Find slow requests (>1000ms)
# Filter in dashboard: responseTime > 1000

# Find all 5xx errors
# Filter: @httpStatus:5xx

# Analyze specific endpoint
# Filter: @path:"/api/checkout"

Operation 5: Filter and Search Logs

Use Railway's powerful filtering syntax for targeted log analysis.

Filter Syntax:

Filter Example Description
Substring "error" Search for text
HTTP Status @httpStatus:500 Filter by status code
Service ID @service:<id> Filter by service
Log Level @level:error Filter by severity
Custom Field @userId:123 Filter by JSON field

Boolean Operators:

# AND - Both conditions must match
@httpStatus:500 AND @path:"/api"

# OR - Either condition matches
@level:error OR @level:warn

# NOT - Exclude matches
NOT @path:"/health"

# Grouping
(@level:error OR @level:warn) AND @service:api

Common Filter Patterns:

# All errors from last hour
@level:error

# Slow HTTP requests (>1000ms)
@httpStatus:200 AND responseTime > 1000

# Failed API calls
@path:"/api" AND @httpStatus:5xx

# Exclude health checks
NOT @path:"/health" NOT @path:"/metrics"

# Specific user errors
@level:error AND @userId:12345

# Database connection issues
"connection refused" OR "timeout"

Dashboard Filtering:

  1. Observability → Logs
  2. Enter filter in search box
  3. Use dropdowns for common filters
  4. Save frequent filters as presets

CLI Filtering:

# Use grep for basic filtering (streaming is default)
railway logs | grep ERROR

# Use jq for JSON logs
railway logs --json | jq 'select(.level == "error")'

# Complex filtering with awk
railway logs | awk '/ERROR/ || /WARN/'

Operation 6: Export Logs Externally

Export logs to external systems for long-term retention and analysis.

Why Export?

  • Railway retention: 7-30 days (plan dependent)
  • Long-term log storage
  • Advanced analytics
  • Compliance requirements
  • Centralized multi-service logging

External Export Options:

Option 1: Locomotive Sidecar (Webhook Export)

Deploy a sidecar container to forward logs via webhooks.

Repository: https://github.com/railwayapp/locomotive

Setup:

# Add locomotive service to Railway project
railway service create locomotive

# Configure environment variables
WEBHOOK_URL=https://your-log-endpoint.com/ingest
WEBHOOK_METHOD=POST
WEBHOOK_HEADERS='{"Authorization": "Bearer xxx"}'

# Deploy locomotive
railway up

Supported Destinations:

  • Custom webhooks
  • Datadog
  • Axiom
  • BetterStack
  • Logtail
  • Any HTTP endpoint

Option 2: OpenTelemetry (OTEL) Integration

Send logs using OTEL protocol.

Environment Variables:

# Add to your service
OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.example.com:4318
OTEL_EXPORTER_OTLP_HEADERS=x-api-key=xxx
OTEL_SERVICE_NAME=my-railway-service

Supported OTEL Collectors:

  • Grafana Alloy
  • OpenTelemetry Collector
  • Datadog Agent
  • New Relic
  • Honeycomb

See Also: observability-stack-setup for LGTM stack

Option 3: Log Streaming Script

Use the provided script to stream logs to external systems.

Usage:

# Stream to file
.claude/skills/railway-logs/scripts/stream-logs.sh --output file --path logs/

# Stream to webhook
.claude/skills/railway-logs/scripts/stream-logs.sh --output webhook \
  --url https://logs.example.com/ingest \
  --token YOUR_API_KEY

# Stream to S3
.claude/skills/railway-logs/scripts/stream-logs.sh --output s3 \
  --bucket my-logs-bucket \
  --prefix railway/

Features:

  • Continuous streaming
  • Automatic reconnection
  • Buffering and batching
  • Multiple output formats

Option 4: Manual Export

Export logs for ad-hoc analysis.

# Export last 1000 lines
railway logs --lines 1000 > logs-$(date +%Y%m%d-%H%M%S).txt

# Export recent logs (specify number of lines)
railway logs --lines 1000 > logs-recent.txt

# Export and compress
railway logs --lines 5000 | gzip > logs.txt.gz

Scheduled Export (cron):

# Add to crontab (every 6 hours)
0 */6 * * * railway logs --lines 10000 > /backup/railway-logs-$(date +\%Y\%m\%d-\%H\%M).txt

Integration with External Tools

Datadog

# Install Datadog agent in Railway
# Add environment variables:
DD_API_KEY=xxx
DD_SITE=datadoghq.com
DD_LOGS_ENABLED=true
DD_LOGS_CONFIG_CONTAINER_COLLECT_ALL=true

Axiom

# Use locomotive sidecar
WEBHOOK_URL=https://api.axiom.co/v1/datasets/<dataset>/ingest
WEBHOOK_HEADERS='{"Authorization": "Bearer <token>"}'

BetterStack (Logtail)

# Add to your application
LOGTAIL_SOURCE_TOKEN=xxx

# Use Logtail SDK
npm install @logtail/node

Grafana Loki

# Deploy Grafana Agent/Alloy
# Configure to scrape Railway logs
# See observability-stack-setup skill

Best Practices

1. Structured Logging

DO:

console.log(JSON.stringify({ level: 'info', message: 'User login', userId: 123 }));

DON'T:

console.log(`User ${userId} logged in`); // Hard to search/filter

2. Log Levels

Use appropriate severity:

  • debug - Development/troubleshooting only
  • info - Normal operations
  • warn - Potential issues (high memory, slow queries)
  • error - Failures requiring attention

3. Sensitive Data

NEVER log:

  • Passwords
  • API keys
  • Credit card numbers
  • Personal identifiable information (PII)

Redact sensitive data:

console.log(JSON.stringify({
  level: 'info',
  message: 'User login',
  email: 'u***@example.com', // Redacted
  ip: req.ip
}));

4. Performance

Avoid excessive logging:

// BAD - Logs every request
app.use((req, res, next) => {
  console.log(`Request: ${req.method} ${req.path}`);
  next();
});

// GOOD - Log only errors or important events
app.use((req, res, next) => {
  if (res.statusCode >= 400) {
    console.log(JSON.stringify({ level: 'error', method: req.method, path: req.path, status: res.statusCode }));
  }
  next();
});

5. External Export

For production:

  • Export logs to external system (Railway retention is limited)
  • Use structured logging (JSON)
  • Implement log rotation
  • Set up alerts on error patterns

Troubleshooting Common Issues

Issue Solution
Logs not appearing Check application is writing to stdout/stderr
JSON logs not parsing Ensure JSON is on single line (no newlines)
Logs truncated Railway may truncate very long log lines (>10KB)
Missing logs Check log retention period for your plan
Can't filter by custom field Verify field is in structured JSON log
High log volume Reduce logging verbosity, sample logs

Quick Reference

Task Command
Stream runtime logs railway logs
Last N lines railway logs --lines 100
Build logs railway logs --build
Deploy logs railway logs --deployment
Export to file railway logs --lines 500 > output.txt
Filter errors railway logs | grep ERROR
JSON filtering railway logs --json | jq 'select(.level == "error")'

Important: CLI vs API

Use CLI for logs, not API. The Railway GraphQL API log queries (deploymentLogs, buildLogs) often return "Problem processing request". The CLI provides reliable log access:

railway logs                    # Runtime logs
railway logs --deployment       # Build/deploy logs
railway logs --lines 100        # Historical logs

See railway-api/references/api-limitations.md for details.

Related Skills

References

See the references/ directory for detailed guides:

Scripts

See the scripts/ directory for automation tools:

Last Updated: 2025-11-26

Weekly Installs
1
Repository
adaptationio/skrillz
Installed on
claude-code1