OpenCode Agent

OpenCode Agent运行时
  ├── 加载opencode-metrics插件（plugin.mjs）
  │     ├── 采集Agent调用事件
  │     ├── 采集模型调用事件
  │     └── 采集工具调用事件
  │
  ├── Trace数据 ──OTLP gRPC──→ APM（调用链）
  └── Metrics数据 ──OTLP gRPC──→ AOM（指标）
                                         │
                                         ▼
                               AgentArts观测平台展示

步骤一：获取接入参数

1. 登录AgentArts 智能体平台。
2. 在左侧导航栏选择“观测与优化 > 观测”。
3. 在“智能体列表”页面，单击“接入智能体”，按照页面指引填写名称、智能体类型，创建一个“OpenCode”智能体，并获取各配置参数。
   图1 获取配置参数
   

步骤二：安装插件

OpenCode Metrics插件提供两种部署方式，可任选其一：

• 方式一（推荐）：通过pip安装whl包，使用install.py脚本一键部署。适合希望自动化完成文件复制、配置生成的场景。
• 方式二：手动放置构建产物文件（plugin.mjs、package.json、config.json文件）到对应目录。适合已获取构建产物、希望手动控制部署过程的场景。

无论采用哪种路径，部署完成后的最终文件布局完全一致：

~/.config/opencode/
└── opencode.json                     # OpenCode主配置（首次启动OpenCode后自动生成，追加插件注册）

~/.opencode/
└── plugins/
    └── opencode-metrics/
        ├── plugin.mjs                # 插件主程序（自包含全部依赖）
        └── package.json              # 插件元数据

~/.opencode-metrics/                  # 插件数据/配置根目录
├── config.json                       # 插件配置（含OTel上报参数）
└── data/
    └── logs/
        └── plugin-YYYY-MM-DD.log     # 插件运行日志（按天滚动，自动创建）

方式一：whl包 + install.py一键部署（推荐）

1. 安装探针包。

   下载OpenCode探针包，将探针包复制到目标节点，执行以下命令安装：

   pip install huaweicloud_opentelemetry_instrumentation_opencode-1.0.0-py3-none-any.whl --force-reinstall

   执行后，whl包内的文件（含plugin.mjs、config.example.json、scripts/install.py等）会被释放到Python安装目录的site-packages目录下，具体位置是：

   <site-packages>/opencode_metrics/

   其中<site-packages>是Python安装第三方库的目录。可用以下命令确认它的实际路径：

   python -c "import sysconfig; print(sysconfig.get_paths()['purelib'])"

2. 运行install.py一键安装。

   install.py位于<site-packages>/opencode_metrics/scripts/install.py路径下。执行以下命令完成安装，命令中的参数按实际替换。

   参数获取方法参考步骤一：获取接入参数。

   Linux / macOS（bash）

   python <site-packages路径>/opencode_metrics/scripts/install.py \
     --agent-id {{agent_id}} \
     --domain-id {{domain_id}} \
     --project-id {{project_id}} \
     --endpoint {{trace_endpoint}} \
     --token {{trace_token}} \
     --aom-endpoint {{metric_endpoint}} \
     --aom-access-code {{metric_token}} \
     --aom-prometheus-id {{prom_id}} \
     --resource-type {{agent|multiagents|workflow}}

   Windows（PowerShell）

   python <site-packages路径>/opencode_metrics/scripts/install.py `
     --agent-id {{agent_id}} `
     --domain-id {{domain_id}} `
     --project-id {{project_id}} `
     --endpoint {{trace_endpoint}} `
     --token {{trace_token}} `
     --aom-endpoint {{metric_endpoint}} `
     --aom-access-code {{metric_token}} `
     --aom-prometheus-id {{prom_id}} `
     --resource-type {{agent|multiagents|workflow}}

   表1 参数说明

   参数	是否必选	说明
   --agent-id	是	智能体ID。
   --domain-id	是	账号domain ID。
   --project-id	是	华为云项目ID。
   --endpoint	是	APM数据上报地址。
   --token	是	APM接入凭证Token。
   --aom-endpoint	条件必填（上报指标数据时必填）	AOM数据上报地址。
   --aom-access-code	条件必填（上报指标数据时必填）	AOM接入凭证Access Code。
   --aom-prometheus-id	条件必填（上报指标数据时必填）	AOM Prometheus实例ID。
   --resource-type	是	智能体类型：agent（单智能体）、multiagents（多智能体）、workflow（工作流）。

   install.py自动完成以下操作：

   • 定位plugin.mjs并复制到~/.opencode/plugins/opencode-metrics/目录。
   • 生成插件元数据package.json。
   • 使用传入的参数值生成config.json并写入~/.opencode-metrics/目录。
   • 打印opencode.json中需要追加的plugin配置（file:// URL自动适配Windows/Linux）。

3. 在opencode.json中注册插件并重启OpenCode。

   按照install.py打印的提示，将plugin配置追加到~/.config/opencode/opencode.json中（详细步骤参考方式二的第3步），然后重启OpenCode即可。

方式二：手动放置构建产物文件

本方式适用于已经获取到构建产物（plugin.mjs + package.json + config.json）的情况。适合希望手动控制文件来源的场景。

下载OpenCode探针包，将探针包复制到目标节点，执行以下命令安装：

pip install huaweicloud_opentelemetry_instrumentation_opencode-1.0.0-py3-none-any.whl

执行后，whl包内的文件（含plugin.mjs、config.example.json、scripts/install.py等）会被释放到Python安装目录的site-packages目录下，具体位置是：

<site-packages>/opencode_metrics/

构建产物包含以下文件：

• plugin.mjs：插件主程序
• package.json：插件元数据
• config.json或config.example.json：插件配置模板

1. 创建插件目录。

   Linux / macOS（bash）

   # 插件安装目录（存放plugin.mjs和package.json）
   mkdir -p ~/.opencode/plugins/opencode-metrics
   # 插件数据目录（运行时日志输出到data/logs/plugin-YYYY-MM-DD.log）
   mkdir -p ~/.opencode-metrics/data/logs

   Windows（PowerShell）

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.opencode\plugins\opencode-metrics" | Out-Null
   New-Item -ItemType Directory -Force "$env:USERPROFILE\.opencode-metrics\data\logs" | Out-Null

2. 放置插件文件。

   将获取到的三个文件分别放置到对应目录：

   # 插件主程序（esbuild单文件，自包含全部依赖）
   cp plugin.mjs ~/.opencode/plugins/opencode-metrics/
   # 插件元数据（OpenCode通过它识别插件，main字段必须与plugin.mjs同名）
   cp package.json ~/.opencode/plugins/opencode-metrics/
   # 插件配置（含OTel上报参数，需按实际环境修改）
   cp config.json ~/.opencode-metrics/

3. 在opencode.json中注册插件。
   • 确认opencode.json文件是否存在。

     正常安装OpenCode后，会自动生成opencode.json文件，该文件是OpenCode的全局主配置文件，位于用户配置目录（注意：是~/.config/opencode/，不是~/.opencode/）：

     • Linux/macOS路径：~/.config/opencode/opencode.json
     • Windows路径：<用户主目录>\.config\opencode\opencode.json

     执行以下命令确认文件是否存在：

     Linux / macOS（bash）

     ls ~/.config/opencode/opencode.json

     Windows（PowerShell）

     Get-Item "$env:USERPROFILE\.config\opencode\opencode.json"

   • 若文件不存在，创建目录和文件：

     Linux / macOS（bash）

     mkdir -p ~/.config/opencode
     touch ~/.config/opencode/opencode.json

     Windows（PowerShell）

     New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\opencode" | Out-Null
     New-Item -ItemType File -Force "$env:USERPROFILE\.config\opencode\opencode.json" | Out-Null

   • 编辑opencode.json，在文件中追加plugin数组配置（注意是追加，不要覆盖文件里已有的其他字段）。

     {
       "$schema": "https://opencode.ai/config.json",
       "plugin": [
         "file://C:/Users/<用户名>/.opencode/plugins/opencode-metrics/plugin.mjs"
       ]
     }

     路径格式说明：

   • Windows：file://C:/Users/...。使用正斜杠，盘符后没有额外的斜杠。
   • macOS/Linux：file:///Users/<用户名>/.opencode/plugins/opencode-metrics/plugin.mjs。注意是三个斜杠。

4. 重启OpenCode。

步骤三：验证数据上报

数据上报成功后，可在AgentArts平台中查看观测数据。

1. 验证OpenCode Metrics插件是否正常加载。

   重启OpenCode后，执行以下命令检查插件是否加载成功：

   # 列出插件日志文件（按天滚动），确认日志目录已生成
   ls -la ~/.opencode-metrics/data/logs/plugin-*.log
   
   # 查看最近 20 行日志，确认插件初始化成功，无报错
   tail -20 ~/.opencode-metrics/data/logs/plugin-*.log

   正常情况下，日志应包含以下关键信息：

   • [opencode-metrics] OTel init config: {...}：初始化配置加载成功
   • [opencode-metrics] AsyncLocalStorageContextManager registered：上下文管理器注册成功
   • [opencode-metrics] APM (Traces) initialized：APM Trace初始化成功
   • [opencode-metrics] AOM (Metrics) initialized：AOM Metrics初始化成功

2. 触发OpenCode会话，验证数据上报。

   在OpenCode中做一轮问答后，触发数据上报，然后执行以下命令查看日志：

   tail -50 ~/.opencode-metrics/data/logs/plugin-*.log

   正常情况下，日志应包含以下关键信息：

   • OTel processTurn: <turnId> events: N：事件采集成功
   • APM (Traces) export SUCCESS {spanCount: N, ...}：Trace上报成功
   • AOM (Metrics) export SUCCESS {totalDataPoints: N, ...}：Metrics上报成功（按collectInterval周期，默认每30秒一次）
   • AOM All Metric Details: {...}：上报属性明细（仅当features.debug: true时打印）

配置参数说明

插件安装后，所有配置集中在~/.opencode-metrics/config.json中。一键部署（方式一）由install.py自动生成，手动部署（方式二）需手动编辑。

config.json是OpenCode Metrics插件的核心配置文件，包含OTel上报参数、功能开关等。完整配置模板如下：

{
  "version": "3.0.0",
  // 插件总开关
  "enabled": true,
  // 日志输出目录（兼容多种路径写法：/d/data/example、D:/data/example、D:\\data\\example）
  "outputDir": "/d/codezone",
  // 用户ID（注入user.id）：为空或不设置则兜底使用主机名
  "user.id": "",
  // 采集周期（毫秒）：每隔多久从内存缓冲采集并上报一次事件，默认30000（30秒）
  "collectInterval": 30000,
  "features": {
    "debug": false,                 // debug日志开关，默认false
    "captureMessageContent": true   // 是否采集trace输入/输出消息内容，默认true
  },
  // ============ OTel上报配置（AgentArts） ============
  "otel": {
    "agentarts_agentops_otel_agent_apm_enable": true,
    "agentarts_agentops_otel_agent_aom_enable": true,
    "agent_domain_id": "<AGENT_DOMAIN_ID>",
    "agentarts_project_id": "<AGENTARTS_PROJECT_ID>",
    "agent_resource_id": "<AGENT_RESOURCE_ID>",
    "resource_type": "<AGENT_TYPE>",
    "agentarts_agentops_apm_token": "<APM_TOKEN>",
    "agentarts_agentops_apm_exporter_endpoint": "<APM_ENDPOINT>",
    "agentarts_agentops_aom_access_code": "<AOM_ACCESS_CODE>",
    "agentarts_agentops_aom_exporter_endpoint": "<AOM_ENDPOINT>",
    "agentarts_agentops_aom_prometheus_id": "<AOM_PROMETHEUS_ID>"
  }
}

"features": {
  "captureMessageContent": false
}

"features": {
  "debug": true
}

"user.id": "<your-user-id>"