Monitoring Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require becklyn/monitoring
   

   The package auto-registers via Laravel’s service provider discovery (no manual config/app.php edits needed).

2. Basic Usage:

   • Uptime Monitor: All HTML responses automatically include a comment:

     <!-- uptime monitor: $project_name -->
     

     Configure project_name in config/monitoring.php (published via php artisan vendor:publish --tag=monitoring-config).

   • TrackJS Integration: Add the monitoring script to Twig templates:

     {% block javascripts %}
         {{- monitoring_embed() }}
         {{ parent() }}
     {% endblock %}
     

     Requires trackjs.token in config.

3. First Test Case:

   • Verify the uptime comment appears in rendered HTML (e.g., via browser DevTools or curl -I).
   • Check if monitoring_embed() outputs the TrackJS script when trackjs.token is set.

Implementation Patterns

1. HTML Uptime Monitoring

• Workflow:

  • The package hooks into Laravel’s response system to inject the uptime comment after the view is rendered.
  • Customization: Override the comment template by publishing the config and modifying uptime_comment_template:

    'uptime_comment_template' => '<!-- uptime: %s (custom: %s) -->',
    

    (Where %s is replaced with $project_name and a custom suffix.)

• Integration Tip:

  • Use this for third-party uptime monitors (e.g., Pingdom, UptimeRobot). Ensure your project_name matches the monitor’s alias.

2. TrackJS Error Tracking

• Workflow:

  • The monitoring_embed() Twig function outputs the TrackJS script only if trackjs.token is configured.
  • Async Loading: The script is wrapped in a defer attribute by default (check the published config to modify).
  • Environment-Specific: Disable in config/monitoring.php for non-production environments:

    'trackjs' => [
        'token' => env('TRACKJS_TOKEN'),
        'enabled' => env('APP_ENV') === 'production',
    ],
    

• Advanced Use:

  • Pass custom TrackJS options via the monitoring_embed function:

    {{- monitoring_embed({'token': 'custom-token', 'async': false}) }}
    

3. Assets Bundle Integration

• Pattern:
  • The package registers a @monitoring namespace in the Becklyn Assets Bundle (assumed to be a custom asset pipeline).
  • Use Case: If your project uses a custom asset pipeline (e.g., for concatenation/minification), include the monitoring script via:

    // In your main JS file
    require('@monitoring/script');
    

  • Fallback: If not using the Assets Bundle, rely on the Twig monitoring_embed() function.

Gotchas and Tips

1. Configuration Pitfalls

• Missing Config:

  • The package does not auto-publish the config. Run:

    php artisan vendor:publish --tag=monitoring-config
    

    to generate config/monitoring.php. Without this, project_name and trackjs.token will default to null.

• Environment Variables:

  • trackjs.token should be set via .env (e.g., TRACKJS_TOKEN=your_token_here). Hardcoding in config/monitoring.php is not recommended.

2. TrackJS Quirks

• Script Injection Timing:

  • The monitoring_embed() function outputs the script before other JS in the javascripts block. If you need it to load last, reorder the Twig blocks or use a custom template.
  • Debugging: Check the rendered HTML to confirm the script tag appears. If missing, verify trackjs.token is set and the config is published.

• Token Validation:

  • TrackJS may reject invalid tokens silently. Test by checking the Network tab in DevTools for a 403 response from trackjs.com.

3. Uptime Monitor Edge Cases

• Non-HTML Responses:

  • The uptime comment is only added to HTML responses. API responses (JSON/XML) or non-text responses (e.g., PDFs) will not include it.
  • Workaround: Manually add the comment in API controllers if needed:

    Response::macro('withUptimeComment', function ($projectName) {
        return $this->header('X-Uptime-Monitor', $projectName);
    });
    

• Project Name Sanitization:

  • The project_name is used in the uptime comment. If it contains special characters (e.g., /, :), some monitors may fail to parse it. Sanitize it in the config:

    'project_name' => str_replace(['/', ':'], '-', env('APP_NAME')),
    

4. Debugging Tips

• Log Output:

  • The package logs configuration issues to Laravel’s log channel (e.g., storage/logs/laravel.log). Check for:

    [Becklyn\Monitoring] Config not published. Using defaults.
    

    or

    [Becklyn\Monitoring] TrackJS token not set. Skipping script injection.
    

• Asset Pipeline Conflicts:

  • If using the @monitoring namespace in the Assets Bundle but the script fails to load, ensure:
    1. The Becklyn Assets Bundle is properly installed and configured.
    2. The @monitoring namespace is correctly mapped in your asset manifest.

5. Extension Points

• Custom Scrubbing Logic:

  • The package mentions IP scrubbing in the assessment, but the actual package does not implement this feature (likely a misalignment with the README). If you need IP scrubbing, consider:
    • Using a dedicated package like spatie/laravel-activitylog with custom filters.
    • Implementing middleware:

      public function handle($request, Closure $next) {
          $request->merge(['ip' => Package::scrubIp($request->ip())]);
          return $next($request);
      }
      

• Custom Uptime Comment:

  • Extend the uptime comment logic by overriding the Becklyn\Monitoring\MonitoringServiceProvider:

    public function boot() {
        parent::boot();
        $this->app['view']->composer('*', function ($view) {
            $view->with('uptime_comment', '<!-- custom: ' . config('monitoring.project_name') . ' -->');
        });
    }