基于 OpenTelemetry 实现 LangChain 观测云全链路可观测

产品架构师刘锐 2026-08-28 6 分钟阅读更新于 2026-08-28

当 LangChain 应用进入真实使用场景后，开发者通常很快会遇到几个共同问题：一次请求里到底经过了哪些链路、Prompt 模板和模型调用分别耗时多少、失败发生在编排层还是模型层、一次对话的上下文是否被正确传递。没有可观测能力时，这些问题往往只能依赖打印日志和人工猜测，排查成本高，也很难稳定复现。对于需要持续迭代的 AI 应用来说，补齐可观测能力通常不是“锦上添花”，而是把应用从能跑提升到能维护、能诊断、能优化的基础工作。

一、为什么 LangChain 必须做可观测？

LangChain 封装了 Prompt 模板、模型调用、上下文管理、链式编排等复杂逻辑，大幅提升开发效率，但也让请求链路变得黑盒化。

尤其在多轮对话、复杂 Prompt、第三方模型网关、工具调用等复杂场景下，开发者亟需精准解答这些核心问题：

单次请求的完整根调用链路是什么？
Prompt 渲染、大模型调用的各自耗时占比？
接口响应慢，是应用编排导致，还是模型侧瓶颈？
单次请求是否存在重复模型调用、无效调用？
接口报错、响应异常，精准定位故障发生阶段？

如果采用传统方式手动初始化 Tracer、Span、OTLP 上报组件，不仅接入门槛高，还会让观测逻辑侵入业务代码，增加维护成本。

而 Zero-Code 自动观测方案，完美适配两大项目阶段：

项目早期：快速验证 LangChain 链路采集能力，低成本落地观测体系
迭代中期：零业务代码改动，平稳升级可观测能力，规避代码侵入风险

二、接入方案

本次实践采用业界轻量化最优方案：OpenTelemetry 自动埋点 + LangChain 专属 instrumentation + Langfuse 兼容 OTLP 上报。

核心优势就是零代码侵入：业务层无需手动创建 Span、无需初始化 OTEL SDK，所有埋点注入、协议适配、鉴权配置、数据上报，均在进程启动层自动完成。

该方案带来两大核心价值：

原有 LangChain 业务逻辑零改动，彻底解耦业务与观测逻辑
标准化统一接入，规避重复造轮子，降低团队整体接入成本

Demo 资源说明

完整可运行 Demo 已开源，包含零代码启动、调试脚本，可直接复刻验证：

✅ 仓库地址：https://github.com/GuanceDemo/langchain-observability-demo

核心文件说明：

app_otel_zero.py：纯业务代码，仅保留 LangChain 多轮对话核心逻辑，无任何观测埋点
run_otel_zero.sh：标准 Zero-Code 启动脚本，自动注入 OTEL 观测能力
run_otel_zero_debug.sh：调试启动脚本，可打印 OTLP 请求/响应头、状态码，快速排查上报异常

接入后，系统会自动生成层级清晰的观测链路 Span，覆盖全流程：

RunnableSequence.workflow：标识完整 LangChain 编排流程
execute_task ChatPromptTemplate：记录 Prompt 模板渲染阶段
ChatOpenAI.chat：监控大模型调用核心阶段

所有埋点均由 opentelemetry-instrumentation-langchain 自动注入，无需人工编码。

三、接入步骤

全程无需修改业务代码，仅需配置环境变量、执行脚本，即可完成全链路观测接入。

1. 环境准备 & 依赖安装

拉取 Demo 仓库，初始化 Python 虚拟环境，安装全部依赖（包含 OTEL 观测组件）：

git clone https://github.com/GuanceDemo/langchain-observability-demo.git
cd langchain-observability-demo

# 初始化虚拟环境
python3 -m venv .venv
source .venv/bin/activate

# 安装全部依赖（含 OTEL 零代码观测核心组件）
python -m pip install -r requirements.txt

本次方案依赖核心观测组件：

opentelemetry-sdk：OTEL 核心 SDK
opentelemetry-distro：自动埋点分发工具
opentelemetry-exporter-otlp-proto-http：OTLP HTTP 上报适配器
opentelemetry-instrumentation-langchain：LangChain 专属自动埋点插件

⚠️ 关键注意：统一采用 OTLP HTTP/protobuf 协议，避免默认 gRPC 协议导致的 otlp_proto_grpc not found 启动报错。

2. 模型服务环境配置

根据自身部署场景，选择对应模型配置，打通 LangChain 调用链路（模型链路正常，观测数据才能正常生成）。

场景 A：OpenAI 兼容网关（推荐）

export MODEL_PROVIDER=compatible
export OPENAI_BASE_URL="http://<your-model-gateway>/v1"
export OPENAI_API_KEY="<your-model-key>"
export OPENAI_MODEL="claude-sonnet-4.5"

场景 B：本地 Ollama 模型

export MODEL_PROVIDER=ollama
export OLLAMA_BASE_URL="http://127.0.0.1:11434"
export OLLAMA_MODEL="qwen3:8b"

3. Langfuse 兼容接口鉴权配置

观测云 Langfuse 兼容接口需双重鉴权，通过 Public Key、Secret Key 生成 Basic Auth 凭证：

export LANGFUSE_PUBLIC_KEY="<your_langfuse_public_key>"
export LANGFUSE_SECRET_KEY="<your_langfuse_secret_key>"

# 生成 Base64 鉴权凭证
BASIC_AUTH="$(
printf '%s:%s' "$LANGFUSE_PUBLIC_KEY" "$LANGFUSE_SECRET_KEY" |
  base64 -w 0
)"

⚠️ 核心要点：必须同时配置 Authorization=Basic 和 x-langfuse-public-key 请求头，缺失任意一项都会触发鉴权失败。

4. OTEL 观测上报核心配置

定义链路上报地址、协议、鉴权头，聚焦 Trace 观测，关闭冗余指标，避免启动异常，完整配置如下：

# 基础服务与观测类型配置
export OTEL_SERVICE_NAME="langchain-observability-demo"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="none"
export OTEL_LOGS_EXPORTER="none"

# 上报鉴权与地址配置
export LANGFUSE_PUBLIC_KEY="<your_langfuse_public_key>"
export LANGFUSE_SECRET_KEY="<your_langfuse_secret_key>"

BASIC_AUTH="$(
printf '%s:%s' "$LANGFUSE_PUBLIC_KEY" "$LANGFUSE_SECRET_KEY" |
base64 -w 0
)"

export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ${BASIC_AUTH},x-langfuse-public-key=${LANGFUSE_PUBLIC_KEY}"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://llm-openway.guance.com/api/public/otel/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"

⚠️ 格式避坑：

请求头参数必须为 key=value 格式，禁止 key:value
多参数分隔统一使用英文逗号，杜绝中文标点

5. 启动应用，开启自动观测

日常运行/调试二选一即可，新手优先使用调试脚本，便于问题定位：

# 常规启动
sh run_otel_zero.sh

# 调试启动（推荐）：打印完整请求/响应日志，验证上报状态
sh run_otel_zero_debug.sh

四、接入效果 & 异常排查

1. 正常效果验证

终端输入对话指令（如 hi），模型正常响应，同时控制台打印如下内容，即代表观测链路搭建成功：

liurui@liurui:~/code/langchain-observability-demo$ sh run_otel_zero_debug.sh 
[config] model provider: openai-compatible (claude-sonnet-4.5)
[session] interactive chat started (otel zero-code)
[session] 通过 OTel auto-instrumentation 启动时会自动注入 LangChain OTEL instrumentation
[session] 输入 exit 或 quit 结束，输入 /clear 清空上下文

You> opentelemetry 支持langchain 自动插桩吗？
[otel-debug] requests hook enabled
[http] --> POST https://llm-openway.guance.com/api/public/otel/v1/traces
[http] --> headers: {'User-Agent': 'OTel-OTLP-Exporter-Python/1.44.0', 'Accept-Encoding': 'gzip, deflate', 'Accept': '*/*', 'Connection': 'keep-alive', 'authorization': '***REDACTED***', 'x-langfuse-public-key': '9358dab0_90aa_11f1_a76e_01b0db22e239', 'Content-Type': 'application/x-protobuf', 'Content-Length': '2879'}
[http] --> body: 2879 bytes, hex[:32]=0abc160a81020a220a1674656c656d657472792e73646b2e6c616e6775616765
[http] <-- 200 OK
[http] <-- headers: {'Date': 'Wed, 05 Aug 2026 09:56:24 GMT', 'Content-Length': '0', 'Connection': 'keep-alive', 'X-Content-Type-Options': 'nosniff'}

Assistant>  **
......

You> [otel-debug] requests hook enabled
[http] --> POST https://llm-openway.guance.com/api/public/otel/v1/traces
[http] --> headers: {'User-Agent': 'OTel-OTLP-Exporter-Python/1.44.0', 'Accept-Encoding': 'gzip, deflate', 'Accept': '*/*', 'Connection': 'keep-alive', 'authorization': '***REDACTED***', 'x-langfuse-public-key': '9358dab0_90aa_11f1_a76e_01b0db22e239', 'Content-Type': 'application/x-protobuf', 'Content-Length': '8908'}
[http] --> body: 8908 bytes, hex[:32]=0ac9450a81020a220a1674656c656d657472792e73646b2e6c616e6775616765
[http] <-- 200 OK
[http] <-- headers: {'Date': 'Wed, 05 Aug 2026 09:56:44 GMT', 'Content-Length': '0', 'Connection': 'keep-alive', 'X-Content-Type-Options': 'nosniff'}

此时观测云后台可生成分层级完整调用链路：