# @axiomhq/logging 中文文档

规范地址：https://npmcn.com/package/%40axiomhq/logging/

版本：0\.4\.1
npm 元数据更新时间：2026-09-09T08:56:39.624Z
中文译文更新时间：2026-11-07T10:53:09.759Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40axiomhq/logging
原文对照：https://npmcn.com/package/%40axiomhq/logging/?lang=original
项目主页：https://github.com/axiomhq/axiom-js/blob/main/packages/logging/README.md
源码仓库：https://github.com/axiomhq/axiom-js

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

- 包体积（解压后）：343 kB，97 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：@axiomhq/js ^1\.0\.0
- 首次发布：2025-02-19T18:52:13.092Z
- 最新版本发布：2026-09-09T08:56:39.254Z
- 近 30 天下载量：838695（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：15（近 12 个月 8 个）

## 中文简介

Axiom 的官方日志包

## 安装

```sh
npm install @axiomhq/logging
```

也可以使用：`pnpm add @axiomhq/logging`、`yarn add @axiomhq/logging`、`bun add @axiomhq/logging`

## README

# Axiom 日志库

这个 `@axiomhq/logging` 软件包允许您从 JavaScript 应用程序中向 Axiom 发送结构化日志.

```ts
// lib/axiom/logger.ts
import axiomClient from '@/lib/axiom/axiom';
import { Logger, ConsoleTransport, AxiomJSTransport } from '@axiomhq/logging';

export const logger = new Logger({
  transports: [
    new AxiomJSTransport({
      axiom: axiomClient,
      dataset: process.env.AXIOM_DATASET!,
      axiomClient: 'my-app/1.0',
    }),
    new ConsoleTransport({ prettyPrint: true }),
  ],
});

logger.info('Hello World!');
```

`AxiomJSTransport` 在 Axiom 客户端的日志包使用中附加 `X-Axiom-Client` 头曰. 以上述实例为例,请求使用 `X-Axiom-Client` 头像 `axiom-js/<version> axiom-logging/<version> my-app/1.0`。 。 。 .

## 代理运输

`ProxyTransport` 用途 `SimpleFetchTransport` 将日志发送到您的 HTTP 端点。 交付是最好的努力:

-   运输机最多保留了1,000个排队活动加上1批最多1,000个飞行活动。 当队列填满时,它会放下最古老的队列事件来保留最近的活动. 机内批次不变. 这些限制约束事件计数,而不是字节或单个事件大小.
-   与 `autoFlush: true`,第一个排队事件启动2秒计时器。 后期的事件不会推迟,当没有批量飞行时,一整队就立即开始发送. `{ durationMs }` 设置不同的延迟。 与 `autoFlush` 省略或删除 `false`时发送 `flush()`。 。 。 .
-   请求一次一个。 网络故障和HTTP 429,500,502,503和504在一秒后最多得到一次重试. 更长的时间 `Retry-After` 很荣幸。 两次尝试和拖延都有一个10秒的最后期限.
-   永久失效, 取消呼叫器, 超时, 或疲劳的重试 放弃批量 。 若为 `Retry-After` 无法在截止日期内装入, 批次不提前重试就被丢弃 。 随后的批次也尊重了服务器的冷却,如果无法在自己的最后期限内等待,则会被丢弃.
-   投产 `console.warn` 包含数的诊断,不包含日志内容。 每次运输最多每30秒发出一次警告;当发生多滴时,在下一次警告中包括被压制的计数.

`flush()` 等待发出或发出该呼吁之前接受的事件。 后期事件不延长该呼叫者的目标,同时发出的呼叫共享序列发件人. 解决的冲水不能保证交货。 丢失响应后重试可以重复服务器已经接受的事件 .

更早的版本保留了失败的批次用于后一冲. 上面的受限重试政策取代了这一行为,因此长时间的停用会导致数据丢失而不会让积压无限期地增加.

## Schema 验证

`Logger` 可以验证和输入日志 `fields` 使用执行标准Schema v1的任何验证符(例如) `zod`) (中文(简体) ).

```ts
import { z } from 'zod';
import { Logger, ConsoleTransport } from '@axiomhq/logging';

const LogFieldsSchema = z
  .object({
    userId: z.string(),
    action: z.enum(['login', 'logout']),
  })
  .strict();

const logger = new Logger({
  transports: [new ConsoleTransport()],
  schema: LogFieldsSchema,
  onValidationError: (context) => {
    console.warn('Dropped invalid log', context.stage, context.reason, context.issues);
  },
});

logger.info('User action', { userId: '123', action: 'login' });
```

运输交付前会丢弃无效的日志 . `schema` 校验输入 `fields` 格式化器运行前,以及 `outputSchema` 能够验证最终格式化的事件 :

```ts
const OutputSchema = z.object({
  eventName: z.string(),
  userId: z.string(),
});

const logger = new Logger({
  transports: [new ConsoleTransport()],
  schema: LogFieldsSchema,
  outputSchema: OutputSchema,
  formatters: [
    (event) => ({
      eventName: event.message,
      userId: event.fields.userId,
    }),
  ],
});
```

未知的密钥行为取决于您的方案配置 :

-   严格的对象计划( 如 `z.object(...).strict()`拒绝未知密钥
-   非限制性计划可能允许

`logger.raw(...)` 绕过计划验证.

## 所需资源

需要20个或以上的节点。 节点.js 18不再支持.

## 安装

```bash
npm install @axiomhq/js @axiomhq/logging
```

## 文档

欲了解如何设置和使用 `@axiomhq/logging` 软件包,参见 [axiom.co/docs/指向/标注](https://axiom.co/docs/guides/javascript)。 。 。 .

## 许可证

[麻省理工学院](https://npmcn.com/package/LICENSE)

## 常见问题

### @axiomhq/logging 是什么？

Axiom 的官方日志包

### 如何安装 @axiomhq/logging？

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

### @axiomhq/logging 支持 TypeScript 吗？

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

### @axiomhq/logging 支持 ESM 还是 CommonJS？

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

### @axiomhq/logging 需要什么版本的 Node\.js？

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

### @axiomhq/logging 可以商用吗？

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

### @axiomhq/logging 的下载量有多少？

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

### @axiomhq/logging 还在维护吗？

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