Vì vậy, lỗi này hiếm khi thật sự là chuyện chậm. Thường thì có một bước đang chờ một điều sẽ không bao giờ xảy ra. Dưới đây là các nguyên nhân theo thứ tự tôi hay kiểm tra, kèm cách sửa cho từng cái:

1. Locator (bộ chọn phần tử) không khớp với phần tử nào, nên lệnh click() hay fill() cứ chờ cho tới khi bài kiểm thử hết giờ. Lý do quen thuộc là test ID bị đổi tên, chữ hiển thị bị đổi, hoặc có hộp thoại che phía trước. Cách sửa: sửa lại locator.
2. Một lần chuyển trang hay lệnh waitForURL() đang chờ một trang không bao giờ tới, vì một lần chuyển hướng (redirect), màn hình đăng nhập hoặc màn hình chạy lần đầu đã đưa ứng dụng sang chỗ khác. Cách sửa: sửa lại điều kiện bạn đang chờ.
3. Bước chuẩn bị chậm thật: máy chủ phát triển (dev server) chỉ bắt đầu biên dịch khi có yêu cầu đầu tiên, backend phải khởi động nguội (cold start) sau khi bị thu về 0 (scale to zero), hoặc đăng nhập qua giao diện trong mọi beforeEach. Cách sửa: sửa môi trường, hoặc chỉ chuẩn bị một lần.
4. Bài kiểm thử vốn dĩ dài. Khi đó, và chỉ khi đó, mới cho riêng bài ấy thêm thời gian bằng test.slow() hoặc test.setTimeout().

Dù là trường hợp nào, việc đầu tiên vẫn là tìm ra bước còn đang chạy vào lúc hết giờ. Việc thứ hai là đặt actionTimeout, để ở lần thất bại sau, chính thông báo lỗi sẽ chỉ ra bước đó cho bạn.

Chỉ cần thêm hai dòng vào use:

import { defineConfig } from "@playwright/test";

export default defineConfig({
  timeout: 30_000,
  expect: { timeout: 5_000 },
  use: {
    actionTimeout: 10_000,
    navigationTimeout: 15_000,
    trace: "retain-on-failure",
  },
});

30 giây ấy bao gồm những gì

#

Timeout của bài kiểm thử là một quỹ thời gian duy nhất, dùng chung cho bước chuẩn bị fixture, các hook beforeEach và hàm kiểm thử. Khi bài kiểm thử kết thúc, các hook afterEach và bước dọn dẹp fixture (teardown) được cấp thêm một quỹ thời gian riêng có cùng độ dài. beforeAll và afterAll cũng nhận cùng giá trị đó, nhưng không dùng chung với bài kiểm thử nào, và khi hết giờ thì báo lỗi bằng thông điệp riêng.

Trong quỹ thời gian đó, chỉ có các câu lệnh kiểm tra (assertion) là có đồng hồ riêng. await expect(locator).toBeVisible() mặc định bỏ cuộc sau 5 giây và cho bạn biết chính xác nó đang tìm gì. Các thao tác và lệnh chuyển trang thì không: actionTimeout và navigationTimeout mặc định là không giới hạn. Đó là toàn bộ lý do khiến lỗi này mơ hồ đến vậy. Một lệnh bấm vào phần tử sẽ không bao giờ xuất hiện thì không hề thất bại. Nó chỉ ngoan ngoãn chờ, cho tới khi có thứ khác kết thúc bài kiểm thử.

Bảng dưới đây liệt kê mọi loại timeout có thể kết thúc một lần chạy, cùng thông báo mà mỗi loại in ra. Các thông báo được chép nguyên văn từ Playwright 1.58 và 1.63, phiên bản cũ nhất và mới nhất trong các dự án của tôi.

Ba hàng thao tác, chuyển trang và toàn bộ lần chạy không có giá trị mặc định để in ra, nên con số ở đó là giá trị do bạn tự đặt.

Năm bài kiểm thử và một test ID bị đổi tên

#

Hồi tháng 2, trong một lần chạy, năm bài kiểm thử trong bộ kiểm thử của ứng dụng báo giá mà tôi đang làm đã thất bại theo cùng một kiểu. Bộ kiểm thử này dùng Playwright để điều khiển bản web của ứng dụng (do máy chủ phát triển của ứng dụng phục vụ), chạy với một worker, gọi tới một backend cục bộ vừa được nạp lại dữ liệu mẫu (seed). Đây là lỗi đầu tiên trong năm lỗi, đã lược bớt:

  1) [default] › tests/example.spec.ts:50:7 › Templates › should edit a template ───

    Test timeout of 30000ms exceeded.

    Error: locator.click: Target page, context or browser has been closed
    Call log:
      - waiting for locator('[data-testid="template-item"]').filter({ hasText: 'E2E Edit Template' }).locator('[data-testid="edit-template"]')


      57 |       .locator('[data-testid="template-item"]')
      58 |       .filter({ hasText: "E2E Edit Template" });
    > 59 |     await item.locator('[data-testid="edit-template"]').click();
         |                                                         ^
      60 |     await page.waitForTimeout(500);

Chỉ nhìn dòng Target page, context or browser has been closed thì tưởng trình duyệt bị sập. Không phải vậy. Đó là thông báo mà một thao tác đưa ra khi trang bị đóng ngay dưới chân nó: 30 giây đã hết, Playwright dọn dẹp bài kiểm thử, và lệnh bấm vẫn đang chờ kia báo lại rằng trang của nó đã mất. Nếu dùng fixture page có sẵn, dòng đó sẽ nhắc lại chuyện hết giờ, thành Error: locator.click: Test timeout of 30000ms exceeded. Các bài kiểm thử này tự mở ngữ cảnh trình duyệt (browser context) trong beforeAll, nên lệnh bấm chỉ nhận được thông báo chung chung.

Dòng có ích là nhật ký lệnh gọi (call log). Lệnh bấm đang chờ [data-testid="template-item"]. Mười tiếng trước đó, tôi đã đổi test ID của component dòng danh sách từ template-item thành template-item-${name}, để các bài kiểm thử đầu cuối (end-to-end) trên bản native của ứng dụng có thể chọn đúng một dòng theo tên. Bộ chọn (selector) thuộc tính dùng = đòi hỏi khớp toàn bộ giá trị, nên lúc này các bài kiểm thử web đang tìm một phần tử không hề tồn tại ở đâu trên trang. Lại không có timeout cho thao tác, nên lệnh bấm đó chắc chắn sẽ chờ cho tới khi bài kiểm thử hết giờ. Năm bài kiểm thử, mỗi bài 30 giây, là hai phút rưỡi, trong một lần chạy tổng cộng mất 3.8 phút.

Thứ tôi thêm vào đầu tiên là chạy lại (retry). Chưa tới nửa tiếng sau, tệp cấu hình đã có retries: process.env.CI ? 2 : 1, kèm một dòng chú thích mà tới giờ vẫn ghi “for flaky browser crashes”, tức là để phòng những lần trình duyệt thỉnh thoảng bị sập. Ở lần chạy kế tiếp, bốn trong năm bài kiểm thử cũ lại thất bại, kể cả ở lần chạy lại, và lần chạy kéo dài 6.4 phút thay vì 3.8. Các khối describe này chạy ở chế độ tuần tự (serial): một bài thất bại thì các bài còn lại trong nhóm bị bỏ qua, còn khi chạy lại thì cả nhóm chạy lại từ đầu. Vì thế mỗi lệnh bấm hỏng đã chờ trọn 30 giây tới hai lần. Một bài kiểm thử lần nào cũng thất bại theo cùng một cách thì chạy lại không cứu được. Nó chỉ bắt bạn trả giá hai lần.

Cách sửa là khớp theo tiền tố:

const item = page
  .locator('[data-testid^="template-item-"]')
  .filter({ hasText: "E2E Edit Template" });
await item.locator('[data-testid="edit-template"]').click();

Bài học rộng hơn là test ID cũng là một dạng hợp đồng, và tôi có tới hai bộ kiểm thử cùng dựa vào ID này mà không bên nào biết bên kia tồn tại. Hướng dẫn thực hành tốt (best practices) của Playwright khuyên ưu tiên các locator dựa trên thuộc tính người dùng nhìn thấy được, như getByRole(), thay vì bộ chọn CSS như của tôi, để bài kiểm thử không vỡ vì những thay đổi DOM mà người dùng chẳng bao giờ nhận ra. Còn nếu bạn mới bắt đầu thiết lập Playwright, lý do tôi khuyên nên bắt đầu từ so sánh ảnh chụp màn hình nằm trong bài Kiểm thử hồi quy giao diện (visual regression testing) với Playwright cho đội nhỏ.

Tìm bước bị treo

#

Hãy đọc call log trước tiên. Nó thuộc về bước vẫn còn đang chạy lúc hết giờ, và nếu sau dòng waiting for locator(...) không có gì nữa, nghĩa là locator chưa bao giờ khớp được với phần tử nào.

Nếu vẫn chưa đủ, hãy mở bản ghi thực thi (trace). Hai bộ kiểm thử ứng dụng của tôi, một cho ứng dụng báo giá và một cho ứng dụng chợ kiêm cộng đồng mà tôi đang làm, đều dùng trace: "on-first-retry". Tùy chọn này chỉ ghi lại ở lần chạy lại đầu tiên, nên cần đặt retries ít nhất là 1. Nếu không dùng chạy lại thì dùng "retain-on-failure"; còn muốn chạy thử một lần thì thêm --trace on. Sau đó mở trace trực tiếp, hoặc mở từ báo cáo HTML:

npx playwright show-trace test-results/<test-folder>/trace.zip
npx playwright show-report

Thao tác chưa bao giờ hoàn tất là mục mang thông báo lỗi, nằm gần cuối danh sách. Chọn nó rồi xem ảnh chụp nhanh (snapshot): đó là trang đúng như lúc Playwright đang chờ, và bạn có thể soi trong đó để tìm phần tử mình mong đợi. Với trường hợp như của tôi, dòng danh sách vẫn nằm ngay đó, chỉ là mang một ID mà bài kiểm thử không hề tìm.

Các phiên bản gần đây còn ghi thêm một tệp error-context.md bên cạnh ảnh chụp màn hình lúc thất bại, chứa ảnh chụp nhanh dạng văn bản của trang vào đúng lúc lỗi xảy ra. Với trường hợp thiếu phần tử, chỉ riêng tệp này nhiều khi là đủ.

Có một cái bẫy: --debug vừa mở Inspector vừa đặt --timeout=0, cùng với --max-failures=1, --headed và --workers=1. Một bài kiểm thử chạy qua được dưới --debug chẳng nói lên điều gì về 30 giây kia.

Đặt trần thời gian cho mọi thao tác

#

Không tệp cấu hình nào của tôi đặt timeout cho thao tác, và đó là lý do một phần tử không tồn tại có thể tiêu tốn 30 giây, tới năm lần. Với đoạn cấu hình ở đầu bài, cùng cái locator hỏng ấy sẽ thất bại như thế này, trong lúc bài kiểm thử vẫn còn thời gian:

    TimeoutError: locator.click: Timeout 10000ms exceeded.
    Call log:
      - waiting for locator('[data-testid="template-item"]').filter({ hasText: 'E2E Edit Template' }).locator('[data-testid="edit-template"]')

Thông báo nêu rõ bước nào, thao tác nào và đã chờ bao lâu. Tôi nghĩ nên để cả hai giá trị thấp hơn hẳn timeout của bài kiểm thử, để một bước bị kẹt không thể ngốn hết quỹ thời gian rồi nấp sau thông báo mơ hồ kia. Hồi tháng 2, vấn đề chưa bao giờ nằm ở con số 30 giây. Đó chỉ là chiếc đồng hồ duy nhất gắn với lệnh bấm ấy, nên nó là cái reo lên.

Chỉ tăng timeout cho bài kiểm thử dài, đừng tăng cho bài bị kẹt

#

Tăng timeout là cách sửa đúng khi bài kiểm thử đang làm việc thật và việc đó tốn thời gian. Nó là cách sửa sai khi có một bước đang chờ điều sẽ không xảy ra, vì con số lớn hơn chỉ khiến thất bại đến chậm hơn. Bản ghi trace thường cho biết bạn đang gặp trường hợp nào: một chuỗi thao tác đều đặn, cái nào cũng hoàn tất, chỉ là có nhiều, thì đó là bài kiểm thử dài; còn một thao tác nằm ở trạng thái waiting for cho tới tận cuối thì đó là bài bị kẹt.

Với bài kiểm thử dài, hãy thêm thời gian ở đúng chỗ dài chứ đừng nới cho cả bộ kiểm thử. Bộ kiểm thử của ứng dụng chợ có một bài kiểm thử khói (smoke test) đi qua màn hình chat và chụp ảnh màn hình ở từng bước, và bài này được cho ba phút:

test("chat: open, send a message, go back", async ({ page }) => {
  test.setTimeout(180_000);
  // ...
});

Gọi test.setTimeout() bên trong describe thì nó áp dụng cho mọi bài kiểm thử trong nhóm (dạng được tài liệu hướng dẫn hiện nay là test.describe.configure({ timeout: 60_000 })); bài kiểm thử tính chi phí công việc (job-cost) trong bộ kiểm thử của ứng dụng báo giá được một phút theo cách đó. test.slow() nhân ba timeout hiện tại, bất kể nó đang là bao nhiêu, và có thể nhận một điều kiện. Trong beforeEach, testInfo.setTimeout() kéo dài thời gian cho mọi bài kiểm thử đi qua hook đó:

test("slow in WebKit", async ({ page, browserName }) => {
  test.slow(browserName === "webkit", "This page is slow in WebKit");
  // ...
});

test.beforeEach(async ({ page }, testInfo) => {
  testInfo.setTimeout(testInfo.timeout + 30_000);
});

Còn một thứ nữa lặng lẽ ăn vào quỹ thời gian ở mọi lần chạy: những lần ngủ cố định. Bộ kiểm thử của ứng dụng báo giá có hơn một trăm lệnh gọi page.waitForTimeout(), rải gần như khắp các tệp spec. Bài kiểm thử chỉnh sửa ở trên ngủ ba giây trước cả khi tới được lệnh bấm, và ngủ bao lâu cũng không cứu được nó. Tài liệu API của Playwright nói rất thẳng về chuyện này: “Never wait for timeout in production. Tests that wait for time are inherently flaky.” Nghĩa là: đừng bao giờ chờ theo thời gian khi chạy thật, vì bài kiểm thử chờ theo thời gian vốn dĩ đã chập chờn. Một assertion kiểu web-first (web-first assertion) vốn đã chờ đúng bao lâu cần thiết, không hơn:

// before
await page.locator('[data-testid="save-template"]').click();
await page.waitForTimeout(1500);
await expect(page.getByText("E2E Edited Template")).toBeVisible();

// after
await page.locator('[data-testid="save-template"]').click();
await expect(page.getByText("E2E Edited Template")).toBeVisible();

Timeout của assertion cũng cần cẩn thận như vậy. Cả hai bộ kiểm thử ứng dụng của tôi đều nâng expect.timeout lên 15 giây, và cả hai đều chạy với máy chủ phát triển của ứng dụng chứ không phải bản build production. Như vậy là có thêm khoảng đệm, nhưng hai assertion chậm liền nhau có thể tiêu hết 30 giây, và khi đó timeout của bài kiểm thử sẽ nổ trước, bạn lại quay về với thông báo mơ hồ.

Khi đồng hồ không phải của bài kiểm thử

#

Nếu thông báo có nhắc tới config.webServer, nghĩa là chưa bài kiểm thử nào kịp chạy. Playwright khởi động lệnh webServer của bạn và chờ cho tới khi url của nó phản hồi rồi mới chạy kiểm thử, với một timeout riêng, mặc định là 60 giây. Cả hai bộ kiểm thử ứng dụng của tôi đều cho máy chủ phát triển hai phút:

webServer: {
  command: "npm run web -- --port 8081",
  url: "http://localhost:8081",
  reuseExistingServer: false,
  timeout: 120_000,
},

Nếu bài kiểm thử của bạn chạy với một môi trường đã triển khai thay vì máy chủ cục bộ, hãy tìm hiểu xem yêu cầu đầu tiên tới đó mất bao lâu. Khi cuối cùng cũng đo môi trường của mình trên nền tảng hosting đang dùng, tôi thấy một máy khởi động nguội từ trạng thái thu về 0 mất từ 25 tới 33 giây mới phục vụ được bất cứ thứ gì. Tức là phần lớn, thậm chí toàn bộ quỹ thời gian của một bài kiểm thử, trước cả lần bấm đầu tiên. Câu chuyện đó nằm trong bài Khởi động nguội (cold start) trên Fly.io với scale to zero: từ 33 giây xuống 3 giây.

Nếu thông báo là “No tests found”

#

No tests found nghe có vẻ liên quan, nhưng nó không phải timeout: Playwright đã đi tìm mà không thấy gì để chạy, thường là vì tệp spec nằm ngoài testDir hoặc đối số dòng lệnh (một biểu thức chính quy so với đường dẫn tệp) không khớp với nó. npx playwright test --list liệt kê những gì nó gom được mà không chạy gì cả; nếu spec của bạn không có trong đó thì nó vốn chẳng bao giờ có cơ hội bị timeout.

Cập nhật ngày 4/11/2026: thêm một điều chỉnh nữa. Những lỗi 504 này không phải là các yêu cầu thăm dò mà máy chủ gốc không trả lời được. Chúng là các lượt tra cứu cache Early Hints của chính Cloudflare, hoàn toàn không đi tới máy chủ gốc, và mã 504 ở đó chỉ có nghĩa là chưa có gì được cache cho URL ấy. Tắt Early Hints cũng không phải cách sửa tốt nhất: khi gửi response header Link, tính năng bắt đầu hoạt động và các lần miss chuyển thành hit. Toàn bộ câu chuyện có trong bài Lỗi 504 Cloudflare không phải sự cố thật: Early Hints và HTTP 103.

Nói ngắn gọn: khi bật auto_stop_machines để thu về 0 (scale to zero), yêu cầu nào rơi vào một máy Fly.io đang dừng đều phải chờ máy khởi động xong. Máy của tôi mất 25 đến 33 giây cho mỗi lần khởi động nguội (cold start), vì mỗi lần máy bật lên, entrypoint lại chạy migration của Django và collectstatic, còn bytecode thì chưa từng được lưu đệm. Khi chỉ chạy những việc đó một lần cho mỗi image (bằng một khóa Redis đặt theo FLY_IMAGE_REF) và thêm compileall vào bước build, khởi động nguội giảm còn khoảng 9 giây. Đổi auto_stop_machines từ 'stop' sang 'suspend' (muốn vậy phải bỏ swap, vì Fly không cho tạm ngưng máy có swap) thì đánh thức máy chỉ còn khoảng 3 giây.

Tôi mở bảng điều khiển (dashboard) của Cloudflare để tìm hiểu một đợt lưu lượng truy cập (traffic) tăng đột biến, và phát hiện bên dưới nó là một chuyện tệ hơn nhiều: trong một ngày, 22% tổng số yêu cầu (request) gửi tới ứng dụng của tôi đã bị lỗi. Không có cảnh báo nào bắn ra. Lượt kiểm tra tình trạng (health check) nào cũng báo xanh. Nhật ký (log) trông hoàn toàn bình thường, vì những yêu cầu bị lỗi chưa bao giờ tới được ứng dụng.

Hóa ra thủ phạm lại là chính script khởi động container của tôi: nó làm những việc hoàn toàn hợp lý, chỉ có điều là vào đúng thời điểm tệ nhất.

Đợt lưu lượng tăng vọt chỉ là cú đánh lạc hướng

#

Ban đầu tôi chỉ định tìm hiểu một khung giờ nhận khoảng 4,900 yêu cầu, trong khi trung vị chỉ là 121. Có bốn mươi hai khách truy cập khác nhau, tức là 110 yêu cầu cho mỗi khách. Người thật thì không lướt web kiểu đó.

Đó là một công cụ quét (scanner): một con bot duy nhất lần lượt dò qua các tên miền phụ (subdomain) do nó tự bịa ra, và hỏi từng cái xem có để lộ thông tin bí mật (secrets) nào không:

api-stage-asia.example.com/.env.local
api-us-east-1-demo.example.com/.env
api-eu-uat.example.com/wp-config.php~
app-test-us-east-1.example.com/actuator/configprops
prod-api-use2.example.com/.env.local
relay.example.com/.env.production

Khoảng ba mươi tên máy chủ (hostname), đủ mọi biến thể .env bạn nghĩ ra được, thêm cả các endpoint actuator của một framework Java trên một ứng dụng Django. Tất cả đều nhận mã 301 chuyển hướng về tên miền chính, và không có gì bị lộ ra ngoài. Nhàm chán, và thật sự vô hại.

Nhưng nhân tiện đang mở trang phân tích (analytics), tôi thử nhóm số liệu của cùng ngày đó theo mã trạng thái (status code). Vấn đề thật nằm ở đây.

Hai mươi hai phần trăm. Và số lỗi này không rải đều khắp trang, mà dồn vào đúng những chỗ đau nhất:

Đây đều là những endpoint mà ứng dụng di động của tôi gọi định kỳ (poll) mỗi 30 giây. Nên đây không phải một con số tỉ lệ lỗi trừu tượng. Đó là điện thoại của từng người dùng, âm thầm không tải được số tin chưa đọc hiện trên biểu tượng, suốt cả ngày, và nhiều khả năng là đã như vậy mấy tuần liền.

Vì sao log vẫn trông bình thường

#

Phản xạ đầu tiên của tôi là ứng dụng đã bị chậm đi. Nhưng không phải. Tôi lấy từ kho nhật ký ra các dòng nhật ký yêu cầu của chính ứng dụng trong một khung giờ tệ nhất:

[2026-09-08 01:00:29] "GET /api/notifications/unread/" 304 61.615
[2026-09-08 01:00:29] "GET /api/notifications/"        304 63.568
[2026-09-08 01:00:59] "GET /api/notifications/unread/" 304 58.742
[2026-09-08 01:00:59] "GET /api/notifications/"        304 105.438

Từ bốn mươi bốn đến một trăm mili giây, toàn bộ đều là 304. Máy chủ gốc (origin) chạy rất nhanh.

Đó là manh mối quan trọng, và đáng để đúc kết thành một quy tắc: nếu tầng biên (edge) báo lỗi mà máy chủ gốc chưa từng nghe thấy, thì yêu cầu đã chết trước khi tới nơi. Lúc đó, hãy thôi đọc nhật ký ứng dụng và bắt đầu nhìn vào những gì đứng trước nó.

Trong trường hợp của tôi, thứ đứng trước là proxy của Fly.io, và câu trả lời nằm ở cách các máy (machine) của tôi được lên lịch chạy.

Thu về 0 (scale to zero) là lời hứa về tiền, không phải về độ trễ

#

Cấu hình của tôi trông như thế này, và thoạt nhìn thì khá hợp lý:

[http_service]
  auto_stop_machines = 'stop'
  auto_start_machines = true
  min_machines_running = 1

Máy nào rảnh thì tự dừng. Có lưu lượng thì tự bật lại. Dùng bao nhiêu trả bấy nhiêu. Với một ứng dụng nhỏ có lưu lượng lúc lên lúc xuống thất thường, đây đúng là thứ bạn cần, và đó cũng là lý do tôi khai báo mười máy nhưng gần như lúc nào cũng chỉ có một cái đang chạy.

Cái giá bị giấu đi ở đây là độ trễ (latency). Khi một yêu cầu tới một máy đang dừng, sẽ có người phải ngồi chờ máy đó khởi động. Nếu thời gian khởi động lâu hơn sức chờ của proxy, người đó sẽ nhận về lỗi 504.

Vậy máy của tôi mất bao lâu để khởi động? Tôi chưa từng đo. Nhưng kho nhật ký thì biết, vì script khởi động có in ra từng giai đoạn, và dòng nhật ký nào cũng kèm ID của máy:

WITH s AS (
  SELECT instance, timestamp,
         CASE WHEN message ILIKE '%Starting app server%' THEN 'begin'
              WHEN message ILIKE '%Migrations complete%' THEN 'migrated'
              WHEN message LIKE  '%"GET /healthz%'       THEN 'serving' END AS phase
  FROM logs
  WHERE app = 'myapp' AND timestamp::date = '2026-09-08'
)
SELECT instance,
       min(timestamp) FILTER (WHERE phase = 'begin')    AS started,
       min(timestamp) FILTER (WHERE phase = 'migrated') AS migrated,
       min(timestamp) FILTER (WHERE phase = 'serving')  AS first_serve
FROM s GROUP BY instance

Kết quả rất nhất quán trên mọi máy:

Sau đó tôi đếm xem chuyện này xảy ra bao nhiêu lần:

SELECT count(*) AS starts, count(DISTINCT instance) AS machines
FROM logs
WHERE app = 'myapp' AND timestamp::date = '2026-09-08'
  AND message ILIKE '%Starting app server%'
-- starts: 92, machines: 10

Chín mươi hai lần khởi động nguội (cold start) chỉ trong một ngày. Mỗi lần là một khoảng nửa phút, trong đó yêu cầu nào được định tuyến tới máy đó cũng đều hết thời gian chờ (timeout). Đến đây thì con số hai mươi hai phần trăm hết còn bí ẩn.

Thủ phạm nằm ngay trong script khởi chạy (entrypoint) của tôi

#

Đây là những gì mọi máy đều phải chạy trước khi chịu trả lời yêu cầu:

# entrypoint.sh, run on every machine start
echo "Running migrations..."
python manage.py migrate --noinput

echo "Running collectstatic in background..."
python manage.py collectstatic --noinput &

exec "$@"    # then start the app server

Hãy đọc lại đoạn này, lần này nhớ trong đầu con số “92 lần mỗi ngày”.

migrate là một lần khởi động Django trọn vẹn: nạp mọi mô hình, kết nối tới Postgres, truy vấn bảng migrations, rồi kết luận là chẳng có gì phải làm. Trên CPU dùng chung (shared CPU), mất mười giây chỉ để không làm gì cả. collectstatic là lần khởi động Django trọn vẹn thứ hai, sau đó còn tải các tệp tĩnh (static file) lên kho lưu trữ đối tượng (object storage), tranh giành đúng một nhân CPU duy nhất mà máy chủ web đang cố khởi động trên đó. Máy chủ ứng dụng (app server) là lần khởi động thứ ba.

Ba trình thông dịch Python, hai trong số đó làm lại những việc đã xong từ trước, và chuyện này lặp lại mỗi khi một máy thức dậy.

Tôi viết như vậy là có lý do chính đáng, và có lẽ script khởi chạy của bạn trông na ná cũng vì lý do đó: chuyển đổi lược đồ thì phải chạy ở đâu đó, release_command của Fly từng bị treo với tôi, và script khởi chạy là nơi duy nhất chắc chắn được chạy mỗi lần triển khai. Đặt việc của khâu triển khai vào đó là đúng. Có điều, đó không phải chỗ đúng để chạy việc đó mỗi lần máy khởi động, và một khi máy tự dừng rồi tự bật lại, hai sự kiện này không còn là một nữa.

Toàn bộ lỗi chỉ có vậy, và tôi nghĩ nó khá phổ biến:

Những việc thuộc về một lần phát hành lại bị chạy lại mỗi lần máy khởi động. Cơ chế thu về 0 biến một sự kiện thành chín mươi hai sự kiện.

Cách sửa: mỗi bản phát hành chỉ chuẩn bị đúng một lần

#

Bước chuyển đổi lược đồ không cần chạy lại trên chiếc máy thứ tám khởi động từ cùng một image. Nó chỉ cần chạy một lần cho image đó, và mọi máy khác cần biết là việc này đã xong.

Nói cách khác, ta cần một khóa (lock) có tên thay đổi theo từng lần triển khai. Fly cung cấp sẵn cái tên đó trong FLY_IMAGE_REF, còn Redis thì tôi đã có sẵn. Tất cả chỉ là một script nhỏ chạy trước khi Django được nạp, nên trong trường hợp thường gặp, nó chỉ tốn vài mili giây thay vì một lần khởi động cả framework:

# release_gate.py: runs before Django exists. Exit code 0 means "prepare this release".
import os, time

PREPARE, SKIP = 0, 1
LOCK_TTL, WAIT, POLL = 300, 240, 2
_sleep, _monotonic = time.sleep, time.monotonic    # aliases, so tests can replace them


def release_id() -> str:
    """Something that changes exactly when the deployed image does."""
    return os.getenv("FLY_IMAGE_REF") or os.getenv("FLY_MACHINE_VERSION") or ""


def claim(client, release: str) -> int:
    if client is None or not release:   # no Redis, or no idea which release: behave as before
        return PREPARE
    done_key, lock_key = f"release:{release}:done", f"release:{release}:lock"
    if client.get(done_key):            # somebody already did it for this image
        return SKIP

    owner = os.getenv("FLY_MACHINE_ID", "unknown")
    if client.set(lock_key, owner, nx=True, ex=LOCK_TTL):
        return PREPARE                  # we won the race; we do the work

    # Someone else is preparing. Wait for them, because serving requests
    # against a half-migrated schema is worse than starting slowly.
    deadline = _monotonic() + WAIT
    while _monotonic() < deadline:
        _sleep(POLL)
        if client.get(done_key):
            return SKIP
        if client.set(lock_key, owner, nx=True, ex=LOCK_TTL):
            return PREPARE              # the owner died and its lock expired; take over
    return PREPARE                      # waited long enough; do it ourselves

# ... plus `done` (sets done_key) and a main() that treats any Redis error as PREPARE

Script khởi chạy giờ chỉ còn một câu if:

if python3 release_gate.py claim; then
    python manage.py migrate --noinput
    python manage.py collectstatic --noinput &
    python3 release_gate.py done
fi

exec "$@"

Mọi nhánh lỗi đều phải dẫn tới “cứ chuẩn bị đi”

#

Phần đáng học theo nằm ở đây, hơn là ở đoạn mã.

Một cổng kiểm soát (gate) như thế này đứng giữa người dùng và một lần chuyển đổi lược đồ. Nếu nó sai theo hướng bỏ qua, bạn sẽ phục vụ yêu cầu trên một cơ sở dữ liệu chưa được chuyển đổi, và đó là một sự cố thật sự nghiêm trọng. Còn nếu nó sai theo hướng chuẩn bị, bạn chỉ chạy lại một bước chuyển đổi lũy đẳng (idempotent) vốn chẳng làm gì, và mất thêm mười giây.

Hai kết cục này không ngang nhau, nên mã nguồn không được xử lý chúng như nhau. Mọi nhánh không chắc chắn đều trả về PREPARE:

• Không có Redis, hoặc không kết nối được tới Redis. Chuẩn bị. Đây chính là hành vi cũ, nên nếu bộ nhớ đệm (cache) có sập thì hệ thống chỉ “chậm” chứ không “hỏng”.
• Biến môi trường không có tham chiếu tới image. Chuẩn bị. Không biết đây là bản phát hành nào thì cũng không thể biết nó đã sẵn sàng hay chưa.
• Máy đang giữ khóa chết giữa chừng lúc chạy chuyển đổi lược đồ. Khóa của nó sẽ hết hạn, và máy tiếp theo đang chờ sẽ giành lấy khóa rồi chuẩn bị.
• Chờ quá thời gian cho phép. Cứ chuẩn bị. Một máy không bao giờ phục vụ được còn tệ hơn một lần chuyển đổi lược đồ bị chạy trùng.

Có một điểm bất đối xứng tôi cố ý đặt theo chiều ngược lại: máy nào thấy một máy khác đang giữ khóa thì sẽ chờ chứ không phục vụ yêu cầu. Khởi động chậm một chút trong lúc triển khai thì không sao. Nhưng trả lời truy vấn trên một lược đồ mới áp dụng được một nửa thì có sao đấy.

Nếu bạn dựng cơ chế này trên một lớp bọc (wrapper) bộ nhớ đệm nuốt luôn lỗi kết nối, như tôi đã làm lúc đầu, hãy cẩn thận với một cái bẫy. Khi không kết nối được Redis, lớp bọc kiểu đó trả về False từ add(), trông y hệt kết quả “đã có máy khác giữ khóa”, và nếu không để ý thì đã khiến mọi máy bỏ qua bước chuyển đổi lược đồ. Đó chính xác là hướng nguy hiểm. Hãy phân biệt hai trường hợp bằng cách đọc lại khóa: nếu không ai giữ khóa, nghĩa là bộ nhớ đệm đang hỏng, chứ không phải bạn thua cuộc đua.

Kiểm thử mà không cần Redis

#

Logic này đáng để viết kiểm thử đơn vị (unit test), vì những nhánh đáng chú ý nhất lại chính là những nhánh bạn không thể tái hiện bằng tay. Chỉ cần một bản giả lập (fake) có hai phương thức là đủ:

class FakeRedis:
    """Enough of a Redis client for the gate: get, and set with nx/ex."""

    def __init__(self) -> None:
        self.store: dict[str, str] = {}

    def get(self, key): return self.store.get(key)

    def set(self, key, value, nx=False, ex=None):
        if nx and key in self.store:
            return None
        self.store[key] = value
        return True

Sau đó, dựng các trường hợp khó bằng cách tự điều khiển thời gian trôi. Đây chính là lý do cổng kiểm soát gọi các bí danh _sleep và _monotonic ở cấp mô-đun chứ không gọi thẳng time.sleep, nên bài kiểm thử có thể thay thế chúng mà không phải vá (patch) mô-đun time cho mọi luồng (thread) khác trong tiến trình:

def test_a_waiter_takes_over_when_the_owner_disappears(self):
    redis = FakeRedis()
    self.assertEqual(release_gate.claim(redis, "img-1"), release_gate.PREPARE)   # the owner takes the lock

    def owner_dies(_seconds):
        redis.store.pop("release:img-1:lock", None)                              # its lock expired

    with patch.object(release_gate, "_sleep", owner_dies):
        self.assertEqual(release_gate.claim(redis, "img-1"), release_gate.PREPARE)

Có hiệu quả không? Được một phần

#

Triển khai, dừng một máy, bật lại, rồi canh đồng hồ. Giờ đây lúc khởi động, script báo ra quyết định của nó rồi nhường đường luôn:

15:23:34  Starting app server...
15:23:36  release gate: this release is already prepared, starting straight away
15:23:44  "GET /healthz HTTP/1.1" 200

Mười giây, và một máy thứ hai đo được mười một giây. So với 25 đến 33 giây trước đó, hai phần ba khoảng thời gian chết đã biến mất, và bản thân cổng kiểm soát chỉ tốn hai giây vì nó không bao giờ nạp Django.

Nhưng mười giây vẫn là mười giây. Yêu cầu nào tới trong những giây đầu tiên đó vẫn bị lỗi. Nên tôi đi tìm tiếp phần còn lại.

Bytecode chẳng ai lưu đệm

#

Image có một dòng mà gần như Dockerfile Python nào cũng có:

ENV PYTHONDONTWRITEBYTECODE=1

Đây là lời khuyên đúng. Container không nên tự ghi các tệp .pyc vào lớp (layer) của image lúc đang chạy. Nhưng tôi chưa bao giờ nghĩ kỹ về nửa còn lại của vấn đề: nếu lúc chạy không ghi bytecode, lúc dựng image cũng không ghi, thì chẳng có gì được lưu đệm cả, và mỗi lần tiến trình khởi động là biên dịch lại toàn bộ cây thư viện phụ thuộc từ mã nguồn.

Tôi thử đếm:

site-packages .py  files : 5,707
site-packages .pyc files : 0

Django, framework REST, mọi thư viện đều bị biên dịch lại trong từng lần khởi động, 92 lần mỗi ngày. Đo trên một máy trong môi trường production:

Cách sửa chỉ có một dòng, và vì compileall luôn ghi bytecode ra tệp, nên nó vẫn hoạt động bất kể biến môi trường kia:

RUN python -m compileall -q /app/.venv/lib /app/myapp || true

Tốn thêm mười sáu giây lúc dựng image, chỉ một lần, trong một lớp đã được lưu đệm.

Nhân tiện, tôi còn phát hiện thêm một vấn đề âm thầm hơn. Tệp .dockerignore ghi:

__pycache__/
*.pyc

Docker so khớp các mẫu (pattern) này với toàn bộ đường dẫn tương đối, chứ không phải với từng thành phần của đường dẫn, nên một mẫu không có neo sẽ chỉ khớp ở thư mục gốc của ngữ cảnh dựng (build context). Kết quả là mọi thư mục __pycache__ lồng bên trong đều bị đóng gói theo. Image chứa 218 tệp .pyc do Python 3.15 biên dịch trên laptop, đi nhờ trong một image có trình thông dịch 3.14, và tất cả đều bị lặng lẽ bỏ qua. Mẫu đúng phải là **/__pycache__/ và **/*.pyc.

Nói thật thì kết quả không như kỳ vọng: tính từ đầu đến cuối, cách này chỉ bớt được khoảng một giây chứ không phải hai. Mười giây còn chín. Phép đo hiệu năng riêng lẻ (benchmark) đã phóng đại, như các phép đo riêng lẻ vẫn thường vậy.

Tạm ngưng (suspend), và dòng cấu hình đang chặn nó

#

Đến mức chín giây thì tôi hết thứ để cắt bỏ. Phần còn lại là một lần khởi động không thể tránh: Python khởi động, Django nạp các mô-đun, rồi ứng dụng WSGI chạy lên trên một nhân CPU dùng chung.

Vậy thì đừng khởi động lại từ đầu nữa. Thay vì tắt hẳn máy, Fly có thể chụp lại toàn bộ bộ nhớ (snapshot) của nó:

[http_service]
  auto_stop_machines = 'suspend'   # was 'stop'

Tôi thử bật lên thì Fly từ chối, kèm theo thông báo lỗi hữu ích nhất trong cả quá trình này:

failed to suspend VM: failed_precondition:
Machines with swap cannot be suspended

Gần đầu tệp cấu hình của tôi có đoạn này, kèm một dòng chú thích (comment) do chính tôi viết và tin sái cổ:

# Swap cushion so a memory spike swaps to disk instead of getting OOM-killed.
swap_size_mb = 2048

Một biện pháp phòng ngừa hợp lý. Nhưng nó có thực sự làm gì không? Máy nào cũng báo:

MemTotal:   985220 kB
SwapTotal: 2097148 kB
SwapFree:  2097148 kB

Chưa từng có một trang bộ nhớ nào bị đẩy ra vùng hoán đổi (swap). Nhật ký trong ngày cũng không có vụ tiến trình nào bị diệt vì hết bộ nhớ (OOM kill) — mười một dòng khớp với chữ “oom” hóa ra là yêu cầu tới một gói JavaScript mà mã băm nội dung tình cờ chứa ba chữ cái đó. Trong khi đó, cơ chế bảo vệ bộ nhớ thật sự lại nằm ở một chỗ hoàn toàn khác, ngay trong cấu hình của chính máy chủ ứng dụng: worker nào vượt quá 800MB sẽ bị khởi động lại từ lâu trước khi kịp chạm tới trần 1GB.

Nói cách khác, vùng hoán đổi dự phòng là bảo hiểm cho một sự cố chưa từng xảy ra, vốn đã có cơ chế khác lo, và phí bảo hiểm phải trả là mất khả năng tạm ngưng. Tôi bỏ nó đi.

Ba lần thử, các kết quả chênh nhau không quá nửa giây. Ngay sau khi thức dậy, endpoint nào cũng trả về 200 trong 250 đến 435 mili giây.

Socket sẽ ra sao khi máy đang ngủ

#

Chẳng có gì tốt đẹp cả, mà cũng không có hook nào để can thiệp. Fly đóng băng máy ảo (VM); tiến trình không nhận được tín hiệu (signal) nào và không kịp đóng thứ gì trước khi ngủ. Những kết nối nó đang giữ vẫn nằm nguyên trong bộ nhớ lúc thức dậy, trỏ tới những socket mà đầu bên kia đã bỏ đi từ mấy phút trước.

Bạn không xử lý chuyện này lúc máy đi ngủ, mà lúc nó thức dậy, và phần lớn là nhờ những quyết định đúng đã có từ trước:

• Kết nối cơ sở dữ liệu được mở theo từng yêu cầu (conn_max_age = 0), nên không có kết nối sống lâu nào để bị cũ.
• Bộ nhớ đệm Redis chỉ xuống cấp chứ không ném ngoại lệ (exception). Một lớp bọc bắt lỗi kết nối và coi như không trúng bộ nhớ đệm (cache miss).

Tôi đã được tận mắt thấy cái thứ hai phát huy tác dụng. Một lần đánh thức ghi ra đúng cái lỗi bạn đoán được:

redis.exceptions.ConnectionError: Error while reading from fly-...

và yêu cầu gặp lỗi đó vẫn trả về 200 sau 3.6 giây, vì bộ nhớ đệm chết thì chỉ khiến trang chậm đi chứ không thành trang lỗi. Những lần đánh thức sau đó thì nhật ký sạch trơn.

Nếu thư viện kết nối bộ nhớ đệm của bạn ném ngoại lệ khi gặp kết nối chết, chế độ tạm ngưng sẽ biến mỗi lần thức dậy thành một tràng lỗi 500. Hãy kiểm tra chuyện đó trước khi bật cấu hình này, đừng đợi đến sau.

Lần kiểm thử đã đánh lừa tôi

#

Lần đo chế độ tạm ngưng đầu tiên cho thấy tính năng này là một thảm họa: 502 sau 30 giây, hai lần liên tiếp.

Lúc đó tôi đã ghim yêu cầu vào một máy cụ thể bằng header fly-force-instance-id. Header này rất tiện khi kiểm thử tải (load test) một máy, nhưng lại cực kỳ tệ cho trường hợp này. Ép vào một máy cụ thể sẽ bỏ qua phần logic của proxy vốn có nhiệm vụ đánh thức máy. Thật ra Fly đã nói rõ điều đó, nếu tôi chịu đọc nó như một câu trả lời thay vì một thông báo lỗi:

machine was recently stopped and is unavailable to service request

Con số đáng quan tâm phải đến từ đường đi mà lưu lượng thật đi qua. Tôi bắn bốn mươi yêu cầu đồng thời qua tầng biên, vượt xa giới hạn mềm (soft limit) là 12, để proxy buộc phải mở rộng theo chiều ngang (scale out) sang các máy đang tạm ngưng:

status codes:  40 × 200
slowest:       2.1s

Có hai bài học, và bài thứ hai là bài đắt giá hơn. Hãy đo trên đường đi mà người dùng thật sự đi, chứ không phải đường đi tiện cho việc gắn công cụ đo. Và khi công cụ từ chối làm gì đó, hãy đọc kỹ lời từ chối: chính câu “Machines with swap cannot be suspended” đã gỡ nút thắt cho cả buổi chiều hôm đó.

Nếu là ứng dụng của bạn, tôi sẽ kiểm tra những gì

#

Nếu bạn đang chạy bất cứ thứ gì trên một nền tảng tự dừng máy khi rảnh, thì những câu hỏi dưới đây chỉ tốn của tôi một buổi chiều, nhưng lẽ ra đã giúp tôi tránh được mấy tuần lỗi âm thầm:

1. Một lần khởi động nguội mất bao lâu? Không phải container mất bao lâu để chạy, mà là mất bao lâu đến khi nó trả lời được một yêu cầu thật. Nếu bạn không trả lời được câu này bằng một con số tính theo giây, hãy đo ngay, trước khi thật sự cần tới nó.
2. Script khởi chạy của bạn đang làm những việc gì mỗi lần khởi động mà lẽ ra thuộc về khâu triển khai? Chuyển đổi lược đồ, gom tệp tĩnh, làm nóng bộ nhớ đệm, dựng chỉ mục. Làm một lần thì không sao. Làm chín mươi hai lần thì rất tốn kém.
3. Có thứ gì đang lưu đệm bytecode cho bạn không? Nếu có PYTHONDONTWRITEBYTECODE mà lúc dựng image không chạy compileall, thì câu trả lời là không.
4. Bạn có thể cho máy tạm ngưng thay vì tắt hẳn không? Nếu không, thì cái gì đang cản bạn? Với tôi, đó là một tệp hoán đổi chưa từng được dùng tới.
5. Tầng biên có thấy những lỗi mà máy chủ gốc không thấy không? Hãy so sánh hai bên. Khoảng chênh giữa chúng không phải do báo cáo bị lệch, mà là yêu cầu đang chết ở khoảng giữa, và nhật ký ứng dụng sẽ không bao giờ cho bạn thấy điều đó.

À, nhân tiện, các lượt kiểm tra tình trạng vẫn xanh suốt từ đầu đến cuối. Lúc nào chúng cũng xanh cả: kiểm tra tình trạng chỉ chạy trên một máy đã khởi động xong, nên không thể báo cáo gì về ba mươi giây trước khi máy đó tồn tại.

Thời gian tôi dành cho việc gỡ lỗi nhiều đến mức khó tin. Mà lập trình viên nào chẳng thế. Dạo này phần lớn thời gian đó tôi ngồi trong Xcode và trình giả lập (Simulator), lần theo lỗi trong chính ứng dụng của mình, và có một điều tôi cứ thấy lạ mãi: Xcode đi kèm cả một kho công cụ gỡ lỗi, vậy mà gần như chẳng ai đụng tới. Dưới đây là quy trình tôi đúc kết qua nhiều năm, chỉ gồm những phần thực sự giúp tiết kiệm thời gian mỗi khi có gì đó hỏng.

Điểm dừng làm được nhiều hơn bạn nghĩ

#

Đa số chúng ta chỉ nhấp vào lề trái để đặt điểm dừng (breakpoint) rồi thôi. Nhưng thử nhấp chuột phải vào một điểm dừng xem, bạn sẽ thấy cả một menu tùy chọn, và nó thay đổi hẳn cách bạn gỡ lỗi.

Điểm dừng có điều kiện (Conditional Breakpoint)

#

Giả sử bạn có một vòng lặp xử lý 1000 phần tử, và chỉ riêng phần tử thứ 347 là trục trặc. Nếu phải dừng ở điểm dừng 346 lần trước khi tới được nó thì coi như mất toi một buổi chiều.

for i in 0..<users.count {
    processUser(users[i])  // Set breakpoint here with condition: i == 347
}

Nhấp chuột phải vào điểm dừng, thêm điều kiện i == 347, thế là Xcode chỉ dừng khi điều kiện đó đúng. Mấy điều kiện kiểu userId == "abc123" hay error != nil cũng dùng tốt y như vậy.

Điểm dừng theo ký hiệu (Symbolic Breakpoint)

#

Loại này dùng khi bạn không biết một phương thức đang được gọi từ đâu. Mở Breakpoint Navigator (Cmd+8), bấm nút +, rồi chọn “Symbolic Breakpoint”.

Muốn biết mỗi lần có view controller nào được nạp? Đặt ký hiệu là viewDidLoad, Xcode sẽ dừng lại ở từng cái một. Thấy nhiều quá? Thì thu hẹp lại: MyViewController.viewDidLoad.

Có mấy cái tôi để cố định trong mọi dự án:

• UIViewAlertForUnsatisfiableConstraints bắt các xung đột Auto Layout ngay khi chúng xảy ra
• objc_exception_throw dừng ở mọi ngoại lệ (exception) Objective-C, trước khi ứng dụng kịp bị sập (crash)
• malloc_error_break giúp tìm ra các lỗi cấp phát bộ nhớ

Điểm dừng ngoại lệ (Exception Breakpoint)

#

Đây nên là thứ đầu tiên bạn thiết lập khi tạo dự án mới. Thêm một cái (Breakpoint Navigator, + → Exception Breakpoint) là Xcode sẽ dừng ngay lúc có ngoại lệ được ném ra, chứ không phải đợi đến khi ứng dụng đã chết hẳn.

Nhờ nó mà tôi bắt được không biết bao nhiêu lỗi mở gói (unwrap) giá trị nil, nhiều hơn mức tôi muốn thừa nhận. Không có nó thì mấy lỗi này chỉ hiện ra dưới dạng những vụ sập khó hiểu trong console.

Hành động của điểm dừng (Breakpoint Action)

#

Điểm dừng không nhất thiết phải dừng chương trình. Sửa một điểm dừng, bấm “Add Action”, và bạn có thể cho nó:

• In giá trị biến ra mà không dừng: "User count: @(users.count)@"
• Tự động chạy lệnh LLDB
• Chạy shell script
• Phát âm thanh (tôi hay dùng cho những nhánh mã hiếm khi chạy tới, để biết ngay khi nó xảy ra)

Đánh dấu thêm “Automatically continue after evaluating actions” là điểm dừng biến thành một công cụ ghi nhật ký (log), không bao giờ làm gián đoạn bạn.

LLDB: những lệnh console bạn sẽ dùng thật

#

Khi chương trình dừng ở điểm dừng, cái console ở dưới cùng không chỉ để đọc nhật ký sự cố (crash log). Đó chính là LLDB, và nó hữu ích hơn bạn tưởng nhiều.

Cơ bản

#

(lldb) po user
▿ User
  - id: "123"
  - name: "John Doe"
  - email: "john@example.com"

po in đối tượng (object) ra ở dạng dễ đọc. Riêng lệnh này đã chiếm tới 90% số lần tôi dùng LLDB.

Cần chi tiết hơn thì dùng p:

(lldb) p user.name
(String) $R0 = "John Doe"

Còn muốn xem toàn bộ biến cục bộ cùng lúc:

(lldb) frame variable

Thay đổi giá trị khi chương trình đang chạy

#

LLDB thực sự đáng đồng tiền ở chỗ này: bạn sửa được giá trị biến mà không cần biên dịch lại.

(lldb) expr user.name = "Jane Doe"
(lldb) expr index = 0

Tìm ra lỗi rồi và muốn thử cách sửa mà không phải biên dịch lại? Cứ đổi giá trị biến rồi cho chương trình chạy tiếp. Tôi dùng cách này liên tục mỗi khi cần khoanh vùng các trường hợp biên (edge case).

Gọi phương thức cũng được luôn:

(lldb) po self.refreshUI()
(lldb) expr navigationController?.popViewController(animated: true)

Di chuyển trong chương trình

#

(lldb) bt              # Show the call stack
(lldb) frame select 3  # Jump to a different stack frame
(lldb) continue        # Keep running (or just 'c')
(lldb) n               # Step over (next line)
(lldb) s               # Step into function

Điểm theo dõi (Watchpoint)

#

Muốn biết khi nào một biến bị thay đổi? Đặt điểm theo dõi:

(lldb) watchpoint set variable user.isLoggedIn

Từ giờ, cứ mỗi lần giá trị đó thay đổi là chương trình dừng lại, bất kể dòng mã nào gây ra. Khi phải truy lùng những lần trạng thái bị thay đổi ngoài ý muốn thì công cụ này quý như vàng.

Console.app: công cụ gỡ lỗi ít người để ý

#

Console của Xcode dùng tạm thì ổn, cho đến khi bạn cần xem mọi thứ: nhật ký hệ thống, báo cáo sự cố (crash report), đủ cả. Những lúc đó tôi mở Console.app.

Nếu bạn đang dùng OSLog (và bạn nên dùng), Console.app cho phép tìm kiếm và lọc các nhật ký đó:

import os.log

let logger = Logger(subsystem: "com.example.app", category: "networking")

logger.info("Starting API request")
logger.debug("Request URL: \(url.absoluteString)")
logger.error("Failed to decode: \(error.localizedDescription)")

Sau đó, trong Console.app:

1. Chọn trình giả lập hoặc thiết bị đang kết nối
2. Lọc theo phân hệ (subsystem) của bạn: subsystem:com.example.app
3. Lọc theo mức độ: subsystem:com.example.app AND level:error

Với những kiểu gỡ lỗi hay làm, bạn có thể lưu sẵn biểu thức lọc (predicate). Tôi có một cái cho yêu cầu mạng, một cái cho các thao tác với cơ sở dữ liệu, và một cái chỉ hiện lỗi với cảnh báo.

Sao lại dùng OSLog thay vì print()?

#

So với việc rải print() khắp nơi thì OSLog hơn hẳn. Nhật ký có cấu trúc nên lọc được theo mức độ và danh mục. Nó đủ nhanh để việc ghi nhật ký không làm ứng dụng chậm đi. Trên môi trường production, dữ liệu nhạy cảm được tự động ẩn đi, và nhật ký vẫn còn nguyên kể cả khi ứng dụng bị sập.

print() vẫn ổn cho mấy lần kiểm tra nhanh rồi xóa. Còn thứ gì sau này bạn có thể cần xem lại thì nên ghi bằng OSLog.

Lọc nâng cao trong Console.app

#

Console.app hỗ trợ đầy đủ truy vấn bằng biểu thức lọc. Đây là mấy câu tôi dùng thường xuyên:

# All errors and faults in your app
subsystem:com.example.app AND (level:error OR level:fault)

# Network requests that failed
subsystem:com.example.app AND category:networking AND eventMessage CONTAINS "failed"

# Everything from the last 5 minutes
subsystem:com.example.app AND timestamp >= now(-5m)

Bạn cũng có thể xuất nhật ký ra để đính kèm vào báo cáo lỗi, tiện hơn nhiều so với sao chép thủ công từ console của Xcode.

Gỡ lỗi giao diện với View Debugger

#

Khi giao diện bị vỡ mà bạn không hiểu tại sao, View Debugger là cách nhanh nhất để tìm ra nguyên nhân.

Chạy ứng dụng, mở tới màn hình bị lỗi, rồi bấm nút “Debug View Hierarchy” trên thanh gỡ lỗi của Xcode (hoặc nhấn Cmd+Shift+D). Xcode sẽ hiện toàn bộ cây phân cấp view (view hierarchy) dưới dạng 3D, tách ra từng lớp.

Xoay qua xoay lại một chút là vấn đề lộ ra ngay:

• View bị vẽ nằm phía sau view khác
• View nằm tít ngoài màn hình
• View có kích thước bằng 0
• Toàn bộ chuỗi ràng buộc (constraint) của view bạn đang chọn

Tôi từng nhờ nó mà tìm ra những cái nút vô hình nuốt mất sự kiện chạm, những nhãn bị vẽ ở kích thước 0x0, và có lần là một tấm ảnh lỡ tay rộng tới 10,000 pixel.

Gỡ lỗi Auto Layout

#

Trong cây phân cấp view, biểu tượng cảnh báo màu tím nghĩa là đang có xung đột ràng buộc. Nhấp vào đó, Xcode sẽ chỉ rõ những ràng buộc nào đang “đánh nhau”.

Hãy đặt định danh (identifier) cho ràng buộc:

heightConstraint.identifier = "ProfileImageHeight"

Khi ràng buộc bị vỡ, thông báo lỗi sẽ hiện "ProfileImageHeight" thay vì một địa chỉ bộ nhớ, và lúc đó nhật ký mới thực sự đọc được.

Bạn cũng có thể in cây ràng buộc ra từ LLDB:

(lldb) po view.hasAmbiguousLayout
(lldb) po view._autolayoutTrace()

Những tính năng của trình giả lập giúp tiết kiệm thời gian

#

Làm chậm hoạt ảnh (Slow Animations)

#

Debug → Slow Animations làm mọi thứ chạy chậm lại còn 1/10. Rất hợp để xem trong một hiệu ứng chuyển cảnh thực sự đang xảy ra chuyện gì, hoặc tìm hiểu vì sao một hoạt ảnh trông sai sai.

Giả lập cảnh báo bộ nhớ

#

Debug → Simulate Memory Warning giúp bạn kiểm tra xem ứng dụng xoay xở ra sao khi thiếu bộ nhớ. Tôi đã tìm ra khá nhiều lỗi liên quan đến bộ nhớ đệm (cache) ảnh theo cách này: mọi thứ vẫn chạy ổn, cho tới khi cảnh báo được phát ra, và tự dưng toàn bộ ảnh biến mất sạch.

Network Link Conditioner

#

Xcode → Open Developer Tools → Network Link Conditioner

Công cụ này giả lập mạng 3G, LTE, mạng mất gói nhiều, hoặc mất kết nối hoàn toàn. Nếu bạn từng gặp một yêu cầu API chạy ngon lành trên WiFi nhưng lại hết thời gian chờ (timeout) khi dùng 4G, thì đây là cách để tái hiện lỗi đó.

Tôi luôn để sẵn một cấu hình tên “Bad Network”, với độ trễ 500ms và tỉ lệ mất gói 10%. Nhờ nó mà lộ ra những lỗi hết thời gian chờ và lỗi ở trạng thái đang tải, loại lỗi bạn sẽ không bao giờ thấy khi ngồi dùng WiFi tốc độ cao ở văn phòng.

Ghi đè thanh trạng thái

#

Nhấp chuột phải vào thanh trạng thái (status bar) trong trình giả lập là bạn ghi đè được giờ, mức pin, cường độ sóng và tên nhà mạng. Rất tiện khi cần chụp ảnh màn hình đồng nhất, hoặc muốn kiểm tra giao diện trông thế nào ở các mức pin khác nhau.

Giả lập vị trí

#

Debug → Location cho phép giả lập các vị trí khác nhau mà không cần rời khỏi bàn làm việc: tọa độ tùy chọn, đi bộ trong thành phố, hay lái xe trên cao tốc. Rất hữu ích khi làm các tính năng dựa trên vị trí, hoặc khi gặp những lỗi chỉ xuất hiện ở một số khu vực nhất định.

Gỡ lỗi bộ nhớ

#

Debug Memory Graph

#

Bấm nút Debug Memory Graph (Cmd+Shift+M), Xcode sẽ hiện ra mọi đối tượng đang nằm trong bộ nhớ, quan hệ giữa chúng, và phần bạn thực sự quan tâm: đối tượng nào đang bị rò rỉ bộ nhớ (memory leak).

Dấu chấm than màu tím nghĩa là có rò rỉ. Nhấp vào là bạn thấy ngay vòng tham chiếu (retain cycle).

Đây là kiểu rò rỉ tôi gặp nhiều nhất:

class ViewController: UIViewController {
    var onComplete: (() -> Void)?

    func setupHandler() {
        onComplete = {
            self.dismiss(animated: true)  // ❌ Captures self strongly
        }
    }
}

Cách sửa là dùng weak self:

onComplete = { [weak self] in
    self?.dismiss(animated: true)  // ✓ No retain cycle
}

Delegate cũng phải khai báo weak:

weak var delegate: ManagerDelegate?  // Not just 'var'

Instruments

#

Khi cần điều tra bộ nhớ nghiêm túc, hãy dùng Instruments (Product → Profile, hoặc Cmd+I).

Công cụ Allocations trong Instruments cho bạn thấy từng lần cấp phát đối tượng, bộ nhớ tăng lên theo thời gian ra sao, lớp nào đang ngốn nhiều bộ nhớ nhất, kèm stack trace cho biết mỗi lần cấp phát xảy ra ở đâu.

Tôi thường tìm ba thứ: bộ nhớ tăng đều theo thời gian (nhiều khả năng là rò rỉ), những lần cấp phát lớn bất thường (mình vừa nạp cả 1000 tấm ảnh một lúc à?), và những đối tượng lẽ ra đã phải được giải phóng nhưng vẫn còn đó.

Bấm đánh dấu generation (nút hình lá cờ nhỏ) trước và sau một thao tác để xem thứ gì vẫn còn nằm lại trong bộ nhớ khi đáng lẽ phải được giải phóng.

Đo hiệu năng

#

Time Profiler

#

Product → Profile → Time Profiler. Bấm ghi, thực hiện đúng thao tác đang chậm trong ứng dụng, rồi đọc cây lời gọi hàm (call tree).

Sắp xếp theo “Self Weight” để tìm điểm nghẽn (bottleneck). Hàm nào có self weight tới 40% thì đó chính là chỗ thời gian của bạn đang bị ngốn.

Có lần tôi phát hiện một hàm phân tích JSON bị gọi tới 1000 lần mỗi giây. Chuyển nó sang hàng đợi chạy nền (background queue) xong là giao diện hết giật ngay.

Main Thread Checker

#

Xcode tự động phát hiện những chỗ cập nhật giao diện từ luồng nền (background thread). Nếu bạn thấy dòng này:

Main Thread Checker: UI API called on a background thread: -[UILabel setText:]

thì nghĩa là bạn đã viết kiểu như thế này:

URLSession.shared.dataTask(with: url) { data, response, error in
    self.label.text = "Loaded"  // ❌ Crash!
}

Sửa lại như sau:

URLSession.shared.dataTask(with: url) { data, response, error in
    DispatchQueue.main.async {
        self.label.text = "Loaded"  // ✓
    }
}

Chẩn đoán khi chạy (Runtime Diagnostics)

#

Vào Edit Scheme → Run → Diagnostics. Ở đây có một loạt ô đánh dấu, mỗi ô bắt được những lỗi mà tự tay bạn sẽ không bao giờ tìm ra.

Address Sanitizer

#

Công cụ này tìm lỗi hỏng bộ nhớ: use-after-free, tràn bộ đệm (buffer overflow), rò rỉ bộ nhớ. Nó làm ứng dụng chậm đi 2-3 lần, nhưng bù lại bắt được những lỗi gần như không thể lần ra bằng cách nào khác. Tôi bật nó mỗi khi đi săn những vụ sập lúc có lúc không.

Thread Sanitizer

#

Thread Sanitizer bắt lỗi tranh chấp dữ liệu (data race) và các lỗi liên quan đến luồng (thread). Bạn chỉ cần bật lên, chạy ứng dụng và dùng như bình thường; nếu trong mã có tình trạng tranh chấp (race condition), nó sẽ tìm ra.

Không thể chạy Address Sanitizer và Thread Sanitizer cùng lúc, nên khi gặp một vụ sập có biểu hiện kỳ quặc, tôi bật luân phiên từng cái một.

Zombie Objects

#

Tùy chọn này bắt các thông điệp (message) được gửi tới đối tượng đã bị giải phóng. Khi bật lên, Xcode sẽ báo chính xác lúc nào bạn đang đụng vào vùng nhớ đã được giải phóng:

*** -[MyViewController viewDidLoad]: message sent to deallocated instance 0x600001234000

Đừng để nó bật thường trực. Zombie Objects ngăn đối tượng bị giải phóng, nên bộ nhớ cứ thế tăng mãi. Nhưng để khoanh vùng một lỗi use-after-free cụ thể thì nó rất tuyệt.

Những tình huống hay gặp

#

Ứng dụng bị sập ngay khi mở

#

Trước hết hãy thêm điểm dừng ngoại lệ; thường thì thế là bắt được luôn.

Nếu vẫn chưa ra, mấy “nghi phạm quen mặt” là: thiếu khóa (key) trong Info.plist, ép mở gói (force-unwrap) optional trong phần mã khởi tạo, hoặc cơ chế tiêm phụ thuộc (dependency injection) bị lỗi.

Giao diện không cập nhật

#

Lần. Nào. Cũng. Vậy. Nguyên nhân chỉ nằm trong mấy trường hợp sau:

1. Việc cập nhật không chạy trên luồng chính (main thread)
2. Outlet chưa được nối
3. View thực ra không hiển thị (kiểm tra bằng po view.window trong LLDB; nếu kết quả là nil thì view không nằm trong cây phân cấp)

Còn nếu là table view hay collection view: bạn quên gọi reloadData() rồi.

Ứng dụng bị sập vì cảnh báo bộ nhớ

#

Dùng Allocations trong Instruments để xem thứ gì đang giữ bộ nhớ. Thường là ảnh nằm trong bộ nhớ đệm mà không bao giờ được nhả ra, view controller không chịu giải phóng (vòng tham chiếu), hoặc một mảng hay dictionary nào đó cứ phình to mãi.

Hãy giả lập cảnh báo bộ nhớ trong trình giả lập để kiểm tra phần mã dọn dẹp của bạn.

Những vụ sập khó hiểu

#

Bật Sanitizer lên. Sập lúc có lúc không thường là do luồng, nên hãy chạy với Thread Sanitizer. Còn sập bên trong framework của hệ thống thì thường là do hỏng bộ nhớ, nên chạy với Address Sanitizer.

Những vụ sập không tái hiện được

#

Khi vụ sập xảy ra trên điện thoại của người khác, thường thì báo cáo sự cố vẫn còn lưu lại ở đâu đó. Với các bản build TestFlight và App Store, Organizer của Xcode (Window → Organizer → Crashes) thu thập báo cáo sự cố từ những người dùng đồng ý chia sẻ dữ liệu phân tích, và báo cáo đã được giải mã ký hiệu (symbolicate) sẵn nếu tệp dSYM được tải lên cùng bản build. Còn với máy của người kiểm thử, báo cáo nằm ngay trên thiết bị, trong Settings → Privacy & Security → Analytics & Improvements → Analytics Data, dưới dạng các tệp .ips có tên bắt đầu bằng tên ứng dụng, và họ có thể gửi cho bạn qua AirDrop. Hãy bắt đầu từ stack trace của luồng bị sập, rồi lần lượt đối chiếu với các tình huống ở trên.

Gỡ lỗi bản cập nhật OTA trong trình giả lập

#

Ứng dụng của tôi có phát hành bản cập nhật qua mạng (OTA), và trình giả lập là nơi dễ nhất để gỡ lỗi toàn bộ luồng cập nhật đó.

Việc đầu tiên tôi làm là theo dõi lưu lượng mạng. Mở Console.app, lọc theo phân hệ của ứng dụng, bạn sẽ thấy các yêu cầu và phản hồi của tệp manifest theo thời gian thực: tiêu đề (header) nào được gửi đi, máy chủ trả về cái gì, rõ ràng từng thứ.

Tiếp theo, tôi cố tình làm cho mạng tệ đi. Network Link Conditioner cho bạn thấy luồng cập nhật xoay xở ra sao khi kết nối chậm và mất gói. Ứng dụng có bị treo không? Có hiện biểu tượng đang tải không? Có chuyển sang phương án dự phòng êm ái không?

Quanh bước kiểm tra cập nhật, tôi ghi nhật ký mọi thứ: lúc bắt đầu kiểm tra, lúc phát hiện có bản mới, lúc bắt đầu tải xuống, và lúc gói (bundle) mới được nạp.

import os.log

let logger = Logger(subsystem: "com.example.app", category: "updates")

logger.info("Checking for updates...")
let update = try await Updates.checkForUpdateAsync()
logger.info("Update available: \(update.isAvailable)")

Cuối cùng, bạn nên kiểm tra riêng endpoint manifest. Dùng curl gọi nó với đúng những tiêu đề mà ứng dụng gửi đi:

curl -H "expo-protocol-version: 1" \
     -H "expo-platform: ios" \
     -H "expo-runtime-version: 1.0.0" \
     https://updates.example.com/manifest

Làm vậy để chắc chắn máy chủ đang trả về đúng dữ liệu, trước khi bạn lao vào đào bới phía máy khách.

Công cụ bên thứ ba

#

Charles Proxy / Proxyman

#

Hai công cụ này cho bạn xem toàn bộ lưu lượng mạng, sửa yêu cầu và phản hồi, và thử các tình huống lỗi. Gỡ lỗi API mà thiếu chúng thì rất khổ.

Proxyman có giao diện đẹp hơn Charles và dùng trên macOS thấy tự nhiên hơn. Tôi chuyển sang từ năm ngoái và chưa một lần muốn quay lại.

Reveal

#

Reveal giống View Debugger của Xcode nhưng mạnh hơn. Nó chạy được trên máy thật mà không cần kết nối với Xcode, nên rất hợp để truy lỗi bố cục ngay trên máy của người kiểm thử (tester).

Trình giả lập hay máy thật

#

Phần lớn việc gỡ lỗi tôi làm trên trình giả lập, vì nó nhanh: không cần cáp, không cần ký ứng dụng (code signing), không phải chờ cài đặt. Nhưng trình giả lập thực chất là một bản iOS chạy trên bộ xử lý của máy Mac, dùng bộ nhớ và kết nối mạng của máy Mac, nên có những lỗi chỉ tồn tại trên điện thoại thật.

Vì vậy tôi viết và gỡ lỗi phần logic trên trình giả lập, còn trước mỗi lần phát hành thì chạy ứng dụng trên chiếc iPhone cũ nhất mà tôi vẫn còn hỗ trợ. Hiệu năng, tình trạng thiếu bộ nhớ và bất cứ thứ gì đụng tới phần cứng thì chưa chạy trên máy thật là coi như chưa thực sự được kiểm thử.

Chạy ứng dụng trên máy thật

#

Cắm iPhone vào máy Mac, chọn nó làm thiết bị chạy (run destination), rồi chọn team trong mục Signing & Capabilities (nếu chỉ chạy trên điện thoại của chính bạn thì một Apple ID miễn phí là đủ). Từ iOS 16 trở đi, điện thoại còn phải bật Developer Mode trong Settings → Privacy & Security, và lần đầu bật thì máy sẽ khởi động lại. Bật xong, ngay trong Settings → Developer của điện thoại cũng có Network Link Conditioner, với đúng những cấu hình mạng kém giống như trên máy Mac.

Gỡ lỗi không dây

#

Cắm máy vào Mac qua cáp USB một lần, vào Window → Devices and Simulators, đánh dấu “Connect via network”, rồi rút cáp ra. Chỉ cần máy và Mac dùng chung mạng WiFi là máy vẫn hiện trong Xcode.

Device Console

#

Window → Devices and Simulators → Open Console. Ở đây hiện đủ mọi thứ: nhật ký hệ thống, nhật ký của ứng dụng, báo cáo sự cố. Chi tiết hơn console của Xcode rất nhiều.

Mỗi khi người kiểm thử báo “ứng dụng bị sập”, tôi luôn nhờ họ cắm máy vào để lấy nhật ký console. Rất hay gặp trường hợp có sẵn một lỗi ở cấp hệ thống nằm ngay đó, giải thích được toàn bộ câu chuyện.

Tôi thực sự làm gì khi gỡ lỗi

#

1. Thêm điểm dừng ngoại lệ nếu chưa có
2. Tái hiện lỗi
3. Đặt điểm dừng gần chỗ tôi nghi là đang sai
4. Kiểm tra giá trị bằng po trong LLDB
5. Sửa giá trị biến để thử cách sửa mà không cần biên dịch lại
6. Xem cây phân cấp view nếu lỗi liên quan đến giao diện
7. Phân tích hiệu năng (profile) bằng Instruments nếu lỗi liên quan đến hiệu năng
8. Bật Sanitizer nếu lỗi liên quan đến bộ nhớ hoặc luồng

Bí quyết là đi ngược từ triệu chứng. Sập? Điểm dừng ngoại lệ. Chậm? Time Profiler. Bộ nhớ? Instruments. Giao diện kỳ cục? View Debugger.

Những mẹo tôi ước mình biết sớm hơn

#

Hãy dùng assertion. Chúng bắt được lỗi logic trước khi lỗi đó kịp gây hậu quả thật:

assert(users.count > 0, "Users array should never be empty here")

Commit trước khi bắt đầu gỡ lỗi. Một khi đã sửa lung tung để thử các giả thuyết, bạn sẽ cần một điểm sạch sẽ để quay về.

Gỡ lỗi xong thì xóa mấy lệnh print đi, hoặc ít nhất bọc chúng trong #if DEBUG. Nhật ký gỡ lỗi cũ để lại chỉ làm cho lỗi tiếp theo khó thấy hơn.

Học LLDB cho tử tế. Nhanh hơn nhiều so với việc biên dịch lại ứng dụng hai mươi lần.

Và nhớ rằng trình giả lập không phải điện thoại thật. Lỗi chỉ xuất hiện trên máy thật thì gần như lúc nào cũng là do luồng hoặc bộ nhớ. Hoặc do hiệu năng, vì trình giả lập chạy bằng CPU của máy Mac chứ không phải chip iPhone thật.

Những công cụ tôi luôn để mở

#

• Xcode, tất nhiên rồi
• Console.app, lọc sẵn theo phân hệ của ứng dụng
• Proxyman để gỡ lỗi mạng
• Instruments, khi mọi chuyện bắt đầu nghiêm trọng

Không có công cụ nào lo được hết mọi thứ. View Debugger không tìm ra rò rỉ bộ nhớ, Instruments cũng không gỡ được xung đột Auto Layout, nên phần lớn kỹ năng nằm ở chỗ chọn đúng công cụ cho đúng triệu chứng. Cái này thì chỉ có làm nhiều mới quen: dính vòng tham chiếu đủ nhiều lần rồi, chỉ cần liếc stack trace là bạn đã “ngửi” ra nó. Gỡ lỗi chẳng bao giờ thực sự vui, nhưng ít ra nó sẽ không còn là cực hình nữa.