lib: added logger api in node core by mertcanaltin · Pull Request #60468 · nodejs/node

mertcanaltin · 2025-10-28T19:09:56Z

Description

Adds an experimental node:logger module that provides a structured, high-performance logging API for Node.js. Available behind the --experimental-logger flag.

Refs: #49296

Architecture

Uses diagnostics_channel as the dispatch mechanism, loggers publish log records to level-specific channels, consumers subscribe to receive them
Pre-serializes bindings at construction time to avoid per-log overhead
Disabled log levels become noop functions, eliminating runtime level checks
JSON output uses the existing internal Utf8Stream (SonicBoom port) for high-throughput writes

API Surface

Logger, Producer class with trace, debug, info, warn, error, fatal methods
LogConsumer, Base consumer class for custom log handling
JSONConsumer, Built-in consumer that outputs structured JSON via Utf8Stream
child(bindings, options), Child loggers with inherited context and serializers
logger.<level>.enabled, Getter for conditional logging (typo-safe)
stdSerializers, Built-in serializers for err, req, res
serialize symbol, Symbol.for('nodejs.logger.serialize'), custom object serialization hook (stacked with field serializers)

Log levels follow RFC 5424 numerical ordering internally (trace: 10, debug: 20, info: 30, warn: 40, error: 50, fatal: 60). The API accepts string level names. diagnostics_channel channel names (log:trace, log:debug, log:info, log:warn, log:error, log:fatal) are used internally and can be subscribed to directly via diagnostics_channel if needed.

Performance

Benchmarked against Pino (output to /dev/null, n=100000):

Scenario	node:logger	pino	Difference
simple	6.06M ops/s	3.48M ops/s	+74%
child	5.76M ops/s	4.41M ops/s	+31%
disabled	174M ops/s	146M ops/s	+19%
fields	2.13M ops/s	1.36M ops/s	+56%

New files

lib/logger.js, Main module (Logger, LogConsumer, JSONConsumer)
lib/internal/logger/serializers.js, Standard err/req/res serializers
doc/api/logger.md, Full API documentation
benchmark/logger/basic-json.js, Benchmarks
test/parallel/test-log-basic.js, Core logger tests
test/parallel/test-logger-serializers.js, Serializer tests

Modified files

src/node_options.h / src/node_options.cc, --experimental-logger flag
lib/internal/process/pre_execution.js, setupLogger() to allow module loading when flag is set
lib/internal/bootstrap/realm.js, Module registration
doc/api/cli.md, Flag documentation
doc/api/index.md / doc/node.1, Index updates
test/parallel/test-code-cache.js / test-process-get-builtin.mjs / test-require-resolve.js, Test adjustments for new module

nodejs-github-bot · 2025-10-28T19:10:01Z

Review requested:

@nodejs/performance

lib/logger.js

mertcanaltin · 2025-10-29T19:25:12Z

thats my first performance results:

I think need improvement for child logger area, but ı'm so happy because other results it looks nice.
cc @mcollina @Qard @trentm @jsumners

node:logger vs pino

➜ node git:(mert/create-logger-api/node-core) ✗ ./node benchmark/logger/vs-pino.js n=100000
logger/vs-pino.js scenario="simple" logger="node-logger" n=100000: 5,240,540.823813018
logger/vs-pino.js scenario="child" logger="node-logger" n=100000: 2,635,847.7027229806
logger/vs-pino.js scenario="disabled" logger="node-logger" n=100000: 159,436,487.67795104
logger/vs-pino.js scenario="fields" logger="node-logger" n=100000: 3,619,336.304205216
logger/vs-pino.js scenario="simple" logger="pino" n=100000: 3,398,489.9761368227
logger/vs-pino.js scenario="child" logger="pino" n=100000: 4,489,799.803418606
logger/vs-pino.js scenario="disabled" logger="pino" n=100000: 119,772,384.56038144
logger/vs-pino.js scenario="fields" logger="pino" n=100000: 1,257,930.8609750536

lib/logger.js

benchmark/logger/basic-json.js

benchmark/logger/vs-pino.js

lib/logger.js

mertcanaltin · 2025-10-29T22:14:10Z

I now learn this feat in Pino

pinojs/pino#2281

I will try add in node:logger

lib/logger.js

mcollina · 2025-10-30T08:49:22Z

This will require support for serializers

mertcanaltin · 2025-10-30T10:58:34Z

This will require support for serializers

I wonder, should we name them like Pino does (built-in serializers), or go with something like standardSerializers ?

test/parallel/test-log-basic.js

lib/logger.js

mcollina · 2025-11-08T10:30:09Z

This will require support for serializers

I wonder, should we name them like Pino does (built-in serializers), or go with something like standardSerializers ?

Follow pino and we’ll change it

mertcanaltin · 2025-11-10T13:29:32Z

This will require support for serializers

I wonder, should we name them like Pino does (built-in serializers), or go with something like standardSerializers ?

Follow pino and we’ll change it

I tryed serializer implement for logger, and some bench result repaired

and fields and simple are experiencing a decline; I will try to resolve these

fields: 3.62M → 2.16M (-40%)
simple: 5.24M → 4.87M (-7%)

previously, the results for the child logger were quite slow at around 70%, but the new results have dropped to 18% and have actually improved significantly.

I continue to try new methods.

➜  node git:(mert/create-logger-api/node-core) ✗ ./node benchmark/logger/vs-pino.js n=100000
logger/vs-pino.js scenario="simple" logger="node-logger" n=100000: 4,868,164.032787085
logger/vs-pino.js scenario="child" logger="node-logger" n=100000: 3,894,327.425314102
logger/vs-pino.js scenario="disabled" logger="node-logger" n=100000: 160,503,080.85663706
logger/vs-pino.js scenario="fields" logger="node-logger" n=100000: 2,157,462.3927336666
logger/vs-pino.js scenario="simple" logger="pino" n=100000: 3,424,706.4418693925
logger/vs-pino.js scenario="child" logger="pino" n=100000: 4,753,595.477010947
logger/vs-pino.js scenario="disabled" logger="pino" n=100000: 122,100,122.10012211
logger/vs-pino.js scenario="fields" logger="pino" n=100000: 1,411,215.99189962
➜  node git:(mert/create-logger-api/node-core) ✗

mertcanaltin · 2025-11-10T14:12:02Z

This will require support for serializers

I wonder, should we name them like Pino does (built-in serializers), or go with something like standardSerializers ?

Follow pino and we’ll change it

I tryed serializer implement for logger, and some bench result repaired

and fields and simple are experiencing a decline; I will try to resolve these

fields: 3.62M → 2.16M (-40%) simple: 5.24M → 4.87M (-7%)

previously, the results for the child logger were quite slow at around 70%, but the new results have dropped to 18% and have actually improved significantly.

I continue to try new methods.
➜  node git:(mert/create-logger-api/node-core) ✗ ./node benchmark/logger/vs-pino.js n=100000
logger/vs-pino.js scenario="simple" logger="node-logger" n=100000: 4,868,164.032787085
logger/vs-pino.js scenario="child" logger="node-logger" n=100000: 3,894,327.425314102
logger/vs-pino.js scenario="disabled" logger="node-logger" n=100000: 160,503,080.85663706
logger/vs-pino.js scenario="fields" logger="node-logger" n=100000: 2,157,462.3927336666
logger/vs-pino.js scenario="simple" logger="pino" n=100000: 3,424,706.4418693925
logger/vs-pino.js scenario="child" logger="pino" n=100000: 4,753,595.477010947
logger/vs-pino.js scenario="disabled" logger="pino" n=100000: 122,100,122.10012211
logger/vs-pino.js scenario="fields" logger="pino" n=100000: 1,411,215.99189962
➜  node git:(mert/create-logger-api/node-core) ✗ 

I inspected pino and I learn some patterns, than I applied this commit and new results! 1ededc7

I used this patterns

removed the cost of serializing bindings in each log for the child logger,
skipped unnecessary serializer checks,
used direct string concatenation instead of object merging,
sped up type checking

simple: 6.06M vs 3.48M ops/s (+74% faster)
child: 5.76M vs 4.41M ops/s (+31% faster)
disabled: 174M vs 146M ops/s (+19% faster)
fields: 2.13M vs 1.36M ops/s (+56% faster)

➜  node git:(mert/create-logger-api/node-core) ✗ ./node benchmark/logger/vs-pino.js n=100000
logger/vs-pino.js scenario="simple" logger="node-logger" n=100000: 6,062,182.962986493
logger/vs-pino.js scenario="child" logger="node-logger" n=100000: 5,758,903.394222795
logger/vs-pino.js scenario="disabled" logger="node-logger" n=100000: 174,026,539.04720467
logger/vs-pino.js scenario="fields" logger="node-logger" n=100000: 2,126,059.37552321
logger/vs-pino.js scenario="simple" logger="pino" n=100000: 3,477,918.037575009
logger/vs-pino.js scenario="child" logger="pino" n=100000: 4,407,389.658686015
logger/vs-pino.js scenario="disabled" logger="pino" n=100000: 145,551,509.22359914
logger/vs-pino.js scenario="fields" logger="pino" n=100000: 1,363,125.197883181
➜  node git:(mert/create-logger-api/node-core) ✗

mertcanaltin · 2025-11-20T21:38:11Z

hello @mcollina do you any comments or suggestions for this end commits, I'm curious 🙏 .

codecov · 2025-11-29T16:46:57Z

Codecov Report

❌ Patch coverage is 95.88415% with 27 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.74%. Comparing base (adac077) to head (c05dcfc).
⚠️ Report is 60 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/logger.js	95.80%	22 Missing and 1 partial ⚠️
lib/internal/logger/serializers.js	95.69%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #60468      +/-   ##
==========================================
+ Coverage   89.70%   89.74%   +0.03%     
==========================================
  Files         692      697       +5     
  Lines      214012   215131    +1119     
  Branches    41054    41157     +103     
==========================================
+ Hits       191984   193067    +1083     
- Misses      14091    14127      +36     
  Partials     7937     7937

Files with missing lines	Coverage Δ
lib/internal/bootstrap/realm.js	`96.22% <100.00%> (+0.01%)`	⬆️
lib/internal/process/pre_execution.js	`98.63% <100.00%> (+1.40%)`	⬆️
src/node_options.cc	`76.58% <100.00%> (+0.11%)`	⬆️
src/node_options.h	`98.00% <100.00%> (+0.04%)`	⬆️
lib/internal/logger/serializers.js	`95.69% <95.69%> (ø)`
lib/logger.js	`95.80% <95.80%> (ø)`

... and 72 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.

lib/logger.js

lib/internal/logger/serializers.js

jsumners · 2026-02-27T14:07:13Z

It's missing tests for a significant part of the exposed API. Apart from my comments, why are we copying pino internals instead of vendoring pino (which is more robust and well tested) into core?

I'd love to hear @mcollina and @jsumners thoughts on this PR too.

As Matteo said, Pino has baggage that we can't realistically remove. I have provided a few tips along the way of this PR, but I really don't have the energy to devote to an actual review of it. So I can't speak to the implementation as it is today. The last time I looked at it, it was going in the right direction and I assume that has continued. If we are at the "go or no-go" point, I can attempt to use it and provide feedback on if it works as I would expect or not.

lib/internal/logger/serializers.js

Co-authored-by: Yagiz Nizipli <yagiz@nizipli.com>

anonrig · 2026-02-27T14:20:19Z

@mertcanaltin Can you update the description of this pull-request? Please provide a full description of all the changes you're bringing, the performance characteristics of this new module etc.

lib/logger.js

mertcanaltin · 2026-02-27T14:49:26Z

@mertcanaltin Can you update the description of this pull-request? Please provide a full description of all the changes you're bringing, the performance characteristics of this new module etc.

I Updated PR description

Qard · 2026-02-28T14:33:45Z

If we are at the "go or no-go" point, I can attempt to use it and provide feedback on if it works as I would expect or not.

I don't think there's any need to rush into this must land immediately. We can provide people the time to review it properly if anyone wants to do so. Personally, I think it's in good shape at this point, but it's also a somewhat big and critical system so it makes sense that we might want to wait a bit for deeper review to ensure we're fully confident in the architecture.

jsumners · 2026-02-28T15:08:47Z

If we are at the "go or no-go" point, I can attempt to use it and provide feedback on if it works as I would expect or not.

I don't think there's any need to rush into this must land immediately. We can provide people the time to review it properly if anyone wants to do so. Personally, I think it's in good shape at this point, but it's also a somewhat big and critical system so it makes sense that we might want to wait a bit for deeper review to ensure we're fully confident in the architecture.

I don't understand this reply. I am not trying to rush anything. I am stating that the best I can do for a review is to try out the "done" product and provide feedback at that point. I have no idea if that point has been reached.

atlowChemi · 2026-03-27T07:00:29Z

@Qard as a month has gone by since your last commit, is this still an issue? I think anyone who might have wanted to review this would by now have had the time.
IMHO this is a great starting point, and as it is marked as experimental, we would still be able to make changes if needed.

jasnell · 2026-03-29T17:17:51Z

doc/api/logger.md

+logs independently.
+
+```mjs
+import { Logger, JSONConsumer } from 'node:logger';


I'd actually prefer if this weren't a new top-level module, and don't really think it's needs to be. We can attach this to require('console') or require('util') ... or event require('console/logging')

I think a separate module is better. IMHO it wouldn't make sense to have multiple things related to logger in node:util.

require('console/logging') counts as a separate module. The key thing I'd rather us avoid is Yet Another Top-Level module.

Do you think node:console/logging would work?
This keeps it as a separate module while avoiding the creation of a new top-level namespace, and we already have a precedent for this pattern with node:test/reporters.

that works for me

I don't really like console a the prefix here, because:

This is not a whatwg console

Having console in the name implies it logs to stdout, which is not the point of the new module

That said, I will not block on this, whatever's the chosen name

Agreed with @atlowChemi. Putting this under node:console seems very strange. A logger does not necessarily target a tty, which is what I expect when I read "console". node:logging or node:logger make the most sense to me. What is the problem with a new module name?

... What is the problem with a new module name?

A couple reasons: (1) new top-level modules have historically been required to be semver-major, which means no backporting to lts versions, and this is something I'd like to see backported. (2) There's an old logger module on npm and even though this would be node:logger that still makes things a bit confusing... My general preference is to hang new things off existing modules as the first choice and only falling back to a new top-level module when nothing existing fits. It doesn't need to be console if folks feel strongly about that.

I think that is very backward. Adding a new module should be a minor change. Changing an existing module should be a major change. I can agree that adding a subspaced module off of an existing module can be a minor change change. But I'd be much more easily convinced that it is a major change than I would be that adding a new module altogether is a major change.

Per the collaborator guide:

For pull requests introducing new core modules: * Allow at least one week for review. * Land only after sign-off from at least two TSC voting members. * Land with a [Stability Index][] of Experimental. The module must remain Experimental until a semver-major release.

Experimental stuff is not covered by semver. Graduating an experimental new core module is semver-major, which means while it can land in backports as experimental it can never be considered non-experimental in downlevel releases.

... Adding a new module should be a minor change

We've never treated it as minor. Adding new features to existing modules has always been treated as minor.

doc/api/logger.md

jasnell

I'd prefer require('console/logging') or require('console').Logging rather than a new top-level node:... module.

lib/internal/logger/serializers.js

lib/logger.js

jasnell · 2026-04-01T15:17:24Z

lib/logger.js

+
+    // Add consumer fields
+    const consumerFields = this.#fields;
+    for (const key of ObjectKeys(consumerFields)) {


should we validate that the fields are JSON-stringifiable types on construction to avoid errors during handle call?

I initially added shallow type validation (rejecting bigint/function/symbol) but removed it because it only checks one level deep, { nested: { val: 42n } } would still throw at log time from JSON.stringify. Partial validation felt inconsistent.

I documented the behavior in the "Non-JSON-serializable values" section instead. Happy to add it back if you prefer the early check even if shallow.

lib/logger.js

doc/api/logger.md

mertcanaltin · 2026-04-05T09:51:53Z

@jasnell Thanks for the reviews. I edited and answered your reviews.

nodejs-github-bot added the needs-ci PRs that need a full CI run. label Oct 28, 2025

mertcanaltin mentioned this pull request Oct 28, 2025

Structured log package in node core #49296

Open

mertcanaltin changed the title ~~lib: added logger package in node core~~ lib: added logger api in node core Oct 28, 2025

mertcanaltin changed the title ~~lib: added logger api in node core~~ [WIP] lib: added logger api in node core Oct 28, 2025

Qard reviewed Oct 28, 2025

View reviewed changes

lib/logger.js Outdated Show resolved Hide resolved

mertcanaltin requested a review from Qard October 29, 2025 14:16

AugustinMauroy reviewed Oct 29, 2025

View reviewed changes

lib/logger.js Outdated Show resolved Hide resolved

AugustinMauroy reviewed Oct 29, 2025

View reviewed changes

benchmark/logger/basic-json.js Outdated Show resolved Hide resolved

AugustinMauroy reviewed Oct 29, 2025

View reviewed changes

benchmark/logger/vs-pino.js Outdated Show resolved Hide resolved

AugustinMauroy reviewed Oct 29, 2025

View reviewed changes

lib/logger.js Outdated Show resolved Hide resolved

atlowChemi reviewed Oct 30, 2025

View reviewed changes

TheOneTheOnlyJJ reviewed Oct 30, 2025

View reviewed changes

test/parallel/test-log-basic.js Outdated Show resolved Hide resolved

TheOneTheOnlyJJ reviewed Oct 30, 2025

View reviewed changes

lib/logger.js Outdated Show resolved Hide resolved

anonrig reviewed Oct 31, 2025

View reviewed changes

lib/logger.js Outdated Show resolved Hide resolved

lib/logger.js Outdated Show resolved Hide resolved

lib/logger.js Outdated Show resolved Hide resolved

mertcanaltin marked this pull request as ready for review November 29, 2025 14:16

mertcanaltin requested a review from a team as a code owner November 30, 2025 17:53

mertcanaltin force-pushed the mert/create-logger-api/node-core branch 2 times, most recently from f5b0108 to 429359b Compare November 30, 2025 18:01

yvele reviewed Nov 30, 2025

View reviewed changes

lib/logger.js Outdated Show resolved Hide resolved

marco-ippolito reviewed Dec 3, 2025

View reviewed changes

lib/internal/logger/serializers.js Outdated Show resolved Hide resolved

anonrig reviewed Feb 27, 2026

View reviewed changes

lib/internal/logger/serializers.js Outdated Show resolved Hide resolved

Update lib/internal/logger/serializers.js

2478f38

Co-authored-by: Yagiz Nizipli <yagiz@nizipli.com>

delete pino benchmark

af4a07c

anonrig reviewed Feb 27, 2026

View reviewed changes

lib/logger.js Show resolved Hide resolved

delete exports (LEVELS, channels)

7e478d9

mertcanaltin added 2 commits March 29, 2026 17:46

Merge branch 'main' into mert/create-logger-api/node-core

1b31e8d

fix: conflict

2c2017e

jasnell reviewed Mar 29, 2026

View reviewed changes

doc/api/logger.md Show resolved Hide resolved

jasnell requested changes Mar 29, 2026

View reviewed changes

edited logger api md

5b52f30

anonrig added the tsc-agenda Issues and PRs to discuss during the meetings of the TSC. label Apr 1, 2026