# OpenClaw Telemetry Galileo (Embedded)

开发者内嵌版伽利略遥测插件，将 OpenClaw 所有调用链路（LLM / Tool / Subagent）串联为完整 OTLP trace，按伽利略 Agent 协议上报 trace、metrics 和日志。

## 功能特性

- **Trace 上报**：自动采集 Agent、LLM、Tool、Subagent 调用链路，生成完整的 OTLP trace
- **Metrics 上报**：自动统计 LLM Chat、Tool 执行、Agent 调用的性能指标
- **日志上报**：支持文件轮询方式采集日志并通过 OTLP 上报
- **自定义配置**：支持配置用户名（userId）和自定义 trace 属性（customAttributes）

## 接入指引

详细的接入指引请参考：[伽利略遥测插件接入文档](https://iwiki.woa.com/p/4018955842?from=recent_view)

## 配置

插件从 `galileo.config.json` 文件读取配置，安装后需根据实际环境修改该文件。

### 配置示例

```json
{
  "galileo": {
    "enabled": true,
    "endpoint": "http://otlp.j.woa.com:80",
    "resource": {
      "target": "你的 target",
      "namespace": "Production",
      "env": "formal",
      "server": "openclaw.agent",
      "containerName": "",
      "operator": "",
      "setName": ""
    },
    "genAi": {
      "system": "openclaw",
      "appName": "openclaw",
      "agentName": "openclaw-agent",
      "agentId": "openclaw-agent-001"
    },
    "trace": {
      "enabled": true
    },
    "metrics": {
      "enabled": true
    },
    "logs": {
      "enabled": true,
      "filePath": "/tmp/openclaw/openclaw-{date}.log",
      "level": "INFO"
    },
    "userId": "你的用户ID",
    "customAttributes": {
      "your_key": "your_value"
    }
  }
}
```

### 配置项说明

| 配置项                     | 说明                                                           |
| -------------------------- | -------------------------------------------------------------- |
| `galileo.enabled`          | 是否启用插件                                                   |
| `galileo.endpoint`         | OTLP 上报地址                                                  |
| `galileo.resource`         | 伽利略资源信息（target、namespace、env 等）                    |
| `galileo.genAi`            | GenAI 信息（system、appName、agentName、agentId）              |
| `galileo.trace.enabled`    | 是否启用 trace 上报                                            |
| `galileo.metrics.enabled`  | 是否启用 metrics 上报                                          |
| `galileo.logs.enabled`     | 是否启用日志上报                                               |
| `galileo.logs.filePath`    | 日志文件路径，支持 `{date}` 占位符                             |
| `galileo.logs.level`       | 日志级别（DEBUG / INFO / WARN / ERROR）                        |
| `galileo.userId`           | 用户 ID，用于标识上报来源                                      |
| `galileo.customAttributes` | 自定义 trace 属性，key-value 形式，上报时自动加 `custom.` 前缀 |

## Trace 链路关系

```
invoke_agent {agentName} (root span, per before_agent_start → agent_end)
  ├── chat {model}         (llm_input → llm_output, 包含完整 prompt/response)
  ├── execute_tool {name}  (before_tool_call → after_tool_call, 包含 params/result)
  └── invoke_agent {id}    (subagent_spawned → subagent_ended)
```

## Metrics 监控项

| 指标类型             | 说明                                   | 上报时机                 |
| -------------------- | -------------------------------------- | ------------------------ |
| **LLMClient (Chat)** | LLM 调用指标，包含 token 用量、延迟等  | `llm_output` 时上报      |
| **GenAIExecuteTool** | Tool 执行指标，包含耗时、成功/失败状态 | `after_tool_call` 时上报 |
| **GenAIInvokeAgent** | Agent 调用指标，包含累计 token、总耗时 | `agent_end` 时上报       |

## 运行时 API

插件导出了以下接口，可在运行时动态设置用户 ID 和自定义属性：

```typescript
import {
  setUserId,
  getUserId,
  setCustomAttributes,
  getCustomAttributes,
} from "@tencent/openclaw-telemetry-galileo-embedded";

// 设置用户 ID
setUserId("your-user-id");

// 设置自定义属性（会以 custom. 前缀注入到 span 中）
setCustomAttributes({ team: "my-team", project: "my-project" });
```
