223 lines
6.3 KiB
Markdown
223 lines
6.3 KiB
Markdown
# PayPal Payment Flow Logging Enhancement - Summary
|
|
|
|
## Problem Addressed
|
|
|
|
Users were experiencing intermittent errors when clicking "Pay from PayPal" button:
|
|
- **JSON parsing errors**
|
|
- **HTTP ERROR 500**
|
|
- **"Currently unable to handle this request"** errors
|
|
|
|
These errors would "flip-flop" between different types, making diagnosis difficult without proper logging.
|
|
|
|
## Solution Implemented
|
|
|
|
Added comprehensive logging throughout the entire PayPal payment flow to capture:
|
|
- All request/response data
|
|
- Error details with full context
|
|
- Unique request IDs for tracking
|
|
- Database operations and results
|
|
- Client-side JavaScript errors
|
|
|
|
## What Changed
|
|
|
|
### Modified Files
|
|
|
|
1. **`api/create_order.php`** - Enhanced with comprehensive logging
|
|
- Logs every step of order creation
|
|
- Captures request data, OAuth process, PayPal API calls
|
|
- Returns request IDs in error messages for tracking
|
|
- Logs to: `logs/paypal_create_order.log`
|
|
|
|
2. **`api/capture_order.php`** - Enhanced existing logging
|
|
- Logs payment capture process
|
|
- Tracks database operations (invoice updates, order creation)
|
|
- Captures all error conditions
|
|
- Logs to: `logs/paypal_capture.log`
|
|
|
|
3. **`cart.php`** - Improved client-side error handling
|
|
- Better error messages with reference IDs
|
|
- Enhanced console logging for debugging
|
|
- Sends errors to server for centralized logging
|
|
- Better user feedback during payment process
|
|
|
|
4. **`api/log_error.php`** - NEW: Client error logging endpoint
|
|
- Captures JavaScript errors from browser
|
|
- Logs to: `logs/client_errors.log`
|
|
|
|
### New Files
|
|
|
|
1. **`PAYPAL_DEBUGGING_GUIDE.md`** - Comprehensive debugging guide
|
|
- How to read logs
|
|
- Common issues and solutions
|
|
- Request flow documentation
|
|
- Monitoring commands
|
|
|
|
2. **`QUICK_DEBUG_REFERENCE.md`** - Quick reference card
|
|
- Common commands
|
|
- Error patterns
|
|
- Quick fixes
|
|
- Troubleshooting checklist
|
|
|
|
## How to Use
|
|
|
|
### When an error occurs:
|
|
|
|
1. **User will see an error message with a reference ID**, for example:
|
|
```
|
|
Failed to create order: API error 500 (Ref: req_abc123)
|
|
```
|
|
|
|
2. **Search the logs for that reference ID**:
|
|
```bash
|
|
cd /home/runner/work/GSP/GSP/modules/billing/logs
|
|
grep "req_abc123" paypal_create_order.log
|
|
```
|
|
|
|
3. **Review the full request flow** to identify where it failed
|
|
|
|
4. **Refer to the debugging guide** for common solutions
|
|
|
|
### Monitor logs in real-time:
|
|
|
|
```bash
|
|
cd /home/runner/work/GSP/GSP/modules/billing/logs
|
|
tail -f paypal_*.log
|
|
```
|
|
|
|
### Check for errors:
|
|
|
|
```bash
|
|
cd /home/runner/work/GSP/GSP/modules/billing/logs
|
|
grep -i error paypal_create_order.log
|
|
grep -i failed paypal_capture.log
|
|
```
|
|
|
|
## Log Files
|
|
|
|
All logs are written to: `/modules/billing/logs/`
|
|
|
|
| Log File | Purpose | When Created |
|
|
|----------|---------|--------------|
|
|
| `paypal_create_order.log` | Order creation requests | When user clicks "Pay with PayPal" |
|
|
| `paypal_capture.log` | Payment capture process | After PayPal approval, during payment capture |
|
|
| `client_errors.log` | JavaScript/browser errors | When browser encounters errors |
|
|
|
|
## Request Tracking
|
|
|
|
Each request has a unique ID:
|
|
- **Create order**: `req_XXXXXXXXXXXXX`
|
|
- **Capture order**: `cap_XXXXXXXXXXXXX`
|
|
|
|
These IDs:
|
|
- Appear in error messages shown to users
|
|
- Are logged in every log entry for that request
|
|
- Can be used to track a request through the entire flow
|
|
|
|
## Log Entry Format
|
|
|
|
```
|
|
[TIMESTAMP] [REQUEST_ID] LOG_LABEL
|
|
key => value
|
|
key => value
|
|
--------------------------------------------------------------------------------
|
|
```
|
|
|
|
Example:
|
|
```
|
|
[2025-10-29 21:30:00] [req_abc123] OAUTH_SUCCESS
|
|
token_length => 1024
|
|
--------------------------------------------------------------------------------
|
|
```
|
|
|
|
## What Gets Logged
|
|
|
|
### Create Order Flow (`api/create_order.php`):
|
|
- ✓ Incoming request data (amount, currency, items)
|
|
- ✓ JSON parsing status
|
|
- ✓ OAuth token acquisition
|
|
- ✓ PayPal order creation request/response
|
|
- ✓ All error conditions with full details
|
|
|
|
### Capture Order Flow (`api/capture_order.php`):
|
|
- ✓ Payment capture request
|
|
- ✓ OAuth process
|
|
- ✓ Database connection status
|
|
- ✓ Invoice update queries and results
|
|
- ✓ Order creation/renewal operations
|
|
- ✓ All error conditions with full details
|
|
|
|
### Client-Side (`cart.php` → `log_error.php`):
|
|
- ✓ JavaScript errors
|
|
- ✓ PayPal SDK errors
|
|
- ✓ Network failures
|
|
- ✓ JSON parsing errors
|
|
|
|
## Benefits
|
|
|
|
1. **Full Visibility**: Every step of payment flow is now logged
|
|
2. **Easy Troubleshooting**: Request IDs link user reports to log entries
|
|
3. **Root Cause Analysis**: Can identify exactly where and why failures occur
|
|
4. **Pattern Detection**: Can identify if errors are consistent or intermittent
|
|
5. **Better User Experience**: Users get reference IDs to report issues
|
|
|
|
## Next Steps
|
|
|
|
1. **Monitor the logs** after deploying this change
|
|
2. **Analyze error patterns** to identify the root cause
|
|
3. **Review common errors** in the debugging guide
|
|
4. **Fix underlying issues** once identified
|
|
|
|
## Documentation
|
|
|
|
- **Full Guide**: `PAYPAL_DEBUGGING_GUIDE.md`
|
|
- **Quick Reference**: `QUICK_DEBUG_REFERENCE.md`
|
|
- **This Summary**: `LOGGING_CHANGES_SUMMARY.md`
|
|
|
|
## Testing
|
|
|
|
The logging system has been tested and verified to work correctly. All components:
|
|
- ✓ Write to correct log files
|
|
- ✓ Include proper timestamps and request IDs
|
|
- ✓ Format data correctly
|
|
- ✓ Handle errors gracefully
|
|
|
|
## Maintenance
|
|
|
|
### Log Rotation
|
|
|
|
Logs will grow over time. Consider setting up log rotation:
|
|
|
|
```bash
|
|
# Manual rotation
|
|
cd /home/runner/work/GSP/GSP/modules/billing/logs
|
|
gzip paypal_create_order.log
|
|
mv paypal_create_order.log.gz paypal_create_order.$(date +%Y%m%d).log.gz
|
|
touch paypal_create_order.log
|
|
```
|
|
|
|
Or use `logrotate` (see `PAYPAL_DEBUGGING_GUIDE.md` for details).
|
|
|
|
### Monitoring
|
|
|
|
Set up automated monitoring to alert on:
|
|
- High error rates
|
|
- Specific error patterns (OAuth failures, DB connection issues)
|
|
- Unusual request volumes
|
|
|
|
## Support
|
|
|
|
If you encounter issues or need help interpreting logs:
|
|
|
|
1. Check `PAYPAL_DEBUGGING_GUIDE.md` for common issues
|
|
2. Review `QUICK_DEBUG_REFERENCE.md` for quick fixes
|
|
3. Provide log excerpts (with request IDs) when asking for help
|
|
|
|
## Changes Made By
|
|
|
|
- Enhanced logging system - Added 2025-10-29
|
|
- Documentation created - 2025-10-29
|
|
- Testing completed - 2025-10-29
|
|
|
|
---
|
|
|
|
**The intermittent JSON/HTTP 500 errors should now be fully traceable and debuggable with this comprehensive logging system.**
|