Logs & Monitoring

System logs help you track activity, diagnose issues, and monitor your PteroCA installation. This guide covers all logging and monitoring features.

Accessing Logs

To view logs:

1. Click Logs in the admin sidebar

2. Choose log type:

   • System Logs - All system actions

   • Email Logs - Outgoing email history

   • Server Logs - Server-specific events

Required permission: access_logs or admin role

System Logs

What is Logged

System logs record all significant actions:

User Actions:

• Login/logout

• Registration

• Password changes

• Profile updates

Server Operations:

• Server creation

• Server suspension/unsuspension

• Server deletion

• Server modifications

• Ownership transfers

Financial Transactions:

• Purchases

• Balance top-ups

• Renewals

• Refunds/adjustments

Administrative Actions:

• User management

• Product changes

• Settings modifications

• Role assignments

Log Entry Information

Each log entry contains:

Who:

• User - Who performed the action

• IP Address - Source IP

• User Agent - Browser/device information

What:

• Action - Type of operation

• Details - Specific information (JSON format)

• Entity - What was affected

When:

• Created At - Timestamp

Viewing System Logs

To browse logs:

1. Go to Logs → System Logs

2. View chronological list of actions

Filter options:

• By user (email or ID)

• By action type

• By date range

• By IP address

Search:

• Search log details

• Find specific actions

• Locate events

Common Log Actions

User-related:

• user.created - New user registered

• user.updated - User profile modified

• user.deleted - User account deleted

• user.login - Successful login

• user.logout - User logged out

Server-related:

• server.created - New server purchased

• server.updated - Server modified

• server.suspended - Server suspended

• server.unsuspended - Server reactivated

• server.deleted - Server removed

• server.transferred - Ownership changed

Payment-related:

• payment.created - Payment initiated

• payment.completed - Payment successful

• balance.adjusted - Manual balance change

Admin-related:

• product.created - New product

• product.updated - Product modified

• settings.updated - Settings changed

• role.assigned - Role given to user

Email Logs

What is Logged

Email logs track all outgoing emails:

Email types:

• Welcome emails

• Email verification

• Password reset

• Purchase confirmations

• Renewal reminders

• Server suspension notices

• Payment receipts

Email Log Information

Each email log entry shows:

• Email Type — Badge showing the type of email (e.g., renewal_reminder, server_created, payment_confirmation, registration)

• User — The user who received the email

• Server — The associated server (if applicable)

• Metadata — JSON data stored with the email log (e.g., template variables used)

• Sent At — Timestamp when the email was dispatched

Viewing Email Logs

To browse email history:

1. Go to Logs → Email Logs

2. View all sent emails

Filter by:

• Email type

• User

• Date range

Troubleshooting Email Issues

If user didn't receive email:

1. Check email logs - Was it sent?

2. Check spam folder - Email marked as spam?

3. Verify email address - Correct spelling?

4. Check SMTP status - Server reachable?

Common email failures:

• Invalid recipient

• SMTP connection timeout

• Authentication failed

• Spam blocking

• Rate limiting

Solutions:

• Verify SMTP configuration

• Check email server status

• Whitelist sender domain

• Test with different email provider

• Review SMTP credentials

See Email Configuration for SMTP setup.

Server Logs

What is Logged

Server logs track server-specific events:

Server lifecycle:

• Server creation

• Configuration changes

• Status changes

• Suspension/unsuspension

• Deletion

Server operations:

• Renewal attempts

• Resource modifications

• Egg changes

• Node transfers

Server Log Information

Each server log entry shows:

Server:

• Server identifier

• Server name

• Owner

Action:

• Operation performed

• Who performed it

• Result

Details:

• Specific changes made

• Old vs new values

• Error messages (if failed)

Timestamp:

• When action occurred

Viewing Server Logs

To browse server logs:

1. Go to Logs → Server Logs

2. View server-specific events

Filter by:

• Server (by ID or name)

• Owner (user)

• Date range

• Action type

Use cases:

• Track server history

• Investigate server issues

• Audit server modifications

• Troubleshoot renewals

Log Retention

Automatic Cleanup

Logs may be automatically cleaned up to:

• Prevent database bloat

• Improve performance

• Comply with data retention policies

Typical retention:

• System logs: 90 days

• Email logs: 30 days

• Server logs: 60 days

(Configuration varies by installation)

Automatic Log Cleanup Configuration

PteroCA supports automatic log cleanup via two database-level settings (configurable directly in the database or via bin/console):

Setting Key	Type	Default	Description
log_cleanup_enabled	BOOLEAN	false	Enable automatic log deletion
log_cleanup_days_after	NUMBER	30	Delete logs older than this many days

Note: These settings are managed at the system level and do not appear in the Admin Panel settings pages. They can be set directly in the setting database table or left at their defaults.

To update via CLI:

# Enable cleanup with 60-day retention
docker exec pteroca_web_dev bin/console pteroca:setting:update log_cleanup_enabled 1
docker exec pteroca_web_dev bin/console pteroca:setting:update log_cleanup_days_after 60

The cleanup runs via the pteroca:system:cleanup-logs scheduled task. Ensure pteroca:cron:schedule is running.

Manual Cleanup

Run manually:

docker exec pteroca_web_dev bin/console pteroca:system:cleanup-logs

See CLI Commands for details.

Export Before Cleanup

Archive important logs:

1. Filter to desired logs

2. Export to CSV/JSON

3. Store in secure location

4. Use for compliance/auditing

Monitoring Best Practices

Regular Monitoring

Daily checks:

• Failed email deliveries

• Recent user registrations

• Payment transactions

• Server creations

• System errors

Weekly reviews:

• User activity patterns

• Email delivery rates

• Server renewal success

• Error trends

Monthly audits:

• Admin actions

• Balance adjustments

• Security events

• Compliance requirements

Security Monitoring

Watch for:

• Multiple failed logins (brute force)

• Unusual login locations

• Unauthorized admin actions

• Suspicious user registrations

• Mass server deletions

• Unexpected balance changes

Red flags:

• Logins from unexpected countries

• Admin actions at odd hours

• Bulk operations

• Repeated failed operations

Actions if suspicious activity:

1. Review related logs

2. Check user accounts involved

3. Block suspicious accounts

4. Change passwords if compromised

5. Contact affected users

6. Document incident

Performance Monitoring

Track metrics:

• Email delivery success rate

• Server creation speed

• Payment processing time

• User registration trends

Identify bottlenecks:

• Slow operations

• High failure rates

• Resource constraints

Using Logs for Troubleshooting

Common Scenarios

User can't log in:

1. Check system logs for login attempts

2. Review failure reasons

3. Check if account blocked

4. Verify password reset attempts

Server wasn't created:

1. Check server logs for creation attempt

2. Review error messages

3. Check Pterodactyl API logs

4. Verify node availability

Email not delivered:

1. Check email logs for sending attempt

2. Review failure reason

3. Verify SMTP configuration

4. Test with different recipient

Payment not processed:

1. Check system logs for payment events

2. Review payment gateway logs

3. Verify webhook/callback receipt

4. Check for error messages

Investigating Issues

Step-by-step:

1. Identify timeframe - When did issue occur?

2. Find relevant logs - Which log type?

3. Filter by criteria - User, action, date

4. Review details - What happened?

5. Trace sequence - What led to issue?

6. Identify cause - Error message or pattern

7. Implement fix - Based on findings

8. Verify resolution - Check logs after fix

Advanced Monitoring

External Monitoring Tools

Integration options:

• Syslog export

• Log aggregation (ELK stack)

• Monitoring services (Datadog, New Relic)

• Custom scripts

Benefits:

• Real-time alerts

• Advanced analytics

• Long-term storage

• Correlation with infrastructure metrics

Alerting

Set up alerts for:

• Failed payments

• Server creation failures

• Email delivery failures

• Security events

• System errors

Alert methods:

• Email notifications

• SMS/phone

• Slack/Discord webhooks

• PagerDuty integration

Privacy and Compliance

Data Logged

Sensitive information:

• IP addresses

• User agents

• Email addresses

• Actions performed

NOT logged:

• Passwords (hashed only)

• Credit card numbers

• Full payment details

GDPR Compliance

User rights:

• Right to access (view their logs)

• Right to deletion (remove logs)

• Right to portability (export logs)

Implementation:

• Export user-specific logs

• Anonymize logs on request

• Comply with data retention policies

Audit Requirements

For compliance:

• Retain logs for required period

• Provide audit trails

• Document access to logs

• Secure log storage

Troubleshooting

Logs Not Appearing

If logs don't show up:

1. Check logging is enabled

2. Verify log level configuration

3. Check database connectivity

4. Review application logs (server-level)

5. Verify permissions

Cannot Filter Logs

If filters don't work:

1. Clear browser cache

2. Try different browser

3. Check for JavaScript errors

4. Verify database indexes

Performance Issues

If log page is slow:

1. Reduce date range

2. Add more specific filters

3. Clean up old logs

4. Optimize database

5. Consider log archival

Related Guides

• Managing Users - User activity tracking

• Managing Servers - Server event monitoring

• Payments & Orders - Payment transaction logs

• System Configuration - Log settings

Need Help?

For logging and monitoring questions:

• Check FAQ

• Review Troubleshooting Guide

• Join Discord Community

• Contact technical support