# @chax-at/log-sink 中文文档

规范地址：https://npmcn.com/package/%40chax-at/log-sink/

版本：2\.0\.2
npm 元数据更新时间：2025-09-24T11:13:26.508Z
中文译文更新时间：2026-11-09T11:56:32.782Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40chax-at/log-sink
原文对照：https://npmcn.com/package/%40chax-at/log-sink/?lang=original

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

- 包体积（解压后）：44.1 kB，29 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2022-02-10T10:54:24.733Z
- 最新版本发布：2025-08-29T13:10:26.133Z
- 近 30 天下载量：3641（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 0 个）

## 中文简介

日志服务

## 安装

```sh
npm install @chax-at/log-sink
```

也可以使用：`pnpm add @chax-at/log-sink`、`yarn add @chax-at/log-sink`、`bun add @chax-at/log-sink`

## README

# 日志链接

LogSink是一个简单的日志包,允许将日志发送到多个目的地. 这些目的地被称为"地道".

## 使用量

软件包提供了LogSink作为默认导出的一个单通实例:

```typescript
import LogSink from '@chax-at/log-sink';
```

在使用 LogSink 实例前, 必须配置至少一个排出 :

```typescript
LogSink.registerDrain(new ConsoleLogDrain(), {
    enabled: true,
    minLevel: LOGGING_CONSOLE_MINLEVEL,
    maxLevel: LOGGING_CONSOLE_MAXLEVEL,
});
```

单子实例可以导入到任何文件中并用于日志:

```typescript
import LogSink from '@chax-at/log-sink';

LogSink.info('This is an info message');
```

### 日志级别

LogSink 只区分了四个日志级别 . 这比其他伐木解决方案要少,但是为了更清楚地说明何时使用每个关卡. 每个关卡的数值都符合syslog标准.

| 职等 | 数字 | 说明 |
| --- | --- | --- |
| 错误 | 3个 | 发生了错误 。 将引发警报。 (取决于排水量) |
| 警告 | 页:1 | 一个警告信息。 将不会触发警报,但可以在仪表板上看到. |
| 资讯 | 6个 | 信息信息,可见于生产日志. |
| 调试 | 第7条 | 调试消息,一般在生产环境中被过滤出. |

在例外也用于非服务器出错的项目中,例如象征性过期的例外, 每种例外情况都应与适当的错误级别相挂钩。 也就是说,

-   `token expired` 将会是调试消息
-   `validation failed` 这将是一个警告信息
-   `PDF generation failed` 将是一个错误消息

```typescript
LogSink.error('This is an error message');
LogSink.warning('This is a warning message');
LogSink.info('This is an info message');
LogSink.debug('This is a debug message');           // Level 7
```

### 标记、属性和时间戳

除了一个消息外,这些方法中的每一个都采用可选标记,属性对象和时间戳:

```typescript
enum LogTags {
    Database = 'database',
}

LogSink.info('This is an info message', LogTags.Database, {attr1: 'value1', attr2: 'value2'}, new Date());
```

如果在编译时未知日志级别,则 `log` 可使用下列方法:

```typescript
LogSink.log(LogLevel.Info, 'This is an info message');
```

如果需要,您可以创建额外的 LogSink 实例 :

```typescript
import {LogSink} from '@chax-at/log-sink';

const logSink = new LogSink();
```

## 排水沟

该套装提供了两个内置排水道: `ConsoleLogDrain` 财务报告和审定财务报表 `GelfLogDrain`。 。 。 . 通过执行《公约》可增加新的排水量 `ILogDrain` 接口.

排水管使用 `registerDrain` 方法. 使用 `minLevel` 财务报告和审定财务报表 `maxLevel`,在每条排水管上,可以过滤出重度水平. 此外,可以使用该图过滤日志 `filter` 方法并使用 `transform` 方法.

```typescript
LogSink.registerDrain(new ConsoleLogDrain(), {
    enabled: true,
    minLevel: LOGGING_CONSOLE_MINLEVEL,
    maxLevel: LOGGING_CONSOLE_MAXLEVEL,
    filter: (options: LogOptions) => {
        return options.tag === LogTags.Database;
    },
    transform: (options: LogOptions) => {
        return {
            ...options,
            message: options.message.toUpperCase(),
        };
    },
});
```

### 控制台LogDrain

这个 `ConsoleLogDrain` 日志信件到控制台。 可以被配置为日志属性并使用颜色.

```typescript
new ConsoleLogDrain({logAttributes: true, useColor: true});
```

### 盖尔夫·洛格德莱恩

这个 `GelfLogDrain` 将信件日志到任何 GELF 功能服务器, 如 Graylog . 用这个 [@chax-at/gelf-客户端](https://www.npmjs.com/package/@chax-at/gelf-client) 在引擎盖下.

```typescript
new GelfLogDrain(new SecureTCPTransport({
    host: GELF_HOST,
    port: GELF_PORT,
    ca: GELF_SERVER_CA_CERT, // CA certificate string or buffer
    cert: GELF_CLIENT_CERT,  // Client certificate string or buffer
    key: GELF_CLIENT_KEY,    // CLient key string or buffer
}));

new GelfLogDrain(new TCPTransport({
    host: GELF_HOST,
    port: GELF_PORT,
}));

new GelfLogDrain(new UDPTransport({
    host: GELF_HOST,
    port: GELF_PORT,
    timeout: GELF_TIMEOUT,   // optional timeout (default 1000ms)
    protocol: GELF_PROTOCOL, // udp4 (default) or udp6
}));
```

### 文件系统LogDrain

这个 `FilesystemLogDrain` 将信件日志到文件系统中的文件.

```typescript
new FilesystemLogDrain({
    fileName? : string; // optional filename (default log.txt)
    formatFunction? : LogFormatFunction; // optional formatting function for the logged message
    indentation? : number; // optional indentation for nested newlines (default 4)
    logAttributes? : boolean; // whether to log embedded attributes (default true)
    outDir: string; // the path of the directory the log file will be created
    separateWithEmptyLine? : boolean; // whether to add an additional newline after each log message to improve readability (default false)
});
```

### 打开遥测LogDrain

这个 `OpenTelemetryLogDrain` 通过 OpenTeleometry 日志消息.

首先,在您的工程中安装必要的软件包 :

```bash
npm i "@opentelemetry/sdk-node" "@opentelemetry/api" "@opentelemetry/sdk-logs" "@opentelemetry/exporter-logs-otlp-proto"
```

然后用如下方式使用

```typescript
import {NodeSDK} from "@opentelemetry/sdk-node";
import {SimpleLogRecordProcessor} from "@opentelemetry/sdk-logs";
import {logs} from '@opentelemetry/api-logs';
import {OTLPLogExporter} from "@opentelemetry/exporter-logs-otlp-proto";

import LogSink, {LogLevel, OpenTelemetryLogDrain} from '@chax-at/log-sink';

const exporter = new OTLPLogExporter({
    //url: defaults to 'http://localhost:4318/v1/logs',
});

const sdk = new NodeSDK({
    logRecordProcessor: new SimpleLogRecordProcessor(exporter),
});
sdk.start();

const logger = logs.getLoggerProvider().getLogger("default");
LogSink.registerDrain(new OpenTelemetryLogDrain(logger), {
    enabled: true,
    minLevel: LogLevel.Error,
    maxLevel: LogLevel.Debug
});

LogSink.info("This is a log");
```

更多信息可在 [打开远程信息](https://npmcn.com/package/%40chax-at/log-sink/docs/otel.md) 或正式的开远文件.

## 常见问题

### @chax-at/log-sink 是什么？

日志服务

### 如何安装 @chax-at/log-sink？

在项目目录运行 npm install @chax-at/log-sink，或使用 pnpm add / yarn add / bun add。

### @chax-at/log-sink 支持 TypeScript 吗？

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

### @chax-at/log-sink 支持 ESM 还是 CommonJS？

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

### @chax-at/log-sink 可以商用吗？

@chax-at/log-sink 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @chax-at/log-sink 的下载量有多少？

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

### @chax-at/log-sink 还在维护吗？

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