Checklist debug và FAQ

Shell vẫn hiện header, catalog không mở được, còn cart chỉ lỗi trên một số tab sau deploy. Bạn nên kiểm tra URL, cache hay React trước? Bắt đầu bằng bước đầu tiên có bằng chứng sai, không bằng config dễ chỉnh nhất.

Trang này là checklist dùng xuyên suốt một lần điều tra: giữ lần lỗi ban đầu, xác định document đang dùng tổ hợp release nào, khoanh vùng boundary rồi chuyển sang runbook chuyên sâu. Mình ưu tiên mỗi lần thử chỉ thay một yếu tố; xóa cache, đổi URL và nâng dependency cùng lúc có thể làm lỗi biến mất nhưng không giải thích được nguyên nhân.

Mục lụcCopy Anchor Link

• Trình tự xử lý khi đang có incident
  • Giảm ảnh hưởng
  • Giữ bằng chứng ban đầu
  • Tìm boundary đầu tiên bị lỗi
  • Kiểm chứng giả thuyết rồi sửa đúng owner
• Chọn nhánh điều tra theo triệu chứng
• Checklist bằng chứng tối thiểu
• Kiểm tra Network và Console
  • Theo đường tải thực tế
  • Đọc response thay vì chỉ đọc status
  • Kiểm chứng HTTP bằng curl
• Đối chiếu manifests và release versions
  • Phân biệt các loại manifest
  • Lập release map của document đang lỗi
  • Kiểm tra contract và tổ hợp tương thích
• Kiểm tra runtime đúng format
  • Webpack classic script
  • Module Federation enhanced và ESM
  • SSR và hydration
• Dùng telemetry để xác định phạm vi
• So sánh có kiểm soát
• Giảm ảnh hưởng và phục hồi an toàn
• Ca mẫu entry thành công nhưng catalog không mở
• Checklist xác nhận đã sửa
• Mẫu bàn giao incident
• FAQ
  • Remote trả 200 thì đã loại trừ lỗi tải chưa
  • Standalone chạy được thì lỗi chắc chắn ở shell không
  • Hard reload hết lỗi có chứng minh CDN cache sai không
  • Đổi config rồi vì sao tab vẫn chạy release cũ
  • Không có telemetry có nghĩa là không còn lỗi không
  • Nên xử lý lỗi nào khi Console có nhiều lỗi
• Tài liệu tham khảo
• Đọc tiếp

Trình tự xử lý khi đang có incidentCopy Anchor Link

Chọn nhánh điều tra theo triệu chứngCopy Anchor Link

Error string là chỉ dẫn chọn nơi xem, không phải kết luận. Ví dụ ChunkLoadError có thể do asset thiếu, sai publicPath, timeout hoặc policy chặn; nó không tự chứng minh cache sai.

Checklist bằng chứng tối thiểuCopy Anchor Link

• Môi trường, browser/version, route đã normalize và thao tác tái hiện cụ thể.
• Lỗi xảy ra khi click trong app, mở trực tiếp, refresh, Back/Forward hay sau khi tab để lâu.
• Thời điểm kèm timezone; thời điểm tab khởi động nếu biết; mốc deploy/config change liên quan.
• Shell release thực tế, config revision đang dùng, remote release được chọn và release thực tế nếu đã có metadata.
• Error đầu tiên, stack và boundary sở hữu lỗi; ghi riêng các lỗi xuất hiện sau đó.
• Request URL liên quan, status hoặc blocked reason, response body/MIME, redirect chain và Initiator.
• Response đến từ network, HTTP cache, service worker hay CDN; ghi unknown nếu chưa xác định.
• Phạm vi ảnh hưởng từ telemetry: journey, cohort, tổ hợp release và nhóm đối chứng.
• Những thử nghiệm đã làm, mỗi lần thay gì, kết quả và hành động giảm ảnh hưởng hiện tại.

Không ghi “latest” thay cho build ID. Không biết remote đã chạy release nào thì ghi chưa xác nhận, thay vì lấy version trên trang dashboard deploy để điền vào.

Kiểm tra Network và ConsoleCopy Anchor Link

Theo đường tải thực tếCopy Anchor Link

direction: down
n0: "Document / config"
n1: "Resolve remote"
n2: "Entry + dependency graph"
n3: "Initialize / evaluate"
n4: "Mount / render / ready"
n5: "API / events / commands"
n0 -> n1 -> n2 -> n3 -> n4 -> n5

Đây là các boundary để khoanh vùng, không phải thứ tự nội bộ bắt buộc: runtime có thể tải shared modules và chunks xen kẽ, hoặc preload trước khi route mở.

1. Kiểm tra request Document nếu shell không lên hoặc deep link lỗi. Với SPA tĩnh, response phải là shell HTML đúng; với SSR, kiểm tra server response theo framework.
2. Tìm config hoặc manifest mà document thực sự consume. Nếu config được nhúng vào HTML hoặc remotes được chốt lúc build, không có request config riêng là bình thường.
3. Đối chiếu Request URL của entry với descriptor đã resolve. Bỏ bộ lọc Network nếu không thấy request; CSP/mixed content có thể chặn trước khi gửi.
4. Khi entry thành công, theo Initiator tới chunk, module, CSS hoặc font liên quan. Giữ request thất bại đầu tiên trong đường này.
5. Nếu graph tải được, xem lỗi initialize/evaluate/mount. Network toàn 200 không chứng minh code đã chạy thành công.
6. Khi UI đã mount, tách API/command failure khỏi loader failure. API 401 không mặc nhiên là lỗi CORS của remote.

Chọn đúng execution context của shell, iframe hoặc worker trong DevTools. Console của tab standalone không cho biết runtime trong shell; với SSR, server logs cũng không thay thế Console của browser.

Đọc response thay vì chỉ đọc statusCopy Anchor Link

Đọc Cache-Control, Age, ETag, Vary và headers cache của nhà cung cấp cùng nhau. Age không phải tuổi của release; ETag không mặc nhiên là commit/build ID nếu pipeline chưa định nghĩa ánh xạ đó. Một header riêng lẻ không đủ xác định owner của bytes sai.

Kiểm chứng HTTP bằng curlCopy Anchor Link

Ví dụ sau dùng GET tới catalog của lab đang chạy, lưu kết quả vào thư mục tạm, không ghi đè file trong workspace:

ENTRY_URL='http://localhost:3001/remoteEntry.js'
CHECK_DIR="$(mktemp -d)"

curl --silent --show-error \
  --connect-timeout 5 --max-time 15 \
  --dump-header "$CHECK_DIR/headers.txt" \
  --output "$CHECK_DIR/body.txt" \
  --write-out 'status=%{http_code}\nurl=%{url_effective}\n' \
  "$ENTRY_URL"

cat "$CHECK_DIR/headers.txt"
head -c 300 "$CHECK_DIR/body.txt"
printf '\nKết quả lưu tại: %s\n' "$CHECK_DIR"

Timeouts là giá trị minh họa cho chẩn đoán, không phải SLO. Lệnh không follow redirect để bạn thấy response đầu tiên và không dùng --fail để giữ body lỗi HTTP. Đọc cả exit status của curl và HTTP status: curl có thể thoát thành công khi endpoint trả 404.

Kết quả mong đợi cho GET mới là 200, MIME JavaScript và body của entry; đây vẫn chỉ là kiểm chứng HTTP. Curl không thực thi JavaScript, CORS/CSP, service worker hay module cache của tab. Dùng cùng URL thực tế từ browser khi kiểm tra production, không tự thêm token hoặc signed query vào log chia sẻ.

Đối chiếu manifests và release versionsCopy Anchor Link

Phân biệt các loại manifestCopy Anchor Link

Config của ứng dụng có thể chọn một URL federation manifest, rồi runtime đọc manifest để tìm entry. Đừng đưa mf-manifest.json vào loader classic script mong đợi JavaScript, hoặc dùng validator của config shop để kết luận federation manifest “sai schema”.

Đối chiếu snapshot đã dùng lúc resolve, không fetch config hiện tại rồi coi đó là snapshot của tab lỗi. Endpoint có thể đã đổi revision trong lúc document vẫn pin revision cũ. Với remotes compile-time, URL nằm trong shell artifact; đổi biến môi trường của hosting không tự cập nhật bundle đã build.

Lập release map của document đang lỗiCopy Anchor Link

Một release map cần phân biệt ba loại bằng chứng: config đã chọn gì, network đã trả gì và module đã báo metadata gì. Bảng sau là mẫu ghi nhận, không phải API bắt buộc:

Nếu load thất bại trước khi module execute, chỉ biết candidate release; không điền actual bằng candidate. Metadata tự khai báo là bằng chứng chẩn đoán cần đối chiếu artifact inventory, không phải cơ chế xác thực code đáng tin cậy.

Hai tab chạy catalog r18 và r19 có thể đều đúng nếu policy pin release theo document. Điều cần kiểm tra là mỗi tab có graph nhất quán và còn tải được lazy chunks trong cửa sổ hỗ trợ. “Không chạy bản mới nhất” khác với “nhận bytes sai tại URL bất biến”.

Kiểm tra contract và tổ hợp tương thíchCopy Anchor Link

• Schema version của config được shell đang chạy hỗ trợ.
• Environment, flag/cohort và URL allowlist khớp policy của shell.
• Host alias, container name, remote format và public key khớp integration.
• Remote contract version, export shape hoặc mount handshake được shell chấp nhận.
• Shared version constraints, singleton policy và provider selection đúng contract đã test.
• Tổ hợp shell/catalog/cart hiện tại có bằng chứng contract hoặc integration test; không chỉ từng app standalone pass.
• Với rollback target, toàn bộ entry, chunks, CSS và source maps cần thiết vẫn được giữ theo policy.

Version package trong source mới nhất không chứng minh version đang chạy. npm ls trong workspace giúp xem dependency tree của build đó, nhưng không tự chứng minh browser có một React identity hay share scope đã chọn provider nào.

Kiểm tra runtime đúng formatCopy Anchor Link

Webpack classic scriptCopy Anchor Link

Sau khi shell đã thử tải catalog của lab, chọn Console context của shell và chỉ đọc container:

const container = globalThis.shop_catalog;
({
  present: Boolean(container),
  get: typeof container?.get,
  init: typeof container?.init,
});

Kỳ vọng present: true, get: 'function', init: 'function'. Nếu thiếu, kiểm tra format, tên container và error lúc execute entry. Nếu có, mới chuyển sang public key ./CatalogPage, share initialization và lỗi module.

Không tự gọi container.init({}), ghi đè global hay chèn entry của release khác vào document để “reset”. Việc đó thay runtime state, có thể tạo container/share-scope conflict và phá tính hợp lệ của phép so sánh. Không có public reset chung áp dụng cho mọi integration.

Module Federation enhanced và ESMCopy Anchor Link

Trong integration enhanced có hỗ trợ debug globals, xem dữ liệu đã được runtime công bố:

({
  federation: globalThis.__FEDERATION__,
  shared: globalThis.__SHARE__,
});

Theo tài liệu runtime tương ứng, __FEDERATION__ chứa thông tin federation sau initialization; __SHARE__ giúp quan sát trạng thái shared modules. Đọc instance, module resolution và provider/version liên quan, nhưng không sửa các globals. Structure và khả năng có mặt phụ thuộc integration/version; thiếu globals không tự chứng minh remote lỗi và webpack core không bắt buộc cung cấp chúng.

Với ESM remote, container có thể nằm trong module namespace thay vì window. Kiểm tra module URL, imports, MIME, CORS và export contract của plugin. Đừng thêm global chỉ để snippet webpack bên trên trả true.

SSR và hydrationCopy Anchor Link

Ghi riêng server release/config snapshot và browser release/config snapshot. Server consume remote thành công không chứng minh browser tải được client graph; localhost trên server và trong browser cũng không cùng đích.

Nếu hydration lỗi, đối chiếu release pin giữa HTML server render và client bootstrap, dữ liệu đầu vào, shared framework compatibility và stack phía browser. Dùng logs/traces phía server cho lỗi server, Console/Network phía client cho lỗi client; không gom hai lỗi thành một kết luận “CORS”. Xem thêm Next.js và SSR.

Dùng telemetry để xác định phạm viCopy Anchor Link

Bắt đầu từ journey và khoảng thời gian có deploy/config change, rồi chia theo môi trường, shell release, candidate/actual remote release, config revision và cohort. So sánh với tổ hợp chưa rollout cùng journey; lỗi tăng ngay sau deploy là tương quan để điều tra, chưa đủ chứng minh deploy là nguyên nhân.

Các field trên là schema ứng dụng minh họa theo Observability, không phải tên bắt buộc của mọi SDK. Nếu subject_release ở load event chỉ là candidate, giữ nguyên ý nghĩa đó khi điều tra; chỉ gán actual release khi có bằng chứng module đã chạy.

Đừng kết luận remote “ready” chỉ vì import Promise resolve. Ready phải theo contract của journey, chẳng hạn route render được và dữ liệu thiết yếu đã sẵn sàng. Tách timeout, cancellation do navigation bị thay thế và failure thực sự để không làm sai tỷ lệ lỗi.

Nếu global handler chỉ biết app unknown, giữ thông tin đó, không đoán owner từ route. Với API lỗi, nối request/trace tới backend nếu propagation đã được triển khai và kiểm chứng; một correlation_id không tự tạo distributed trace.

So sánh có kiểm soátCopy Anchor Link

Sau khi giữ bằng chứng, chọn phép thử có thể bác bỏ giả thuyết. Ghi cả điều giữ nguyên và điều thay đổi.

Disable cache chỉ có tác dụng theo công cụ browser khi bật; nó không xóa module đã evaluate. Nếu lỗi không tạo request mới, xem runtime/module cache và snapshot trước khi chỉnh cache headers.

Không bật query cache-buster ngẫu nhiên cho mọi asset: nó có thể đổi cache key và che graph sai, nhưng không khôi phục chunk đã bị xóa. Không unregister worker hoặc xóa storage hàng loạt chỉ để đạt một lần test xanh.

Giảm ảnh hưởng và phục hồi an toànCopy Anchor Link

Retry load phải có giới hạn, backoff và classification phù hợp runtime. Không retry liên tục lỗi schema, module key không tồn tại hoặc lỗi policy đã biết.

Với command ghi dữ liệu như thêm cart hoặc checkout, timeout không chứng minh backend chưa xử lý. Dùng operation/idempotency contract và xác minh kết quả trước khi retry; retry network loader và retry nghiệp vụ là hai việc khác nhau. Chi tiết vận hành ở Rollout và rollback và Resilience.

Ca mẫu entry thành công nhưng catalog không mởCopy Anchor Link

Giả sử tab A đã mở trước deploy và pin catalog r18; tab B mở sau deploy chọn r19. Sau khi tab A vào một route lazy chưa tải, UI hiện fallback. Dữ liệu minh họa:

Tab A:
  shell release:         shell@demo-a
  config revision:       demo-config-42
  catalog candidate:     r18
  catalog actual:        r18 (metadata ghi nhận từ lần mount trước)
  entry response:        200, JavaScript r18, đã tải trước deploy
  lazy chunk request:    /catalog/releases/r18/product.demo.js → 404

Tab B:
  config revision:       demo-config-43
  catalog candidate:     r19
  same journey:          thành công

Chẩn đoán theo checklist:

1. Giữ Network của tab A, xác nhận URL chunk thuộc r18 và không phải HTML fallback 200.
2. Kiểm tra inventory origin qua công cụ được phép: chunk r18 không còn, trong khi artifact lưu trữ của r18 có file đó.
3. Đối chiếu audit pipeline: cleanup đã xóa graph r18 khi publish r19. Đây là bằng chứng nguyên nhân; tab B chạy tốt một mình chưa chứng minh được điều này.
4. Khôi phục nguyên artifact r18 từ bản lưu và dừng cleanup sớm. Nếu edge cache 404, invalidation đúng URL/key sau khi origin đã phục hồi.
5. Thử lại lazy journey ở tab cũ nếu runtime hỗ trợ retry an toàn; nếu không, dùng phục hồi client có kiểm soát và kiểm thử tab pin r18 trong preview. Kiểm tra thêm tab mới r19.

Kết luận không phải “mọi người cần hard reload” hay “entry phải no-cache”. Selection của hai tab có thể đều đúng; sai ở availability của graph r18. Regression test nên giữ document cũ qua một lần deploy rồi mở route lazy, kèm kiểm tra retention của rollback target.

Checklist xác nhận đã sửaCopy Anchor Link

• Journey gây lỗi ban đầu thành công; không chỉ GET entry hoặc mở trang chủ.
• Config/candidate/actual release có bằng chứng và graph khớp artifact inventory.
• Deep link, refresh, Back/Forward và mount/unmount chạy đúng nếu lỗi chạm routing/lifecycle.
• Tab cũ lẫn document mới được kiểm tra khi liên quan deploy/cache; có route lazy chưa tải.
• Shell/catalog/cart chạy với tổ hợp rollback và rollout target đã kiểm chứng.
• Fallback, timeout, retry và cancellation không tạo loop hoặc mất dữ liệu chưa lưu.
• Command không bị thực hiện trùng; kết quả chưa rõ đã được reconcile theo contract.
• Không nới security policy hoặc ghi đè URL immutable để làm test pass.
• Telemetry có dữ liệu với denominator phù hợp; cohorts bị ảnh hưởng phục hồi trong cửa sổ quan sát đã thống nhất.
• Source map đúng build; owner, nguyên nhân, thay đổi và evidence links đã được lưu.
• Có regression test đúng boundary hoặc kiểm tra pipeline ngăn nguyên nhân tái diễn.

Smoke test xanh là bước đầu. Nếu sampling hoặc traffic thấp chưa đủ xác nhận tỷ lệ lỗi phục hồi, ghi trạng thái “đang quan sát” cùng tiêu chí kết thúc thay vì tuyên bố đã hết lỗi.

Mẫu bàn giao incidentCopy Anchor Link

Dùng mẫu này khi chuyển từ shell owner sang remote, CDN hoặc platform owner. Điền unknown cho phần chưa biết, không tự suy luận để đủ field.

Incident / evidence links:
Environment, thời điểm và timezone:
Journey / route template:
Impact / cohorts / cửa sổ quan sát:
Browser và execution context:
Cách tái hiện, tab cũ hay document mới:

Shell actual release:
Config revision đã consume:
Remote alias / format / container / public key:
Remote candidate release + entry/manifest URL đã rà soát:
Remote actual release + nguồn metadata, hoặc unknown:
Các app/shared providers liên quan:

Boundary đầu tiên bị lỗi:
Error / stack đã sanitize:
Request URL đã rà soát, status/blocked reason, MIME, Initiator:
Response source / cache headers / body excerpt an toàn:
Correlation / trace / request IDs qua kênh nội bộ:

Giả thuyết:
Phép thử, yếu tố thay đổi và kết quả:
Hành động giảm ảnh hưởng hiện tại:
Thay đổi đề xuất / owner / rollback plan:
Kết quả kiểm chứng, phần chưa xác nhận và bước tiếp theo:

Khi escalation, gửi một request/stack đại diện và release map có nguồn, thay vì toàn bộ log không chọn lọc. Ghi rõ bạn cần owner kiểm tra gì, chẳng hạn “xác nhận chunk r18 còn ở origin và thời điểm cleanup”, để lần bàn giao có hành động cụ thể.

FAQCopy Anchor Link

Remote trả 200 thì đã loại trừ lỗi tải chưaCopy Anchor Link

Chưa. 200 có thể là HTML/login, script không execute được hoặc entry đúng nhưng dependency graph lỗi. Kiểm tra body, MIME, browser policy, container/export và chunk tiếp theo. Import thành công cũng chưa chứng minh mount/render/ready đã thành công.

Standalone chạy được thì lỗi chắc chắn ở shell khôngCopy Anchor Link

Không. Standalone có HTML, bootstrap, base URL, router và shared providers riêng; nó có thể không đi qua federated entry. So sánh cùng artifact trong hai đường chạy rồi tìm boundary khác nhau. Owner sửa lỗi có thể là shell, remote adapter, hosting hoặc contract chung.

Hard reload hết lỗi có chứng minh CDN cache sai khôngCopy Anchor Link

Không. Reload tạo document/runtime mới, có thể nhận config, cohort hoặc worker controller khác; đồng thời ảnh hưởng browser cache. Ghi release map và nguồn response trước/sau, rồi kiểm tra từng lớp. Một lần reload hết lỗi chỉ cho biết điều kiện tái hiện đã thay đổi.

Đổi config rồi vì sao tab vẫn chạy release cũCopy Anchor Link

Document có thể pin snapshot, module đã evaluate hoặc remote đã mount. Config mới chỉ ảnh hưởng lần resolve theo contract của loader, không thay code đang chạy. Với giá trị compile-time như URL trong shell bundle hoặc client NEXT_PUBLIC_* của Next.js, đổi environment sau build không cập nhật bundle đó.

Không có telemetry có nghĩa là không còn lỗi khôngCopy Anchor Link

Không. Kiểm tra SDK bootstrap, delivery, sampling và ingest health; đối chiếu Console/Network cùng lượng journey thực tế. Nếu không có denominator hoặc pipeline đang mất dữ liệu, chưa đủ bằng chứng để kết luận phục hồi.

Nên xử lý lỗi nào khi Console có nhiều lỗiCopy Anchor Link

Ưu tiên lỗi liên quan journey tại boundary sớm nhất, dùng timing và Initiator để nối chuỗi. Chunk lỗi có thể làm mount thất bại rồi tạo thêm render error; telemetry endpoint lỗi lại có thể độc lập. Timestamp từ nhiều máy không đủ suy ra thứ tự chính xác: dùng correlation/trace context và bằng chứng trong cùng execution context.

Tài liệu tham khảoCopy Anchor Link

• Chrome DevTools: Network features reference — Preserve log, cache controls, Initiator và HAR export.
• Module Federation: Global variables — debug globals của integration hỗ trợ; chỉ đọc, không sửa.
• Webpack: Module Federation — container, shared modules và các boundary của federation core.

Đọc tiếpCopy Anchor Link