Logs & Debugging

Master Runtime’s logging capabilities to quickly diagnose issues in your deployments.

Log Types

Type	Content	When Available
`build`	Docker build output	After build starts
`deploy`	Fly.io deployment	After deploy starts
`runtime`	Application output	When app is running

Basic Commands

# All logs
runtm logs dep_abc123xyz

# Specific type
runtm logs dep_abc123xyz --type runtime

# More lines
runtm logs dep_abc123xyz --lines 100

Search & Filter

Single Keyword

runtm logs dep_abc123xyz --search "error"

Multiple Keywords (OR)

runtm logs dep_abc123xyz --search "error,warning,failed"

Regex Patterns

# HTTP errors (4xx, 5xx)
runtm logs dep_abc123xyz --search "HTTP.*[45]\d\d"

# Database queries
runtm logs dep_abc123xyz --search "SELECT|INSERT|UPDATE|DELETE"

# Timestamps
runtm logs dep_abc123xyz --search "\d{4}-\d{2}-\d{2}"

Pipe-Friendly Output

Raw Mode

# Output without formatting
runtm logs dep_abc123xyz --raw

Piping to grep

# Filter with grep
runtm logs dep_abc123xyz --raw | grep "error"

# Multiple filters
runtm logs dep_abc123xyz --raw | grep -E "error|exception|failed"

# Exclude lines
runtm logs dep_abc123xyz --raw | grep -v "INFO"

# Count occurrences
runtm logs dep_abc123xyz --raw | grep -c "error"

Piping to Other Tools

# Sort unique errors
runtm logs dep_abc123xyz --raw | grep "error" | sort | uniq

# Last N errors
runtm logs dep_abc123xyz --raw | grep "error" | tail -20

# Save to file
runtm logs dep_abc123xyz --raw > debug.log

JSON Output

For programmatic access:

runtm logs dep_abc123xyz --json

{
  "deployment_id": "dep_abc123xyz",
  "logs": [
    {
      "type": "build",
      "content": "Step 1/12: FROM python:3.11-slim...",
      "created_at": "2024-01-15T10:30:45Z"
    },
    {
      "type": "runtime",
      "content": "INFO: Application startup complete.",
      "created_at": "2024-01-15T10:32:00Z"
    }
  ],
  "source": "stored"
}

Processing with jq

# Extract runtime logs only
runtm logs dep_abc123xyz --json | jq '.logs[] | select(.type == "runtime")'

# Get log content
runtm logs dep_abc123xyz --json | jq -r '.logs[].content'

# Filter by content
runtm logs dep_abc123xyz --json | jq '.logs[] | select(.content | test("error"; "i"))'

Processing with Python

import subprocess
import json

# Get logs
result = subprocess.run(
    ['runtm', 'logs', 'dep_abc123xyz', '--json'],
    capture_output=True, text=True
)
data = json.loads(result.stdout)

# Find errors
for log in data['logs']:
    if 'error' in log['content'].lower():
        print(f"[{log['type']}] {log['content'][:100]}...")

Common Debug Scenarios

Build Failures

# View build logs
runtm logs dep_abc123xyz --type build

# Look for pip/npm errors
runtm logs dep_abc123xyz --type build --search "error,failed,cannot"

Common build issues:

Missing dependencies in requirements.txt/package.json
Wrong Python/Node version
Network issues downloading packages

Deploy Failures

# View deploy logs
runtm logs dep_abc123xyz --type deploy

# Look for health check issues
runtm logs dep_abc123xyz --type deploy --search "health"

Common deploy issues:

Health check timeout (app not starting fast enough)
Port mismatch (app listening on wrong port)
Missing environment variables

Runtime Errors

# View recent runtime logs
runtm logs dep_abc123xyz --type runtime --lines 100

# Search for exceptions
runtm logs dep_abc123xyz --type runtime --search "exception,traceback,error"

Common runtime issues:

Unhandled exceptions
Database connection errors
External API failures

Health Check Debugging

The health check must:

Respond at /health (or custom health_path)
Return HTTP 200
Respond within 100ms

Testing Locally

# Start app
runtm run

# Test health endpoint
curl -w "\nTime: %{time_total}s\n" http://localhost:8080/health

If Health Checks Fail

# Check deploy logs
runtm logs dep_abc123xyz --type deploy

# Look for startup issues
runtm logs dep_abc123xyz --type runtime --search "startup,listen,ready"

Environment Variable Issues

Missing Variables

# Check for env var errors
runtm logs dep_abc123xyz --search "environment,missing,required"

# List what should be set
runtm secrets list

Wrong Values

# Look for connection errors
runtm logs dep_abc123xyz --search "connection,refused,timeout,invalid"

Performance Debugging

Slow Requests

# Look for slow queries
runtm logs dep_abc123xyz --search "slow,timeout,took"

# Check for N+1 queries
runtm logs dep_abc123xyz --search "SELECT" | wc -l

Memory Issues

# Look for memory errors
runtm logs dep_abc123xyz --search "memory,oom,killed"

If you see out-of-memory errors, upgrade to a higher tier:

runtm deploy --tier standard

Best Practices

Add structured logging

Use JSON logs for easier parsing:

import logging
import json

logging.info(json.dumps({
    "event": "request",
    "path": "/api/items",
    "duration_ms": 45
}))

Log at appropriate levels

DEBUG: Detailed debugging info
INFO: Normal operation events
WARNING: Something unexpected but handled
ERROR: Something failed

Include context

Include request IDs, user IDs, etc. to trace issues:

logger.info(f"Processing order {order_id} for user {user_id}")

Don't log secrets

Never log API keys, passwords, or PII. Runtime redacts known secrets, but be careful.

runtm logs - CLI reference
Logs API - API reference

Open Source

Guides

Features

OSS Templates

CLI Reference

Self-Hosting

OSS API

Deployments

Logs

Domains

User

Logs & Debugging

Logs & Debugging

Log Types

Basic Commands

Search & Filter

Single Keyword

Multiple Keywords (OR)

Regex Patterns

Pipe-Friendly Output

Raw Mode

Piping to grep

Piping to Other Tools

JSON Output

Processing with jq

Processing with Python

Common Debug Scenarios

Build Failures

Deploy Failures

Runtime Errors

Health Check Debugging

Testing Locally

If Health Checks Fail

Environment Variable Issues

Missing Variables

Wrong Values

Performance Debugging

Slow Requests

Memory Issues

Best Practices

​Logs & Debugging

​Log Types

​Basic Commands

​Search & Filter

​Single Keyword

​Multiple Keywords (OR)

​Regex Patterns

​Pipe-Friendly Output

​Raw Mode

​Piping to grep

​Piping to Other Tools

​JSON Output

​Processing with jq

​Processing with Python

​Common Debug Scenarios

​Build Failures

​Deploy Failures

​Runtime Errors

​Health Check Debugging

​Testing Locally

​If Health Checks Fail

​Environment Variable Issues

​Missing Variables

​Wrong Values

​Performance Debugging

​Slow Requests

​Memory Issues

​Best Practices

​Related

Logs & Debugging

Log Types

Basic Commands

Search & Filter

Single Keyword

Multiple Keywords (OR)

Regex Patterns

Pipe-Friendly Output

Raw Mode

Piping to grep

Piping to Other Tools

JSON Output

Processing with jq

Processing with Python

Common Debug Scenarios

Build Failures

Deploy Failures

Runtime Errors

Health Check Debugging

Testing Locally

If Health Checks Fail

Environment Variable Issues

Missing Variables

Wrong Values

Performance Debugging

Slow Requests

Memory Issues

Best Practices

Related