Amp Sql Profiler Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle

   composer require --dev async/amp-sql-profiler-bundle
   

   Ensure dev environment only (remove 'test' from bundles.php if auto-added).

2. Replace Amp\Sql\Pool with ProfiledPool In config/services_dev.yaml:

   Amp\Postgres\PostgresConnectionPool: ~  # Replace with your DB driver (e.g., Amp\Mysql\MysqlConnectionPool)
   ScriptFUSION\AmpSqlProfilerBundle\ProfiledPool:
     arguments:
       - '@Amp\Postgres\PostgresConnectionPool'
   

3. Verify Profiler Integration Restart your Symfony dev server (symfony serve --no-tls-verify). Check the Profiler toolbar (top-right) for SQL queries.

First Use Case

• Debug a Slow Query: Use the profiler to identify bottlenecks in Amp SQL queries during development.
• Transaction Inspection: Verify transaction boundaries and nested queries via the profiler’s backtrace.

Implementation Patterns

Workflow Integration

1. Dependency Injection Replace all Amp\Sql\Pool instances in your services with the ProfiledPool alias (via services_dev.yaml). Example:

   services:
     App\Service\QueryService:
       arguments:
         - '@ScriptFUSION\AmpSqlProfilerBundle\ProfiledPool'  # Profiled alias
   

2. Query Analysis

   • Toolbar Summary: Click the SQL icon in the profiler toolbar to see query counts, execution times, and slowest queries.
   • Detailed View: Navigate to /_profiler/[request_id]/sql to inspect individual queries, backtraces, and execution stats.

3. Transaction Handling The profiler groups queries within transactions. Use this to validate:

   $pool = $container->get(ProfiledPool::class);
   $pool->beginTransaction();
   // Queries here will be grouped under the transaction in the profiler.
   

Advanced Patterns

• Conditional Profiling: Disable profiling in production by removing the ProfiledPool alias from services.yaml.
• Custom Data Collection: Extend ProfiledPool to log additional metadata (e.g., custom tags) via the collect() method:

  $pool->collect('custom_tag', 'value');
  

Gotchas and Tips

Pitfalls

1. Circular Dependency

   • Symptom: ProfiledPoolFactory fails with circular reference errors.
   • Fix: Explicitly define the underlying Pool (e.g., Amp\Postgres\PostgresConnectionPool) in services_dev.yaml as shown in the README.

2. Unsupported Features

   • Prepared Statements: Queries using prepared statements may not appear in the profiler. Rewrite or avoid them in dev.
   • Savepoints: Transactions with savepoints (SAVEPOINT) are unsupported. Restructure logic if needed.

3. Profiler Overhead

   • Profiling adds minor latency. Disable in staging/production:

     # config/packages/dev/amp_sql_profiler.yaml
     scriptfusion_amp_sql_profiler:
       enabled: false
     

Debugging Tips

• Missing Queries? Ensure all Amp\Sql\Pool instances are replaced with ProfiledPool. Use Symfony’s debug:container to verify:

  php bin/console debug:container | grep ProfiledPool
  

• Backtrace Clarity The profiler includes backtraces. For cleaner output, ensure your code uses descriptive method names (e.g., fetchUserOrders() instead of query()).

Extension Points

1. Custom Data Collectors Override ScriptFUSION\AmpSqlProfilerBundle\Profiler\Collector\SqlCollector to add custom query metadata:

   class CustomSqlCollector extends SqlCollector {
       public function collect(QueryEvent $event) {
           $event->setData(['custom_field' => 'value']);
           parent::collect($event);
       }
   }
   

   Register it in services_dev.yaml:

   ScriptFUSION\AmpSqlProfilerBundle\Profiler\Collector\SqlCollector:
     class: App\Profiler\CustomSqlCollector
   

2. Query Filtering Filter queries by type or tags in the profiler view by extending the collector’s getQueries() method.

3. Non-Dev Environments Use environment variables to toggle profiling dynamically:

   # config/packages/amp_sql_profiler.yaml
   scriptfusion_amp_sql_profiler:
       enabled: '%env(bool:AMP_SQL_PROFILER_ENABLED)%'