lib: added logger api to 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

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

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

I now learn this feat in Pino

pinojs/pino#2281

I will try add in node:logger

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 ?

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.93023% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.33%. Comparing base (75c1982) to head (d4f75da).
⚠️ Report is 174 commits behind head on main.

Files with missing lines	Patch %	Lines
lib/logger.js	95.84%	23 Missing and 1 partial ⚠️
lib/internal/logger/serializers.js	95.83%	4 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #60468      +/-   ##
==========================================
+ Coverage   90.32%   90.33%   +0.01%     
==========================================
  Files         730      732       +2     
  Lines      234653   235341     +688     
  Branches    43933    44051     +118     
==========================================
+ Hits       211949   212607     +658     
- Misses      14416    14450      +34     
+ Partials     8288     8284       -4

Files with missing lines	Coverage Δ
lib/internal/bootstrap/realm.js	`96.31% <100.00%> (+0.01%)`	⬆️
lib/internal/process/pre_execution.js	`97.36% <100.00%> (-0.58%)`	⬇️
src/node_options.cc	`76.70% <100.00%> (+0.02%)`	⬆️
src/node_options.h	`98.01% <100.00%> (+<0.01%)`	⬆️
lib/internal/logger/serializers.js	`95.83% <95.83%> (ø)`
lib/logger.js	`95.84% <95.84%> (ø)`

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

Signed-off-by: Mert Can Altin <mertgold60@gmail.com>

mcollina · 2026-04-22T15:26:31Z

@anonrig what is the question for the TSC?

mcollina · 2026-05-06T13:29:48Z

No question for the TSC, removing.

H4ad · 2026-05-06T13:38:34Z

@mcollina the question was not related to the module this logger API would be released?

I didn't see the other comment, sorry for not sending this earlier.

mcollina · 2026-05-06T22:53:06Z

@H4ad I don't understand.

H4ad · 2026-05-07T00:35:03Z

@mcollina If the new logger will be released as node:logger or node:console/logging

Ref:

Signed-off-by: Mert Can Altin <mertgold60@gmail.com>

mcollina

I have a few issues with this implementation, which probably would need a bit more design and community discussion before landing.

the diagnostics channels are global

The main problem with this is that the diagnostic channels are global. This match reality for most applications I've seen where logging is a "global" concern, however it makes it harder for testing. We create a logger with new, which implies a local scope, even though the logs go to a global stream.

Let's say that I what to create two or more instances of the logger with two different transports, how can I achieve that?

(I still think that diagnostics_channel are the best primitive here, but we need to have answers to these questions?

levels are strings, not numbers, in the diagnostics channels.

In most implementations, log levels are actually mapped to integers. This has an advantage when further processing them down. We can see this in action with the n number of diagnostic channel listeners. This is present here, but not moved down the diagnostics channels. Why do we have one channel per level instead of just a single channel with integer values?

The concept of "ERROR is more important than INFO" is pushed down to consumers, and not built into the lib.

As an additional question: many companies want to create their own custom levels (unfortunately), how can this be implemented here?

Note this is about tradeoffs.

the basic logger has a pre-serialized binding string

Part of the goal of this library is to be protocol agnostic, however there is a #bindingStr, which is some inheritance from Pino. I don't think we can afford to do this here in a generic way.
Child logger properties should be LRUd/cached down in the consumer.

mcollina · 2025-12-17T07:58:23Z

+   * @returns {object} Serialized error object
+   * @private
+   */
+  #serializeError(err, seen = new SafeSet()) {


I think this should be in a serializer

Yes, I was added in a serialize, https://github.com/nodejs/node/pull/60468/changes#diff-2d1249526faad148f37dc1ea3bfd8d56b77ceb4bf1e27299de1ed8e1d6ffc12cR9

mcollina · 2026-06-16T07:28:56Z

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


Adding a new module should be a minor change

IMHO this was due to the "shadowing" of the ecosystem. I think this is relaxable/not needed for node: prefixed modules.

mcollina · 2026-06-17T13:48:19Z

@mcollina If the new logger will be released as node:logger or node:console/logging

My understanding is there are quite a few plus in doing node:logger vs node:console/logging.

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

Comment thread lib/logger.js Outdated

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

AugustinMauroy reviewed Oct 29, 2025

View reviewed changes

Comment thread lib/logger.js Outdated

AugustinMauroy reviewed Oct 29, 2025

View reviewed changes

Comment thread benchmark/logger/basic-json.js Outdated

AugustinMauroy reviewed Oct 29, 2025

View reviewed changes

Comment thread benchmark/logger/vs-pino.js Outdated

AugustinMauroy reviewed Oct 29, 2025

View reviewed changes

Comment thread lib/logger.js Outdated

atlowChemi reviewed Oct 30, 2025

View reviewed changes

TheOneTheOnlyJJ reviewed Oct 30, 2025

View reviewed changes

Comment thread test/parallel/test-log-basic.js Outdated

TheOneTheOnlyJJ reviewed Oct 30, 2025

View reviewed changes

Comment thread lib/logger.js Outdated

anonrig reviewed Oct 31, 2025

View reviewed changes

Comment thread lib/logger.js Outdated

Comment thread lib/logger.js Outdated

Comment thread lib/logger.js Outdated

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

Comment thread lib/logger.js Outdated

marco-ippolito reviewed Dec 3, 2025

View reviewed changes

Comment thread lib/internal/logger/serializers.js Outdated

mertcanaltin added 2 commits April 20, 2026 22:40

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

42ae3a8

Signed-off-by: Mert Can Altin <mertgold60@gmail.com>

src: remove duplicate experimental_stream_iter

b686bee

Signed-off-by: Mert Can Altin <mertgold60@gmail.com>

openjs-meetings-bot Bot mentioned this pull request Apr 23, 2026

Node.js Technical Steering Committee (TSC) Meeting 2026-04-29 nodejs/TSC#1851

Open

openjs-meetings-bot Bot mentioned this pull request Apr 30, 2026

Node.js Technical Steering Committee (TSC) Meeting 2026-05-06 nodejs/TSC#1854

Closed

mcollina removed the tsc-agenda Issues and PRs to discuss during the meetings of the TSC. label May 6, 2026

mcollina added the tsc-agenda Issues and PRs to discuss during the meetings of the TSC. label May 8, 2026

This was referenced May 9, 2026

Node.js Technical Steering Committee (TSC) Meeting 2026-05-13 nodejs/TSC#1857

Open

Node.js Technical Steering Committee (TSC) Meeting 2026-05-20 nodejs/TSC#1860

Open

openjs-meetings-bot Bot mentioned this pull request May 21, 2026

Node.js Technical Steering Committee (TSC) Meeting 2026-05-27 nodejs/TSC#1862

Open

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

d4f75da

Signed-off-by: Mert Can Altin <mertgold60@gmail.com>

mertcanaltin force-pushed the mert/create-logger-api/node-core branch 2 times, most recently from f2faa6d to d4f75da Compare May 26, 2026 22:00

anonrig approved these changes May 27, 2026

View reviewed changes

anonrig changed the title ~~lib: added logger api in node core~~ lib: added logger api to node core May 27, 2026

openjs-meetings-bot Bot mentioned this pull request May 28, 2026

Node.js Technical Steering Committee (TSC) Meeting 2026-06-03 nodejs/TSC#1865

Open

This was referenced Jun 4, 2026

Node.js Technical Steering Committee (TSC) Meeting 2026-06-10 nodejs/TSC#1866

Open

Node.js Technical Steering Committee (TSC) Meeting 2026-06-17 nodejs/TSC#1868

Open

targos removed request for TheOneTheOnlyJJ, jsumners, targos and yvele June 11, 2026 09:30

mcollina added the request-ci Add this label to start a Jenkins CI on a PR. label Jun 16, 2026

mcollina requested changes Jun 16, 2026

View reviewed changes

mcollina removed the tsc-agenda Issues and PRs to discuss during the meetings of the TSC. label Jun 17, 2026

Uh oh!

Conversation

mertcanaltin commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Architecture

API Surface

Performance

New files

Modified files

Uh oh!

nodejs-github-bot commented Oct 28, 2025

Uh oh!

Uh oh!

mertcanaltin commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mertcanaltin commented Oct 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mcollina commented Oct 30, 2025

Uh oh!

mertcanaltin commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mcollina commented Nov 8, 2025

Uh oh!

mertcanaltin commented Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mertcanaltin commented Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mertcanaltin commented Nov 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

codecov Bot commented Nov 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

mcollina commented Apr 22, 2026

Uh oh!

mcollina commented May 6, 2026

Uh oh!

H4ad commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mcollina commented May 6, 2026

Uh oh!

H4ad commented May 7, 2026

Uh oh!

mcollina left a comment

Choose a reason for hiding this comment

the diagnostics channels are global

levels are strings, not numbers, in the diagnostics channels.

the basic logger has a pre-serialized binding string

Uh oh!

mcollina Dec 17, 2025

Choose a reason for hiding this comment

mertcanaltin commented Oct 28, 2025 •

edited

Loading

mertcanaltin commented Oct 29, 2025 •

edited

Loading

mertcanaltin commented Oct 29, 2025 •

edited

Loading

mertcanaltin commented Oct 30, 2025 •

edited

Loading

mertcanaltin commented Nov 10, 2025 •

edited

Loading

mertcanaltin commented Nov 10, 2025 •

edited

Loading

mertcanaltin commented Nov 20, 2025 •

edited

Loading

codecov Bot commented Nov 29, 2025 •

edited

Loading

H4ad commented May 6, 2026 •

edited

Loading