Langfuse的4种监控构建方式（从非侵入到侵入）

Langfuse 的监控不是全都是侵入式的。它提供了一条从完全侵入到完全非侵入的光谱你可以按自己的场景挑。但有一个前提要先说清“非侵入在 LLM 可观测性里通常指不改业务代码”而不是系统完全无感知——数据总得有人在某个环节采集。Langfuse 的四种接入方式侵入程度递增1. 网关代理模式最接近非侵入如果你在架构里已经走了 LiteLLM Proxy 这类网关所有 LLM 调用都路由经过它那么只需在代理配置里加上 Langfuse callback应用代码一行都不用改。# litellm_config.yamlmodel_list:-model_name:gpt-5.1litellm_params:model:gpt-5.1litellm_settings:callbacks:[langfuse_otel]exportLANGFUSE_PUBLIC_KEYpk-lf-...exportLANGFUSE_SECRET_KEYsk-lf-...exportLANGFUSE_OTEL_HOSThttps://us.cloud.langfuse.com启动代理后所有经过http://0.0.0.0:4000/v1/chat/completions的请求都会自动在 Langfuse 里出现 trace 。侵入程度⭐ 几乎为零。你的应用还是调openai.chat.completions.create()只是base_url指向代理而不是api.openai.com。 这种模式的代价网关能看到的是一次 LLM API 调用但看不到你应用内部的业务逻辑——比如 RAG 的检索步骤、Agent 的工具调用决策、业务函数的嵌套关系。这些细粒度链路网关是没法替你采集的。2. OpenTelemetry 接收端模式非侵入但需 OTel 埋点Langfuse 本身就是一个OpenTelemetry Backend它在/api/public/otel端点接收标准 OTLP 数据 。这意味着如果你的应用、框架或 collector 已经在发 OTel traces只需改个 endpoint 就能把数据导到 Langfuse从 Arize Phoenix 迁移到 Langfuse 时不需要重新埋点——OpenInference 的 spans 直接兼容改个 OTLP endpoint 和 auth header 就行OTEL_EXPORTER_OTLP_ENDPOINThttps://cloud.langfuse.com/api/public/otelOTEL_EXPORTER_OTLP_HEADERSAuthorizationBasic${AUTH_STRING},x-langfuse-ingestion-version4Java/Go 这类 Langfuse 没有原生 SDK 的语言官方推荐直接用 OTel 原生 API 发 spans 到 Langfuse 。OpenLLMetry、OpenLIT 这些 OTel 生态库可以把 AutoGen、Semantic Kernel 等框架的调用自动变成 spans 发给 Langfuse 。侵入程度⭐⭐ 低。如果框架本身有 OTel 自动埋点如 LangChain 的 OTel 集成你只需要配置环境变量如果框架没有那你还是得在代码里创建 span。3. 框架集成模式低侵入Langfuse 对主流 LLM 框架提供了一行接入的集成LangChain传入LangfuseCallbackHandler即可自动捕获 Chain/Agent 链路OpenAI SDK用from langfuse.openai import openai替换原来的 importdrop-in wrapper 自动加 OTel tracingLiteLLM SDKlitellm.callbacks [langfuse_otel]Vercel AI SDK、Pydantic AI、Claude Agent SDK、Dify、n8n等 100 集成侵入程度⭐⭐⭐ 中等。通常需要改 import 或传一个 callback 对象但不需要在每个函数上手写埋点代码。4. SDK observe()装饰器模式侵入式这是 Langfuse 最精细的接入方式能捕获到你应用里的每一个函数调用层级fromlangfuseimportobserve,get_clientobserve()defretrieve_docs(query:str)-str:# 检索步骤自动成为一个 Observation...observe(as_typegeneration)defgenerate_answer(query:str,docs:str)-str:# 生成步骤额外记录模型和 token...observe()defhandle_request(text:str)-str:docsretrieve_docs(text)returngenerate_answer(text,docs)侵入程度⭐⭐⭐⭐ 高。你需要在每个想追踪的函数上加observe()装饰器。但带来的好处是链路最完整——Langfuse 面板里能看到handle_request→retrieve_docs→generate_answer的完整嵌套结构每个步骤的耗时、输入输出、token 消耗都一清二楚 。四种方式的取舍方式侵入程度链路粒度适用场景网关代理几乎为零仅 LLM API 调用级已用 LiteLLM只想看模型调用OTel 接收端低取决于 OTel 埋点深度Java/Go 等无原生 SDK 的语言框架集成中等框架自动捕获的链路LangChain/Vercel AI SDK 项目SDK observe()高函数级精细链路需要深度调试 Agent/RAG 内部逻辑一个工程实践中的真相纯非侵入在 LLM 可观测性里是个伪命题。原因网关模式虽然不改应用代码但你必须在架构里引入并维护一个代理层。而且网关只能看到LLM 调用这一种 span看不到业务函数的嵌套关系。OTel 模式虽然标准但 LLM 应用的语义约定GenAI Semantic Conventions还在演化中 不同框架发的 attributes 略有差异Langfuse 要做 attribute mapping 。真实生产环境的最佳实践是混合模式网关层LiteLLM Proxy负责采集所有 LLM 调用的骨架在关键业务函数上加observe()装饰器补充业务语义通过 OTel Context Propagation 把两者串成一条完整 trace这样既不至于在每个函数上都写埋点太侵入也不会丢失 Agent 内部的决策链路太粗糙。关于侵入式的两个常见误解⚠️误解一“observe() 装饰器会拖慢我的应用”实际上 Langfuse SDK 全程异步上报几乎不给业务增加延迟且 SDK 自身报错会被捕获绝不会拖垮主流程 。装饰器的侵入是代码层面的不是性能层面的。⚠️误解二“非侵入就是零成本”网关模式看似不改代码但你引入了单点故障代理挂了怎么办、增加了网络跳数延迟 1 RTT、还要维护代理的可用性和扩缩容。这些非侵入的代价往往比在代码里加几个observe()更高。选型建议选网关模式当你已经在用 LiteLLM 或其他 LLM 网关你只关心模型调用这层不需要看业务内部逻辑你的应用是多语言混合栈不想在每个语言里都接 SDK选 OTel 模式当你的技术栈是 Java/Go/Ruby 等 Langfuse 没有原生 SDK 的语言你已经在用 OTel 做可观测性想把 LLM trace 并入现有体系你从 Phoenix 等其他 OTel 后端迁移过来选框架集成当你的项目基于 LangChain、Vercel AI SDK、Claude Agent SDK 等主流框架你想快速接入不想手写装饰器选 SDK observe() 当你在深度调试 Agent/RAG 的内部逻辑你需要函数级的精细链路和耗时分析你在做 LLM 应用的性能优化需要知道到底是哪个步骤慢所以回到你的问题Langfuse 的监控不都是侵入式的。它提供从网关代理几乎零侵入到 observe() 装饰器深度侵入的完整光谱。Langfuse vs LangSmith语境下这一点也是 Langfuse 的优势——LangSmith 与 LangChain 深度绑定非 LangChain 场景往往需要手动埋点而 Langfuse 因为 OTel 原生 100 集成 网关支持无论你用什么框架总能找到侵入程度匹配的接入方式。