LogTape，一个用于 JavaScript 和 TypeScript 的零依赖结构化日志库，已发布 v0.6.0。发生了什么变化？

覆盖父记录器的接收器

LogTape 的功能之一是通过分层类别继承接收器。例如，如果您设置两个记录器，如下所示：

import { configure, getConsoleSink, getFileSink } from "@logtape/logtape";

await configure({
  sinks: {
    console: getConsoleSink(),
    file:    getFileSink("app.log"),
  },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"] },
  ],
});

写入 ["app"] 记录器的日志将仅保存到 app.log 文件，但写入 ["app", "module"] 记录器的日志将同时保存到 app.log 文件

app.log

文件并输出到控制台。这是因为 ["app", "module"] 记录器从其父类别 ["app"] 继承了接收器。 但是，有时您可能不希望出现这种行为。从 LogTape 0.6.0 开始，您现在可以
覆盖

父记录器的接收器。例如，如果您为子记录器启用parentSinks：“覆盖”选项，如下所示：

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

等待配置({ 汇：{ /* 省略；与上面相同*/ }, 记录器：[ { 类别：[“应用程序”]，级别：“调试”，接收器：[“文件”] }， { 类别：[“应用程序”，“模块”]，级别：“调试”，接收器：[“控制台”]，parentSinks：“覆盖”}， ], }); 写入["app"]记录器的日志只会保存到

app.log

文件，写入["app","module"]记录器的日志只会输出到控制台。这是因为子记录器 ["app", "module"] 覆盖了 ["app"] 记录器的接收器。

当然，默认值是parentSinks: "inherit"，所以如果你不指定该选项，它的行为会和以前一样。

如果您想了解此功能添加的背景，请参阅 GitHub Issue #15。

允许消息模板中的占位符使用前导/尾随空格

在以前的版本中，如果您这样登录：

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

logger.info("你好，{ name }!", { name: "Alice" });

与预期相反，一条日志Hello, undefined!将被创建。这是因为占位符 { name } 包含空格字符，因此它查找属性“ name ”而不是“ name ”。换句话说，您必须从占位符中删除空格，如下所示：

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

logger.info("你好，{name}！", { name: "Alice" });

或者在实际属性名称中添加相同的空格，如下所示：

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

logger.info("你好，{ name }！", { " name ": "Alice" });

虽然这并不是严格意义上的错误，但根据编码习惯，它是容易出错的行为。

但是，从LogTape 0.6.0开始，即使占位符的开头和结尾有空格，它也会寻找不带空格的属性名称。例如，如果您像这样登录：

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

logger.info("你好，{ name }!", { name: "Alice" });

正如预期的那样，日志是Hello, Alice!将被创建。

但是，如果有一个属性完全匹配（包括空格字符），则该属性将被优先考虑。例如，如果您像这样登录：

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

logger.info("你好，{ name }!", { name: "Alice", " name ": "Bob" });

你好，鲍勃！将被记录而不是你好，爱丽丝！。

如果您想了解此功能添加的背景，请参阅 GitHub Issue #16。

LogRecord.rawMessage 属性

LogRecord 是一种数据类型，表示在 LogTape 输出和格式化之前的日志。

虽然 LogRecord.message 属性已经存在，但该属性包含消息模板中的占位符替换为实际属性值后的结果。这在大多数情况下已经足够了，但是当日志输出目的地（接收器）是另一个日志系统时，您可能希望分别输出原始消息模板和属性值，从而允许接收日志系统用属性替换消息模板中的占位符直接值。

LogTape 0.6.0 中添加的 LogRecord.rawMessage 正是用于此目的的属性，其中包含消息模板的原始状态以及未替换的占位符。例如，如果您像这样登录：

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

logger.info("你好，{name}！", { name: "Alice" });

虽然 LogRecord.message 将包含值 ["Hello, ", "Alice", "!"]，但 LogRecord.rawMessage 将包含值 "Hello, {name}!"。

如果您想了解此功能添加的背景，请参阅 GitHub Issue #17。

可定制的内置文本格式化程序

文本格式化程序是一个接口，它确定每个日志如何在流接收器、文件接收器等中格式化为文本。实际的类型定义非常简单：

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

导出类型TextFormatter = (记录: LogRecord) => string;

但是，每次直接定义文本格式化程序可能会很麻烦，因此 LogTape 内置了 defaultTextFormatter 和 ansiColorFormatter 可供您使用。到目前为止，由于无法进行其他配置，因此您必须按原样接受预定格式。例如，如果您不喜欢像“警告”这样的日志级别输出为像 WRN 这样的三个字母缩写，则必须从头开始实现 TextFormatter。

但是，从 LogTape 0.6.0 开始，您可以通过 getDefaultTextFormatter() 和 getAnsiColorFormatter() 函数根据自己的喜好自定义各种格式设置，而无需从头开始实现 TextFormatter。

例如，如果要将“警告”这样的日志级别表示为单个大写字母W，可以这样配置：

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

const myFormatter = getDefaultTextFormatter({ level: "L" });

或者如果你想省略时间戳中的日期和时区，只显示时间，你可以这样配置：

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

const myFormatter = getDefaultTextFormatter({ 时间戳: "时间" });

更多格式化选项的说明，请参考相关文档。

如果您想了解此功能添加的背景，请参阅 GitHub Issue #13。

从 JSR 和 npm 获取

LogTape 0.6.0 已在 JSR 和 npm 上可用，所以立即获取！

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

deno 添加 @logtape/[email protected] # Deno npm 添加@logtape/[email protected] # npm pnpm 添加@logtape/[email protected] # pnpm 纱线添加 @logtape/[email protected] # 纱线 包子添加@logtape/[email protected] # 包子

祝您登录愉快！