Quan sát API: Định nghĩa và Hướng dẫn triển khai

Khả năng quan sát API (API observability) là khả năng hiểu được tại sao API của bạn hoạt động theo cách nó đang hoạt động bằng cách kiểm tra dữ liệu đo lường (telemetry) mà nó phát ra: các chỉ số (metrics), nhật ký (logs) và dấu vết (traces). Nó không chỉ dừng lại ở việc xem một bộ bảng điều khiển cố định. Một API được đo lường tốt cho phép bạn đặt ra những câu hỏi mới về trạng thái nội bộ của nó, bao gồm cả những câu hỏi bạn chưa từng nghĩ tới, chỉ bằng cách sử dụng dữ liệu nó đã tạo ra.

nút

Khả năng quan sát API thực sự có nghĩa là gì

Thuật ngữ này xuất phát từ lý thuyết điều khiển, nơi một hệ thống có thể quan sát được nếu bạn có thể suy ra trạng thái nội bộ của nó từ các đầu ra bên ngoài của nó. Áp dụng vào phần mềm, một API có thể quan sát được khi các đầu ra của nó (dữ liệu đo lường) cung cấp cho bạn đủ thông tin để chẩn đoán bất kỳ hành vi nào mà không cần triển khai mã mới để thêm một dòng nhật ký.

Phần cuối cùng đó rất quan trọng. Với khả năng quan sát, khi một khách hàng báo cáo yêu cầu thanh toán chậm lúc 2 giờ sáng cho người dùng ở một khu vực trên một phiên bản API, bạn nên trả lời "tại sao" từ dữ liệu bạn đã thu thập. Bạn đo lường đủ sâu để điều tra các chế độ lỗi mà bạn không lường trước được. Đó là một mục tiêu khác so với việc kiểm tra thời gian hoạt động (uptime checks), vốn chỉ trả lời những câu hỏi bạn đã biết cần hỏi.

Khả năng quan sát và Giám sát

Mọi người sử dụng những từ này thay thế cho nhau, nhưng chúng mô tả những điều khác nhau.

Giám sát (Monitoring) theo dõi các tín hiệu đã biết và cảnh báo khi chúng vượt quá ngưỡng. Bạn quyết định trước những gì cần theo dõi (tỷ lệ lỗi, CPU, độ trễ p99) và những gì được coi là xấu. Giám sát trả lời câu hỏi "liệu thứ tôi dự kiến sẽ hỏng có đang hỏng không?"

Khả năng quan sát (Observability) là một thuộc tính của hệ thống: mức độ mà dữ liệu đo lường của nó cho phép bạn đặt các câu hỏi tùy ý về trạng thái nội bộ. Nó trả lời câu hỏi "tại sao điều này lại hoạt động theo cách này?" ngay cả khi "điều này" là thứ bạn chưa bao giờ xây dựng bảng điều khiển cho.

Nói một cách đơn giản, giám sát cho bạn biết rằng có gì đó không ổn. Khả năng quan sát giúp bạn tìm ra nguyên nhân. Bạn cần cả hai. Giám sát cung cấp cho bạn cảnh báo; khả năng quan sát cung cấp cho bạn con đường từ cảnh báo đến nguyên nhân gốc rễ. Nếu bạn muốn tìm hiểu sâu hơn về mặt cảnh báo, hướng dẫn giám sát API của chúng tôi đề cập chi tiết.

Đây là sự khác biệt trong một bảng.

Khía cạnh	Giám sát (Monitoring)	Khả năng quan sát (Observability)
Câu hỏi được trả lời	Một tín hiệu đã biết có vượt ngoài phạm vi không?	Tại sao hệ thống lại hoạt động theo cách này?
Được định nghĩa khi nào	Trước thời điểm (kiểm tra được xác định trước)	Tại thời điểm điều tra (truy vấn ngẫu hứng)
Tốt nhất cho	Các chế độ lỗi đã biết, vi phạm SLO	Các vấn đề mới, không mong muốn
Đầu ra	Cảnh báo, bảng điều khiển trạng thái	Dữ liệu đo lường có tính đa dạng cao, có thể truy vấn được

Ba trụ cột: Chỉ số, Nhật ký, Dấu vết

Khả năng quan sát dựa trên ba loại dữ liệu đo lường, thường được gọi là ba trụ cột. OpenTelemetry, tiêu chuẩn trung lập với nhà cung cấp, chính thức hóa chúng thành "tín hiệu" đo lường. OpenTelemetry hiện hỗ trợ dấu vết, chỉ số, nhật ký và hành trang (baggage), với các sự kiện (events) và hồ sơ (profiles) đang được phát triển. Ba trụ cột cổ điển tương ứng với ba tín hiệu đầu tiên của nó.

Chỉ số (Metrics)

Các chỉ số là các phép đo số học được tổng hợp theo thời gian. Đối với một API, những chỉ số quan trọng nhất là tỷ lệ yêu cầu, tỷ lệ lỗi và phân phối độ trễ. Báo cáo độ trễ dưới dạng phần trăm (p95 và p99), không chỉ là giá trị trung bình. Giá trị trung bình che giấu phần đuôi chậm mà người dùng thực sự cảm nhận.

Các chỉ số rẻ để lưu trữ và nhanh để truy vấn, điều này làm cho chúng trở nên lý tưởng cho các bảng điều khiển và cảnh báo. Điểm yếu của chúng là tính đa dạng thấp (low cardinality): chúng cho bạn biết rằng độ trễ p99 đã tăng đột biến, nhưng không phải yêu cầu nào đã gây ra nó.

Nhật ký (Logs)

Nhật ký là các bản ghi có dấu thời gian của các sự kiện rời rạc. Các nhật ký có cấu trúc, được phát ra dưới dạng JSON với các trường nhất quán, hữu ích hơn nhiều so với các dòng văn bản tự do vì bạn có thể lọc và tổng hợp chúng.

{
  "timestamp": "2026-06-22T02:14:09Z",
  "level": "error",
  "method": "POST",
  "path": "/v2/checkout",
  "status": 503,
  "duration_ms": 4812,
  "trace_id": "8f3a1c9d2e7b4a16",
  "user_region": "ap-southeast-1",
  "api_version": "2026-05"
}

Hãy chú ý trường trace_id. ID đó là thứ liên kết một dòng nhật ký với luồng yêu cầu rộng hơn, điều này đưa chúng ta đến trụ cột thứ ba.

Dấu vết (Traces)

Một dấu vết phân tán (distributed trace) theo dõi một yêu cầu khi nó di chuyển qua các dịch vụ. Mỗi bước nhảy (hop) trở thành một span, và các span chia sẻ một ID dấu vết để bạn có thể tái tạo lại toàn bộ đường dẫn và xem thời gian đã đi đâu. Khi một yêu cầu đi qua một gateway, một dịch vụ xác thực và ba microservice, dấu vết cho thấy bước nhảy nào đã thêm 4 giây.

Dấu vết là thứ làm cho việc gỡ lỗi microservice trở nên khả thi. Nếu không có chúng, bạn đang đoán xem dịch vụ nào trong chuỗi đang chậm.

Ba trụ cột hoạt động cùng nhau. Một cảnh báo chỉ số báo hiệu sự tăng đột biến. Một dấu vết chỉ ra dịch vụ chậm. Nhật ký từ dịch vụ đó, được lọc theo ID dấu vết, cho bạn biết chính xác điều gì đã xảy ra.

Phương pháp RED và Tín hiệu vàng

Bạn không cần phải theo dõi mọi thứ. Phương pháp RED cung cấp cho bạn một điểm khởi đầu tập trung cho bất kỳ dịch vụ dựa trên yêu cầu nào. Tom Wilkie đã giới thiệu nó vào năm 2015 khi làm việc tại Weaveworks, được phát triển từ bốn tín hiệu vàng của Google.

RED là viết tắt của:

Rate (Tỷ lệ): số yêu cầu mỗi giây mà API của bạn xử lý.
Errors (Lỗi): số lượng hoặc tỷ lệ các yêu cầu thất bại, chẳng hạn như phản hồi 5xx và phản hồi 4xx không mong muốn.
Duration (Thời lượng): phân phối độ trễ yêu cầu, được báo cáo dưới dạng p95 và p99.

Tỷ lệ     = yêu cầu/giây
Lỗi      = % của phản hồi 5xx (và 4xx không mong muốn)
Thời lượng = phân phối độ trễ, báo cáo p95 và p99 (không chỉ trung bình)

RED tập trung vào yêu cầu, phù hợp với API, gateway và service mesh. Đối tác của nó, USE (Utilization - Sử dụng, Saturation - Bão hòa, Errors - Lỗi), nhắm mục tiêu vào các tài nguyên cơ sở hạ tầng như CPU và đĩa. Đối với một API, hãy bắt đầu với RED và thêm USE cho các máy chủ bên dưới.

SLI và SLO: Biến tín hiệu thành mục tiêu

Dữ liệu khả năng quan sát trở nên hữu ích khi bạn gắn các mục tiêu vào nó. Sách SRE của Google định nghĩa hai thuật ngữ ở đây.

Chỉ số mức độ dịch vụ (SLI) là một thước đo định lượng của một khía cạnh dịch vụ của bạn. Các SLI phổ biến là độ trễ yêu cầu, tỷ lệ lỗi (phần trăm tổng số yêu cầu thất bại) và thông lượng theo yêu cầu mỗi giây. Những điều này phù hợp một cách rõ ràng với RED.

Mục tiêu mức độ dịch vụ (SLO) là một giá trị hoặc phạm vi mục tiêu cho một SLI. Ví dụ: "99.9% yêu cầu trong cửa sổ 28 ngày hoàn thành dưới 300 ms." SLO cho bạn và nhóm của bạn biết khi nào API đủ khỏe mạnh và khi nào nên dành thời gian kỹ thuật cho độ tin cậy thay vì các tính năng.

SLI và SLO mang lại ý nghĩa cho các chỉ số của bạn. Nếu không có chúng, biểu đồ độ trễ chỉ là một đường lượn sóng; với chúng, nó là một hợp đồng mà bạn có thể đo lường.

Công cụ: OpenTelemetry và các Backend

Bạn có thể chia các công cụ khả năng quan sát thành hai lớp: cách bạn tạo dữ liệu đo lường và nơi bạn gửi nó.

Để tạo, OpenTelemetry là tiêu chuẩn đáng học. Đây là một dự án của Cloud Native Computing Foundation (CNCF), được hình thành bằng cách hợp nhất OpenTracing và OpenCensus. Nó không phụ thuộc vào nhà cung cấp và công cụ, vì vậy nó hoạt động với nhiều loại backend. Nguyên tắc cốt lõi của nó là bạn sở hữu dữ liệu mình tạo, không bị khóa với nhà cung cấp nào. Nó cung cấp API, SDK ngôn ngữ, quy ước ngữ nghĩa, giao thức truyền tải OTLP, tự động đo lường và OpenTelemetry Collector.

Để lưu trữ và phân tích, bạn có nhiều lựa chọn. Prometheus kết hợp với Grafana là một bộ công cụ mã nguồn mở phổ biến cho chỉ số và bảng điều khiển. Các nền tảng thương mại như Datadog và Honeycomb tiếp nhận dấu vết, chỉ số và nhật ký, đồng thời cung cấp khả năng truy vấn có tính đa dạng cao. Nếu bạn sử dụng Datadog, hướng dẫn chi tiết về Datadog API của chúng tôi cho thấy cách đẩy và kéo dữ liệu theo chương trình.

Mục đích của OpenTelemetry là bạn chỉ cần đo lường một lần, sau đó chuyển đổi backend mà không cần đo lường lại. Khả năng di động đó là lý do chính để áp dụng nó sớm.

Vị trí của Kiểm thử và Kiểm tra tổng hợp

Khả năng quan sát không chỉ là một mối quan tâm trong môi trường sản xuất. Một số tín hiệu hữu ích nhất đến từ các bài kiểm tra bạn chạy có chủ đích, cả trước và sau khi triển khai.

Dịch trái: kiểm thử hợp đồng và chạy CI

Trước khi mã được phát hành, các kiểm thử hợp đồng xác minh rằng API của bạn vẫn phù hợp với đặc tả của nó. Chạy các kiểm thử này trong CI giúp phát hiện các thay đổi gây lỗi trước khi chúng đến tay người dùng. Mỗi lần chạy kiểm thử CI là một tín hiệu: thành công hoặc thất bại gắn liền với một commit, một môi trường và một dấu thời gian. Lịch sử đó là dữ liệu khả năng quan sát về chất lượng phát hành của bạn.

Apidog CLI chạy các kịch bản kiểm thử của bạn trong một pipeline. Nó được xây dựng trên Node.js và yêu cầu Node v16 trở lên.

npm install -g apidog-cli
# verify the install
node -v && apidog -v

Chạy một kịch bản kiểm thử đối với một môi trường. Cờ môi trường là bắt buộc, và bạn truyền token của mình một cách rõ ràng.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli

Ở đây -t là ID kịch bản kiểm thử, -e là ID môi trường, và -r đặt các định dạng báo cáo (cli, html, json, junit). Trình báo cáo mặc định là cli. Để điều khiển kịch bản từ một tệp CSV hoặc JSON, hãy thêm -d ./data.csv (cờ -d, hoặc --iteration-data, nhận một đường dẫn tệp). Bạn cũng có thể đẩy tổng quan báo cáo lên đám mây Apidog.

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli --upload-report

Để có một pipeline hoàn chỉnh mà bạn có thể sao chép và điều chỉnh, hãy xem hướng dẫn Apidog CLI cho CI/CD của chúng tôi, hoặc tham khảo CLI đầy đủ cho mọi cờ.

Giám sát tổng hợp trong môi trường sản xuất

Giám sát tổng hợp chạy các yêu cầu đã được kịch bản hóa đối với API trực tiếp của bạn theo một lịch trình, từ bên ngoài, theo cách mà người dùng sẽ truy cập. Nó phát hiện vấn đề trước khi lưu lượng truy cập thực tế và cung cấp cho bạn một luồng dữ liệu độ trễ và khả dụng ổn định. Một kiểm tra tình trạng API cơ bản là hình thức đơn giản nhất. Giám sát tổng hợp đầy đủ mở rộng nó sang các luồng đa bước như đăng nhập rồi thanh toán.

Các kiểm tra này tự chúng là tín hiệu khả năng quan sát. Một lần chạy tổng hợp thất bại lúc 02:00 với thời lượng 4 giây chính xác là loại sự kiện bạn muốn cung cấp cho các dấu vết và nhật ký của mình. Để có một khảo sát về các công cụ chuyên dụng, hãy xem tổng hợp các công cụ kiểm thử tổng hợp hàng đầu của chúng tôi, và đối với các nền tảng giám sát sản xuất, danh sách các công cụ giám sát API của chúng tôi.

Tạo tín hiệu thực với các tác vụ theo lịch trình của Apidog

Apidog có thể tạo các tín hiệu tổng hợp định kỳ thông qua Chức năng Lập lịch tác vụ (Scheduled Tasks). Tính năng này tự động chạy các kịch bản kiểm thử đã cấu hình vào những thời điểm đã định, ghi lại kết quả và hỗ trợ kiểm thử hồi quy theo lịch trình. Bạn có thể tìm thấy nó trong module Tests, tại Scheduled Tasks.

Một vài điều cần biết trước khi bạn phụ thuộc vào nó. Chức năng Lập lịch tác vụ hiện đang ở giai đoạn Beta, vì vậy hãy coi nó là đang phát triển hơn là một tính năng ổn định lâu dài. Nó cũng yêu cầu một Runner tự lưu trữ (self-hosted Runner) đã được cấu hình; các tùy chọn "Runs On" hiện liệt kê một Runner tự lưu trữ, với Apidog Cloud được liệt kê là sẽ sớm ra mắt. Vì vậy, hiện tại chưa có kiểm tra theo lịch trình hoàn toàn trên đám mây.

Khi bạn thiết lập một tác vụ, bạn chọn:

Kịch bản kiểm thử: một hoặc nhiều kịch bản để thực thi.
Chế độ chạy: một chu kỳ thời gian, chẳng hạn như mỗi Chủ Nhật lúc 11 giờ tối hoặc mỗi 6 giờ.
Thông báo: cảnh báo sau mỗi lần chạy, hoặc chỉ khi thất bại.

Số lần chạy phụ thuộc vào gói đăng ký của bạn. Để có một hướng dẫn thực hành, hãy xem hướng dẫn chi tiết về Apidog Scheduled Tasks của chúng tôi.

Giá trị ở đây là hoàn thiện chu trình. Bạn thiết kế và kiểm thử API của mình ở một nơi, sau đó chạy các kịch bản tương tự đó theo một chu kỳ để chúng tiếp tục tạo ra các tín hiệu thành công/thất bại và độ trễ mà bạn có thể hành động. Hãy thử Apidog miễn phí, không yêu cầu thẻ tín dụng, và biến các kịch bản kiểm thử hiện có của bạn thành các tín hiệu định kỳ.

Một con đường thực tế để có một API có thể quan sát được

Nếu bạn đang bắt đầu từ đầu, hãy thực hiện theo thứ tự này:

Phát ra nhật ký có cấu trúc với một lược đồ nhất quán và một ID dấu vết trên mỗi yêu cầu.
Đo lường bằng OpenTelemetry để các dấu vết, chỉ số và nhật ký chia sẻ ngữ cảnh và duy trì khả năng di động trên các backend.
Theo dõi các chỉ số RED (tỷ lệ, lỗi, thời lượng với p95 và p99) và đưa chúng lên một bảng điều khiển.
Xác định SLI và SLO để các chỉ số của bạn có mục tiêu, không chỉ là xu hướng.
Thêm kiểm thử hợp đồng trong CI để phát hiện các thay đổi gây lỗi trước khi phát hành.
Chạy các kiểm tra tổng hợp theo lịch trình đối với môi trường sản xuất, ví dụ với Apidog Scheduled Tasks.

Bạn không cần phải làm tất cả sáu bước cùng một lúc. Ngay cả bước một, nhật ký có cấu trúc với ID dấu vết, cũng đưa bạn tiến xa hơn rất nhiều so với nhật ký văn bản phẳng.

Các câu hỏi thường gặp

Khả năng quan sát API là gì?

Khả năng quan sát API là khả năng hiểu trạng thái nội bộ của API từ dữ liệu đo lường mà nó phát ra, cụ thể là các chỉ số, nhật ký và dấu vết. Một API có thể quan sát được cho phép bạn điều tra lý do tại sao nó hoạt động theo một cách nhất định, bao gồm cả những vấn đề bạn không lường trước được, mà không cần thêm công cụ đo lường mới.

Khả năng quan sát API và giám sát: sự khác biệt là gì?

Giám sát theo dõi các tín hiệu được định nghĩa trước và cảnh báo khi chúng vượt ngưỡng, trả lời câu hỏi "có điều gì tôi mong đợi sẽ hỏng đang hỏng không?" Khả năng quan sát là một thuộc tính của hệ thống cho phép bạn đặt các câu hỏi mới, tùy ý về hành vi của nó, trả lời câu hỏi "tại sao điều này lại xảy ra?" Giám sát cho bạn biết có gì đó không ổn; khả năng quan sát giúp bạn tìm ra nguyên nhân. Bạn cần cả hai.

Ba trụ cột của khả năng quan sát là gì?

Ba trụ cột là các chỉ số (metrics), nhật ký (logs) và dấu vết (traces). Chỉ số là các con số được tổng hợp như tỷ lệ yêu cầu và phần trăm độ trễ. Nhật ký là các bản ghi có dấu thời gian của các sự kiện rời rạc, lý tưởng là được cấu trúc dưới dạng JSON. Dấu vết theo dõi một yêu cầu trên các dịch vụ để bạn có thể thấy thời gian đã được dành ở đâu. OpenTelemetry chính thức hóa chúng thành các tín hiệu đo lường.

Làm thế nào để bạn làm cho một API có thể quan sát được?

Bắt đầu bằng cách phát ra nhật ký có cấu trúc với ID dấu vết trên mỗi yêu cầu. Đo lường mã của bạn bằng OpenTelemetry để các chỉ số, nhật ký và dấu vết chia sẻ ngữ cảnh. Theo dõi các chỉ số RED, xác định SLI và SLO làm mục tiêu, thêm kiểm thử hợp đồng trong CI, và chạy các kiểm tra tổng hợp theo lịch trình đối với môi trường sản xuất. Mỗi bước bổ sung một tín hiệu có thể truy vấn.

OpenTelemetry có bắt buộc đối với khả năng quan sát không?

Không. Khả năng quan sát là một thuộc tính mà bạn có thể đạt được với bất kỳ công cụ đo lường nào, và nhiều nhóm đã sử dụng các tác nhân độc quyền rất lâu trước khi OpenTelemetry tồn tại. Mặc dù vậy, OpenTelemetry là tiêu chuẩn CNCF trung lập với nhà cung cấp, vì vậy việc áp dụng nó cho phép bạn đo lường một lần và chuyển đổi các backend như Prometheus, Datadog hoặc Honeycomb mà không cần đo lường lại. Nó là một lựa chọn mặc định mạnh mẽ, không phải là một yêu cầu bắt buộc.