# `@spinajs/log`

The logging system for SpinaJS. You resolve a `Log` service, call level methods
(`info`, `error`, …), and a **rules + targets** configuration decides which
logger writes **where** and in **what format**. It supports plain-text layouts
and structured JSON, buffered file logging with rotation/retention, network
sinks (Grafana Loki, OTLP), composable wrapper targets, a filter pipeline,
ambient request-scoped context with trace correlation, and runtime level
control.

## Table of contents

- [Which package do I import?](#which-package-do-i-import)
- [Quick start](#quick-start)
- [Log levels](#log-levels)
- [Loggers](#loggers)
- [Logging API](#logging-api)
- [Layouts / templates](#layouts--templates)
- [Targets (sinks)](#targets-sinks)
- [Rules](#rules)
- [Filters](#filters)
- [Structured logging](#structured-logging)
- [Async context & correlation](#async-context--correlation)
- [File archiving](#file-archiving)
- [Runtime level control](#runtime-level-control)
- [Configuration reference](#configuration-reference)
- [Extending](#extending)
- [Package map](#package-map)

## Which package do I import?

| Package | Use it for |
| --- | --- |
| `@spinajs/log` | **Application code.** Resolve `Log` and log. Ships the console/file/JSON/memory targets, the filter pipeline, `LogContext`, and runtime level control. |
| `@spinajs/log-common` | Only when writing a **custom target or filter** (abstract `LogTarget` / `LogFilter`, `ILogEntry`, `LogLevel`, `createLogMessageObject`, `serializeError`/`safeStringify`, `BatchQueue`). No implementation, so it avoids a circular dependency. |
| `@spinajs/internal-logger` | Only inside low-level packages (DI, configuration) that must log **before** the logger/config exists. Messages buffer and replay into the real logger once configuration resolves. |
| `@spinajs/log-source-graphana-loki` | The Grafana **Loki** target (`GraphanaLogTarget`). |
| `@spinajs/log-otlp` | The **OTLP/HTTP** export target (`OtlpLogTarget`) for any OpenTelemetry backend. |
| `@spinajs/telemetry` | Prometheus metrics + Apdex + an HTTP request-timing middleware. Metrics, not a log sink — see its own README. |

## Quick start

```ts
import { DI } from "@spinajs/di";
import { Log } from "@spinajs/log";

const log = await DI.resolve(Log, ["my-module"]); // logger named "my-module"

log.info("started");
log.info("user %s logged in", userId);            // printf-style args
log.error(err, "could not connect to %s", host);  // Error first, then message
log.info({ reqId, sku }, "checkout started");      // structured fields (merging object)
```

With no configuration the logger writes every level to a colored console.

## Log levels

Eight levels, lowest to highest severity:

```
trace < debug < info < success < warn < error < fatal < security
```

`success` and `security` are SpinaJS extras (a positive/notice level and a
top-of-scale audit level). A rule's `level` is the **minimum**; lower-severity
messages for that logger are dropped.

Each level also maps to the OpenTelemetry **SeverityNumber** (1–24), emitted by
the JSON/OTLP targets so any observability backend can rank/filter by severity:

| Level | SeverityNumber |
| --- | --- |
| trace | 1 |
| debug | 5 |
| info | 9 |
| success | 11 |
| warn | 13 |
| error | 17 |
| fatal | 21 |
| security | 23 |

## Loggers

- **Named** — `DI.resolve(Log, ["name"])`. The same name returns the same logger.
- **`@Logger` decorator** — inject a logger into a class property:
  ```ts
  import { Logger, Log } from "@spinajs/log";
  class UserService {
    @Logger("UserService") protected Log: Log;
    save() { this.Log.info("saving"); }
  }
  ```
- **Child loggers** — `const child = log.child("db", { pool: 1 });` creates a
  logger named `parent.db` that inherits the parent's variables plus any extra.
- **Per-logger variables** — `log.addVariable("region", "eu");` makes `${region}`
  available in that logger's layouts and structured records.
- **Timers** — `log.timeStart("q"); …; const ms = log.timeEnd("q");` returns the
  elapsed milliseconds.

## Logging API

Every level method (`trace`/`debug`/`info`/`warn`/`error`/`fatal`/`security`/`success`)
accepts three call shapes, dispatched by the **first argument**:

```ts
log.info("plain message");
log.info("formatted %s = %d", name, count);      // printf args
log.error(new Error("boom"), "while saving %s", id); // Error first -> structured `error`
log.info({ reqId: "abc", userId: 42 }, "handled"); // plain object first -> merged fields
```

- **Error first** → the error is serialized into a structured `error` field and
  the message/args follow.
- **Plain object first** (not an `Error`/array) → its keys are merged into the
  entry's variables (available as `${key}` in layouts and as fields in JSON),
  the second argument is the format string.
- **String first** → it is the message / printf format string.

**printf specifiers** (in the message string):

| Spec | Meaning |
| --- | --- |
| `%s` | string |
| `%d` | number |
| `%i` | `parseInt` |
| `%f` | `parseFloat` |
| `%j` / `%o` / `%O` | JSON / object |
| `%%` | literal `%` (consumes no argument) |

Leftover arguments are appended space-separated.

## Layouts / templates

Text targets render each entry through a **layout** string using `${…}`
placeholders. The default layout is:

```
${datetime} ${level} ${message}${?error} Exception: ${error:message}${/error} (${logger})
```

Available constructs:

| Construct | Renders |
| --- | --- |
| `${datetime}` | current date-time |
| `${date:dd_MM_yyyy}` | formatted date (Luxon-style format) |
| `${level}` | upper-case level, e.g. `ERROR` |
| `${message}` | the formatted message |
| `${logger}` | the logger name |
| `${myVar}` | any per-logger / merged / ambient variable |
| `${error:message}` | sub-property access on a variable (here the structured error's `message`) |
| `${?error} … ${/error}` | conditional block — rendered only when `error` is truthy |
| `${callsite}` | the caller's `file:line` (opt-in — see below) |

Set a target's `layout` to override the default, e.g.
`"${datetime} ${level} ${message} @ ${callsite} (${logger})"`.

**`${callsite}`** is captured only when *some* target's layout references it, so
logging stays zero-cost otherwise (no stack is walked). It resolves to
`basename:line` and is best-effort (empty string if the runtime stack can't be
parsed).

## Targets (sinks)

A **target** is where messages go. Each configured target has a `name`
(referenced by rules) and a `type` (the DI key). Common options
(`ICommonTargetOptions`): `name`, `type`, `enabled` (default `true`), `layout`.

> **Per-target filters.** A target definition may carry its own `filters` list
> (same shape as `logger.filters`). These run **only** when writing to that
> target, **after** the logger-level pipeline, and drop/mutate the entry for
> **that target only** — the entry is cloned per target first, so a mutating
> filter (e.g. `WhenRepeatedFilter`'s `(xN)`) never bleeds into other targets:
>
> ```js
> targets: [
>   { name: "Audit", type: "FileTarget",
>     filters: [{ type: "MatchFilter", pattern: "secret", mode: "drop" }] },
>   { name: "Console", type: "ConsoleTarget" }, // still sees everything
> ]
> ```

> **`enabled: false` targets are never instantiated.** A target definition
> marked `enabled: false` is skipped at resolve time — its class is never
> constructed, so a disabled `FileTarget` never opens its file, starts its flush
> timer, or spins up its archive service. A rule that references only disabled
> targets is silently skipped (treated as intentionally not routed); a rule that
> references a target **name that does not exist at all** still throws
> `InvalidOption`.

> **Config shape note:** some targets read their settings **flat** on the target
> definition (Console `theme`/`layout`, `MemoryTarget.limit`, `JsonTarget.stream`),
> while File/JSON-file and the wrapper targets read them **nested under an
> `options` object**. Loki and OTLP accept either. Each example below uses the
> form that target expects.

> **Runtime targets (attach/detach a sink).** Besides config, you can attach or
> detach a target on a specific logger **at runtime** (bunyan `addStream` style):
>
> ```js
> const log = DI.resolve(Log, ["my-logger"]);
>
> // attach – resolves the target ( honoring enabled:false ) and returns the instance
> const mem = log.addTarget(
>   { name: "Live", type: "MemoryTarget" },
>   { level: "warn" } // optional level window [level, maxLevel ?? security] + filters
> );
>
> // detach – flushes buffered entries, then removes it ( does NOT dispose it )
> await log.removeTarget("Live");
> ```
>
> `addTarget(def, opts?)` returns the resolved target instance (or `undefined`
> when `def.enabled === false`). `opts` accepts `level` / `maxLevel` (the level
> window) and `filters` (appended after `def.filters`). Adding a target whose
> `name` already exists **replaces** the previous one (flushed first), so a name
> is never duplicated, and the `MinLevel` / `${callsite}` gates are recomputed.
> `removeTarget(name)` force-flushes each matching target **before** detaching so
> no buffered entry is lost; it is a no-op when no target has that name.

| `type` | Class | Package | Writes to |
| --- | --- | --- | --- |
| `ConsoleTarget` | `ColoredConsoleTarget` / `BrowserConsoleTarget` | `@spinajs/log` | stdout/stderr (ANSI colors on Node; devtools styling in the browser) |
| `FileTarget` | `FileTarget` | `@spinajs/log` | a file via `@spinajs/fs`, buffered, with rotation/retention/zip |
| `JsonTarget` | `JsonTarget` | `@spinajs/log` | **stdout** as newline-delimited JSON (NDJSON) |
| `JsonFileTarget` | `JsonFileTarget` | `@spinajs/log` | a **file** as NDJSON (inherits FileTarget rotation) |
| `MemoryTarget` | `MemoryTarget` | `@spinajs/log` | an in-memory ring buffer (readable in-process) |
| `BlackHoleTarget` | `BlackHoleTarget` | `@spinajs/log` | nowhere (discards; useful in tests) |
| `SplitGroupTarget` | `SplitGroupTarget` | `@spinajs/log` | fans one target out to many |
| `AutoFlushTarget` | `AutoFlushTarget` | `@spinajs/log` | wraps a target; force-flushes it on high-severity entries |
| `RetryingTarget` | `RetryingTarget` | `@spinajs/log` | wraps a target; retries its `write` on rejection |
| `FallbackGroupTarget` | `FallbackGroupTarget` | `@spinajs/log` | ordered fallback across targets (+ drop-hook) |
| `GraphanaLogTarget` | `GraphanaLokiLogTarget` | `@spinajs/log-source-graphana-loki` | Grafana Loki over HTTP, batched |
| `OtlpLogTarget` | `OtlpLogTarget` | `@spinajs/log-otlp` | any OTLP/HTTP backend at `/v1/logs` |

### Console

```js
{ name: "Console", type: "ConsoleTarget" }
```

Node uses ANSI colors per level (override the palette with a `theme` map);
the browser build maps levels to `console.debug/log/warn/error`.

> **Browser caveat:** because output is formatted and dispatched through the
> logger, browser devtools attribute log lines to the console target, not your
> call site. Use `${callsite}` in the layout if you need the origin.

### File

Writes through the [`@spinajs/fs`](../fs) abstraction, so the active log and its
archives can live on any registered provider (local disk, S3, FTP, …). Options
live under `options`:

```js
{
  name: "File",
  type: "FileTarget",
  options: {
    path: "logs/log_${logger}_${date:dd_MM_yyyy}.txt", // required; variables allowed
    archivePath: "logs/archive",
    maxSize: 1024 * 1024,       // rotate past this many bytes
    compress: true,             // zip archived files
    maxBufferSize: 100,         // buffered messages before a flush
    maxQueueSize: 100000,       // hard in-memory cap; drops oldest if a sink is stuck
    flushInterval: 1000,        // ms; flush a partial buffer at least this often
    archiveStrategy: "SizeLogArchiveStrategy",
    retentionStrategies: ["CountLogRetentionStrategy"],
    maxArchiveFiles: 5,
    maxAge: 7 * 24 * 60 * 60,   // seconds
    archiveInterval: 60,        // seconds between size checks
  },
}
```

| option | default | meaning |
| --- | --- | --- |
| `path` | *required* | active log path, relative to the `fs` provider base path (variables allowed) |
| `archivePath` | log dir | archive directory, relative to the `archiveFs` provider |
| `fs` | `fs-log-default` | provider for the active log (`fs-log-default` is registered automatically at `process.cwd()`) |
| `archiveFs` | = `fs` | provider archives are moved to |
| `archiveStrategy` | `SizeLogArchiveStrategy` | rotation strategy class name |
| `retentionStrategies` | `["CountLogRetentionStrategy"]` | ordered retention strategy class names |
| `maxSize` | `1048576` | rotate when the active log exceeds this many bytes |
| `archiveInterval` | `60` | seconds between size checks |
| `rotate` | — | cron expression for `CronLogArchiveStrategy` (6-field, seconds supported) |
| `compress` | `false` | zip the archived file, then delete the raw copy |
| `maxBufferSize` | `100` | buffered messages before a flush |
| `maxQueueSize` | `100000` | hard cap; oldest buffered messages are dropped past it |
| `flushInterval` | `1000` | periodic flush tick in ms |
| `maxArchiveFiles` | `5` | archives to keep (`CountLogRetentionStrategy`) |
| `maxAge` | `604800` | max archive age in seconds (`AgeLogRetentionStrategy`) |

Writes are buffered and flushed as one batched `fs.append`, guarded by a
write-lock so a rotation never races an append; a failed append is retried
(never silently dropped, up to the `maxQueueSize` cap).

### JSON (stdout) and JSON file

`JsonTarget` emits one JSON object per line to stdout — ideal for container log
collectors (promtail/Loki, Filebeat/Elastic, Datadog, CloudWatch) that index
fields instead of parsing text:

```js
{ name: "Json", type: "JsonTarget", stream: "stdout" } // or "stderr"
```

A record looks like:

```json
{"time":"2026-07-15T…","severityNumber":17,"level":"ERROR","logger":"checkout","message":"save failed","reqId":"abc","error":{"name":"Error","message":"save failed","stack":"…","code":"ECONNREFUSED"}}
```

`JsonFileTarget` writes the same NDJSON to a **file**, reusing all of
FileTarget's rotation/retention/zip (configure it exactly like `FileTarget`
under `options`, with `type: "JsonFileTarget"`). Both stamp `time` at log time
and serialize with a never-throwing, circular-safe stringifier.

### Memory (ring buffer)

Keeps the last `limit` entries in memory so a debug endpoint or a crash handler
can read recent context back in-process:

```js
{ name: "Memory", type: "MemoryTarget", limit: 200 } // default 100
```

```ts
const ring = DI.resolve<MemoryTarget>("MemoryTarget");
ring.getRecords(); // ILogEntry[] (newest last); ring.clear() to empty
```

### BlackHole

```js
{ name: "Null", type: "BlackHoleTarget" } // discards everything
```

### Wrapper targets

Wrappers decorate inner target definitions (given under `options`).

**SplitGroup** — fan one logical target out to many sinks:

```js
{ name: "Multi", type: "SplitGroupTarget", options: { targets: [
  { name: "Console", type: "ConsoleTarget" },
  { name: "File", type: "FileTarget", options: { path: "logs/app.log" } },
]}}
```

**AutoFlush** — force-flush an inner (buffered) target when a high-severity entry
arrives, so a crash-level event is never left buffered:

```js
{ name: "SafeFile", type: "AutoFlushTarget", options: {
  target: { name: "File", type: "FileTarget", options: { path: "logs/app.log" } },
  flushLevel: "error", // default "error"
}}
```

**Retrying** — retry an inner target's `write` on rejection with exponential
backoff + jitter:

```js
{ name: "RetryOut", type: "RetryingTarget", options: {
  target: { name: "Custom", type: "MyTarget" },
  maxAttempts: 3,  // default 3
  delayMs: 100,    // default 100
}}
```

**FallbackGroup** — an ordered list; write advances to the next target when the
primary **rejects** (write-rejection contract), *and* a drop-hook chains entries
a self-healing network target **gives up on** (buffer overflow or a non-retryable
delivery failure) to the next target — a durable fallback for a down sink, with
no duplicates:

```js
{ name: "Durable", type: "FallbackGroupTarget", options: { targets: [
  { name: "Otlp", type: "OtlpLogTarget", options: { endpoint: "http://collector:4318" } },
  { name: "Spill", type: "JsonFileTarget", options: { path: "logs/undelivered.ndjson" } },
]}}
```

### Grafana Loki (`@spinajs/log-source-graphana-loki`)

```js
{ name: "Loki", type: "GraphanaLogTarget", options: {
  host: "http://localhost:3100",
  auth: { username: "admin", password: "admin" }, // optional (unauthenticated Loki allowed)
  labels: { app: "my-app" },
  interval: 3000, bufferSize: 10, maxBufferSize: 1000, timeout: 1000,
}}
```

Batched HTTP push with exponential-backoff + jitter retry (honoring
`Retry-After`, retrying only network errors and 429/502/503/504); non-retryable
errors surface instead of looping. The primary buffer is bounded.

### OTLP (`@spinajs/log-otlp`)

Export to any OpenTelemetry backend (OTel Collector, Grafana/Tempo, Datadog, …):

```js
{ name: "Otlp", type: "OtlpLogTarget", options: {
  endpoint: "http://localhost:4318",       // POSTs to /v1/logs
  headers: { Authorization: "Bearer …" },  // optional
  resource: { "service.name": "my-app" },  // resource attributes
  scopeName: "@spinajs/log",
  interval: 3000, bufferSize: 10, maxBufferSize: 1000, timeout: 5000,
}}
```

Maps each entry to the OTLP Logs model — `severityNumber`, `body`, resource +
record attributes, `traceId`/`spanId` from the request trace context, and a
structured `error` to `exception.type`/`exception.message`/`exception.stacktrace`
semantic attributes. Batched with the same resilience retry as Loki.

## Rules

A **rule** binds a logger-name pattern to a minimum `level` and one or more
`target` names:

```js
{ name: "http/*/controller", level: "info", target: ["Console", "File"] }
```

### Level windows (`maxLevel`)

`level` is the **lower** bound. Add an optional `maxLevel` to route only a level
**window** `[level, maxLevel]` (inclusive) — e.g. warn/error but **not**
fatal/security:

```js
{ name: "*", level: "warn", maxLevel: "error", target: "Ops" }
```

Without `maxLevel` the upper bound defaults to the highest level (`security`), so
a plain min-only rule is unchanged.

Several rules may route to the **same** target with **different** windows; the
target then accepts the **union** of those windows. So two rules `info..info` and
`error..error` to one target deliver `info` and `error` but **not** a `warn`
between them.

> `maxLevel` does **not** lower the per-logger `MinLevel` fast-gate: a call above
> every window still builds the entry and is then filtered out per target — the
> gate only tracks the lowest `level` across rules.

Name matching uses glob semantics:

- `*` — any logger name.
- `prefix*` — names starting with `prefix`.
- `a.b.*` — dotted namespaces.
- an exact name matches only itself.

### Ordered, additive matching (`final`)

Rules are evaluated **in config order**, and matching is **additive** (NLog-style):
**every** rule whose pattern matches a logger applies, so a logger matched by both
`*` and a specific rule routes to **both** (targets are de-duped downstream, so a
target hit by two matching rules still receives each entry once).

A matched rule marked `final: true` **stops** evaluation of any *later* rules; that
final rule and all earlier matched rules still apply.

```js
rules: [
  { name: "db.pool", level: "trace", target: "PoolDebug", final: true }, // stops here
  { name: "*",       level: "info",  target: "Console" },                 // skipped for db.pool
]
```

- `db.pool` matches the first rule, applies it, and stops — the later `*` is **not**
  applied, so `db.pool` routes **only** to `PoolDebug`.
- any other logger doesn't match `db.pool`, falls through, and routes to `Console`.

> **Migration from the old behavior.** Previously a specific rule *dropped* the `*`
> catch-all, so adding a rule for one logger silently **excluded** it from the
> global console/file. Now the specific rule is **additive** — that logger reaches
> both its own target **and** the catch-all. To restore the old "this logger goes
> **only** here" behavior, mark its rule `final: true` and place it **before** the
> `*` catch-all (as above).

## Filters

Filters run in order per logger and can drop or modify entries. Configure a list
under `logger.filters`; each item's `type` is a DI-registered filter. A filter
returns the (possibly modified) entry to keep, or drops it.

```js
logger: {
  filters: [
    { type: "LevelFilter", min: "warn" },
    { type: "MatchFilter", pattern: "healthcheck", mode: "drop" },
    { type: "RateLimitFilter", limit: 100, intervalSeconds: 10 },
    { type: "WhenRepeatedFilter", timeout: 10 },
  ],
  // …targets, rules
}
```

| Filter | Options | Effect |
| --- | --- | --- |
| `WhenRepeatedFilter` | `timeout` (s, default 10), `maxKeys` (default 1024) | collapses identical repeated entries within the window into one, appending `(xN)` when logging resumes |
| `LevelFilter` | `min`, `max` (level names) | keeps only entries whose level is within `[min, max]` |
| `MatchFilter` | `pattern`, `field` (default `message`), `mode` (`keep`/`drop`, default `keep`), `flags` | regex-match a variable; keep on match (or drop, in `drop` mode); an invalid pattern is a no-op |
| `RateLimitFilter` | `limit`, `intervalSeconds`, `key` (optional variable) | fixed-window rate limit; drops overflow, per-key or global |

Filters run **after** the near-zero-cost level gate, so disabled levels never
reach them. The legacy `logger.whenRepeated` option still works (mapped to a
prepended `WhenRepeatedFilter`).

The same filter list can also be attached **per target** (`targets[].filters`) to
filter for one sink only — see [Targets](#targets-sinks). Per-target filters run
**after** the logger-level pipeline on a per-target clone, so a filter that mutates
the entry there never affects other targets.

## Structured logging

Use `JsonTarget`/`JsonFileTarget` (or Loki/OTLP) to emit machine-readable
records. The pieces:

- **Serializer registry** — registered field serializers run when an entry is
  built. The default `error` serializer turns an `Error` into
  `{ name, message, stack, code, signal }`, walking the `.cause` /
  `AggregateError` chain into `stack`. Register your own:
  ```ts
  import { registerSerializer } from "@spinajs/log-common";
  registerSerializer("req", (r: any) => ({ method: r.method, url: r.url }));
  // then: log.info({ req }, "handled")
  ```
  A serializer that throws degrades to `{ serializerError }` — logging never
  crashes the caller.
- **Merging-object fields** — `log.info({ reqId, sku }, "…")` adds `reqId`/`sku`
  as first-class fields.
- **`safeStringify`** — the JSON targets serialize with a never-throwing,
  `[Circular]`-safe stringifier, so a circular field can't break logging.
- **`severityNumber`** — the OTel severity number is included on JSON/OTLP
  records for backend severity ranking.

## Async context & correlation

`LogContext` provides ambient, per-operation variables over an
`AsyncLocalStorage` shared with `@spinajs/http` — so anything logged inside a
request automatically carries its context with zero threading.

```ts
import { LogContext } from "@spinajs/log";

LogContext.with({ requestId: "abc", tenant: "acme" }, async () => {
  // any logger, any depth, across awaits:
  log.info("deep inside"); // entry carries requestId + tenant
});
```

- `LogContext.with(vars, fn)` — run `fn` with `vars` merged onto the current
  context (copy-on-write; nesting accumulates).
- `LogContext.active()` — the current context (or `{}`).
- `LogContext.set(key, value)` — late-bind a value onto the active context.
- `LogContext.bind(fn)` — capture the context and re-attach it to a detached
  callback / event handler.

Only **scalar** values (string/number/boolean/bigint) from the ambient context
are projected into log lines — objects/arrays/Dates are skipped as noise (pass
structured payloads explicitly per call). Inside an HTTP request the context is
`req.storage`, so logs automatically carry `requestId` and `realIp`.

**Trace correlation** — the http `RequestId` middleware continues an inbound W3C
`traceparent` (or starts a new trace) and seeds `traceId`/`spanId` into the
context, so every log line across services shares a trace id (and they surface as
top-level fields on OTLP records). Helpers `parseTraceparent`,
`formatTraceparent`, and `newTraceContext` are exported for custom propagation.

## File archiving

`FileTarget`/`JsonFileTarget` rotate and prune via strategies selected by class
name:

**Rotation** (when to archive) — one strategy:

- `SizeLogArchiveStrategy` — interval timer; rotates when the active log passes `maxSize`.
- `CronLogArchiveStrategy` — rotates on the `rotate` cron expression (6-field, seconds supported).

**Retention** (which archives to delete) — an ordered list, so policies compose:

- `CountLogRetentionStrategy` — keep the newest `maxArchiveFiles`.
- `AgeLogRetentionStrategy` — delete archives older than `maxAge` seconds.

```js
{ name: "File", type: "FileTarget", options: {
  path: "logs/app.log",
  rotate: "0 0 1 * * *",                // 1am daily
  archiveStrategy: "CronLogArchiveStrategy",
  retentionStrategies: ["CountLogRetentionStrategy", "AgeLogRetentionStrategy"],
  maxArchiveFiles: 5,
  maxAge: 7 * 24 * 60 * 60,
  compress: true,
}}
```

Custom strategies extend `LogArchiveStrategy` / `LogRetentionStrategy`, register
in DI, and are named in the config. The browser build omits `FileTarget` and the
archive module (and never pulls in `@spinajs/fs`).

## Runtime level control

Every logger supports a runtime override on top of its rule-derived minimum
level, with a near-zero-cost disabled path (a disabled call returns before
building an entry):

```ts
log.getLevel();            // current effective LogLevel
log.setLevel("error");     // gate everything below error (persists in the browser)
log.setDefaultLevel("info"); // set only if nothing is already overridden/persisted
log.enableAll();           // = setLevel("trace")
log.disableAll();          // silence everything
log.resetLevel();          // back to the rule-derived level
```

In the browser the chosen level persists to `localStorage` (cookie fallback), so
it survives reloads; on Node persistence is a no-op. `setLevel` accepts a level
name or a `LogLevel` value (validated via `normalizeLevel`).

## Configuration reference

A complete `logger` configuration, validated against the schema in
`src/schemas/log.configuration.ts` (`targets` and `rules` are required non-empty
arrays; a target needs `name` + `type`; a rule needs `name` + `level` + `target`):

```js
module.exports = {
  logger: {
    variables: {},
    targets: [
      { name: "Console", type: "ConsoleTarget" },
      { name: "Json", type: "JsonTarget", stream: "stdout" },
      { name: "File", type: "FileTarget", options: {
          path: "logs/log_${logger}_${date:dd_MM_yyyy}.txt",
          archivePath: "logs/archive",
          maxSize: 1024 * 1024,
          compress: true,
          maxBufferSize: 8 * 1024,
          retentionStrategies: ["CountLogRetentionStrategy", "AgeLogRetentionStrategy"],
          maxArchiveFiles: 5,
          maxAge: 7 * 24 * 60 * 60,
      }},
    ],
    filters: [
      { type: "WhenRepeatedFilter", timeout: 10 },
    ],
    rules: [
      { name: "*", level: "info", target: "Console" },        // everything -> console
      { name: "audit*", level: "trace", target: ["Json", "File"] }, // audit loggers -> json + file
    ],
  },
};
```

## Flushing & shutdown

Buffered targets (`FileTarget`, Loki, OTLP) hold entries in an in-memory
`BatchQueue` and drain them on their own tick. To force a drain explicitly:

- **`log.flush()`** — force-drains THIS logger's targets' buffers
  (`Promise<void>`). It calls `forceFlush()` on each target; on a non-buffered
  target that is a harmless no-op. `flush()` does **not** close or dispose the
  target — handle and timer teardown remains the DI container's job.
- **`Log.flushAll()`** — flushes every registered logger (best-effort; never
  rejects). Static.
- **`Log.clearLoggers()`** — flushes all loggers **before** disposing them, so
  buffered entries are written out during teardown rather than relying on the DI
  container disposing the target singletons.

On a **clean** process exit the log bootstrapper registers a Node-only
`beforeExit` hook that runs `Log.flushAll()`. This is best-effort: `beforeExit`
does not fire on hard exits (`process.exit`, signals, crashes), so call
`Log.flushAll()` / `Log.clearLoggers()` yourself in those paths.

## Extending

**Custom target** — extend `LogTarget`, register it under a `type`, implement
`write`. Optionally implement `forceFlush` (for buffered targets) and set
`OnDropped` semantics (see the fallback contract):

```ts
import { LogTarget, ICommonTargetOptions, ILogEntry } from "@spinajs/log-common";
import { Injectable, Singleton } from "@spinajs/di";
import { format } from "@spinajs/configuration-common";

@Singleton()
@Injectable("MyTarget")
export class MyTarget extends LogTarget<ICommonTargetOptions> {
  public write(entry: ILogEntry): void {
    if (!this.Options.enabled) return;
    const line = format(entry.Variables, this.Options.layout);
    // …deliver `line`… ; reject/throw to signal non-acceptance (Retry/Fallback act on it)
  }
}
```

The `write()` contract: it **may reject** to signal the entry was not accepted —
`RetryingTarget`/`FallbackGroupTarget` act on that. Self-healing targets resolve
and call the optional `OnDropped(entry)` hook for entries they ultimately give
up on, which `FallbackGroupTarget` chains to a durable fallback.

**Custom filter** — extend `LogFilter`, register it under a `type`, implement
`apply` (return the entry to keep, or `null` to drop):

```ts
import { LogFilter, ILogEntry } from "@spinajs/log-common";
import { Injectable } from "@spinajs/di";

@Injectable("OnlyErrors")
export class OnlyErrors extends LogFilter {
  public apply(entry: ILogEntry): ILogEntry | null {
    return entry.Level >= 5 /* Error */ ? entry : null;
  }
}
```

## Package map

```
your code ──> @spinajs/log ( Log service, targets, filters, rules, LogContext )
                    ▲
 low-level pkgs ──> @spinajs/internal-logger  (buffers until config is ready,
                    │                           then replays into @spinajs/log)
                    ▼
              @spinajs/log-common  (contracts: Log, LogTarget, LogFilter,
                                    BatchQueue, serializers, layout variables)

network sinks:  @spinajs/log-source-graphana-loki ( GraphanaLogTarget )
                @spinajs/log-otlp                  ( OtlpLogTarget )
metrics:        @spinajs/telemetry                 ( Prometheus + Apdex + timing )
```

`InternalLogger` exists so packages that load **before** configuration/logging
(DI, configuration) can still log. Those messages buffer and flush into the real
targets once `Configuration` resolves; on process exit any still-buffered
messages print to the console so nothing is lost. Do not use `InternalLogger` in
application code — resolve `Log` instead.