日志服务 接入 DeepSeek Harness 数据

一、操作场景

完成接入后，你可以在腾讯云 Agent 可观测中查看以下信息：

·单次任务的完整调用链路，以及 Agent、推理步骤、模型调用和工具调用之间的父子关系。

·各步骤的执行耗时、模型首字延迟（TTFT）、输入 Token、输出 Token 和缓存 Token。

·模型与工具调用的成功状态、失败原因和重试过程。

·同一会话下多轮任务的关联关系。

这篇提供以下两种接入方式，你可根据实际情况选择：

二、前提条件

开始接入前，请确保已完成以下准备工作：

·已开通 AgentObs（Agent 可观测）。

·已确定接入地域（Region），例如广州地域为 ap-guangzhou。方式一直接填写 Region；方式二还需获取该地域对应的 Endpoint。

·已准备具备日志写入权限的访问凭证。建议使用 CAM 子账号、CAM Role 或临时密钥。云 API 密钥信息可前往 API 密钥管理 获取，密钥需对目标主题有写入权限，权限模板参见 采集 Agent 可观测数据。

·已安装 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 HarnessRegion：ap-guangzhou

四、方式二：手动配置接入

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

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

手动接入前，请先进入 Agent 可观测，通过应用接入创建应用，并在新创建的应用右侧单击编辑，复制其日志主题 ID（用于下方 CLS_TOPIC_ID）。

注意：说明：

六、步骤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/webecho "enable-scripts=true" >> .npmrcpnpm install

headless 或 harness Profile 请替换目录名称。完成一次配置后，后续安装或更新通常无需重复执行。

注意：安装或更新插件后，需要重启对应的 DSH 进程，插件配置才能生效。

八、步骤3：配置连接信息

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

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

在启动 DSH 的同一终端中执行以下命令：

export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.comexport CLS_TOPIC_ID=<日志主题 ID>export CLS_SECRET_ID=<SecretId>export CLS_SECRET_KEY=<SecretKey>export CLS_SERVICE_NAME=dsh-agent

参数说明如下：

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

编辑 $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-dshdsh plugin –profile headless remove tencentcloud-agentobs-sdk-dshdsh plugin –profile harness remove tencentcloud-agentobs-sdk-dsh

20、配置项说明

21、Span 结构说明

插件以一次 DSH Turn 为一条 Trace，并通过 sessionID 关联同一会话中的多轮 Trace。

ENTRY└── AGENT └── STEP ├── CHAT └── TOOL

注意：说明：

注意：DSH 内部用于上下文压缩和会话标题生成的模型调用不会生成 CHAT Span，避免框架内部调用影响业务侧模型调用统计。

23、插件已安装，但 AgentObs 中没有 Trace 数据

请按以下顺序检查：

1. 确认插件安装在当前正在运行的 Profile 中。

2. 安装或修改配置后，确认已重启 DSH 进程。

3. 查看 DSH 日志，确认存在 [cls-dsh] loaded 信息，且没有配置缺失提示。

4. 确认 CLS_ENDPOINT 与 Trace 日志主题位于同一地域。

5. 确认 CLS_TOPIC_ID 为日志主题 ID，而不是 Agent 可观测应用 ID。

6. 确认访问凭证具备向目标日志主题写入数据的权限。

7. 确认当前环境能够访问所配置的 Endpoint。

8. 完成测试任务后，等待至少一个刷新周期再查询数据。

如需查看更多插件运行信息，可临时设置 debug: true，重启 DSH 后查看以 [cls-dsh] 开头的日志。

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

请检查以下配置：

·插件配置中的 captureContent 是否设置为 false。

·环境变量 OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT 是否设置为 false、no、off、disabled 或 0。

关闭内容采集不会影响调用树、耗时、状态和 Token 用量的上报。

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

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

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

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