Stopwatch Laravel Package

Product Decisions This Supports

• Performance instrumentation roadmap: Decide whether to add lightweight timing checkpoints to Laravel requests, jobs, and deferred work to expose slow paths without adopting a full APM stack.
• Build vs. buy for diagnostics: Evaluate this package against Xdebug, Laravel Telescope, Debugbar-only profiling, or commercial APM. The package fits teams that want local/staging profiling with CLI and MCP-friendly run inspection, not distributed production tracing.
• Debugging workflow prioritization: The v0.16.0 fixes around TRANSIENT_EXCEPTION, deferred-job run retention, and stopwatch:runs:list --threw make failed-run investigation more trustworthy. PMs can prioritize exposing these filters in support/debug playbooks.
• Run-history semantics and reporting: recorded_at now represents run start time and stopwatch:runs:list labels it Started. Use this for consistent reporting; note that pre-v0.16.0 run files retain end time until pruned.
• Configuration safety and default behavior: Fixes to STOPWATCH_INJECT handling and run_log.min_duration_ms reduce accidental always-on tracking and noise. This lowers adoption risk for teams enabling the package in shared environments.
• Feature scoping for observability UX: Debugbar timeline accuracy for sub-1ms checkpoints and correct started() behavior after auto-dropped runs inform whether to invest in finer-grained checkpoint visualization.
• CI/quality signal: StructArmed architecture checks added to QA/CI are a positive maintenance signal for build-vs-buy and dependency-risk reviews.

When to Consider This Package

Consider it when:

• You have a Laravel/PHP application and need lightweight, checkpoint-based timing for requests, jobs, or specific workflows.
• You want developer-facing run logs, CLI inspection via stopwatch:runs:list, Debugbar timeline visibility, and MCP-based querying.
• You are debugging intermittent failures, deferred jobs, or transient exceptions and need run history that can be filtered by thrown exceptions.
• You want configurable noise control, such as skipping runs under a minimum duration.
• You are comfortable with a pre-1.0 package and can validate behavior in staging before broad rollout.

Look elsewhere when:

• You need production-grade distributed tracing, sampling, alerting, or long-term metrics storage.
• You require a mature, stable API with strong backward-compatibility guarantees.
• Your team does not use Debugbar, CLI run inspection, or MCP workflows and mainly needs aggregate dashboards.
• You cannot tolerate run-log schema/behavior evolution, such as the recorded_at semantic change and legacy files retaining end times until pruning.

How to Pitch It (Stakeholders)

For executives: This package is a low-cost, Laravel-native diagnostic tool that helps engineering find slow paths and failed runs faster. The latest release improves trust in run history, fixes missing failed-run visibility, and reduces accidental tracking from misconfiguration.

For engineering: v0.16.0 tightens run lifecycle behavior, fixes deferred-job run loss, corrects TRANSIENT_EXCEPTION filtering in CLI/MCP, makes STOPWATCH_INJECT handling safer, and ensures run_log configs without min_duration_ms do not log every run. It also improves Debugbar accuracy for sub-millisecond checkpoints and adds CI architecture checks.

For product: Adopt it where faster debugging and targeted performance visibility matter, especially in staging or developer workflows. Avoid positioning it as a production APM replacement; treat it as a focused instrumentation aid with some pre-1.0 maturity risk.