@vedapointe-shared/node-logger
v3.0.0
Published
A node.js service logger.
Readme
Vedapointe Node Logger
A shared winston logger for our Node services. In 3.x it also ships logs and traces to ClickHouse with OpenTelemetry: see docs/opentelemetry.md for how that works and every option, and docs/otel-v3-plan.md for the rollout plan.
How to run
npm run dev- Watch and build files to thelibdir.npm run build- Build files to thelibdir.npm test- Run the tests.npm run lint- Lintsrcandtest.
Setting up a service
Every service loads the preload before the app and calls initOtel() once at startup.
Express service on ECS
CMD ["node", "--require", "@vedapointe-shared/node-logger/register", "main.js"]import {
initOtel,
installShutdownHooks,
vpExpressContext,
vpExpressRequestLogger,
} from '@vedapointe-shared/node-logger';
await initOtel({
serviceName: process.env.APP_NAME,
environment: process.env.APP_ENV,
level: process.env.LOG_LEVEL,
});
app.use(vpExpressContext({ user: true, tenantId: true }));
app.use(vpExpressRequestLogger({ skip: skipHealthCheckLog }));
const server = app.listen(port);
installShutdownHooks(server);initOtel() throws at startup when serviceName or environment is missing or invalid.
Lambda
Set NODE_OPTIONS=--require @vedapointe-shared/node-logger/register on the function (after deploying a build
that uses node-logger 3.x), then:
import { initOtel, withTelemetry } from '@vedapointe-shared/node-logger';
async function main(event: ScheduledEvent) {
await initOtel({ serviceName: vars.appName, environment: vars.appEnv });
// ...
}
export const handler = withTelemetry(main, {
attributes: (event) => ({ tenantGuid: tenantGuidFrom(event) }),
});Logging
import { logger } from '@vedapointe-shared/node-logger';
logger.info('Contact plan created', { contactPlanId, actionId });
logger.warn('Retrying', { attempt });
logger.error('Failed to save contact plan', err);- The object after the message becomes structured attributes (filterable in ClickHouse); put ids there rather than in the message.
- Pass errors as real
Errorobjects; they becomeexception.*fields with the stack trace. withLogContext({ eventUuid }, () => work())adds attributes to every line logged insidework.- While logs are exported, stdout (CloudWatch) only gets warnings and errors. Everything at
levelgoes to ClickHouse.
More in docs/opentelemetry.md.
Muting noisy requests (e.g. health checks)
vpExpressRequestLogger takes an optional skip function. It runs after the response finishes, so it can see
the final res.statusCode; return true to leave a request out of the request log. Use it to mute successful
health check polling without hiding failed probes:
const HEALTH_CHECK_PATHS = ['/status', '/health', '/healthz', '/ready', '/live'];
app.use(
vpExpressRequestLogger({
skip: (req, res) => HEALTH_CHECK_PATHS.includes(req.path) && res.statusCode === 200,
})
);Moving from 1.x / 2.x to 3.x
| 1.x / 2.x | 3.x |
| ------------------------------------------- | -------------------------------------------------------------- |
| vpLogger(options) | initOtel({ serviceName, environment, level }) |
| vpExpressLogger(options) | vpExpressContext({ user: true, tenantId: true }) |
| vpExpressRequestLogger(options) | vpExpressRequestLogger({ skip }) |
| LoggerOptions.format: 'ecs' \| 'otel' | Removed. stdout is always ECS JSON (coloured text for local) |
| registerInstrumentation() / preload file | --require @vedapointe-shared/node-logger/register |
| initTracing() | Done by initOtel() |
| Manual flushTracing() in a Lambda handler | withTelemetry(handler) |
| process.on('SIGTERM', shutdownTracing) | installShutdownHooks(server) |
| vp-trace-id / vp-request-id headers | Removed. Lines carry the real OTel trace and span ids |
| Default level debug | Default level info |
Unchanged: the logger export, ECS JSON on stdout (with the log.level field the error emailer filters on),
flushTracing and shutdownTracing. Node 22 or later is required.
Minor or major release
npm version minor # or: npm version major
npm publish --access publicprepublishOnly runs automatically before publish — it lints, tests, and builds.
