aarokorhonen/pino-preview

A utility web app for real-time previewing of structured JSON logs

Pino Preview 🌲

Interactive Web Viewer for Structured Logs

This is a utility web app for near-real-time previewing of structured JSON logs. It is designed to consume output from applications which use the pino library format for logs.

The utility runs on Node.js, and uses websockets to stream log information to a locally running web interface.

Disclaimer

Note: This is experimental software which may change at any time under development, and should not be relied on for critical use cases.

Note: For security reasons, never run this software against untrusted or potentially malicious input.

Installation

Publishing this package in the npmjs.com registry is currently work-in-progress. In the meanwhile, you can install the package directly from GitHub.

Using NPM

npm install --global "git://github.com/aarokorhonen/pino-preview#release/latest-experimental"

Using Yarn

yarn global add "git://github.com/aarokorhonen/pino-preview#release/latest-experimental"

Usage

This app provides a CLI command called pino-preview which consumes input from the stdin stream. To use it, setup a pipe for the log-producing app (use cat or tail -f if your logs are in a file). For example:

./run-your-app.sh | pino-preview

By default, the app will be served at http://localhost:3001. This can be modified by specifying the PORT environment variable. Use the --open flag to automatically open the web app in your default browser.

Using the sidebar controls, you can filter the log entry view by free text search, log level, timestamp, or by the package field of JSON objects.

As long as you remain scrolled to the bottom of the log panel, the view will auto-follow to scroll down to new log entries as they appear.

For convenience, this app also forwards stdin to stdout, you can also see all log entries in your terminal in addition to the web interface. You can also pipe them to other utilities (such as pino-pretty). For example, a complete usage might be:

./run-your-app.sh | pino-preview --open | pino-pretty

pino-preview's Issues

Fix details pane responsive styles for small viewports

Details pane layout is broken on small viewports (width <= 1028px):

Scroll-to-bottom feature is inconsistent

Sometimes when pressing the downward arrow button in the bottom right corner, the browser will not stick scrolling to bottom as expected.

This issue reproduces inconsistently and can sometimes cause the "renders 100 messages" Cypress test to be flaky.

GitHub Actions 'Release' workflow should ensure `package.json` has correct version

Automating this will reduce human error during the release process, and potentially also avoid manual Pull Requests such as #191

Options:

1. The workflow can check the package.json field to ensure that the tag input (such as v0.1.5-experimental) matches the package.json field (such as 0.1.5)

2. Additionally or alternatively, the workflow can automatically modify this file, commit, and push the related change to origin.

Improve perfomrance when ingesting a very large number of lines

The app can become sluggish if ingesting a very large number of lines, such as large time series data or large log dump files.

Potential options:

• Pagination
• Culling very old lines
• ...

Shell prompt sometimes left in garbage state after app terminates

Sometimes when using pipes, if the left-most app uses control characters in specific ways, after the app terminates, stdout can be left in a garbage state (shell prompt not fully visible). Shell restart is required to restore it back to functional state. I do not have a screenshot at this time, and root cause is unknown. One option to fix this would be to add a CLI option to disable stdout forwarding by this app, bypassing the issue and ensuring that the environment is always intact.

Very large JSON objects are split into multiple lines

This happens when process.stdin emits multiple data events for a single JSON line. The app should automatically handle this case and parse the object back into syntactically valid JSON.

Open question: What is the standard NDJSON/JSONL best practice in this problem domain?

JSON `"msg"` fields with newlines are not displayed correctly on summary line

See screenshot where "msg" has an escaped newline character, but the summary line only renders one line:

Open question: Is there a standard NDJSON/JSONL best practice for handling newlines in the message field?

Font glyphs do not work on some browsers

Font glyphs have issues rendering on some browsers, such as some versions of Safari. Explore replacing custom font glyphs with SVG icons.

WebSocket client does not automatically attempt reconnecting after terminating

Connection can terminate for various reasons. Under most circumstances, the app should attempt to periodically reconnect the WebSocket, up to a certain limit.