Glossary

Glossary

The words BxLens uses, in plain language. The i icons in the bar and in the console show the same text, and the console has a Glossary page with a search box.

Advisor

A fixed set of rules that look at data BxLens already has and report what looks wrong, with the evidence and a suggestion.

Findings are free. The thresholds are fixed and listed in the documentation.

Average

The total time divided by the number of requests.

One very slow request lifts the average. Compare it with p50 and p95.

Board

A short ranked list that answers: what should I look at first?

Each row says why it ranks and links to the evidence.

Error rate

Failed requests divided by all requests. A request failed when its status is 500 or more, or an exception was not caught.

A board needs a minimum number of requests, so one failure out of one request does not top the list.

Event cache

ColdBox can keep the output of an event in the template cache, so the next request for it is answered without running the handler.

An event is cacheable when its handler has cache=true. The cache key includes the rc values, so URL variations make separate entries.

Event cache hit

ColdBox answered this request from the event cache. Only preProcess and postProcess ran.

BxLens infers a hit: the event is cacheable and the handler never ran.

Event cache miss

The event is cacheable, but it was not in the cache, so the handler ran and its output was cached.

Many misses without a hit mean the cache key changes on every request.

Eviction

An object removed from a cache before it expired, to make room for a new one.

Many evictions mean the cache is too small for what is put in it.

Executor

A pool of threads that runs tasks in the background.

Check its active threads, its queue and how fast tasks finish.

Executor queue

Tasks waiting for a free thread of an executor.

A queue that keeps growing means tasks arrive faster than they finish.

Finding

One thing the Advisor found: a severity, the evidence, a suggestion and the page that shows it.

Critical needs action, warning needs a look, note is good to know.

Garbage collection (GC)

The JVM freeing memory that nothing uses any more. While it runs, your application can pause for a moment.

Frequent or long collections mean the heap is too small or the application creates too many objects.

Handler

A ColdBox class whose functions (actions) answer an event, for example users.show is the show action of the Users handler.

The time in the handler is the time spent in the action itself.

Heap

The memory the JVM gives to your objects. It grows up to the maximum and is cleaned by garbage collection.

A heap that stays near its maximum after a collection is a memory problem.

Hit ratio

How often a cache had the answer when it was asked. Hits divided by hits plus misses.

A low ratio means the cache is not helping: the keys are different every time, the timeouts are too short, or the cache is too small.

In flight

A request that has started and has not finished yet.

Many requests in flight for a long time point to a stuck lock, a slow database or an exhausted pool.

Interceptor

A ColdBox class that listens to interception points such as preEvent or postProcess and runs code at those moments.

BxLens registers one of its own to see the request.

Late task

A task whose next run was due more than two minutes ago and has not happened.

The executor may be busy, or the task may be stuck.

Layout

The page frame of a ColdBox request. A layout wraps the views, so its time includes them.

Look at layout time minus view time to see what the layout itself costs.

Max

The slowest single request seen.

It can be a one-off such as the first request after a start, which includes compiling templates.

Minimum volume

A board ignores a URL or event with too few requests, so one failure or one slow request does not top the list.

The minimum is shown on each board.

Module activation

The time ColdBox needs to load a module and run its configuration and onLoad.

A parent's time includes its child modules. Startup pays this on every reinit.

Module resolution

Which copy of a module ColdBox loaded when the same module exists in more than one place or version.

ColdBox loads one module per name and skips the other copies without telling you. The Resolution view shows the ones it found and which one won.

N+1 query

The same query was run again and again, once for each row of an earlier result.

One query for the list plus one query per row. Fix it with a join, or load the related rows with one query that uses IN.

Nested module

A module inside the modules folder of another module. It can go several levels deep.

Deep nesting slows startup and hides duplicate versions.

p50 (median)

Half of the requests were faster than this. The typical request.

If p50 is low and p95 is high, most users are fine and a few wait a long time.

p90

9 out of 10 requests were faster than this.

Use it with p50 to see how far the slow tail stretches.

p95

95 out of 100 requests were faster than this. It is the slow ones: 1 request in 20 took longer.

Look at p95 when the median looks fine but people still complain. BxLens counts latency in buckets (5, 10, 25, 50, 100, 250, 500 ms and so on), so a percentile is the upper edge of the bucket that holds it.

p99

99 out of 100 requests were faster than this. Only 1 request in 100 took longer.

p99 shows the worst cases that real users hit now and then. It is noisy when there are few requests.

Reap

A cleanup of a cache that removes the objects that have expired.

Reaping happens on a schedule. Reaping by hand only brings it forward.

Redaction

Hiding a value that looks like a secret (a password, token or key) before it is shown or sent to a model.

BxLens never reads the values of rc or prc, and masks secret-looking names everywhere.

Reinit

Restarting the ColdBox framework inside the running application: configuration, handlers, modules and caches are loaded again.

Sessions and anything the application keeps in memory are lost. ColdBox reads the request for the reinit key and, if one is set, a password. BxLens never reads that password.

Scheduler

Something that owns scheduled tasks and runs each at its time on an executor.

BoxLang has schedulers, and every ColdBox application has its own.

Slow query

A query that took longer than the slow query limit (thresholds.slowQueryMs).

The first run can include a new connection. Look at the query plan in your database.

Slow request

A request that took longer than the slow request limit (thresholds.slowRequestMs).

Set the limit in the settings. On BoxLang+ a slow request also gets a stack sample that says where it was.

Tag

A short word on a request that says what kind of request it was, for example coldbox or checkout.

BxLens tags ColdBox requests itself. Your code can add more with lensTag().

Task group

A name you give to tasks that belong together, for example billing/invoices.

A slash makes a tree: billing/invoices sits under billing. Tasks without a group are in Ungrouped.

Task meta

Facts the code attached to a task with setMeta: an owner, a runbook link, a team.

Secret-looking keys are hidden. Meta is free to read.

Throughput

How many requests the server handled, usually per minute.

A drop with the same traffic usually means requests are stuck or failing before they finish.

View cache

ColdBox can cache a rendered view with cache=true on the view. The next render returns the saved text.

Cache a view that is expensive and the same for many requests.

View rendered more than once

The same view was rendered two or more times in one request.

Often a partial inside a loop. Render it once and reuse the text, or cache the view.

Where the time goes

Calls multiplied by the average time: the biggest total cost.

A fast URL called very often can cost more than a slow one called once.