Introduction

DSH extends Host and client capabilities through plugins. When troubleshooting runtime issues, if the output of the Host-side Cordis logger only exists in the process logs, it is not convenient to view and replay. dsh-logger-panel connects this output to the Settings > Logs page, provides a live view via SSE, and writes records to JSONL files with date and size limits.

What it is

dsh-logger-panel is a DSH plugin: it captures Host-side Cordis logger output, allows real-time viewing in the Web profile’s settings page, and persists to rotating JSONL files. The repository address is https://github.com/LingLambda/dsh-logger-panel, the license is MIT, the version in package.json is 0.2.0, and packageManager is yarn@4.15.0.

It is a dsh bundle: package.json points dsh.bundle to cordis.patch.yml and declares dsh.client, allowing the Web profile to automatically discover the browser-side bundle.

Requirements

First, confirm that the environment meets the following requirements:

  • DSH with Web profile, including the Settings shell, client module system provided by dsh-client-ui-settings, and dsh-host-webserver; version 0.1.0-rc.6 or later.
  • Node version is ^22.19 || >=24.

Core Features

Below are the main capabilities of the plugin:

  1. Captures Host-side Cordis logger output and sends it to the Settings > Logs page via SSE.
  2. The live view uses snapshots and appends records in batches of 100 ms.
  3. The page renders records as plain text; original logger parameters, Fiber references, ANSI escapes, and executable markup do not pass through the browser wire.
  4. The auto-follow at the bottom pauses when scrolling up and resumes when clicking Latest.
  5. After clicking Load older, historical records are read from rotated JSONL files, spanning across rotations and dates.
  6. Host retains the most recent 2000 records for the connected browser.
  7. Persistent filenames are YYYY-MM-DD-N.jsonl, rotating by date and size; the individual file limit is 5 MiB, and files older than 30 days are removed.
  8. The log directory defaults to $DSH_HOME/logs/dsh-logger-panel, with directory permissions 0700 and file permissions 0600.
  9. The disk queue limit is 1000 records; on persistent failure, the panel reports the failure, the live stream continues working, and omitted records are counted.
  10. Initial directory creation or file opening failure will reject plugin activation; subsequent write failures will stop persistence and report it in the panel while keeping the in-memory/SSE path.

Installation and Activation

Before installation, confirm the requirements above. The example uses the demo profile; the actual profile name needs to be adjusted according to the environment.

Installation example via npm:

dsh plugin --profile demo add dsh-logger-panel
dsh --profile demo

Installation via git:

dsh plugin --profile demo add github:LingLambda/dsh-logger-panel#<sha>

The <sha> here is a placeholder in the README example and needs to be filled in according to the actual commit. Before installation, you also need to authorize the build in the profile’s pnpm-workspace.yaml.

For local development, you can use an overlay against the Harness checkout:

pnpm dsh web --patch ./cordis.patch.yml --patch /absolute/path/to/dsh-logger-panel/overlay.yml

Overlay example:

- insert:
    - id: logger-panel
      name: /absolute/path/to/dsh-logger-panel/src/index.ts

This overlay inserts logger-panel and points to the local source entry point.

Typical Usage

After opening Settings > Logs, you can directly view the live logs.

Common operations:

  • Click Load older: reads earlier rotated JSONL records.
  • Scroll up: auto-follow pauses, making it easier to view the current window.
  • Click Latest: resumes following the latest logs.

If you need to override default behavior, you can modify the config of logger-panel in the profile patch. The provided configuration options include:

root、maxRecords、maxRecordChars、batchMs、maxFileBytes、maxAgeDays、maxPendingRecords、historyPageSize

The explicitly given defaults or limits are: root defaults to $DSH_HOME/logs/dsh-logger-panel, maxRecords is 2000, batchMs is 100, maxAgeDays is 30, maxPendingRecords is 1000, and the single JSONL file limit is 5 MiB.

Use Cases and Notes

This plugin is suitable for scenarios where you need to view DSH Host logs in real-time and retain a history that can be looked back upon. The live window has memory limits, while history pagination reads from rotated files.

Notes before use:

  • The plugin runs with the permissions of the current dsh process; you should check the source code, build method, and license before installation.
  • Logs will be written to $DSH_HOME/logs/dsh-logger-panel; directory permissions are 0700, file permissions are 0600.
  • If disk writing fails, live viewing can still continue, but historical persistence will stop, the failure status will be displayed in the panel, and omitted records will be counted.

Links

The DSH community directory is a separate site; this article does not describe it as an official app store.

  • Repository: https://github.com/LingLambda/dsh-logger-panel
  • Directory page: No fixed URL provided with this text; you can search for dsh-logger-panel in the DSH community directory.