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

Go to Alpha Insights → Settings
Navigate to the Debug settings page
You'll see four tabs: General, Sessions, Data Management, and Migrations

Page Tabs

General: Debug order calculations and WP Davies logs (default)
Sessions: Review raw session rows, calculated traffic source, landing-page parameters, and fold-out events
Data Management: Inspect and delete Alpha Insights-generated data
Migrations: Review and manually run data migrations after plugin updates

Sessions Debug

Use the Sessions tab to inspect how Alpha Insights classified each visit. This is especially useful when reviewing Direct traffic that you expected to attribute elsewhere.

What It Shows

Session ID: Analytics session identifier
Started: Session start time in your site timezone, plus duration
IP address: Visitor IP stored on the session
Landing page: Path and query parameters broken out as key/value pairs
User agent: Raw user agent stored with the session
Source: The same calculated traffic source used in reports (from landing-page parameters, referral URL, and Facebook/Instagram in-app user agents)

Filters

Date range: Defaults to the last 30 days
Session source: Filter to Direct, Organic, paid channels, and other calculated sources

Results are paginated at 100 sessions per page. Expand a row to see referral URL, full landing page, device details, and every stored event for that session.

Use Export to CSV to download every matching session, not just the current page. The modal lets you choose a flat session data file or a flat event data file.

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

Find the order ID you want to debug
- Go to WooCommerce → Orders
- Find the order (e.g., #5469)
- Note the order ID number
On the Debug Settings General tab, enter order ID in "Debug order ID" field
Click Debug button
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 on the General tab.

Log Display

The log section shows all available log files in a split-panel interface. Use Delete All Logs in the logs header to remove every log file at once.

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:

Open Facebook API Log
Look for ERROR entries
Check error messages
Note timestamps of failures
Provide to support if needed

Google Ads problems:

Review Google Ads API Error Log
Check for authentication errors
Look for API quota issues
Verify conversion tracking events

Calculation discrepancies:

Check Calculation Log
Look for order-specific entries
Identify when calculation was last updated
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:

Debug the specific order in question
Take screenshot of output or copy text
Note the order ID clearly
Include in support ticket

Log excerpts:

Navigate to relevant log file
Screenshot error entries
Include timestamps
Note which log file

Performance data:

Screenshot performance report table
Note which operations are slow
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

Note the order ID
Go to Debug Settings
Enter order ID and click Debug
Review cost breakdown
Identify which cost is unexpectedly high
Check if product cost is correct
Verify payment gateway fee calculation
Confirm shipping cost is accurate

Scenario: Facebook Sync Not Working

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

Scenario: Reports Loading Slowly

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

Scenario: Missing Product Costs

Debug an order with the affected product
Review line item details
Check product cost field
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!