first commit

docs/observability/monitor/logger/src/console/console-logger.md

@@ -0,0 +1,70 @@
+# console-logger
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+`ConsoleLogger` extends `AbstractLogger` to provide human-readable, ANSI-coloured terminal output — the default logger for development and local debugging. It wires a `ConsoleSink` as the first element of its sink chain, so the full enterprise pipeline (level filtering, redaction, sampling, OTel correlation, metrics) runs before any output reaches the terminal. Configuration mirrors the existing v1 API exactly, preserving backward compatibility.
+
+## Features
+
+- ANSI colour per severity level (configurable at construction and runtime)
+- ISO timestamp prefix (configurable)
+- Optional tag rendering as `#tag` tokens
+- Optional metadata rendering as compact JSON suffix
+- All `AbstractLogger` features: redaction, sampling, OTel, clock injection, `getMetrics()`
+
+## Usage: Basic Example
+
+```ts
+import { ConsoleLogger } from "@suaveplan/logger/console";
+
+const log = new ConsoleLogger({ level: "info" });
+log.info("Server started", { port: 3000 });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { ConsoleLogger } from "@suaveplan/logger/console";
+
+const log = new ConsoleLogger({
+  level: "debug",
+  colors: true,
+  timestamp: true,
+  includeMetadata: true,
+  tags: ["api"],
+  redaction: { rules: [{ kind: "pattern", pattern: /token|secret/i }] },
+});
+
+log.info("User authenticated", { userId: "u-1", token: "abc" }, ["auth"]);
+// [2024-…] [INFO] [#api #auth] User authenticated
+// { "userId": "u-1", "token": "[REDACTED]" }
+```
+
+## API Reference
+
+### `class ConsoleLogger<TMetadata> extends AbstractLogger<TMetadata>`
+
+**Constructor**: `new ConsoleLogger(config?: ConsoleLoggerConfig<TMetadata>)`
+
+Extends `AbstractLoggerConfig` with:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `colors` | `boolean` | `true` | ANSI colour codes |
+| `timestamp` | `boolean` | `true` | ISO timestamp prefix |
+| `includeMetadata` | `boolean` | `false` | Compact JSON metadata suffix |
+| `includeTags` | `boolean` | `true` | `#tag` tokens inline |
+
+#### Runtime mutation methods
+
+- `setColors(enabled: boolean)`
+- `setTimestamp(enabled: boolean)`
+- `setIncludeMetadata(enabled: boolean)`
+- `setIncludeTags(enabled: boolean)`
+
+## Implementation Notes
+
+The `writeLog()` hook is a no-op — all output is delegated to `ConsoleSink` registered in the `sinks` array. This ensures records pass through redaction and sampling (handled by `AbstractLogger`) before any console call. Runtime mutation methods write directly to the `ConsoleSink`'s protected fields.