Logs & Monitoring

📊 Access deployment logs, runtime logs, error tracking, and basic performance metrics.

This guide explains WEMAZU's logging system, what gets logged, how to access logs, and what metrics are available.

Table of Contents

  1. Logging Architecture
  2. What Gets Logged
  3. What Does NOT Get Logged
  4. Log Levels
  5. Accessing Logs
  6. Log Retention
  7. Error Tracking
  8. Basic Metrics
  9. Log Filtering

Logging Architecture

Dual Storage System

WEMAZU uses a dual storage logging system:

  1. Database Logs (structured storage)

    • Structured, queryable logs
    • Fast retrieval
    • Filterable by project, deployment, user, etc.

  2. File Logs (app.log, deployment-debug.log, webhook-debug.log)

    • Detailed debugging information
    • Full stack traces
    • System-level operations

Log Sources

Database Logs:

  • User actions (project creation, deployment triggers)
  • System events (webhook received, deployment status changes)
  • Application-level operations

File Logs:

  • Detailed deployment execution
  • Webhook processing
  • System-level debugging
  • Error stack traces

Log Aggregation

The WEMAZU dashboard merges logs from both sources:

  1. Fetches structured logs from the database
  2. Reads file logs from log files
  3. Merges and sorts by timestamp
  4. Displays unified log view

What Gets Logged

Deployment Logs

Deployment Creation:

  • ✅ Project ID
  • ✅ Domain ID
  • ✅ Branch name
  • ✅ Commit SHA
  • ✅ User who triggered deployment
  • ✅ Timestamp

Deployment Execution:

  • ✅ Server information (host, type)
  • ✅ Deploy path
  • ✅ Git operations (for SSH deployments)
  • ✅ File upload progress (for FTP/SFTP)
  • ✅ Command output (stdout/stderr)
  • ✅ Execution duration

Deployment Status Changes:

  • ✅ Status transitions (queued → building → success/failed)
  • ✅ Build start/completion timestamps
  • ✅ Error messages (if failed)

Example Log Entry:

{
  "level": "info",
  "message": "Deployment started",
  "action": "deployment.create",
  "project_id": "abc123...",
  "domain_id": "def456...",
  "branch": "main",
  "commit_sha": "abc123def456...",
  "simezu_user_id": "user123...",
  "source": "user",
  "created_at": "2025-01-25T10:00:00Z"
}

Project Logs

Project Creation:

  • ✅ Project name
  • ✅ GitHub owner/repo
  • ✅ User who created project

Project Updates:

  • ✅ Changes made (field-by-field)
  • ✅ User who made changes
  • ✅ Timestamp

Project Deletion:

  • ✅ Project ID
  • ✅ Project name
  • ✅ User who deleted
  • ✅ Timestamp

Domain Logs

Domain Creation:

  • ✅ Domain name
  • ✅ Server ID
  • ✅ Deploy path
  • ✅ Branch configurations
  • ✅ User who created

Domain Updates:

  • ✅ Changes made
  • ✅ Status changes
  • ✅ User who made changes

Domain Deletion:

  • ✅ Domain ID
  • ✅ Domain name
  • ✅ User who deleted

Server Logs

Server Actions:

  • ✅ Server creation (name, type, host, port)
  • ✅ Server updates (changes made)
  • ✅ Connection tests (success/failure, error details)
  • ✅ Server deletion

Example:

{
  "level": "info",
  "message": "Server connection test successful",
  "action": "server.test_connection",
  "server_id": "server123...",
  "server_type": "vps",
  "host": "your-server-ip",
  "port": 22,
  "result": "success"
}

Webhook Logs

Webhook Received:

  • ✅ Event type (push, ping, etc.)
  • ✅ Repository (owner/repo)
  • ✅ Branch
  • ✅ Commit information
  • ✅ Processing result

Webhook Creation:

  • ✅ GitHub API response
  • ✅ Webhook URL
  • ✅ Webhook secret
  • ✅ Success/failure

Example:

{
  "level": "info",
  "message": "GitHub webhook received",
  "action": "webhook.received",
  "event": "push",
  "repository": "atypisch/testdeploy",
  "branch": "main",
  "commit_sha": "abc123...",
  "source": "github"
}

Application Logs

System Operations:

  • ✅ Database operations (if errors occur)
  • ✅ API requests (authentication, authorization)
  • ✅ Service initialization
  • ✅ Configuration loading

Error Logs:

  • ✅ Exception messages
  • ✅ Stack traces (truncated to 1000 chars)
  • ✅ Error context (file, line, function)
  • ✅ Suggested actions

What Does NOT Get Logged

Sensitive Information

WEMAZU does not log:

  • ❌ Passwords: Server passwords, GitHub tokens (encrypted), user passwords
  • ❌ API Keys: Third-party API keys, service credentials
  • ❌ Personal Data: User email addresses (only user IDs), personal information
  • ❌ File Contents: Actual file contents during deployment (only file names and counts)

Runtime Application Logs

WEMAZU does not log:

  • ❌ Application-level logs: Logs from your deployed application (PHP error logs, application logs)
  • ❌ Server logs: Apache/Nginx access logs, server error logs
  • ❌ Database queries: Queries executed by your application
  • ❌ Performance metrics: Response times, memory usage of your application

Note: WEMAZU logs deployment operations, not runtime application behavior. For application logs, check your server's log files directly.

External Service Logs

WEMAZU does not log:

  • ❌ GitHub API logs: Detailed GitHub API request/response logs (only success/failure)
  • ❌ SIMEZU API logs: Authentication API calls (only authentication results)
  • ❌ Third-party service logs: CDN logs, monitoring service logs

Log Levels

Available Levels

WEMAZU uses four log levels:

  1. info: Normal operations, successful actions

    • Project creation
    • Successful deployments
    • Status updates

  2. warning: Non-critical issues

    • Webhook creation warnings
    • Non-fatal errors
    • Deprecated feature usage

  3. error: Failures, exceptions

    • Deployment failures
    • API errors
    • Database errors
    • Connection failures

  4. debug: Detailed debugging information

    • Step-by-step execution
    • Variable dumps
    • Detailed stack traces

Log Level Usage

Info Level:

{
  "level": "info",
  "message": "Deployment completed successfully",
  "action": "deployment.success",
  "deployment_id": "abc123..."
}

Warning Level:

{
  "level": "warning",
  "message": "Webhook URL is localhost, GitHub may reject it",
  "action": "webhook.create.warning",
  "webhook_url": "http://localhost/wemazu/backend/api/webhooks/github"
}

Error Level:

{
  "level": "error",
  "message": "Deployment failed: Connection timeout",
  "action": "deployment.failed",
  "error": "Connection timeout after 30 seconds",
  "stack_trace": "...",
  "suggested_action": "Check server connectivity and firewall settings"
}

Debug Level:

{
  "level": "debug",
  "message": "Executing git pull",
  "action": "deployment.git_pull",
  "command": "git pull origin main",
  "output": "Already up to date."
}

Accessing Logs

Dashboard Logs View

Location: Dashboard → Logs

Features:

  • ✅ Unified view of database and file logs
  • ✅ Real-time updates (refreshes every 30 seconds)
  • ✅ Filtering by level, source, action
  • ✅ Search functionality
  • ✅ Export logs (download as JSON)

Log Types

Application Logs:

  • Database logs (structured)
  • File logs (app.log)
  • Merged and sorted by timestamp

System Logs:

  • deployment-debug.log: Detailed deployment execution
  • webhook-debug.log: Webhook processing
  • app.log: Application-level logs

API Access

Endpoint: GET /api/logs

Query Parameters:

  • level: Filter by level (info, warning, error, debug, all)
  • source: Filter by source (GitHub, Server, Local, System, all)
  • action: Filter by action type (e.g., deployment.create)
  • project_id: Filter by project
  • deployment_id: Filter by deployment
  • limit: Max results (default 100, max 1000)
  • offset: Pagination offset

Example Request:

GET /api/logs?level=error&project_id=abc123&limit=50

Example Response:

{
  "logs": [
    {
      "id": "log123...",
      "level": "error",
      "message": "Deployment failed",
      "action": "deployment.failed",
      "project_id": "abc123...",
      "deployment_id": "def456...",
      "created_at": "2025-01-25T10:00:00Z",
      "context": {
        "error": "Connection timeout",
        "suggested_action": "Check server connectivity"
      }
    }
  ]
}

File Log Access

File Locations:

  • Application logs: app.log
  • Deployment execution logs: deployment-debug.log
  • Webhook processing logs: webhook-debug.log

Note: Exact file paths depend on your WEMAZU installation. Check your server configuration for the exact locations.

Access Methods:

  1. Via Dashboard: System logs tab
  2. Via SSH: Direct file access on server
  3. Via API: GET /api/logs/system?type=deployment

Log Retention

Database Logs

Retention Policy:

  • ✅ No automatic deletion: Logs are kept indefinitely
  • ⚠️ Manual cleanup: You can delete old logs via API or database
  • ⚠️ Storage consideration: Large deployments may generate many logs

Recommendation:

  • Keep logs for at least 90 days for troubleshooting
  • Archive older logs if storage is a concern
  • Export important logs before deletion

File Logs

Retention Policy:

  • ✅ Rotation: Logs may be rotated by system (logrotate, etc.)
  • ⚠️ Size limits: Large log files may be truncated
  • ⚠️ Manual cleanup: Old logs should be cleaned up manually

File Log Sizes:

  • app.log: Can grow large, should be rotated
  • deployment-debug.log: Detailed per-deployment, can be large
  • webhook-debug.log: Per-webhook, moderate size

Best Practices:

  1. Rotate logs: Use logrotate or similar tools
  2. Archive old logs: Compress and archive logs older than 30 days
  3. Monitor disk space: Ensure sufficient disk space for logs
  4. Clean up: Periodically clean up very old logs (90+ days)

Log Cleanup

Manual Cleanup (Database):

-- Delete logs older than 90 days
DELETE FROM logs 
WHERE created_at < DATE_SUB(NOW(), INTERVAL 90 DAY);

Manual Cleanup (Files):

# Archive old logs
tar -czf logs-archive-$(date +%Y%m%d).tar.gz backend/storage/logs/*.log

# Remove archived logs
rm backend/storage/logs/*.log

Error Tracking

Error Visibility

Where Errors Appear:

  1. Dashboard Logs: Filter by level=error
  2. Deployment Detail: Failed deployments show error message
  3. Domain Status: Domains with failed deployments show error status
  4. System Logs: Detailed error logs in file logs

Error Information

Error Context:

  • ✅ Error message
  • ✅ Stack trace (truncated to 1000 chars)
  • ✅ Deployment context (project, domain, branch, commit)
  • ✅ Suggested action
  • ✅ Timestamp

Example Error Log:

{
  "level": "error",
  "message": "Deployment failed: Git pull failed",
  "action": "deployment.failed",
  "project_id": "abc123...",
  "domain_id": "def456...",
  "deployment_id": "ghi789...",
  "error": "fatal: not a git repository",
  "stack_trace": "DeploymentService::executeSshDeployment()...",
  "suggested_action": "Ensure repository exists on server and path is correct",
  "created_at": "2025-01-25T10:00:00Z"
}

Error Summary

Dashboard Error Summary:

  • Location: Dashboard → Error Summary widget
  • Shows: Recent errors (last 24 hours)
  • Filters: By project, by level, by source

API Endpoint: GET /api/logs/summary

Response:

{
  "errors": 5,
  "warnings": 12,
  "since": "2025-01-24T10:00:00Z",
  "recent_errors": [
    {
      "level": "error",
      "message": "Deployment failed",
      "project_id": "abc123...",
      "created_at": "2025-01-25T09:00:00Z"
    }
  ]
}

Basic Metrics

Available Metrics

WEMAZU provides basic metrics (not comprehensive performance monitoring):

Deployment Metrics:

  • ✅ Total deployments (success/failed)
  • ✅ Deployment duration (average, min, max) - calculated from build_started_at and build_completed_at
  • ✅ Success rate (percentage)

Project Metrics:

  • ✅ Number of projects
  • ✅ Number of domains
  • ✅ Number of servers

Log Metrics:

  • ✅ Error count (last 24 hours)
  • ✅ Warning count (last 24 hours)
  • ✅ Log volume (logs per day)

Metrics Access

Dashboard Widgets:

  • Deployment success rate
  • Recent errors
  • Active projects

API Endpoints:

  • GET /api/logs/summary: Error summary
  • GET /api/projects: Project count
  • GET /api/deployments: Deployment statistics

Metrics Limitations

What WEMAZU Does NOT Track:

  • ❌ Application Performance: Response times, memory usage, CPU usage
  • ❌ Server Metrics: Server CPU, memory, disk usage
  • ❌ Network Metrics: Bandwidth, latency
  • ❌ User Metrics: User activity, page views, conversions

For Comprehensive Monitoring:

  • Use external monitoring tools (Datadog, New Relic, etc.)
  • Set up server monitoring (Prometheus, Grafana, etc.)
  • Use application-level monitoring (APM tools)

Log Filtering

Filter Options

By Level:

  • all: All log levels
  • info: Info logs only
  • warning: Warning logs only
  • error: Error logs only
  • debug: Debug logs only
  • actions: Action logs only

By Source:

  • all: All sources
  • GitHub: GitHub webhook logs
  • Server: Server operation logs
  • Local: Local operation logs
  • System: System-level logs

By Action:

  • Filter by specific action type (e.g., deployment.create, webhook.received)

By Project:

  • Filter logs for specific project

By Deployment:

  • Filter logs for specific deployment

Filtering in Dashboard

  1. Go to Dashboard → Logs
  2. Select Level filter (dropdown)
  3. Select Source filter (if available)
  4. Enter Search term (searches message and context)
  5. Logs update automatically

Filtering via API

Example:

# Get error logs for a project
GET /api/logs?level=error&project_id=abc123

# Get deployment logs
GET /api/logs?action=deployment.create

# Get recent errors
GET /api/logs?level=error&limit=50

Log Format

Database Log Format

Log Entry Structure:
Each log entry contains:

  • Unique log ID
  • Log level (info, warning, error, debug)
  • Message text
  • Context (JSON with additional metadata)
  • User ID (if user-specific)
  • Project ID (if project-specific)
  • Deployment ID (if deployment-specific)
  • Creation timestamp

Context JSON Structure:

{
  "action": "deployment.create",
  "source": "user",
  "project_id": "abc123...",
  "deployment_id": "def456...",
  "branch": "main",
  "commit_sha": "abc123def456...",
  "error": "Connection timeout",
  "suggested_action": "Check server connectivity"
}

File Log Format

App Log Format:

[2025-01-25 10:00:00] [info] [Server] [deployment.create] Deployment started {context_json}

Deployment Debug Log Format:

[2025-01-25 10:00:00] [DeploymentService::deployDomain] Starting deployment...
[2025-01-25 10:00:01] [DeploymentService::deployDomain] Domain found: example.com
[2025-01-25 10:00:02] [DeploymentService::executeSshDeployment] Executing git pull...

Troubleshooting

"No logs showing"

Problem: Dashboard shows no logs.

Check:

  1. Verify logs exist in the system
  2. Check that log files are accessible
  3. Ensure user has access to projects
  4. Verify filters are not too restrictive

Solution:

  1. Check database connection
  2. Verify log files exist
  3. Clear filters and refresh
  4. Check browser console for errors

"Logs not updating"

Problem: Logs do not refresh automatically.

Check:

  1. Dashboard refresh interval (30 seconds)
  2. Browser is not paused/backgrounded
  3. API endpoint is accessible

Solution:

  1. Manually refresh page
  2. Check network tab for API calls
  3. Verify API endpoint responds

"Too many logs"

Problem: Dashboard is slow due to too many logs.

Solution:

  1. Use filters to narrow down logs
  2. Reduce limit parameter
  3. Clean up old logs (see Log Retention)
  4. Use pagination (offset parameter)

Next Steps: