FastGPT 统一可观测性 SDK 实战用 fastgpt-sdk/otel 一站式接入 OpenTelemetry 日志、指标与链路追踪【免费下载链接】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 仓库中统一的可观测性 SDK——fastgpt-sdk/otel位于 sdk/otel/README.md。该包的目标是把分散的fastgpt-sdk/logger、fastgpt-sdk/metrics与 tracing 能力收拢到单一入口同时提供“统一入口”和“渐进迁移入口”两种用法。读完本文你将掌握其环境变量体系、日志结构化输出与安全归一化规则、指标与采样的底层实现以及如何像 FastGPT service 层那样用它接入 OpenTelemetry Collector / OTLP 后端。一、定位为什么需要一个统一的可观测性 SDK从源码看fastgpt-sdk/otel是一个自包含self-contained包内部自带 logger 实现、metrics 实现与 tracing 实现不依赖fastgpt-sdk/logger或fastgpt-sdk/metrics三者可独立工作它的定位是“整理好的统一入口”而不是“已经迁移完成的替换方案”——现有 logger 与 metrics 包仍然可以继续独立使用后续再逐步迁移。它对外提供四类能力能力说明统一入口渐进迁移入口日志基于 LogTape 的 loggerfastgpt-sdk/otelfastgpt-sdk/otel/logger指标OpenTelemetry Metricsfastgpt-sdk/otelfastgpt-sdk/otel/metrics链路追踪OpenTelemetry Tracingfastgpt-sdk/otelfastgpt-sdk/otel/tracing初始化统一的configureOtel()/configureOtelFromEnv()fastgpt-sdk/otel—两种入口对应两种接入策略新代码直接用统一入口存量代码按模块逐个切换到子路径入口实现渐进式迁移。包版本与导出结构可查看 sdk/otel/package.json当前版本 0.1.2exports中声明了.、./logger、./metrics、./tracing四个子路径包以 ESM 方式构建产物为dist/index.mjs等。二、快速开始2.1 统一入口最直接的用法是在应用启动时调用configureOtelFromEnv()把日志、指标、追踪三者一次性从环境变量初始化import { configureOtelFromEnv, getLogger, getMeter, getTracer } from fastgpt-sdk/otel; await configureOtelFromEnv({ defaultServiceName: fastgpt-client }); const logger getLogger([system]); const meter getMeter(fastgpt-client); const tracer getTracer(fastgpt-client);其中defaultServiceName是兜底服务名当环境变量没有显式指定时日志的LOG_OTEL_SERVICE_NAME、指标的METRICS_OTEL_SERVICE_NAME、追踪的TRACING_OTEL_SERVICE_NAME以及标准 OTEL 的OTEL_SERVICE_NAME均会回退到它。2.2 渐进迁移入口如果只想逐步替换某个模块可以按需导入子路径import { configureLoggerFromEnv, getLogger } from fastgpt-sdk/otel/logger; import { configureMetricsFromEnv, getMeter } from fastgpt-sdk/otel/metrics; import { configureTracingFromEnv, getTracer } from fastgpt-sdk/otel/tracing;2.3 初始化与销毁的底层行为configureOtel()/configureOtelFromEnv()的实现见 src/client.ts 与 src/env.ts本质上是并发执行三个子模块的初始化await Promise.all([ configureLogger(options.logger ?? {}), configureMetrics(options.metrics ?? {}), configureTracing(options.tracing ?? {}) ]);三者互不阻塞、互不依赖任何一个失败都会让整体初始化失败。对应的disposeOtel()也并行执行disposeLogger()、disposeMetrics()、disposeTracing()分别完成 LogTape dispose、MeterProvider shutdown、TracerProvider shutdown用于优雅退出。值得注意的工程细节是三个子模块的configure*都是幂等的。以 logger 为例src/logger/client.ts内部维护configured标志与configurePromise重复调用不会重复创建 sink并发调用则复用同一个 Promise——这保证了在模块多处初始化、或测试与生产代码混跑时不会出现双重注册。三、日志logger能力深入3.1 环境变量与默认值logger 的初始化由configureLoggerFromEnv完成src/logger/env.ts支持的变量与默认值如下环境变量作用默认值LOG_ENABLE_CONSOLE是否输出到控制台trueLOG_CONSOLE_LEVEL控制台最低日志级别traceLOG_ENABLE_OTEL是否开启 OTel 日志导出falseLOG_OTEL_LEVELOTel 导出的最低日志级别warningLOG_OTEL_SERVICE_NAME导出时的服务名defaultServiceNameLOG_OTEL_LOGGER_NAMELogger 名称同服务名LOG_OTEL_URLOTLP HTTP logs 端点http://localhost:4318/v1/logs日志级别取值集合为trace / debug / info / warning / error / fatal非法值会静默回退到默认值src/logger/env.ts。布尔环境变量解析遵循1/true/yes/on为真、0/false/no/off为假的规则见 src/env-utils.ts。3.2 双 sink 架构控制台 OTelsink 的组装在 src/logger/sinks.ts控制台 sink使用 LogTape 的getConsoleSinkgetPrettyFormatter输出人类可读的格式化日志级别低于LOG_CONSOLE_LEVEL的记录被过滤OTel sink通过getOpenTelemetrySinksrc/logger/otel.ts创建内部使用OTLPLogExporterBatchLogRecordProcessor批量上报支持懒初始化——第一条日志到达时才初始化 exporter初始化前的日志先进入pendingRecords缓冲队列初始化完成后统一补发若初始化失败如端点不可达则丢弃缓冲并只向控制台打印错误。日志级别到 OTel SeverityNumber 的映射由mapLevelToSeverityNumber完成src/logger/helpers.tstrace→TRACE、debug→DEBUG、info→INFO、warning→WARN、error→ERROR、fatal→FATAL。3.3 OTel 日志的结构化输出约定这是 README 重点强调的设计src/logger/otel.tsbody承载业务数据形如{ __log_message, ...properties }。__log_message是把 LogTape 的 message 模板与占位符拼接后的人读摘要properties中剩余字段作为结构化上下文扁平放入 bodyattributes只保留日志元信息仅保留category即[system]、[http, request]这类分类数组不再复制 properties避免 body 与 attributes 内容重复名为traceId/spanId的 properties 是保留字段会被跳过避免与链路上下文重复见 src/logger/otel.ts。单元测试 sdk/otel/test/logger/otel.test.ts 用createMemoryLoggerProvider直接验证了这一点带completionsBody等复杂对象属性时body中完整保留结构化内容而attributes严格等于{ category: [test] }。3.4 安全归一化JS 特有值不再出现[object Object]在把 properties 写入 OTel body 之前所有值都要经过normalizeLogValuesrc/logger/otel.ts安全归一化规则包括输入类型归一化结果Map展开为普通对象key 字符串化Set转换为数组BigInt转为字符串Symbol转为字符串Function[Function name]DateISO 8601 字符串Error{ name, message, stack, cause, errors }含AggregateError的errors数组Uint8Array原样保留或按bytesAsSummary输出[Uint8Array lengthN]摘要class 实例普通对象化并附带__type: 构造函数名必要时用util.inspect兜底循环引用标记为[Circular]超出深度/键数深度上限 8 层[MaxDepth]单对象键数上限 128 个__truncated: true对应测试见 sdk/otel/test/logger/otel.test.tsMap被展开、Set变数组、bigint变字符串、class 实例带__type: CustomValue、循环引用输出[Circular]。这一设计保证了即使业务属性里混入原生 JS 类型也不会在序列化时抛异常或产出无意义的[object Object]。3.5 敏感属性过滤与日志上下文OTel sink 还支持sensitiveProperties过滤src/logger/sinks.ts当一条日志的 properties 中出现命中名单的键时该记录不会被导出到 OTel。FastGPT service 层在初始化时传入了sensitiveProperties: [fastgpt]见 packages/service/common/logger/client.ts。此外getLogger()返回的是带 Proxy 的 logger当调用形式为logger.info(msg, { verbose: false, ...properties })时verbose: false标记会被剥离、其余属性作为结构化上下文传入避免把控制开关写进日志数据src/logger/client.ts。withContext()与withCategoryPrefix()也从logtape/logtape直接转发用于在异步上下文中注入requestId等关联字段。四、指标metrics能力4.1 环境变量configureMetricsFromEnvsrc/metrics/env.ts支持的变量环境变量作用默认值METRICS_ENABLE_OTEL是否开启 OTel 指标导出false或OTEL_METRICS_EXPORTERotlp时自动开启METRICS_OTEL_SERVICE_NAME指标服务名回退到OTEL_SERVICE_NAME/defaultServiceNameMETRICS_OTEL_URLOTLP HTTP metrics 端点回退到OTEL_EXPORTER_OTLP_METRICS_ENDPOINTMETRICS_EXPORT_INTERVAL导出周期毫秒30000同时兼容标准OTEL_METRIC_EXPORT_INTERVALOTEL_METRICS_EXPORTER标准导出器选择为otlp时自动启用—底层实现src/metrics/client.ts使用MeterProviderPeriodicExportingMetricReader按exportIntervalMillis周期批量导出URL 会自动规范化不以/v1/metrics结尾时自动追加该路径。默认 meter 名为fastgpt可通过defaultMeterName覆盖。4.2 FastGPT service 层的指标实践FastGPT service 层已经用该 SDK 埋了两个典型指标集运行时指标packages/service/common/metrics/runtime.ts在fastgpt.runtimemeter 下注册了fastgpt.runtime.process.memory.{rss,heap_used,heap_total,external,array_buffers}、fastgpt.runtime.process.cpu.{user,system,utilization}、fastgpt.runtime.process.uptime等 ObservableGaugeCPU 利用率由两次采样间的 CPU 时间差与核数计算得到Redis 连接指标packages/service/common/metrics/redis.ts在fastgpt.redis.runtimemeter 下注册fastgpt.redis.connections.active/created/errors、fastgpt.redis.health.checks、fastgpt.redis.health.duration、fastgpt.redis.shutdown.durationDAL 层只注入观测回调不直接依赖 OTel测试时可以注入内存 recorder 而不初始化 exporter。service 层封装configureMetrics()packages/service/common/metrics/client.ts在初始化 OTel 后自动启动运行时指标采集disposeMetrics()时同步停止。五、链路追踪tracing能力5.1 专属环境变量与标准 OTEL 回退tracing 的环境变量解析在 src/tracing/env.tsREADME 列出的专属变量与回退逻辑如下专属变量优先级最高环境变量作用TRACING_ENABLE_OTEL是否开启 tracingtrue时启用TRACING_OTEL_SERVICE_NAME追踪服务名TRACING_OTEL_URLOTLP HTTP traces 端点TRACING_OTEL_SAMPLE_RATIO采样率0~1越界会被 clamp标准 OTEL fallback当专属变量缺失时按优先级读取标准变量作用OTEL_SERVICE_NAME服务名兜底OTEL_EXPORTER_OTLP_TRACES_ENDPOINTtraces 端点兜底OTEL_EXPORTER_OTLP_ENDPOINT通用 OTLP 端点兜底会自动追加/v1/tracesOTEL_TRACES_EXPORTER值为otlp时自动启用 tracingOTEL_TRACES_SAMPLER采样器选择支持always_on、always_off、traceidratio及其parentbased_*变体OTEL_TRACES_SAMPLER_ARG采样器参数用于 ratio 型采样器采样率的解析规则src/tracing/env.tsalways_off/parentbased_always_off映射为 0always_on/parentbased_always_on映射为 1traceidratio/parentbased_traceidratio读取OTEL_TRACES_SAMPLER_ARG其余情况回退默认值。5.2 采样与端点实现的底层细节默认采样率为 1全量采样经Math.max(0, Math.min(1, value))归一化底层使用NodeTracerProvider采样器为ParentBasedSampler({ root: new TraceIdRatioBasedSampler(ratio) })——即根 span 按比率采样子 span 跟随父 span 决策见 src/tracing/client.tsspan 通过BatchSpanProcessorOTLPTraceExporter批量导出端点缺失时只注册 provider 不导出span 仍可在进程内使用getCurrentSpanContext()可读取当前活跃 span 的traceId/spanId用于把链路 ID 拼进日志实现 trace 与 log 关联。5.3 service 层的 tracing 封装FastGPT service 层基于该 SDK 提供了三个生产级封装packages/service/common/tracing/client.ts默认采样策略TRACING_OTEL_SAMPLE_RATIO未配置时NODE_ENV production使用 0.011% 采样控制成本非生产环境使用 1全量采样withActiveSpan(name, callback)自动创建 span、注入 attributes、异常时setSpanError记录 exception 并置 ERROR 状态、finally中结束 spangetTraceLogContext()返回{ traceId, spanId }供日志上下文关联。实际调用链可参考两处HTTP 入口在 packages/service/common/http/entry.ts 中用withContext({ requestId })包裹withActiveSpan({ name: http.request, tracerName: fastgpt.http })把 method、route、body size 写入 span attributes工作流调度在 packages/service/core/workflow/dispatch/index.ts 与同文件第 1612 行对节点执行也包了withActiveSpan。这些是追踪能力在真实业务中的直接落地样本。六、迁移思路与在 FastGPT 中的落地现状README 给出了明确的三阶段迁移路径收拢初始化入口先把 logger/metrics/tracing 的初始化从多个 SDK 入口收到fastgpt-sdk/otel或fastgpt-sdk/otel/*子入口替换 import把业务代码中的logger/metricsimport 逐步改成otel子路径补充 traces最后按业务需要补充 span。从仓库现状看FastGPT 的 service 层已经完成了第一阶段甚至进入了第二阶段fastgpt-sdk/otel已通过workspace:*加入 service 依赖packages/service/package.jsonlogger 封装从fastgpt-sdk/otel/logger导入packages/service/common/logger/client.tsmetrics 封装从fastgpt-sdk/otel/metrics导入tracing 封装从fastgpt-sdk/otel/tracing导入测试与 Vitest 配置分别用paths/resolve.alias将三个子路径映射到sdk/otel/src下的入口文件见 packages/service/test/tsconfig.json 与 packages/service/vitest.config.ts说明子路径导出在开发与测试环境均可直接指向源码。service 层环境变量的生产配置集中在 packages/service/env.ts这些默认值可作为实际部署参考变量service 层默认值LOG_ENABLE_CONSOLEtrueLOG_CONSOLE_LEVELdebugLOG_ENABLE_OTELfalseLOG_OTEL_LEVELinfoLOG_OTEL_SERVICE_NAMEfastgpt-clientLOG_OTEL_URL可选METRICS_ENABLE_OTELfalseMETRICS_EXPORT_INTERVAL30000毫秒METRICS_OTEL_SERVICE_NAMEfastgpt-clientMETRICS_OTEL_URL可选TRACING_ENABLE_OTELfalseTRACING_OTEL_SERVICE_NAMEfastgpt-clientTRACING_OTEL_URL可选TRACING_OTEL_SAMPLE_RATIO可选0~1未配置时按 NODE_ENV 决定生产 0.01否则 1七、小结fastgpt-sdk/otel是 FastGPT 可观测性体系的“统一收口层”一键初始化configureOtelFromEnv()并行初始化 logger / metrics / tracingdisposeOtel()并行优雅销毁双入口设计统一入口适合新代码子路径入口适合存量代码渐进迁移两者 API 完全一致日志结构化body 承载业务数据、attributes 只留元信息配合 Map/Set/Error/循环引用等 JS 类型的深度安全归一化保证导出数据可查询、可检索标准兼容专属*_OTEL_*变量与标准OTEL_*变量双轨并存采样率、导出端点均有完备回退已在生产路径落地service 层的 HTTP 入口、工作流调度、运行时与 Redis 指标均基于该 SDK可直接作为接入范本。参考阅读sdk/otel/README.md包说明、sdk/otel/src/index.ts统一入口导出、sdk/otel/test/logger/otel.test.ts日志结构化行为测试、packages/service/common/logger/client.tsservice 层日志封装、packages/service/env.ts生产环境变量默认值。【免费下载链接】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），仅供参考 FastGPT 统一可观测性 SDK 实战：用 @fastgpt-sdk/otel 一站式接入 OpenTelemetry 日志、指标与链路追踪
FastGPT 统一可观测性 SDK 实战用 fastgpt-sdk/otel 一站式接入 OpenTelemetry 日志、指标与链路追踪【免费下载链接】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 仓库中统一的可观测性 SDK——fastgpt-sdk/otel位于 sdk/otel/README.md。该包的目标是把分散的fastgpt-sdk/logger、fastgpt-sdk/metrics与 tracing 能力收拢到单一入口同时提供“统一入口”和“渐进迁移入口”两种用法。读完本文你将掌握其环境变量体系、日志结构化输出与安全归一化规则、指标与采样的底层实现以及如何像 FastGPT service 层那样用它接入 OpenTelemetry Collector / OTLP 后端。一、定位为什么需要一个统一的可观测性 SDK从源码看fastgpt-sdk/otel是一个自包含self-contained包内部自带 logger 实现、metrics 实现与 tracing 实现不依赖fastgpt-sdk/logger或fastgpt-sdk/metrics三者可独立工作它的定位是“整理好的统一入口”而不是“已经迁移完成的替换方案”——现有 logger 与 metrics 包仍然可以继续独立使用后续再逐步迁移。它对外提供四类能力能力说明统一入口渐进迁移入口日志基于 LogTape 的 loggerfastgpt-sdk/otelfastgpt-sdk/otel/logger指标OpenTelemetry Metricsfastgpt-sdk/otelfastgpt-sdk/otel/metrics链路追踪OpenTelemetry Tracingfastgpt-sdk/otelfastgpt-sdk/otel/tracing初始化统一的configureOtel()/configureOtelFromEnv()fastgpt-sdk/otel—两种入口对应两种接入策略新代码直接用统一入口存量代码按模块逐个切换到子路径入口实现渐进式迁移。包版本与导出结构可查看 sdk/otel/package.json当前版本 0.1.2exports中声明了.、./logger、./metrics、./tracing四个子路径包以 ESM 方式构建产物为dist/index.mjs等。二、快速开始2.1 统一入口最直接的用法是在应用启动时调用configureOtelFromEnv()把日志、指标、追踪三者一次性从环境变量初始化import { configureOtelFromEnv, getLogger, getMeter, getTracer } from fastgpt-sdk/otel; await configureOtelFromEnv({ defaultServiceName: fastgpt-client }); const logger getLogger([system]); const meter getMeter(fastgpt-client); const tracer getTracer(fastgpt-client);其中defaultServiceName是兜底服务名当环境变量没有显式指定时日志的LOG_OTEL_SERVICE_NAME、指标的METRICS_OTEL_SERVICE_NAME、追踪的TRACING_OTEL_SERVICE_NAME以及标准 OTEL 的OTEL_SERVICE_NAME均会回退到它。2.2 渐进迁移入口如果只想逐步替换某个模块可以按需导入子路径import { configureLoggerFromEnv, getLogger } from fastgpt-sdk/otel/logger; import { configureMetricsFromEnv, getMeter } from fastgpt-sdk/otel/metrics; import { configureTracingFromEnv, getTracer } from fastgpt-sdk/otel/tracing;2.3 初始化与销毁的底层行为configureOtel()/configureOtelFromEnv()的实现见 src/client.ts 与 src/env.ts本质上是并发执行三个子模块的初始化await Promise.all([ configureLogger(options.logger ?? {}), configureMetrics(options.metrics ?? {}), configureTracing(options.tracing ?? {}) ]);三者互不阻塞、互不依赖任何一个失败都会让整体初始化失败。对应的disposeOtel()也并行执行disposeLogger()、disposeMetrics()、disposeTracing()分别完成 LogTape dispose、MeterProvider shutdown、TracerProvider shutdown用于优雅退出。值得注意的工程细节是三个子模块的configure*都是幂等的。以 logger 为例src/logger/client.ts内部维护configured标志与configurePromise重复调用不会重复创建 sink并发调用则复用同一个 Promise——这保证了在模块多处初始化、或测试与生产代码混跑时不会出现双重注册。三、日志logger能力深入3.1 环境变量与默认值logger 的初始化由configureLoggerFromEnv完成src/logger/env.ts支持的变量与默认值如下环境变量作用默认值LOG_ENABLE_CONSOLE是否输出到控制台trueLOG_CONSOLE_LEVEL控制台最低日志级别traceLOG_ENABLE_OTEL是否开启 OTel 日志导出falseLOG_OTEL_LEVELOTel 导出的最低日志级别warningLOG_OTEL_SERVICE_NAME导出时的服务名defaultServiceNameLOG_OTEL_LOGGER_NAMELogger 名称同服务名LOG_OTEL_URLOTLP HTTP logs 端点http://localhost:4318/v1/logs日志级别取值集合为trace / debug / info / warning / error / fatal非法值会静默回退到默认值src/logger/env.ts。布尔环境变量解析遵循1/true/yes/on为真、0/false/no/off为假的规则见 src/env-utils.ts。3.2 双 sink 架构控制台 OTelsink 的组装在 src/logger/sinks.ts控制台 sink使用 LogTape 的getConsoleSinkgetPrettyFormatter输出人类可读的格式化日志级别低于LOG_CONSOLE_LEVEL的记录被过滤OTel sink通过getOpenTelemetrySinksrc/logger/otel.ts创建内部使用OTLPLogExporterBatchLogRecordProcessor批量上报支持懒初始化——第一条日志到达时才初始化 exporter初始化前的日志先进入pendingRecords缓冲队列初始化完成后统一补发若初始化失败如端点不可达则丢弃缓冲并只向控制台打印错误。日志级别到 OTel SeverityNumber 的映射由mapLevelToSeverityNumber完成src/logger/helpers.tstrace→TRACE、debug→DEBUG、info→INFO、warning→WARN、error→ERROR、fatal→FATAL。3.3 OTel 日志的结构化输出约定这是 README 重点强调的设计src/logger/otel.tsbody承载业务数据形如{ __log_message, ...properties }。__log_message是把 LogTape 的 message 模板与占位符拼接后的人读摘要properties中剩余字段作为结构化上下文扁平放入 bodyattributes只保留日志元信息仅保留category即[system]、[http, request]这类分类数组不再复制 properties避免 body 与 attributes 内容重复名为traceId/spanId的 properties 是保留字段会被跳过避免与链路上下文重复见 src/logger/otel.ts。单元测试 sdk/otel/test/logger/otel.test.ts 用createMemoryLoggerProvider直接验证了这一点带completionsBody等复杂对象属性时body中完整保留结构化内容而attributes严格等于{ category: [test] }。3.4 安全归一化JS 特有值不再出现[object Object]在把 properties 写入 OTel body 之前所有值都要经过normalizeLogValuesrc/logger/otel.ts安全归一化规则包括输入类型归一化结果Map展开为普通对象key 字符串化Set转换为数组BigInt转为字符串Symbol转为字符串Function[Function name]DateISO 8601 字符串Error{ name, message, stack, cause, errors }含AggregateError的errors数组Uint8Array原样保留或按bytesAsSummary输出[Uint8Array lengthN]摘要class 实例普通对象化并附带__type: 构造函数名必要时用util.inspect兜底循环引用标记为[Circular]超出深度/键数深度上限 8 层[MaxDepth]单对象键数上限 128 个__truncated: true对应测试见 sdk/otel/test/logger/otel.test.tsMap被展开、Set变数组、bigint变字符串、class 实例带__type: CustomValue、循环引用输出[Circular]。这一设计保证了即使业务属性里混入原生 JS 类型也不会在序列化时抛异常或产出无意义的[object Object]。3.5 敏感属性过滤与日志上下文OTel sink 还支持sensitiveProperties过滤src/logger/sinks.ts当一条日志的 properties 中出现命中名单的键时该记录不会被导出到 OTel。FastGPT service 层在初始化时传入了sensitiveProperties: [fastgpt]见 packages/service/common/logger/client.ts。此外getLogger()返回的是带 Proxy 的 logger当调用形式为logger.info(msg, { verbose: false, ...properties })时verbose: false标记会被剥离、其余属性作为结构化上下文传入避免把控制开关写进日志数据src/logger/client.ts。withContext()与withCategoryPrefix()也从logtape/logtape直接转发用于在异步上下文中注入requestId等关联字段。四、指标metrics能力4.1 环境变量configureMetricsFromEnvsrc/metrics/env.ts支持的变量环境变量作用默认值METRICS_ENABLE_OTEL是否开启 OTel 指标导出false或OTEL_METRICS_EXPORTERotlp时自动开启METRICS_OTEL_SERVICE_NAME指标服务名回退到OTEL_SERVICE_NAME/defaultServiceNameMETRICS_OTEL_URLOTLP HTTP metrics 端点回退到OTEL_EXPORTER_OTLP_METRICS_ENDPOINTMETRICS_EXPORT_INTERVAL导出周期毫秒30000同时兼容标准OTEL_METRIC_EXPORT_INTERVALOTEL_METRICS_EXPORTER标准导出器选择为otlp时自动启用—底层实现src/metrics/client.ts使用MeterProviderPeriodicExportingMetricReader按exportIntervalMillis周期批量导出URL 会自动规范化不以/v1/metrics结尾时自动追加该路径。默认 meter 名为fastgpt可通过defaultMeterName覆盖。4.2 FastGPT service 层的指标实践FastGPT service 层已经用该 SDK 埋了两个典型指标集运行时指标packages/service/common/metrics/runtime.ts在fastgpt.runtimemeter 下注册了fastgpt.runtime.process.memory.{rss,heap_used,heap_total,external,array_buffers}、fastgpt.runtime.process.cpu.{user,system,utilization}、fastgpt.runtime.process.uptime等 ObservableGaugeCPU 利用率由两次采样间的 CPU 时间差与核数计算得到Redis 连接指标packages/service/common/metrics/redis.ts在fastgpt.redis.runtimemeter 下注册fastgpt.redis.connections.active/created/errors、fastgpt.redis.health.checks、fastgpt.redis.health.duration、fastgpt.redis.shutdown.durationDAL 层只注入观测回调不直接依赖 OTel测试时可以注入内存 recorder 而不初始化 exporter。service 层封装configureMetrics()packages/service/common/metrics/client.ts在初始化 OTel 后自动启动运行时指标采集disposeMetrics()时同步停止。五、链路追踪tracing能力5.1 专属环境变量与标准 OTEL 回退tracing 的环境变量解析在 src/tracing/env.tsREADME 列出的专属变量与回退逻辑如下专属变量优先级最高环境变量作用TRACING_ENABLE_OTEL是否开启 tracingtrue时启用TRACING_OTEL_SERVICE_NAME追踪服务名TRACING_OTEL_URLOTLP HTTP traces 端点TRACING_OTEL_SAMPLE_RATIO采样率0~1越界会被 clamp标准 OTEL fallback当专属变量缺失时按优先级读取标准变量作用OTEL_SERVICE_NAME服务名兜底OTEL_EXPORTER_OTLP_TRACES_ENDPOINTtraces 端点兜底OTEL_EXPORTER_OTLP_ENDPOINT通用 OTLP 端点兜底会自动追加/v1/tracesOTEL_TRACES_EXPORTER值为otlp时自动启用 tracingOTEL_TRACES_SAMPLER采样器选择支持always_on、always_off、traceidratio及其parentbased_*变体OTEL_TRACES_SAMPLER_ARG采样器参数用于 ratio 型采样器采样率的解析规则src/tracing/env.tsalways_off/parentbased_always_off映射为 0always_on/parentbased_always_on映射为 1traceidratio/parentbased_traceidratio读取OTEL_TRACES_SAMPLER_ARG其余情况回退默认值。5.2 采样与端点实现的底层细节默认采样率为 1全量采样经Math.max(0, Math.min(1, value))归一化底层使用NodeTracerProvider采样器为ParentBasedSampler({ root: new TraceIdRatioBasedSampler(ratio) })——即根 span 按比率采样子 span 跟随父 span 决策见 src/tracing/client.tsspan 通过BatchSpanProcessorOTLPTraceExporter批量导出端点缺失时只注册 provider 不导出span 仍可在进程内使用getCurrentSpanContext()可读取当前活跃 span 的traceId/spanId用于把链路 ID 拼进日志实现 trace 与 log 关联。5.3 service 层的 tracing 封装FastGPT service 层基于该 SDK 提供了三个生产级封装packages/service/common/tracing/client.ts默认采样策略TRACING_OTEL_SAMPLE_RATIO未配置时NODE_ENV production使用 0.011% 采样控制成本非生产环境使用 1全量采样withActiveSpan(name, callback)自动创建 span、注入 attributes、异常时setSpanError记录 exception 并置 ERROR 状态、finally中结束 spangetTraceLogContext()返回{ traceId, spanId }供日志上下文关联。实际调用链可参考两处HTTP 入口在 packages/service/common/http/entry.ts 中用withContext({ requestId })包裹withActiveSpan({ name: http.request, tracerName: fastgpt.http })把 method、route、body size 写入 span attributes工作流调度在 packages/service/core/workflow/dispatch/index.ts 与同文件第 1612 行对节点执行也包了withActiveSpan。这些是追踪能力在真实业务中的直接落地样本。六、迁移思路与在 FastGPT 中的落地现状README 给出了明确的三阶段迁移路径收拢初始化入口先把 logger/metrics/tracing 的初始化从多个 SDK 入口收到fastgpt-sdk/otel或fastgpt-sdk/otel/*子入口替换 import把业务代码中的logger/metricsimport 逐步改成otel子路径补充 traces最后按业务需要补充 span。从仓库现状看FastGPT 的 service 层已经完成了第一阶段甚至进入了第二阶段fastgpt-sdk/otel已通过workspace:*加入 service 依赖packages/service/package.jsonlogger 封装从fastgpt-sdk/otel/logger导入packages/service/common/logger/client.tsmetrics 封装从fastgpt-sdk/otel/metrics导入tracing 封装从fastgpt-sdk/otel/tracing导入测试与 Vitest 配置分别用paths/resolve.alias将三个子路径映射到sdk/otel/src下的入口文件见 packages/service/test/tsconfig.json 与 packages/service/vitest.config.ts说明子路径导出在开发与测试环境均可直接指向源码。service 层环境变量的生产配置集中在 packages/service/env.ts这些默认值可作为实际部署参考变量service 层默认值LOG_ENABLE_CONSOLEtrueLOG_CONSOLE_LEVELdebugLOG_ENABLE_OTELfalseLOG_OTEL_LEVELinfoLOG_OTEL_SERVICE_NAMEfastgpt-clientLOG_OTEL_URL可选METRICS_ENABLE_OTELfalseMETRICS_EXPORT_INTERVAL30000毫秒METRICS_OTEL_SERVICE_NAMEfastgpt-clientMETRICS_OTEL_URL可选TRACING_ENABLE_OTELfalseTRACING_OTEL_SERVICE_NAMEfastgpt-clientTRACING_OTEL_URL可选TRACING_OTEL_SAMPLE_RATIO可选0~1未配置时按 NODE_ENV 决定生产 0.01否则 1七、小结fastgpt-sdk/otel是 FastGPT 可观测性体系的“统一收口层”一键初始化configureOtelFromEnv()并行初始化 logger / metrics / tracingdisposeOtel()并行优雅销毁双入口设计统一入口适合新代码子路径入口适合存量代码渐进迁移两者 API 完全一致日志结构化body 承载业务数据、attributes 只留元信息配合 Map/Set/Error/循环引用等 JS 类型的深度安全归一化保证导出数据可查询、可检索标准兼容专属*_OTEL_*变量与标准OTEL_*变量双轨并存采样率、导出端点均有完备回退已在生产路径落地service 层的 HTTP 入口、工作流调度、运行时与 Redis 指标均基于该 SDK可直接作为接入范本。参考阅读sdk/otel/README.md包说明、sdk/otel/src/index.ts统一入口导出、sdk/otel/test/logger/otel.test.ts日志结构化行为测试、packages/service/common/logger/client.tsservice 层日志封装、packages/service/env.ts生产环境变量默认值。【免费下载链接】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），仅供参考