Console Logging
Probe API Signature
A probe.gl function invocation typically looks like this:
log.probe(priority, message, ...args)();
There are a lot of conventions and built-in capabilities. The following sections contains observations about this signature and provide more background about what is going on.
Why Double Function Calls?
A distinctive aspect of the probe API is the requirement for double function calls, i.e. the extra parenthesis at the end of log.probe``(...)()
. The double function calls ensure that the Chrome browser console's clickable links are generated correctly. Thanks to these double parentheses you can click on a probe in the Chrome console and "go" directly to the probe call in your application source code.
The double parenthesis is a rather unusual JavaScript programming idiom and if you forget it nothing will be logged. Therefore probe.gl will keep track of whether a returned log function was called and warn you next time you call probe if it wasn't.
Log Priority
A basic feature of probe.gl is that you can assign a priority
threshold to each probe. The term priority
can seem a little counter-intuitive at first, as specifying a higher value in your probes actually make them less likely to "fire". The basic idea is that a probe will only "fire" if the log priority is greater than or equal to the probe's priority.
Because of this most probe.gl APIs take a priority
parameter as a first argument.
| 0
| Unconditional. Always fires. errors and warnings are priority 0
by default. |
| 1
| Fires . |
| 2
| Always fires. |
| 3
| Always fires. |
| 4
| Always fires. |
Note that regardless of log level, probes will only fire assuming probe itself is enabled.
Log Options
The priority
parameter is an overloaded parameter that can be supplied in the following ways:
priority
can be ommitted entirely. In this case,priority
defaults to0
, which means that the probe is executed / printed regardless of log level.priority
can be aNumber
, in which case it is used as thepriority
threshold of this probe, which will only "fire" if the log priority is greater than or equal to this value.priority
can be anObject
, in which case it is used as thepriority
threshold of this probe. It will only "fire" if the log priority is greater than or equal to this value.priority
(Number
) - as above, if not supplied defaults to0
(fires unconditonally if probe is enabled).once
(Boolean
|Number
) - iftrue
, the argument string will be cached and this log will only be fired once. If a number, this is the minimum amount of seconds between logging the same message.
Log Message
Many probe.gl API calls take a message
parameter. This message
is an overloaded parameter that can be either a string or a function that returns a string, which will be called every time the probe fires.
The main purpose of supporting functions is to avoid situations where a message string is being generated even when the probe doesn't fire:
A typical inconvenience when logging is unwanted performance impact when generating dynamic log messages. In the case below, the string template literal is being generated every time the line executes, even when logging is disabled:
log.probe(1, `${object} has ${value}`)();
With probe, the solution is easy:
log.probe(1, () => `${object} has ${value}`)();
Now the performance overhead of the probe is again minimized.
Log Parameters
Most probe method accept a variable number of additional arguments at the end of the function call. These arguments will be passed directly to the underlying console method. This allows you to leverage the built-in Chrome console printing mechanisms for e.g. Objects and Arrays (these allow you to expand and descend into objects).
Probe Timings
Types of Probes
Groups
Chrome provides a wonderful grouping feature that allows us to organize logs in expandable headers.
Tables
Chrome provides a table logging method
Images
Under Chrome it is possible to log images to the console, using a rather involved styling trick. log.image
will be a no-op under all other environments.