메뉴
wellcrafted/logger for library diagnostics: 5 levels, typed errors, injected sinks, and host-owned durability. Use for attach primitives, background errors, durable host logs, or replacing console.* in library code.
기본적으로 소스를 먼저 확인하는 Prompt가 선택됩니다. 직접 명령으로 전환하거나 로컬 사본을 다운로드할 수도 있습니다.
설치 여부를 결정하기 전에 SKILL.md와 SkillsMP에 표시된 보조 파일을 읽어 보세요.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
직접 명령은 검토 Prompt를 거치지 않습니다. 실행하기 전에 소스를 확인하세요.
npx skills add https://github.com/EpicenterHQ/epicenter --skill logging명령은 한 줄로 유지됩니다. 복사하기 전에 가로로 스크롤해 전체 내용을 확인하세요.
로컬 사본을 원하시나요? SkillsMP에서 현재 제공할 수 있는 파일을 다운로드하세요.
SOC 직업 분류 기준
SKILL.md 표시 중
| name | logging |
| description | wellcrafted/logger for library diagnostics: 5 levels, typed errors, injected sinks, and host-owned durability. Use for attach primitives, background errors, durable host logs, or replacing console.* in library code. |
| metadata | {"author":"epicenter","version":"2.2"} |
Structured, level-keyed, field-oriented logging for library code. Modeled on Rust's tracing. Completes the defineErrors story: errors are structured data; level lives at the call site.
Ground API and behavior claims in the official wellcrafted-dev/wellcrafted
source and logger declarations for Epicenter's installed version. Ground call
site examples in current Epicenter code.
All of it ships from wellcrafted/logger: createLogger, consoleSink, memorySink, composeSinks, and the types. Runtime-agnostic, browser-safe. No file sink in-process: durability is a host concern (shell redirect, systemd journal, Cloudflare tail). The library emits to consoleSink; the operator decides where stdout/stderr go.
import { createLogger } from 'wellcrafted/logger';
const log = createLogger('markdown-materializer'); // defaults to consoleSink
log.();
result = ();
(result. !== ) log.(result.);
trace | debug | info | warn | error. No fatal: process termination is the app's call, not the library's.
| Level | Signature | Use for |
|---|---|---|
trace | (message, data?) | Per-token / per-message noise; off in prod |
debug | (message, data?) | Internal state transitions (handshakes, cache loads) |
info | (message, data?) | Lifecycle events (connected, loaded, flushed) |
warn | (err) | Recoverable failure: retry, fallback, partial result |
error | (err) | Unrecoverable at this layer; the operation has given up |
Shape split is intentional. warn / error take a typed error unary: the variant carries message, name, and captured fields. trace / debug / info are free-form because free-running diagnostic events don't need enumeration.
Native Error also satisfies the logger's structural { name, message }
contract. This is intentional for migration and exception boundaries; prefer a
tagged variant when the layer owns a stable failure vocabulary.
// Right: same error, different levels in different contexts
log.warn(SyncError.ConnectionFailed({ cause })); // inside retry loop
log.error(SyncError.ConnectionFailed({ cause })); // last attempt, giving up
Do NOT attach a severity to defineErrors variants. That's miette's pattern; tracing, log, and every production Rust logger put level on the call. Context-dependent data belongs at the context.
In epicenter, the typical pattern is branch on the Result, log inside the branch, then take action. The Result's data is usually needed on the Ok branch, so a chain combinator wouldn't earn its keep:
const walResult = trySync({
try: () => db.query('PRAGMA journal_mode = WAL').get(),
catch: (cause) => SqliteWriterError.PragmaSetupFailed({ pragma: 'WAL', cause }),
});
if (walResult.error !== null) {
log.warn(walResult.error);
} else if (walResult.data !== 'wal') {
log.warn(SqliteWriterError.WalSilentFallback({ actualMode: walResult.data }));
}
You can also mint-and-log a tagged variant directly inside a .catch tail when there's no Result to branch on:
}).catch((cause) => {
log.warn(MaterializerWriteError.TableWriteFailed({ tableName, cause }));
});
A sink is ((event) => void) & Partial<AsyncDisposable>: a callable with optional resource cleanup.
import {
createLogger,
consoleSink, // default; routes to console[level]
memorySink, // for tests; returns { sink, events }
composeSinks, // fan out to multiple sinks
} from 'wellcrafted/logger';
For a long-running daemon or CLI that needs durable logs, the library still emits to consoleSink; the operator decides where the stream goes:
bun run start # dev: console
bun run start 2>> ~/.app/app.jsonl # ad-hoc file capture
systemd-run --user bun run start # journal (structured queries via journalctl)
This used to be jsonlFileSink; that primitive was removed because owning a file writer in-process bought complexity (backpressure, dispose semantics, error fallbacks) that shell redirection already solves.
composeSinks(...): fan outconst sink = composeSinks(consoleSink, myCustomSink);
const log = createLogger('source', sink);
composeSinks forwards disposal to members that implement it (via sink[Symbol.asyncDispose]?.()). consoleSink is a no-op on dispose; stateful sinks flush and close.
memorySink(): for testsconst { sink, events } = memorySink();
const log = createLogger('test', sink);
log.warn(MyError.Thing({ cause: new Error('boom') }));
expect(events).toHaveLength(1);
expect(events[0]).toMatchObject({ level: 'warn', source: 'test' });
Do NOT assert on console.* output. Inject a memorySink and inspect the event array.
No module-level logger registry. No setDefaultLogger(). Each attach primitive takes an optional log?: Logger option and defaults to createLogger(<source>) (console sink). Caller wires sinks explicitly.
const markdown = attachMarkdownExport(workspace, { dir, tables, log });
const sqlite = attachBunSqliteMaterializer(workspace, { filePath, log });
const collaboration = openCollaboration(workspace.ydoc, {
url,
openWebSocket,
onReconnectSignal,
log,
});
Share one sink across loggers when you build a custom one:
const sink = composeSinks(consoleSink, myCustomSink);
const markdown = attachMarkdownExport(workspace, {
dir,
tables,
log: createLogger('workspace/markdown', sink),
});
const sqlite = attachBunSqliteMaterializer(workspace, {
filePath,
log: createLogger('workspace/sqlite', sink),
});
The whole surface is pure JS and browser-safe.
Every sink receives:
type LogEvent = {
ts: number; // epoch millis
level: LogLevel; // 'trace' | 'debug' | 'info' | 'warn' | 'error'
source: string; // from createLogger()
message: string; // human text: for warn/error, inherited from the typed error
data?: unknown; // the typed error for warn/error; free-form for info/debug/trace
};
Custom sinks that serialize for the wire should convert ts to ISO-8601 and flatten native Error instances (otherwise they JSON.stringify to {}).
error-handling skill: the trySync/tryAsync patterns the logger consumesdefine-errors skill: how to mint the typed error variants the logger consumesrust-errors skill: full tracing ↔ Logger mappingtapErr (from wellcrafted/result): Result-chain combinator that logs on the Err branch and passes the Result through. Rare in epicenter, since most call sites branch on result.error directly to use the data on the Ok branch. Reach for it only when the Result flows out of the function in a .then(...) chain.