# @frontmcp/observability 中文文档

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

版本：1\.12\.2
npm 元数据更新时间：2026-11-14T21:10:03.384Z
中文译文更新时间：2026-11-15T15:18:29.569Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40frontmcp/observability
原文对照：https://npmcn.com/package/%40frontmcp/observability/?lang=original
项目主页：https://frontmcp.dev/reference/server/observability
源码仓库：https://github.com/agentfront/frontmcp

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

- 包体积（解压后）：369 kB，68 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：1 个
- peer 依赖：pino ^8\.0\.0 \|\| ^9\.0\.0，winston ^3\.0\.0，@frontmcp/sdk 1\.12\.2，@frontmcp/utils 1\.12\.2，@opentelemetry/sdk-node ^0\.219\.0，@opentelemetry/sdk-trace-base ^2\.8\.0，@opentelemetry/exporter-trace-otlp-http ^0\.219\.0
- 首次发布：2026-04-05T23:53:10.693Z
- 最新版本发布：2026-11-14T21:10:02.906Z
- 近 30 天下载量：5638（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：84（近 12 个月 84 个）

## 中文简介

OpenTeleometry tracking,结构化的JSON记录,为FrontMCP服务器请求日志和Prometheus格式的度量衡

## 安装

```sh
npm install @frontmcp/observability
```

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

## README

# @ frontmcp/ 可观察性

OpenTeleometry tracking,结构化的JSON日志,每个请求日志对象和FrontMCP服务器的计数器. 打开它 `@FrontMcp({ observability })`:每个请求都得到一个跨度,每个工具调用,资源读取并提示它服务,工具代码不变. 里面还有柜台和普罗米修斯系列器 `/metrics` 结束点 `@FrontMcp({ metrics })` 服务.

[![npm](https://img.shields.io/npm/v/@frontmcp/observability.svg)](https://www.npmjs.com/package/@frontmcp/observability) [![License](https://img.shields.io/npm/l/@frontmcp/observability.svg)](https://github.com/agentfront/frontmcp/blob/main/LICENSE)

## 安装

```bash
npm install @frontmcp/observability
```

要求节点js 24或以后,以及 `@frontmcp/sdk` 在应用程序中(同级依赖,如 `@frontmcp/utils`和SDK一起来的. `@opentelemetry/api` 与软件包一起安装.

可选的同龄人各自可以做到一件事:

| 软件包 | 启用 |
| --- | --- |
| `@opentelemetry/sdk-trace-base` | 印刷跨度在开发中, `setupOTel({ exporter: 'console' })` 财务报告和审定财务报表 `createTestTracer()` |
| `@opentelemetry/sdk-node` | `setupOTel()`,它也需要 `@opentelemetry/resources` 财务报告和审定财务报表 `@opentelemetry/semantic-conventions` |
| `@opentelemetry/exporter-trace-otlp-http` | 向 OpenTeleometry 采集器发送跨度( OpenTeleometry 协议), 例如 `setupOTel({ exporter: 'otlp' })` |
| `pino`, (中文(简体) ), `winston` | 这个 `pino` 财务报告和审定财务报表 `winston` 日志汇,它会写入您创建的日志 |

## 使用量

```ts
import { createCounter, type RequestLog } from '@frontmcp/observability';
import { App, FrontMcp, Tool, ToolContext, z } from '@frontmcp/sdk';

const ticketsClosed = createCounter('helpdesk_tickets_closed_total', 'Tickets closed');

@Tool({ name: 'close_ticket', description: 'Close a support ticket', inputSchema: { id: z.string() } })
class CloseTicket extends ToolContext {
  async execute({ id }: { id: string }) {
    await this.telemetry.withSpan('tickets.close', async (span) => {
      span.setAttribute('ticket.id', id);
    });
    ticketsClosed.inc();
    return { id, status: 'closed' };
  }
}

@App({ id: 'help-desk', name: 'Help Desk', tools: [CloseTicket] })
class HelpDeskApp {}

@FrontMcp({
  info: { name: 'help-desk', version: '1.0.0' },
  apps: [HelpDeskApp],
  observability: {
    tracing: true,
    logging: { sinks: [{ type: 'stdout' }], redactFields: ['password', 'token', 'authorization'] },
    requestLogs: {
      onRequestComplete: (entry) => {
        const log = entry as RequestLog;
        if (log.status === 'error') console.error(log.request_id, log.error);
      },
    },
  },
  metrics: { enabled: true, auth: 'token' }, // GET /metrics, with the bearer token in FRONTMCP_METRICS_TOKEN
})
export default class Server {}
```

-   **西班牙语** 按照每项请求: `POST /` (或你的进入之路),那么 `tools/call`,则 `tool close_ticket`与您的 `tickets.close` 每个出入口的客户端 `this.fetch()`。它们具有MCP属性,例如 `mcp.method.name`, (中文(简体) ), `frontmcp.tool.name` {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}还有一席之地 绝对不会.
-   **日志**: 服务器日志中的每行都会变成一个 JSON 对象, 并带有请求的跟踪和请求的ID, 发送到其中的每个槽 `logging.sinks`。 。 。 .
-   **请求日志**数字 : `onRequestComplete` 每个 HTTP 请求获得一个对象, 包括它的时间, 它叫什么, 它的状况和错误, 以及它所写的日志行 .
-   **计量**数字 : `/metrics` 以普罗米修斯文本格式,或 JSON 格式,为进程测量仪(记忆、CPU、事件启动后差)和每个计数器服务 `format: 'json'`。 。 。 .

`@FrontMcp({ observability: true })` 独自追踪 在没有安装软件包的情况下,一个服务器 `observability` 并记录一个警告; 服务器 `metrics.enabled` 不开始.

### 送去某个地方

插件记录跨越了OpenTeleometter的全局追踪器提供者,FrontMCP不为您注册一个(在开发中它会打印出每个跨度到控制台). 在服务器处理请求前注册一个提供者 . `setupOTel()` 使用 OpenTeleometry 的节点 SDK 进行 :

```ts
import { setupOTel } from '@frontmcp/observability';

const shutdown = setupOTel({ serviceName: 'help-desk', exporter: 'otlp', endpoint: 'http://localhost:4318' });
```

`exporter` 实值 `'console'` (默认)或 `'otlp'`,发送到 `endpoint` 加号 `/v1/traces`。 。 。 . `endpoint` 默认为 `OTEL_EXPORTER_OTLP_ENDPOINT`,则 `http://localhost:4318`,以及 `serviceName` 改为 `OTEL_SERVICE_NAME`,则 `'frontmcp-server'`。调用它返回的函数来冲出并阻止提供者。 登记全球追踪器提供者的任何其他 OpenTeleometry 设置也奏效 .

### 选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `tracing` | `boolean | TracingOptions` | `true` | 请求和电话的传真 `this.telemetry` 工具、资源和提示 |
| `logging` | `boolean | { sinks, redactFields, includeStacks, staticFields }` | `false` | 结构化日志条目,发送给 `sinks`没有 `sinks` (单位:千美元)`logging: true` 包含),在stdout上每行有一个JSON对象(ster over stdio;浏览器中的控制台) |
| `requestLogs` | `boolean | { maxEntries, includeSummaries, onRequestComplete }` | `false` | 每个 HTTP 请求一个对象, 传递到 `onRequestComplete`。 。 。 . `includeSummaries: true` 添加 `input_summary` 财务报告和审定财务报表 `output_summary`: 参数名称、结果密钥、内容类型和大小、永不值 |

`TracingOptions` 打开或关闭组合 : `httpSpans`, (中文(简体) ), `executionSpans`, (中文(简体) ), `fetchSpans`, (中文(简体) ), `transportSpans`, (中文(简体) ), `authSpans`, (中文(简体) ), `oauthSpans`, (中文(简体) ), `elicitationSpans`, (中文(简体) ), `flowStageEvents` 财务报告和审定财务报表 `startupReport` 默认为 `true`,以及 `hookSpans` (每个钩子的跨度,动词)到 `false`。 。 。 . `authSpans` 给每个 HTTP 请求一个 `auth session:verify` 间距,与 `frontmcp.auth.result` (单位:千美元)`authorized`, (中文(简体) ), `anonymous`, (中文(简体) ), `unauthorized`, (中文(简体) ), `forbidden` 或者说 `error`) (中文(简体) ).

木汇是 `{ type: 'stdout', pretty? }` (每行一个JSON对象), `{ type: 'console' }` (可读行), `{ type: 'callback', fn }`, (中文(简体) ), `{ type: 'otlp', endpoint?, headers?, batchSize?, flushIntervalMs?, serviceName? }`, (中文(简体) ), `{ type: 'pino', logger }` 财务报告和审定财务报表 `{ type: 'winston', logger }`。 。 。 .

`@FrontMcp({ observability })` 登记册 `ObservabilityPlugin` 给你的 您可以注册 `ObservabilityPlugin.init(options)` 内 `plugins` 换成你自己,但是 `observability` 并连接 `logging` 汇到服务器的日志器,而插件本身没有。 使用一个或另一个:设置的服务器 `observability` 清单 `ObservabilityPlugin` 内 `@FrontMcp({ plugins })` 启动时失败 `PluginConfiguredTwiceError` (代码) `PLUGIN_CONFIGURED_TWICE`) (中文(简体) ).

## 主要出口

| 导出 | 目的 |
| --- | --- |
| `ObservabilityPlugin` | 这个插件 `observability` 负载 |
| `setupOTel` | 通过 OpenTeleometry 的节点 SDK 注册跟踪提供者 |
| `createCounter`, (中文(简体) ), `getMetricSnapshot`, (中文(简体) ), `getCounterTotal`, (中文(简体) ), `resetMetricSnapshot` | 柜台 `/metrics` (和全局的OpenTeleometer 计数器,如果你注册一个),并在测试中读取 |
| `renderPrometheusExposition(counters, gauges?)`, (中文(简体) ), `renderJsonExposition`, (中文(简体) ), `PROMETHEUS_CONTENT_TYPE` | 串接您自己的端点的反快照 |
| `ProcessStatsCollector` | 进程计数:CPU,内存,上行时间,事件-锁定滞后,活动控件,打开文件描述符 |
| `StructuredLogTransport`, (中文(简体) ), `createSinks`, (中文(简体) ), `StdoutSink`, (中文(简体) ), `ConsoleSink`, (中文(简体) ), `CallbackSink`, (中文(简体) ), `OtlpSink`, (中文(简体) ), `PinoSink`, (中文(简体) ), `WinstonSink` | 结构化伐木构件 |
| `McpAttributes`, (中文(简体) ), `FrontMcpAttributes`, (中文(简体) ), `RpcAttributes`, (中文(简体) ), `HttpAttributes`, (中文(简体) ), `EnduserAttributes` | 扩展属性名称 |
| `FrontMcpPropagator`, (中文(简体) ), `withSpan`, (中文(简体) ), `startSpan`, (中文(简体) ), `startToolSpan`,, , , , , , , , . | 下级跨度助手 |
| `createTestTracer`, (中文(简体) ), `getFinishedSpans`, (中文(简体) ), `assertSpanExists`, (中文(简体) ), `assertSpanAttribute`, (中文(简体) ), `findSpan` | 收集内存的跨度并在测试中检查 |

## 通过 MCP 追踪上下文

关于修改协议 `2026-07-28`,客户端可以发送 `traceparent`, (中文(简体) ), `tracestate` 财务报告和审定财务报表 `baggage` 在请求中 `_meta`,然后FrontMCP复制到结果 `_meta`。为了将服务器的跨度放在客户端的跟踪中,发送W3C `traceparent` HTTP 头版. 见 [协议版本](https://frontmcp.dev/reference/server/protocol-versions)。 。 。 .

## 文档

-   [观测和遥测](https://frontmcp.dev/reference/server/observability)每一个选项,跨度 一个呼叫记录, `this.telemetry`,结构化日志,请求日志和计数器
-   [健康检查和计量](https://frontmcp.dev/reference/deployment/health-and-metrics)数字 : `/metrics`, (中文(简体) ), `/healthz` 财务报告和审定财务报表 `/readyz`与普罗米修斯一起刮去
-   [日志](https://frontmcp.dev/reference/server/logging): 服务器自己的日志, 该日志 `logging` 吸收汇

## 相关软件包

-   [`@frontmcp/sdk`](https://www.npmjs.com/package/@frontmcp/sdk):框架;框架 `observability` 财务报告和审定财务报表 `metrics` 选项装入此软件包
-   [`@frontmcp/testing`](https://www.npmjs.com/package/@frontmcp/testing): FrontMCP 服务器的端到端测试

## 捐款

资料来源: [`libs/observability`](https://github.com/agentfront/frontmcp/tree/main/libs/observability)欢迎提出问题和拉动请求;见 [捐款额](https://github.com/agentfront/frontmcp/blob/main/CONTRIBUTING.md)。 。 。 .

## 许可证

阿帕奇2.0 (英语). 见 [自由主义](https://github.com/agentfront/frontmcp/blob/main/LICENSE)。 。 。 .

## 常见问题

### @frontmcp/observability 是什么？

OpenTeleometry tracking,结构化的JSON记录,为FrontMCP服务器请求日志和Prometheus格式的度量衡

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

在项目目录运行 npm install @frontmcp/observability，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@frontmcp/sdk（1\.12\.2）、@frontmcp/utils（1\.12\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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

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

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