Debug Bar
Introduction
The debug bar is a panel at the bottom of your pages that shows what the last request did: the SQL it ran and how long each statement took, the logs it wrote, the events it dispatched, the cache it touched, and any error it raised. It records JSON, API and Inertia requests too, so you can inspect a request that has no page.
The bar is for development. It is on when the application runs in debug mode, and off in production and in tests. @bunyad/debugbar also keeps a history of recent requests, which an AI agent can read through the MCP server.
Installation
Install the package as a development dependency:
bun add -d @bunyad/debugbar@betaRegister the provider where you register your other providers:
import { DebugbarServiceProvider } from "@bunyad/debugbar";
// Inside the function that registers your providers:
app.register(DebugbarServiceProvider);Reload any HTML page. The bar appears at the bottom, and every response carries an X-Debugbar-Id header. Click an item in the bar to open its panel, and click the ✕ at the end of the tab row to close it again.
The bar decides whether to run in this order:
- The
enabledoption inconfig/debugbar.ts, when you set it. - The
DEBUGBARenvironment variable:DEBUGBAR=falseturns it off andDEBUGBAR=trueforces it on. - Otherwise, on when the application is in debug mode and is not running in production or in tests.
What the bar shows
The bar summarizes the request: method, path, status, route name, query count and elapsed query time, request time, memory, and counts of exceptions, events, logs and cache operations. Each item opens a tab:
| Tab | Contents |
|---|---|
| Messages | Lines you add with Debugbar.message() |
| Timeline | The request, your Debugbar.measure() spans and every query on one time axis |
| Queries | Each statement with its time and bindings. Duplicate, slow and possible N+1 queries are flagged |
| Request | The route, query string, body, headers, cookies and response headers |
| Events | Events dispatched during the request, with listener counts |
| Logs | Everything written through @bunyad/log during the request |
| Cache | Hits, misses, writes and forgets |
| Exceptions | Server errors (status 500 and up) with stack traces |
Requests your page makes afterwards, such as fetches from a single-page app or Inertia visits, are added to a dropdown on the bar. Pick one to inspect it.
The bar is only added to HTML responses that contain a closing </body> tag. Redirects and downloads are not changed, but their requests are still recorded.
Adding your own information
Debugbar.message() adds a line to the Messages tab, and Debugbar.measure() times a block on the Timeline:
import { Debugbar } from "@bunyad/debugbar";
Debugbar.message("loaded 12 rows");
const report = await Debugbar.measure("build report", () => buildReport());measure() returns what your function returns. Both helpers do nothing when the bar is off, so they are safe to leave in your code.
Reading the Queries tab
The Queries tab lists every statement the request ran. Use the chips above the table to show all of them, only duplicates, only slow ones, or only possible N+1 patterns.
- Duplicate. The same SQL with the same values ran more than once in one request.
- Slow. The statement took at least
slowQueryMs(100 ms by default). - Possible N+1. A
selectwhose shape rannPlusOneThresholdor more times (5 by default) with different values, for example one query per row of a list. The tab groups each pattern and shows how many times it ran and the total time.
Click a row to see its bindings and to copy the SQL.
Where a query came from
Each query shows the file and line of your code that issued it. The bar records the call stack at the moment the query starts and keeps the first frame that is yours, skipping node_modules, the runtime and the framework itself. Set queryOrigin: false to turn this off.
Origin is best-effort. Batched eager-load queries, such as with("brand"), are issued by the ORM after the parent query returns, so they have no origin, although the parent query does. A function that ends with return Model.query().get() straight after an earlier await also loses its own frame. Write const rows = await Model.query().get(); return rows; to keep it.
Elapsed time and summed time
Queries that run in parallel overlap. If five queries of 10 ms run at once, the request waited about 10 ms, not 50. The bar shows the elapsed figure next to the request time, and keeps the summed figure in the tooltip and in the Queries tab header.
A query's time starts when it is issued, so it includes any wait for a free database connection. The Queries tab also shows how many queries were in flight at once. If that is much higher than your connection pool, the extra queries were queueing.
Jobs, scheduled tasks and commands
Work that is not an HTTP request gets its own history entry too, with its queries, logs, events and errors. Wrap it in Debugbar.profile():
import { Debugbar } from "@bunyad/debugbar";
await Debugbar.profile("SendReceipt", () => sendReceipt(order), { kind: "job" });kind is job, schedule or command. profile() returns what your function returns and rethrows what it throws. When the bar is off it only runs your function. Inside a request it adds a Timeline span instead of a separate entry.
Scheduled tasks are recorded automatically, named after the task. Queued jobs are not wrapped for you, so call profile() in the code that runs your queue payloads.
These entries have no page, so there is no bar to show. They appear in the history, as JOB, SCHEDULE and COMMAND rows. A worker or scheduler is a separate process from your web server, so set driver: "file" for them to share one history.
History
The bar keeps the most recent requests, 50 by default (history). Three URLs read it:
| URL | Returns |
|---|---|
/_debugbar |
A page listing the recent requests |
/_debugbar/latest |
The newest request as JSON |
/_debugbar/{id} |
One request as JSON |
By default the history lives in memory and is lost when the server restarts. To keep it on disk, set driver: "file". Each request is then written as one JSON file under storage/debugbar, so the history survives restarts and other processes can read it. Add that directory to .gitignore. Snapshots older than maxAgeHours (24 by default) are deleted.
Clear the history with the console command:
bunyad debugbar:clearWrites happen after the response is sent and never fail a request.
Privacy
The bar records SQL, request bodies, headers, logs and events, so it masks sensitive values before it stores them or shows them to anyone, including an AI agent:
- By name. Fields called
password,token,secret,authorization,cookie,csrf,api key,cardand similar are masked. So is personal data such as email, phone, address, national id and bank details, unless you setredactPii: false. This applies to request bodies, headers, cookies, query strings, event payloads and log context. - SQL bindings by column. A binding is only a value, so the bar works out which column each placeholder belongs to.
WHERE email = ?,SET password = ?,INSERT INTO contacts (email, phone) VALUES (...),IN (...)lists,BETWEENandLIKEare all understood. Inline string literals for those columns are masked in the SQL text as well. Duplicate and N+1 detection still compare the real values. - By shape. JWTs, password hashes,
BearerandBasiccredentials and long opaque tokens are masked in any field. UUIDs are left alone. - Free text. Log lines, error messages and stack traces have
password=…,token: …andBearer …values masked. - URLs. Secret query values (
?token=…) and secret route parameters (/reset/{token}) are masked in the stored URL and path.
This is pattern-based and best-effort. It cannot recognise a secret in a column it does not know, or in SQL it cannot parse. Add your own patterns with redact, or set captureBindings: false to keep no query values at all. The SQL, timings and N+1 detection still work without values.
Configuration
Create config/debugbar.ts. Every option is optional:
export default {
driver: "file",
history: 100,
slowQueryMs: 50,
except: ["/health"],
};Then include it in the config object in bootstrap/app.ts, the same way as your other config files (see Configuration):
import debugbarConfig from "../config/debugbar.ts";
const app = new Application({
basePath,
config: { app: appConfig, debugbar: debugbarConfig },
router,
});| Option | Default | What it does |
|---|---|---|
enabled |
follows debug mode | Force the bar on or off |
path |
"/_debugbar" |
URL prefix for the history page and JSON |
history |
50 |
How many requests to keep |
driver |
"memory" |
"file" keeps history on disk |
storagePath |
"storage/debugbar" |
Directory for the file driver, relative to the application |
maxAgeHours |
24 |
File driver: delete older entries |
store |
none | Your own store object (put, get, list, clear), replacing the built-in ones |
slowQueryMs |
100 |
Queries at least this slow are flagged |
nPlusOneThreshold |
5 |
Repeats of one query shape before it is flagged as N+1 |
queryOrigin |
true |
Record the file and line that issued each query |
eventsIgnore |
cache events | Event names the Events tab skips. A trailing * matches a prefix |
maxRecords |
500 |
Most records kept per tab, per request |
except |
[] |
Path prefixes the bar ignores |
redact |
[] |
Extra name patterns to mask |
redactPii |
true |
Also mask personal data by name |
captureBindings |
true |
false hides every query value |
inject |
true |
false keeps history and the header but adds no bar |
Asking an AI agent
With the MCP server, an AI agent in your editor can read the same history and answer questions such as which queries run in every request, which route is slowest, or whether a page has an N+1. Use driver: "file" for this, because the MCP server runs as a separate process and can only read history from disk.