自定义插桩
在本页面中，您将学习如何手动将追踪信息传播到您的 JavaScript 应用程序内外。
如果满足以下条件之一，分布式追踪将自动设置：
- 您已 设置了追踪，或
- 您正在使用包含开箱即用的追踪传播功能的 SDK 之一：
@sentry/nextjs@sentry/sveltekit@sentry/remix@sentry/astro
如果您使用的是其他软件包，并且尚未启用追踪，您可以手动设置应用程序以使分布式追踪正常工作。
要为您的前端启用分布式追踪，请按照 自动插桩 文档中的说明，在 Sentry.init() 选项中添加 browserTracingIntegration。
如果您希望使用分布式追踪但不使用追踪功能，可以将 tracesSampleRate 选项设置为 0。
Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [Sentry.browserTracingIntegration()],
// If this is 0, tracing is disabled
// but distributed tracing is not
tracesSampleRate: 0,
});
默认情况下，browserTracingIntegration 会自动继续在 <meta> 标签中找到的追踪——详情请参阅 自动追踪传播。 如果您希望继续不同的追踪，例如因为您无法通过 meta 标签传播追踪而需要使用其他机制，您可以按照以下方法进行：
const client = Sentry.init({
dsn: "https://examplePublicKey@o0.ingest.sentry.io/0",
integrations: [
Sentry.browserTracingIntegration({
// Disable default pageload instrumentation
instrumentPageLoad: false,
}),
],
});
// Start the pageload span manually
const sentryTrace = getSentryTraceStringFromSomewhere();
const baggage = getBaggageStringFromSomewhere();
Sentry.startBrowserTracingPageLoadSpan(
client,
{
name: window.location.pathname,
},
{ sentryTrace, baggage },
);
如果您不希望使用 browserTracingIntegration 集成，可以通过手动提取和注入追踪数据来连接多个系统。为此，您必须：
- 在页面加载时从 HTML
<meta>标签中提取并存储传入的追踪信息。 - 将追踪信息注入到任何传出请求中。
要了解更多关于分布式追踪的信息，请参阅我们的 分布式追踪 文档。
如果您有一个渲染应用程序 HTML（SSR）的服务器，并且该服务器也在运行 Sentry SDK，您可以使用追踪将前端与后端连接起来。
为此，可以让服务器在渲染的 HTML 中包含带有 Sentry 追踪信息的 <meta> 标签。在前端，在页面加载时提取这些追踪信息，并用它创建与传入后端追踪相关联的新事务。
一些 Sentry 后端 SDK 提供了将这些 <meta> 标签注入渲染 HTML 的内置方法。例如：
然后，在 pageload 时，您可以执行以下操作：
import { propagationContextFromHeaders } from "@sentry/core"; // Before version 8.40.0, import from "@sentry/utils"
import * as Sentry from "@sentry/browser";
// Read meta tag values
const sentryTrace = document.querySelector(
"meta[name=sentry-trace]",
)?.content;
const baggage = document.querySelector("meta[name=baggage]")?.content;
// Generate a propagation context from the meta tags
const propagationContext = propagationContextFromHeaders(
sentryTrace,
baggage,
);
Sentry.getCurrentScope().setPropagationContext(propagationContext);
Sentry.startSpan(
{
name: `Pageload: ${window.location.pathname}`,
op: "pageload",
},
() => {
// do something
},
);
在这个示例中，我们创建了一个新的根跨度，该跨度附加到 sentry-trace 和 baggage HTML <meta> 标签中指定的追踪。
为了使分布式追踪正常工作，您从活动根跨度中提取并存储的两个头（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，它将提取并保存追踪信息以备后用。
这两个服务现在通过您的自定义分布式追踪实现连接起来了。
自 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 头。如果包含，说明分布式追踪正在正常工作。