# @egeria-systems/observability 中文文档

规范地址：https://npmcn.com/package/%40egeria-systems/observability/

版本：0\.3\.0
npm 元数据更新时间：2026-08-13T18:44:28.909Z
中文译文更新时间：2026-11-13T09:59:54.388Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40egeria-systems/observability
原文对照：https://npmcn.com/package/%40egeria-systems/observability/?lang=original
源码仓库：https://github.com/Egeria-Systems/egeria-scaffold

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

- 包体积（解压后）：88.2 kB，21 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-08-06T22:10:50.067Z
- 最新版本发布：2026-08-13T18:44:28.330Z
- 近 30 天下载量：4851（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

暂无中文简介

## 安装

```sh
npm install @egeria-systems/observability
```

也可以使用：`pnpm add @egeria-systems/observability`、`yarn add @egeria-systems/observability`、`bun add @egeria-systems/observability`

## README

# @egeria-systems/可观察性

设定业务事件和限制误诊合同,为生成的应用程序注入交货界限.

该软件包具有零运行时间依赖性. 它不导入框架,平台SDK,浏览器API,或Node.js runtime API. 应用程序注入时钟,结构化的日志编写器,HTTP请求,以及浏览器发送器的构成根.

## API 表面

-   `@egeria-systems/observability` 创建不可变的策略 `2.0.0` 允许列出事件和有界限的错误报告. `OperationalSink` 仅接收安全事件; `DiagnosticSink` 明确选择限制性诊断。 两种调度路径都含有遥测故障.
-   `@egeria-systems/observability/server` 提供注射式结构-对象记录,加上明显的安全和受限制的更好的Stack HTTP适配器。 精确的 HTTP `202` 这是唯一的成功状态.
-   `@egeria-systems/observability/browser` 发出不同的方案 `2.0.0` `operational-event` 财务报告和审定财务报表 `error-report` 信封 信封 信封 错误报告被确定为最多为8 192 UTF-8字节,并使用注入式同源运输.
-   `@egeria-systems/observability/testing` 提供安全和诊断的内存汇,并作出内容安全的断言.

```ts
import {
  createOperationalEvent,
  dispatchOperationalEvent,
} from "@egeria-systems/observability";
import { createMemorySink } from "@egeria-systems/observability/testing";

const created = createOperationalEvent(
  {
    name: "example.application.ready",
    kind: "application.lifecycle",
    runtime: "server",
    severity: "info",
    context: {
      eventId: "example-event",
      correlationId: "example-operation",
      service: "web",
    },
  },
  { clock: { now: () => new Date() } },
);

if (created.ok) {
  const memory = createMemorySink();
  await dispatchOperationalEvent(created.value, [memory.sink]);
}
```

意外错误使用单独的报告和汇合同 :

```ts
import {
  createOperationalErrorReport,
  createOperationalEvent,
  dispatchOperationalErrorReport,
} from "@egeria-systems/observability";

const errorEvent = createOperationalEvent(
  {
    name: "example.application.error",
    kind: "application.error",
    runtime: "server",
    severity: "error",
    context: { eventId: "example-error", service: "web" },
    errorCategory: "unexpected",
  },
  { clock: { now: () => new Date() } },
);
const report = errorEvent.ok
  ? createOperationalErrorReport(
      errorEvent.value,
      new Error("example failure"),
      { mechanism: "selected-catch", handled: true },
      {},
    )
  : undefined;

if (report?.ok) {
  await dispatchOperationalErrorReport(report.value, {
    operationalSinks: [workersLogsSink],
    diagnosticSinks: [approvedDiagnosticSink],
  });
}
```

示例汇变量是应用程序自有的注入边界. 软件包没有发现提供者或证书.

## 隐私和失败合同

事件名称,上下文符号,和字符串属性使用受约束的符号词汇. 属性是平面平面平面的数值,只能通过明确的允许列表被接受. 被禁的私人数据密钥,不安全的字符串,嵌入值,非无限数字,原始错误,消息,堆栈,原因,请求数据,任意对象都被排除在安全事件分级之外.

错误报告只读取已知的类似错误的字段 。 他们将消息绑定到2,048个UTF-8字节,堆叠到16,384个UTF-8字节和64行,导致两个链接,并取代了常见的秘密,证书,令牌,电子邮件,IP,URL-detail,以及绝对路径形状. 这些报告是有限的业务数据。 基于Regex的校正可以减少明显的暴露,但并不是隐私保障. 供应商的准入、区域、保留、删除和操作者处理需要单独的审查和认证.

Better Stack 边界只接受验证 `betterstackdata.com` 摄取主机和有限制的服务器持有的无记名符号。 它从不暴露配置,提供者的响应内容,请求有效载荷,或者将出错的内容扔入结果. 顶级诊断记录使用点化提供者密钥;其 `exception.cause` 值保留了递归 `ExceptionDiagnostics` 有骆驼的线形 `exceptionType` 财务报告和审定财务报表 `exceptionStacktrace`当同一经核准的“更好堆栈”标识器收到内容丰富的诊断报告时,安全错误的交付就会被抑制,从而避免重复的提供者记录。 浏览器表面没有提供者的令牌,存储,回放,行为捕捉,分析,或控制台截取.

每个水槽都返回一个限定的交付类别. 调度器尝试每个槽并包含抛出,拒绝,或错误的结果,因此可观察性不能成为应用程序失败路径.

分析仍然是一个独立的能力。 导入此软件包后, Cloudflare Web Analytics 或其他访问者- 分析提供者将无法使用 。 犬类所有权边界记录在 [软件包所有权](https://npmcn.com/package/docs/architecture/package-ownership.md)。 。 。 .

## 兼容性和释放状态

源候选人从 schema 中推进事件和浏览器信封 `1.0.0` 改为 `2.0.0`时,需要 `eventId` 财务报告和审定财务报表 `service`,并制作 `correlationId` 选项。 其表现为: `0.3.0` 发布候选人, 且与已公布的不相容 `0.2.0` 合同。 版本实事求是并不授权出版;现场登记验证,准确的终极核准,整合,推倒,出版仍然是单独的出入口.

运行 `pnpm run verify` 在此软件包中构建声明和 JavaScript, 插入严格的源, 运行行为测试, 以及类型检查软件包 .

## 来源和执照

软件包来源是 [`packages/observability`](https://github.com/Egeria-Systems/egeria-scaffold/tree/main/packages/observability)。它根据 [阿帕奇 - 2.0](https://npmcn.com/package/%40egeria-systems/observability/LICENSE)。 。 。 .

## 常见问题

### 如何安装 @egeria-systems/observability？

在项目目录运行 npm install @egeria-systems/observability，或使用 pnpm add / yarn add / bun add。

### @egeria-systems/observability 支持 TypeScript 吗？

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

### @egeria-systems/observability 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @egeria-systems/observability 可以商用吗？

@egeria-systems/observability 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @egeria-systems/observability 的下载量有多少？

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

### @egeria-systems/observability 还在维护吗？

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