@ frontmcp/ 可观察性
OpenTeleometry tracking,结构化的JSON日志,每个请求日志对象和FrontMCP服务器的计数器. 打开它 @FrontMcp({ observability }):每个请求都得到一个跨度,每个工具调用,资源读取并提示它服务,工具代码不变. 里面还有柜台和普罗米修斯系列器 /metrics 结束点 @FrontMcp({ metrics }) 服务.
安装
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 日志汇,它会写入您创建的日志 |
使用量
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 进行 :
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 头版. 见 协议版本。 。 。 .
文档
- 观测和遥测每一个选项,跨度 一个呼叫记录,
this.telemetry,结构化日志,请求日志和计数器 - 健康检查和计量数字 :
/metrics, (中文(简体) ),/healthz财务报告和审定财务报表/readyz与普罗米修斯一起刮去 - 日志: 服务器自己的日志, 该日志
logging吸收汇
相关软件包
@frontmcp/sdk:框架;框架observability财务报告和审定财务报表metrics选项装入此软件包@frontmcp/testing: FrontMCP 服务器的端到端测试
捐款
资料来源: libs/observability欢迎提出问题和拉动请求;见 捐款额。 。 。 .
许可证
阿帕奇2.0 (英语). 见 自由主义。 。 。 .