Scenarios
When executing coding tasks, DeepSeek Harness (DSH) generates runtime data such as sessions, reasoning steps, model calls, and tool calls. You can install the Tencent Cloud Agent Observability plugin tencentcloud-agentobs-sdk-dsh to convert the native DSH lifecycle into Agent Trace data and report it to CLS.
After completing the integration, you can view the following information in Tencent Cloud Agent Observability:
The complete call chain of a single task, and the parent-child relationships among Agents, reasoning steps, model calls, and tool calls.
The execution duration of each step, time to first Token (TTFT), input tokens, output tokens, and cached tokens.
The success status, failure reasons, and retry process of model and tool calls.
The relationships among multiple rounds of tasks within the same session.
This document provides the following two integration methods. You can choose one based on your actual needs:
|
| Use an AI tool that supports Skill to let AI automatically create or reuse log topics, identify the DSH environment, and complete plugin access and analysis. | Use an AI tool that supports Skill and want one-click access with minimal manual configuration. |
| Install the DSH plugin by following the steps, and manually specify parameters such as the region access point, log topic, and key to complete the access. | Require fine-grained control over access parameters, or the tool used does not support Skill. |
Prerequisites
Before you start the integration, make sure you have completed the following preparations:
The integration region has been determined. For example, the Guangzhou region is ap-guangzhou. For method 1, directly enter the Region. For method 2, you also need to obtain the CLS Endpoint corresponding to the region.
Prepared access credentials with CLS log write permissions. We recommend using a CAM sub-account, CAM Role, or temporary key. You can obtain TencentCloud API key information from API Key Management. DSH has been installed, and the DSH version is confirmed to be >=0.1.0-rc.6 <0.2.0.
The Node.js version of the plugin runtime environment must be 18.0.0 or later. For the Node.js version required by DSH itself, refer to the official documentation of the installed DSH version.
Method 1: Quick Integration and Analysis via Skill
If you use an AI tool that supports Skills, you can use the Tencent Cloud Agent Observability Onboarding Assistant to automatically complete the onboarding and analysis. This Skill integrates the onboarding and analysis capabilities, and can automatically create or reuse log topics, identify the DSH environment, and complete plugin installation and configuration. Enter the following content in your AI tool:
Use the Tencent Cloud Agent Observability Onboarding Skill:
https://skillhub.cn/skills/tencentcloud-cls-agent-obs
Help me integrate the current DeepSeek Harness into Tencent Cloud Agent Observability.
Integration method: DeepSeek Harness
Region:ap-guangzhou
Method 2: Manual Configuration for Integration
If you need fine-grained control over parameters such as plugins, log topics, or access credentials, or if your tool does not support Skills, complete the integration manually by following the steps below.
Step 1: Create an Agent Observability Application
Before manual integration, go to the CLS console > Agent Observability. Create an application through Application Integration, click Edit on the right side of the newly created application, and copy its log topic ID (for CLS_TOPIC_ID below). Note:
The Agent Observability application and Trace log topic must be in the same region.
The CLS Endpoint in the plugin configuration must be consistent with the region of the Trace log topic. For example, the Guangzhou region uses ap-guangzhou.cls.tencentcs.com.
Step 2: Install the DSH Plugin
DSH plugins are installed by Profile. Run the corresponding command based on the Profile that is actually in use.
Observability web Profile:
dsh plugin --profile web add tencentcloud-agentobs-sdk-dsh
Observability headless Profile:
dsh plugin --profile headless add tencentcloud-agentobs-sdk-dsh
Observe the harness Profile:
dsh plugin --profile harness add tencentcloud-agentobs-sdk-dsh
pnpm Build Script Issues
pnpm v9 and later may block dependency packages from running install scripts by default. If ERR_PNPM_IGNORED_BUILDS appears, go to the corresponding Profile directory and run the following command:
cd ~/.dsh/profiles/web
echo "enable-scripts=true" >> .npmrc
pnpm install
For the headless or harness Profile, replace the directory name accordingly. After a one-time configuration, subsequent installations or updates typically do not require repeating this step.
Note:
After installing or updating plugins, you must restart the corresponding DSH process for the plugin configuration to take effect.
Step 3: Configure CLS Connection Information
The plugin supports providing connection information through environment variables or the DSH plugin configuration file. Explicit plugin configuration takes precedence over environment variables.
Method 1: Using Environment Variables (Recommended)
Run the following command in the same terminal where DSH is started:
export CLS_ENDPOINT=ap-guangzhou.cls.tencentcs.com
export CLS_TOPIC_ID=<log topic ID>
export CLS_SECRET_ID=<SecretId>
export CLS_SECRET_KEY=<SecretKey>
export CLS_SERVICE_NAME=dsh-agent
The parameters are described as follows:
|
CLS_ENDPOINT
| Yes | Taking the Guangzhou region as an example, public network domain name: ap-guangzhou.cls.tencentyun.com, private network domain name: ap-guangzhou.cls.tencentcs.com. |
CLS_TOPIC_ID
| Yes | Log topic ID obtained in step 1. |
CLS_SECRET_ID
| Yes | |
CLS_SECRET_KEY
| Yes | |
CLS_SERVICE_NAME
| No | Service name, used to distinguish different DSH instances or services in CLS. The default value is deepseek-harness. |
Method 2: Using a Plugin Configuration File
Edit $DSH_HOME/profiles/<profile>/cordis.patch.yml. If DSH_HOME is not set, the default path is typically ~/.dsh/profiles/<profile>/cordis.patch.yml.
Add the following content to the plugin configuration:
- id: cls-observability
config:
enabled: true
endpoint: ap-guangzhou.cls.tencentcs.com
topicId: <Trace log topic ID>
secretId: <SecretId>
secretKey: <SecretKey>
serviceName: dsh-agent
captureContent: true
batchMaxSize: 32
flushIntervalMs: 5000
debug: false
Warning:
Access credentials are sensitive information. We recommend that you inject them through environment variables or secret management tools, and do not commit real SecretId and SecretKey values to code repositories.
Step 4: Start DSH and Generate Test Traces
Using the web Profile as an example, run the following command to start DSH:
After startup is complete, initiate a test task in DSH. We recommend that the test task trigger at least one model invocation. If you also need to verify tool spans, use a non-sensitive test task that triggers file reads, command execution, or other tool invocations.
When the plugin is loaded successfully, the following information will appear in the DSH logs:
[cls-dsh] loaded; endpoint=<CLS Endpoint>; topic=<Topic ID prefix>...; content=enabled
If the configuration is incomplete, the plugin will list the missing configuration items in the log and stop collection, but this will not affect the startup of DSH itself.
Step 5: Verify the Reporting Result
After completing the test task, wait for one refresh cycle. The default refresh interval is 5 seconds.
Verifying in Agent Observability
2. Go to the application created in Step 1. 3. View the latest Trace and confirm that the call tree contains the following Span types:
ENTRY: A request enters DSH.
AGENT: The execution process of the Agent.
STEP: A single ReAct reasoning step.
CHAT: A single actual model call.
TOOL: A single tool call.
4. Select a CHAT Span and confirm that you can view the model name, duration, TTFT, Token usage, and status information.
5. Select a TOOL Span and confirm that you can view the tool name, call duration, and execution status.
Verifying in Search and Analysis
You can also go to the Search and Analysis page of the Trace log topic and execute the following statement to query the latest data:
* | SELECT traceID, spanID, parentSpanID, spanKind, name, durationMs, statusCode
ORDER BY __TIMESTAMP__ DESC
LIMIT 50
Query a specified Trace:
If multiple Spans can be queried under the same Trace, and the parentSpanID can be associated with the corresponding parent Span, the Trace data has been successfully reported.
Common Operations
Disabling Content Collection
By default, the plugin writes prompts, model responses, tool parameters, and tool results into Spans. For environments containing source code, credentials, or personal data, you are advised to disable content collection and retain only the call structure, duration, status, and Token usage.
Disable it through an environment variable:
export OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=false
Disable it through plugin configuration:
- id: cls-observability
config:
captureContent: false
Note:
Explicit plugin configuration takes precedence over environment variables.
Update a plugin
Run the following command to update the installed plugins in the corresponding Profile:
dsh plugin --profile web update
For the headless or harness Profile, replace the --profile parameter. After the update is complete, restart the corresponding DSH process.
Uninstalling a Plugin
Only the Profiles with installed plugins need to be uninstalled. Run the following command based on the actually installed 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
Related Instructions
Description
|
enabled
| true
| Whether to enable collection. When set to false, collection stops without uninstalling the plugin. |
endpoint
| CLS_ENDPOINT
| CLS API endpoint. |
topicId
| CLS_TOPIC_ID
| Trace log topic ID. |
secretId
| CLS_SECRET_ID
| Tencent Cloud access credential SecretId. |
secretKey
| CLS_SECRET_KEY
| Tencent Cloud access credential SecretKey. |
serviceName
| deepseek-harness
| Service name. |
resourceAttributes
| {}
| Custom resource attributes written to spans. Both keys and values are strings. |
captureContent
| true
| Whether to collect prompts, model responses, tool parameters, and tool results. |
contentMaxChars
| 128000
| Maximum number of characters retained for a single content attribute. Characters beyond this limit are truncated. |
batchMaxSize
| 32
| Maximum number of spans reported in a single batch. |
maxQueueSize
| 2048
| Maximum number of spans in the memory queue. When the limit is exceeded, the plugin discards the earliest data to avoid blocking DSH. |
flushIntervalMs
| 5000
| Scheduled flush interval in milliseconds. |
retryTimes
| 3
| Number of request retries for the CLS SDK. |
debug
| false
| Whether to output plugin debug logs. |
Span Structure Description
The plugin treats each DSH Turn as a Trace and associates multiple Traces in the same session through sessionID.
ENTRY
└── AGENT
└── STEP
├── CHAT
└── TOOL
|
ENTRY
| enter_application
| A request enters DSH and serves as the root Span of the current Trace. |
AGENT
| invoke_agent {agentName}
| Agent execution process, summarizing the model, Token, and end status of this Turn. |
STEP
| react round_{step}
| One ReAct reasoning step. |
CHAT
| chat {model}
| One actual model call. A model retry generates a new CHAT Span and does not merge it with the previous one. |
TOOL
| execute_tool {toolName}
| One tool call, including the tool name, call ID, duration, and status. |
Note:
Model calls within DSH for context compression and session title generation do not generate CHAT Spans, preventing internal framework calls from affecting business-side model call statistics.
FAQs
Plugins Are Installed but No Trace Data in CLS
Check in the following order:
1. Confirm that the plugin is installed in the currently running Profile.
2. After installing or modifying the configuration, confirm that the DSH process has been restarted.
3. Check the DSH logs to confirm that the [cls-dsh] loaded message is present and that there are no configuration missing warnings.
4. Confirm that CLS_ENDPOINT is in the same region as the Trace log topic.
5. Confirm that CLS_TOPIC_ID is the log topic ID, not the Agent Observability application ID.
6. Confirm that the access credential has the permission to write data to the target log topic.
7. Confirm that the current environment can access the configured CLS Endpoint.
8. After completing the test task, wait for at least one refresh cycle before querying the data.
To view more plugin runtime information, you can temporarily set debug: true, and after restarting DSH, check the logs that start with [cls-dsh].
No Prompts, Responses, or Tool Parameters in Trace
Check the following configuration:
Is captureContent in the plugin configuration set to false?
Is the environment variable OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT set to false, no, off, disabled, or 0?
Disabling content capture does not affect the reporting of call trees, latency, status, or Token usage.
Two Similar Traces in the Same DSH Task
Check whether multiple DSH Trace reporting paths are enabled at the same time, for example, the CLS DSH plugin is enabled together with other collectors or OTLP plugins, and data is sent to the same log topic. Except for controlled verification, it is recommended to keep only one Trace reporting path for a single DSH instance.
Some Internal DSH Model Calls Not Displayed in Trace
This is expected behavior. The plugin ignores internal model calls used for context compaction and session title generation, and only collects model calls made during actual task execution.