GitHub_Trending/ty/typescript-sdk日志与监控：生产环境部署必备指南

舒京涌

306人浏览 · 2025-09-28 01:06:14

舒京涌 · 2025-09-28 01:06:14 发布

GitHub_Trending/ty/typescript-sdk日志与监控：生产环境部署必备指南

【免费下载链接】typescript-sdk The official Typescript SDK for Model Context Protocol servers and clients 项目地址: https://gitcode.com/GitHub_Trending/ty/typescript-sdk

在现代微服务架构中，日志与监控是保障系统稳定性和可观测性的关键环节。GitHub_Trending/ty/typescript-sdk作为Model Context Protocol（MCP）的官方TypeScript SDK，为构建服务器和客户端应用提供了强大支持。本文将详细介绍如何在生产环境中配置和使用该SDK的日志与监控功能，帮助开发和运维人员快速定位问题、优化性能。

日志系统概述

GitHub_Trending/ty/typescript-sdk内置了灵活的日志系统，通过中间件机制实现对HTTP请求和响应的全面跟踪。该系统支持自定义日志格式、级别过滤和第三方日志集成，满足不同生产环境的需求。

核心日志组件

SDK的日志功能主要通过src/client/middleware.ts中的withLogging中间件实现。该中间件提供了以下核心能力：

请求时长跟踪
状态码过滤
请求/响应头记录
错误自动分类
自定义日志处理器集成

// 基础日志配置示例
import { withLogging } from './client/middleware';

const enhancedFetch = withLogging({
  statusLevel: 400, // 仅记录400及以上状态码
  includeRequestHeaders: true,
  includeResponseHeaders: true
})(fetch);

默认日志行为

默认情况下，withLogging使用内置的控制台日志器：

成功请求（2xx状态码）使用console.log输出
错误响应（4xx/5xx状态码）和网络错误使用console.error输出
包含请求方法、URL、状态码和响应时间
不记录请求/响应头信息

注意：默认日志器使用console对象，不建议在stdio传输和应用程序中使用。

高级日志配置

自定义日志处理器

通过实现RequestLogger接口，您可以将日志集成到任何监控系统中：

// 自定义日志处理器示例
import { withLogging, RequestLogger } from './client/middleware';

const customLogger: RequestLogger = (logData) => {
  // 发送日志到集中式日志系统
  fetch('/api/logs', {
    method: 'POST',
    body: JSON.stringify(logData),
    headers: { 'Content-Type': 'application/json' }
  });
  
  // 同时记录到本地文件系统
  fs.appendFileSync('app.log', `${JSON.stringify(logData)}\n`);
};

// 应用自定义日志器
const enhancedFetch = withLogging({
  logger: customLogger,
  statusLevel: 0, // 记录所有请求
  includeRequestHeaders: true
})(fetch);

日志级别控制

使用statusLevel选项可以灵活控制日志粒度：

配置值	行为描述
0	记录所有请求
400	仅记录客户端错误(4xx)和服务器错误(5xx)
500	仅记录服务器错误(5xx)

// 生产环境常用配置：仅记录错误
const errorOnlyLogger = withLogging({ statusLevel: 400 })(fetch);

错误处理机制

SDK提供了全面的错误处理机制，帮助开发者捕获和处理各类异常情况。

错误类型体系

SDK定义了多种特定领域错误类型，位于src/server/auth/errors.ts：

InvalidClientError: 客户端认证失败
InvalidGrantError: 授权令牌无效
UnauthorizedClientError: 客户端未授权

import { InvalidClientError, InvalidGrantError } from './server/auth/errors';

try {
  // SDK操作
} catch (error) {
  if (error instanceof InvalidClientError) {
    // 处理客户端认证错误
    refreshClientCredentials();
  } else if (error instanceof InvalidGrantError) {
    // 处理令牌无效错误
    redirectToLogin();
  }
}

传输层错误处理

不同传输类型提供了特定的错误处理机制：

WebSocket错误处理

src/client/websocket.ts中定义了WebSocket传输的错误处理：

const socket = new WebSocketTransport('wss://api.example.com');

// 监听错误事件
socket.onerror = (error) => {
  console.error('WebSocket错误:', error);
  // 实现重连逻辑
  setTimeout(() => connect(), 5000);
};

SSE错误处理

src/server/sse.ts中的SSE服务器实现了完善的错误处理：

const sseServer = new SSEServer(httpServer);

// 监听传输错误
sseServer.onerror = (error) => {
  console.error('SSE传输错误:', error);
  // 记录错误并通知管理员
  notifyAdmin(`SSE错误: ${error.message}`);
};

监控指标收集

关键性能指标

SDK自动收集以下性能指标，可通过日志系统导出：

请求响应时间（duration）
状态码分布
请求频率
错误率

事件流监控

对于流处理应用，可以监控事件吞吐量和延迟：

import { SSETransport } from './client/sse';

const sse = new SSETransport('https://stream.example.com/events');

let eventCount = 0;
const startTime = Date.now();

sse.on('event', () => {
  eventCount++;
  
  // 每分钟计算吞吐量
  if (Date.now() - startTime > 60000) {
    const throughput = eventCount / 60;
    console.log(`事件吞吐量: ${throughput.toFixed(2)} events/sec`);
    
    // 重置计数器
    eventCount = 0;
    startTime = Date.now();
  }
});

生产环境最佳实践

日志安全考虑

敏感信息过滤：确保日志中不包含敏感信息

// 安全日志处理器示例
const secureLogger: RequestLogger = (logData) => {
  // 过滤敏感头信息
  if (logData.requestHeaders) {
    const safeHeaders = new Headers(logData.requestHeaders);
    safeHeaders.delete('Authorization');
    safeHeaders.delete('Cookie');
    logData.requestHeaders = safeHeaders;
  }
  
  // 发送清理后的日志数据
  sendToLogService(logData);
};

日志聚合策略：使用ELK栈或类似工具集中管理日志

高可用监控配置

// 生产环境日志与认证组合示例
import { applyMiddlewares, withOAuth, withLogging } from './client/middleware';
import { OAuthClientProvider } from './client/auth';

const oauthProvider = new OAuthClientProvider({
  clientId: 'your-client-id',
  clientSecret: process.env.CLIENT_SECRET
});

// 组合认证和日志中间件
const productionFetch = applyMiddlewares(
  withOAuth(oauthProvider),
  withLogging({
    logger: productionLogger,
    statusLevel: 400,
    includeRequestHeaders: true,
    includeResponseHeaders: true
  })
)(fetch);