# @emartech/json-logger 中文文档

规范地址：https://npmcn.com/package/%40emartech/json-logger/

版本：9\.2\.5
npm 元数据更新时间：2026-11-04T10:11:11.477Z
中文译文更新时间：2026-11-13T14:36:32.620Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：29.6 kB，21 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- 首次发布：2017-09-11T10:43:31.542Z
- 最新版本发布：2026-06-01T06:27:43.630Z
- 近 30 天下载量：92933（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：57（近 12 个月 5 个）

## 中文简介

有命名空间支持的小型和快Json日志

## 安装

```sh
npm install @emartech/json-logger
```

也可以使用：`pnpm add @emartech/json-logger`、`yarn add @emartech/json-logger`、`bun add @emartech/json-logger`

## README

# @emartech/json-logger (英语)

一个以 JSON 格式输出日志的小而快的日志库 . 其基于命名空间的启用/失效机制与 [调试](https://github.com/visionmedia/debug)。 。 。 .

### 安装

```bash
npm install @emartech/json-logger
```

### 使用量

自8.0.0起,默认在伐木时将使用ECS字段.

如果您还需要旧格式, 您需要覆盖 `outputFormat` 相会. `configure` 将在全球范围内对日志的所有实例应用此设置.

```javascript
const { createLogger } = require('@emartech/json-logger');

createLogger.configure({
  outputFormat: 'legacy'
});

```

#### 脚本

```javascript
process.env.DEBUG = 'redis';
const { createLogger } = require('@emartech/json-logger');
const mongoLogger = createLogger('mongo');
const redisLogger = createLogger('redis');

redisLogger.info('connected', { domain: 'yahoo' });
// ECS format: {"event":{"action":"connected","created":"2016-08-15T08:50:23.566Z"},"log":{"logger":"redis","level":30},"domain":"yahoo"}
// Legacy format: {"name":"redis","action":"connected","level":30,"time":"2016-08-15T08:50:23.566Z","domain":"yahoo"}

mongoLogger.info('connected', { domain: 'google' });
// no output, because 'mongo' is not within namespaces (process.env.DEBUG)

redisLogger.fromError('query', new Error('Unauthorized'), { problem: 'missmatch' });
// ECS format: {"event":{"action":"query","created":"2016-08-15T08:50:23.569Z"},"log":{"logger":"redis","level":50},"error":{"type":"Error","message":"Unauthorized","stack_trace":"..."},"problem":"mismatch"}
// Legacy format: {"name":"redis","action":"query","level":50,"time":"2016-08-15T08:50:23.569Z","error_name":"Error","error_stack":"Error: Unauthorized\n    at Object.<anonymous> (/home/blacksonic/workspace/bunyan-debug/example.js:15:32)\n    at Module._compile (module.js:541:32)\n    at Object.Module._extensions..js (module.js:550:10)\n    at Module.load (module.js:458:32)\n    at tryModuleLoad (module.js:417:12)\n    at Function.Module._load (module.js:409:3)\n    at Module.runMain (module.js:575:10)\n    at run (bootstrap_node.js:352:7)\n    at startup (bootstrap_node.js:144:9)\n    at bootstrap_node.js:467:3","error_message":"Unauthorized","problem":"missmatch"}
```

#### 类

```javascript
const { createLogger } = require('@emartech/json-logger');
const logger = createLogger('Exporter');

class Exporter {
  export() {
    mongoLogger.info('export', { customer_id: 123 });
  }
}
```

```typescript
import { createLogger } from '@emartech/json-logger';
const logger = createLogger('Exporter');

class Exporter {
  export() {
    mongoLogger.info('export', { customer_id: 123 });
  }
}
```

#### 测试

```javascript
import { Logger } from '@emartech/json-logger';

describe('Exporter', () => {
  it('should log', () => {
    jest.spyOn(Logger.prototype, 'info').mockReturnValue();
    const exporter = new Exporter();
    
    exporter.export();

    expect(Logger.prototype.info).toHaveBeenCalledWith('export', { customer_id: 123 });
  })
});
```

更多实例可见于 `examples` 目录.

### API 密码

##### JsonLogger( 命名空间)

图书馆的默认导出起到工厂方法的作用. 返回带有指定命名空间的日志实例 . 这个 `DEBUG` 然后使用环境变量来启用基于逗号限制名称的这些实例. 已禁用实例输出无日志 .

```javascript
process.env.DEBUG = 'redis,mysql';
const { createLogger } = require('@emartech/json-logger');

const mongoLogger = createLogger('mongo');
// mongo instance will be disabled

const redisLogger = createLogger('redis');
// redis instance will be enabled
```

##### JsonLogger.prototype.info(动作,数据) 互联网档案馆的存檔,存档日期2011-10-21

用 JSON 格式打印提供给控制台的数据.

```javascript
const { createLogger } = require('@emartech/json-logger');
const redisLogger = createLogger('redis');

redisLogger.info('connected', { domain: 'yahoo' });
// ECS format: {"event":{"action":"connected","created":"2016-08-15T08:50:23.566Z"},"log":{"logger":"redis","level":30},"domain":"yahoo"}
// Legacy format: {"name":"redis","action":"connected","level":30,"time":"2016-08-15T08:50:23.566Z","domain":"yahoo"}

redisLogger.info('connected');
// ECS format: {"event":{"action":"connected","created":"2016-08-15T08:50:23.566Z"},"log":{"logger":"redis","level":30}}
// Legacy format: {"name":"redis","action":"connected","level":30,"time":"2016-08-15T08:50:23.566Z"}
```

默认显示实例的命名空间( N)`name`),以ISO8601格式显示的当前时间(`time`, (中文(简体) ), 将动作传递到日志方法和与该方法相关的日志级别. 第二个论点被分配到这些基本领域,并连同它们一起展示.

##### Json Logger.prototype.trace(动作,数据)

和追踪日志级别的信息相同.

##### JsonLogger.prototype.debug(动作,数据)

与调试日志级别的信息相同 .

##### Json Logger.prototype.warn(动作,数据) 互联网档案馆的存檔,存档日期2013-12-21

与警告日志级别的信息相同 .

##### JsonLogger.prototype.error(动作,数据) 互联网档案馆的存檔,存档日期2011-12-21

与错误日志级别的信息相同 .

##### Json Logger.prototype.fatal(动作,数据)

与致命日志级别的信息相同.

##### Json Logger. prototype. from Error( 动作, 数据)

显示一个格式化为一行的错误对象. 所显示行包含堆栈痕量,名称和出错消息(对于Axios出错,也包含请求和响应细节). 日志级别默认为出错 .

```javascript
const { createLogger } = require('@emartech/json-logger');
const redisLogger = createLogger('redis');

redisLogger.fromError('query', new Error('Unauthorized'), { problem: 'missmatch' });
// ECS format: {"event":{"action":"query","created":"2016-08-15T08:50:23.569Z"},"log":{"logger":"redis","level":50},"error":{"type":"Error","message":"Unauthorized","stack_trace":"..."},"problem":"mismatch"}
// Legacy format: {"name":"redis","action":"query","level":50,"time":"2016-08-15T08:50:23.569Z","error_name":"Error","error_stack":"Error: Unauthorized\n    at Object.<anonymous> (/home/blacksonic/workspace/bunyan-debug/example.js:15:32)\n    at Module._compile (module.js:541:32)\n    at Object.Module._extensions..js (module.js:550:10)\n    at Module.load (module.js:458:32)\n    at tryModuleLoad (module.js:417:12)\n    at Function.Module._load (module.js:409:3)\n    at Module.runMain (module.js:575:10)\n    at run (bootstrap_node.js:352:7)\n    at startup (bootstrap_node.js:144:9)\n    at bootstrap_node.js:467:3","error_message":"Unauthorized","problem":"missmatch"}
```

##### JsonLogger.prototype.warn FromError(动作,数据) 互联网档案馆的存檔,存档日期2011-12-20

与 `fromError`,但带有警告日志级别.

##### Json Logger.prototype.timer () 互联网档案馆的存檔,存档日期2013-12-21

创建与日志实例( 信息、 警告、 错误、 来自 Error等) 方法相同的新定时器实例 并且记录了从创建实例起以毫秒计的时间. 所经过的时间将记入 `duration` 字段.

```javascript
const { createLogger } = require('@emartech/json-logger');
const redisLogger = createLogger('redis');

const timer = redisLogger.timer();

// heavy task

timer.info('completed');
// Legacy format: {"name":"redis","action":"completed","level":30,"time":"2016-08-15T08:50:23.566Z","duration": 1500}
// ECS format: {"event":{"action":"completed","duration":"1500","created":"2016-08-15T08:50:23.566Z"},"log":{"logger":"redis","level":30}}
```

##### JsonLogger.confetch( 选项)

伐木过程的单独步骤可以在此配置. 这些修改影响到图书馆的所有实例. 有了变压器,我们就可以在传递到前置物和输出之前更改要记录的数据. 它是一个完美的地方,可以添加机器运行中的名称或与当前存储在本地续存上的线程相关的请求ID. 随着“ 增强的StackTraces” 选项被设定为对齐, 错误堆栈跟踪将包含错误的原因以及( 如果有的话) 包括其堆栈跟踪 并显著改进了截取限制.

```javascript
const { createLogger } = require('@emartech/json-logger');

createLogger.configure({
  formatter: JSON.stringify,
  output: console.log,
  transformers: [],
  outputFormat: 'ecs',
  enhancedStackTrace: true
});

```

### 日志级别

-   "肥"(60):"al". 该服务/应用程序现在将停止或无法使用. 接线员应该马上调查一下.
-   ""误"(50): 对特定请求来说是致命的,但服务/应用程序仍在继续 为其他请求提供服务。 接线员应该马上看(ish) .
-   "温"(40): 关于某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某某 最终操作员.
-   "资料"(30): 经常操作的细节.
-   "调试" (20): 其它的,即太动词不能包含在"info"级别.
-   "追踪"(10): 从应用程序使用的外部库登录或 _非常喜欢_ 详细的应用程序记录.

### 自动登录请求标识符

你需要使用中间的软件 `@emartech/cls-adapter` 并将其变压器添加到日志配置方法中. 这样可以登录来自信头字段的请求标识符( E)`X-Request-Id`)到每个日志行 ,而所谓的函数来源于路由处理器.

用于自动化

```javascript
const Koa = require('koa');
const { createLogger } = require('@emartech/json-logger');
const clsAdapter = require('@emartech/cls-adapter');
const logger = createLogger('redis');

createLogger.configure({
  transformers: [
    clsAdapter.addContextStorageToInput()
  ]
});

const app = new Koa();
app.use(clsAdapter.getKoaMiddleware());

app.use(async () => {
  logger.info('connected');
  // Legacy format: {"name":"redis","action":"connected","level":30,"time":"2016-08-15T08:50:23.566Z","request_id":"d5caaa0e-b04e-4d94-bc88-3ed3b62dc94a"}
})
```

## 常见问题

### @emartech/json-logger 是什么？

有命名空间支持的小型和快Json日志

### 如何安装 @emartech/json-logger？

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

### @emartech/json-logger 支持 TypeScript 吗？

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

### @emartech/json-logger 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

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

### @emartech/json-logger 可以商用吗？

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

### @emartech/json-logger 的下载量有多少？

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

### @emartech/json-logger 还在维护吗？

最新版本 9\.2\.5 发布于 2026/06/01（5 个月前）；至今共发布 57 个版本，其中过去 12 个月发布了 5 个；首次发布于 2017/09/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。