ADR 0015: Ghi vào VictoriaMetrics bằng API nhập JSON thay cho remote-write
1. Tiêu đề quyết định (Title)
Collector ghi số liệu vào VictoriaMetrics bằng POST /api/v1/import (JSON line), không dùng Prometheus remote-write như ADR 0005 mô tả.
2. Trạng thái (Status)
Chấp nhận (Accepted) ngày 01/10/2026 bởi Product Owner, sau khi đo hiệu năng ghi (mục 6): 1 writer đạt 268.000 mẫu/s, gấp khoảng 11 lần tải thiết kế 23.000 mẫu/s. Điều chỉnh một phần ADR 0005 (ADR 0005 đã được đánh dấu).
Ngày quyết định: 30/09/2026 (ngày ghi nhận; ngày cài đặt xem lịch sử git, COL-5).
3. Ngữ cảnh (Context)
- ADR 0005 chọn VictoriaMetrics "qua Prometheus remote-write", với lý do chuẩn ghi cho phép thay TSDB (Prometheus, Mimir, Thanos) mà không đổi collector.
- Cài đặt remote-write cần thư viện nén snappy và protobuf của Prometheus. Dự án chọn tránh phụ thuộc này ở giai đoạn đầu (
docs/04). - Ràng buộc: Go, hạn chế thêm phụ thuộc bên thứ ba, an toàn chuỗi cung ứng.
4. Quyết định (Decision)
Bộ ghi TSDB (internal/tsdb/vm.go) gửi POST /api/v1/import, mỗi dòng JSON một series với values và timestamps, đáp ứng thành công là 204. Nhãn company_id và server_id luôn được đặt sau cùng và thắng mọi nhãn khác. Ngữ nghĩa dữ liệu không đổi so với remote-write. Truy vấn dùng API đọc của VM với matcher company_id và server_id do collector ép (giá trị được escape bằng strconv.Quote).
Phạm vi: Collector.
5. Cơ sở lý luận (Rationale)
Ưu điểm:
- Không thêm phụ thuộc snappy và protobuf Prometheus, giảm bề mặt chuỗi cung ứng và mã.
- API nhập JSON đơn giản, dễ kiểm thử bằng
httptest.
Nhược điểm chấp nhận được:
- Gắn với VictoriaMetrics: JSON import là API của VM, không phải chuẩn. Đổi sang Prometheus, Mimir, Thanos đòi hỏi viết bộ ghi mới. Lý do "thay được TSDB không đổi collector" trong ADR 0005 không còn đúng nguyên văn; tính thay thế còn ở mức giao diện
tsdb.Writertronginternal/tsdb. - JSON kém gọn hơn nhị phân nén, tốn băng thông và CPU hơn ở khối lượng lớn (chung, chưa đo trong dự án).
- Roadmap ghi adapter chỉ kiểm thử bằng httptest (COL-5); nay dev chạy VM thật nên cần bổ sung kiểm thử tích hợp và đo hiệu năng.
6. Ảnh hưởng (Consequences)
- Tích cực: ít phụ thuộc, mã ngắn gọn.
- Rủi ro: khóa chặt vào VM (bổ sung cho quyết định ở ADR 0014), hiệu năng ghi ở quy mô 23.000 mẫu/s đã được đo trên một máy (xem bên dưới), còn cần đo lại trên phần cứng và mạng thật (X-7, X-9).
- Việc tiếp theo:
- (Xong) ADR 0005 đã được đánh dấu "Một phần bị điều chỉnh bởi ADR 0015".
- Đo hiệu năng ghi thật ở X-7 và X-9, cân nhắc thêm bộ ghi remote-write nếu cần đổi kho.
- Kiểm thử tích hợp với VM thật (không chỉ httptest).
Kết quả đo hiệu năng ghi (01/10/2026, spike S3)
Bài đo: deploy/dev/vmcheck/vmbench_test.go (chạy khi đặt AHC_BENCH_VM_URL), dùng bộ ghi tsdb.VM thật của collector, VictoriaMetrics v1.153.0 tạm, một máy 4 nhân, cùng máy với bộ sinh tải. Tải: 10.000 máy chủ, mỗi máy 69 series, mỗi lần flush 72 agent (4.968 mẫu, gần max_batch 5000). VM ghi nhận 697.794 series (khớp 10.000 × 69), không có lỗi nào.
| Kịch bản | Mẫu/s | Trễ ghi p50 / p99 | CPU VM | RSS VM |
|---|---|---|---|---|
| Tải thiết kế, 2 writer, 23.000 mẫu/s | 23.000 | 27,6 / 47 ms | 0,13 nhân | 232 MB |
| Tối đa, 1 writer | 268.000 | 17,5 / 43 ms | 0,63 nhân | 379 MB |
| Tối đa, 2 writer | 346.000 | 26,8 / 57 ms | 0,85 nhân | 384 MB |
| Tối đa, 4 writer | 527.000 | 34 / 85 ms | 1,13 nhân | 442 MB |
| Tối đa, 8 writer | 585.000 | 59 / 156 ms | 1,55 nhân | 472 MB |
| Tối đa, 4 writer, gzip | 496.000 | 36 / 92 ms | 1,13 nhân | 434 MB |
- Truy vấn một giờ của một máy chủ khi đang ghi 23.000 mẫu/s: p50 0,7 ms, p95 2,4 ms, tối đa 11 ms.
- Kích thước: JSON thô 160 byte/mẫu (~29 Mbit/s ở 23.000 mẫu/s), gzip còn 15,6 byte/mẫu, CPU client gần như không đổi. Trên đĩa 6,4 byte/mẫu cộng 48 byte/series cho chỉ mục, với dữ liệu nhiễu ngẫu nhiên nên gần mức xấu nhất.
- Giới hạn của phép đo: không đo remote-write (cần thêm thư viện), bộ sinh tải và VM dùng chung một máy, timestamp ghi lùi về quá khứ, chưa đo vmalert và vm-long. Dung lượng 30 ngày thật cần đo lại trên dữ liệu thật.
- Hệ quả: chưa cần bộ ghi remote-write. Nếu băng thông agent tới collector là ràng buộc thì bật gzip (chưa cài đặt).
7. Các phương án được đánh giá (Considered Options)
| Phương án | Ưu điểm | Nhược điểm | Kết luận |
|---|---|---|---|
| Prometheus remote-write (ADR 0005) | Chuẩn, thay được kho | Thêm phụ thuộc snappy và protobuf Prometheus | Không chọn ở giai đoạn này |
| VM JSON import | Đơn giản, ít phụ thuộc | Gắn với VM, kém gọn | Chọn (đề xuất) |
| Định dạng nhập khác của VM (Prometheus text, Influx line) | Cũng đơn giản | Không có lợi thế rõ so với JSON, cũng gắn với VM | Không chọn |
8. Tài liệu liên quan (Related Artifacts)
- ADR: 0005, 0014
docs/04-data-model.md(mục Ghi),internal/tsdb/vm.go,internal/tsdb/vm_test.go- Báo cáo lựa chọn TSDB (tính năng số 2)
9. Phê duyệt (Approvals)
| Tên | Vai trò | Ghi chú |
|---|---|---|
| chưa chỉ định | Enterprise Architect | Chưa duyệt |
| chưa chỉ định | Solution Architect | Chưa duyệt |
| Thiện Phan Ngọc | Product Owner | Chấp nhận 01/10/2026, sau khi đo hiệu năng (mục 6) |