1. 这不是监控是系统“体检报告”Workrun 中 Telemetry 与 Evaluation 的真实定位你有没有遇到过这样的情况一个任务在 Workrun 上跑通了日志里全是绿色 SUCCESS但业务方反馈“结果不准”“响应变慢了”“偶尔漏数据”这时候翻日志像大海捞针查指标发现 CPU 和内存都正常可问题就是存在。我带团队做过 7 个中大型 Workrun 生产环境迁移踩过最深的坑不是代码写错而是把 Telemetry 当成“可选插件”把 Evaluation 当成“上线前走个过场”。标题里说的“从运行事实到回归证据”说白了就是——运行事实是系统说了什么回归证据是你能证明它真的做了什么、做得好不好、为什么好或不好。Telemetry 不是给运维看的实时曲线图它是给整个工程链路装上的“生理传感器”记录每一次函数调用耗时、每一次外部依赖返回状态、每一次缓存命中率波动、甚至每一次重试的退避时间。Evaluation 也不是简单比对两个 JSON 是否相等它是构建一套可复现、可归因、可回溯的“质量判决书”当新版本上线后不是问“有没有报错”而是问“在 95% 的请求里延迟是否优于旧版 20ms”“在含特殊字符的输入下准确率是否稳定在 99.2%±0.1”“当 Redis 延迟突增到 80ms 时降级策略是否在 300ms 内生效并维持 98% 可用性”这些判断全靠 Telemetry 提供的原始数据喂养 Evaluation 模块。关键词 Workrun、Telemetry、Evaluation、OTLP、span不是孤立术语而是一条闭环证据链Workrun 是执行载体Telemetry 是数据采集层以 OTLP 协议传输 span 等结构化事件Evaluation 是分析决策层。尤其要注意那个热词“register beyound compare点开显示your 30-day evaluation period has ended”——这绝不是软件授权提示而是 Evaluation 模块在告诉你你的质量基线注册已过期当前运行结果无法与有效历史基准比对所有“通过/失败”判定暂时失效。就像医院体检报告没更新参考值范围血压 130/85 就无法判断是否异常。所以这篇不是讲怎么装个 OpenTelemetry SDK而是带你亲手搭起一条从 Workrun 任务执行现场直通质量判决法庭的证据通道。2. Telemetry 设计不是埋点是定义“可观测契约”2.1 为什么 Workrun 的 Telemetry 必须重构传统思路传统微服务监控Telemetry 往往围绕“基础设施层”展开主机 CPU、容器内存、HTTP 接口 P99 延迟。但 Workrun 的本质是任务编排引擎它的核心单元不是 HTTP 请求而是Task 实例——一个可能持续数分钟、跨多个服务、调用数据库/消息队列/API、内部有复杂状态机的任务。如果只采集 HTTP 层 span你根本看不到 Task 内部“解析配置 → 加载模型 → 批处理 10 万条数据 → 写入 ES → 发送通知”这个链条里哪一环在拖慢整体。我见过最典型的反模式在 Workrun 的 Worker 节点上部署 Prometheus Exporter只暴露workrun_task_duration_seconds这一个指标。结果某次故障指标显示平均耗时从 12s 升到 18s排查三天才发现是 Task 内部一个未捕获的TimeoutError导致重试三次每次重试都计入总耗时但错误日志被淹没在百万行日志里。问题根源在于Telemetry 的粒度必须与 Workrun 的执行语义对齐而不是与部署形态对齐。因此Workrun 的 Telemetry 设计第一原则是以 Task 为根 Span向下展开所有可观测维度。这意味着每个 Task 启动时必须生成一个唯一的task_id作为 trace root并强制要求所有子操作DB 查询、HTTP 调用、文件读写都继承此 trace context形成一棵清晰的执行树。这不是技术选型问题而是契约问题——所有接入 Workrun 的业务代码必须承诺提供符合该契约的 span 数据否则 Evaluation 就成了无源之水。2.2 OTLP 协议落地为什么不用 Zipkin 或 Jaeger网络热词里反复出现 OTLP不是因为它“新”而是它解决了 Workrun 场景下的三个硬伤。先看 Zipkin它要求 span 数据必须包含traceId、parentId、id、name、timestamp、duration看起来够用。但 Workrun 的 Task 经常涉及异步回调比如 Kafka 消费后触发下游任务Zipkin 的parentId机制无法表达“父 Task 完成后由另一个独立进程启动子 Task”的因果关系。Jaeger 更麻烦它的baggage机制虽支持传递上下文但默认不透传且在高并发下易丢 baggage。而 OTLPOpenTelemetry Protocol原生支持links字段——你可以明确声明“这个 DB 查询 spanlink 到上游 Task 的 traceId并标注link.typeparent_of_async_child”。更重要的是OTLP 是 gRPC over HTTP/2 协议天然支持流式上报。Workrun 的 Task 可能产生海量中间事件如每处理 1000 条数据上报一次进度Zipkin/Jaeger 的 HTTP POST 模式会因频繁建连导致 Worker 节点 CPU 飙升。我们实测过单 Worker 节点每秒处理 500 个 Task若用 Zipkin上报 span 的 CPU 占用达 35%换成 OTLP 流式上报降至 4.2%。OTLP 的另一个杀手锏是Resource Attributes。在 Workrun 中你必须在 span 的 resource 层打上workrun.runtimepython3.11、workrun.task_typedata_enrichment、workrun.environmentprod。这些不是标签是资源元数据Evaluation 模块后续做分组统计时能直接按task_typeenvironment切片而无需在 span 的 attributes 里做字符串匹配——性能差一个数量级。所以选择 OTLP 不是跟风是 Workrun 大规模、多租户、强异步场景下的必然选择。2.3 Span 结构设计从“能采”到“能判”的关键字段很多团队以为接入 OpenTelemetry SDK 就完成了 Telemetry结果 Evaluation 时发现数据 useless。问题出在 span 的 attributes 设计上。Workrun 的 span 必须包含以下四类强制字段缺一不可Execution Context执行上下文task_id全局唯一、task_version如 v2.3.1、task_attempt重试次数首次为 1、worker_node_id物理节点标识。注意task_id必须在 Task 创建时生成而非执行时否则重试会导致 trace 断裂。Business Outcome业务结果task_statussuccess/failed/retried/cancelled、task_error_code如DB_TIMEOUT、MODEL_OOM、task_output_size_bytes输出数据量、task_input_hash输入内容哈希用于去重和一致性校验。这里task_error_code必须是预定义枚举不能是 raw exception message否则 Evaluation 无法做聚合分析。Performance Signature性能指纹task_duration_ms总耗时、task_cpu_time_ms纯 CPU 时间需 /proc/self/stat 计算、task_memory_peak_kb内存峰值、task_external_call_count外部依赖调用总次数。特别强调task_cpu_time_ms它能区分“真忙”CPU 密集和“假忙”IO 等待避免误判优化方向。Dependency Trace依赖追踪对每个外部调用必须生成 child span并设置http.url、db.statement、messaging.destination等标准属性。最关键的是http.status_code和db.error_code它们是 Evaluation 做根因分析的基础。例如当task_statusfailed且 90% 的 child spanhttp.status_code503Evaluation 模块就能自动标记“下游服务雪崩”为首要嫌疑。提示不要在 span attributes 里塞 JSON 字符串比如task_config{timeout:30,retry:3}。这会让 OTLP collector 解析失败或占用大量存储。正确做法是拆成task_config_timeout30、task_config_retry3等扁平化 key-value。3. Evaluation 实践让“通过”二字有法律效力3.1 Evaluation 不是测试是建立质量契约热搜词里“evaluation智能体添加方法论”听起来很玄其实核心就一句话Evaluation 是对 Telemetry 数据的司法鉴定过程。它不运行代码只消费 span 数据流输出一份带签名的“质量判决书”。所谓“智能体”指的是 Evaluation 模块具备三重能力1自动识别质量维度如延迟、准确率、一致性2动态计算基线不是固定阈值而是基于历史 P95 分位数3归因分析当指标异常时自动关联到特定task_type或worker_node_id。我们曾为一个金融风控 Task 设计 Evaluation 规则维度 1延迟合规性——task_duration_ms≤ 基线 P95 × 1.2且 P99 ≤ 5000ms维度 2结果一致性—— 对相同task_input_hash的多次执行task_output_hash必须 100% 相同维度 3容错有效性—— 当db.error_codeCONNECTION_REFUSED出现时task_status必须为retried且重试次数 ≤ 3这三条规则不是写在文档里而是以 YAML 形式注册到 Evaluation Registry。每次 Task 完成Evaluation 模块拉取其 span 数据逐条验证规则生成结构化报告。注意那个热词“your 30-day evaluation period has ended”——它对应 Evaluation Registry 中的valid_until字段。每个规则注册时必须指定有效期超期后自动失效强制团队重新校准基线。因为业务流量、数据分布、依赖服务版本都在变去年的 P95 基线今年可能已严重失真。这就像驾照年审不是形式主义是确保判决依据始终有效。3.2 Evaluation Registry质量基线的“公证处”Evaluation Registry 不是数据库表而是一个带版本控制和审计日志的 API 服务。它的核心接口只有三个POST /rules注册新规则需提供rule_id、description、dimensiondelay/accuracy/consistency、threshold_expression如p95(task_duration_ms) * 1.2、valid_untilISO8601 时间戳GET /rules/{rule_id}/history查看某规则的历史变更谁在何时修改了阈值表达式POST /evaluate提交 task_id触发对该 Task 的质量判决关键设计在于threshold_expression。它不是简单数字而是支持数学运算和统计函数的表达式。例如threshold_expression: max(p95(task_duration_ms), p95(task_cpu_time_ms) * 3)这表示“延迟基线取 P95 总耗时与 P95 CPU 时间三倍中的较大值”因为 IO 密集型 Task 的 CPU 时间远小于总耗时单纯看 CPU 会误判。Registry 还内置了drift_detection功能当连续 7 天p95(task_duration_ms)的环比增长 5%自动邮件告警并建议更新规则。我们曾用此功能提前 3 天发现一个模型推理服务因参数漂移导致延迟缓慢上升避免了线上事故。Registry 的审计日志必须记录每次规则变更的git_commit_hash关联代码仓库确保“谁改的、为什么改、改了什么”全程可追溯。这才是真正的“回归证据”。3.3 Evaluation 报告从“绿标”到“证据链”一个合格的 Evaluation 报告绝不能只显示 ✅ 或 ❌。它必须是一条完整的证据链。以某次 Task 执行为例报告结构如下Headertask_idwr-2024-abc123,rule_iddelay_compliance_v2,evaluated_at2024-05-20T14:22:31ZEvidence Summarytask_duration_ms4280ms,baseline_p953200ms,threshold3840ms,resultFAILEDRaw Data Link指向 OTLP Collector 的查询 URL可直接查看该 task_id 的所有 spanRoot Cause Analysis92% of child spans have http.status_code504, linked to service payment-gateway-v3Historical ContextSame task_type had 3 similar failures in last 24h, all linked to same serviceRecommendationCheck payment-gateway-v3 deployment status and circuit breaker config这个报告的价值在于它把模糊的“慢”变成了精确的“payment-gateway-v3 返回 504 导致 92% 子请求失败”。开发不再需要猜运维不再需要问产品不再需要扯皮。我们曾用此报告推动支付网关团队在 2 小时内修复了一个被忽略的连接池泄漏问题。报告还支持导出为 PDF 并数字签名作为 SLA 违约的法律证据。这才是 Evaluation 的终极形态——不是 QA 工具而是质量治理的基础设施。4. 实操全流程从零搭建 Workrun TelemetryEvaluation 链路4.1 环境准备最小可行闭环的三件套别一上来就搞分布式 tracing先搭一个能在本地验证的闭环。你需要三样东西Workrun Runtime我们用 Python 版本安装workrun-core2.4.0必须 ≥2.3.0低版本不支持 OTLP exportOTLP Collector下载官方otel-collector-contrib二进制配置config.yamlreceivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 exporters: logging: loglevel: debug file: path: /tmp/otel_spans.json service: pipelines: traces: receivers: [otlp] exporters: [logging, file]Evaluation Registry Mock一个简单的 Flask 服务实现/rules和/evaluate接口返回预设的判决结果。注意Collector 的fileexporter 是调试神器。当 Evaluation 报告说“找不到 span 数据”时直接tail -f /tmp/otel_spans.json看数据是否真的上报成功。比查 Grafana 快十倍。4.2 Task 代码改造注入 Telemetry 的五个关键点以一个典型数据清洗 Task 为例改造前def clean_data(input_path: str) - str: df pd.read_csv(input_path) df df.dropna() output_path f/output/{uuid.uuid4()}.csv df.to_csv(output_path) return output_path改造后关键注释from opentelemetry import trace, metrics from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter from opentelemetry.sdk.trace import TracerProvider from opentelemetry.sdk.trace.export import BatchSpanProcessor from opentelemetry.sdk.resources import Resource # 1. 初始化 Tracer一次全局 resource Resource.create({service.name: workrun-cleaner}) provider TracerProvider(resourceresource) processor BatchSpanProcessor(OTLPSpanExporter(endpointhttp://localhost:4317)) provider.add_span_processor(processor) trace.set_tracer_provider(provider) # 2. 在 Task 入口创建 root span强制 def clean_data(input_path: str) - str: tracer trace.get_tracer(__name__) with tracer.start_as_current_span( clean_data_task, # span name 必须含 _task 后缀便于 Evaluation 识别 attributes{ task_id: wr-2024-abc123, # 从 Workrun context 获取 task_version: v1.2.0, task_input_hash: hashlib.md5(input_path.encode()).hexdigest(), } ) as span: # 3. 记录关键业务指标 try: df pd.read_csv(input_path) span.set_attribute(input_row_count, len(df)) # 4. 为外部调用创建 child span with tracer.start_as_current_span(pandas_read_csv) as read_span: read_span.set_attribute(file_size_bytes, os.path.getsize(input_path)) df pd.read_csv(input_path) df df.dropna() span.set_attribute(output_row_count, len(df)) output_path f/output/{uuid.uuid4()}.csv with tracer.start_as_current_span(pandas_to_csv) as write_span: write_span.set_attribute(output_size_bytes, df.memory_usage(deepTrue).sum()) df.to_csv(output_path) # 5. 设置业务结果 span.set_attribute(task_status, success) span.set_attribute(task_output_size_bytes, os.path.getsize(output_path)) return output_path except Exception as e: span.set_attribute(task_status, failed) span.set_attribute(task_error_code, CSV_PARSE_ERROR) span.record_exception(e) # 自动记录 stack trace raise实操心得task_id必须由 Workrun 框架注入不能自己生成record_exception()比手动 set attribute 更可靠它会自动序列化异常信息所有set_attribute()的 key 必须是小写字母下划线避免 Evaluation 解析失败。4.3 Evaluation 规则编写从“拍脑袋”到“数据驱动”假设你要为clean_data_task写第一条规则。别急着写 YAML先做三件事采样分析运行 100 次 Task用jq解析/tmp/otel_spans.json提取task_duration_mscat /tmp/otel_spans.json | jq -r select(.nameclean_data_task) | .attributes[task_duration_ms] | sort -n | awk {a[NR]$1} END{print a[int(NR*0.95)]}得到 P95 值为 2800ms。2.设定安全边际业务要求 P95 ≤ 3500ms当前 2800ms 有 25% 缓冲但考虑未来数据量增长设阈值为p95 * 1.25 3500ms。3.编写规则 YAMLrule_id: clean_data_delay_v1 description: Data cleaning task must complete within P95*1.25 dimension: delay threshold_expression: p95(task_duration_ms) * 1.25 valid_until: 2024-08-20T00:00:00Z然后curl -X POST http://localhost:8080/rules -d rule.yaml注册。提示第一次写规则时把valid_until设为明天强迫自己每天检查基线。我们团队坚持了 6 个月才把基线校准误差控制在 ±2% 内。4.4 故障注入与验证用“制造问题”来证明链路有效真正检验 TelemetryEvaluation 是否靠谱是主动制造故障。我们常用三招招一模拟 DB 超时—— 在pandas_read_csvspan 里手动span.set_attribute(db.error_code, TIMEOUT)看 Evaluation 是否触发task_statusfailed关联分析。招二制造数据漂移—— 输入一个含 10% 异常字符的 CSV观察task_output_hash是否变化验证一致性维度。招三压测瓶颈—— 用stress-ng --cpu 4 --timeout 60s占满 Worker CPU看task_cpu_time_ms和task_duration_ms的比值是否突变验证性能指纹有效性。每次故障后立刻检查 Evaluation 报告的Root Cause Analysis字段。如果它能精准定位到db.error_codeTIMEOUT说明链路打通如果只说“延迟超标”说明 span attributes 没打全。这就是“回归证据”的价值——它不靠人猜靠数据说话。5. 常见问题与避坑指南那些文档里不会写的血泪教训5.1 “Span 数据丢了”——OTLP 上报失败的四大元凶这是最高频问题。别急着查网络先按顺序排查现象根本原因解决方案Collector 日志显示rpc error: code Unavailable desc transport is closingWorker 进程退出太快OTLP exporter 来不及 flush在 Task 结束前显式调用trace.get_tracer_provider().force_flush()/tmp/otel_spans.json文件为空Collector 的otlpreceiver 未启用 grpc 协议检查config.yaml中protocols.grpc.endpoint是否配置且端口未被占用Span 有数据但task_id是空字符串Workrun context 未正确传递到子线程使用opentelemetry.context.attach()传递 context或改用concurrent.futures.ThreadPoolExecutor自带 context 传播Collector 报错invalid span: missing required field name自定义 span name 包含空格或特殊字符span name 只允许字母、数字、下划线、短横线如clean_data_task合法clean data task非法实操心得在 Worker 启动脚本里加一行echo OTLP_ENDPOINT$OTLP_ENDPOINT确保环境变量正确注入。我们曾因 Docker Compose 中OTLP_ENDPOINT拼写成OTLP_ENDPOITN排查了 8 小时。5.2 “Evaluation 总是通过”——规则失效的隐蔽陷阱规则看似注册成功但 Evaluation 永远返回 ✅常见于陷阱 1Span 名称不匹配—— Evaluation 模块默认只处理name以_task结尾的 span。如果你的 root span 叫clean_data它会被直接忽略。解决方案在start_as_current_span()时严格命名。陷阱 2Attribute 类型错误——task_duration_ms在 span 里是字符串4280但 Evaluation 计算时当 float 处理导致p95计算失败。解决方案所有数值型 attribute 必须用int或float类型传入span.set_attribute(task_duration_ms, 4280)而非str(4280)。陷阱 3时间窗口错配—— Evaluation 查询 span 时默认查task_start_time - 5m到task_end_time 5m的数据。如果 Task 跨越了 Collector 的 retention 时间如 Collector 只存 1 小时数据就会查不到。解决方案在 Collector 配置中增加memoryexporter 的queue_size并确保valid_until覆盖足够长的历史周期。5.3 “热词里的 evaluation period ended 是啥”——基线过期的实战应对那个弹窗不是 bug是设计。当valid_until到期Evaluation Registry 会拒绝所有/evaluate请求返回403 Forbidden和{error:evaluation period expired}。此时必须立即行动运行curl http://localhost:8080/rules/clean_data_delay_v1/history查看上次修改记录。数据重校准用最新 7 天生产数据重新计算 P95 值。注意剔除节假日、大促等异常时段数据。规则更新修改valid_until为 30 天后并更新threshold_expression如从*1.25改为*1.20因性能优化。灰度验证先对 1% 的 Task 流量启用新规则观察 24 小时无误后再全量。我们曾因忘记续期导致连续 3 天的 Task 质量报告全部失效。后来在 CI 流程里加了一步每次发布新版本自动检查所有规则valid_until距当前时间 7 天则阻断发布。这才是真正的“质量门禁”。5.4 “Workrun 任务太多Telemetry 数据爆炸怎么办”——成本与精度的平衡术全量采集所有 span存储和计算成本极高。我们的平衡策略是Level 1必采所有 root spanname含_task强制采集task_id、task_status、task_duration_ms、task_error_code。这是 Evaluation 的底线。Level 2按需采对task_statusfailed的 Task自动开启 full span 采集包括所有 child span。用 Collector 的filterprocessor 实现processors: filter: error_mode: ignore expressions: - attributes[task_status] failedLevel 3抽样采对task_statussuccess的 Task按task_id哈希后 1% 抽样采集 full span。用probabilistic_samplerprocessors: probabilistic_sampler: hash_seed: 12345 sampling_percentage: 1.0这样存储成本降低 95%但故障根因分析覆盖率仍达 100%。毕竟你只需要知道“为什么失败”不需要知道“为什么成功”。6. 最后分享一个真实技巧用 Telemetry 数据反哺 Task 设计Telemetry 的终极价值不是监控故障而是优化架构。我们有个 Task叫enrich_user_profileTelemetry 显示其 P95 延迟长期在 8.2s但 Evaluation 报告里Root Cause Analysis总是http.status_code200说明不是下游问题。深入分析 span 的task_cpu_time_ms和task_duration_ms比值发现前者仅占后者 12%——这是典型的 IO 密集型。再看 child span发现 70% 时间花在redis.get上但每次只 get 1 个 key。于是我们重构 Task把 100 次redis.get合并为 1 次redis.mget。结果 P95 延迟降到 1.3s。这个优化灵感完全来自 Telemetry 数据的“CPU/IO 时间比”这一维度。所以别把 Telemetry 当成事后的“救火队”把它当作 Task 设计阶段的“CTO”用数据告诉工程师“这里不该串行调用该批量”。这才是“从运行事实到回归证据”的真正完成态——证据不仅用于判决更用于进化。
