systemview-plugin
v2.23.0
Published
Connects your SystemLynx project to the SystemView UI
Downloads
60
Readme
systemview-plugin
Connects a SystemLynx service to SystemView — the documentation and testing suite for SystemLynx.
Installation
npm install systemview-pluginSetup
const { App } = require("systemlynx");
App.startService({ route, port })
.module("Users", Users)
.module("Orders", Orders);
if (process.env.SYSTEMVIEW_HOST) {
const SystemViewPlugin = require("systemview-plugin")({
connection: process.env.SYSTEMVIEW_HOST, // SystemView API URL
specs: "./specs", // local path for docs and test files
projectCode: "myProject", // groups services together in SystemView
serviceId: "MyService", // name for this service
});
App.use(SystemViewPlugin);
}Set SYSTEMVIEW_HOST to your SystemView instance, e.g.:
SYSTEMVIEW_HOST=http://localhost:3000/systemview/api node index.jsConfig options
| Option | Default | Description |
|---|---|---|
| connection | http://localhost:3300/systemview/api | SystemView API URL to register with |
| specs | ./specs | Local path for docs and test files |
| projectCode | — | Groups services together in the UI |
| serviceId | — | Name for this service |
| logs | ./systemview.logs | Base name for the per-service NDJSON log file — written as systemview.<serviceId>.logs so sibling services sharing a cwd don't collide on one shared file |
| limit | 100 | Default number of entries getLog returns |
| trace | true | Auto-tracing — see below |
| redact | [] | Paths to mask in logged arguments/returnValue — see below |
| exclude | [] | Module or Module.method names to skip entirely |
| useSystemViewLogs | true | Register the local log module + auto-instrumentation |
| useSystemViewUI | true | Register with the SystemView UI server |
| stats | true | Roll the trace stream into bounded per-method stats (counts, latency histograms → p50/p95/p99, status codes, per-minute buckets w/ per-method rollups, 24h retention) — powers the UI's Stats page, incl. its time-range windowing. false to disable, or an object of overrides ({ bucketMs, retention, file }) |
| tentacle | null | A live LoadBalancer Tentacle handle — puts the plugin in LB mode: it reads cluster state in-process (getClusterState) and records route_assigned fairness tallies + a join/evict timeline, served via SystemView.getCluster() for the Stats page's Load Balancer window. Auto-detected via App.getModule("Tentacle") when the plugin is loaded inside an app that registers the Tentacle |
trace
Controls auto-instrumentation. Every RPC call emits a start trace and one terminal trace — end on success, error on failure — all sharing a single traceId.
trace: true(default) — trace every call.trace: false— disable auto-tracing entirely.trace: (req) => ({ ...ctx })— a function returning request-scoped context. It runs fresh at each entry, and its result is merged into every record sharing that request'straceId— thestart/end/errorauto-traces and any manualthis.log()/warn()/error()/debug()fired during the request. Use it to stamp e.g. a user id onto everything a request logged, so you can filter the whole request by who caused it. (Out-of-request logs carry noreq, so they get nothing.)
trace: (req) => ({ user_id: req.session?.user_id })redact
Masks sensitive values in the captured arguments/returnValue before they're written. Paths are relative to the argument array — ["[0].password"] masks password on the first argument. Masked values become "[REDACTED]".
redact: ["[0].password", "[0].card.number"]exclude
Skip logging/tracing for whole modules or specific methods:
exclude: ["HealthCheck", "Users.ping"]What it does on startup
- Registers with SystemView — sends connection data to the SystemView server so the service appears in the UI under
projectCode > serviceId - Writes
systemview.manifest.json— saves connection data and spec file locations to the project root so the SystemView CLI can run tests without the SystemView server running - Rolls up stats (when
statsis on) — bounded per-method rollups from the same trace stream, read live viaSystemView.getStats() - Propagates traces across services (SystemLynx ≥ 3.2) — outbound calls made through
this.useService(...)are stamped withx-sv-trace(the inbound request's trace id) andx-sv-caller(service.Module.method); the receiving service's plugin adopts the trace and records the caller → the Stats page's Topology draws real caller→callee edges with live call volumes - Observes local module coupling (SystemLynx ≥ 3.3) — listens for the framework's
use_module/use_service/event_subscriptionsignals and records who's wired to whom in-process → the Stats page's Module Coupling report
If multiple services in the same project use the plugin, each one merges its own entry into the manifest rather than overwriting it.
systemview.manifest.json
Written automatically to the root of your service project on each startup:
{
"projectCode": "myProject",
"services": [
{
"serviceId": "MyService",
"system": {
"connectionData": {
"serviceUrl": "http://localhost:4100/my/api",
"modules": [ ... ],
"routing": { ... }
}
},
"specList": {
"docs": ["Users.md"],
"tests": ["Users.signUp.json"]
}
}
]
}Add it to .gitignore — it's a local artifact that regenerates on each startup.
With the manifest in place, the CLI can run tests directly against your live service without needing the SystemView server:
systemview test myProjectSpecs folder
The plugin reads and writes documentation and test files from the specs path you configure:
specs/
docs/ # markdown files, one per method
tests/ # JSON test files, one per methodThese files are committed to your repo. The SystemView UI saves to them via the plugin's saveDoc and saveTest methods.
