DEV Community

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

Posted on • Originally published at apidog.com

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

#api #devops #monitoring #tutorial

Khả năng quan sát API (API observability) là khả năng hiểu vì sao API hoạt động như hiện tại dựa trên dữ liệu đo lường (telemetry) mà API phát ra: metrics, logs và traces. Thay vì chỉ nhìn dashboard cố định, một API được instrument tốt cho phép bạn đặt câu hỏi mới về trạng thái bên trong hệ thống bằng chính dữ liệu đã được thu thập.

Dùng thử Apidog ngay hôm nay

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

Trong lý thuyết điều khiển, một hệ thống “có thể quan sát được” khi bạn có thể suy ra trạng thái nội bộ từ các đầu ra bên ngoài. Với phần mềm, API có thể quan sát được khi telemetry của nó đủ giàu để bạn chẩn đoán hành vi mà không cần deploy thêm code chỉ để thêm một dòng log.

Ví dụ: khách hàng báo rằng request thanh toán chậm lúc 2 giờ sáng, chỉ xảy ra với người dùng ở một region và một version API cụ thể. Nếu API có khả năng quan sát tốt, bạn có thể trả lời:

  • Request nào bị chậm?
  • Chậm ở service nào?
  • Có lỗi downstream không?
  • Có liên quan đến region, version, user segment hoặc dependency nào không?

Đây là điểm khác biệt với uptime check. Uptime check chỉ trả lời “API còn sống không?”. Observability giúp trả lời “vì sao request này chậm hoặc lỗi?”.

Khả năng quan sát và giám sát khác nhau thế nào?

Hai khái niệm này liên quan chặt chẽ nhưng không giống 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 ngưỡng: error rate, CPU, p99 latency, uptime.

Khả năng quan sát (Observability) là thuộc tính của hệ thống: telemetry có đủ chi tiết để bạn đặt câu hỏi mới trong lúc điều tra hay không.

Nói ngắn gọn:

  • Monitoring cho biết có vấn đề.
  • Observability giúp tìm nguyên nhân gốc rễ.

Bạn cần cả hai. Monitoring tạo cảnh báo; observability cung cấp đường đi từ cảnh báo đến root cause. Nếu muốn đi sâu vào phần cảnh báo, xem thêm hướng dẫn giám sát API.

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 ngưỡng không? Vì sao hệ thống hoạt động như vậy?
Thời điểm định nghĩa Trước khi sự cố xảy ra Trong lúc điều tra
Phù hợp cho Lỗi đã biết, vi phạm SLO Vấn đề mới, không lường trước
Đầu ra Alert, dashboard trạng thái Telemetry có thể truy vấn theo nhiều chiều

Ba trụ cột: Metrics, Logs, Traces

Khả năng quan sát thường bắt đầu với ba loại telemetry chính:

  1. Metrics
  2. Logs
  3. Traces

OpenTelemetry gọi chúng là các “signals”. Hiện OpenTelemetry hỗ trợ traces, metrics, logs và baggage; events và profiles đang tiếp tục được phát triển.

Metrics: đo tín hiệu tổng quan

Metrics là các phép đo số được tổng hợp theo thời gian. Với API, hãy bắt đầu bằng RED:

  • Request rate
  • Error rate
  • Latency distribution

Đừng chỉ dùng latency trung bình. Hãy theo dõi percentile như p95 và p99 vì phần đuôi chậm mới là thứ người dùng cảm nhận rõ nhất.

Ví dụ metric nên có:

api_requests_total
api_request_errors_total
api_request_duration_seconds_bucket
api_request_duration_seconds_p95
api_request_duration_seconds_p99
Enter fullscreen mode Exit fullscreen mode

Metrics rẻ để lưu trữ và nhanh để query, nên rất phù hợp cho dashboard và alert. Điểm yếu là metrics thường có cardinality thấp: chúng cho biết p99 latency tăng, nhưng không chỉ ra request cụ thể nào gây ra.

Logs: ghi sự kiện có cấu trúc

Logs là bản ghi có timestamp của các sự kiện rời rạc. Với API production, nên dùng structured logs thay vì text log tự do.

Ví dụ log JSON:

{
  "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"
}
Enter fullscreen mode Exit fullscreen mode

Các field nên có trong API log:

  • timestamp
  • level
  • method
  • path
  • status
  • duration_ms
  • trace_id
  • request_id
  • user_region
  • api_version
  • service_name

Field quan trọng nhất ở đây là trace_id. Nó giúp liên kết một dòng log với toàn bộ luồng request.

Traces: theo request qua nhiều service

Distributed trace theo dõi một request khi nó đi qua nhiều service. Mỗi bước là một span, và các span cùng chia sẻ một trace ID.

Ví dụ một request checkout có thể đi qua:

API Gateway
  -> Auth Service
  -> Checkout Service
  -> Payment Service
  -> Inventory Service
  -> Notification Service
Enter fullscreen mode Exit fullscreen mode

Trace giúp bạn thấy thời gian bị tiêu tốn ở đâu:

POST /v2/checkout                   4812 ms
├─ auth.validate_token                42 ms
├─ checkout.create_order             120 ms
├─ payment.charge_card              4100 ms
├─ inventory.reserve                 320 ms
└─ notification.enqueue               35 ms
Enter fullscreen mode Exit fullscreen mode

Không có trace, bạn phải đoán service nào chậm. Có trace, bạn biết ngay payment.charge_card là span cần điều tra.

Ba trụ cột hoạt động tốt nhất khi được liên kết với nhau:

  1. Metric alert báo p99 latency tăng.
  2. Trace chỉ ra service hoặc dependency chậm.
  3. Log theo trace_id cho biết lỗi hoặc điều kiện cụ thể.

Áp dụng RED cho API

Bạn không cần theo dõi mọi thứ ngay từ đầu. Với API, hãy bắt đầu bằng phương pháp RED:

  • Rate: số request mỗi giây.
  • Errors: số lượng hoặc tỷ lệ request thất bại, ví dụ 5xx và các 4xx không mong muốn.
  • Duration: phân phối latency, đặc biệt p95 và p99. 
Rate      = requests/second
Errors    = % response 5xx + unexpected 4xx
Duration  = latency distribution, p95, p99
Enter fullscreen mode Exit fullscreen mode

RED phù hợp với API, gateway và service mesh. Với hạ tầng bên dưới như CPU, memory, disk, network, bạn có thể bổ sung USE:

  • Utilization
  • Saturation
  • Errors

Cách triển khai thực tế:

  1. Tạo dashboard RED cho từng service quan trọng.
  2. Tách metric theo route, method, status code.
  3. Cẩn thận với cardinality: không đưa user_id hoặc giá trị quá động vào label metric.
  4. Dùng logs/traces cho dữ liệu chi tiết cấp request.

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

Telemetry chỉ hữu ích khi bạn biết “tốt” nghĩa là gì.

SLI (Service Level Indicator) là chỉ số đo được của dịch vụ. Ví dụ:

  • Tỷ lệ request thành công
  • Latency p95
  • Latency p99
  • Throughput
  • Availability

SLO (Service Level Objective) là mục tiêu cho SLI.

Ví dụ:

99.9% request trong cửa sổ 28 ngày phải hoàn thành dưới 300 ms.
Enter fullscreen mode Exit fullscreen mode

Hoặc:

Tỷ lệ lỗi 5xx của POST /v2/checkout phải nhỏ hơn 0.1% trong 7 ngày.
Enter fullscreen mode Exit fullscreen mode

SLO giúp nhóm quyết định khi nào nên ưu tiên reliability thay vì tiếp tục thêm feature. Nếu không có SLO, biểu đồ latency chỉ là một đường dao động. Có SLO, nó trở thành mục tiêu vận hành có thể đo được.

Công cụ: OpenTelemetry và backend quan sát

Có hai lớp công cụ chính:

  1. Công cụ tạo telemetry.
  2. Backend để lưu trữ, query và hiển thị telemetry.

Tạo telemetry với OpenTelemetry

OpenTelemetry là tiêu chuẩn trung lập với nhà cung cấp thuộc CNCF, được hình thành từ OpenTracing và OpenCensus. Nó cung cấp:

  • API và SDK theo ngôn ngữ
  • Semantic conventions
  • OTLP protocol
  • Auto-instrumentation
  • OpenTelemetry Collector

Lợi ích chính: bạn instrument một lần, sau đó có thể gửi dữ liệu đến nhiều backend khác nhau mà không phải viết lại toàn bộ instrumentation.

Backend phổ biến

Một số lựa chọn phổ biến:

  • Prometheus + Grafana cho metrics và dashboard.
  • Datadog cho metrics, logs, traces và alerting.
  • Honeycomb cho truy vấn high-cardinality.
  • Các backend tương thích OTLP khác.

Nếu bạn dùng Datadog, xem thêm hướng dẫn Datadog API để làm việc với dữ liệu theo chương trình.

Đưa kiểm thử vào observability

Observability không chỉ đến từ production traffic. Các bài kiểm thử cũng tạo ra tín hiệu quan trọng, đặc biệt trong CI/CD và synthetic monitoring.

Shift-left: kiểm thử hợp đồng trong CI

Trước khi release, contract test giúp xác minh API vẫn khớp với đặc tả. Khi chạy trong CI, mỗi lần test tạo ra một tín hiệu:

  • Commit nào?
  • Environment nào?
  • Test case nào fail?
  • Endpoint nào bị ảnh hưởng?
  • Thời điểm nào?

Đó là telemetry về chất lượng release.

Apidog CLI có thể chạy test scenario trong pipeline. Công cụ này chạy trên Node.js và yêu cầu Node v16 trở lên.

Cài đặt:

npm install -g apidog-cli

# kiểm tra phiên bản
node -v && apidog -v
Enter fullscreen mode Exit fullscreen mode

Chạy một test scenario với environment cụ thể:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -r html,cli
Enter fullscreen mode Exit fullscreen mode

Trong đó:

  • -t: ID kịch bản kiểm thử
  • -e: ID môi trường
  • -r: định dạng báo cáo, ví dụ cli, html, json, junit

Nếu muốn chạy test theo dữ liệu từ CSV hoặc JSON:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  -r html,cli \
  -d ./data.csv
Enter fullscreen mode Exit fullscreen mode

Cờ -d hoặc --iteration-data nhận đường dẫn đến file dữ liệu.

Bạn cũng có thể upload tổng quan báo cáo lên Apidog Cloud:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  -r html,cli \
  --upload-report
Enter fullscreen mode Exit fullscreen mode

Để có pipeline hoàn chỉnh, xem hướng dẫn Apidog CLI cho CI/CD hoặc tham khảo CLI đầy đủ.

Synthetic monitoring trong production

Synthetic monitoring chạy các request đã kịch bản hóa vào API production theo lịch. Nó mô phỏng cách người dùng thật truy cập hệ thống, nhưng được kiểm soát và lặp lại.

Một health check đơn giản có thể kiểm tra:

GET /health
Enter fullscreen mode Exit fullscreen mode

Một flow tổng hợp thực tế hơn có thể là:

1. Login
2. Lấy danh sách sản phẩm
3. Tạo đơn hàng
4. Thanh toán
5. Kiểm tra trạng thái đơn hàng
Enter fullscreen mode Exit fullscreen mode

Một kiểm tra tình trạng API là dạng đơn giản nhất. Giám sát tổng hợp mở rộng sang các luồng nhiều bước như đăng nhập rồi thanh toán.

Synthetic checks cũng là tín hiệu observability. Ví dụ:

{
  "check_name": "checkout-flow",
  "status": "failed",
  "duration_ms": 4021,
  "region": "ap-southeast-1",
  "timestamp": "2026-06-22T02:00:00Z"
}
Enter fullscreen mode Exit fullscreen mode

Khi synthetic check fail, bạn nên correlate nó với traces và logs cùng thời điểm.

Để khảo sát thêm công cụ, xem các công cụ kiểm thử tổng hợp hàng đầu và các công cụ giám sát API.

Tạo tín hiệu định kỳ với Apidog Scheduled Tasks

Apidog có thể tạo tín hiệu tổng hợp định kỳ bằng 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 theo lịch, ghi lại kết quả và hỗ trợ kiểm thử hồi quy theo chu kỳ.

Bạn có thể tìm thấy tính năng này trong module Tests, mục Scheduled Tasks.

Khi tạo một scheduled task, bạn cần chọn:

  • Test scenario: một hoặc nhiều kịch bản cần chạy.
  • Run mode: lịch chạy, ví dụ mỗi 6 giờ hoặc mỗi Chủ Nhật lúc 23:00.
  • Notification: thông báo sau mỗi lần chạy hoặc chỉ khi thất bại.

Một số lưu ý quan trọng:

  • Scheduled Tasks hiện ở giai đoạn Beta.
  • Tính năng này yêu cầu self-hosted Runner đã được cấu hình.
  • Tùy chọn Apidog Cloud trong “Runs On” được liệt kê là sắp ra mắt.
  • Số lần chạy phụ thuộc vào gói đăng ký.

Xem hướng dẫn thực hành tại hướng dẫn chi tiết về Apidog Scheduled Tasks.

Giá trị chính là bạn có thể dùng lại test scenario đã thiết kế, rồi chạy chúng theo lịch để tạo tín hiệu thành công/thất bại và latency định kỳ.

Lộ trình triển khai API observability

Nếu bắt đầu từ đầu, hãy đi theo thứ tự này.

1. Chuẩn hóa structured logs

Đảm bảo mọi request có log theo schema nhất quán:

{
  "timestamp": "2026-06-22T02:14:09Z",
  "level": "info",
  "service": "checkout-api",
  "method": "POST",
  "path": "/v2/checkout",
  "status": 200,
  "duration_ms": 183,
  "trace_id": "8f3a1c9d2e7b4a16",
  "request_id": "req_123"
}
Enter fullscreen mode Exit fullscreen mode

Ưu tiên log JSON thay vì text tự do.

2. Thêm trace ID cho mọi request

Mỗi request nên có:

  • trace_id
  • span_id
  • request_id

Truyền các ID này qua service boundary bằng header, ví dụ:

traceparent: 00-8f3a1c9d2e7b4a16b7c2d9e3f1a0b2c3-3f2a1b4c5d6e7f80-01
Enter fullscreen mode Exit fullscreen mode

3. Instrument bằng OpenTelemetry

Dùng OpenTelemetry để metrics, logs và traces chia sẻ cùng context. Bắt đầu với auto-instrumentation nếu stack của bạn hỗ trợ, sau đó thêm manual spans cho business logic quan trọng.

Ví dụ span nên có:

checkout.validate_cart
checkout.create_order
payment.charge
inventory.reserve
Enter fullscreen mode Exit fullscreen mode

4. Tạo dashboard RED

Dashboard tối thiểu cho mỗi API service nên có:

  • Requests per second
  • Error rate theo status code
  • p95 latency
  • p99 latency
  • Top slow endpoints
  • Top failing endpoints

5. Định nghĩa SLI và SLO

Ví dụ SLI/SLO cho checkout API:

SLI: tỷ lệ request POST /v2/checkout thành công
SLO: 99.9% request thành công trong 28 ngày

SLI: p95 latency của POST /v2/checkout
SLO: p95 < 300 ms trong 7 ngày
Enter fullscreen mode Exit fullscreen mode

6. Thêm contract test vào CI

Chạy test trước khi merge hoặc deploy. Nếu test fail, dừng pipeline.

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  -r junit,cli
Enter fullscreen mode Exit fullscreen mode

Report junit hữu ích khi tích hợp với CI server.

7. Chạy synthetic checks theo lịch

Chạy các flow quan trọng như login, checkout, payment, token refresh theo lịch. Khi check fail, dùng timestamp, region và trace/log để điều tra.

Bạn không cần làm đủ bảy bước cùng lúc. Chỉ riêng structured logs kèm trace ID đã cải thiện đáng kể khả năng debug so với log text phẳng.

Checklist triển khai nhanh

Dùng checklist này để rà soát API hiện tại:

  • [ ] Mọi request có request_id
  • [ ] Mọi request có trace_id
  • [ ] Logs ở dạng JSON
  • [ ] Logs có method, path, status, duration_ms
  • [ ] Metrics có request rate, error rate, latency p95/p99
  • [ ] Có distributed tracing cho request đi qua nhiều service
  • [ ] Có dashboard RED cho service chính
  • [ ] Có alert dựa trên SLO
  • [ ] Có contract test trong CI
  • [ ] Có synthetic monitoring cho flow quan trọng
  • [ ] Có cách liên kết alert → trace → log

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ừ telemetry mà nó phát ra, gồm metrics, logs và traces. Một API có thể quan sát được cho phép bạn điều tra vì sao nó hoạt động theo một cách nhất định mà không cần thêm instrumentation mới trong lúc sự cố.

Khả năng quan sát API và giám sát khác nhau thế nào?

Giám sát theo dõi tín hiệu được định nghĩa trước và cảnh báo khi vượt ngưỡng. Khả năng quan sát cho phép bạn đặt câu hỏi mới về hành vi hệ thống trong lúc điều tra. Monitoring cho biết có vấn đề; observability giúp tìm nguyên nhân.

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

Ba trụ cột là metrics, logs và traces. Metrics là số liệu tổng hợp như request rate và latency percentile. Logs là bản ghi sự kiện có timestamp, tốt nhất là JSON có cấu trúc. Traces theo dõi một request qua nhiều service để biết thời gian được tiêu tốn ở đâu.

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

Bắt đầu bằng structured logs có trace ID cho mỗi request. Sau đó instrument bằng OpenTelemetry, theo dõi RED metrics, định nghĩa SLI/SLO, thêm contract test trong CI và chạy synthetic checks theo lịch trong production.

OpenTelemetry có bắt buộc không?

Không. Observability là thuộc tính của hệ thống, không phụ thuộc vào một công cụ cụ thể. Tuy vậy, OpenTelemetry là tiêu chuẩn CNCF trung lập với nhà cung cấp, giúp bạn instrument một lần và gửi telemetry đến nhiều backend như Prometheus, Datadog hoặc Honeycomb mà không cần viết lại instrumentation.

Top comments (0)