208 lines
8.6 KiB
Markdown
208 lines
8.6 KiB
Markdown
# @mifi/logger
|
||
|
||
Intentional, namespaced logging for TypeScript browser and Node.js applications.
|
||
|
||
```ts
|
||
import { createLogger } from "@mifi/logger";
|
||
|
||
const logger = createLogger({ environment: "production", namespace: "WIDGET" });
|
||
logger.child("Button").debug("Rendered", () => ({ expensive: "only evaluated when shown" }));
|
||
```
|
||
|
||
## Install
|
||
|
||
```bash
|
||
pnpm add @mifi/logger
|
||
```
|
||
|
||
Requires Node.js `>=24`. Published to the private `@mifi` registry.
|
||
|
||
## Quick start
|
||
|
||
```ts
|
||
import { createLogger } from "@mifi/logger";
|
||
|
||
const logger = createLogger({
|
||
environment: "development", // "development" | "staging" | "production"
|
||
namespace: "API", // optional; string or string[] joined with ":"
|
||
});
|
||
|
||
logger.trace("very detailed");
|
||
logger.debug("diagnostic", () => ({ snapshot: heavyWork() }));
|
||
logger.info("ready");
|
||
logger.warn("slow response", { ms: 1200 });
|
||
logger.error("request failed", error);
|
||
logger.assert(userId, "missing user id");
|
||
|
||
const auth = logger.child("auth"); // namespace → "API:auth"
|
||
auth.info("token refreshed");
|
||
```
|
||
|
||
Console utility methods (`group`, `groupCollapsed`, `table`, `time`, `count`, `dir`, …) are available and gated by the same level policy as `info`.
|
||
|
||
## Runtime policy
|
||
|
||
Default levels by environment:
|
||
|
||
| Environment | Default level | Console shows |
|
||
| ------------- | ------------- | --------------- |
|
||
| `development` | `trace` | all levels |
|
||
| `staging` | `warn` | `warn`, `error` |
|
||
| `production` | `error` | `error` only |
|
||
|
||
Levels in order (most → least verbose): `trace` → `debug` → `info` → `warn` → `error` → `silent`.
|
||
|
||
### Override precedence
|
||
|
||
Highest wins:
|
||
|
||
1. Explicit `level` option on `createLogger`
|
||
2. Browser `sessionStorage.showLoggingFor`
|
||
3. Env vars `MIFI_LOG_LEVEL` / `MIFI_LOG_NAMESPACES`
|
||
4. Environment default (table above)
|
||
|
||
### Browser session override
|
||
|
||
```js
|
||
sessionStorage.setItem("showLoggingFor", "debug");
|
||
// or restrict to namespaces (exact or descendants):
|
||
sessionStorage.setItem("showLoggingFor", "debug:WIDGET,API");
|
||
```
|
||
|
||
`WIDGET` matches `WIDGET` and `WIDGET:Button`.
|
||
|
||
### Container / Node env overrides
|
||
|
||
See [Environment variables](#environment-variables) and [`env.example`](./env.example).
|
||
|
||
```bash
|
||
MIFI_LOG_LEVEL=debug
|
||
MIFI_LOG_NAMESPACES=WIDGET,API
|
||
```
|
||
|
||
## Environment variables
|
||
|
||
These are read from `process.env` (or from `options.env` when testing/injecting):
|
||
|
||
| Variable | Description |
|
||
| --------------------- | --------------------------------------------------------------------------- |
|
||
| `MIFI_LOG_LEVEL` | Override level: `trace`, `debug`, `info`, `warn`, `error`, or `silent`. |
|
||
| `MIFI_LOG_NAMESPACES` | Optional comma-separated namespace filters applied with the level override. |
|
||
|
||
When only `MIFI_LOG_LEVEL` is set, all namespaces are enabled at that level. When `MIFI_LOG_NAMESPACES` is also set, only matching namespaces (and their children) emit at that level.
|
||
|
||
Copy [`env.example`](./env.example) as a starting point for local or container config.
|
||
|
||
## Sentry
|
||
|
||
The Sentry adapter has **no SDK dependency**. Pass your official `@sentry/node`, `@sentry/browser`, or `@sentry/nextjs` module directly to `createSentrySink` — no consumer adapter or cast is required.
|
||
|
||
**Development never sends to Sentry.** Staging and production attach the sink when `sentry` is configured.
|
||
|
||
Destination policy when `sentry` is configured and `sinks` is not:
|
||
|
||
| Runtime + environment | Console | Sentry |
|
||
| ---------------------- | ---------------------- | -------------------------------- |
|
||
| Production **browser** | Off | Issues for errors; optional Logs |
|
||
| Production **Node** | On (stderr for errors) | Issues for errors; optional Logs |
|
||
| Staging | On (default `warn`+) | Issues for errors; optional Logs |
|
||
| Development | On | Nothing |
|
||
|
||
### Issues vs Logs
|
||
|
||
- **Errors** → Sentry Issues (`captureException` / `captureMessage`). Not also written to Logs.
|
||
- **Warnings and lower** → Sentry Logs (`sentry.logger.*`) only when `{ logs: true }` on the sink (or forced per call).
|
||
|
||
Default Sentry Logs thresholds when `logs` is enabled:
|
||
|
||
| Environment | Logs threshold |
|
||
| ----------- | -------------- |
|
||
| Staging | `info` |
|
||
| Production | `warn` |
|
||
|
||
Override with `logLevel` on `createSentrySink`. Console policy stays independent — production browsers can stay quiet while warnings still appear in Sentry Logs.
|
||
|
||
### Per-call options
|
||
|
||
`trace` / `debug` / `log` / `info` / `warn` / `error` (and `assert`) accept a trailing options object. Console utilities (`group`, `time`, …) do not.
|
||
|
||
```ts
|
||
import * as Sentry from "@sentry/nextjs";
|
||
import { createLogger } from "@mifi/logger";
|
||
import { createSentrySink } from "@mifi/logger/sentry";
|
||
|
||
const logger = createLogger({
|
||
environment: "production",
|
||
namespace: "API",
|
||
sentry: createSentrySink(Sentry, { logs: true }),
|
||
});
|
||
|
||
logger.error("Request failed", error, { requestId: "req_1" });
|
||
logger.warn("slow", { ms: 1200 }); // → Sentry Logs in production
|
||
logger.info("investigating", { orderId }, { sentry: true }); // force Logs
|
||
logger.error("expected", err, { suppressSentry: true }); // console only (when enabled)
|
||
```
|
||
|
||
| Option | Effect |
|
||
| ---------------------- | ------------------------------------------------------------------------ |
|
||
| `sentry: true` | Force this event to Sentry Logs (ignores Logs threshold; not for errors) |
|
||
| `suppressSentry: true` | Skip creating a Sentry Issue for an error |
|
||
|
||
A last argument is treated as options only when every key is `sentry` or `suppressSentry`. Prefer the third-argument form when you also pass data.
|
||
|
||
Logs payload: string message + flat primitive attributes (including `logger.namespace`). Nested objects are not unfurled.
|
||
|
||
Issue severities use Sentry’s union (`warning`, not logger `warn`). The sink maps `warn` → `warning` and `trace` → `debug` for Issues only; Logs keep logger level names (`sentry.logger.warn`).
|
||
|
||
## Custom sinks
|
||
|
||
Replace the default destinations entirely with `sinks`:
|
||
|
||
```ts
|
||
import { createLogger, createConsoleSink, type LogSink } from "@mifi/logger";
|
||
|
||
const analyticsSink: LogSink = {
|
||
emit(event) {
|
||
if (event.sendToConsole) analytics.track("log", event);
|
||
},
|
||
};
|
||
|
||
const logger = createLogger({
|
||
environment: "production",
|
||
sinks: [createConsoleSink(), analyticsSink],
|
||
});
|
||
```
|
||
|
||
When `sinks` is provided, the `sentry` option is not used for default sink selection.
|
||
|
||
## API overview
|
||
|
||
| Export | From | Purpose |
|
||
| ---------------------- | --------------------- | ------------------------------------------------ |
|
||
| `createLogger` | `@mifi/logger` | Build a namespaced, Console-shaped logger |
|
||
| `createConsoleSink` | `@mifi/logger` | Default styled console destination |
|
||
| `parseLoggingOverride` | `@mifi/logger` | Parse `debug` / `debug:NS1,NS2` override strings |
|
||
| `createSentrySink` | `@mifi/logger/sentry` | Adapter for any Sentry-like SDK |
|
||
|
||
Types: `Logger`, `LoggerOptions`, `LogLevel`, `LoggerEnvironment`, `LogEvent`, `LogSink`, `LogData`, `LogCallOptions`, and (from `/sentry`) `SentryLike`, `SentryScopeLike`, `SentrySeverityLevel`, `SentrySink`, `SentrySinkOptions`.
|
||
|
||
Optional destinations live under `src/sinks/` (console, Sentry today; New Relic / Datadog-style adapters can land beside them later). Public import paths stay `@mifi/logger` and `@mifi/logger/sentry`.
|
||
|
||
All public APIs include JSDoc with parameter and example documentation in the TypeScript sources.
|
||
|
||
## Lazy arguments
|
||
|
||
Any function passed **after** the first argument is invoked only if the event is emitted:
|
||
|
||
```ts
|
||
logger.debug("state", () => buildHugeSnapshot()); // skipped when debug is suppressed
|
||
```
|
||
|
||
## Releases
|
||
|
||
Woodpecker verifies pull requests and `main`, reports CI to Mattermost, then automatically releases from Conventional Commits merged to `main`. It updates `package.json` and `CHANGELOG.md`, creates a `vX.Y.Z` tag, and publishes to the private `@mifi` registry.
|
||
|
||
Use `fix:` for a patch, `feat:` for a minor release, and `feat!` / `fix!` (or a `BREAKING CHANGE:` footer) for a major release. Commits such as `docs:`, `test:`, and `chore:` do not release a package.
|
||
|
||
The release workflow uses the existing global `gitea_package_token`, `gitea_registry_username`, `gitea_release_token`, `mattermost_bot_access_token`, `mattermost_tests_channel_id`, `mattermost_pushes_channel_id`, and `mattermost_post_api_url` secrets.
|