Moleculer Laboratory

Self-hosted, open-source monitoring & observability dashboard for Moleculer microservices projects.

• Live cluster view — nodes, services, actions, events with real-time registry updates
• Topology & dependency graphs — animated traffic flow visualization
• Metrics — collection, aggregation, history charts and a metrics explorer with drag-and-drop dashboards (charts + KPI tiles)
• Distributed tracing — trace list with bubble chart, span waterfall view
• Centralized logs — live tailing with search
• Alerting — metric threshold / availability / log-rate rules, persisted alert history
• Data explorer — browse, filter and edit the entities of @moleculer/database services
• Workflows — job queues, task timelines and live signals of @moleculer/workflows
• REST API browser — list and invoke the endpoints published by moleculer-web gateways
• Interactive tools — call any action, emit/broadcast any event, command palette
• Self-contained — everything runs inside your infrastructure; embedded database by default, optional external PostgreSQL for long-term retention

Works with Moleculer >= 0.14 (tested with 0.14 and 0.15).

Quick start

npm i @moleculer/lab

// lab.service.js
const Laboratory = require("@moleculer/lab");

module.exports = {
	mixins: [Laboratory.AgentService],
	settings: {
		name: "My Project"
	}
};

// moleculer.config.js
require("@moleculer/lab");

module.exports = {
	logger: [{ type: "Console" }, { type: "Laboratory" }],
	metrics: { enabled: true, reporter: [{ type: "Laboratory" }] },
	tracing: { enabled: true, exporter: [{ type: "Laboratory" }] }
};

Start your project and open http://localhost:3210/lab — the exact URL is printed at startup.

The Laboratory has no built-in authentication: it serves the local project's data. If you expose it beyond your own network, protect it with a fronting reverse proxy.

Serving through moleculer-web

Disable the embedded server and mount the Laboratory behind your API gateway:

// lab.service.js
settings: { server: { enabled: false } }

// api.service.js (moleculer-web)
const { createWebRoute } = require("@moleculer/lab");

module.exports = {
	mixins: [ApiGateway],
	dependencies: ["$lab"],
	async started() {
		this.addRoute(createWebRoute(this.broker)); // serves /lab
	}
};

Long-term storage

By default data lives in an embedded database with a 30-minute retention. For long-term storage point the agent at a PostgreSQL server:

settings: {
	store: {
		connectionString: "postgres://user:pass@localhost:5432/lab",
		metrics: { retentionMins: 7 * 24 * 60 },
		tracing: { retentionMins: 24 * 60 },
		logging: { retentionMins: 24 * 60 }
	}
}

Repository layout

pnpm monorepo:

Package	Description
packages/agent	@moleculer/lab — the agent service, collectors, HTTP API and bundled UI
packages/ui	The dashboard web app (Vue 3)
packages/shared	Shared API contract (types + schemas)

See CLAUDE.md for architecture notes and development conventions.

Development

Requires Node.js >= 22 and pnpm. The demo project's workflows feature needs a local Redis.

pnpm install
pnpm build          # build all packages + bundle UI into the agent
pnpm dev            # run the demo project with the agent (packages/agent/example)
pnpm dev:ui         # run the UI dev server (proxies to the demo agent)
pnpm test

License

MIT © MoleculerJS