<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>链路追踪 Tracer - 新生命团队</title>
<link rel="stylesheet" href="css/site.css">
</head>
<body>
<!-- ===== 顶部导航 ===== -->
<header class="site-header">
<div class="container">
<button class="nav-toggle" type="button" aria-label="菜单" aria-expanded="false">
<span></span><span></span><span></span>
</button>
<a class="brand" href="home.html">
<span class="logo">N</span>
<span>新生命团队</span>
</a>
<nav class="main-nav">
<a href="home.html">首页</a>
<div class="nav-dropdown">
<a class="active" href="list.html">文档 <span class="caret"></span></a>
<div class="dd-menu">
<a class="active" href="list.html">核心组件（NewLife全家桶）<span class="dd-desc">/core</span></a>
<a href="list.html">大数据中间件XCode<span class="dd-desc">/xcode</span></a>
<a href="list.html">魔方Cube（快速开发平台）<span class="dd-desc">/cube</span></a>
<a href="list.html">精心匠造（平台级产品）<span class="dd-desc">/blood</span></a>
<a href="list.html">物联网 & 嵌入式<span class="dd-desc">/iot</span></a>
<a href="list.html">计算机技术<span class="dd-desc">/tech</span></a>
<a href="list.html">事件活动<span class="dd-desc">/events</span></a>
</div>
</div>
<a href="https://github.com/NewLifeX" target="_blank">开源项目</a>
<a href="https://ai.newlifex.com/" target="_blank">AI问答</a>
<a href="info.html">关于我们</a>
</nav>
<div class="nav-actions">
<form class="search-box" action="search.html" method="get">
<span class="icon">
<svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
</span>
<input type="text" name="key" placeholder="搜索文章…" aria-label="搜索">
</form>
<a class="btn btn-outline btn-sm" href="/Admin" target="_blank">管理后台</a>
</div>
</div>
</header>
<!-- ===== 面包屑 ===== -->
<div class="container">
<nav class="crumb">
<a href="home.html">首页</a>
<span class="sep">/</span>
<a href="list.html">核心组件（NewLife全家桶）</a>
<span class="sep">/</span>
<span class="cur">链路追踪 Tracer</span>
</nav>
</div>
<!-- ===== 详情双栏 ===== -->
<div class="container">
<div class="doc-layout">
<!-- 正文区 -->
<div class="doc-main">
<div class="article-header">
<h1>链路追踪 Tracer：可观测性埋点规范与实践</h1>
<div class="article-meta">
<span>作者 <span class="meta-strong">大石头</span></span>
<span class="sep">·</span>
<span>发布 <span class="meta-strong">2024-12-16 09:16:28</span></span>
<span class="sep">·</span>
<span>浏览 <span class="meta-strong">5,102</span></span>
</div>
</div>
<article class="article-content">
<p>可观测是衡量现代应用质量的核心指标之一。NewLife 设计了 <code>ITracer</code>/<code>ISpan</code> 这一套链路追踪规范，开发者可以根据该规范编写各种关键性代码埋点，在应用项目注入星尘监控后，实现埋点数据的采集与上报分析。NewLife 全系列项目（大于 30 个）均使用了 <code>ITracer</code> 埋点。</p>
<h2 id="s1">为什么需要链路追踪</h2>
<p>在单体时代，排查问题只需要看日志；而进入微服务与分布式时代后，一次用户请求可能跨越多个服务、多个进程，传统日志无法串联整个调用链。链路追踪通过为每次请求生成唯一的 <strong>TraceId</strong>，并在每个节点记录耗时与状态，从而还原出完整的调用拓扑。</p>
<blockquote>
一句话总结：链路追踪把"散落各处的日志"串成"一条完整的调用链"，让慢请求、错误请求无处遁形。
</blockquote>
<h2 id="s2">核心概念</h2>
<p>NewLife 的追踪体系包含以下核心概念：</p>
<table>
<thead>
<tr><th>概念</th><th>说明</th><th>对应接口</th></tr>
</thead>
<tbody>
<tr><td>追踪器</td><td>全局追踪入口，负责创建 Span</td><td><code>ITracer</code></td></tr>
<tr><td>链路片段</td><td>一次方法/请求的耗时与状态记录</td><td><code>ISpan</code></td></tr>
<tr><td>追踪 ID</td><td>整条调用链的唯一标识</td><td><code>TraceId</code></td></tr>
<tr><td>片段 ID</td><td>单个 Span 的唯一标识</td><td><code>SpanId</code></td></tr>
<tr><td>父片段</td><td>调用者的 Span，形成树形结构</td><td><code>ParentId</code></td></tr>
</tbody>
</table>
<h2 id="s3">快速开始</h2>
<p>在任意方法中埋点，只需要两行代码：</p>
<pre><code>// 全局或依赖注入的追踪器
private readonly ITracer _tracer;
public String GetName(Int32 id)
{
using var span = _tracer?.NewSpan("GetName", id);
// ...业务逻辑
return name;
}</code></pre>
<p>使用 <code>using</code> 语句块，Span 会在方法结束时自动记录耗时与结果，异常也会被自动捕获并标记为错误。</p>
<h3 id="s3-1">设置错误与标签</h3>
<p>当需要标记错误或附加自定义信息时，可以使用以下方式：</p>
<pre><code>using var span = _tracer?.NewSpan("GetName", id);
try
{
// ...业务逻辑
}
catch (Exception ex)
{
span?.SetError(ex, "查询用户失败");
throw;
}</code></pre>
<h3 id="s3-2">串联调用链</h3>
<p>跨进程调用时，将当前 <code>TraceId</code> 随请求透传，下游接收后创建子 Span，即可把整条链路串联起来：</p>
<pre><code>// 上游：写入请求头
request.Headers["X-Trace-Id"] = DefaultSpan.Current?.TraceId;
// 下游：读取并创建子片段
var traceId = request.Headers["X-Trace-Id"];
using var span = _tracer?.NewSpan("HandleRequest", traceId);</code></pre>
<h2 id="s4">最佳实践</h2>
<ul>
<li><strong>埋点粒度</strong>：对热点路径与外部调用（数据库、HTTP、RPC、MQ）埋点，避免对纯内存计算过度埋点。</li>
<li><strong>命名规范</strong>：Span 名称使用"动词 + 名词"，如 <code>Query-Order</code>、<code>Send-Sms</code>。</li>
<li><strong>数据最小化</strong>：<code>AppendTag</code> 只附加关键参数，避免写入敏感信息与超长内容。</li>
<li><strong>零侵入</strong>：优先使用框架内置埋点（如 <code>ApiHttpClient</code>、<code>Db</code>），业务代码只需补充自定义关键路径。</li>
</ul>
<blockquote>
注意：埋点本身也会有性能开销。NewLife 的 <code>ITracer</code> 采用异步采样与批量上报，在关闭采样或未接入上报端时，埋点开销可忽略不计。
</blockquote>
<h2 id="s5">与星尘的配合</h2>
<p>应用项目通过 <code>services.AddStardust()</code> 注入星尘后，星尘会自动挂载 <code>ITracer</code> 实现，将采集到的调用链数据实时上报到星尘 APM 平台，在控制台即可查看调用拓扑、耗时分布与错误详情。</p>
<h2 id="s6">总结</h2>
<p><code>ITracer</code>/<code>ISpan</code> 用最小的侵入成本，为应用提供了标准化的可观测能力。无论项目规模大小，建议从一开始就建立埋点习惯，为后续的线上问题排查与性能优化打下坚实基础。</p>
</article>
<!-- 上一篇/下一篇 -->
<div class="article-nav">
<a class="nav-item" href="info.html">
<div class="nav-label">← 上一篇</div>
<div class="nav-title">缓存架构 ICacheProvider</div>
</a>
<a class="nav-item next" href="info.html">
<div class="nav-label">下一篇 →</div>
<div class="nav-title">插件框架 IPlugin：业务插件化开发指南</div>
</a>
</div>
</div>
<!-- 目录树（滚动高亮） -->
<aside class="toc">
<div class="toc-title">📑 本页目录</div>
<ul>
<li><a class="active" href="#s1">为什么需要链路追踪</a></li>
<li><a href="#s2">核心概念</a></li>
<li>
<a href="#s3">快速开始</a>
<ul>
<li><a class="toc-level-3" href="#s3-1">设置错误与标签</a></li>
<li><a class="toc-level-3" href="#s3-2">串联调用链</a></li>
</ul>
</li>
<li><a href="#s4">最佳实践</a></li>
<li><a href="#s5">与星尘的配合</a></li>
<li><a href="#s6">总结</a></li>
</ul>
</aside>
</div>
</div>
<!-- ===== 页尾 ===== -->
<footer class="site-footer">
<div class="container">
<div class="f-grid">
<div class="f-brand">
<div class="f-logo"><span class="logo">N</span>新生命团队</div>
<p>学无先后达者为师！新生命团队成立于 2002 年，致力于软硬件应用方案咨询、系统架构规划与开发服务。</p>
</div>
<div class="f-col">
<h4>友情链接</h4>
<a href="home.html">新生命团队</a>
<a href="https://github.com/NewLifeX" target="_blank">开源项目</a>
<a href="https://ai.newlifex.com/" target="_blank">AI问答</a>
</div>
<div class="f-col">
<h4>文档</h4>
<a href="list.html">核心组件</a>
<a href="list.html">大数据中间件 XCode</a>
<a href="list.html">魔方 Cube</a>
<a href="https://sso.newlifex.com/" target="_blank">用户中心</a>
</div>
<div class="f-col">
<h4>关于</h4>
<a href="info.html">关于我们</a>
<a href="product.html">核心产品</a>
<a href="https://github.com/NewLifeX/NewLife.Yuque" target="_blank">本站源码</a>
<a href="/Admin" target="_blank">管理后台</a>
</div>
</div>
<div class="f-bottom">
<span>©2002-2026 NewLife · <a href="https://get.dot.net/" target="_blank">.NET 10.0.0</a></span>
<span><a href="https://beian.miit.gov.cn/" target="_blank">沪ICP备2025143774号-1</a></span>
</div>
</div>
</footer>
<script src="js/site.js"></script>
</body>
</html>
|