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

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

Review requested:

@nodejs/performance

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

I now learn this feat in Pino

pinojs/pino#2281

I will try add in node:logger

This will require support for serializers

This will require support for serializers

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

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

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) ✗

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) ✗

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

Codecov Report

❌ Patch coverage is 95.90044% with 28 lines in your changes missing coverage. Please review.
✅ Project coverage is 90.33%. Comparing base (f914e45) to head (1a1c110).
⚠️ Report is 2 commits behind head on main.

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

Additional details and impacted files

@@            Coverage Diff             @@
##             main   #60468      +/-   ##
==========================================
- Coverage   92.07%   90.33%   -1.74%     
==========================================
  Files         399      753     +354     
  Lines      177007   250459   +73452     
  Branches    27381    47293   +19912     
==========================================
+ Hits       162978   226255   +63277     
- Misses      13716    15567    +1851     
- Partials      313     8637    +8324

Files with missing lines	Coverage Δ
lib/internal/bootstrap/realm.js	96.31% <100.00%> (+0.83%)	⬆️
lib/internal/process/pre_execution.js	97.27% <100.00%> (+15.62%)	⬆️
src/node_options.cc	79.45% <100.00%> (ø)
src/node_options.h	95.34% <100.00%> (ø)
lib/internal/logger/serializers.js	95.83% <95.83%> (ø)
lib/logger.js	95.80% <95.80%> (ø)

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

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.

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

how can I achieve that?

right, unfortunately current desing is acting wrongly, I tried create new consumer but hit the some global key "log:info"
I think the fix is fewer channels, not more, a single channel with a namespace per logger.

the basic logger has a pre-serialized binding string
Child logger properties should be LRUd/cached down in the consumer.

yes not protocol agnostic current code, if as you said this different consumer, example msgpack or send to opentelemetry the current record only carries a JSON string, so a non-JSON consumer can't use it

but if I use protocol-agnostic, it work for all consumer, but without cache it serialize every log, so million times

I think good weakMap for this problem, fast and protocol agnostic

levels are strings, not numbers

sgtm, as you said, the level is already in the record, so we can use a single channel and send the integer level in the payload, since the level is just a number, custom levels become easy, without the lib knowing it in advence

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

Hello @mcollina, I sent a repair commit for your comments, now we use a single diagnostics channel, bindings cache as you said moved to consumer, removed before serialized bindingsStr , now has a numeric level for all record

I want to get your comments on custom levels each record already has levelValue, so no core changes needed to add them later

Hi @mcollina, I've addressed your review comments in 2e64414. The logger now publishes to a single log channel, and consumers filter by level on their side.

I solved the conflict.

To avoid taking up any more of the reviewers time, I'm closing this PR. Thanks a lot, everyone. If anyone wants to pick this up and needs help, I'd be happy to assist them.

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 force-pushed the mert/create-logger-api/node-core branch 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

Closed

This was referenced Jun 4, 2026

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

Closed

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

Closed

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

use single diagnostics channel with consumer-side filtering

2e64414

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

updated doc

98f3e5a

mertcanaltin added 4 commits June 27, 2026 21:35

apply serializers to bindings in Logger constructor

8ddfad1

remove double serialize

dfe69ff

simplify bindings handling in child logger creation

1108c7e

add default error serializers to logger class

f38c709

mertcanaltin requested a review from mcollina July 2, 2026 17:41

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

9641dc6

doc: regenerate node.1

1a1c110

mertcanaltin closed this Aug 13, 2026

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

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

Uh oh!

Uh oh!

lib: added logger api to node core - #60468

lib: added logger api to node core#60468mertcanaltin wants to merge 31 commits intonodejs:mainnodejs/node:mainfrom mertcanaltin:mert/create-logger-api/node-coremertcanaltin/node:mert/create-logger-api/node-coreCopy head branch name to clipboard

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 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!

Uh oh!

mcollina Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

mcollina commented Jun 17, 2026

Uh oh!

mertcanaltin commented Jun 19, 2026

Uh oh!

mertcanaltin commented Jun 27, 2026

lib: added logger api to node core#60468
mertcanaltin wants to merge 31 commits into
nodejs:mainfrom
mertcanaltin:mert/create-logger-api/node-core

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