ColdBox
On this page
ColdBox
The ColdBox tab shows what ColdBox did for one request. It appears by itself on a request that ColdBox handled, and not on any other page. Nothing in your application changes: no module to install and no line in ColdBox.bx. See BxLens for ColdBox for how it works.
The numbers at the top
| Tile | Meaning |
|---|---|
| Events | Events that ran, including nested runEvent() calls. A request served from the event cache runs none. |
| Views | Views rendered, with how many of them were different. A view is counted every time it renders. |
| Layouts | Layouts rendered. |
| Handler | Time spent in the event handler, for the events that ran first. |
| Layout and views | Time spent rendering. A layout wraps its views, so the time of the views it renders is inside its time. |
When a view renders more than once in a request, a line says which one and how many times, with the total time. A partial that is rendered in a loop is the usual cause. Render it once, or cache it with cache=true on the view.
What it knows about the request
| Row | Meaning |
|---|---|
| Event, Handler, Module | The event that ColdBox ran, the handler and action, and the module the handler belongs to. |
| Route, Routed URL | The route that matched (its name and pattern) and the URL it matched. |
| Layout, View | The layout and the main view of the request, with their modules. |
| Ajax | Whether ColdBox treated the request as an ajax request. |
| rc keys, prc keys | The names of the values in the request collection and the private request collection. Never the values: they can hold anything, including secrets. The keys that ColdBox sets itself (the current route, view and layout) are left out. |
| ColdBox | The version and the environment setting. |
| Level | full records the events, views and layouts. At light only the request facts are kept. See collect level. |
Help icons
The tiles and labels of the tab have the same i icons as the console (events, views, layouts, the handler time, the event cache, the view cache). Hover or focus one for a short explanation. See Help icons and the Glossary.
Findings
When the Advisor finds something wrong in the request, the tab shows it in an amber note above the details. It is free.
| Finding | When |
|---|---|
| View rendered more than once | A view rendered two or more times in the request. It names the view, how many times and the time spent. |
| Slow for this event | The request took more than three times the 95th percentile of its own event, and more than 100 ms, and at least 20 requests of that event have been seen. It says how much of the time was in the handler and in views. |
When the assistant is set up, Ask Lensy about this request opens the console and asks Lensy to read the request with its ColdBox tools. The console has more findings, about the whole application: see Findings.
The event cache
ColdBox can cache the output of an event (cache=true on the handler action). The tab says what the event cache did for this request.
| Result | Meaning |
|---|---|
| HIT | ColdBox sent the cached output and did not run the handler. Only the first and last interception points of the request fire, so no event, view or layout was recorded. |
| MISS | The event is cacheable and ran. Its output is now in the cache. |
| not cacheable | The event has no event cache. |
The provider, the timeout and the idle timeout come from the handler. ColdBox has no flag that says "this was a hit", so BxLens decides it from what ran: a cacheable event for which no event ran is a hit. The View cache row lists each view that rendered and whether it is cached, with its provider and timeout.
What ran
The waterfall lists the events, the layout and the views in the order they started. Views are one level in, under the layout that rendered them, and a partial rendered inside a view is one level further. Each row has its time and a bar on the request's time scale. A view that rendered more than once has a x2 mark.
The same events, views and layouts are in the Timeline, next to the templates, queries and HTTP calls that ran inside them, so you can see which view ran which query.
Deeply nested views stay readable: the indent stops after five levels, and a +3 mark says how many levels deeper the row is. Hover a row for its full name and file.
Buttons
| Button | What it does |
|---|---|
| Clear event cache | Clears the event cache of the application. It says how many entries it removed. |
| Clear view cache | Clears the view cache. |
| Reinit framework | Reinitializes the ColdBox application, like ?fwreinit=1. It asks first. |
All three are free. They work for the callers the bar is shown to, with a token that the page carries, and they are written to the audit log.
Reinit and the reinit password
ColdBox can protect a reinit with a password (coldbox.reinitPassword, kept as a hash). BxLens never reads that password and never sees what you type:
- No password set: the button asks once, then sends
fwreinit=true. - A password set: the button asks for it. Your browser sends it to the application as a form field (not in the address, so it stays out of access logs), and ColdBox checks it. A wrong password does nothing.
BxLens only asks the application whether a password is needed and what the reinit key is called (coldbox.reinitKey, fwreinit by default). After a reinit ColdBox has a new controller. BxLens notices it on the next request and registers again, so the tab keeps working.
The buttons are off when bar.actions is false, and never work when the console is read only (console.readOnly).
The cached event, seen in the bar
Settings
| Setting | Default | |
|---|---|---|
collectors.coldbox.enabled | true | Turn ColdBox support off. It does nothing until a ColdBox application is found. |
collectors.coldbox.maxEvents | 50 | Events kept per request. |
collectors.coldbox.maxViews | 50 | Views kept per request. |
bar.actions | true | The buttons that change something. |
Good to know
- Needs ColdBox 7 or 8. The application must keep its controller in
application.cbController, which is where ColdBox puts it. - A request that fails before ColdBox handles it, a static file, or a page that is not routed through ColdBox has no ColdBox tab.
- The first request after a reinit may not be recorded: ColdBox is still starting when it arrives.
- Everything shown is also in the Requests page of the console, with the ColdBox tag and the event.