ColdBox
On this page
ColdBox
The ColdBox page shows up in the sidebar, under Runtime, once BxLens has seen a ColdBox application handle a request. Open any page of your application and the entry appears. Nothing is installed in your application. If more than one ColdBox application runs on the server, pick one from the list at the top.
Everything on the page is read from the running application. It is live data: nothing is saved. Names, counts, times and flags only. BxLens never reads a value from rc, prc, a setting that may hold a secret or the reinit password.
Overview
ColdBox version, environment, how many requests BxLens has seen, whether reinit is open or needs a password, and what the application is made of (handlers, routes, interceptors, modules, caches, executors). Click a count to open that tab.
Settings that matter for speed shows handler caching, event caching, view caching and debug mode. A switch that usually should be on and is off is marked, so you can tell at a glance why a production application is slow.
Findings
The Advisor checks the application against a fixed set of rules, on data BxLens already has. Findings are free. Each one has a severity (critical, warning or note), the evidence (the numbers), a suggestion and a button to open the page that shows it. The number of findings is on the tab and in the Overview.
| Rule | Severity | Fires when |
|---|---|---|
reinit-open-production | critical | The environment is production and no reinitPassword is set. Only whether one is set is read, never its value. |
dev-settings-production | warning | In production, handlerCaching is off or handlersIndexAutoReload is on. |
no-error-handling | note | In production, neither exceptionHandler nor customErrorTemplate is set. |
cbdebugger-production | warning | The module cbdebugger is loaded in production. BxLens replaces it. |
module-multiple-versions | warning | A module name exists on disk in different versions. It names the loaded copy and the skipped ones. |
module-bundled-twice | warning | The same module at the same version exists twice, for example under two parents. |
module-deep-nesting | note | A module is nested more than 4 levels deep. It shows the chain. |
slow-module-startup | note | A module took more than 1500 ms to register and activate. |
task-failing | warning, critical | A task fails (critical when it has failed 5 times or more and never succeeded, or cannot be scheduled). Its group and owner are in the evidence. |
task-late | warning | The next run of a task is more than 2 minutes in the past. |
task-paused | note | A task is paused. |
executor-saturated | warning | Every thread of an executor is busy and 5 or more tasks wait. |
cache-pressure | note | A CacheBox cache has a hit ratio below 50% over 100 lookups, is at 90% of its object limit, or has 100 evictions. |
event-cache-never-hits | note | A cacheable event missed 10 times and never hit. |
The thresholds are fixed in code. The request rules, shown in the bar, are view-repeated and slow-event. A rule that needs a dependency range of a module (a version that does not satisfy what a parent asks for) is not in this version.
Ask Lensy and Find solution
With BoxLang+ and the assistant set up, every finding has Find solution and Ask Lensy, and every tab of the page has an Ask Lensy button with a question that fits the tab.
- Find solution asks Lensy to read the evidence with its ColdBox tools and then write one prompt for a coding agent: the context, the probable cause, the files and lines, what to change, what not to touch, how to verify, and a request for a patch and a test. You copy it. Lensy changes nothing. It runs only when you press it: nothing is prepared in the background and no tokens are spent until then.
- Copy prompt is free. It builds a prompt from the finding (names and numbers only) for any chat or coding agent you use.
Composition
The routes with their pattern, name, handler, action and module, the handlers (by convention or external), the interceptors declared in the configuration and the layouts. Long lists are cut at 300 rows and say so.
Modules
ColdBox modules can be nested several levels deep, and the same module can exist more than once on disk. This tab answers three questions: what loaded, how long it took and which copy won.
| View | What it shows |
|---|---|
| Timeline | One bar per module, indented by nesting level. A bar is the time the module took to activate. A parent's bar includes its children, because ColdBox activates the children inside the parent. Framework modules are grey. |
| Tree | The nesting as a tree, with version, entry point, activation time and where the module lives. |
| Table | One row per module: parent, version, author, when it registered, activation time, handlers, routes, interceptors. |
| Resolution | Every module name found on disk with all its copies and versions. The copy ColdBox loaded is marked loaded, the others not loaded. A name with different versions is flagged. |
How the duplicate check works
BxLens walks the module folders of your application (the folders of the loaded modules, modules and modules_app) and reads the name, slug and version of each box.json. Nothing else in the file is read. A scan stops at 400 files or 1.5 seconds and says so. A module that is found twice with different versions is flagged, because ColdBox loads one module per name and the other copy is silently unused.
Schedulers
The ColdBox schedulers and their tasks, in the same layout as the Tasks page: status (scheduled, paused, failing, not run yet), schedule, next run, last run, runs and failures, a next runs strip across all schedulers, and the groups tree with filter and an Ungrouped bucket. The Meta of a task (set in your scheduler with setMeta()) is shown in the detail, with secret-looking keys masked.
Viewing is free. Run now, Pause, Resume and Remove are BoxLang+ actions, blocked in a read-only console and written to the audit log (coldbox.task.run, .pause, .resume, .remove):
- Run now runs the task once, even if it is paused.
- Pause disables the task and cancels its schedule. Resume enables it and schedules it again.
- Remove takes the task out of its scheduler until the application reinitializes.
Task groups are free for BoxLang tasks too: see Tasks.
Caches
The CacheBox caches of the application, in the same layout as the Caches page: provider, hit rate, objects against the maximum, evictions, reaps and policy, plus a capped, filterable list of keys (keys only, never values).
Evict, reap and clear are BoxLang+ actions, like on the BoxLang Caches page. They are blocked in a read-only console and are written to the audit log (coldbox.cache.clear, coldbox.cache.reap, coldbox.cache.evict). Clearing the ColdBox event and view caches is always free: use the buttons in the bar.
Executors
The executors of the ColdBox AsyncManager with their health, type, thread use, queue and tasks per minute.
Routes
These routes serve the page. All are GET unless noted.
| Route | Answers |
|---|---|
coldbox | The ColdBox applications BxLens has seen. |
coldbox/{app}/overview | Version, environment, counts, flags. |
coldbox/{app}/advice | The Advisor findings. |
coldbox/{app}/events | What each event has done since the server started. |
coldbox/{app}/composition | Routes, handlers, interceptors, layouts. |
coldbox/{app}/modules | Modules, the resolution scan. |
coldbox/{app}/schedulers | Schedulers and tasks. |
POST coldbox/{app}/schedulers/{scheduler}/{task}/{run\|pause\|resume\|remove} | BoxLang+. |
coldbox/{app}/caches | Caches with statistics. |
coldbox/{app}/caches/{name}/keys?filter= | A capped key list. |
POST coldbox/{app}/caches/{name}/{clear\|reap\|evict} | BoxLang+. |
coldbox/{app}/executors | Executors. |
If the page says ColdBox did not answer
BxLens calls ColdBox through one small class and never lets a failure reach a request. When ColdBox changes in a way the class cannot follow, the page shows the reason instead of data. Support covers ColdBox 7 and 8. Please report the message.