SH

Soloharness

概念 · 故事 · Agent

← 返回概念解读

Concept Fable精修版

跨度

Span · Observability artifact

先读故事。这里不急着给定义,先让问题自己长出来。

寓言故事

长条纸上那一枚被忽略的小印章

海鸥邮局开始给每个包裹留下完整路径后,局长终于能看到包裹从柜台到收件人手里的全过程。大家都觉得问题解决了。只要长条纸还在,包裹就不会再无故失踪。

可是新的问题出现了。很多包裹没有失踪,只是慢。长条纸显示它们都走完了全程,但没有说明到底是哪一段拖慢了。局长看着一串印章,只能说:这一趟用了两天半。至于慢在称重、分拣、装船还是转运,仍然不清楚。

老邮差提醒他:你现在有了路,但还没有量每一段路。长条纸告诉你包裹走过哪里;每一枚印章才告诉你那一步到底发生了什么。

于是邮局改了印章。过去一枚章只写‘已处理’,现在每一枚章都要写四件事:开始时间、结束时间、处理人、结果。如果这一步调用了别的仓库、查了别的账、等了别的车,也要写在章旁边。

第一次用新章,问题立刻浮出来。一箱瓷器从柜台到仓库只花了一刻钟,从仓库到码头却等了五个时辰。再看码头那枚章,原因不是船慢,而是包装复核一直排队。包装复核这件小事,藏在过去的‘已处理’三个字里。

另一次,包裹显示分拣很快,但分拣章旁边写着‘重试三次’。局长才知道,分拣员其实连续查错了目的地,只是最后一次查对了,所以结果看起来成功。没有这枚细章,成功会掩盖过程里的不稳定。

慢慢地,邮局开始把一枚枚章当作最小的诊断单位。整条路径叫旅程,每一枚章叫一段。要优化旅程,不能只盯终点;要先知道哪一段慢、哪一段错、哪一段重试最多。

后来局长说,长条纸让我们看见包裹的一生,小印章让我们看见它每一次呼吸。没有长条纸,我们不知道整体;没有小印章,我们不知道细节。

揭示

这个故事讲的是:跨度

Span(跨度)是 Trace 中的一次具体操作记录。它通常表示一次模型调用、检索、工具调用、数据库查询、解析、审批或中间步骤,包含开始时间、结束时间、耗时、输入输出、状态、错误和关联上下文。多个 span 组合起来,构成一次完整 trace。

它重要的地方在于:它不只是一个术语,而是在真实 AI / Agent 系统里会反复出现的结构性问题。理解它,才能判断什么时候该加模型,什么时候该改流程,什么时候该补治理。

隐喻映射

  • 长条纸:Trace,一次端到端执行路径
  • 每一枚印章:Span,执行路径中的单个操作
  • 只写‘已处理’:缺少细粒度 span 信息,无法诊断延迟和错误
  • 开始时间和结束时间:span 的时间边界,用于计算延迟
  • 处理人和结果:span 的执行组件、状态和输出
  • 包装复核排队:某个子步骤造成整体延迟
  • 重试三次但最终成功:span 能揭示最终成功背后的不稳定过程
  • 最小诊断单位:span 是排查 Agent 任务细节的基础颗粒度

Soloharness 判断

这个概念的实战价值,是帮你把“看起来聪明的 AI 功能”拆成可交付、可验收、可治理的工作单元。

traceOpenTelemetrylatencyinstrumentationobservability