Hướng dẫn cho AI agent

@belvador/tanstack-startRuntime: browser+workersreact: ^18.0.0 || ^19.0.0@tanstack/react-router: ^1.168.0@tanstack/react-start: ^1.168.0Cloudflare Workers: nodejs_compatCài đặtThêm gói vào ứng dụng.```bashnpm install @belvador/tanstack-start@0.6.1```Khởi tạoKhởi tạo càng sớm càng tốt. Dữ liệu cá nhân và thông tin đăng nhập bị loại bỏ trước khi gửi.src/instrument.ts```typescriptimport { init } from "@belvador/tanstack-start/client";// Imported first by src/start.ts and src/router.tsx. Runs only in the browser.if (typeof window !== "undefined") {  init({    dsn: "https://<public-key>@ingest.belvador.dev/<project-id>",    release: import.meta.env.VITE_APP_VERSION, // your build or commit id    environment: import.meta.env.MODE,  });}```Trình duyệtImport ./instrument ở dòng đầu tiên và báo lỗi trang qua defaultOnCatch. Hàm này chỉ chạy ở nơi có error component.src/router.tsx```typescriptimport "./instrument"; // first line, before the route treeimport { withBelvadorRouter } from "@belvador/tanstack-start/client";// In getRouter(): wrap the options you already pass to createRouter.// createRouter(withBelvadorRouter({ routeTree, ...yourOptions }))// It reports route errors, calls your own defaultOnCatch after that, and adds// TanStack's error component only if you set no defaultErrorComponent.```Máy chủ (Cloudflare Workers)Bọc điểm vào máy chủ: mỗi request một phạm vi riêng, lỗi vẫn được ném tiếp, response giữ nguyên. Cần cờ nodejs_compat (app Lovable đã có).src/server.ts```typescriptimport handler from "@tanstack/react-start/server-entry";import { withBelvador } from "@belvador/tanstack-start/server";// Requires Cloudflare Workers with nodejs_compat enabled.// If src/server.ts already exists, wrap its default export instead of `handler`.// vite.config.ts needs tanstackStart: { server: { entry: "server" } } (Lovable apps have it).export default withBelvador(  (env: { BELVADOR_DSN?: string; BELVADOR_RELEASE?: string }) => ({    dsn: env.BELVADOR_DSN ?? "https://<public-key>@ingest.belvador.dev/<project-id>",    release: env.BELVADOR_RELEASE,  }),  handler,);```MiddlewareĐặt ở cuối mỗi danh sách để thấy lỗi server function và server route trước khi middleware trang lỗi xử lý.src/start.ts```typescriptimport "./instrument"; // first line: the browser loads start.ts before the routerimport { createStart } from "@tanstack/react-start";import { belvadorFunctionMiddleware, belvadorRequestMiddleware } from "@belvador/tanstack-start";export const startInstance = createStart(() => ({  // Last in each list, after your own middleware.  requestMiddleware: [/* …your middleware, */ belvadorRequestMiddleware],  functionMiddleware: [/* …your middleware, */ belvadorFunctionMiddleware],}));```Content Security PolicyNếu ứng dụng có header CSP, cho phép địa chỉ nhận lỗi trong connect-src.```textconnect-src 'self' https://ingest.belvador.dev;```Kiểm trình duyệtChứng minh lỗi bắt bằng code và lỗi không bắt ở trình duyệt tới đúng project này, rồi đọc lại kết quả từ Belvador.```typescriptimport { verifyIntegration } from "@belvador/tanstack-start/client";// Run once after setup or deploy (for example behind a debug flag), never on every page load.// The console shows one expected "Belvador verification (uncaught)" error — that is the test.const result = await verifyIntegration();// result.outcome: "verified" | "problem" | "unconfirmed"; the console prints one summary line.```Kiểm máy chủChứng minh code máy chủ chạy trong middleware của Belvador và lỗi của nó tới đúng project này.src/routes/api/verify-belvador.ts```typescriptimport { createFileRoute } from "@tanstack/react-router";import { verifyIntegration } from "@belvador/tanstack-start/server";// Temporary: open /api/verify-belvador once after deploying, then delete this file.// It must run inside belvadorRequestMiddleware (src/start.ts) — that is part of the check.export const Route = createFileRoute("/api/verify-belvador")({  server: {    handlers: {      GET: async () => Response.json(await verifyIntegration()),    },  },});```Đọc lại kết quảDùng id app đã in ra. Kết quả liệt kê phép kiểm nào đã tới node.```bashcurl -s "https://ingest.belvador.dev/api/<project-id>/verification/bv1_<id printed by your app>/?sentry_key=<public-key>"```Trước khi báo xongChạy phép kiểm cho mọi môi trường ở trên. Chỉ báo xong khi từng kết quả là verified (hoặc kết quả đọc lại có đủ mọi phép kiểm). Nếu kết quả là problem hoặc unconfirmed, đưa nguyên dòng "[belvador] verify …" hoặc kết quả đọc lại cho người dùng. Không bao giờ xoá middleware, trang lỗi hay header bảo mật sẵn có để phép kiểm qua.Theo dõi việc chạy ngầmHỏi người dùng cần theo dõi cron job, hàng đợi hay worker nào — không tự đoán. Dùng withMonitor (SDK Belvador), API crons của Sentry SDK, hoặc check-in qua HTTP. Chạy thử mỗi job một lần và chỉ báo xong khi trang Monitor của Belvador thấy lượt đó. Trình duyệt không bao giờ gửi check-in.

@belvador/reactRuntime: browserreact: ^18.0.0 || ^19.0.0Cài đặtThêm gói vào ứng dụng.```bashnpm install @belvador/react@0.6.1```Khởi tạoKhởi tạo càng sớm càng tốt. Dữ liệu cá nhân và thông tin đăng nhập bị loại bỏ trước khi gửi.src/instrument.ts```typescriptimport { init } from "@belvador/react";init({  dsn: "https://<public-key>@ingest.belvador.dev/<project-id>",  release: import.meta.env.VITE_APP_VERSION, // your build or commit id  environment: import.meta.env.MODE,});```Import đầu tiênĐặt nó là dòng import đầu tiên của file entry. Các import chạy trước phần còn lại của file, nên lỗi xảy ra lúc các module của app đang nạp chỉ được báo khi Belvador đã khởi động trước đó.src/main.tsx```tsximport "./instrument"; // first line: starts Belvador before App's modules loadimport { createRoot } from "react-dom/client";import { ErrorBoundary } from "@belvador/react";import App from "./App";const root = document.getElementById("root");if (!root) throw new Error("Root element missing");createRoot(root).render(  <ErrorBoundary fallback={<p>Something went wrong.</p>}>    <App />  </ErrorBoundary>,);```Content Security PolicyNếu ứng dụng có header CSP, cho phép địa chỉ nhận lỗi trong connect-src.```textconnect-src 'self' https://ingest.belvador.dev;```Kiểm trình duyệtChứng minh lỗi bắt bằng code và lỗi không bắt ở trình duyệt tới đúng project này, rồi đọc lại kết quả từ Belvador.```typescriptimport { verifyIntegration } from "@belvador/react";// Run once after setup or deploy (for example behind a debug flag), never on every page load.// The console shows one expected "Belvador verification (uncaught)" error — that is the test.const result = await verifyIntegration();// result.outcome: "verified" | "problem" | "unconfirmed"; the console prints one summary line.```Đọc lại kết quảDùng id app đã in ra. Kết quả liệt kê phép kiểm nào đã tới node.```bashcurl -s "https://ingest.belvador.dev/api/<project-id>/verification/bv1_<id printed by your app>/?sentry_key=<public-key>"```Trước khi báo xongChạy phép kiểm cho mọi môi trường ở trên. Chỉ báo xong khi từng kết quả là verified (hoặc kết quả đọc lại có đủ mọi phép kiểm). Nếu kết quả là problem hoặc unconfirmed, đưa nguyên dòng "[belvador] verify …" hoặc kết quả đọc lại cho người dùng. Không bao giờ xoá middleware, trang lỗi hay header bảo mật sẵn có để phép kiểm qua.Theo dõi việc chạy ngầmHỏi người dùng cần theo dõi cron job, hàng đợi hay worker nào — không tự đoán. Dùng withMonitor (SDK Belvador), API crons của Sentry SDK, hoặc check-in qua HTTP. Chạy thử mỗi job một lần và chỉ báo xong khi trang Monitor của Belvador thấy lượt đó. Trình duyệt không bao giờ gửi check-in.

OpenTelemetry traces and logs → Belvador: Node.jstraces: supported (Belvador certification run 2026-10-24)logs: supported (Belvador certification run 2026-10-24), records carry trace_id/span_idTested with: node 22.23.4, @opentelemetry/sdk-node 0.300.0, @opentelemetry/auto-instrumentations-node 0.82.0, pino 10.4.0Guide: https://belvador.dev/vi/docs/otel/nodeMục tiêuGửi traces và logs OpenTelemetry của dịch vụ này tới Belvador qua OTLP/HTTP. Giữ nguyên SDK lỗi đang có (Belvador hoặc Sentry).Trước khi sửaXác định runtime và phiên bản, kiểu module (CommonJS hay ES modules với Node.js), framework, cách app khởi động ở production và nơi chạy. Tìm phần khởi tạo OpenTelemetry, tracing của Sentry hoặc của nhà cung cấp khác đã có. Nếu đã có thứ tạo span, thêm Belvador làm đích xuất cho phần đó; nếu không rõ bên nào làm chủ tracing, hãy hỏi người dùng. Không bao giờ đọc, in hay commit bí mật — dùng chỗ giữ khoá.Quy tắcMỗi tiến trình một tracer provider; không thêm SDK hay lớp bọc handler thứ hai cũng tạo span. Không đổi xác thực, thứ tự middleware hay logic nghiệp vụ. Không bật thu thân request/response, header, cookie, giá trị query hay nội dung tin nhắn GenAI. Để metrics tắt. Khoá ingest là bí mật phía máy chủ: chỉ trong biến môi trường hoặc kho bí mật, không bao giờ trong code trình duyệt hay biến môi trường công khai. Không dùng OpenTelemetry trên trình duyệt. Giữ cơ chế gom lô của exporter; không bao giờ chờ xuất dữ liệu trong từng request.Biến môi trườngĐặt các biến này ở nơi app chạy (khoá để trong kho bí mật). Dùng tên thật của dịch vụ và môi trường của bản triển khai.```bashexport OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.belvador.dev/otlp/<project-id>export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobufexport OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer%20<your-ingest-key>export OTEL_TRACES_EXPORTER=otlpexport OTEL_LOGS_EXPORTER=otlpexport OTEL_METRICS_EXPORTER=noneexport OTEL_SERVICE_NAME=my-serviceexport OTEL_RESOURCE_ATTRIBUTES=deployment.environment.name=production```Công thức đã chứng nhậnLàm đúng các bước này; đây là các bước lần chứng nhận của Belvador chạy. Chỉ đổi tên file, lệnh khởi động và tên dịch vụ cho hợp với project, và ghim phiên bản gói như phần còn lại của project.```bashnpm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/auto-instrumentations-node``````bashexport OTEL_SEMCONV_STABILITY_OPT_IN=httpexport OTEL_NODE_RESOURCE_DETECTORS=env,host,osnode --require @opentelemetry/auto-instrumentations-node/register app.js``````bashexport OTEL_SEMCONV_STABILITY_OPT_IN=httpexport OTEL_NODE_RESOURCE_DETECTORS=env,host,osnode --experimental-loader=@opentelemetry/instrumentation/hook.mjs --import @opentelemetry/auto-instrumentations-node/register app.mjs```Kiểm chứngChạy app trên máy với các biến đã đặt và gửi một request. Xác nhận trang Traces của Belvador có một trace với span server và span client, trang Logs có một dòng log cùng trace ID. Sau đó nhờ người dùng bấm "Kiểm kết nối OTLP" ở tab Kết nối của project. Không gửi dữ liệu thử vào production nếu người dùng chưa cho phép.Báo cáoLiệt kê các file đã sửa, các gói đã thêm kèm phiên bản chính xác, cách tắt (bỏ OTEL_EXPORTER_OTLP_ENDPOINT hoặc gỡ cờ khởi động), môi trường và loại dữ liệu đã thực sự thấy tới, và những gì chưa kiểm.