自定义插桩
在本页面中，您将学习如何手动将追踪信息传播到您的 JavaScript 应用程序内外。
如果满足以下条件之一，分布式追踪将自动设置：
- 您已 设置了追踪，或
- 您正在使用包含开箱即用的追踪传播功能的 SDK 之一：
@sentry/nextjs@sentry/sveltekit@sentry/remix@sentry/astro
如果您使用的是其他软件包，并且尚未启用追踪，您可以手动设置应用程序以使分布式追踪正常工作。
如果您希望使用分布式追踪但不使用追踪功能，可以将 tracesSampleRate 选项设置为 0。
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
// If this is 0, tracing is disabled
// but distributed tracing is not
tracesSampleRate: 0,
});
您也可以手动提取和注入追踪数据到您的应用程序中。为此，您必须：
- 从传入请求头或其他类似来源提取并存储传入的追踪信息。
- 将追踪信息注入到任何传出请求中。
要了解更多关于分布式追踪的信息，请参阅我们的 分布式追踪 文档。
您必须将传入的追踪信息提取并存储在内存中以备后用。Sentry 提供了 continueTrace() 函数来帮助您完成此操作。传入的追踪信息可以来自不同的地方：
- 在 Web 环境中，它通过 HTTP 头发送，例如由您前端项目中使用的另一个 Sentry SDK 发送。
- 在作业队列中，可以从元数据或头变量中检索。
- 您还可以从环境变量中获取追踪信息。
以下是一个使用 continueTrace() 提取和存储传入追踪信息的示例：
const http = require("http");
http.createServer((request, response) => {
const sentryTraceHeaders = request.headers["sentry-trace"];
const sentryTrace = Array.isArray(sentryTraceHeaders)
? sentryTraceHeaders.join(",")
: sentryTraceHeaders;
const baggage = request.headers["baggage"];
Sentry.continueTrace({ sentryTrace, baggage }, () => {
Sentry.startSpan(
{,
name: "my request",
op: "http.server",
},
() => {
// Your API code...
}
);
});
});
在这个示例中，我们创建了一个新的事务，该事务附加到 sentry-trace 和 baggage 请求头中指定的追踪。
为了使分布式追踪正常工作，您从活动根跨度中提取并存储的两个头（sentry-trace 和 baggage）必须添加到传出的 HTTP 请求中。
以下是一个收集并注入这些追踪信息到传出请求的示例：
const activeSpan = Sentry.getActiveSpan();
const rootSpan = activeSpan ? Sentry.getRootSpan(activeSpan) : undefined;
// Create `sentry-trace` header
const sentryTraceHeader = rootSpan
? Sentry.spanToTraceHeader(rootSpan)
: undefined;
// Create `baggage` header
const sentryBaggageHeader = rootSpan
? Sentry.spanToBaggageHeader(rootSpan)
: undefined;
// Make outgoing request
fetch("https://example.com", {
method: "GET",
headers: {
baggage: sentryBaggageHeader,
"sentry-trace": sentryTraceHeader,
},
}).then((response) => {
// ...
});
在这个示例中，追踪信息被传播到运行在 https://example.com 的项目。如果该项目使用了 Sentry SDK，它将提取并保存追踪信息以备后用。
这两个服务现在通过您的自定义分布式追踪实现连接起来了。
如果您在服务器端渲染 HTML，并且在浏览器应用程序中使用 Sentry SDK，您可以通过将服务器的追踪信息作为 <meta> 标签注入到最初发送给浏览器的 HTML 中，从而连接后端和前端的追踪。当前端 SDK 初始化时，它会自动从 <meta> 标签中提取追踪信息并继续该追踪。请注意，您的浏览器 SDK 需要注册 browserTracingIntegration 才能实现这一点。
最简单且推荐的方法是使用 Sentry.getTraceMetaTags()：
index.jsfunction renderHtml() {
return `
<html>
<head>
${Sentry.getTraceMetaTags()}
</head>
<body>
<!-- Your HTML content -->
</body>
</html>
`;
}
或者，如果您需要对如何生成 meta 标签进行更多控制，可以使用 Sentry.getTraceData() 仅获取 meta 标签的值并自行生成 meta 标签：
index.jsfunction renderHtml() {
const metaTagValues = Sentry.getTraceData();
return `
<html>
<head>
<meta name="sentry-trace" content="${metaTagValues["sentry-trace"]}">
<meta name="baggage" content="${metaTagValues.baggage}">
</head>
<body>
<!-- Your HTML content -->
</body>
</html>
`;
}
自 SDK 版本 8.5.0 起可用。
如果 SDK 的 默认追踪持续时间行为 不符合您的需求，您可以手动启动一个新追踪，该追踪将不再与当前（分布式）追踪关联。 这意味着在此新追踪期间由 SDK 收集的跨度或错误将不会与在此新追踪之前或之后收集的跨度或错误相关联。
要启动一个在回调期间有效的全新追踪，请使用 startNewTrace：
myButton.addEventListener("click", async () => {
Sentry.startNewTrace(() => {
Sentry.startSpan(
{ op: "ui.interaction.click", name: "fetch click" },
async () => {
await fetch("http://example.com");
},
);
});
});
一旦回调结束，SDK 将继续之前的追踪（如果存在）。
如果您从项目向其他服务发出传出请求，请检查请求中是否包含 sentry-trace 和 baggage 头。如果包含，说明分布式追踪正在正常工作。