tencent cloud

日志服务

文档日志服务Agent 可观测接入指南接入 DeepSeek Harness 数据

接入 DeepSeek Harness 数据

Download
聚焦模式
字号
最后更新时间： 2026-08-21 17:40:49

操作场景

DeepSeek Harness（以下简称 DSH）在执行编码任务时，会产生会话、推理步骤、模型调用和工具调用等运行数据。您可以安装腾讯云 Agent 可观测插件 tencentcloud-agentobs-sdk-dsh，将 DSH 原生生命周期转换为 Agent Trace 数据并上报到日志服务（Cloud Log Service，CLS）。
完成接入后，您可以在腾讯云 Agent 可观测中查看以下信息：
单次任务的完整调用链路，以及 Agent、推理步骤、模型调用和工具调用之间的父子关系。
各步骤的执行耗时、模型首字延迟（TTFT）、输入 Token、输出 Token 和缓存 Token。
模型与工具调用的成功状态、失败原因和重试过程。
同一会话下多轮任务的关联关系。
本文提供以下两种接入方式，您可根据实际情况选择：
接入方式
说明
推荐场景
使用支持 Skill 的 AI 工具，由 AI 自动创建或复用日志主题、识别 DSH 环境并完成插件接入与分析。
使用支持 Skill 的 AI 工具，希望一键接入、减少手动配置。
按步骤安装 DSH 插件，手动填写地域接入点、日志主题、密钥等参数完成接入。
需要精细化控制接入参数，或所用工具不支持 Skill。

前提条件

开始接入前，请确保已完成以下准备工作：
已开通 日志服务 CLS。
已确定接入地域（Region），例如广州地域为 ap-guangzhou。方式一直接填写 Region；方式二还需获取该地域对应的 CLS Endpoint。
已准备具备 CLS 日志写入权限的访问凭证。建议使用 CAM 子账号、CAM Role 或临时密钥。云 API 密钥信息可前往 API 密钥管理 获取。
已安装 DSH，并确认 DSH 版本为 >=0.1.0-rc.6 <0.2.0。
插件运行环境的 Node.js 版本为 18.0.0 或更高版本。DSH 本身的 Node.js 版本要求请以所安装 DSH 版本的官方说明为准。

方式一：通过 Skill 快速接入与分析

如果您使用支持 Skill 的 AI 工具，可使用 腾讯云 Agent 可观测接入助手 自动完成接入与分析。该 Skill 已合并接入与分析能力，可自动创建或复用日志主题、识别 DSH 环境并完成插件安装和配置。
在 AI 工具中输入以下内容：
请使用腾讯云 Agent 可观测接入 Skill：
https://skillhub.cn/skills/tencentcloud-cls-agent-obs

帮我把当前 DeepSeek Harness 接入腾讯云 Agent 可观测。

接入方式：DeepSeek Harness
Region：ap-guangzhou

方式二：手动配置接入

如果您需要精细化控制插件、日志主题或访问凭证等参数，或者所用工具不支持 Skill，请按以下步骤手动完成接入。

步骤1：创建 Agent 可观测应用

手动接入前，请先进入 日志服务控制台 > Agent 可观测，通过应用接入创建应用，并在新创建的应用右侧单击编辑，复制其日志主题 ID（用于下方 CLS_TOPIC_ID）。
说明：
Agent 可观测应用和 Trace 日志主题必须位于同一地域。
插件配置中的 CLS Endpoint 必须与 Trace 日志主题所在地域一致。例如，广州地域使用 ap-guangzhou.cls.tencentcs.com。

步骤2：安装 DSH 插件

DSH 插件按 Profile 安装。请根据实际运行的 Profile 执行对应命令。
观测 web Profile：
dsh plugin --profile web add tencentcloud-agentobs-sdk-dsh
观测 headless Profile：
dsh plugin --profile headless add tencentcloud-agentobs-sdk-dsh
观测 harness Profile：
dsh plugin --profile harness add tencentcloud-agentobs-sdk-dsh

pnpm 构建脚本问题

pnpm v9及以上版本可能默认禁止依赖包运行 install 脚本。如果出现 ERR_PNPM_IGNORED_BUILDS，请进入对应 Profile 目录执行：
cd ~/.dsh/profiles/web
echo "enable-scripts=true" >> .npmrc
pnpm install
headless 或 harness Profile 请替换目录名称。完成一次配置后，后续安装或更新通常无需重复执行。
注意：
安装或更新插件后，需要重启对应的 DSH 进程，插件配置才能生效。

步骤3：配置 CLS 连接信息

插件支持通过环境变量或 DSH 插件配置文件提供连接信息。显式插件配置的优先级高于环境变量。

方式一：使用环境变量（推荐）

在启动 DSH 的同一终端中执行以下命令：
export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.com
export CLS_TOPIC_ID=<日志主题 ID>
export CLS_SECRET_ID=<SecretId>
export CLS_SECRET_KEY=<SecretKey>
export CLS_SERVICE_NAME=dsh-agent
参数说明如下：
环境变量
是否必填
说明
CLS_ENDPOINT
是
CLS 地域接入点域名，请参见 地域和访问域名。
以广州地域为例，外网域名：ap-guangzhou.cls.tencentyun.com，内网域名：ap-guangzhou.cls.tencentcs.com。
CLS_TOPIC_ID
是
步骤 1 中获取的日志主题 ID。
CLS_SECRET_ID
是
腾讯云访问凭证 SecretId，可前往 API 密钥管理 获取。
CLS_SECRET_KEY
是
腾讯云访问凭证 SecretKey。可前往 API 密钥管理 获取。
CLS_SERVICE_NAME
否
服务名称，用于在 CLS 中区分不同 DSH 实例或业务。默认值为 deepseek-harness。

方式二：使用插件配置文件

编辑 $DSH_HOME/profiles/<profile>/cordis.patch.yml。如果未设置 DSH_HOME，默认路径通常为 ~/.dsh/profiles/<profile>/cordis.patch.yml。
在插件配置中添加以下内容：
- id: cls-observability
  config:
    enabled: true
    endpoint: ap-guangzhou.cls.tencentcs.com
    topicId: <Trace 日志主题 ID>
    secretId: <SecretId>
    secretKey: <SecretKey>
    serviceName: dsh-agent
    captureContent: true
    batchMaxSize: 32
    flushIntervalMs: 5000
    debug: false
警告：
访问凭证属于敏感信息。建议优先通过环境变量或密钥管理工具注入，不要将真实 SecretId 和 SecretKey 提交到代码仓库。

步骤4：启动 DSH 并生成测试 Trace

以 web Profile 为例，执行以下命令启动 DSH：
dsh --profile web
启动完成后，在 DSH 中发起一次测试任务。建议测试任务至少触发一次模型调用；如需同时验证工具 Span，可使用会触发文件读取、命令执行或其他工具调用的无敏感测试任务。
插件加载成功时，DSH 日志中将出现以下信息：
[cls-dsh] loaded; endpoint=<CLS Endpoint>; topic=<Topic ID 前缀>...; content=enabled
如果配置不完整，插件会在日志中列出缺失的配置项并停止采集，但不会影响 DSH 本身启动。

步骤5：验证上报结果

完成测试任务后，等待一个刷新周期。默认刷新间隔为5秒。

在 Agent 可观测中验证

1. 登录 日志服务控制台 > Agent 可观测。
2. 进入 步骤1 创建的应用。
3. 查看最新 Trace，并确认调用树中包含以下 Span 类型：
ENTRY：一次请求进入 DSH。
AGENT：Agent 执行过程。
STEP：一次 ReAct 推理步骤。
CHAT：一次实际模型调用。
TOOL：一次工具调用。
4. 选择 CHAT Span，确认可查看模型名称、耗时、TTFT、Token 用量和状态信息。
5. 选择 TOOL Span，确认可查看工具名称、调用耗时和执行状态。

在检索分析中验证

也可以进入 Trace 日志主题的 检索分析 页面，执行以下语句查询最新数据：
* | SELECT traceID, spanID, parentSpanID, spanKind, name, durationMs, statusCode
    ORDER BY __TIMESTAMP__ DESC
    LIMIT 50
查询指定 Trace：
traceID:"<Trace ID>"
如果同一 Trace 下可以查询到多个 Span，且 parentSpanID 能够关联到对应父 Span，表示 Trace 数据已成功上报。

常用操作

关闭内容采集

默认情况下，插件会将提示词、模型回复、工具参数和工具结果写入 Span。对于包含源代码、凭证或个人数据的环境，建议关闭内容采集，仅保留调用结构、耗时、状态和 Token 用量。
通过环境变量关闭：
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false
通过插件配置关闭：
- id: cls-observability
  config:
    captureContent: false
说明：
显式插件配置优先于环境变量。

更新插件

执行以下命令更新对应 Profile 中已安装的插件：
dsh plugin --profile web update
headless 或 harness Profile 请替换 --profile 参数。更新完成后，请重启对应的 DSH 进程。

卸载插件

仅需卸载已安装插件的 Profile。根据实际安装的 Profile 执行以下命令：
dsh plugin --profile web remove tencentcloud-agentobs-sdk-dsh
dsh plugin --profile headless remove tencentcloud-agentobs-sdk-dsh
dsh plugin --profile harness remove tencentcloud-agentobs-sdk-dsh

相关说明

配置项说明

配置项
默认值
说明
enabled
true
是否启用采集。设置为 false 时，无需卸载插件即可停止采集。
endpoint
CLS_ENDPOINT
CLS API 接入点。
topicId
CLS_TOPIC_ID
Trace 日志主题 ID。
secretId
CLS_SECRET_ID
腾讯云访问凭证 SecretId。
secretKey
CLS_SECRET_KEY
腾讯云访问凭证 SecretKey。
serviceName
deepseek-harness
服务名称。
resourceAttributes
{}
写入 Span 的自定义资源属性，键和值均为字符串。
captureContent
true
是否采集提示词、模型回复、工具参数与工具结果。
contentMaxChars
128000
单个内容属性保留的最大字符数，超出部分将被截断。
batchMaxSize
32
单次批量上报的最大 Span 数量。
maxQueueSize
2048
内存队列的最大 Span 数量。超过上限时，插件将丢弃最早的部分数据，避免阻塞 DSH。
flushIntervalMs
5000
定时刷新间隔，单位为毫秒。
retryTimes
3
CLS SDK 的请求重试次数。
debug
false
是否输出插件调试日志。

Span 结构说明

插件以一次 DSH Turn 为一条 Trace，并通过 sessionID 关联同一会话中的多轮 Trace。
ENTRY
└── AGENT
    └── STEP
        ├── CHAT
        └── TOOL
Span 类型
名称格式
说明
ENTRY
enter_application
一次请求进入 DSH，是当前 Trace 的根 Span。
AGENT
invoke_agent {agentName}
Agent 执行过程，汇总该 Turn 的模型、Token 和结束状态。
STEP
react round_{step}
一次 ReAct 推理步骤。
CHAT
chat {model}
一次实际模型调用。模型重试会生成新的 CHAT Span，不会与前一次合并。
TOOL
execute_tool {toolName}
一次工具调用，包含工具名称、调用 ID、耗时和状态。
说明：
DSH 内部用于上下文压缩和会话标题生成的模型调用不会生成 CHAT Span，避免框架内部调用影响业务侧模型调用统计。

常见问题

插件已安装，但 CLS 中没有 Trace 数据

请按以下顺序检查：
1. 确认插件安装在当前正在运行的 Profile 中。
2. 安装或修改配置后，确认已重启 DSH 进程。
3. 查看 DSH 日志，确认存在 [cls-dsh] loaded 信息，且没有配置缺失提示。
4. 确认 CLS_ENDPOINT 与 Trace 日志主题位于同一地域。
5. 确认 CLS_TOPIC_ID 为日志主题 ID，而不是 Agent 可观测应用 ID。
6. 确认访问凭证具备向目标日志主题写入数据的权限。
7. 确认当前环境能够访问所配置的 CLS Endpoint。
8. 完成测试任务后，等待至少一个刷新周期再查询数据。
如需查看更多插件运行信息，可临时设置 debug: true，重启 DSH 后查看以 [cls-dsh] 开头的日志。

Trace 中没有提示词、回复或工具参数

请检查以下配置：
插件配置中的 captureContent 是否设置为 false。
环境变量 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 是否设置为 false、no、off、disabled 或 0。
关闭内容采集不会影响调用树、耗时、状态和 Token 用量的上报。

同一个 DSH 任务出现两条相似 Trace

请检查是否同时启用了多个 DSH Trace 上报路径，例如同时启用了 CLS DSH 插件和其他采集器或 OTLP 插件，并将数据发送到同一个日志主题。除对照验证外，建议同一个 DSH 实例仅保留一条 Trace 上报路径。

部分 DSH 内部模型调用未显示在 Trace 中

这是预期行为。插件会忽略用于上下文压缩（compaction）和会话标题生成（session title）的内部模型调用，仅采集实际任务执行过程中的模型调用。

上一篇: 查看 Agent 可观测应用详情下一篇: 使用 Langfuse SDK 上报 Trace 数据到 CLS

帮助和支持

本页内容是否解决了您的问题？

填写满意度调查问卷，共创更好文档体验。

文档反馈