Skip to main content
Pulse includes a compiled React dashboard for inspecting events, consumers, deliveries, attempts, errors, and leases. It reads the Pulse collections directly from MongoDB and does not load your service or application code.

​
Start the dashboard

From a project that has @orion-js/pulse installed:
By default, it listens on http://127.0.0.1:4111 and opens the browser. The database can be part of the URI or passed separately:
The command accepts the URI from the first positional argument or, in order, MONGO_URL, MONGODB_URI, or DATABASE_URL.

​
Command options

​
What you can monitor

The overview provides:
  • MongoDB availability and query latency.
  • Retained events, deliveries, attempts, and subscriptions.
  • Pending, successful, and terminal-error deliveries.
  • Queued, active, and expired attempt locks.
  • Error rate and oldest pending delivery.
  • Published, successful, and failed throughput over one hour to 30 days.
  • Per-topic and per-consumer-group health.
  • Recent failures with their error codes and messages.
The explorer views provide paginated inspection of:
  • Events and their payloads, headers, retention date, and group outcomes.
  • Deliveries by topic, group, status, event, and final attempt.
  • Attempt history, retry timing, duration, error details, and lock state.
  • Durable subscriptions, offsets, configuration, and active leases.
Use live refresh for a five-second operational view, or turn it off and refresh manually while investigating a changing record. Live refresh runs only while the dashboard tab is visible, and only the active view queries MongoDB. Switching tabs pauses all dashboard reads until the page becomes visible again. The UI includes light and dark themes and responsive layouts.

​
Health interpretation

The overview summarizes operator signals: These are operational hints, not application-level service-level objectives. A retained historical delivery error can keep the state at attention until TTL cleanup.

​
Read-only architecture

The installed package contains two dashboard assets:
The CLI starts node assets/dashboard.js. The server connects to MongoDB, serves the compiled frontend, and exposes read-only GET endpoints for that frontend:
  • /api/health
  • /api/overview
  • /api/events
  • /api/deliveries
  • /api/history
  • /api/subscriptions
Mutation methods are rejected. Importing @orion-js/pulse from a service does not import the dashboard server, React, or its browser assets into the service process. All dashboard reads use MongoDB’s secondaryPreferred read preference, falling back to the primary only when no eligible secondary is available. Every query also receives a server-side maxTimeMS and matching connection, socket, server-selection, and pool wait timeouts. The default is thirty seconds and can be changed with --query-timeout-ms. Because monitoring reads may come from a secondary, the dashboard can briefly lag the primary during replication delay. React, Vite, Tailwind CSS, and the UI components are build-time development dependencies. They do not increase Pulse’s runtime dependency graph.

​
Security

The dashboard has no built-in authentication and can display event payloads, headers, error stacks, and service topology.
Keep the default loopback host unless access is protected. If you bind to 0.0.0.0, place the dashboard behind an authenticated reverse proxy and network policy.
Create a dedicated MongoDB user with read-only access to the four Pulse collections. The dashboard does not need permission to create indexes or mutate documents. Avoid placing credentials directly in shell history. Prefer an environment variable:

​
Troubleshooting

​
A database is required

Include it in the URI or pass --database:

​
Dashboard assets are missing

Reinstall or rebuild @orion-js/pulse. Published packages include assets, dist, and dist-cli; source-only checkouts must run the package build before using the CLI. The dashboard and Pulse workers query MongoDB directly through polling; neither requires or opens Change Streams.