Technical Manual sections
Reference › Technical Manual › Logging and debugging
For error pages, exit codes, and restarts, see Errors and restarts.
kitten.log (src/lib/log.ts) is a set of loggers, one per section:
lifecycle,event,streamingHtml, andrepl: these also log while the interactive shell is open.debug,router,html,watcher,pageSocketRoute,webSocketRoute, andverbose: these log only when you turn them on.
The LOG environment variable turns sections on. It is a comma-separated list of section names, where * turns on every section and a name that ends in * turns on every section that starts with the rest of the name (e.g., LOG=page* turns on pageSocketRoute). While Kitten runs, the kitten.log.all(), kitten.log.none(), and kitten.log.only() methods turn sections on and off. (on() and off() are aliases of all() and none().)
Inside Kitten, log with a section logger instead of console.info(), and use console.warn() and console.error() for what must always show. (This applies to Kitten itself, not to apps.)
src/REPL.ts starts once the server is listening. When Kitten’s standard output is a terminal, pressing s opens a Node.js REPL (read–eval–print loop) in the server’s process, and Ctrl C quits Kitten. Otherwise (e.g., under systemd), you connect with the shell command.
Both shells have these commands:
.ls: lists the keys of the globalkittenobject..stats: shows statistics about the Kitten server..settings,.sign-in, and.sign-out: show the links to the Settings app, the sign-in page, and the sign-out page..id: shows the owner’s ID. (.id createcreates the identity if it doesn’t exist yet, shows its secret, and asks the terminal to copy the secret to the clipboard.)
The shell saves its history in repl/history.txt in the app’s data directory (kitten.paths.APP_REPL_DIRECTORY). While a shell is open, the kitten.__replIsActive property is true.
LOG='*' kittenturns on every log section. (See Debugging routes for the sections that show what routes do, and Files for thewatchersection.)INSPECT=true kittenruns the Kitten bundle with--inspect-brk, without the Kitten Process Manager (see Launcher), so Kitten waits for a debugger to attach before it starts. In VSCodium, use the Attach command in the Run and Debug panel. In Chromium, go tochrome://inspectand select Open dedicated DevTools for Node.PROFILE=true kittenmakes page routes log how long each page takes to import and to render. It also turns onconsole.profileTime()andconsole.profileTimeEnd(), which the loader adds toconsole(src/lib/loader.ts). They callconsole.time()andconsole.timeEnd()whenPROFILEis set, and do nothing otherwise.FLAME_GRAPH=true kittenruns Kitten under 0x (see Launcher) to generate a flame graph. Kitten doesn’t restart when you change a file or when it crashes. It exits instead, and 0x opens the flame graph in your browser.In the interactive shell, the
kitten.requestsproperty lists the last 25 request URLs, and thekitten.pagesproperty contains the live pages that Kitten has in memory (the connected ones, and the ones that haven’t connected yet). The$tree()method on a page or a component shows its component hierarchy, and the$info()method also lists its methods and public properties. Thekitten.$tablesproperty lists the tables ofkitten.db, and thekitten.$showEventsOnTable()method logs the changes to one of them (see the Kitten introspection API).In development, while the shell is open or
LOG=lifecycleis set, Kitten logs a line you can paste into the shell to get a reference to each page that connects.On a server, the
kitten logscommand shows the service’s journal. The files in updates/ in the data home record what automatic updates did (see Updates).
Source code: