Periscope Laravel Package

Product Decisions This Supports

Feature / roadmap: queue observability across non-Redis drivers. Periscope's defining design choice is that it derives telemetry from Laravel's queue events rather than from driver internals. Practically, that means it works with redis, database, sqs, beanstalkd, and sync — whereas Horizon is Redis-only. This is the single decision it informs: if our queue roadmap includes SQS, database queues, or Beanstalkd (or a migration between them), Horizon is not an option and we either buy a monitor or build one.

Build vs buy. Building event-based queue monitoring is not hard in principle (listen to job events, persist throughput/failures/latency, expose a UI) but it is a multi-week distraction from the core product. Buying a package to close this gap is defensible — conditional on the adoption criteria below, because at 6 stars and pre-1.0 we are buying code, not a relationship.

Prioritization input: what "good enough" monitoring means for us. Before committing, decide whether we need (a) a live developer-facing dashboard, (b) historical throughput/failure metrics for incident review, or (c) alerting. Periscope's evidence base describes a long-running daemon and a config file — it does not evidence alerting, retention, or SLO reporting. If our actual requirement is (b) or (c), this package is a partial fit and we should scope what we'd build on top.

Operational readiness as a roadmap item. Adoption creates a new long-lived process to own: supervisor entry, deploy-hook restart, pcntl in the runtime image, shutdown runbook. That's real backlog work, not a composer require. Treat it as a spike ticket with an explicit go/no-go, not a line item in a feature sprint.

Due diligence flag — the metadata contradiction. The package's own description asserts it is a roles and permissions package; the release notes, technical assessments, and internal agent guide all describe a queue monitor. That inconsistency is itself a product finding: documentation quality is unreliable, so no decision should rest on the README. Verify behavior by running it, and price in the cost of reading source to answer questions the docs don't.

Use cases that justify the spend: teams running mixed queue drivers across environments (SQS in prod, database locally); platform teams wanting one monitor regardless of driver choice; migrations off Redis where losing Horizon visibility for a quarter is unacceptable.

When to Consider This Package

Adopt (to a spike, then a pinned pilot) when:

• You run Laravel queues on a non-Redis driver — this is essentially the entire reason to look here. If you're all-Redis, Horizon is more mature and better supported; stop.
• You deploy as Linux containers or VMs with a real process supervisor (systemd, supervisord, Kubernetes) and can guarantee ext-pcntl in the runtime image (not just the dev box). Official php:* images have it; slimmed Alpine and custom builds often don't.
• You can tolerate a pre-1.0 dependency pinned to an exact minor (0.5.*), with release notes read before every bump.
• You have an owner for the operational surface: restart on deploy, restart on config change, a shutdown runbook, and a memory/restart-on-schedule policy for the daemon.
• You can run a staging spike — start the daemon, exercise real jobs, send SIGINT/SIGTERM, confirm prompt exit and no orphaned children — before any production commitment.

Look elsewhere when:

• Redis-only stack. Horizon wins on maturity, ecosystem, and support. No reason to take pre-1.0 risk.
• Serverless / Vapor. No long-lived processes; this is architecturally incompatible, not merely awkward.
• Windows-based development where developers must run the command locally. pcntl is POSIX-only, so this becomes a permanent "works on my machine" tax.
• You need vendor support, an SLA, alerting/retention guarantees, or a security review trail. Six stars and a probable single maintainer cannot supply these.
• You already run Horizon, Octane, or queue workers in the same container. Multiple signal handlers in one container is a known source of shutdown bugs; verify collision behavior or isolate the process.
• The org cannot absorb a pre-1.0 dependency. 0.6.0 may rename a command or config key without semver protection.

Defer / kill if the static review shows ext-pcntl is not declared in composer.json. That means installs succeed on unsupported platforms and fail at command start — the worst possible failure timing — and it tells you how much the maintainer has thought about the deployment surface.

How to Pitch It (Stakeholders)

To executives, in one paragraph: We have a visibility gap in our job queue, and the standard Laravel tool (Horizon) only works if we stay on Redis forever. Periscope is a driver-agnostic queue monitor that works with Redis, database, SQS, and Beanstalkd, which keeps our queue choice a technical decision rather than one locked in by monitoring. It's MIT-licensed, ships as an optional sidecar process, and touches nothing in our request path — so it's cheap to try and cheap to remove. The risks are maturity, not lock-in: it's pre-1.0, six GitHub stars, and likely one maintainer, so we'd pin the version, pilot it in staging first, and keep Horizon as the fallback if we stay on Redis. Recommendation: approve a one-to-two week spike, not an adoption.

To engineering, the short version: One Artisan daemon (periscope:start), config-driven, event-based — it listens to Laravel queue events, not driver internals, which is why it's driver-agnostic and why it won't fight the queue driver. Requirements: ext-pcntl verified in the runtime image, POSIX host, a supervisor with numprocs=1, and SIGTERM reaching PHP (use init: true in Compose or exec the command). v0.5.3 fixed a real bug where the master blocked in usleep() and ignored Ctrl+C until the sleep elapsed — that's a correctness improvement, but it also tightens shutdown timing, so re-check any stopwaitsecs/TimeoutStopSec tuning and confirm in-flight children still drain. Add a restart to the deploy script and on config change. Success criteria for the spike: visible job telemetry for our actual drivers, prompt exit on SIGINT and SIGTERM, no orphaned processes on SIGKILL of the master, and stable RSS over several days. Failure of any one of those is a no-go.