Corewatch Laravel Package

Product Decisions This Supports

• Observability Stack Consolidation: Eliminates the need for third-party SaaS tools (e.g., Datadog, New Relic) or self-hosted stacks (Prometheus + Grafana) by embedding core monitoring directly into Laravel. Reduces operational overhead and vendor lock-in.
• DevOps Efficiency: Accelerates incident response with real-time log streaming, server metrics, and a "safe ops" panel (graceful shutdowns, process management) without context-switching to external dashboards. v2.2.0 adds php artisan corewatch:doctor — a one-command diagnostic across System, Database, Cache, Queue, Scheduler, Alerts, and Security — turning "is the platform healthy?" into a scriptable, repeatable check rather than a manual runbook.
• Cost Optimization: Avoids recurring SaaS spend for small-to-medium Laravel applications, especially startups and internal tools where observability is critical but budgets are constrained.
• Roadmap Alignment: Strengthens the case for teams prioritizing developer experience (DX) and platform reliability:
  • Faster Time-to-Value: corewatch:doctor gives a guided first-run health check and corewatch:test-alert verifies Slack/Telegram delivery interactively — collapsing what used to be a multi-day "configure and hope" setup into minutes. This is a concrete onboarding accelerator and a strong pilot success criterion.
  • Alerting at Production Scale: Asynchronous delivery via SendQueuedAlertJob (ShouldQueue, backoff retries, configurable via COREWATCH_NOTIFICATIONS_QUEUE) removes the biggest scaling objection to self-hosted alerting — slow or failing webhook calls no longer block request handling or drop alerts during traffic spikes.
  • Feature Flagging / SRE Practices: CoreWatch::doctor() on the Facade and CoreWatchManager exposes diagnostics programmatically, enabling scheduled health probes, pre-deploy gates, and alerts tied to health metrics — without shelling out to artisan.
  • Multi-Environment Parity: Standardize monitoring across dev/staging/prod with minimal configuration drift; the doctor command doubles as a parity check between environments.
• Build vs. Buy: Buy (adopt) for Laravel-native teams; build only if requiring custom metrics or non-PHP integrations (e.g., Kubernetes-native telemetry). The PHPStan Level 8 / zero-error posture and Throwable-level hardening materially lower the "we'll have to maintain this ourselves" risk that normally pushes teams toward buying.
• Procurement & Risk: The release resolves Composer security advisories and hardens exception handling from \Exception to \Throwable across collectors, controllers, repositories, and actions. This directly answers the standard security-review objection: an observability tool must never be the thing that crashes the app.

When to Consider This Package

• Consider if:
  • You're a Laravel-first shop needing lightweight, embedded observability.
  • Your app is serverless or containerized (Docker/Kubernetes metrics supported).
  • You want to reduce tooling complexity — no external daemons, agents, or databases required (SQLite default, MySQL optional).
  • Your alerting needs are basic to moderate ("CPU > 90% for 5 mins", queue latency, scheduled-task failures) but must be reliable — v2.2.0's queued delivery with retries covers this; you must configure a queue worker for async alerts to fire.
  • Onboarding speed matters: corewatch:doctor + corewatch:test-alert let a single engineer validate an environment end-to-end, with no dedicated observability owner.
  • You want diagnostics as code: CoreWatch::doctor() fits naturally into scheduled commands, deploy gates, and health-check endpoints.
• Look elsewhere if:
  • You need advanced APM (transaction tracing, flame graphs) → Laravel Telescope + Blackfire or New Relic.
  • Your stack is non-PHP (Node.js, Go) → Prometheus or OpenTelemetry.
  • You require distributed tracing across microservices → Jaeger or Zipkin.
  • Operational caveat: if you cannot run a queue worker, async alerting degrades — validate your queue topology before committing.
  • Your team lacks PHP/Laravel expertise → higher learning curve than SaaS alternatives.

How to Pitch It (Stakeholders)

For Executives:

"CoreWatch lets us monitor and debug our Laravel apps without adding SaaS costs or operational complexity — a built-in DevOps dashboard covering server health, real-time logs, alerting, and safe operations (e.g., restarting queues). The new 2.2.0 release adds a built-in server doctor that diagnoses the app and its surrounding infrastructure in one command, and makes alerting queue-backed and retry-safe, so we don't miss incidents when traffic spikes. Where we'd otherwise pay [X] dollars/year for [Y] SaaS tool, we get this for free, with no vendor lock-in and no telemetry by default. It's a 10x productivity boost for our SRE team and reduces MTTR."

Key Metrics to Track:

• Reduction in incident resolution time ("logs in 1 click vs. 10"; alerts now retried rather than dropped).
• Cost savings (e.g., "$50K/year avoided" vs. Datadog).
• Time-to-first-insight for a new environment (target: under 1 hour using corewatch:doctor + test-alert).
• Developer happiness (fewer context switches, fewer "works on my machine" issues).

For Engineering:

"CoreWatch is a zero-config, Laravel-native observability layer. In 2.2.0 it becomes genuinely production-defensible:

1. php artisan corewatch:doctor — full diagnostics across System, Database, Cache, Queue, Scheduler, Alerts, and Security. Also available programmatically via CoreWatch::doctor(), so you can wire it into deploy gates and scheduled health checks.
2. php artisan corewatch:test-alert — interactive verification of Slack/Telegram delivery. No more silent misconfigured webhooks.
3. Async alerting — SendQueuedAlertJob implements ShouldQueue with backoff retries, configurable via COREWATCH_NOTIFICATIONS_QUEUE. Alerting no longer blocks the request cycle. Requires a running queue worker.
4. Resilience — exception handling hardened from \Exception to \Throwable across collectors, controllers, repositories, and actions. The monitoring layer cannot take down the app it monitors.
5. Quality signal — PHPStan Level 8, zero errors, Composer advisories resolved, 32 tests / 211 assertions.
6. UI — Filament integration; no custom frontend work.

Trade-offs:

• Not a full APM: no deep PHP profiling (use Xdebug/Blackfire).
• Self-hosted: you own the data (lightweight — not Prometheus-scale ops).
• New operational dependency: async alerts need a healthy queue; the doctor command includes a Queue check precisely to catch this.

Proposal:

• Pilot: install in staging; run corewatch:doctor to baseline, corewatch:test-alert to validate channels, and measure whether debug time drops >30% in 2 weeks.
• Scale: roll out to prod once the doctor reports clean and alerts are confirmed queued and delivered; then extend to other Laravel apps.
• Extend: emit custom metrics (e.g., queue job latency) via the `CoreWatch