Liên kết lỗi qua nhiều tầng bằng trace

Một cú bấm trên trình duyệt có thể kết thúc bằng một lỗi cách đó ba tầng: server function, rồi một Worker, rồi một job. Khi bật trace propagation, mọi lỗi và lượt chạy job do cú bấm đó gây ra mang cùng một trace ID, và Belvador hiện chúng cùng nhau trong Cùng trace ở mỗi issue và ở trang Trace.

Đây là liên kết, không phải tracing hiệu năng: các SDK Belvador không tạo span hay đo thời gian từng tầng — chỉ ghi lỗi và lượt chạy nào chung một trace. Muốn có span và thời gian, hãy gửi traces OpenTelemetry; tuỳ chọn bên dưới giúp lỗi khớp với chúng.

Bật lên#

Có từ @belvador/* 0.3.0. Mặc định tắt, vì thêm header vào request có thể kích hoạt kiểm tra CORS ở các API bạn không kiểm soát.

Trình duyệt và React#

import { init } from "@belvador/browser"; // or @belvador/reactinit({  dsn: "https://<public-key>@ingest.belvador.dev/<project-id>",  // Only your own APIs. Every other URL is left alone.  tracePropagation: { targets: ["/api/", "https://api.example.com/"] },});

TanStack Start#

import { init } from "@belvador/tanstack-start/client";if (typeof window !== "undefined") {  init({    dsn: "https://<public-key>@ingest.belvador.dev/<project-id>",    // Same-origin server functions and routes; the server SDK continues the trace.    tracePropagation: { targets: ["/_serverFn/", "/api/"] },  });}

targets liệt kê các URL được thêm header trace: chuỗi khớp mọi URL có chứa nó (và, trên trình duyệt, đường dẫn của request cùng origin); RegExp được thử trên URL. Chỉ liệt kê API của chính bạn. Danh sách rỗng là tắt.

Các gói phía máy chủ (@belvador/tanstack-start/server, @belvador/cloudflare) tự nối tiếp trace đi vào: lỗi hay lượt withMonitor trong request đó mang trace ID của bên gọi. Worker cũng chuyển header tiếp ở các lệnh fetch của chính nó khi bạn đặt tracePropagation trong tuỳ chọn của withBelvador.

Khi đã dùng OpenTelemetry#

Nếu app đã chạy OpenTelemetry, hãy để OpenTelemetry làm chủ trace và đưa API của nó cho Belvador. Lỗi được bắt trong lúc một span đang chạy sẽ mang trace ID và span ID của span đó, nên issue mở đúng span trong waterfall của trace:

import * as api from "@opentelemetry/api";import { withBelvador } from "@belvador/cloudflare"; // same option in every @belvador/* initexport default withBelvador(  (env: { BELVADOR_DSN?: string }) => ({    dsn: env.BELVADOR_DSN ?? "https://<public-key>@ingest.belvador.dev/<project-id>",    // The same @opentelemetry/api copy your OpenTelemetry setup uses.    otel: { api },  }),  handler,);

• Truyền chính module (import * as api from "@opentelemetry/api") — bản mà SDK OpenTelemetry của bạn đã đăng ký provider. Belvador không tự import nó, không tạo span và không đăng ký provider.

• ID lấy từ span đang chạy lúc bắt lỗi: captureException bên trong span của bạn, hoặc lỗi framework báo trước khi span kết thúc. Lỗi thoát ra khỏi span rồi mới được handler bên ngoài báo thì giữ trace ID của request, không có span đó.

• Khi đã đặt otel, tracePropagation bị bỏ qua (OpenTelemetry đã gửi traceparent), và SDK báo chẩn đoán BLV_TRACE_OWNER_OTEL cho tới khi bạn bỏ nó đi.

• Có từ @belvador/* 0.4.0.

Header được gửi#

Request tới cổng nhận của Belvador không bao giờ được thêm header trace.

CORS#

Nếu API ở origin khác, preflight CORS của nó phải cho phép các header mới, nếu không trình duyệt chặn request:

Access-Control-Allow-Headers: traceparent, sentry-trace# only when you also turn on baggage:Access-Control-Allow-Headers: traceparent, sentry-trace, baggage

Hãy kiểm việc này trước khi bật ở production: thiếu header trong Access-Control-Allow-Headers làm request thất bại, không chỉ mất trace.

Đọc một trace#

• Ở issue, Cùng trace liệt kê tối đa 200 lỗi và lượt chạy cùng trace ID trong ±24 giờ quanh event đó, trên các project của workspace mà bạn được xem.

• Mở trace hiện chúng theo thứ tự thời gian. Bạn có thể dán trace ID hoặc nguyên header traceparent vào ⌘K để mở.

• Trace chỉ gom dữ liệu trong một workspace. Request đi vào app của workspace khác hiện ở đó thành một mảnh riêng.

Event không có trace ID sẽ ghi rõ trên issue; điều đó bình thường với lỗi không đến từ một request có truyền trace.