Profiling & Debugging

Tools and techniques for debugging and profiling the CPR backend.

Laravel Pail (Log Monitoring)

Laravel Pail provides real-time log tailing in the terminal:

# Start watching logs
php artisan pail

# Filter by level
php artisan pail --filter="error"

Pail is automatically started when running composer dev.

Sentry (Error Tracking)

Sentry is configured for production error tracking and performance monitoring.

SENTRY_LARAVEL_DSN=https://your-dsn@sentry.io/project
SENTRY_TRACES_SAMPLE_RATE=1.0

Sentry automatically captures:

• Unhandled exceptions
• Database query performance
• HTTP request performance
• Queue job failures

See the Sentry tooling page for detailed configuration.

Activity Log (Audit Trail)

Spatie Activity Log tracks all model changes:

// All models use the LogsActivity trait
// Changes are automatically logged to the activity_log table

// Query the log
Activity::causedBy($user)
    ->forSubject($patient)
    ->get();

Debug Mode

DANGER

Never enable APP_DEBUG=true in production. It exposes sensitive information in error responses.

In development, APP_DEBUG=true provides:

• Detailed error pages with stack traces
• Full exception details in API responses
• Query logging in the debug bar

Logging

Log Channels

LOG_CHANNEL=stack    # Uses multiple channels
LOG_LEVEL=debug      # Minimum log level

Writing Logs

use Illuminate\Support\Facades\Log;

Log::info('Patient created', ['patient_id' => $patient->id]);
Log::warning('Stock low', ['item' => $item->name, 'quantity' => $stock]);
Log::error('Payment failed', ['transaction' => $transactionId]);

Log Files

• Development: storage/logs/laravel.log
• Production: Configure external log aggregation (e.g., Sentry, Datadog)

Database Query Debugging

Enable Query Logging

DB::enableQueryLog();

// ... your code ...

dd(DB::getQueryLog());

Detect N+1 Queries

Use Laravel's built-in prevention in development:

// In AppServiceProvider::boot()
Model::preventLazyLoading(! app()->isProduction());

This throws an exception when a relation is lazy-loaded, helping you identify missing eager loads.

PHPStan (Static Analysis)

Run static analysis to catch type errors and potential bugs:

composer stan
# or
vendor/bin/phpstan analyse

See the PHPStan tooling page for configuration details.

Common Debugging Workflows

API Response Issues

1. Check the controller method
2. Check the Form Request validation rules
3. Check the Service method
4. Check the Repository query
5. Check the Resource transformation

Authentication Issues

1. Verify the token is valid: Check personal_access_tokens table
2. Verify Sanctum stateful domains in config/sanctum.php
3. Check CORS configuration
4. Check middleware stack on the route

Branch Context Issues

1. Verify X-Branch-Id header is sent
2. Verify the user has access to the branch (check branch_users pivot)
3. Check the EnsureBranchContext middleware logic