Excalidraw与Tempo分布式追踪集成

Excalidraw与Tempo分布式追踪集成

在微服务架构日益复杂的今天，系统调用链路动辄跨越数十个服务，一次用户请求可能经历网关、认证、订单、库存、支付等多个环节。当故障发生时，传统的日志排查方式就像在迷宫中摸索——你有一堆碎片信息，却难以拼出完整的路径。与此同时，团队协作也在面临挑战：新成员看不懂架构图，老员工画的流程图永远停留在“初稿”状态，设计文档和实际运行系统渐行渐远。

有没有一种方式，能让架构图不再只是静态图片，而是能“活过来”，实时反映系统的运行状态？
能不能让一张手绘风格的草图，不仅能用于头脑风暴，还能直接点击某个服务节点，查看它最近的性能瓶颈或错误追踪？

这正是我们将 Excalidraw 与 Tempo 结合的出发点——把“看得懂”的设计语言，和“跑得动”的可观测性数据打通，构建一个从视觉理解到运行洞察的闭环。

Excalidraw 的魅力从来不只是因为它长得像手绘。它的真正价值在于极低的认知门槛。一个产品经理可以五分钟内画出系统交互逻辑，前端工程师随手标注 API 调用关系，运维同事圈出高延迟模块——所有人都能在同一张图上对话。这种“人人可编辑”的特性，让它迅速成为远程团队的技术沟通中枢。

但问题也随之而来：这张图是“死”的。
上周画的服务依赖，可能已经因为灰度发布而改变；图中标注的“稳定服务”，也许这两天已经开始频繁超时。我们缺少的是动态反馈机制——让真实世界的 trace 数据反过来驱动设计图的演进。

这时候，Tempo 就登场了。

作为 Grafana Labs 推出的高性能分布式追踪后端，Tempo 不追求花哨的 UI，而是专注于一件事：以最低成本存储和查询海量 trace。它不依赖 Elasticsearch 那样的重型索引，而是直接将 trace 写入对象存储（如 S3），通过 trace ID 进行精确查找。这意味着你可以轻松保留数周甚至数月的追踪数据，而不必担心磁盘爆炸。

更重要的是，Tempo 完全兼容 OpenTelemetry 协议，几乎任何现代应用都可以通过 OTLP 上报 span 数据。结合 OpenTelemetry Collector，还能实现采样策略控制、敏感字段脱敏、多目的地分发等高级功能。

# OpenTelemetry Collector 示例配置 receivers: otlp: protocols: grpc: http: exporters: tempo: endpoint: "tempo.example.com:4317" tls: insecure: true service: pipelines: traces: receivers: [otlp] exporters: [tempo]

这套组合拳下来，你的系统就有了“神经系统”：每个请求都带着唯一的 trace ID 穿梭于服务之间，被完整记录下来。接下来的问题就是——如何让这些冷冰冰的数据，重新回到那张温暖的手绘图上？

设想这样一个场景：

某日凌晨两点，告警响起：order-service响应时间陡增。值班工程师打开 Grafana，查到几个异常 trace，发现瓶颈出现在inventory-service到pricing-service的调用上。他本想在群里贴个截图说明情况，却发现文字描述太抽象，新人根本看不懂上下文。

如果此时他能直接点击“在架构图中查看此 trace”，然后跳转到 Excalidraw 白板，看到一条红色虚线从订单服务一路延伸到定价服务，并且相关节点自动闪烁提示……会怎样？

这就是集成的核心思路：双向联动。

具体实现上，关键在于建立“图元”与“服务名”的映射关系。在 Excalidraw 中绘制服务框时，可以通过自定义属性绑定 metadata：

const serviceNode = { id: "svc-order", type: "rectangle", x: 200, y: 150, width: 120, height: 60, strokeColor: "#c92a2a", backgroundColor: "#fff", roughness: 2, seed: 12345, // 自定义数据字段，用于关联追踪系统 customData: { serviceName: "order-service", environment: "prod", team: "e-commerce" } };

只要这个serviceName与 OpenTelemetry 上报的service.name标签一致，就可以通过插件实现在白板上查询对应 trace。例如，在 Excalidraw 外层封装一个轻量级插件面板：

function TraceInspector({ selectedElement }) { const [traces, setTraces] = useState([]); useEffect(() => { if (selectedElement?.customData?.serviceName) { fetch(`/api/tempo/traces?service=${selectedElement.customData.serviceName}&limit=5`) .then(res => res.json()) .then(data => setTraces(data)); } }, [selectedElement]); return ( <div className="inspector-panel"> <h4>近期调用追踪</h4> {traces.map(trace => ( <Link key={trace.id} to={`/grafana/explore?traceId=${trace.id}`}> 🕵️‍♂️ {trace.duration}ms | {trace.httpStatus} </Link> ))} </div> ); }

这样一来，点击任何一个服务节点，就能看到它最近的执行快照。更进一步，还可以做“热力着色”：根据过去 5 分钟内该服务的平均延迟，动态调整其背景色深浅。绿色表示健康，黄色预警，红色则代表已触发告警。

这不仅仅是个炫技功能。它改变了我们阅读架构图的方式——不再是被动接收信息，而是主动感知系统脉搏。

再往深处想，这种集成甚至能推动一种新的调试范式：Model-Driven Debugging（模型驱动调试）。

传统做法是“先查日志，再看拓扑”。而现在，你可以反向操作：“先看图，再钻取数据”。比如你在图上发现payment-service和fraud-check-service之间的连线特别粗，说明调用量异常升高，于是顺藤摸瓜去查是否有刷单行为。这是一种自顶向下、由结构引导分析的新路径。

当然，落地过程中也有不少细节需要权衡。

首先是权限问题。并不是所有人都应该看到生产环境的完整架构图，尤其是涉及核心金融系统的拓扑。因此，Excalidraw 实例必须接入统一身份认证（如 OAuth2），并支持细粒度的画布访问控制。可以借鉴 Notion 的权限模型：谁可以查看、编辑、评论，一目了然。

其次是性能考量。Tempo 虽然擅长按 trace ID 查找，但“搜索包含某服务的所有 trace”这类操作仍需扫描大量 block。对于高频查询，建议引入缓存层（如 Redis），将常见标签组合的结果暂存一段时间。同时在前端启用懒加载，避免一次性拉取过多数据导致页面卡顿。

还有一个容易被忽视的点是版本一致性。今天的架构图，真的是昨天那个吗？如果没有版本管理，很容易出现“图不对文”的尴尬。理想情况下，Excalidraw 应与 Git 仓库联动，每次重大变更都生成 commit 记录，并允许回溯历史版本。这样，当你分析一个月前的事故时，也能还原当时的系统结构。

部署模式上，小团队完全可以用 Kubernetes 快速搭建一套轻量级组合：

• 使用官方 Helm chart 部署 Tempo 到私有集群；
• 用 Docker 运行 Excalidraw 并开启 WebSocket 协作；
• 通过 Nginx 反向代理统一入口，加上 TLS 加密；
• 所有组件共享同一个 LDAP/SSO 认证体系。

而对于大型企业，则可以直接采用Grafana Cloud的托管方案。它内置了 Tempo 实例，并提供与 Excalidraw 私有部署实例的安全 API 对接能力，省去了运维负担。

值得期待的是 AI 的加入会让整个系统变得更聪明。假设你输入一句：“帮我找出最近三天内从下单到支付失败的所有路径。”
背后的系统可以：

1. 解析语义，提取关键实体：order → payment,status=failure;
2. 调用 Tempo Search API 查询符合条件的 trace 列表；
3. 提取每条 trace 的服务调用序列；
4. 在 Excalidraw 图中高亮所有涉及失败路径的边；
5. 自动生成统计摘要：“共发现 47 次失败，其中 83% 卡在支付网关验证环节”。

这不是科幻。OpenAI 的函数调用（Function Calling）能力已经可以让大模型安全地触发 API 请求，而无需自己生成原始数据。只要给它清晰的工具定义，就能完成上述推理链条。

最终，我们会得到一个会思考的架构图：它不仅展示“系统长什么样”，还能回答“为什么出问题”、“哪里最脆弱”、“如何改进”。

回头来看，Excalidraw 和 Tempo 的结合，本质上是在解决一个根本矛盾：
人类适合用图形思考，而机器擅长处理事件流。
前者直观但静态，后者精准但晦涩。只有把两者缝合起来，才能既看得明白，又追得清楚。

未来的 DevOps 工具链中，这类“可视化+可观测性”的融合体可能会成为标配。它们不再是孤立的监控面板或绘图工具，而是真正意义上的系统数字孪生体——一个随真实世界同步演进的虚拟映射。

也许有一天，当我们说“打开系统看看”时，打开的不再是一堆指标图表，而是一张会呼吸、会报警、会建议优化方案的智能地图。

而这张地图的起点，或许就是你现在画下的第一根箭头。