imp-ui - Logging
imp has a small built-in logger. The library sends all of its own diagnostics through it, and your app can import the same logger for its own messages. Everything an imp app writes to the browser console then obeys one log level. You set that level per environment, with no change to the code.
How to use the logger
Import the ready-made logger, or create a named logger that puts a prefix on every message:
import { createLogger, logger } from 'imp/log'
logger.info('checkout opened')
const log = createLogger('myapp.cart')
log.debug('recalculating totals', { items: 3 })
log.warn('price feed is stale - using cached prices')
A logger has four methods: debug, info, warn, and error. Each accepts any number of
arguments, exactly like the console. An argument can be a string, an object, or an error. A named
logger puts its name in front of the first argument, as in myapp.cart: recalculating totals. A
filter on your prefix then shows only your messages, and a filter on imp: shows only the messages
of the library.
The messages go to the browser console. debug and info go through console.log, warn goes
through console.warn, and error goes through console.error. The severity filters of the
console, and its handling of a stack trace, keep working as usual.
Log levels
There are four levels, in this order: debug < info < warn < error. imp writes a message only
when its level is at or above the active level. The default level is info while you develop and
test, so the warnings and errors of imp show, and debug tracing stays quiet. In a built app the
default level is warn, so an info message does not fill the console of every user.
imp build always makes a production build. It removes the warnings and the debug trace of imp
itself from the bundle, with their text. A warning of imp points at a mistake in the code of the
app, so you fix it during development, where it shows. The debug trace is for you while you develop.
Their text is a large part of the library, and your users do not need it. The build keeps the errors
of imp, which report a problem of the running app, and every message of your own loggers. To read
the warnings and the trace of imp, run the app with imp start.
To set the level per environment, use the IMP_LOG_LEVEL value in an environment file. See
Environments in Configuration. In a built app, the level filters your own
loggers and the errors of imp:
{
"API_URL": "https://api.example.com",
"IMP_LOG_LEVEL": "debug"
}
You can also change the level at runtime, from the browser console, while you debug a running app:
import { logLevel, setLogLevel } from 'imp/log'
setLogLevel('debug')
logLevel() // 'debug'
What imp logs at the debug level
With IMP_LOG_LEVEL set to debug, imp traces its own activity under imp start and imp test.
A built app has no trace, because imp build removes it. The trace is the fastest way to see why a
binding updates too often, or does not update at all:
- State reads. Every
get(), with the value it returned. - State sets. Every applied
set(), with the new value. imp also logs a set it skipped because the new value equals the current one. - Subscriptions. Every
watchthat attaches and detaches, and each notification with its subscriber count. This includes the subscriptions thattext,view,each, and a state-bound prop create. - State lifecycle. The states imp initializes and resolves, and the consumers that bind again after a component moves.
- Computed states. Every recompute, including the ones whose result did not change.
- Component lifecycle. The components imp defines, mounts, and unmounts, and the components that bind their subscriptions again after a move.
The debug log prints state values as they are. So a password or an API key in a state shows in the
console of every developer who turns on debug tracing. A form field with secret: true keeps its
value out of the form state, so the log never contains it. See Forms in
Standard components. Keep any other secret out of state.
Everything at warn and error shows at the default level. That covers an invalid state value, a
failed subscriber, a mount failure, and similar problems. In a built app, only the errors of imp
remain, because the build removes its warnings and its debug trace.