用途：整理 Langfuse SDK 的生产级使用模式，帮助在应用中正确接入追踪、观测与评分能力。
主要能力：单例客户端与一次性 OpenTelemetry 初始化；observe 包装器为现有函数自动创建 span；startActiveObservation 实现嵌套追踪与内联控制；会话与用户跟踪；优雅关闭以排空待发送事件；错误安全追踪，保证追踪失败不影响业务。
使用方式：v4+ 使用 @langfuse/tracing、@langfuse/otel、@opentelemetry/sdk-node，在应用入口初始化 NodeSDK 并注册 LangfuseSpanProcessor，在 SIGTERM/SIGINT 时调用 sdk.shutdown()；用 observe 包装函数，用 updateActiveObservation 记录输入输出、模型与用量；v3 使用 langfuse 包，通过 trace.span 并在 try/finally 中调用 span.end()。
适用场景：LLM 调用链追踪、请求级观测、会话级分析、现有函数低成本加追踪。
限制与注意：避免每请求新建客户端、热路径等待 flush、记录完整请求体、v3 遗漏 .end()、硬编码 API 密钥；追踪应视为非关键基础设施，导出失败需记录上下文但不得掩盖业务结果。前置条件为已完成 langfuse-install-auth 配置并理解 async/await。具体版本差异与配置细节以官方文档为准。