lib: implement node:logger

[jasnell]

A simpler attempt to add a structured logging API.

Uses a provider model similar to VFS.

This implements four providers out of the box:

• ConsoleProvider -- emits to stderr or stdout using Utf8Stream
• EventProvider -- implements EventEmitter, emits logs as events
• DiagnosticsProvider -- emits to diagnostics channels
• AggregateProvider -- fans out to multiple providers

const { create } = require('node:logger');
const logger = create(); // default logger to console
logger.info('foo');

// ...
const als = new AsyncLocalStorage();
const logger2 = create(new ConsoleProvider({ pid: true }), {
  name: 'foo',
  bindings: {
    'abc': 'included in every log line',
    'xyz': als,  // current als.getStore() included in
                 // every log line
  }
});
logger2.info('foo', { baz: 1 });

The Logger itself keeps things as simple as possible, leaving actual handling of the log events to the providers, which can be fully customized. Easy to adapt to other loggers like pino or extend capabilities without directly touching the facade.

The current json output produced by the ConsoleProvider is:

{"attributes":{},"bindings":{},"level":{"name":"info","value":30},"message":"test","name":"foo","timestamp":1788677600214,"pid":670179}

But there are options to produce a "flattened" version

We should bikeshed the format a bit before this lands.

---

Updated... I've tweaked things just a bit more.

The module itself exports the create function directly, making it possible to do:

const create = require('node:logger');
const logger = create();

It still has all the exports off of it.

There's also a singleton default provider. When create() is called without a provider option, then the default singleton ConsoleProvider is created lazily. An application can override the default using setDefaultProvider...

const logger = require('node:logger');
logger.setDefaultProvider(new logger.EventProvider());

const log = logger();

log.warn('...');  // Uses the singleton EventProvider

This way, modules can just create a logger and dispatch to the application's default configured provider without worrying about where those will go.

Also includes a fix to fs.Utf8Stream's async and sync flush handling that I noticed wasn't working quite right when testing.

[nodejs-github-bot]

Review requested:

• @nodejs/loaders
• @nodejs/startup

[TheOneTheOnlyJJ]

@mertcanaltin, your experience from #60468 may be valuable here.

[codecov]

Codecov Report

❌ Patch coverage is 97.10327% with 23 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.19%. Comparing base (1e0ebef) to head (efff647).
⚠️ Report is 26 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/internal/streams/fast-utf8-stream.js	87.69%	16 Missing ⚠️
lib/logger.js	98.94%	7 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #65840      +/-   ##
==========================================
+ Coverage   90.17%   90.19%   +0.01%     
==========================================
  Files         771      772       +1     
  Lines      265097   265854     +757     
  Branches    50362    50559     +197     
==========================================
+ Hits       239054   239786     +732     
- Misses      17004    17013       +9     
- Partials     9039     9055      +16     

Files with missing lines	Coverage Δ
lib/internal/bootstrap/realm.js	96.98% <100.00%> (+<0.01%)	⬆️
lib/logger.js	98.94% <98.94%> (ø)
lib/internal/streams/fast-utf8-stream.js	84.00% <87.69%> (+3.13%)	⬆️

... and 39 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[mertcanaltin]

The Logger keeps things as simple as possible, leaving actual handling of the log events to the providers, which can be fully customized. Easy to adapt to other loggers like pino or extend capabilities without directly touching the facade.

I think this step is very good for review. We started with a big step before, but it was very costly for reviewers.

I want to share some topics we had in #60468. I hope they help this PR.

Do custom levels need to be part of the public contract in the first version? I'm not sure. Level names and numeric ordering are a long-term cost for both users and providers.

My suggestion is to limit the first version to the built-in levels, so the API stays smaller. Providers can do their own mapping internally when necessary.

This comment is not a blocker for this PR.

[jasnell]

Do custom levels need to be part of the public contract in the first version

I think they ought to be, yes, at least to an extent. I absolutely don't think we should do the automatic custom level method installation like what pino does (e.g. logger.foo(...)) but the generic logger.log(level, ... gives enough coverage to minimally meet the need.

[nodejs-github-bot]

CI: https://ci.nodejs.org/job/node-test-pull-request/77194/