Metadata-Version: 2.4
Name: tencentcloud-cls-sdk-langchain
Version: 1.0.1
Summary: CLS observability SDK for LangChain/LangGraph — 6-layer span hierarchy, direct upload to Tencent Cloud CLS
Author: Tencent Cloud CLS Team
License: Apache-2.0
Project-URL: Homepage, https://cloud.tencent.com/product/cls
Project-URL: Documentation, https://cloud.tencent.com/document/product/614
Project-URL: Repository, https://github.com/TencentCloud/cls-sdk-langchain
Keywords: tencent,cls,langchain,langgraph,opentelemetry,observability,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-sdk>=1.20.0
Requires-Dist: opentelemetry-instrumentation>=0.40b0
Requires-Dist: wrapt>=1.14.0
Requires-Dist: tencentcloud-cls-sdk-python>=1.0.8
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"

# tencentcloud-cls-sdk-langchain

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

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

## 安装

```bash
pip install tencentcloud-cls-sdk-langchain
```

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

## 快速接入

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

```bash
python -m tencentcloud_cls_sdk_langchain.cls_config init
```

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

### 2. 代码接入

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

```python
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 控制台](https://console.cloud.tencent.com/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
