tencentcloud-cls-sdk-langchain 1.0.2

CLS observability SDK for LangChain/LangGraph — 6-layer span hierarchy, direct upload to Tencent Cloud CLS

tencentcloud-cls-sdk-langchain

腾讯云 CLS（日志服务）LangChain/LangGraph 可观测插件。

自动采集 LangChain/LangGraph 应用的调用链路，生成 6 层 Span 层级模型，直接上报到 CLS。

安装

pip install tencentcloud-cls-sdk-langchain

插件不包含 LangChain/LangGraph 本身，如未安装请先：pip install langchain langgraph langchain-openai

快速接入

1. 配置 CLS 凭据（一次性）

python -m tencentcloud_cls_sdk_langchain.cls_config init

按提示输入 CLS 接入点、Topic ID、SecretId/SecretKey，配置保存到 .env。

2. 代码接入

在应用启动代码中加入 3 行：

from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from tencentcloud_cls_sdk_langchain import LangChainInstrumentor
from tencentcloud_cls_sdk_langchain.cls_cloud_exporter import CLSCloudExporter

provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(CLSCloudExporter()))
LangChainInstrumentor().instrument(tracer_provider=provider)

# 下面正常写你的 LangChain/LangGraph 代码，无需任何改动

3. 验证

运行应用后约 30 秒，到 CLS 控制台 → 日志主题 → 检索分析，应能看到 6 类 Span。

Span 层级模型

entry (应用入口)
 └─ session (对话窗口)
     └─ agent (每次提问)
         └─ step (每轮 ReAct)
             ├─ chat (LLM 调用)
             └─ tool (工具调用)

环境变量

配置命令 cls_config init 会自动写入 .env，也可以手动设置：

变量	必填	说明
CLS_ENDPOINT	是	CLS API 接入点
CLS_TOPIC_ID	是	CLS 日志主题 ID
CLS_SECRET_ID	是	腾讯云 SecretId
CLS_SECRET_KEY	是	腾讯云 SecretKey
CLS_SERVICE_NAME	否	服务名称（默认 langchain-app）

License

Apache-2.0