# APMPlus OpenClaw Plugin

OpenClaw 插件，通过 OpenTelemetry 将 OpenClaw 的可观测性数据（Traces、Metrics、Logs）上报至火山引擎 APMPlus 平台。

## 前置条件

- 已安装 [OpenClaw](https://github.com/volcengine/openclaw)
- 已在 [APMPlus 平台](https://console.volcengine.com/observe/apmplus-server/) 创建应用并获取 APP Key

## 安装

### 方式一：使用一键安装 CLI（推荐）

```bash
npx @volcengine/apmplus-openclaw-plugin-onboard-cli
```

按提示输入 Region、APP Key、ServiceName 即可完成安装与配置。

### 方式二：手动安装

```bash
openclaw plugins install @volcengine/apmplus-openclaw-plugin
```

安装后需在 `~/.openclaw/openclaw.json` 中配置插件参数。

## 配置

在 `openclaw.json` 的 `plugins.entries.apmplus-openclaw-plugin.config` 中配置：

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| endpoint | string | 是 | OTLP 上报地址，格式：`http://apmplus-{region}.volces.com/server_collect/third_party/open_telemetry/v2/{appKey}` |
| serviceName | string | 否 | 服务名称，默认 `openclaw` |
| headers | object | 否 | 自定义请求头（如 Authorization） |
| exportIntervalMillis | number | 否 | Metrics 上报间隔（毫秒），默认 30000 |
| debug | boolean | 否 | 是否开启调试日志，默认 false |
| log | boolean | 否 | 是否上报日志，默认 true |
| reportDiagnosticsLog | boolean | 否 | 是否开启诊断日志，默认 false |
| diagnosticsLogEndpoint | string | 否 | 诊断日志自定义 OTLP HTTP 上报地址，若不设置则默认回退到 `endpoint` |
| allowUserDetailInfoReport | boolean | 否 | 是否上报所有 span attr信息，将包含 e.g. user_id, chat detail, chat log 等，默认 true |
| trace | boolean | 否 | 是否启用 trace 上报，默认 true |
| metric | boolean | 否 | 是否启用 metric 上报，默认 true |
| openclawNativeMetrics | boolean | 否 | 是否启用 OpenClaw 原生指标，默认 true |
| extraResourceAttributes | object | 否 | 自定义 Resource Attributes，如 `{"env": "prod"}` |

### 配置示例

```json
{
  "plugins": {
    "allow": ["apmplus-openclaw-plugin"],
    "entries": {
      "apmplus-openclaw-plugin": {
        "enabled": true,
        "config": {
          "endpoint": "http://apmplus-cn-beijing.volces.com/server_collect/third_party/open_telemetry/v2/your-app-key",
          "serviceName": "my-openclaw-service"
        }
      }
    }
  }
}
```

## 支持的 Region

| region_id | 名称 |
|-----------|------|
| cn-beijing | 华北2（北京） |
| cn-shanghai | 华东2（上海） |
| cn-guangzhou | 华南1（广州） |
| cn-hongkong | 中国香港 |
| ap-southeast-1 | 亚太东南（柔佛） |

## License

Apache-2.0，详见 [LICENCE](./LICENCE)。