PHPackages webrek/laravel-telescope-mongodb - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Database & ORM](/categories/database) 4. / 5. webrek/laravel-telescope-mongodb ActiveLibrary[Database & ORM](/categories/database) webrek/laravel-telescope-mongodb ================================ Native MongoDB storage driver for Laravel Telescope. v1.3.0(1mo ago)053MITPHPPHP ^8.3CI passing Since May 25Pushed 1mo agoCompare [ Source](https://github.com/webrek/laravel-telescope-mongodb)[ Packagist](https://packagist.org/packages/webrek/laravel-telescope-mongodb)[ Docs](https://github.com/webrek/laravel-telescope-mongodb)[ RSS](/packages/webrek-laravel-telescope-mongodb/feed)WikiDiscussions main Synced 3w ago READMEChangelog (1)Dependencies (22)Versions (8)Used By (0) Laravel Telescope MongoDB Driver ================================ [](#laravel-telescope-mongodb-driver) [![Latest Version on Packagist](https://camo.githubusercontent.com/6d673f578086ef07edb4396356305a9358f18419f0aa798d969f413c61c528d4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f77656272656b2f6c61726176656c2d74656c6573636f70652d6d6f6e676f64622e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/webrek/laravel-telescope-mongodb)[![Total Downloads](https://camo.githubusercontent.com/0af38981e9c799a66bcd3a3fccb5ac03b3a595e3e5fca937c02b1fe938fc5cb4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f77656272656b2f6c61726176656c2d74656c6573636f70652d6d6f6e676f64622e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/webrek/laravel-telescope-mongodb)[![Tests](https://camo.githubusercontent.com/277366fd9aa36ef5c289b270464c2c9acc98ae63df263c6db722af1412737f56/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f77656272656b2f6c61726176656c2d74656c6573636f70652d6d6f6e676f64622f74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/webrek/laravel-telescope-mongodb/actions/workflows/tests.yml)[![PHP Version](https://camo.githubusercontent.com/19da3de7163b94266c1f32cde70e8fe721e40d2696018c54f33af8acab8c6c57/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f77656272656b2f6c61726176656c2d74656c6573636f70652d6d6f6e676f64622e7376673f7374796c653d666c61742d737175617265)](https://php.net)[![License](https://camo.githubusercontent.com/49c2d1c0a315262c0be06f8cfc49058961975c25c24ab550d6539619b6b1c3fe/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f77656272656b2f6c61726176656c2d74656c6573636f70652d6d6f6e676f64622e7376673f7374796c653d666c61742d737175617265)](LICENSE) A drop-in MongoDB storage driver for [Laravel Telescope](https://laravel.com/docs/telescope). Run Telescope on a MongoDB-only stack without touching MySQL or PostgreSQL. Quickstart ---------- [](#quickstart) ``` composer require webrek/laravel-telescope-mongodb php artisan telescope-mongodb:install ``` That's it. The installer publishes Telescope's assets, removes the relational migration Telescope ships (you do not need a SQL database), creates the seven MongoDB indexes the driver relies on, and binds itself to Telescope's `EntriesRepository`. Open `/telescope` and you will see your requests, exceptions, jobs, queries, mails, notifications and batches streaming straight from MongoDB. Already running Telescope on MySQL or PostgreSQL? Migrate your existing data in one command: ``` php artisan telescope-mongodb:migrate-from-sql --from=mysql ``` Why --- [](#why) Telescope ships with an Eloquent-backed storage layer that relies on JSON columns, joins to a tag pivot table, and an auto-increment `sequence`. None of that maps cleanly onto MongoDB, which is why Telescope has historically required a relational database alongside your Mongo workload. This package implements Telescope's `EntriesRepository`, `ClearableRepository`, `PrunableRepository`, and `TerminableRepository` contracts directly against MongoDB. Tags live on the entry document as an array, the `_id` ObjectId acts as the monotonic sequence, and indexes are managed for you. Why move Telescope off your primary database -------------------------------------------- [](#why-move-telescope-off-your-primary-database) A common Telescope-in-production story: traffic grows, the dashboard starts feeling sluggish, and you notice MySQL is suddenly pinned at 60-80% CPU. The application queries did not change — Telescope is the new hot tenant on your primary database. Five mechanics make the default storage layer expensive on relational engines: 1. **Write amplification.** A typical request produces 5–20+ Telescope entries: one `request`, a handful of `query`, one or two `view`, optionally `cache`, `mail`, `notification`, `job`, `exception`. Multiply by your request rate and your primary database is absorbing writes that have nothing to do with your business data. 2. **Auto-increment contention.** Every insert into `telescope_entries` takes a row-level lock on the `sequence` `AUTO_INCREMENT`. Under concurrent traffic those inserts serialise against the same hot spot. 3. **JSON column scans.** The `content` field is `LONGTEXT` holding JSON. MySQL does not index JSON natively, so dashboard filters fall back to full scans or `JSON_EXTRACT` calls that fight for the same buffer pool your application queries depend on. 4. **Pivot writes.** Tags live in `telescope_entries_tags`. An entry with N tags is `1 + N` inserts, all of which take their own locks. 5. **Buffer pool contention.** The Telescope working set evicts your application's hot pages out of InnoDB's buffer pool, slowing down the queries that actually matter. MongoDB removes each of these by construction: - **No central sequence.** `_id` is an `ObjectId` minted by the driver, monotonic but contention-free. - **Tags are an embedded array** with a native multikey index. One document, zero pivots. - **Document-level indexes on `type`, `tags`, `family_hash`, `batch_id`, `should_display_on_index`** — the dashboard's filters hit indexes directly. - **Separate database.** Telescope writes go to your Mongo server (or Atlas tier), not the SQL server that holds your real data — zero buffer-pool competition. - **Optional TTL index.** MongoDB removes expired entries server-side, continuously, with no `telescope:prune` cron required. ### Benchmark: MySQL vs. MongoDB driver [](#benchmark-mysql-vs-mongodb-driver) The repository ships with a reproducible benchmark (`make bench-setup && make bench`) that boots two identical Laravel 13 applications side by side — one writing through stock Telescope to MySQL 8, one writing through this driver to MongoDB 7. Same routes, same request count, same `php artisan serve` process, same host. Numbers below were captured on a Docker Desktop host (Apple Silicon) with both database containers and the load generator competing for the same CPU — directional, not absolute. WorkloadStorageThroughputp50 latencyp95 latencyp99 latency500 req × 10 concurrentMongoDB driver**247.5 req/s****33.9 ms****39.5 ms****41.8 ms**500 req × 10 concurrentStock MySQL130.2 req/s69.0 ms79.4 ms92.0 ms1000 req × 20 concurrentMongoDB driver**262.9 req/s****69.0 ms****78.4 ms****82.4 ms**1000 req × 20 concurrentStock MySQL131.3 req/s144.5 ms160.1 ms184.8 msEnd-to-end the driver is **roughly 2× the throughput and 2× lower latency** of the stock MySQL backend on this workload. Production differences tend to be larger because in production your MySQL is also serving the application's own queries — the buffer-pool contention is real. Reproduce it yourself: ``` make bench-setup REQUESTS=1000 CONCURRENCY=20 make bench ``` How this compares to existing packages -------------------------------------- [](#how-this-compares-to-existing-packages) A few prior attempts exist on Packagist. They all take the same shape — a **complete fork** of `laravel/telescope` that re-vendors thousands of lines of PHP, Vue, JS and Blade so a handful of storage classes can be swapped. This package takes a different path: it ships a few hundred lines of storage code that implement Telescope's public contracts. Telescope itself is installed as a normal Composer dependency and updated by the Laravel team. PackageApproachLatest LaravelMaintenance shape`webrek/laravel-telescope-mongodb` (this one)Driver implementing the four Telescope contracts11 / 12 / 13Track upstream by bumping `laravel/telescope``dij-digital/telescope-mongodb`Full fork of Telescope itself (~2k commits ahead of upstream)11 / 12Rebase or merge every Telescope release`farmani/telescope-mongodb`Full forkup to 11Same fork rebase burden`yektadg/laravel-telescope-mongodb`Full fork (jenssegers/mongodb era)up to 9Stale since early 2024In practice, that means three things if you pick this package: - **You stay on the Telescope your team already knows.** Same Vue dashboard, same watchers, same authorization gate. Only the storage layer changes. - **Security and feature updates flow through Composer.** When `laravel/telescope` ships a fix, `composer update` brings it to you — there is no rebase queue waiting on a maintainer to merge. - **The diff a security reviewer has to read is small.** All MongoDB-specific behaviour lives in `src/Storage/MongoDbEntriesRepository.php` and four artisan commands — under 1,000 lines total. Requirements ------------ [](#requirements) ComponentVersionPHP8.3+Laravel12.x / 13.xTelescope5.xMongoDB server6.0+`mongodb/laravel-mongodb`5.x`ext-mongodb`1.21+ or 2.xInstallation ------------ [](#installation) ``` composer require webrek/laravel-telescope-mongodb ``` Make sure `mongodb/laravel-mongodb` is configured in `config/database.php` with a `mongodb` connection: ``` 'mongodb' => [ 'driver' => 'mongodb', 'dsn' => env('MONGODB_URI'), 'database' => env('MONGODB_DATABASE', 'app'), ], ``` Then run the installer: ``` php artisan telescope-mongodb:install ``` That command will: 1. Publish `config/telescope-mongodb.php`. 2. Run `telescope:install` so the standard Telescope UI/config is in place. 3. Create the required MongoDB indexes via `telescope-mongodb:sync-indexes`. You do **not** need to run Telescope's migrations — this driver does not use SQL tables. If your Laravel project has no SQL database at all, remove the `telescope:install` step and set `TELESCOPE_ENABLED=true` directly. Configuration ------------- [](#configuration) ``` return [ 'connection' => env('TELESCOPE_MONGODB_CONNECTION', 'mongodb'), 'collections' => [ 'entries' => env('TELESCOPE_MONGODB_ENTRIES_COLLECTION', 'telescope_entries'), 'monitoring' => env('TELESCOPE_MONGODB_MONITORING_COLLECTION', 'telescope_monitoring'), ], 'chunk' => [ 'store' => (int) env('TELESCOPE_MONGODB_STORE_CHUNK', 1000), 'prune' => (int) env('TELESCOPE_MONGODB_PRUNE_CHUNK', 5000), ], 'indexes' => [ // When true, the driver ensures its indexes (including the TTL index) // on the first write of each process, so a fresh deploy is self-healing // even if you forget to run sync-indexes. Set false to manage indexes // exclusively through the artisan commands. 'auto_create' => (bool) env('TELESCOPE_MONGODB_AUTO_INDEXES', true), // Seconds before MongoDB removes an entry automatically (TTL index on // created_at). null disables server-side pruning. See "Pick a retention // strategy" below. 'ttl_seconds' => env('TELESCOPE_MONGODB_TTL_SECONDS') !== null ? (int) env('TELESCOPE_MONGODB_TTL_SECONDS') : null, ], ]; ``` > The value of `config('telescope.driver')` is irrelevant once this package is installed: the service provider binds Telescope's repository contracts to the MongoDB implementation directly, so entries always go to MongoDB regardless of whether `telescope.driver` still says `database`. Document shape -------------- [](#document-shape) Entries are stored as a single document per Telescope entry: ``` { "_id": ObjectId("..."), "uuid": "0f24c1f0-...-...", "batch_id": "0f24c1f0-...-...", "family_hash": null, "should_display_on_index": true, "type": "request", "content": { "method": "GET", "uri": "/users", "...": "..." }, "tags": ["status:200", "Auth:42"], "created_at": ISODate("...") } ``` Indexes created by `telescope-mongodb:sync-indexes`: NameKeyNotes`uuid_unique``{ uuid: 1 }`unique`batch_id``{ batch_id: 1 }``family_hash``{ family_hash: 1 }`exception grouping`type_recent``{ type: 1, _id: -1 }`listing`tags``{ tags: 1 }`multikey on tag array`display_type_recent``{ should_display_on_index: 1, type: 1, _id: -1 }`default Telescope index views`created_at``{ created_at: 1 }`pruningPruning ------- [](#pruning) Telescope's `telescope:prune` command works out of the box because this driver implements `PrunableRepository`: ``` php artisan telescope:prune --hours=48 php artisan telescope:prune --hours=72 --keep-exceptions ``` Pruning is chunked (see `chunk.prune` in config) so it stays gentle on the working set. Pagination ---------- [](#pagination) Telescope's `before` cursor is the entry sequence. Since MongoDB has no auto-increment, this driver returns the `ObjectId` as the `id` and `sequence` fields. ObjectIds are monotonic, so the existing Telescope UI pagination works without changes. Production checklist -------------------- [](#production-checklist) The defaults are safe but conservative — review these knobs before you run this in front of real traffic. ### Lock down the dashboard [](#lock-down-the-dashboard) Telescope's `TelescopeServiceProvider` ships with a `gate()` method that whitelists which users can open `/telescope` outside `local`. The driver does not change that — make sure the published provider is updated: ``` // app/Providers/TelescopeServiceProvider.php protected function gate(): void { Gate::define('viewTelescope', function (User $user) { return in_array($user->email, [ 'you@yourcompany.com', ]); }); } ``` ### Pick a retention strategy [](#pick-a-retention-strategy) You have two options. They are mutually exclusive — pick one. - **Cron-driven (`telescope:prune`)** — keeps you in control of *when* deletion happens. Schedule it in `app/Console/Kernel.php`: ``` $schedule->command('telescope:prune --hours=48 --keep-exceptions')->hourly(); ``` - **Server-driven (TTL index)** — MongoDB removes documents automatically as they age past the configured TTL. No cron, no cold paths. Set it once and the `sync-indexes` command will install the TTL index: ``` TELESCOPE_MONGODB_TTL_SECONDS=172800 # 48 hours php artisan telescope-mongodb:sync-indexes ``` TTL is the right default for most teams — it removes a class of failure (cron never ran) and amortises deletion cost continuously instead of in large nightly bursts. ### Choose a write concern that matches your deployment [](#choose-a-write-concern-that-matches-your-deployment) The `write_concern` config maps directly to MongoDB's [write concern](https://www.mongodb.com/docs/manual/reference/write-concern/). Recommended values: Deployment`w``journal`WhySingle-node (dev)`1``false`Default. Lowest latency, single-server durability.Replica set`majority``true`Survives a single-node failure mid-write.High-volume tracing`0``false`Fire-and-forget. Accept occasional loss for low latency.Atlas Serverless / M0`majority``false`Atlas enforces majority anyway; journal is implicit.Configured via env: ``` TELESCOPE_MONGODB_WRITE_W=majority TELESCOPE_MONGODB_WRITE_JOURNAL=true TELESCOPE_MONGODB_WRITE_TIMEOUT_MS=2000 ``` ### Verify the install [](#verify-the-install) After every deploy, run the doctor to catch index drift, missing TTL, or a stale Mongo server: ``` php artisan telescope-mongodb:doctor ``` Exit code is `0` when everything is healthy and `1` if the connection or required indexes are missing. ### Scale: when the collection grows past a few million entries [](#scale-when-the-collection-grows-past-a-few-million-entries) MongoDB scales the `telescope_entries` collection naturally up to tens of millions of documents on a single node. Beyond that, the typical pattern is: 1. Reduce TTL so the collection stays bounded. 2. If you need long retention plus high write rate, shard on `{ _id: "hashed" }` — `_id` is monotonic but hashed sharding spreads the writes evenly while still giving you `_id`-based pagination. 3. Move heavy `content` payloads (views, large request bodies) off the hot path by filtering them in Telescope's `filter` callback before they reach storage. Testing ------- [](#testing) The repository ships with a fully containerised test environment so contributors do not need PHP or MongoDB installed locally. A PHP 8.3 container with `ext-mongodb` and Composer is wired against a `mongo:7` service in `docker-compose.yml`. ``` make build # build the PHP image once make install # composer install inside the container make test # run the full PHPUnit suite against MongoDB make shell # drop into a bash shell inside the PHP container make mongo-shell # open a mongosh shell against the test database make clean # tear everything down ``` ### End-to-end Laravel playground [](#end-to-end-laravel-playground) For an end-to-end smoke test against a real Laravel app, the repository also ships with a bootstrap script. It creates a fresh Laravel installation under `playground/`, wires this package via a Composer path repository, points it at the Mongo service, runs the installer, and seeds a handful of demo routes. ``` make build # one-time make playground # composer create-project + install package + install Telescope make playground-up # boot php artisan serve on http://127.0.0.1:8000 curl http://127.0.0.1:8000/ping curl http://127.0.0.1:8000/log-something curl http://127.0.0.1:8000/mongo-query curl http://127.0.0.1:8000/boom open http://127.0.0.1:8000/telescope ``` After a few requests, `make mongo-shell` followed by `use telescope_playground; db.telescope_entries.find()` shows the captured documents stored natively. `make playground-reset` tears it all down and rebuilds. If you prefer to run things on your host, point the suite at any reachable MongoDB instance: ``` export TELESCOPE_MONGODB_TEST_DSN="mongodb://127.0.0.1:27017" export TELESCOPE_MONGODB_TEST_DATABASE="telescope_mongodb_tests" vendor/bin/phpunit ``` License ------- [](#license) MIT ### Health Score 43 — FairBetter than 89% of packages Maintenance92 Actively maintained with recent releases Popularity12 Limited adoption so far Community6 Small or concentrated contributor base Maturity53 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~4 days Total 7 Last Release 38d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/7d8deca81629993819087597b5ad7695976b02e3d014f038e26e985f35f569de?d=identicon)[webrek](/maintainers/webrek) --- Top Contributors [![webrek](https://avatars.githubusercontent.com/u/5001338?v=4)](https://github.com/webrek "webrek (15 commits)") --- Tags apmdebugginglaravellaravel-packagelaravel-telescopemongodbmongodb-driverobservabilityphptelescopelaravelloggingdebugginglaravel-packageapmmongodbobservabilitytelescopelaravel telescopemongodb-driver ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StyleLaravel Pint Type Coverage Yes ### Embed Badge ![Health badge](/badges/webrek-laravel-telescope-mongodb/health.svg) ``` [![Health](https://phpackages.com/badges/webrek-laravel-telescope-mongodb/health.svg)](https://phpackages.com/packages/webrek-laravel-telescope-mongodb) ``` ### Alternatives [illuminate/database The Illuminate Database package. 2.8k54.9M12.2k](/packages/illuminate-database)[mongodb/laravel-mongodb A MongoDB based Eloquent model and Query builder for Laravel 7.1k8.4M98](/packages/mongodb-laravel-mongodb)[psalm/plugin-laravel Psalm plugin for Laravel 3345.3M347](/packages/psalm-plugin-laravel)[laravel/ai The official AI SDK for Laravel. 1.0k3.2M246](/packages/laravel-ai)[moonshine/moonshine Laravel administration panel 1.3k253.1k86](/packages/moonshine-moonshine)[api-platform/laravel API Platform support for Laravel 58174.6k17](/packages/api-platform-laravel) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)