@n8io/baseline-logger 3.0.0 → 3.1.1

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 CHANGED
@@ -1,16 +1,23 @@
1
1
  # @n8io/baseline-logger
2
2
 
3
- The one [pino](https://getpino.io) logger every app and package logs through: JSON to stdout, with credentials redacted and errors reduced to a safe shape.
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
- ## Exports
9
+ <p align="center"><img src="https://raw.githubusercontent.com/n8io/baseline/main/docs/readme/error-tracking-report.svg" width="880" alt="One logger.error call with a DatabaseError whose message holds an email address. The log line carries its class as msg, its code, constraint, stack frames and trace id; loggerErrorListen hands the same error to an Error report. The message is struck out of both."></p>
10
10
 
11
- - `logger`: the one logger, typed as the package's own `Logger` (`fatal`, `error`, `warn`, `info`, `debug`, `trace` and `level`), so the library behind it can change without touching a caller. Fields named like credentials (`authorization`, `cookie`, `password`, `token` and others) are logged as `[Redacted]`, also one level down and in headers.
12
- - `Logger` and `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`.
13
- - `@n8io/baseline-logger/err-serialize`: `loggerErrSerialize(value)` and `LoggerErr`. An error leaves the process only as its class name, `code`, `constraint` and stack, down the `cause` chain; never its message, which can hold input text. `logger` uses it for every `err`.
11
+ ## Guarantees
12
+
13
+ | You get | How |
14
+ | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
15
+ | **One logger everywhere** | Every app and Package imports the same `logger`, typed as this Package's own `Logger`, so the library behind it can change without touching a caller. |
16
+ | **Credentials never logged** | Fields named like credentials (`authorization`, `cookie`, `password`, `token` and others) log as `[Redacted]`, also one level down and in headers. |
17
+ | **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. |
18
+ | **Errors reach error tracking** | `loggerErrorListen` hears each error logged at error or fatal, inside the log call, so it sees the caller's trace. |
19
+ | **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. |
20
+ | **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`. |
14
21
 
15
22
  ## Example
16
23
 
@@ -23,7 +30,18 @@ logger.error({ err: error }, "Postgres idle client error");
23
30
  logger.error({ err: error });
24
31
  ```
25
32
 
26
- ## Needs
33
+ Tests read what was logged with `vi.spyOn(logger, "warn")`; nothing to configure.
34
+
35
+ ## Reference
36
+
37
+ <details><summary><b>Exports</b></summary>
38
+
39
+ | Export | Does |
40
+ | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41
+ | `logger` | The one logger: `fatal`, `error`, `warn`, `info`, `debug`, `trace` and `level`. Credential fields are redacted as above. |
42
+ | `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`. |
43
+ | `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. |
44
+ | `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. |
45
+ </details>
27
46
 
28
- - Env: `LOG_LEVEL` (`fatal`, `error`, `warn`, `info`, `debug`, `trace` or `silent`; default `info`).
29
- - With `@n8io/baseline-telemetry` preloaded, each record also goes out as an OTLP log with the active trace id.
47
+ **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,3 +1,6 @@
1
+ type LoggerErrorListener = (error: unknown) => void;
2
+ /** Calls `listener` with every error logged at error or fatal; the returned function stops it. */
3
+ export declare const loggerErrorListen: (listener: LoggerErrorListener) => (() => void);
1
4
  export type LoggerMethod = {
2
5
  (fields: unknown, message?: string): void;
3
6
  (message: string): void;
@@ -11,4 +14,5 @@ export type Logger = {
11
14
  debug: LoggerMethod;
12
15
  trace: LoggerMethod;
13
16
  };
14
- export declare const logger: Logger;
17
+ export declare const logger: Logger;
18
+ export type { LoggerErrorListener };
package/dist/index.js CHANGED
@@ -1,5 +1,29 @@
1
1
  import { loggerErrSerialize } from "./logger-err-serialize.js";
2
2
  import { pino } from "pino";
3
+ // src/logger-error-listen.ts
4
+ const listenersKey = Symbol.for("@n8io/baseline-logger.errorListeners");
5
+ const registry = globalThis;
6
+ registry[listenersKey] ??= /* @__PURE__ */ new Set();
7
+ const listeners = registry[listenersKey];
8
+ let emitting = false;
9
+ /** Calls `listener` with every error logged at error or fatal; the returned function stops it. */
10
+ const loggerErrorListen = (listener) => {
11
+ listeners.add(listener);
12
+ return () => {
13
+ listeners.delete(listener);
14
+ };
15
+ };
16
+ const loggerErrorEmit = (error) => {
17
+ if (emitting) return;
18
+ emitting = true;
19
+ try {
20
+ for (const listener of listeners) try {
21
+ listener(error);
22
+ } catch {}
23
+ } finally {
24
+ emitting = false;
25
+ }
26
+ };
3
27
  // src/logger-options.ts
4
28
  const fieldsSecret = [
5
29
  "accessToken",
@@ -26,10 +50,12 @@ const errFind = (first) => {
26
50
  if (first instanceof Error) return first;
27
51
  if (typeof first === "object" && first !== null && "err" in first && !("msg" in first)) return first.err;
28
52
  };
53
+ const levelError = 50;
29
54
  const loggerOptionsCreate = (level) => ({
30
- hooks: { logMethod(args, method) {
55
+ hooks: { logMethod(args, method, level) {
31
56
  const [first, second] = args;
32
57
  const err = errFind(first);
58
+ if (err !== void 0 && level >= levelError) loggerErrorEmit(err);
33
59
  if (err !== void 0 && typeof second !== "string") {
34
60
  const type = loggerErrSerialize(err).type;
35
61
  return method.apply(this, [first, type]);
@@ -45,4 +71,4 @@ const loggerOptionsCreate = (level) => ({
45
71
  });
46
72
  // src/index.ts
47
73
  const logger = pino(loggerOptionsCreate(process.env.LOG_LEVEL || "info"));
48
- export { logger };
74
+ export { logger, loggerErrorListen };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@n8io/baseline-logger",
3
- "version": "3.0.0",
3
+ "version": "3.1.1",
4
4
  "description": "The one pino logger every baseline app and package logs through.",
5
5
  "type": "module",
6
6
  "license": "MIT",