Harness AutoExecutor V3 + Telemetry 系统上线

发布时间：2026-03-31 重点：OpenTelemetry 兼容的数据记录系统

---

一、核心改进

版本	特性
V1	基础 AutoExecutor
V2	sessions_spawn 真执行
V3	Telemetry Enabled ✅

V3 新特性

1. OpenTelemetry 兼容

   • Trace: 任务执行的完整链路
   • Metric: 执行时间、成功率、任务数量
   • Log: 结构化事件日志

2. 数据持久化

   • MySQL: harness_traces + harness_metrics + harness_logs
   • JSONL: 本地 events.jsonl 文件
   • 后续接入 OpenTelemetry 只需替换 exporter

3. 完整监控

   • 每个操作都有 span 记录
   • 关键事件都有 log 记录
   • 执行指标都有 metric 记录

---

二、数据表结构

harness_traces (链路追踪)

CREATE TABLE harness_traces ( trace_id VARCHAR(64), span_id VARCHAR(64), parent_span_id VARCHAR(64), operation_name VARCHAR(255), start_time DATETIME, end_time DATETIME, duration_ms INT, status VARCHAR(20), attributes JSON, events JSON );

harness_metrics (指标)

CREATE TABLE harness_metrics ( metric_name VARCHAR(128), value DECIMAL(10,2), unit VARCHAR(20), attributes JSON );

harness_logs (日志)

CREATE TABLE harness_logs ( trace_id VARCHAR(64), span_id VARCHAR(64), severity VARCHAR(20), message TEXT, attributes JSON );

---

三、使用示例

Python 代码

from harness_telemetry import HarnessTelemetry

创建 telemetry recorder

telemetry = HarnessTelemetry(service_name='my-service')

开始 trace

telemetry.start_trace('task-001')

开始 span

span = telemetry.start_span('execute_task', attributes={'task_id': 'admin-M1'})

添加事件

telemetry.add_event('subagent_spawned', {'session_key': 'xxx'})

结束 span

telemetry.end_span(status='ok', message='Task completed')

记录指标

telemetry.record_metric('task_duration_ms', 2000, unit='ms')

---

四、OpenTelemetry 接入计划

当前架构

HarnessTelemetry → MySQL + JSONL

后续接入

1. 安装 opentelemetry-sdk
2. 配置 exporter (OTLP/Jaeger/Prometheus)
3. 使用 OpenTelemetryAdapter 替换 HarnessTelemetry

兼容性

• 数据结构符合 OpenTelemetry 规范
• Trace/Span/Event/Metric 对应 OTel 概念
• 无需修改代码，只需替换底层实现

---

五、成果展示

数据记录示例

Trace ID: autoexecutor-20260331-202253

Spans:

• autoexecutor_main (0ms)
• ensure_project_dir (0ms)
• query_pending_tasks (194ms)

Metrics:

• tasks_pending_count = 0
• autoexecutor_idle = 1

---

六、文件位置

文件	路径
Telemetry 模块	claude-harness/telemetry/harness_telemetry.py
AutoExecutor V3	claude-harness/scripts/auto_executor_v3.py
日志文件	claude-harness/telemetry/events.jsonl

---

七、下一步

计划	说明
OpenTelemetry 接入	OTLP exporter 配置
Dashboard 可视化	Grafana/Jaeger 集成
Python 日志采集	OpenTelemetry logging handler

---

本系统已上线，后续可直接接入 OpenTelemetry 采集系统。