first commit

docs/observability/monitor/logger/src/init/init.md

@@ -0,0 +1,65 @@
+# init
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`initLogger` is the single bootstrap entry point for `@suaveplan/logger`. A caller invokes it once at application startup to get a fully configured logger with the `@suaveplan/error` interceptor bridge already wired. The function is idempotent-safe — the underlying `installSuaveplanErrorInterceptor` guards against double-registration — so calling `initLogger` from multiple modules during startup is safe.
+
+## Features
+
+- Accepts an optional pre-built `logger` to wire, otherwise creates a `ConsoleLogger`
+- Accepts `consoleConfig` to configure the default `ConsoleLogger` without constructing it manually
+- Wires `installSuaveplanErrorInterceptor` and returns the `uninstall` handle alongside the logger
+- Returns a typed `InitLoggerResult` so callers can cleanly tear down on shutdown
+
+## Usage: Basic Example
+
+```ts
+import { initLogger } from "@suaveplan/logger/init";
+
+const { logger, uninstall } = initLogger();
+logger.info("Application started");
+
+// On shutdown:
+process.on("SIGTERM", () => uninstall());
+```
+
+## Usage: Advanced Example
+
+```ts
+import { initLogger } from "@suaveplan/logger/init";
+import { JsonSink } from "@suaveplan/logger/sink";
+
+const jsonSink = new JsonSink({ writer: writeToLogAggregator });
+
+const { logger, uninstall } = initLogger({
+  consoleConfig: {
+    level: "info",
+    sinks: [jsonSink],
+    redaction: { rules: [{ kind: "pattern", pattern: /token|secret/i }] },
+  },
+});
+
+logger.info("Server ready", { port: 8080 });
+```
+
+## API Reference
+
+### `initLogger<TMetadata>(options?): InitLoggerResult`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `logger` | `Logger?` | Pre-built logger to wire into the error bridge |
+| `consoleConfig` | `ConsoleLoggerConfig?` | Config for the default `ConsoleLogger` when `logger` is absent |
+
+Returns `{ logger: Logger, uninstall: () => void }`.
+
+## Implementation Notes
+
+`initLogger` is intentionally thin — it delegates to `ConsoleLogger` and `installSuaveplanErrorInterceptor`. Keeping it as a thin coordinator makes it testable: callers that need a custom logger or specific sink configuration pass them in, rather than configuring a global singleton.
+
+### Startup Hook
+
+`initLogger` is the process-startup counterpart to `createLogger` — it installs a global error bridge that catches uncaught exceptions, unhandled promise rejections, and `SIGTERM` / `SIGINT` signals, then flushes any buffered sinks before exiting. Calling `initLogger` more than once is a no-op: the module tracks its own install state on a `Symbol.for` marker.