Skip to main content

Logging

BugPin uses structured logging with different outputs depending on your deployment method. Logs are accessible through Docker's built-in log commands or the systemd journal. This guide covers viewing logs in real time, filtering by log level, configuring log rotation, and common patterns for diagnosing issues.

Log Levels​

BugPin supports four log levels (configurable via LOG_LEVEL environment variable):

LevelDescriptionUse Case
debugVerbose diagnostic informationDevelopment, troubleshooting
infoGeneral informational messagesProduction (default)
warnWarning messages for potential issuesProduction
errorError messages for failuresProduction

Default log levels:

  • Development: debug
  • Production: info

Set custom log level:

See deployment-specific configuration below (Docker or systemd).

Log Format​

All logs follow this structured format:

[2026-01-05T16:00:00.000Z] [INFO] Server started on port 7300
[2026-01-05T16:00:01.123Z] [DEBUG] [req-abc123] GET /api/reports
[2026-01-05T16:00:01.456Z] [ERROR] Database connection failed {"error": "ECONNREFUSED"}

Format:

  • [timestamp] - ISO 8601 timestamp
  • [level] - Log level (DEBUG, INFO, WARN, ERROR)
  • [requestId] - Optional request correlation ID
  • message - Log message
  • {context} - Optional JSON context with additional data

Deployment Methods​

BugPin can be deployed in two ways, each with its own logging system:

MethodPlatformSetup RequiredLogs Location
DockerAnyDocker setupDocker logs (docker compose logs)
systemdLinuxsystemd setupsystemd journal (journalctl)

Choose your deployment:

info

systemd is a process manager that must be configured before you can view logs. Follow the systemd setup guide first.

Docker Logging​

View Logs​

# View all logs
docker compose logs

# Follow logs in real-time
docker compose logs -f

# Last 100 lines
docker compose logs --tail=100

# Logs from specific time
docker compose logs --since "2026-01-05T15:00:00"
docker compose logs --since "1h"
docker compose logs --since "30m"

# Show timestamps
docker compose logs -t

Log Storage​

Docker stores logs in JSON format at:

/var/lib/docker/containers/<container-id>/<container-id>-json.log

Configure Log Rotation​

Add to docker-compose.yml:

services:
  bugpin:
    image: registry.arantic.cloud/bugpin/bugpin:latest
    logging:
      driver: "json-file"
      options:
        max-size: "10m"      # Max size per log file
        max-file: "3"        # Keep 3 rotated files
        compress: "true"     # Compress rotated logs

Alternative Log Drivers​

Local File Driver​

logging:
  driver: "local"
  options:
    max-size: "10m"
    max-file: "5"

Syslog​

logging:
  driver: "syslog"
  options:
    syslog-address: "tcp://localhost:514"
    tag: "bugpin"

Fluentd​

logging:
  driver: "fluentd"
  options:
    fluentd-address: "localhost:24224"
    tag: "bugpin"

Export Docker Logs​

# Export to file
docker compose logs > bugpin-logs.txt

# Export with timestamps
docker compose logs -t > bugpin-logs-$(date +%Y%m%d).txt

# Export specific time range
docker compose logs --since "2026-01-05" --until "2026-01-06" > bugpin-logs-jan5.txt

systemd Logging​

View Logs​

# View all logs
sudo journalctl -u bugpin

# Follow logs in real-time
sudo journalctl -u bugpin -f

# Last 100 lines
sudo journalctl -u bugpin -n 100

# Logs since specific time
sudo journalctl -u bugpin --since "2026-01-05 15:00:00"
sudo journalctl -u bugpin --since "1 hour ago"
sudo journalctl -u bugpin --since today
sudo journalctl -u bugpin --since yesterday

# Logs with specific priority
sudo journalctl -u bugpin -p err        # Errors only
sudo journalctl -u bugpin -p warning    # Warnings and above

# Show timestamps
sudo journalctl -u bugpin -o short-iso

# Show with full details
sudo journalctl -u bugpin -o verbose

# JSON format
sudo journalctl -u bugpin -o json

Log Storage​

systemd stores logs in the journal:

/var/log/journal/

Export systemd Logs​

# Export to file
sudo journalctl -u bugpin > bugpin-logs.txt

# Export with timestamps
sudo journalctl -u bugpin -o short-iso > bugpin-$(date +%Y%m%d).txt

# Export specific time range
sudo journalctl -u bugpin --since "2026-01-05" --until "2026-01-06" > bugpin-jan5.txt

# Export as JSON
sudo journalctl -u bugpin -o json > bugpin-logs.json

Log Rotation​

systemd journal rotates automatically based on:

# /etc/systemd/journald.conf
SystemMaxUse=500M       # Max disk space for journal
SystemKeepFree=1G       # Keep 1GB free on disk
SystemMaxFileSize=50M   # Max size per journal file
MaxRetentionSec=1month  # Keep logs for 1 month

Apply changes:

sudo systemctl restart systemd-journald

Vacuum Old Logs​

# Remove logs older than 7 days
sudo journalctl --vacuum-time=7d

# Limit total journal size to 500MB
sudo journalctl --vacuum-size=500M

# Remove all but last 10 journal files
sudo journalctl --vacuum-files=10

Development Logging​

When running with bun run dev, logs output directly to your terminal (stdout/stderr).

Custom Log Level​

# Verbose debugging
LOG_LEVEL=debug bun run dev

# Production-like logging
LOG_LEVEL=info bun run dev

# Only errors
LOG_LEVEL=error bun run dev

Save Development Logs​

# Save to file
bun run dev > dev.log 2>&1

# Save with timestamps
bun run dev 2>&1 | ts '[%Y-%m-%d %H:%M:%S]' > dev.log

# Tee to both terminal and file
bun run dev 2>&1 | tee dev.log

Log Analysis​

Common Patterns​

Find Errors​

# Docker
docker compose logs | grep ERROR

# systemd
sudo journalctl -u bugpin -p err

Find Slow Requests​

# Search for requests taking > 1000ms
docker compose logs | grep -E "duration.*[0-9]{4,}ms"

Count Log Levels​

# Docker
docker compose logs | grep -oP '\[(DEBUG|INFO|WARN|ERROR)\]' | sort | uniq -c

# systemd
sudo journalctl -u bugpin | grep -oP '\[(DEBUG|INFO|WARN|ERROR)\]' | sort | uniq -c

Find Specific Request​

# Search by request ID
docker compose logs | grep "req-abc123"

Log Monitoring Tools​

# Install
sudo apt install lnav  # Ubuntu/Debian
brew install lnav      # macOS

# View Docker logs
docker compose logs -f | lnav

# View systemd logs
sudo journalctl -u bugpin -f | lnav

Troubleshooting​

No Logs Appearing​

Docker:

# Check if container is running
docker compose ps

# Check log driver
docker inspect bugpin | grep LogConfig

# Check logs location
docker inspect bugpin | grep LogPath

systemd:

# Check service status
sudo systemctl status bugpin

# Check journal is running
sudo systemctl status systemd-journald

# Check disk space
df -h /var/log/

Log Files Too Large​

Docker:

# Add log rotation in docker-compose.yml
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

systemd:

# Limit journal size
sudo journalctl --vacuum-size=500M

Logs Missing Context​

Check LOG_LEVEL environment variable:

# Docker
docker compose exec bugpin env | grep LOG_LEVEL

# systemd
sudo systemctl show bugpin -p Environment

Set to debug for more details:

# Docker: Add to docker-compose.yml
environment:
  - LOG_LEVEL=debug

# systemd: Add to bugpin.service
Environment=LOG_LEVEL=debug

We use cookies for analytics to improve our website. More information in our Privacy Policy.