# @agentskit/observability 中文文档

规范地址：https://npmcn.com/package/%40agentskit/observability/

版本：0\.13\.1
npm 元数据更新时间：2026-10-24T15:09:50.537Z
中文译文更新时间：2026-11-06T00:58:00.647Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40agentskit/observability
原文对照：https://npmcn.com/package/%40agentskit/observability/?lang=original
项目主页：https://www.agentskit.io/docs/reference/packages/observability
源码仓库：https://github.com/AgentsKit-io/agentskit

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

- 包体积（解压后）：1.2 MB，48 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19
- 运行依赖：2 个
- peer 依赖：pg ^8\.23\.1，langfuse ^3\.38\.20，langsmith ^0\.8\.1，drizzle-orm ^0\.44\.0 \|\| ^0\.45\.3，@opentelemetry/api ^1\.9\.1，@opentelemetry/sdk-trace-base ^2\.9\.0，@opentelemetry/exporter-trace-otlp-http ^0\.220\.0 \|\| ^0\.221\.0
- 首次发布：2026-04-06T14:28:31.200Z
- 最新版本发布：2026-10-24T15:09:50.161Z
- 近 30 天下载量：7630（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：42（近 12 个月 42 个）

## 中文简介

Kit探员的日志和追踪层.

## 安装

```sh
npm install @agentskit/observability
```

也可以使用：`pnpm add @agentskit/observability`、`yarn add @agentskit/observability`、`bun add @agentskit/observability`

## README

# @ agentskit/ 可观察性

简介 : `beta-package`

![AgentsKit](https://raw.githubusercontent.com/AgentsKit-io/agentskit/main/apps/docs-next/public/brand/logo-wordmark.svg)

确切地看你的代理人做什么——每个LLM的呼叫,工具执行,和推理步骤——与你的代理代码零相接.

[![npm version](https://img.shields.io/npm/v/@agentskit/observability?color=blue)](https://www.npmjs.com/package/@agentskit/observability) [![npm downloads](https://img.shields.io/npm/dm/@agentskit/observability)](https://www.npmjs.com/package/@agentskit/observability) [![bundle size](https://img.shields.io/bundlejs/size/@agentskit/observability?label=bundle)](https://bundlejs.com/?q=@agentskit/observability) [![license](https://img.shields.io/badge/license-MIT-blue.svg)](https://npmcn.com/package/LICENSE) [![stability](https://img.shields.io/badge/stability-beta-yellow)](https://npmcn.com/package/docs/STABILITY.md) [![GitHub stars](https://img.shields.io/github/stars/AgentsKit-io/agentskit?style=social)](https://github.com/AgentsKit-io/agentskit)

**标记 :** `ai` • 妇女 `agents` • 妇女 `llm` • 妇女 `agentskit` • 妇女 `ai-agents` • 妇女 `observability` • 妇女 `tracing` • 妇女 `opentelemetry` • 妇女 `langsmith` • 妇女 `logging` • 妇女 `monitoring`

## 已核实的证据

-   软件包元数据和测试在 `packages/observability/`。 。 。 .
-   软件包指南 : [https://www.agentskit.io/docs/参考文献/packages/可观察性](https://www.agentskit.io/docs/reference/packages/observability)
-   稳定地图: [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)

## 如何适应生态系统

@agentskit/可观察性使得代理行为可以检查有痕迹,成本,审计日志,devtools,以及生产遥测钩.

-   **探员Kit**:与本回购中的其他包一起作曲,从可互换的小零件来构建代理.
-   **书记官处**: 查找已使用此图层的即时代理和模板 [登记. agentskit.io](https://registry.agentskit.io/)。 。 。 .
-   **游戏本**: 学习本层背后的生产模式 [游戏本. agentskit.io](https://playbook.agentskit.io/)。 。 。 .

文档 : [软件包指南](https://www.agentskit.io/docs/reference/packages/observability) • 妇女 [代理交接](https://github.com/AgentsKit-io/agentskit/blob/main/llms.txt)

## 为什么观察

-   **分钟内调试, 不计时** ——追踪全ReAct循环:哪些工具被叫来,LLM收到什么,哪里出错,都在一个地方
-   **用您已有的跟踪堆栈工作** – LangSmith, OpenTelemotry (OTLP), 或简单的控制台记录器; 观察者只是 `{ name, on(event) }` 对象
-   **没有接合,没有锁** - 附属于 `AgentEvent` 运行时间的排放; 删除它和您的代理代码不变
-   **设计非阻塞** − 观察者的错误从未浮出物剂;生产稳定性没有危险

## 安装

```bash
npm install @agentskit/observability
```

## 快速实例

```ts
import { createRuntime } from '@agentskit/runtime'
import { anthropic } from '@agentskit/adapters'
import { consoleLogger, langsmith } from '@agentskit/observability'

const runtime = createRuntime({
  adapter: anthropic({ apiKey: process.env.ANTHROPIC_API_KEY, model: 'claude-sonnet-4-6' }),
  observers: [
    consoleLogger({ format: 'human' }),
    langsmith({ apiKey: process.env.LANGSMITH_API_KEY }),
  ],
})

const result = await runtime.run('Analyze sales data in ./data/sales.csv')
console.log(result.content)
// Every step is now logged and traced automatically
```

## 计数

`@agentskit/observability` 包括一个零依赖指数计算API——用于上下文窗口预算检查,成本估算和消息剪切.

### 快速近似数

```ts
import { countTokens, approximateCounter } from '@agentskit/observability'

// async convenience function
const total = await countTokens(messages)
if (total > 120_000) trimOldMessages(messages)

// synchronous via counter directly
const syncTotal = approximateCounter.count(messages)
```

使用 `chars / 4 + 4 per message` 热心. 略为高估——有意为预算卫士.

### 按信息分列的数据

```ts
import { countTokensDetailed } from '@agentskit/observability'

const { total, perMessage } = await countTokensDetailed(messages)
// total      → number
// perMessage → number[]  (one entry per message, same order)
```

### 精确的计数器

```ts
import { createProviderCounter, countTokens } from '@agentskit/observability'
import { encoding_for_model } from 'tiktoken'

const enc = encoding_for_model('gpt-4o')
const tiktokenCounter = createProviderCounter({
  name: 'tiktoken',
  tokenize: (text) => [...enc.encode(text)],
})

const exact = await countTokens(messages, { counter: tiktokenCounter, model: 'gpt-4o' })
```

`createProviderCounter` 覆盖任意 `tokenize(text, model?)` 函数 a `TokenCounter` 符合核心合同并支持 `countDetailed` 自动.

## 特征

-   `consoleLogger({ format })` 本地 dev 的漂亮打印或 JSON 结构日志
-   `langsmith({ apiKey })` - LangSmith生命周期观察员(可选) `langsmith` 端点)
-   `opentelemetry(config)` ——OTLP寿命周期观察器(可选的开放遥测同位素)
-   `datadogSink` 编号 : `axiomSink` 编号 : `newRelicSink` - HTTP生命周期汇,有管理的分批处理
-   费用警卫 - `costGuard`, (中文(简体) ), `multiTenantCostGuard`, (中文(简体) ), `createAdvancedCostGuard`
-   `approximateCounter` 零分同步符号计数器(`chars/4` 高压)
-   `countTokens` 编号 : `countTokensDetailed` 使用可选的自定义计数器计数符号
-   `createProviderCounter` - 工厂将tiktoken或任何装饰剂包装在 `TokenCounter` 合同
-   观察界面 : `{ name: string, on(event: AgentEvent): void }` - 在几分钟内写自定义观察者
-   通过附件 `observers` 阵列在 `createRuntime` ——代理逻辑零变化

## 生产生命周期(水槽+SDK桥)

Datadog, Axiom, 新遗迹, LangSmith, 和 OpenTeleometry 工厂返回 **生命周期观察员**数字 :

```ts
type LifecycleObserver = Observer & {
  flush(): Promise<void>
  shutdown(): Promise<void> // idempotent
}
```

HTTP汇分享有限度、最有效出口(不是交货担保):

| 选项 | 默认 | 作用 |
| --- | --- | --- |
| `batchSize` | `25` | 最大事件/ POST |
| `maxQueueSize` | `1000` | 硬队盖; **丢出最老的** 满分时 |
| `flushIntervalMs` | `2000` | 定期排水量 |
| `maxRetries` | `3` | 初始尝试后重复 |
| `retryBaseDelayMs` | `100` | 全速指数后退基数,上限为30s |
| `requestTimeoutMs` | `10000` | 按请求暂停 |
| `onError` | —— 说 | 孤立错误槽( 扔出/ 拒绝 永远无法逃脱) `on`(中文(简体) ) |

HTTP 汇重试网络错误和状态响应 `408`, (中文(简体) ), `429`,或 `5xx`。 。 。 . 一个有效的 `Retry-After` 三角秒或 HTTP- date 是最小的延迟; 每个等待是 30岁时封顶 缺少或无效头头使用全快指数回放.

击打是 **单机**。可选的 SDK 同伴会懒散地解析; 软件包拥有其构造的 SDK 的冲/冲。 在优雅的程序或要求终止期间, **等待时 `shutdown()`** 因此,飞行中 批量有排出的机会。 过度流量在压力下仍然下降得最久——计划能力和 `onError` 相应监测.

## 费用警卫

```ts
import {
  costGuard,
  multiTenantCostGuard,
  createAdvancedCostGuard,
} from '@agentskit/observability'

const controller = new AbortController()
const guard = costGuard({
  budgetUsd: 0.10,
  controller,
  // prices: { 'gpt-4o': { input: …, output: … } }, // override DEFAULT_PRICES
})

// Advanced modes
const advanced = createAdvancedCostGuard({
  budgets: { tenantA: 1 },
  mode: 'reject', // 'warn' | 'reject' | 'kill'
  // mode 'kill' requires disableRuntime(tenant, reason)
})
advanced.setTenant('tenantA')
// Host enforcement for reject:
if (advanced.isRejected('tenantA')) {
  // reject the request / stop scheduling work
}
```

语义( 当前硬化行):

-   **递增会计** ——每个 `llm:end` 使用 **活动模式** 为了那个事件 当模型改变时,历史符号永远不会被重新定价. 总计保持累积.
-   **敌对用途** —— 说 `NaN` 编号 : `Infinity` / 立即或完成数为负数 `0` 永远不要毒药成本,状态,或JSON有效载荷.
-   **零预算** ——首次正支出超过;利用率和回调保持有限(sentinel) `1` 当预算是 `0` 施舍是正的.
-   **隔离** —— 说 `onCost` 编号 : `onExceeded` /警报汇/ `disableRuntime` 编号 : `tenantOf` 编号 : `now` 失败被隔离; 可选 `onError` 报告他们没有 手无寸铁的拒绝.
-   **模式** —— 说 `warn` 仅观察; `reject` 由 **东道方咨询 `isRejected(tenant)`** (窗被卷起时,窗被拒绝;全被拒绝,直到 `reset`(三); `kill` 持续呼叫 `disableRuntime` 并揭露 `isDisabled` (如果禁用失败则无法关闭) .
-   **`DEFAULT_PRICES`** 是一个基线快照,方便. **覆盖 `prices` 目前供应商费率** ——表号不是稳定合同. 守卫默认在未知型号上无法关闭;简单的守卫会中止其控制器,而多租户/高级守卫则根据其模式报告或屏蔽. 设定 `unknownModelPolicy: 'allow-zero'` 仅用于明确自由/本地模式.

简单 `costGuard` 通过所供应的终止 `AbortController` 当运行预算超过时( 标记 + 在潜在敌意之前中止) `onExceeded`) (中文(简体) ). 多租户和高级警卫不默认中止运行时间.

### 长期预算 `CostStore`

一个没有商店的守护者会保持其总计在进程内存中:它们在重启时重设,并且不会在实例或隔离之间共享. 这在开发上是好的,在没有服务器或多功能主机上是错误的,所以当没有设置商店时,警卫警告过一次 `NODE_ENV=production`,或者在云旗工人时 `NODE_ENV` 未设置。 过 `warnWithoutStore: true` 或者说 `false` 自己决定.

`CostStore` 是持久端口. `reserve` 持有对租户上限的估算, `commit` 把它取而代之的是真正的支出 并写出使用分类账, `release` 当呼叫失败时返回,并且 `window` 读取当前状态。 四人都拿房客身份证; `reserve`, (中文(简体) ), `commit` 财务报告和审定财务报表 `release` 以偶数计 `reservationId`。 。 。 .

```ts
import { Pool } from 'pg'
import { drizzle } from 'drizzle-orm/node-postgres'
import { multiTenantCostGuard } from '@agentskit/observability'
import { postgresCostMigrationSql, postgresCostStore } from '@agentskit/observability/postgres'

const pool = new Pool({ connectionString: process.env.DATABASE_URL })
await pool.query(postgresCostMigrationSql) // once, from your migration step
const store = postgresCostStore({ db: drizzle(pool) })

// Gate a request before calling the model.
const reserved = await store.reserve({ tenant, reservationId: turnId, amountUsd: 0.02, capUsd: planCapUsd })
if (!reserved.ok) return new Response('quota exceeded', { status: 402 })
try {
  const usage = await runTurn()
  await store.commit({ tenant, reservationId: turnId, actualUsd: usage.costUsd, usage: usage.calls })
} catch (error) {
  await store.release({ tenant, reservationId: turnId })
  throw error
}

// Or let a guard record every priced call and trip on the shared total.
const guard = multiTenantCostGuard({ budgets: { [tenant]: planCapUsd }, store })
```

-   **原子盖.** PostgreSQL商店在一份声明中承认保留(`reserved + spent + amount <= cap`)),因此并行请求不能将盖相加过度. 盖子是一个论点 `reserve`:从你的计划或应享权利表读取.
-   **会计窗口.** 支出按 `windowKey`,默认为世界协调时的月份(`2026-10`) (中文(简体) ). 过 `windowKey` 到存储选项或每个调用另一个时段。 有商店,警卫的预算适用于目前的窗口.
-   **真正的支出赢了.** `commit` 记录 `actualUsd` 即使它高于预估。 如果绝对不能通过上限, 则保留一个上限.
-   **后卫录事.** 一个警卫写每个价钱 `llm:end` 到商店和旅行 当存储总量通过预算。 为了在开销前阻止一个请求 打电话 `reserve` 和上面一样.
-   **连接寿命是你的.** 在节点上用个游泳池. 关于工人,创建 `pg` 客户端或每个请求的一个小池并关闭其中 `waitUntil`。 。 。 . `drizzle-orm` 财务报告和审定财务报表 `pg` 是可选的同伴,仅供 `/postgres` 子路径.
-   **一个释放的ID保持释放.** `reserve` 被解除的保留的编号 `AK_COST_RESERVATION_RELEASED` 而不是报告为承认。 使用新代号重试一个呼叫 .
-   **被废弃的保留.** 从未承诺或释放的保留(一个崩溃的过程)保持其数量;商店没有背景收割者。 时间表 `expirePostgresCostReservations({ db, olderThan })` 比起你最慢的电话 截断时间更长 `new Date(Date.now() - 60 * 60_000)`。 。 。 .
-   **存储失败 .** 当商店倒闭时 警卫从不逃跑 它把错误报告给 `onError`; 无 `onError` 它记录了第一个失败的警告。 设定 `onError` 所以一个停止录音的商店是可见的.
-   **匹配错误 `code`。 。 。 .** 在 CommonJS 中,每个子路径都捆绑自己的副本 `CostReservationError`这样 `instanceof` 失败 `require('@agentskit/observability')` 财务报告和审定财务报表 `require('@agentskit/observability/postgres')`比较 `error.code`。 。 。 .
-   **交易.** 打电话 `reserve` 在您自己的交易之外,或在保存点内。 当两个调用一个预留ID的比赛时,商店会吸收失败者的独特违规,但PostgreSQL已经中止了附加交易.
-   **你自己的店铺.** 执行 `CostStore` 翻过桌子跑 `costStoreContract` 从 `@agentskit/observability/cost-store-contract` 在你的测试室. `createInMemoryCostStore()` 是开发和测试的实施.

## 生态系统

| 软件包 | 作用 |
| --- | --- |
| [@ agentskit/ 运行时间](https://www.npmjs.com/package/@agentskit/runtime) | 说明追踪步骤 |
| [@ agentskit/ 核心](https://www.npmjs.com/package/@agentskit/core) | `AgentEvent` 流线 |
| [@ agentskit/ eval (英语)](https://www.npmjs.com/package/@agentskit/eval) | 质量门与痕迹 |

## 贡献者

[![AgentsKit contributors](https://contrib.rocks/image?repo=AgentsKit-io/agentskit)](https://github.com/AgentsKit-io/agentskit/graphs/contributors)

## 许可证

麻省理工学院——见 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 文档

[完整文档](https://www.agentskit.io/) • 妇女 [GitHub 图像](https://github.com/AgentsKit-io/agentskit)

## 成熟性和相容性

-   稳定性: **β 语录** 看到了吗 [文件/服务.md](https://npmcn.com/package/docs/STABILITY.md)
-   **节点.js 20+** 财务报告和审定财务报表 **类型脚本** 严格模式
-   发表于 `@agentskit/observability`

## 捐款

见 [捐款额](https://npmcn.com/package/CONTRIBUTING.md) 单曲 [自由主义](https://npmcn.com/package/LICENSE)。 。 。 .

## 常见问题

### @agentskit/observability 是什么？

Kit探员的日志和追踪层\.

### 如何安装 @agentskit/observability？

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

### @agentskit/observability 支持 TypeScript 吗？

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

### @agentskit/observability 支持 ESM 还是 CommonJS？

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

### @agentskit/observability 需要什么版本的 Node\.js？

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

### @agentskit/observability 可以商用吗？

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

### @agentskit/observability 的下载量有多少？

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

### @agentskit/observability 还在维护吗？

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