FastGPT 日志与可观测性审查实践指南：统一 Logger、结构化日志与 OTEL 链路

FastGPT 日志与可观测性审查实践指南：统一 Logger、结构化日志与 OTEL 链路

【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT

FastGPT 作为基于 LLM 的知识库与可视化 AI 工作流编排平台，其服务端承载着知识库训练、向量检索、队列任务、HTTP 请求等大量并发业务，日志的可检索、可聚合与可回放能力直接决定线上排障效率。本文以 FastGPT 仓库中《日志与可观测性审查标准》为骨架，结合@fastgpt/service/common/logger及其底层 OTEL SDK 的真实实现，完整讲解 FastGPT 服务端日志的接入方式、分类体系、结构化规范、等级约定、链路上下文与敏感信息治理，帮助你在开发与代码审查中产出统一、可观测、不泄密的日志代码。

一、统一 Logger 接入：为什么必须使用@fastgpt/service/common/logger

FastGPT 服务端明确要求：统一使用@fastgpt/service/common/logger，禁止散落的console.log。这一约束由 logger/index.ts 的导出定义承载，模块对外暴露四个能力：

export { configureLogger, disposeLogger, getLogger } from './client'; export { withContext, withCategoryPrefix } from '@fastgpt-sdk/otel/logger'; export { LogCategories } from './categories'; export type { LogCategory } from './categories';

1.1 初始化：configureLogger()只应执行一次

启动入口只初始化一次configureLogger()，其实现位于 client.ts：

export async function configureLogger() { const { serviceEnv } = await import('../../env'); await configureLoggerFromEnv({ env: serviceEnv, defaultCategory: ['system'], defaultServiceName: 'fastgpt-client', sensitiveProperties: ['fastgpt'] }); }

这段代码揭示了三个关键约定：

• 默认分类（category）为['system']：未显式指定分类的 logger 会落入 system 分类；
• 默认服务名为fastgpt-client：OTEL 导出时的 service.name 默认值；
• 敏感属性标记为['fastgpt']：凡结构化字段中带fastgpt属性的日志，一律不进入 OTEL 导出链路（详见本文第七节）。

从底层实现看，configureLogger最终调用@fastgpt-sdk/otel/logger的configureLoggerFromEnv（见 sdk/otel/src/logger/env.ts），其内部通过AsyncLocalStorage与@logtape/logtape建立 logger 实例与异步上下文（见 sdk/otel/src/logger/client.ts），这也是后文withContext能实现跨模块上下文传递的基础。

1.2 获取实例：getLogger(LogCategories.XXX)

import { configureLogger, getLogger, LogCategories } from '@fastgpt/service/common/logger'; await configureLogger(); const logger = getLogger(LogCategories.SYSTEM); logger.info('System initialized successfully');

审查标准强调：未经讨论不要自定义 category 字符串数组，即不允许出现getLogger(['custom', 'random'])这类写法，分类必须来自LogCategories枚举。

仓库中的真实接入示例可以佐证这一约定：如 frequencyLimit.ts 使用getLogger(LogCategories.HTTP.RESPONSE)，plusRequest.ts 使用getLogger(LogCategories.HTTP.ERROR)，tracks/processor.ts 使用getLogger(LogCategories.EVENT.TRACK)。业务代码中凡是需要日志，都应遵循"文件顶部统一创建分类 logger、全文件复用"的模式。

二、分类（Category）选择：LogCategories的完整层级

日志分类的价值在于：让日志在采集端可以按维度聚合、过滤与告警。FastGPT 的分类定义集中在 categories.ts，采用五层结构：system（应用层）、infra（基础设施层）、http（HTTP 请求/响应层）、module（业务模块层，参考pages/api路径，省略core/support前缀）、error（错误日志层）与event（事件日志层）。

2.1 应用层（SYSTEM / NETWORK）

SYSTEM: Object.assign(['system'], { UPGRADE: Object.assign(['system', 'upgrade'], { V4163: ['system', 'upgrade', '4163'] }) }), NETWORK: ['system', 'network'],

SYSTEM用于系统级初始化与全局状态；注意UPGRADE.V4163这类带版本号的子分类，说明分类也承担了"版本升级事件追踪"的职责。

2.2 基础设施层（INFRA）

INFRA: { MONGO: ['infra', 'mongo'], POSTGRES: ['infra', 'postgres'], REDIS: ['infra', 'redis'], VECTOR: ['infra', 'vector'], QUEUE: ['infra', 'queue'], S3: ['infra', 's3'], OTEL: ['infra', 'otel'], FILE: ['infra', 'file'], WORKER: ['infra', 'worker'] }

数据库（MongoDB、PostgreSQL、Redis）、向量库、队列、对象存储（S3）、文件与 Worker 等基础设施日志统一归入INFRA.*，方便按存储组件维度排障。真实使用如 tts/schema.ts 与 file/image/schema.ts 均使用LogCategories.INFRA.MONGO。

2.3 HTTP 层与业务模块层

HTTP: { REQUEST: ['http', 'request'], RESPONSE: ['http', 'response'], ERROR: ['http', 'error'] }

HTTP.*用于请求、响应与请求错误。FastGPT 的 HTTP 网关在 http/entry.ts 中正是分别用LogCategories.HTTP.REQUEST与LogCategories.HTTP.RESPONSE创建请求/响应 logger。

业务模块层MODULE.*覆盖了 FastGPT 的核心域：WORKFLOW（含 AI、DATASET、DISPATCH、CODE_SANDBOX 等）、APP（含 EVALUATION、HTTP_TOOLS、MCP_TOOLS、LOGS 等）、DATASET（含 COLLECTION、DATA、TRAINING 及 FILE_PARSE、EMBEDDING、QA、IMAGE_PARSE 等训练子分类）、AI（含 AGENT、TOOL_CALL、LLM、RERANK、SANDBOX 等）、AGENT_SKILLS、USER、WALLET、OUTLINK（含 DINGTALK、FEISHU、WECOM 等）、CHAT（含 FEEDBACK、RECORD、QUOTE 等）、PLUGIN、MCP、OPENAPI等。分类命名与pages/api下的路由结构一一对应，审查时"参考pages/api路径选择 MODULE 分类"即可。

此外还有ERROR: ['error']错误层与EVENT.TRACK: ['event', 'track']事件层（埋点事件日志，见 middle/tracks/processor.ts）。

2.4 缺少分类时的处理

审查标准明确：缺少分类时补充到packages/service/common/logger/categories.ts，而不是在业务代码里内联字符串。categories.ts同时导出了LogCategory类型（见 categories.ts）与moduleCategories常量，新增分类后 TypeScript 会对getLogger的入参做全量类型检查，从编译期杜绝拼写错误。

三、结构化日志与消息规范：短消息 + 结构化字段

审查标准的核心主张是：消息要短、稳定、可检索；关键字段放入结构化对象。

// ✅ 推荐 logger.info('Vector queue task finished', { taskId, durationMs, count }); // ❌ 不推荐 logger.info(`Task finished: ${JSON.stringify({ taskId, durationMs, count })}`);

不推荐写法的问题在于：JSON.stringify会破坏字段的结构化性，导致采集端无法按taskId、durationMs等字段做索引与聚合；同时应避免在消息中包含用户输入或大段文本，防止日志体积膨胀与注入风险。

底层实现为此提供了双重保障。首先，getLogger返回的是一个 Proxy 包装的 logger（见 sdk/otel/src/logger/client.ts），当传入第二个参数为对象时，会自动将消息渲染为消息: {*}占位格式，从而避免对象被误拼入消息文本。其次，OTEL sink 的convertRecordToStructuredBody（见 sdk/otel/src/logger/otel.ts）会逐字段将结构化属性转换为 OTEL 的AnyValue，缺失时回退为structured log占位文本——这保证了结构化字段在 OTEL 侧以独立 key 存在，可直接被日志平台索引。

四、错误日志标准：保留 Error 对象与关键上下文

错误日志的目标是"可回放"，即拿到一条错误日志就能还原失败现场：

try { await doSomething(); } catch (error) { logger.error('Do something failed', { error, teamId, datasetId }); throw error; }

审查要点包含三条：

• 使用error字段记录Error对象，保留堆栈：将 Error 实例作为结构化字段传入，OTEL sink 会序列化其name、message、stack等属性（见 sdk/otel/src/logger/otel.ts 附近的属性转换逻辑），丢失堆栈的错误日志几乎无法定位；
• 包含关键上下文：teamId、datasetId、jobId等业务标识是聚合排障的索引键；
• 捕获后必须记录或向上抛出，避免静默失败：catch块吞掉异常会让错误不可观测，属于审查红线。示例中throw error保留了原始堆栈，同时logger.error已带上上下文。

五、日志等级规范：info / warn / error / debug / trace 的职责边界

审查标准特别强调：高频循环日志必须使用debug/trace，避免大量循环日志污染 info 流。这一约定与 sink 的等级过滤机制相呼应：console sink 默认接收trace及以上全量日志（见 sdk/otel/src/logger/sinks.ts），而 OTEL sink 默认只导出warning及以上（见 sdk/otel/src/logger/env.ts），等级映射通过mapLevelToSeverityNumber（见 sdk/otel/src/logger/helpers.ts）转为 OTelSeverityNumber。因此调试日志默认不会涌入生产 OTEL 链路，开发环境（console 全量）与生产环境（OTEL 只出 warning 以上）天然隔离。

六、请求/任务链路上下文：withContext与 requestId 贯穿

分布式可观测性的关键是链路串联。审查标准给出三个要点：

• HTTP 请求日志应带requestId，优先使用withContext；
• 队列/定时任务日志应带jobId/queueName；
• 跨模块调用尽量保持同一上下文字段名。

return withContext({ requestId }, async () => { logger.info('Request received', { requestId, method, url }); });

withContext由@logtape/logtape基于AsyncLocalStorage实现（见 sdk/otel/src/logger/index.ts 的再导出），其语义是：在withContext回调的整个异步执行链中，logger 都会自动携带requestId上下文，无需在每个调用点手工透传。

FastGPT 的 HTTP 网关是这一模式的示范实现。在 http/entry.ts 中可以看到：网关为每个请求生成randomUUID()作为requestId，写入响应头x-request-id，然后以withContext({ requestId }, ...)包裹整个请求处理，内部使用withActiveSpan（tracerName: 'fastgpt.http'）创建http.request链路 span，并记录http.request.method、http.route、http.request.body.size等属性。请求日志形如：

requestLogger.info(`[${method}] ${url}`, { verbose: false, // 标记非 verbose，简化消息渲染 requestId, method, url, ip, userAgent, contentLength });

由此，一条线上请求可以从x-request-id出发，贯穿网关日志、业务模块日志到下游队列任务，实现全链路回放。

七、敏感信息与 OTEL 导出治理：脱敏、截断与阻断导出

日志泄露 token、密钥、密码或完整对话内容是安全事故，审查标准给出三道防线：

logger.warn('Payload truncated for debug', { fastgpt: true, payloadPreview: payload.slice(0, 200) });

1. 禁止输出敏感内容：token、密钥、密码、完整对话内容一律不得入日志；
2. 必须记录时脱敏或截断：示例中用payload.slice(0, 200)截断，只保留预览；
3. 需要阻止 OTEL 导出时添加fastgpt属性：这是 FastGPT 特有的"逃生舱"机制。

该机制的底层原理在 sink 过滤逻辑中（见 sdk/otel/src/logger/sinks.ts）：

sinks.otel = withFilter( getOpenTelemetrySink({ ... }), (record) => { const properties = record.properties ?? {}; return ( levelFilter(record, otelOptions.level) && !sensitiveProperties.some((property) => property in properties) ); } );

只要结构化属性中带有fastgpt键（由 client.ts 的sensitiveProperties: ['fastgpt']配置），这条日志就只进 console、不进 OTEL 导出——既满足了调试期的可见性，又守住了生产采集链路的红线。

7.1 环境变量开关一览

日志行为完全由环境变量控制（见 sdk/otel/src/logger/env.ts），常用配置如下：

控制台 sink 使用getPrettyFormatter（无图标、缩写等级、自定义时间戳格式、categorySeparator: ':'，见 sdk/otel/src/logger/sinks.ts），产出适合人类阅读的彩色日志；两路 sink 均配置bufferSize: 8192、flushInterval: 5000、nonBlocking: true与lazy: true（见 sinks.ts），即异步非阻塞写入，日志开销不会拖慢业务主链路。

八、审查清单速查

将审查标准浓缩为一条可执行清单，适用于 PR 代码审查与自检：

1. 服务端是否统一使用@fastgpt/service/common/logger，无console.log残留；
2. configureLogger()是否只在启动入口调用一次；
3. getLogger是否始终传LogCategories.XXX，无自定义字符串分类；
4. 消息是否短且稳定，关键字段是否在结构化对象中，无JSON.stringify拼消息；
5. 消息中是否包含用户输入或大段文本（禁止）；
6. 错误日志是否带error字段（保留堆栈）与teamId/datasetId/jobId上下文，无静默失败；
7. 等级选择是否符合"info 阶段、warn 可恢复、error 失败、高频循环用 debug/trace"；
8. HTTP 请求是否带requestId并优先用withContext，队列/定时任务是否带jobId/queueName；
9. 是否杜绝 token、密钥、密码、完整对话内容入日志，必要时截断并加fastgpt: true阻断 OTEL 导出。

结语

FastGPT 的日志体系是一套"规范约束 + 底层设施"双轮驱动的可观测性方案：上层以@fastgpt/service/common/logger与LogCategories统一接入口径，中层以结构化字段、等级约定与withContext保证日志可检索、可聚合、可回放，底层以基于@logtape/logtape与 OTel 的双 sink 架构（console + OTLP）实现异步落盘与采集导出，并以fastgpt敏感属性完成导出阻断。无论你是为 FastGPT 贡献代码的开发者，还是正在做日志代码审查的维护者，遵循本文这套标准，就能让每一条日志都成为可被索引、可被追溯、不泄露机密的可靠观测数据。

【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT