@n8io/baseline-logger 3.1.0 → 3.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +24 -9
- package/dist/index.d.ts +21 -6
- package/dist/index.js +24 -2
- package/dist/logger-err-serialize.d.ts +8 -0
- package/dist/logger-err-serialize.js +4 -0
- package/package.json +12 -11
package/README.md
CHANGED
|
@@ -1,17 +1,21 @@
|
|
|
1
1
|
# @n8io/baseline-logger
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**One logger that keeps credentials and error messages out**: JSON to stdout, credentials redacted, and an error logged only as its class, code and stack frames, never its message.
|
|
4
4
|
|
|
5
5
|
```sh
|
|
6
6
|
pnpm add @n8io/baseline-logger
|
|
7
7
|
```
|
|
8
8
|
|
|
9
|
-
##
|
|
9
|
+
## Guarantees
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
11
|
+
| You get | How |
|
|
12
|
+
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
13
|
+
| **One logger everywhere** | Every Project and Package imports the same `logger`, typed as this Package's own `Logger`, so the library behind it can change without touching a caller. |
|
|
14
|
+
| **Credentials never logged** | Fields named like credentials (`authorization`, `cookie`, `password`, `token` and others) log as `[Redacted]`, also one level down and in headers. |
|
|
15
|
+
| **No message text** | An error leaves only as its class name, `code`, `constraint` and stack frames, down the `cause` chain. With no message given, `msg` is the class name. |
|
|
16
|
+
| **Errors reach error tracking** | `loggerErrorListen` hears each error logged at error or fatal, inside the log call, so it sees the caller's trace. |
|
|
17
|
+
| **A listener cannot break logging** | A listener that throws is skipped and the line still goes out; an error a listener logs is not heard again. |
|
|
18
|
+
| **Logs join the trace** | With `@n8io/baseline-telemetry` preloaded, each record also goes out as an OTLP log with the active trace id, and the stdout line gains `trace_id` and `span_id`. |
|
|
15
19
|
|
|
16
20
|
## Example
|
|
17
21
|
|
|
@@ -24,7 +28,18 @@ logger.error({ err: error }, "Postgres idle client error");
|
|
|
24
28
|
logger.error({ err: error });
|
|
25
29
|
```
|
|
26
30
|
|
|
27
|
-
|
|
31
|
+
Nothing to configure in tests. Assert on what the code returns, not on log lines; a test that must read a line captures stdout for its run and restores it in `onTestFinished`, as the Template's `src/error-tracking-open.test.ts` does.
|
|
28
32
|
|
|
29
|
-
|
|
30
|
-
|
|
33
|
+
## Reference
|
|
34
|
+
|
|
35
|
+
<details><summary><b>Exports</b></summary>
|
|
36
|
+
|
|
37
|
+
| Export | Does |
|
|
38
|
+
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
39
|
+
| `logger` | The one logger: `fatal`, `error`, `warn`, `info`, `debug`, `trace` and `level`. Credential fields are redacted as above. |
|
|
40
|
+
| `Logger`, `LoggerMethod` | The types of `logger` and of one level's call, `(fields, message?)` or `(message)`. There is no `child`, no printf-style arguments and no way to set `level`; the level comes from `LOG_LEVEL`. |
|
|
41
|
+
| `loggerErrorListen(listener)`, `LoggerErrorListener` | Calls `listener` with each error logged at error or fatal (an `err` field, or an Error passed first), inside the log call, so it sees the caller's active trace; returns a function that stops it. A listener that throws is skipped and the log line still goes out, and an error a listener logs is not heard again. Listeners live on `globalThis`, so two copies of this Package share them. A level that `LOG_LEVEL` turns off reaches no listener, nor does an `err` logged beside a `msg` field. `@n8io/baseline-error-tracking` reports errors this way. |
|
|
42
|
+
| `loggerErrSerialize(value)`, `LoggerErr` (`/err-serialize`) | The safe shape. An error leaves the process only as its class name, `code`, `constraint` and stack, down the `cause` chain (10 deep at most); never its message, which can hold input text. `logger` uses it for every `err`, and telemetry and error tracking build on it. |
|
|
43
|
+
</details>
|
|
44
|
+
|
|
45
|
+
**Needs** `LOG_LEVEL` (`fatal`, `error`, `warn`, `info`, `debug`, `trace` or `silent`; default `info`). Runs on [pino](https://getpino.io); nothing in the API names it.
|
package/dist/index.d.ts
CHANGED
|
@@ -1,11 +1,16 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
1
|
+
/**
|
|
2
|
+
* One level's call: fields then a message, a caught value alone, or a message alone. An `err`
|
|
3
|
+
* field, or an Error passed first, is logged in the safe shape of loggerErrSerialize.
|
|
4
|
+
*/
|
|
5
|
+
type LoggerMethod = {
|
|
5
6
|
(fields: unknown, message?: string): void;
|
|
6
7
|
(message: string): void;
|
|
7
8
|
};
|
|
8
|
-
|
|
9
|
+
/**
|
|
10
|
+
* What every Project and Package may call. The library behind it can change without touching a
|
|
11
|
+
* caller.
|
|
12
|
+
*/
|
|
13
|
+
type Logger = {
|
|
9
14
|
readonly level: string;
|
|
10
15
|
fatal: LoggerMethod;
|
|
11
16
|
error: LoggerMethod;
|
|
@@ -14,5 +19,15 @@ export type Logger = {
|
|
|
14
19
|
debug: LoggerMethod;
|
|
15
20
|
trace: LoggerMethod;
|
|
16
21
|
};
|
|
22
|
+
/** The one logger: JSON to stdout, level from `LOG_LEVEL` (default `info`). A
|
|
23
|
+
* `LOG_LEVEL` that is not a level throws a `TypeError` on import. */
|
|
17
24
|
export declare const logger: Logger;
|
|
18
|
-
|
|
25
|
+
/**
|
|
26
|
+
* Who hears each error the logger logs at error or fatal: error tracking, without its callers
|
|
27
|
+
* changing. A listener runs inside the log call, so it sees the caller's active trace, and must
|
|
28
|
+
* return at once and never throw; one that throws is skipped.
|
|
29
|
+
*/
|
|
30
|
+
type LoggerErrorListener = (error: unknown) => void;
|
|
31
|
+
/** Calls `listener` with every error logged at error or fatal; the returned function stops it. */
|
|
32
|
+
export declare const loggerErrorListen: (listener: LoggerErrorListener) => (() => void);
|
|
33
|
+
export type { Logger, LoggerErrorListener, LoggerMethod };
|
package/dist/index.js
CHANGED
|
@@ -1,5 +1,23 @@
|
|
|
1
1
|
import { loggerErrSerialize } from "./logger-err-serialize.js";
|
|
2
2
|
import { pino } from "pino";
|
|
3
|
+
// src/logger-level-assert.ts
|
|
4
|
+
const loggerLevels = [
|
|
5
|
+
"fatal",
|
|
6
|
+
"error",
|
|
7
|
+
"warn",
|
|
8
|
+
"info",
|
|
9
|
+
"debug",
|
|
10
|
+
"trace",
|
|
11
|
+
"silent"
|
|
12
|
+
];
|
|
13
|
+
/**
|
|
14
|
+
* Returns `level` when it is one the logger knows, so a typo in `LOG_LEVEL` fails at import with
|
|
15
|
+
* this Package's message, not the vendor's. Throws a `TypeError` otherwise.
|
|
16
|
+
*/
|
|
17
|
+
const loggerLevelAssert = (level) => {
|
|
18
|
+
if (!loggerLevels.includes(level)) throw new TypeError(`LOG_LEVEL must be one of ${loggerLevels.join(", ")}, not "${level}"`);
|
|
19
|
+
return level;
|
|
20
|
+
};
|
|
3
21
|
// src/logger-error-listen.ts
|
|
4
22
|
const listenersKey = Symbol.for("@n8io/baseline-logger.errorListeners");
|
|
5
23
|
const registry = globalThis;
|
|
@@ -13,6 +31,7 @@ const loggerErrorListen = (listener) => {
|
|
|
13
31
|
listeners.delete(listener);
|
|
14
32
|
};
|
|
15
33
|
};
|
|
34
|
+
/** Hands `error` to every listener; the logger calls it, nothing else does. */
|
|
16
35
|
const loggerErrorEmit = (error) => {
|
|
17
36
|
if (emitting) return;
|
|
18
37
|
emitting = true;
|
|
@@ -51,6 +70,7 @@ const errFind = (first) => {
|
|
|
51
70
|
if (typeof first === "object" && first !== null && "err" in first && !("msg" in first)) return first.err;
|
|
52
71
|
};
|
|
53
72
|
const levelError = 50;
|
|
73
|
+
/** pino's options for the one logger: redaction, the safe `err` shape and the error listeners. */
|
|
54
74
|
const loggerOptionsCreate = (level) => ({
|
|
55
75
|
hooks: { logMethod(args, method, level) {
|
|
56
76
|
const [first, second] = args;
|
|
@@ -69,6 +89,8 @@ const loggerOptionsCreate = (level) => ({
|
|
|
69
89
|
},
|
|
70
90
|
serializers: { err: loggerErrSerialize }
|
|
71
91
|
});
|
|
72
|
-
// src/
|
|
73
|
-
|
|
92
|
+
// src/logger.ts
|
|
93
|
+
/** The one logger: JSON to stdout, level from `LOG_LEVEL` (default `info`). A
|
|
94
|
+
* `LOG_LEVEL` that is not a level throws a `TypeError` on import. */
|
|
95
|
+
const logger = pino(loggerOptionsCreate(loggerLevelAssert(process.env.LOG_LEVEL || "info")));
|
|
74
96
|
export { logger, loggerErrorListen };
|
|
@@ -1,3 +1,7 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The only error shape that leaves the process: class name, code, constraint and stack frames,
|
|
3
|
+
* down the cause chain. Never message or detail, because both can hold input text.
|
|
4
|
+
*/
|
|
1
5
|
export type LoggerErr = {
|
|
2
6
|
cause?: LoggerErr;
|
|
3
7
|
code?: number | string;
|
|
@@ -5,4 +9,8 @@ export type LoggerErr = {
|
|
|
5
9
|
stack?: string;
|
|
6
10
|
type: string;
|
|
7
11
|
};
|
|
12
|
+
/**
|
|
13
|
+
* Turns any caught value into the safe shape: an Error's class name, `code`, `constraint` and
|
|
14
|
+
* stack frames, down the `cause` chain (10 deep at most); anything else as its type.
|
|
15
|
+
*/
|
|
8
16
|
export declare const loggerErrSerialize: (value: unknown) => LoggerErr;
|
|
@@ -22,5 +22,9 @@ const errSerialize = (value, depth) => {
|
|
|
22
22
|
if (value.cause !== void 0 && depth < causeDepthMax) shape.cause = errSerialize(value.cause, depth + 1);
|
|
23
23
|
return shape;
|
|
24
24
|
};
|
|
25
|
+
/**
|
|
26
|
+
* Turns any caught value into the safe shape: an Error's class name, `code`, `constraint` and
|
|
27
|
+
* stack frames, down the `cause` chain (10 deep at most); anything else as its type.
|
|
28
|
+
*/
|
|
25
29
|
const loggerErrSerialize = (value) => errSerialize(value, 0);
|
|
26
30
|
export { loggerErrSerialize };
|
package/package.json
CHANGED
|
@@ -1,21 +1,17 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@n8io/baseline-logger",
|
|
3
|
-
"version": "3.1.
|
|
4
|
-
"description": "
|
|
5
|
-
"type": "module",
|
|
3
|
+
"version": "3.1.2",
|
|
4
|
+
"description": "One JSON logger for a Project and its Packages that keeps credentials and error messages out of every line.",
|
|
6
5
|
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"engines": {
|
|
8
|
+
"node": ">=26"
|
|
9
|
+
},
|
|
7
10
|
"repository": {
|
|
8
11
|
"type": "git",
|
|
9
12
|
"url": "git+https://github.com/n8io/baseline.git",
|
|
10
13
|
"directory": "packages/logger"
|
|
11
14
|
},
|
|
12
|
-
"engines": {
|
|
13
|
-
"node": ">=26"
|
|
14
|
-
},
|
|
15
|
-
"files": [
|
|
16
|
-
"dist",
|
|
17
|
-
"README.md"
|
|
18
|
-
],
|
|
19
15
|
"exports": {
|
|
20
16
|
".": {
|
|
21
17
|
"types": "./dist/index.d.ts",
|
|
@@ -26,6 +22,10 @@
|
|
|
26
22
|
"default": "./dist/logger-err-serialize.js"
|
|
27
23
|
}
|
|
28
24
|
},
|
|
25
|
+
"files": [
|
|
26
|
+
"dist",
|
|
27
|
+
"README.md"
|
|
28
|
+
],
|
|
29
29
|
"publishConfig": {
|
|
30
30
|
"access": "public",
|
|
31
31
|
"registry": "https://registry.npmjs.org"
|
|
@@ -36,6 +36,7 @@
|
|
|
36
36
|
"scripts": {
|
|
37
37
|
"build": "tsdown",
|
|
38
38
|
"check": "tsc --noEmit && pnpm pack --out dist/package.tgz && publint dist/package.tgz --strict && attw dist/package.tgz --profile esm-only",
|
|
39
|
-
"test": "vitest run"
|
|
39
|
+
"test": "vitest run",
|
|
40
|
+
"test:unit": "vitest run"
|
|
40
41
|
}
|
|
41
42
|
}
|