Cli Snapshot Profiler Newrelic Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require aeatech/cli-snapshot-profiler-newrelic-bundle
   

   Enable the bundle in config/bundles.php:

   AEATech\CLISnapshotProfilerNewrelicBundle\AEATechCLISnapshotProfilerNewrelicBundle::class => ['dev' => true, 'prod' => true],
   

2. Configure Environment Variables: Add these to your .env:

   AEA_TECH_CLI_SNAPSHOT_PROFILER_NEWRELIC_APP_NAME="MyCLIApp"
   AEA_TECH_CLI_SNAPSHOT_PROFILER_NEWRELIC_LICENSE="your_newrelic_license_key"
   

3. Enable Profiling: Update config/packages/aea_tech_cli_snapshot_profiler_newrelic.yaml:

   aea_tech_cli_snapshot_profiler_newrelic:
       is_profiling_enabled: true
   

4. First Use Case: Run a CLI command (e.g., php bin/console your:command). New Relic will now profile the execution.

Implementation Patterns

Workflows

1. Profiling CLI Commands:

   • The bundle automatically profiles Symfony CLI commands. No manual instrumentation is required for standard commands.
   • For custom commands, ensure they extend Symfony\Component\Console\Command\Command and are registered as services.

2. Conditional Profiling: Use environment variables or config overrides to toggle profiling dynamically:

   # config/packages/dev/aea_tech_cli_snapshot_profiler_newrelic.yaml
   aea_tech_cli_snapshot_profiler_newrelic:
       is_profiling_enabled: "%kernel.debug%"
   

3. Event-Based Profiling: Configure event matching to profile specific CLI invocations (e.g., by command name or arguments):

   aea_tech_cli_snapshot_profiler_newrelic:
       events:
           - command: "your:command"
             arguments:
                 --force: true
   

4. Integration with Artisan: Profile Artisan commands (e.g., migrations, cache clears) by ensuring they are invoked via symfony/console:

   php bin/console cache:clear --env=prod
   

5. Custom Profiler Extensions: Extend the bundle’s profiler by implementing AEATech\CLISnapshotProfilerNewrelicBundle\Profiler\ProfilerInterface and binding it as a service.

Gotchas and Tips

Pitfalls

1. New Relic Extension Version:

   • Requires ext-newrelic >= 12.1. Older versions may cause errors or incomplete profiling.
   • Verify with:

     php -m | grep newrelic
     

2. Environment-Specific Config:

   • Profiling enabled in prod may impact performance. Test thoroughly in staging first.
   • Use %kernel.debug% or environment-specific configs to avoid accidental production profiling.

3. Command Registration:

   • Only Symfony-registered commands are profiled. Custom scripts (e.g., php your_script.php) require manual instrumentation.

4. License Key Exposure:

   • Ensure AEA_TECH_CLI_SNAPSHOT_PROFILER_NEWRELIC_LICENSE is not committed to version control. Use .env or a secure secrets manager.

5. Profiling Overhead:

   • Profiling adds latency. Disable it in performance-critical paths or use it sparingly in production.

Debugging

1. Logs: Enable debug mode to log profiler events:

   aea_tech_cli_snapshot_profiler_newrelic:
       debug: true
   

   Check var/log/dev.log for errors or warnings.

2. New Relic Dashboard:

   • Verify profiles appear in New Relic’s "CLI" or "Custom" app section.
   • Filter by aea_tech_cli_snapshot_profiler transaction name.

3. Common Errors:

   • "New Relic extension not loaded": Ensure ext-newrelic is installed and enabled.
   • "Invalid license key": Double-check the key in .env and New Relic’s account.
   • "Command not profiled": Confirm the command is registered as a Symfony service.

Tips

1. Exclude Sensitive Commands: Use event matching to exclude commands with sensitive data:

   aea_tech_cli_snapshot_profiler_newrelic:
       events:
           - exclude: true
             command: "user:reset-password"
   

2. Custom Metrics: Add custom metrics via New Relic’s API in your command logic:

   \NewRelic\Agent::recordCustomMetric('Custom/CLI/YourCommand', 42);
   

3. CI/CD Integration: Enable profiling in CI pipelines to catch performance regressions early:

   # .github/workflows/ci.yml
   env:
       AEA_TECH_CLI_SNAPSHOT_PROFILER_NEWRELIC_IS_PROFILING_ENABLED: true
   

4. Performance Baselines: Use New Relic’s "Baseline" feature to track CLI performance trends over time.

5. Bundle Updates: Monitor for updates to the bundle or ext-newrelic that may require config adjustments.