yoanbernabeu/periscope-bundle

Agent-first CLI observability for Symfony Messenger and Scheduler.

v0.1.0-alpha 2026-04-16 20:40 UTC

Requires

• php: >=8.4
• doctrine/dbal: ^3.8 || ^4.0
• doctrine/doctrine-bundle: ^2.12
• symfony/console: ^7.4 || ^8.0
• symfony/dependency-injection: ^7.4 || ^8.0
• symfony/event-dispatcher: ^7.4 || ^8.0
• symfony/framework-bundle: ^7.4 || ^8.0
• symfony/messenger: ^7.4 || ^8.0
• symfony/scheduler: ^7.4 || ^8.0
• symfony/uid: ^7.4 || ^8.0

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.64
• phpstan/extension-installer: ^1.4
• phpstan/phpstan: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• phpstan/phpstan-symfony: ^2.0
• phpunit/phpunit: ^13.0
• symfony/phpunit-bridge: ^7.4 || ^8.0
• symfony/yaml: ^7.4 || ^8.0

MIT

• Yoan Bernabeu

• symfony
• cli
• monitoring
• scheduler
• Messenger
• symfony-bundle
• observability

README

See through the surface of your queues.

Agent-first CLI observability for Symfony Messenger and Symfony Scheduler.

Overview

PeriscopeBundle records every Messenger message and Scheduler run that flows through your Symfony application and exposes them through a suite of bin/console periscope:* commands. Output is designed to be:

• Machine-friendly by default (compact tabular text when piped), so coding agents and scripts can consume it cheaply;
• Human-friendly on demand (rich tables, colors) when run in an interactive terminal;
• Strictly structured via --format=ndjson|json|yaml for pipelines.

No web UI. No prompts. No surprises.

Requirements

• PHP 8.4+
• Symfony 7.4 LTS or 8.x
• Doctrine DBAL 3.8+ or 4.x
• A database supported by the Doctrine storage backend (PostgreSQL recommended, MySQL/MariaDB, SQLite)

Installation

composer require yoanbernabeu/periscope-bundle
php bin/console periscope:install

CLI commands

Command	Description	Exit codes
periscope:install	Create the Periscope schema on the configured connection. Idempotent; --dump-sql prints the statements without executing.	0
periscope:messages	List observed Messenger/Scheduler messages. Supports --status, --transport, --class, --scheduled, --since, --until, --limit, --offset, --format, --fields.	0 results / 1 no result / 2 invalid input
periscope:message <uuid>	Full event timeline of a single message identified by its periscope id.	0 / 1 unknown id / 2 invalid input
periscope:schedules	Every recurring message configured in the application, with its next run. --schedule=name filters.	0 / 1 none / 2
periscope:queues	On-demand depth of every observed Messenger transport.	0 / 1 no transport / 2
periscope:purge	Delete events older than the retention window. --older-than=7d overrides, --dry-run previews.	0 / 2
periscope:health	Aggregated snapshot and threshold check, designed for cron/alerting scripts. --threshold-failure-rate and --threshold-min-total exit with code 3 on breach.	0 / 2 / 3

Every command supports --format=auto|compact|pretty|json|ndjson|yaml. auto picks pretty on a TTY and compact otherwise, which is what agents and pipes expect.

Status

Early development — the bundle is not yet functional. The product definition lives in PRD.md; releases are tracked in CHANGELOG.md.

Development

A local Symfony application with Postgres running in Docker is used to exercise the bundle end-to-end. The scaffold lives under playground/ and is intentionally not committed — each contributor generates it locally. See docs/DEVELOPMENT.md once it is in place.

Quality tooling:

composer ci          # full pipeline (cs, phpstan, phpunit)
composer phpstan     # PHPStan at max level
composer cs          # PHP-CS-Fixer (dry-run)
composer cs-fix      # apply style fixes
composer test        # PHPUnit

License

MIT — see LICENSE.