Merv-Local

Centralized logs

Run several projects at once and watch one Merv-Logs page. Point each project at a shared report server with merv.log.server. Each project still keeps its own log/ copy; remote send is async and never blocks your tests.

You will learn
  • How to start a hub report server and open Merv-Logs
  • How to copy merv.log.server settings from the UI
  • How client projects forward logs with a project name
  • Why local write happens first (non-blocking remote POST)
  • How npx merv show-logs opens the live console directly

Overview

By default, Merv writes NDJSON under each project’s {merv.report.folder}/log/. That is ideal for a single repo. When you have API + UI + batch jobs in separate folders, centralized logs let you fan-in those streams to one hub.

Hub

One project keeps npx merv show-logs (or show-report) running.

Clients

Other projects set merv.log.server to the hub URL.

Project name

merv.log.source labels each line on the shared page.

Safe send

Local disk first; remote ingest on a background task.

How it works

  1. Hub starts the report server and opens Merv-Logs.
  2. On Merv-Logs, click Log server URL and copy the settings.
  3. Paste into each client project’s merv.properties.
  4. Run clients as usual — lines appear on the hub page, stamped with the project name.

Under the hood, clients POST to {merv.log.server}/api/logs/ingest. The hub appends those records into its own log/ folder so the live viewer can poll them.

Hub project

Pick any project that already uses Merv-Local (or create an empty hub with merv.properties + merv-client installed). Keep the server running while others send logs.

Open Merv-Logs directly

npx merv show-logs
npx merv show-logs --host 0.0.0.0
npx merv show-logs ./merv-reports --port 6174

Opens http://127.0.0.1:6174/merv-logs.html (default port).

Or via the dashboard

npx merv show-report --host 0.0.0.0
# then click Merv-Logs in the sidebar

Use --host 0.0.0.0 so other machines on the LAN can reach the hub.

Java hubs: You can also run MervLocalReportServer (see Share / Download — serve reports) or point npx merv show-logs ./merv-reports at a Java report folder.

Copy settings from the UI

  1. Open the hub Merv-Logs page over HTTP (not file://).
  2. Click Log server URL (same size as Clear view / Clear files).
  3. In the popup, use Copy settings (or Copy URL for the base URL only).

Copied settings look like: 

# Send this project's logs to the shared Merv-Logs server
merv.log.server=http://127.0.0.1:6174
# Project name shown on the shared page
merv.log.source=my-project-name
Note: If the hub was started with --host 0.0.0.0, the popup rewrites that bind address to 127.0.0.1 for local clients. For machines on another host, replace the host with your LAN IP (the same idea as Share on LAN).

Client projects

In each project that should send logs to the hub, add the properties to merv.properties (or mervlogger.properties on Java). Install merv-client / merv-client-api as usual and keep using MervLogger / console from merv-client. 

merv.log.server=http://127.0.0.1:6174
merv.log.source=checkout-api

Vite / React frontend (browser)

# .env
VITE_MERV_LOG_SERVER=http://127.0.0.1:6174
VITE_MERV_LOG_SOURCE=frontend
import { console } from 'merv-client/browser';

console.log('User signed in', { userId });

The merv-client/browser entry only uses fetch — no filesystem. DevTools output is unchanged; lines are POSTed to the hub’s /api/logs/ingest.

merv.log.source is the project name shown on the shared page. If you omit it, JS uses the package.json name (or folder name); Java uses the project folder name.

Env overrides: MERV_LOG_SERVER, MERV_LOG_SOURCE (Node). In Vite/React use VITE_MERV_LOG_SERVER and VITE_MERV_LOG_SOURCE with import { console } from 'merv-client/browser'.

Doctor setup-log

Before wiring merv.log.server on client projects, run the logging-only doctor on each repo: 

npx merv-client doctor setup-log
npm install
npx merv-client doctor set console
# optional: wire console.log → merv-client (Node backends / scripts)

Full reference: Merv-Logs — Doctor commands (setup-log, set console, unset console).

Properties

Property Purpose
merv.log.server Base URL of the hub report server (no trailing slash required). Example: http://127.0.0.1:6174. When unset, logs stay only in this project.
merv.log.source Project name stamped on forwarded lines (Merv-Logs project field). Optional aliases: merv.project.
merv.logger.file Local NDJSON under this project’s log/ (default true). When merv.log.server is set, a local copy is still written first even if you mainly care about the hub.

Local first, async send

npx merv show-logs

Same server as show-report, but the browser opens /merv-logs.html immediately. 

npx merv-client doctor setup-log
npm install
npx merv show-logs
npx merv show-logs --host 0.0.0.0
npx merv show-logs --port 6174 --no-open
npm run show-logs

doctor setup-log adds only Merv-Logs essentials (merv.properties, show-logs script, merv-client dep) — no jsconfig.json or custom-report sample. Options match show-report: --host, --port, --no-open, optional report folder path.

Troubleshooting

Symptom What to check
Client logs missing on hub Hub server must be running. URL must be reachable (curl http://127.0.0.1:6174/api/logs/ingest from the client machine). Confirm merv.log.server has no typo.
Still seeing old Merv-Logs UI Report folders cache merv-logs.html. Restart npx merv show-logs (it refreshes the page from the package) and hard-refresh the browser.
Cannot find module 'merv-client' Run npm install at the project root (where package.json lists merv-client). merv.properties alone does not install the npm package.
Lines have no project name Set merv.log.source=your-project. The name is stamped only when forwarding to a hub.
LAN clients cannot reach hub Start with --host 0.0.0.0, allow the port in the firewall, and use the hub machine’s LAN IP in merv.log.server (not 0.0.0.0).

What’s next

← Back to Merv-Local documentation