# @bonniernews/logger 中文文档

规范地址：https://npmcn.com/package/%40bonniernews/logger/

版本：0\.0\.13
npm 元数据更新时间：2026-08-26T12:06:53.833Z
中文译文更新时间：2026-11-08T11:00:42.195Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bonniernews/logger
原文对照：https://npmcn.com/package/%40bonniernews/logger/?lang=original
项目主页：https://github.com/BonnierNews/logger#readme
源码仓库：https://github.com/BonnierNews/logger

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：47.6 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=18
- 运行依赖：2 个
- peer 依赖：@types/express ^4\.0\.0 \|\| ^5\.0\.0
- 首次发布：2024-10-31T14:25:05.586Z
- 最新版本发布：2025-10-15T08:33:32.740Z
- 近 30 天下载量：20806（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 0 个）

## 中文简介

使用 Trace 背景进行关联日志的一些简单功能

## 安装

```sh
npm install @bonniernews/logger
```

也可以使用：`pnpm add @bonniernews/logger`、`yarn add @bonniernews/logger`、`bun add @bonniernews/logger`

## README

# @ bonniernews/ 浏览器

Bonnier News logger 库,这使得统一伐木更容易. 它为GCP预配置,包括Express服务器的追踪能力.

```sh
npm install @bonniernews/logger
```

## 使用量

以下是启用日志跟踪的示例服务器 .

```js
import {
  getTraceparent,
  middleware,
  logger as buildLogger
} from "@bonniernews/logger";
import express from "express";

const logger = buildLogger();
const app = express();

// This middleware will create a request context and
// automatically decorate all logs with tracing data:
app.use(middleware());

app.get("/", async (req, res) => {
  logger.info("Hello, world!");

  // Propagate traceparent to other services
  const response = await fetch("https://some.other.service.bn.nr/some/endpoint", {
    headers: { traceparent: getTraceparent() },
  });

  ...
});
```

这个 `middleware` 应该尽早放入,因为只有在这个中间软件之后的日志才能得到追踪数据。 中间软件将从GCP中查找活动项目ID. 或者,你可以设置 `GCP_PROJECT` 用于此目的的环境变量.

使用 `getTraceparent` 函数将追踪信头传递给下游服务. 使用 `getTraceId` 如果您只想知道当前追踪识别.

如果您想要用自定义数据来装饰日志, 请使用导出 `decorateLogs` 函数。 为了使用这个,需要先安装中间软件.

## 接口

图书馆有这些命名的输出:

-   `logger`: 用于创建日志, 参见 [下级](https://npmcn.com/package/%40bonniernews/logger/#readme-logger)。 。 。 .
-   `middleware`:用于安装请求上下文商店的中件软件,用于以自动跟踪来装饰日志. 此中间软件允许使用 `decorateLogs`, (中文(简体) ), `getLoggingData`, (中文(简体) ), `getTraceparent` 财务报告和审定财务报表 `getTraceId`。 。 。 .
-   `attachTrace`: 如果您有单独的脚本或功能, 不使用快递的中件, 您可以在其中使用日志 lib .
-   `decorateLogs`: 向请求上下文添加数据的函数.
-   `getLoggingData`: 返回被装饰的数据字段并附带微量信息.
-   `getTraceparent`: 返回溯源头值 - 用于向下游服务提出的请求.
-   `getTraceId`: 返回微分值 - 如果想要将其添加到API 错误响应中,则有用.
-   `createTraceparent`: 生成微量母头值的功能.

### 锁定器

#### 选项

此库使用 [皮诺伐木机](https://github.com/pinojs/pino),并使用相同的选项创建实例。 在大多数情况下,不需要这样,您可以使用默认:

-   用途 `info` 作为最小日志级别
-   JSON 登录 `severity` 财务报告和审定财务报表 `message` 非本地环境的字段 - 符合 [GCP 结构化伐木](https://cloud.google.com/logging/docs/structured-logging) 标准
-   有利于当地发展和测试环境的采伐

#### 日志级别

记录器有以下的级别, 以及相应的GCP `severity` 映射 :

| 日志级别 | GCP 严重性 |
| --- | --- |
| `trace` | `DEBUG` |
| `debug` | `DEBUG` |
| `info` | `INFO` |
| `warn` | `WARNING` |
| `error` | `ERROR` |
| `fatal` | `CRITICAL` |

#### 日志消息

以下是如何使用日志的几个例子:

```js
import { logger } from "@bonniernews/logger";

const log = logger({ level: "debug" });

log.debug("This is just a message");

log.info("This is how to use %s strings: %d", "template", 123);

log.info({ any: { additional: "data" } }, "I'm attaching relevant data");

const error = new Error("Oops!");

// This will set error.message as the log message,
// and add a serialized error object under the `err` key:
log.warn(error);

// The `err` key is special, and triggers error serialization:
log.error({ err: error }, "This message takes precedence over err.message");
```

### 附加跟踪

示例

```js
import { attachTrace } from "@bonniernews/logger";

const getTrace = () => new Promise((resolve) => resolve(getTraceId()));
const runScript = async function (param1, param2) {
  const output = [param1, param2];
  output.push(getTraceId());
  const trace = await getTrace(); // The trace is available since this is invoked from a trace context.
  output.push(trace);
  return output;
};

const runWithTrace = await attachTrace(runScript);
const res1 = await runWithTrace(1, 2); // Will execute runScript with parameters 1, 2
const res2 = await runWithTrace(3, 4); // Will execute runScript with parameters 3, 4
```

#### 追踪

如果您想要对日志进行编解, 请使用库中的 `middleware`,它将使用节点ASync钩子存储和装饰所有日志 [标准化](https://www.w3.org/TR/trace-context/) `traceparent` 头曰.

## 常见问题

### @bonniernews/logger 是什么？

使用 Trace 背景进行关联日志的一些简单功能

### 如何安装 @bonniernews/logger？

在项目目录运行 npm install @bonniernews/logger，或使用 pnpm add / yarn add / bun add。

### @bonniernews/logger 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bonniernews/logger 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @bonniernews/logger 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @bonniernews/logger 可以商用吗？

@bonniernews/logger 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bonniernews/logger 的下载量有多少？

根据 npm 官方下载统计，@bonniernews/logger 在 2026/10/09 – 2026/11/07 这 30 天内被下载 20,806 次，日均约 694 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bonniernews/logger 还在维护吗？

最新版本 0\.0\.13 发布于 2025/10/15（1\.1 年前）；至今共发布 13 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/10/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。