Expand description
rustlavel-telescope: the debugging dashboard, enabled with one line.
App::new()?
.routes(routes::web::routes)
.plugin(Telescope::default())
.serve()
.awaitTelescope listens on the instrumentation bus core has carried since the
first release, keeps what it hears in a bounded in-memory ring buffer, and
serves a single self-contained page at /telescope that shows requests, the
queries and log lines each one produced, and how long everything took.
§Why a ring buffer and not SQLite
Laravel Telescope writes every entry to a database. That is the right answer in PHP, where the process dies at the end of the request and there is nowhere else to put anything. Rust has a process that lives for weeks, so this crate makes two promises instead:
A debugging tool must never be the reason a request is slow. Recording
an entry costs a redaction pass, a short mutex and a push onto a
VecDeque — no connection, no transaction, no fsync, no await on the
request’s path. Optional persistence is a send into a queue that a writer
thread drains; the request never waits for a disk. The buffer is bounded, so
a server under load a week from now uses exactly the memory it uses today.
A debugging tool must never add a dependency to production builds. The
whole crate depends on rustlavel-core and rustlavel-http and nothing
else — no embedded database, no serialisation framework, not even an async
runtime of its own. Persistence is JSON lines written with the JSON
implementation core already has: readable with tail -f, recoverable after
a kill -9 at the cost of at most the last line, and compacted at boot so
the file can never outgrow the buffer it feeds.
§What it records
Whatever is dispatched. The framework emits http.request, db.query and
log today, and the roadmap promises ai.call, queue.job and
mail.sent; an Entry therefore stores an open field map rather than a
fixed enum, and every renderer degrades gracefully — a kind Telescope has
never seen still gets a readable summary, a stable colour, a duration and a
full field table.
§Safety
The dashboard shows SQL, log messages, and every field a package chose to
emit. So it refuses to mount in production unless someone explicitly says
otherwise (telescope.enabled, or Telescope::even_in_production), and
values under keys that look like credentials are replaced at record time —
before they reach the buffer, the API, or the journal on disk.
Re-exports§
pub use entry::Entry;pub use journal::Journal;pub use plugin::Telescope;pub use recorder::Recorder;pub use store::Filter;pub use store::Store;
Modules§
- dashboard
- The dashboard page: one self-contained HTML document.
- entry
- One recorded moment, as Telescope keeps and renders it.
- journal
- Optional JSON-lines persistence, so a restart does not lose the request you were about to look at.
- plugin
- Turning Telescope on, and refusing to turn it on where it does not belong.
- recorder
- The subscriber that turns framework events into entries.
- redact
- Scrubbing credentials out of anything Telescope is about to remember.
- routes
- The routes Telescope mounts on the application’s own router.
- store
- The ring buffer everything Telescope knows lives in.