@lakutata/logger 0.0.0-stage → 3.0.0-beta.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2023-present Lakutata
+
+All rights reserved
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# @lakutata/logger
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The logger component of the lakutata framework: it writes the log format of pino (one JSON object per line) or
+readable, colored lines, to stdout or any writable streams, buffered for speed and flushed when the process exits. The
+umbrella package `lakutata` presets it as the `log` component of every application (created first, so the framework
+logs through it too) and re-exports it as `lakutata/com/logger`.
+
+## Installation
+
+```shell
+npm install lakutata
+```
+
+It has no optional dependencies.
+
+## Usage
+
+### Configuring the preset logger
+
+An application of `lakutata` already has its logger, named `log`: configure it through the `log` entry of its
+`components` (no `class` needed), and get it with `@Inject('log')` or `getObject('log')`; it is a singleton.
+
+```typescript
+import {createWriteStream} from 'node:fs'
+import {Application, Component} from 'lakutata'
+import {Inject} from 'lakutata/decorator/di'
+import {Logger} from 'lakutata/com/logger'
+
+class Orders extends Component {
+    @Inject('log')
+    protected readonly log: Logger
+
+    public pay(orderId: number, amount: number): void {
+        this.log.info({orderId: orderId, amount: amount}, 'order %d paid', orderId)
+    }
+}
+
+Application
+    .run(() => ({
+        id: 'shop.app',
+        name: 'Shop',
+        components: {
+            log: {
+                //trace, debug, info, warn, error, fatal or silent
+                level: 'info',
+                //JSON lines for a log collector
+                pretty: false,
+                destinations: [process.stdout, createWriteStream('shop.log', {flags: 'a'})]
+            },
+            orders: {class: Orders}
+        }
+    }))
+    .onLaunched(async (app: Application): Promise<void> => {
+        const orders: Orders = await app.getObject('orders')
+        orders.pay(42, 9.9)
+    })
+```
+
+| Option | Default | What it does |
+|---|---|---|
+| `level` | `'trace'` | The lowest level written: `'trace'` (10), `'debug'` (20), `'info'` (30), `'warn'` (40), `'error'` (50), `'fatal'` (60, only `fatal()`) or `'silent'` (nothing) |
+| `pretty` | `true` | Readable lines when `true`, pino's JSON lines when `false` |
+| `colorize` | `true` | Colors the readable lines written to `process.stdout` (never the other streams, nor the JSON) |
+| `sync` | `false` | Writes each line at once; otherwise the lines are buffered until the next turn of the event loop (or 16 KB) |
+| `destinations` | `[process.stdout]` | The writable streams receiving every line; not closed by the logger |
+| `redactedHeaders` | `['authorization', 'cookie', 'set-cookie', 'proxy-authorization']` | The headers of a logged request or response written as `[Redacted]` (case-insensitive); the list replaces the default one, `[]` redacts none |
+
+### Logging
+
+Each method (`error`, `warn`, `info`, `debug`, `trace`) takes the arguments of pino: an optional object of properties,
+then a message with printf-style placeholders, then their values.
+
+```typescript
+import {Logger} from 'lakutata/com/logger'
+
+declare const log: Logger
+
+//A message, with placeholders: %s string, %d / %f number, %i integer, %o / %O / %j JSON, %% a percent sign
+log.info('user %s signed in from %s', 'alice', '10.0.0.7')
+//Properties added to the line, then the message
+log.warn({orderId: 42, retries: 3}, 'payment retried %d times', 3)
+//An error: written under "err" (type, message, stack, causes, own properties); its message is the default message
+log.error(new Error('connection refused'), 'payment failed')
+log.debug({query: 'SELECT 1', durationMs: 2.4})
+```
+
+The JSON line of the second call:
+
+```text
+{"level":40,"time":1791117611866,"pid":4242,"hostname":"api-1","name":"Shop","orderId":42,"retries":3,"msg":"payment retried 3 times"}
+```
+
+and its readable line:
+
+```text
+[14:20:11.866] WARN (Shop/4242): payment retried 3 times
+    orderId: 42
+    retries: 3
+```
+
+- **Errors**: an `Error` (or an `err` property) is serialized with its type, its message followed by the messages of
+  its causes, its stack followed by its causes' stacks, its aggregated errors and its own enumerable properties.
+- **HTTP**: a request (`IncomingMessage`) is written under `req` (method, URL, query, params, headers, remote address
+  and port), a response under `res` (status code, headers).
+- **Redaction**: the `Authorization`, `Cookie`, `Set-Cookie` and `Proxy-Authorization` headers of a logged request or
+  response are written as `[Redacted]` (the `redactedHeaders` option). Nothing else is redacted: log the fields you
+  need, not tokens, passwords or whole objects holding them.
+- **Fatal errors**: `fatal()` logs at level 60, above `error`, and writes the pending lines at once, before the process
+  exits.
+- **No child loggers**: add the context (a request ID) to the object of each call.
+- **Buffering**: unless `sync` is on, the lines are written at the next turn of the event loop; `flush()` writes them
+  at once, and the logger flushes when the process exits or the component is destroyed. A stream with a file
+  descriptor (stdout, stderr, a file) is written synchronously, so the lines keep their order.
+
+## API
+
+| Export | What it is |
+|---|---|
+| `Logger` | The component: `fatal()`, `error()`, `warn()`, `info()`, `debug()`, `trace()`, `flush()`; the options `level`, `pretty`, `colorize`, `sync`, `destinations`, `redactedHeaders` |
+| `ILogger` | The interface of the application loggers (from `@lakutata/core`): the five log methods `error()` to `trace()` (not `fatal()`, which only `Logger` has) |
+| `ILogMethod` | The signatures of a log method: `(obj, msg?, ...args)` or `(msg, ...args)` |
+
+All are exported by `lakutata/com/logger` and `@lakutata/logger`. The typings document each declaration with examples.
+
+## Errors
+
+| Exception | When |
+|---|---|
+| `InvalidObjectOptionsException` (from `lakutata`) | The application starts with invalid logger options: an unknown `level`, a destination that is not a stream (`InvalidValueException` when the logger is created outside the checked options, as in a bare `Container`) |
+
+A log method never throws for what it logs: the values that cannot be serialized (functions, symbols) are left out,
+and the circular references are replaced.
+
+## See also
+
+- `doc/en/Core.md` of the package `lakutata` (Chinese in `doc/zh`): the components and the application lifecycle.
+- `@lakutata/core` (`lakutata`): `Application`, the components and the console logger of core.
+- `@lakutata/monitor` (`lakutata/com/monitor`): the process monitors, whose statistics the logger can report.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,158 @@
+# Third-party notices
+
+Parts of `@lakutata/logger` are derived from the third-party projects listed below: the log line format, the
+message formatting, the serializers and the pretty format reproduce their behavior (the format of lakutata 2.x).
+They are rewritten in TypeScript and modified; the original copyright notices and license terms are reproduced
+here as required.
+
+## pino 10.1.0
+
+Used in `src/lib/Record.ts` (log lines).
+
+The MIT License (MIT)
+
+Copyright (c) 2016-2025 Matteo Collina, David Mark Clements and the Pino contributors listed at <https://github.com/pinojs/pino#the-team> and in the README file.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## pino-pretty 13.1.2
+
+Used in `src/lib/Pretty.ts` and `src/lib/Colors.ts` (pretty format).
+
+The MIT License (MIT)
+
+Copyright (c) 2019 the Pino team listed at https://github.com/pinojs/pino#the-team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## pino-std-serializers 7.0.0
+
+Used in `src/lib/Serializers.ts`.
+
+Copyright Mateo Collina, David Mark Clements, James Sumners
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## quick-format-unescaped 4.0.4
+
+Used in `src/lib/Format.ts`.
+
+The MIT License (MIT)
+
+Copyright (c) 2016-2019 David Mark Clements
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## safe-stable-stringify 2.5.0
+
+Used in `src/lib/Stringify.ts`.
+
+The MIT License (MIT)
+
+Copyright (c) Ruben Bridgewater
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## colorette 2.0.20
+
+Used in `src/lib/Colors.ts`.
+
+Copyright © Jorge Bucaran <<https://jorgebucaran.com>>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+## secure-json-parse 4.1.0
+
+Used in `src/lib/Pretty.ts` (prototype properties).
+
+Copyright (c) 2019, Sideway Inc, and project contributors
+Copyright (c) 2019-present The Fastify team
+All rights reserved.
+
+The Fastify team members are listed at https://github.com/fastify/fastify#team.
+
+The complete list of contributors can be found at:
+- https://github.com/hapijs/bourne/graphs/contributors
+- https://github.com/fastify/secure-json-parse/graphs/contributors
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/dist/cjs/Logger.d.ts

@@ -0,0 +1,291 @@
+import { Component } from '@lakutata/core';
+import type { ILogger } from '@lakutata/core/com/logger';
+/**
+ * The logger component of the applications built with `lakutata`: the package presets it as the `log` component (and
+ * creates it first), so the framework and the application log through it. It writes the pino log format: one JSON
+ * object per line, with `level` (10 trace, 20 debug, 30 info, 40 warn, 50 error, 60 fatal), `time` (milliseconds since the epoch),
+ * `pid`, `hostname`, `name` (the application's name), the properties of the logged object and `msg`; with `pretty` on
+ * (the default), it writes readable lines instead: `[HH:MM:ss.SSS] LEVEL (name/pid): message`, then one indented line
+ * per property, in the local time zone.
+ *
+ * Configure it through the `log` entry of the application's `components` (no `class` needed:
+ * `log: {level: 'info', pretty: false}`), and get it with `@Inject('log')` or `getObject('log')`; it is a singleton.
+ * The lines are buffered and written at the next turn of the event loop (or once 16 KB are pending), and the pending
+ * lines are written synchronously when the process exits or the component is destroyed; `sync: true` writes each line
+ * at once instead. A stream with a file descriptor (stdout, stderr, an opened file) is written synchronously through
+ * it, so the lines keep their order.
+ *
+ * An HTTP request or response logged as the object of a line is written under `req` or `res` with the values of its
+ * credential headers (`Authorization`, `Cookie`, `Set-Cookie`, `Proxy-Authorization`) replaced by `[Redacted]` (see
+ * the `redactedHeaders` option). Nothing else is redacted and there are no child loggers: the other properties are
+ * written as is, so log the fields you need rather than secrets or whole objects holding them.
+ * @example
+ * ```typescript
+ * import {Application, Component} from 'lakutata'
+ * import {Inject} from 'lakutata/decorator/di'
+ * import {Logger} from 'lakutata/com/logger'
+ *
+ * class Orders extends Component {
+ *     @Inject('log')
+ *     protected readonly log: Logger
+ *
+ *     public pay(orderId: number, amount: number): void {
+ *         //{"level":30,...,"orderId":42,"msg":"order 42 paid: 9.90"}
+ *         this.log.info({orderId: orderId}, 'order %d paid: %s', orderId, amount.toFixed(2))
+ *     }
+ *
+ *     public fail(error: Error): void {
+ *         //The error serialized under "err", its message as the message unless one is given
+ *         this.log.error(error, 'payment failed')
+ *     }
+ * }
+ *
+ * Application.run(() => ({
+ *     id: 'shop.app',
+ *     name: 'Shop',
+ *     components: {
+ *         //The preset logger: JSON lines from the info level in production
+ *         log: {level: 'info', pretty: process.env.NODE_ENV !== 'production'},
+ *         orders: {class: Orders}
+ *     }
+ * }))
+ * ```
+ */
+export declare class Logger extends Component implements ILogger {
+    #private;
+    /**
+     * Write readable lines (`[HH:MM:ss.SSS] LEVEL (name/pid): message`, then the properties) when `true`, the JSON lines
+     * of pino when `false` (for a log collector).
+     * @default true
+     * @protected
+     */
+    protected readonly pretty: boolean;
+    /**
+     * The lowest level written: `'trace'`, `'debug'`, `'info'`, `'warn'`, `'error'`, `'fatal'` (only the lines of
+     * {@link Logger.fatal}) or `'silent'` (nothing); the lines of lower levels are dropped.
+     * @default 'trace'
+     * @protected
+     */
+    protected readonly level: string;
+    /**
+     * Color the readable lines written to `process.stdout` (the level, the message, the properties); the other
+     * destinations and the JSON lines are never colored.
+     * @default true
+     * @protected
+     */
+    protected readonly colorize: boolean;
+    /**
+     * Write each line at once when `true`; when `false`, the lines are buffered and written at the next turn of the
+     * event loop (or once 16 KB are pending), which costs less per line. The pending lines are written synchronously when
+     * the process exits either way.
+     * @default false
+     * @protected
+     */
+    protected readonly sync: boolean;
+    /**
+     * The streams the lines are written to, each receiving every line: `process.stdout`, `process.stderr`, a file
+     * (`fs.createWriteStream(path, {flags: 'a'})`) or any writable stream. The streams are not closed by the logger.
+     * @default [process.stdout]
+     * @protected
+     */
+    protected readonly destinations: NodeJS.WritableStream[];
+    /**
+     * The headers whose values are written as `[Redacted]` when an HTTP request or response (of `node:http`, Express,
+     * Fastify) is logged as the object of a line, by name (case-insensitive). The list replaces the default one: to
+     * redact another header, list the default ones with it; `[]` writes every header as is. The headers of the request
+     * or response are not changed.
+     * @default ['authorization', 'cookie', 'set-cookie', 'proxy-authorization']
+     * @protected
+     */
+    protected readonly redactedHeaders: string[];
+    /**
+     * Set up the destinations and the level, and register the logger to flush its pending lines when the process exits.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Write the pending lines and stop flushing at the process exit.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Build a log line and write it to every destination, unless its level is below the configured `level`.
+     * @param level The numeric level of the line: 10 trace, 20 debug, 30 info, 40 warn, 50 error, 60 fatal.
+     * @param args The arguments of the log method: `[obj, msg, ...args]` or `[msg, ...args]`.
+     * @protected
+     */
+    protected write(level: number, args: unknown[]): void;
+    /**
+     * Write the buffered lines now, synchronously for the streams with a file descriptor (before a `process.exit()`
+     * in a signal handler, for instance). Does nothing with `sync: true`.
+     */
+    flush(): void;
+    /**
+     * Log a fatal error (a failure the application cannot continue after, logged before it exits) at the `fatal`
+     * level (60), unless the configured `level` is `'silent'`. The line and the pending ones are written at once, as
+     * by {@link Logger.flush}.
+     * @param obj The properties added to the line (`{orderId: 42}`). An `Error` is written under `err` (its type,
+     * message, stack, causes and own properties), its message becoming the message when `msg` is omitted; an HTTP
+     * request or response of `node:http` is written under `req` or `res`, its credential headers redacted.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    fatal<T extends object>(obj: T, msg?: string, ...args: any[]): void;
+    /**
+     * Log a fatal error (a failure the application cannot continue after, logged before it exits) at the `fatal`
+     * level (60), unless the configured `level` is `'silent'`. The line and the pending ones are written at once, as
+     * by {@link Logger.flush}.
+     * @param obj The properties added to the line (`{orderId: 42}`). An `Error` is written under `err` (its type,
+     * message, stack, causes and own properties), its message becoming the message when `msg` is omitted; an HTTP
+     * request or response of `node:http` is written under `req` or `res`, its credential headers redacted.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    fatal(obj: unknown, msg?: string, ...args: any[]): void;
+    /**
+     * Log a fatal error (a failure the application cannot continue after, logged before it exits) at the `fatal`
+     * level (60), unless the configured `level` is `'silent'`. The line and the pending ones are written at once, as
+     * by {@link Logger.flush}.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    fatal(msg: string, ...args: any[]): void;
+    /**
+     * Log an error (a failure the application needs to act on) at the `error` level (50), unless the configured `level` is higher.
+     * @param obj The properties added to the line (`{orderId: 42}`). An `Error` is written under `err` (its type,
+     * message, stack, causes and own properties), its message becoming the message when `msg` is omitted; an HTTP
+     * request or response of `node:http` is written under `req` or `res`, its credential headers redacted.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    error<T extends object>(obj: T, msg?: string, ...args: any[]): void;
+    /**
+     * Log an error (a failure the application needs to act on) at the `error` level (50), unless the configured `level` is higher.
+     * @param obj The properties added to the line (`{orderId: 42}`). An `Error` is written under `err` (its type,
+     * message, stack, causes and own properties), its message becoming the message when `msg` is omitted; an HTTP
+     * request or response of `node:http` is written under `req` or `res`, its credential headers redacted.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    error(obj: unknown, msg?: string, ...args: any[]): void;
+    /**
+     * Log an error (a failure the application needs to act on) at the `error` level (50), unless the configured `level` is higher.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    error(msg: string, ...args: any[]): void;
+    /**
+     * Log a warning (an unexpected event the application recovers from) at the `warn` level (40), unless the configured `level` is higher.
+     * @param obj The properties added to the line (`{orderId: 42}`). An `Error` is written under `err` (its type,
+     * message, stack, causes and own properties), its message becoming the message when `msg` is omitted; an HTTP
+     * request or response of `node:http` is written under `req` or `res`, its credential headers redacted.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    warn<T extends object>(obj: T, msg?: string, ...args: any[]): void;
+    /**
+     * Log a warning (an unexpected event the application recovers from) at the `warn` level (40), unless the configured `level` is higher.
+     * @param obj The properties added to the line (`{orderId: 42}`). An `Error` is written under `err` (its type,
+     * message, stack, causes and own properties), its message becoming the message when `msg` is omitted; an HTTP
+     * request or response of `node:http` is written under `req` or `res`, its credential headers redacted.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    warn(obj: unknown, msg?: string, ...args: any[]): void;
+    /**
+     * Log a warning (an unexpected event the application recovers from) at the `warn` level (40), unless the configured `level` is higher.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    warn(msg: string, ...args: any[]): void;
+    /**
+     * Log an information (the normal course of the application) at the `info` level (30), unless the configured `level` is higher.
+     * @param obj The properties added to the line (`{orderId: 42}`). An `Error` is written under `err` (its type,
+     * message, stack, causes and own properties), its message becoming the message when `msg` is omitted; an HTTP
+     * request or response of `node:http` is written under `req` or `res`, its credential headers redacted.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    info<T extends object>(obj: T, msg?: string, ...args: any[]): void;
+    /**
+     * Log an information (the normal course of the application) at the `info` level (30), unless the configured `level` is higher.
+     * @param obj The properties added to the line (`{orderId: 42}`). An `Error` is written under `err` (its type,
+     * message, stack, causes and own properties), its message becoming the message when `msg` is omitted; an HTTP
+     * request or response of `node:http` is written under `req` or `res`, its credential headers redacted.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    info(obj: unknown, msg?: string, ...args: any[]): void;
+    /**
+     * Log an information (the normal course of the application) at the `info` level (30), unless the configured `level` is higher.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    info(msg: string, ...args: any[]): void;
+    /**
+     * Log a debugging detail at the `debug` level (20), unless the configured `level` is higher.
+     * @param obj The properties added to the line (`{orderId: 42}`). An `Error` is written under `err` (its type,
+     * message, stack, causes and own properties), its message becoming the message when `msg` is omitted; an HTTP
+     * request or response of `node:http` is written under `req` or `res`, its credential headers redacted.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    debug<T extends object>(obj: T, msg?: string, ...args: any[]): void;
+    /**
+     * Log a debugging detail at the `debug` level (20), unless the configured `level` is higher.
+     * @param obj The properties added to the line (`{orderId: 42}`). An `Error` is written under `err` (its type,
+     * message, stack, causes and own properties), its message becoming the message when `msg` is omitted; an HTTP
+     * request or response of `node:http` is written under `req` or `res`, its credential headers redacted.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    debug(obj: unknown, msg?: string, ...args: any[]): void;
+    /**
+     * Log a debugging detail at the `debug` level (20), unless the configured `level` is higher.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    debug(msg: string, ...args: any[]): void;
+    /**
+     * Log a tracing detail, finer than debug at the `trace` level (10), unless the configured `level` is higher.
+     * @param obj The properties added to the line (`{orderId: 42}`). An `Error` is written under `err` (its type,
+     * message, stack, causes and own properties), its message becoming the message when `msg` is omitted; an HTTP
+     * request or response of `node:http` is written under `req` or `res`, its credential headers redacted.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    trace<T extends object>(obj: T, msg?: string, ...args: any[]): void;
+    /**
+     * Log a tracing detail, finer than debug at the `trace` level (10), unless the configured `level` is higher.
+     * @param obj The properties added to the line (`{orderId: 42}`). An `Error` is written under `err` (its type,
+     * message, stack, causes and own properties), its message becoming the message when `msg` is omitted; an HTTP
+     * request or response of `node:http` is written under `req` or `res`, its credential headers redacted.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    trace(obj: unknown, msg?: string, ...args: any[]): void;
+    /**
+     * Log a tracing detail, finer than debug at the `trace` level (10), unless the configured `level` is higher.
+     * @param msg The message, with printf-style placeholders replaced by `args`: `%s` (string), `%d` and `%f` (number),
+     * `%i` (integer), `%o`, `%O` and `%j` (JSON), `%%` (a percent sign).
+     * @param args The values of the placeholders of `msg`, in order; the values without a placeholder are dropped.
+     */
+    trace(msg: string, ...args: any[]): void;
+}