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/FastGPTFastGPT 作为基于 LLM 的知识库与可视化 AI 工作流编排平台其服务端承载着知识库训练、向量检索、队列任务、HTTP 请求等大量并发业务日志的可检索、可聚合与可回放能力直接决定线上排障效率。本文以 FastGPT 仓库中《日志与可观测性审查标准》为骨架结合fastgpt/service/common/logger及其底层 OTEL SDK 的真实实现完整讲解 FastGPT 服务端日志的接入方式、分类体系、结构化规范、等级约定、链路上下文与敏感信息治理帮助你在开发与代码审查中产出统一、可观测、不泄密的日志代码。一、统一 Logger 接入为什么必须使用fastgpt/service/common/loggerFastGPT 服务端明确要求统一使用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.tsexport async function configureLogger() { const { serviceEnv } await import(../../env); await configureLoggerFromEnv({ env: serviceEnv, defaultCategory: [system], defaultServiceName: fastgpt-client, sensitiveProperties: [fastgpt] }); }这段代码揭示了三个关键约定默认分类category为[system]未显式指定分类的 logger 会落入 system 分类默认服务名为fastgpt-clientOTEL 导出时的 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基础设施层、httpHTTP 请求/响应层、module业务模块层参考pages/api路径省略core/support前缀、error错误日志层与event事件日志层。2.1 应用层SYSTEM / NETWORKSYSTEM: Object.assign([system], { UPGRADE: Object.assign([system, upgrade], { V4163: [system, upgrade, 4163] }) }), NETWORK: [system, network],SYSTEM用于系统级初始化与全局状态注意UPGRADE.V4163这类带版本号的子分类说明分类也承担了版本升级事件追踪的职责。2.2 基础设施层INFRAINFRA: { 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 的职责边界等级用途典型场景info阶段开始/完成logger.info(Training started, { datasetId })debug高频循环/过程细节logger.debug(Training progress, { datasetId, step, total })warn可恢复异常logger.warn(Retrying batch, { batchId, retryLeft })error失败或影响流程的异常logger.error(Training failed, { datasetId, error })审查标准特别强调高频循环日志必须使用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 }, ...)包裹整个请求处理内部使用withActiveSpantracerName: 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) });禁止输出敏感内容token、密钥、密码、完整对话内容一律不得入日志必须记录时脱敏或截断示例中用payload.slice(0, 200)截断只保留预览需要阻止 OTEL 导出时添加fastgpt属性这是 FastGPT 特有的逃生舱机制。该机制的底层原理在 sink 过滤逻辑中见 sdk/otel/src/logger/sinks.tssinks.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常用配置如下环境变量默认值说明LOG_ENABLE_CONSOLEtrue是否输出到控制台LOG_CONSOLE_LEVELtrace控制台输出最低等级LOG_ENABLE_OTELfalse是否启用 OTEL 日志导出LOG_OTEL_LEVELwarningOTEL 导出最低等级LOG_OTEL_SERVICE_NAMEfastgpt-clientOTEL service.nameLOG_OTEL_LOGGER_NAME同 serviceNameOTEL logger 名称LOG_OTEL_URLhttp://localhost:4318/v1/logsOTLP HTTP 日志采集端点控制台 sink 使用getPrettyFormatter无图标、缩写等级、自定义时间戳格式、categorySeparator: :见 sdk/otel/src/logger/sinks.ts产出适合人类阅读的彩色日志两路 sink 均配置bufferSize: 8192、flushInterval: 5000、nonBlocking: true与lazy: true见 sinks.ts即异步非阻塞写入日志开销不会拖慢业务主链路。八、审查清单速查将审查标准浓缩为一条可执行清单适用于 PR 代码审查与自检服务端是否统一使用fastgpt/service/common/logger无console.log残留configureLogger()是否只在启动入口调用一次getLogger是否始终传LogCategories.XXX无自定义字符串分类消息是否短且稳定关键字段是否在结构化对象中无JSON.stringify拼消息消息中是否包含用户输入或大段文本禁止错误日志是否带error字段保留堆栈与teamId/datasetId/jobId上下文无静默失败等级选择是否符合info 阶段、warn 可恢复、error 失败、高频循环用 debug/traceHTTP 请求是否带requestId并优先用withContext队列/定时任务是否带jobId/queueName是否杜绝 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
