Symfony Performance Analyzer Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require 2a/symfony-performance-analyzer
   

   Add to config/bundles.php:

   return [
       // ...
       Ajenguianis\PerformanceAnalyzerBundle\AjenguianisPerformanceAnalyzerBundle::class => ['all' => true],
   ];
   

2. Basic Configuration Update config/packages/ajenguianis_performance_analyzer.yaml:

   ajenguianis_performance_analyzer:
       enabled: true
       dashboard_path: /_performance
       alerts:
           response_time: 500ms
   

3. First Use Case

   • Access the dashboard at /_performance to see real-time metrics.
   • Run a CLI command (e.g., php bin/console cache:clear) and check the "CLI Performance" tab.

Implementation Patterns

Core Workflows

1. Request Profiling

   • Automatic: Enable via enabled: true in config. No manual instrumentation needed.
   • Manual: Use PerformanceAnalyzer::start() and stop() for granular control:

     use Ajenguianis\PerformanceAnalyzerBundle\PerformanceAnalyzer;
     
     $analyzer = PerformanceAnalyzer::getInstance();
     $analyzer->start('custom_section');
     // ... code ...
     $analyzer->stop('custom_section');
     

2. N+1 Query Detection

   • Database Integration: Works out-of-the-box with Doctrine. Configure thresholds:

     ajenguianis_performance_analyzer:
         n_plus_1:
             max_queries_per_request: 50
             max_duplicates: 3
     

   • Review Reports: Check the "Database" tab in the dashboard for query waterfalls and duplicates.

3. Cognitive Complexity

   • Automated Scanning: Run via CLI:

     php bin/console performance:complexity:scan src/
     

   • Thresholds: Configure in config/packages/ajenguianis_performance_analyzer.yaml:

     complexity:
         max_complexity: 10
         excluded_paths: ['src/Migrations/*']
     

4. CI/CD Integration

   • Generate Reports:

     php bin/console performance:report:generate --format=json --output=report.json
     

   • Badge Output:

     php bin/console performance:badge:generate --threshold=500ms --output=badge.svg
     

   • GitHub Actions Example:

     - name: Run Performance Tests
       run: php bin/console performance:report:generate --format=json
     - name: Upload Report
       uses: actions/upload-artifact@v3
       with:
         name: performance-report
         path: report.json
     

5. Alerting

   • Webhook Alerts: Configure in config/packages/ajenguianis_performance_analyzer.yaml:

     alerts:
         webhook_url: 'https://your-webhook.example.com/alerts'
         enabled: true
     

   • Slack Notifications: Use the performance:alert:slack command with a pre-configured webhook.

Integration Tips

• Symfony Flex: Works seamlessly with Symfony Flex recipes. No manual wiring required.
• Doctrine Events: Extend query analysis by listening to AjenguianisPerformanceAnalyzerBundle\Event\QueryEvent:

  use Ajenguianis\PerformanceAnalyzerBundle\Event\QueryEvent;
  use Symfony\Component\EventDispatcher\EventSubscriberInterface;
  
  class CustomQuerySubscriber implements EventSubscriberInterface
  {
      public static function getSubscribedEvents()
      {
          return [
              QueryEvent::QUERY_EXECUTED => 'onQueryExecuted',
          ];
      }
  
      public function onQueryExecuted(QueryEvent $event)
      {
          if ($event->getQuery()->getSql() === 'SELECT * FROM legacy_table') {
              $event->markAsCritical('Legacy query detected');
          }
      }
  }
  

• Monolog Integration: Forward performance logs to Monolog:

  monolog:
      handlers:
          performance:
              type: stream
              path: "%kernel.logs_dir%/performance.log"
              level: debug
              channels: ["performance"]
  

  Then enable in the bundle config:

  ajenguianis_performance_analyzer:
      logging:
          enabled: true
          channel: performance
  

Gotchas and Tips

Pitfalls

1. Dashboard Security

   • The /_performance endpoint is not secured by default. Protect it in security.yaml:

     access_control:
         - { path: ^/_performance, roles: ROLE_ADMIN }
     

   • For public dashboards, use basic auth or IP whitelisting:

     ajenguianis_performance_analyzer:
         dashboard:
             http_basic_auth:
                 username: admin
                 password: $2y$10$92IXUNpk...  # hashed password
     

2. Performance Overhead

   • Real-time metrics add ~5-10ms overhead per request. Disable for production if critical:

     ajenguianis_performance_analyzer:
         enabled: "%kernel.debug%"  # Only in dev
     

   • Complexity Analysis: Scanning large codebases can be slow. Run in CI, not locally:

     php bin/console performance:complexity:scan --parallel=4 src/
     

3. Doctrine Proxy Issues

   • N+1 detection may miss proxied entities. Exclude known proxies:

     ajenguianis_performance_analyzer:
         n_plus_1:
             excluded_entities: ['App\Entity\Proxy\__CG__\User']
     

4. CLI Command Conflicts

   • Avoid naming custom commands performance:* to prevent conflicts with the bundle’s commands.

Debugging Tips

1. Log Levels

   • Adjust logging verbosity in config/packages/ajenguianis_performance_analyzer.yaml:

     logging:
         level: debug  # Options: error, warning, info, debug
     

2. Query Debugging

   • Enable SQL logging to identify slow queries:

     doctrine:
         dbal:
             logging: true
     

   • Use the performance:query:debug command to inspect specific queries:

     php bin/console performance:query:debug --query="SELECT * FROM users"
     

3. Complexity False Positives

   • Temporarily increase thresholds for legacy code:

     complexity:
         max_complexity: 20
         excluded_methods: ['*get*', '*set*']
     

4. Dashboard Caching

   • Clear the dashboard cache if metrics don’t update:

     php bin/console cache:clear AjenguianisPerformanceAnalyzerBundle
     

Extension Points

1. Custom Metrics

   • Add custom metrics via the PerformanceAnalyzer service:

     $analyzer = PerformanceAnalyzer::getInstance();
     $analyzer->addMetric('custom_metric', 42, 'Custom value');
     

2. Report Customization

   • Extend report templates by overriding the Twig templates in templates/bundles/ajenguianisperformanceanalyzer/:

     templates/
         bundles/
             ajenguianisperformanceanalyzer/
                 report/
                     index.html.twig  # Override default template
     

3. Storage Backends

   • Switch from the default SQLite storage to PostgreSQL or Redis by implementing Ajenguianis\PerformanceAnalyzerBundle\Storage\StorageInterface and configuring:

     ajenguianis_performance_analyzer:
         storage:
             class: App\Storage\CustomPerformanceStorage
     

4. Event Listeners

   • Listen for performance events to react to issues dynamically:

     use Ajenguianis\PerformanceAnalyzerBundle\Event\PerformanceEvent;
     
     $dispatcher->addListener(PerformanceEvent::REQUEST_COMPLETED, function (PerformanceEvent $event) {
         if ($event->getTotalDuration() > 1000) {
             // Trigger fallback logic
         }
     });
     

5. Badge Customization

   • Override badge colors or labels by extending the BadgeGenerator:

     use Ajenguianis\PerformanceAnalyzerBundle\Generator\BadgeGenerator;
     
     class CustomBadgeGenerator extends BadgeGenerator
     {
         protected function getColor(int $score): string
         {
             return $score > 800 ? 'red' : 'yellow';
         }
     }
     

     Then configure in services.yaml:

     Ajenguianis\PerformanceAnalyzerBundle\Generator\BadgeGenerator:
         class: App\Generator\CustomBadgeGenerator