SeliseBlocks LMT Client (Node.js)

Logging + distributed tracing for any Node.js service, exported to the SELISE cloud over Azure Service Bus — set up with one function call. Node.js port of the C# Blocks.LMT.Client.

• Logs — BlocksLogger, Serilog-style message templates, batched + auto-correlated to the active trace.
• Traces — OpenTelemetry spans for incoming HTTP, outgoing 3rd-party HTTP, Express routes, and MongoDB commands (MongoDb::<command> spans), batched and exported.
• Transport — Azure Service Bus topic lmt-<serviceId>, with automatic retry + failed-batch queueing.
• Self-contained — owns all the OpenTelemetry wiring, so your app needs no @opentelemetry/* dependency of its own.

Requires Node ≥ 18.19 (OpenTelemetry 2.x SDK). Full guide: USAGE.md.

Install

npm install blocks-lmt-node

Quick start

// telemetry.js — require this at the VERY TOP of your entry file,
// BEFORE http / express / mongoose are loaded.
const path = require("path");
const { startTelemetry } = require("blocks-lmt-node");

module.exports = startTelemetry({ envPath: path.resolve(__dirname, ".env") });

// anywhere in your app
const lmt = require("./telemetry");

lmt.logger.logInformation("order {id} accepted total {amount}", "A-100", 42);

await lmt.runInSpan("price-calc", async (span) => {
  span.setAttribute("symbol", "BTC");
  return computePrice();
});

startTelemetry() reads config from a .env (or explicit options) and returns: { logger, runInSpan, getActiveTraceId, getActiveSpan, getTracer, instrumentMongoose, shutdown, lmtClient, ... }.

Configuration (.env)

lmt.service-id=YOUR_SERVICE_ID
lmt.connection-string=Endpoint=sb://<ns>.servicebus.windows.net/;SharedAccessKeyName=...;SharedAccessKey=...;EntityPath=lmt-YOUR_SERVICE_ID
lmt.x-blocks-key=YOUR_TENANT_KEY
# optional: lmt.log-batch-size=100  lmt.trace-batch-size=1000  lmt.flush-interval-seconds=5
#           lmt.max-retries=3  lmt.max-failed-batches=100  lmt.enable-logging=true  lmt.enable-tracing=true

Keep credentials in .env/secret manager only — never commit them.

What gets traced

| | Automatic? | Setup | |---|---|---| | Incoming HTTP, outgoing 3rd-party HTTP, Express routes | ✅ | none | | MongoDB queries (MongoDb::find, …) | ✅ per query | connect with { monitorCommands: true } + instrumentMongoose(connection) | | Your own business logic | — | wrap in runInSpan(name, fn) |

Logs in a trace's Log tab: a log shows under a trace only if emitted while the root span is active — i.e. log at handler level. Logs inside a runInSpan(...) child appear in the global Logs view but not the trace tab. See USAGE.md §7.

Logging

logger.logTrace / logDebug / logInformation / logWarning(template, ...args);
logger.logError / logCritical(template, errorOrArg, ...args);

Values appear in the message only where there's a {placeholder}; every arg is also stored as Arg0, Arg1, … Keep logs small (don't dump large objects).

Example services (for local testing)

Create a .env with your lmt.* keys, then:

npm run example:start    # logging service  (GET /health, GET /demo)
npm run example:test     # one-shot verification of the logging service
npm run example:trace    # tracing service  (GET /health, GET /trace) on port 3301
npm run example:trace:test

The /trace response includes the generated traceId for locating spans in the lmt-<serviceId> topic / SELISE cloud.

API

• startTelemetry(options?) — the primary entry point (above). Options: envPath, autoInstrument, instrumentations, ignoreIncomingPaths, registerShutdownHooks, plus explicit LMT fields. See USAGE.md §8.
• createLmtClient(options) (advanced) — returns { logger, traceProcessor, sender, shutdown } if you want to wire the OpenTelemetry provider yourself.
• instrumentMongoose(connection) / instrumentMongoClient(client) — attach the MongoDb::<command> span tracer (needs monitorCommands: true).
• BlocksLogger, LmtLogLevel (Trace…Critical), LmtTraceProcessor — exported for advanced use.

Payload compatibility

Sent to topic lmt-<serviceId>:

• Logs: { Type: "logs", ServiceName, Data: [...] }
• Traces: { Type: "traces", ServiceName, Data: { [tenantId]: [...] } }

with application properties matching the C# client (serviceName, timestamp, source, type).

Graceful shutdown

startTelemetry() installs SIGINT/SIGTERM flush hooks by default (registerShutdownHooks: true). For an app that owns its own shutdown order, pass registerShutdownHooks: false and call await lmt.shutdown() yourself. See USAGE.md §7–8.

Publish

# bump "version" in package.json first
npm pack --dry-run   # preview the tarball
npm publish

Only src/, README.md, USAGE.md, LICENSE are published (see the files field) — no .env, scripts, or tests.