ADR 0006Chấp nhận

ADR 0006. Chọn chỉ số bằng glob include, exclude trên danh mục định nghĩa trong mã

1. Danh mục chỉ số là một nguồn duy nhất trong mã (internal/catalog): tên, nhóm, đơn vị, nhãn cho phép, bộ thu, nền tảng, mặc định, bắt buộc, mô tả vi và en. Allowed và mọi công cụ khác sinh từ đó. 2. Cấu hình có hai danh sách metrics.include và metrics.exclude, mỗi phần tử là tên hoặc glob theo path.Match, chồng lên công tắc enabled của từng bộ thu. Include rỗng nghĩa là mọi chỉ số bật mặc định. Include khác rỗng nghĩa là chỉ chỉ số khớp. Exclude thắng include. 3. Chỉ số bắt buộc (toàn bộ nhóm agent, dùng để tự giám sát) không bao giờ bị loại. Cố loại thì giữ lại và ghi cảnh báo. 4. Mẫu sai cú pháp hoặc không khớp chỉ số nào là lỗi cấu hình, thông báo kèm danh sách tên hợp lệ, để lỗi gõ tên không âm thầm mất dữ liệu. 5. Lọc thực hiện trong engine trước khi làm sạch. Mẫu bị loại không được phát và không tính vào số mẫu bị bỏ. Bộ thu có mọi chỉ số bị loại thì không chạy. 6. Lệnh metrics list và metrics show cho thấy trạng thái hiệu lực theo cấu hình đang nạp. Kiểm thử đồng bộ giữ danh mục trong mã khớp docs/03-metrics-catalog.md theo cả hai chiều.

Ngày quyết định

30/09/2026

Chấp nhận

30/09/2026

Phạm vi

Agent

Người chấp nhận

Chưa ghi

1. Đề xuất30/09/2026
2. Chấp nhận30/09/2026

• Trạng thái: Đã chấp nhận
• Ngày: 2026-09-30

Bối cảnh

Mỗi agent bị giới hạn 500 series (limits.max_series) và hàng nghìn máy cùng đẩy về một Collector, nên chi phí lưu trữ tỷ lệ trực tiếp với số chỉ số mỗi máy. Quản trị viên cần bỏ bớt chỉ số không dùng (ví dụ mem_slab_bytes, nhóm psi_*) mà không phải tắt cả bộ thu. Trước đây tên chỉ số nằm rải rác: danh sách trắng Allowed trong mã, bảng trong tài liệu, danh mục phía Collector, nên dễ lệch nhau.

Quyết định

1. Danh mục chỉ số là một nguồn duy nhất trong mã (internal/catalog): tên, nhóm, đơn vị, nhãn cho phép, bộ thu, nền tảng, mặc định, bắt buộc, mô tả vi và en. Allowed và mọi công cụ khác sinh từ đó.
2. Cấu hình có hai danh sách metrics.include và metrics.exclude, mỗi phần tử là tên hoặc glob theo path.Match, chồng lên công tắc enabled của từng bộ thu. Include rỗng nghĩa là mọi chỉ số bật mặc định. Include khác rỗng nghĩa là chỉ chỉ số khớp. Exclude thắng include.
3. Chỉ số bắt buộc (toàn bộ nhóm agent, dùng để tự giám sát) không bao giờ bị loại. Cố loại thì giữ lại và ghi cảnh báo.
4. Mẫu sai cú pháp hoặc không khớp chỉ số nào là lỗi cấu hình, thông báo kèm danh sách tên hợp lệ, để lỗi gõ tên không âm thầm mất dữ liệu.
5. Lọc thực hiện trong engine trước khi làm sạch. Mẫu bị loại không được phát và không tính vào số mẫu bị bỏ. Bộ thu có mọi chỉ số bị loại thì không chạy.
6. Lệnh metrics list và metrics show cho thấy trạng thái hiệu lực theo cấu hình đang nạp. Kiểm thử đồng bộ giữ danh mục trong mã khớp docs/03-metrics-catalog.md theo cả hai chiều.

Hệ quả

• Thêm một chỉ số là thêm một dòng vào danh mục và một dòng vào tài liệu, kiểm thử báo lệch nếu thiếu một bên.
• Nhãn cho phép nằm cùng chỗ với tên, không còn hai danh sách riêng.
• Cấu hình từ xa có thể dùng cùng cơ chế, lọc chỉ làm giảm dữ liệu nên không mở rộng bề mặt tấn công (ADR 0005).
• Phía Collector và Access Hub vẫn phải khai báo chỉ số mới trong danh mục riêng của họ.

Phương án đã cân nhắc

Phương án	Lý do không chọn
Chỉ dùng công tắc enabled theo bộ thu	Quá thô: muốn bỏ một chỉ số phải tắt cả nhóm
Liệt kê từng tên trong cấu hình, không glob	Dài và dễ sai với nhóm nhiều chỉ số (psi_*, net_*_packets_per_sec)
Regex thay cho glob	Khó đọc hơn cho người vận hành, dễ viết sai neo, khó liệt kê kết quả
Danh mục tải từ tệp YAML hoặc từ Collector	Thêm bề mặt cấu hình và điểm lỗi, mất kiểm tra lúc biên dịch