Debug Settings

The Debug Settings page provides powerful tools for troubleshooting, analyzing order calculations, reviewing system logs, and monitoring performance. This page is essential for diagnosing issues, verifying calculations, and understanding how Alpha Insights processes your data.

Accessing Debug Settings

1. Go to Alpha Insights → Settings
2. Navigate to the Debug settings page
3. You'll see debugging tools and system logs

Who Should Use Debug Settings

• Store owners: Verify specific order calculations
• Developers: Troubleshoot integration issues
• Support team: Diagnose problems with guidance from WP Davies support
• Advanced users: Deep dive into plugin operations

Note: This page contains technical information. If you're just getting started, you may not need to use these tools.

Debug Order Calculations

The most useful tool on this page - see complete calculation breakdown for any specific order.

Debug Order ID

What It Does

Produces a complete output of all calculations, costs, and data for a specific order. This shows you exactly how Alpha Insights calculated profit for that order.

How to Use

1. Find the order ID you want to debug
   • Go to WooCommerce → Orders
   • Find the order (e.g., #5469)
   • Note the order ID number
2. On Debug Settings page, enter order ID in "Debug order ID" field
3. Click Debug button
4. Page reloads and shows complete calculation output below

Order Data Dump Output

When you debug an order, you'll see a detailed data dump including:

Order Information

• Order ID: WooCommerce order number
• Order total: Total amount customer paid
• Order status: Current order status
• Payment method: How customer paid
• Shipping method: How order will ship
• Order date: When order was placed
• Currency: Order currency

Revenue Breakdown

• Order total: Full amount charged
• Subtotal: Before tax and shipping
• Tax: Tax amount collected
• Shipping charged: Shipping fee charged to customer
• Discounts: Coupon or discount amounts
• Refunds: Any refunded amounts

Cost Breakdown

• Product costs (COGS): Per product and total
• Custom product costs: Any custom cost fields per product
• Shipping cost: What you paid carrier
• Payment gateway fee: Processing fee
• Custom order costs: Any custom order-level costs
• Total costs: Sum of all costs

Profit Calculations

• Gross profit: Revenue minus order costs
• Gross margin: Profit as percentage
• Net profit: After additional expenses (if applicable)
• Net margin: Net profit percentage

Line Item Details

For each product in the order:

• Product name and ID
• Quantity ordered
• Price per unit
• Cost of goods per unit
• Custom costs per unit
• Line item profit
• Line item margin

Order Meta Data

• All order meta fields
• Alpha Insights custom meta
• Calculation overrides (if any)
• Tracking data (campaigns, UTM, GCLID)
• Custom field values

When to Debug an Order

Verify calculations:

• Order profit seems incorrect
• Want to understand specific cost breakdown
• Checking if costs are being applied correctly

Troubleshoot issues:

• Negative profit on unexpected order
• Costs not matching expectations
• Missing cost data
• Incorrect margin calculations

Support requests:

• WP Davies support asks for order debug data
• Providing detailed information about calculation issue
• Comparing calculations between orders

Understanding Debug Output

Green values: Positive amounts (revenue, profit)

Red values: Negative amounts (costs, refunds, losses)

Bold labels: Key calculation fields

Nested arrays: Related data grouped together

• Line items under "items"
• Costs under "cost_breakdown"
• Meta data under "order_meta"

WP Davies Logs

View system logs from Alpha Insights operations.

Log Display

The log section shows all available log files in a split-panel interface:

Left panel: List of available logs

• Each log file listed by name
• Click log name to view contents
• Active log highlighted
• Scrollable if many logs

Right panel: Log contents

• Shows entries from selected log
• Most recent entries at bottom
• Timestamped entries
• Color-coded by severity (errors in red, etc.)

Common Log Files

Facebook API Log:

• Facebook connection attempts
• Data sync operations
• API errors and responses
• Campaign data fetching

Google Ads API Log:

• Google Ads connection status
• Sync operations
• Conversion tracking events
• API errors

General System Log:

• Plugin activation/deactivation
• Database updates
• Cache operations
• System errors

Calculation Log:

• Order calculation events
• Cost updates
• Batch processing

Reading Log Entries

Each log entry typically includes:

Timestamp: When event occurred

• Format: "2024-10-22 14:35:22"
• Uses WordPress timezone

Severity level:

• ERROR: Something failed (red)
• WARNING: Potential issue (yellow)
• INFO: General information (blue)
• DEBUG: Detailed technical info (gray)

Message: Description of what happened

• Human-readable explanation
• May include IDs, URLs, or values
• Technical details for debugging

Log Management

Automatic cleanup:

• Logs over 10MB are automatically deleted
• Prevents excessive disk space usage
• Keeps most recent entries

Manual log clearing:

• Currently requires FTP/file manager access
• Logs stored in uploads folder
• Can delete log files manually if needed

Using Logs for Troubleshooting

Facebook sync issues:

1. Open Facebook API Log
2. Look for ERROR entries
3. Check error messages
4. Note timestamps of failures
5. Provide to support if needed

Google Ads problems:

1. Review Google Ads API Error Log
2. Check for authentication errors
3. Look for API quota issues
4. Verify conversion tracking events

Calculation discrepancies:

1. Check Calculation Log
2. Look for order-specific entries
3. Identify when calculation was last updated
4. See if overrides were applied

Performance Reports

If available, shows performance metrics for various plugin operations.

Performance Metrics

Performance report table includes:

Report Type: What operation was measured

• Order data fetch
• Product cost calculation
• Report generation
• Cache operations
• API calls

Metrics displayed:

• Execution time: How long operation took (milliseconds)
• Memory usage: RAM used during operation
• Query count: Number of database queries
• Cache hits: How often cache was used
• API calls: External API requests made

Understanding Performance Data

Good performance indicators:

• Low execution times (<1000ms)
• Efficient memory usage (<50MB)
• Minimal database queries (<100)
• High cache hit ratio (>80%)

Performance issues:

• Very long execution times (>5000ms)
• High memory usage (>256MB)
• Excessive queries (>500)
• Low cache effectiveness (<50%)

When to Check Performance

• Site feels slow when viewing reports
• Dashboard takes long to load
• Experiencing timeouts
• Server resource issues
• Optimizing large stores

Debugging Best Practices

Order Debugging

• Start with specific order: Debug individual problematic orders first
• Compare similar orders: Debug working order vs problem order
• Check recent changes: Debug order after making settings changes
• Document findings: Screenshot or copy debug data when reporting issues

Log Review

• Check logs after errors: Immediately after seeing an error
• Look for patterns: Recurring errors indicate systematic issues
• Note timestamps: Correlate log entries with observed issues
• Start with recent entries: Most recent issues are at bottom

Performance Monitoring

• Regular checks: Review performance monthly
• After updates: Check performance after plugin updates
• When issues arise: First place to look for slow performance
• Before optimization: Baseline metrics before making changes

Working with Support

Providing Debug Information

When contacting WP Davies support, they may ask for debug data:

Order debug data:

1. Debug the specific order in question
2. Take screenshot of output or copy text
3. Note the order ID clearly
4. Include in support ticket

Log excerpts:

1. Navigate to relevant log file
2. Screenshot error entries
3. Include timestamps
4. Note which log file

Performance data:

1. Screenshot performance report table
2. Note which operations are slow
3. Include store size context (order count)

What NOT to Share Publicly

Sensitive data in debug output:

• Customer names and addresses
• Full order details
• Payment information
• Access tokens or API keys
• License keys

Share with support only: Debug data should only go to official WP Davies support channels

Common Debug Scenarios

Scenario: Negative Profit on Order

1. Note the order ID
2. Go to Debug Settings
3. Enter order ID and click Debug
4. Review cost breakdown
5. Identify which cost is unexpectedly high
6. Check if product cost is correct
7. Verify payment gateway fee calculation
8. Confirm shipping cost is accurate

Scenario: Facebook Sync Not Working

1. Go to Debug Settings
2. Open Facebook API Log
3. Look for ERROR entries
4. Check error message
5. Common issues:
   • "Token expired" → Reconnect Facebook
   • "Permission denied" → Check ad account access
   • "Rate limit" → Wait and sync will resume

Scenario: Reports Loading Slowly

1. Go to Debug Settings
2. Review Performance Reports
3. Identify slow operations
4. Check execution times
5. If report generation is slow:
   • Clear report cache (General Settings)
   • Reduce date range being queried
   • Contact support if consistently slow

Scenario: Missing Product Costs

1. Debug an order with the affected product
2. Review line item details
3. Check product cost field
4. If showing 0 or default:
   • Go to Cost of Goods Manager
   • Verify product has cost entered
   • Save cost if missing
   • Clear cache
   • Debug order again to verify

Advanced Debugging

For Developers

If you're a developer working with Alpha Insights:

Use WordPress debug constants:

• Enable WP_DEBUG in wp-config.php
• Set WP_DEBUG_LOG to true
• Alpha Insights will log more detailed information

Query Monitor plugin:

• Install Query Monitor
• See database queries from Alpha Insights
• Identify slow queries
• Monitor API calls

Browser developer tools:

• Check AJAX requests in Network tab
• View console for JavaScript errors
• Monitor API responses

Summary

Debug Settings provide:

• Order debugging: Complete calculation breakdowns for any order
• System logs: Detailed operation history and error tracking
• Performance monitoring: Identify slow operations and bottlenecks
• Troubleshooting tools: Essential for diagnosing issues
• Support assistance: Data needed for effective support

While you may not need Debug Settings for everyday use, they're invaluable when something doesn't look right or when you need to verify how Alpha Insights is calculating your store's profitability. Keep this page bookmarked for troubleshooting needs!