Danh mục chỉ số
Nguồn sự thật của tên chỉ số, nhãn cho phép và đặc tính từng chỉ số là internal/catalog/catalog.go (mã Go). Tài liệu này phản chiếu nó và có kiểm thử đồng bộ (internal/catalog/docs_sync_test.go): thêm, đổi tên, đổi nhãn, đơn vị, mặc định hoặc cờ bắt buộc ở một bên mà quên bên kia thì CI đỏ. Collector giữ bản máy đọc được (internal/catalog/metrics.yaml của collector) sinh từ cùng nguồn, thay đổi phải đồng bộ hai bên.
Xem danh mục ngay trên máy: accesshub-agent metrics list và accesshub-agent metrics show <tên> (có trạng thái bật, tắt theo cấu hình hiện tại).
Quy ước
- Chỉ dùng gauge. Tốc độ do agent tính từ bộ đếm, mẫu đầu tiên sau khởi động bị bỏ (xem 10-wire-contract.md, chỉ gauge).
- Tên:
^[a-z][a-z0-9_]{0,63}$. Trong TSDB có tiền tốah_, agent gửi tên không có tiền tố. - Nhãn hệ thống
company_id,server_iddo collector gắn, agent không gửi. - Đơn vị nằm trong tên (
_percent,_bytes,_seconds,_per_sec). Cột Đơn vị chỉ để tham khảo. - Nhóm (
group) dùng để xem và lọc trong CLI:cpu,memory,disk,net,system,checks,agent.
Chọn chỉ số cần thu thập
Có hai lớp, áp dụng lần lượt:
- Bật, tắt bộ thu (
metrics.cpu.enabled,memory,disk,net,uptime,pressure): tắt cả nhóm chỉ số do bộ thu đó tạo ra. - Danh sách
metrics.includevàmetrics.exclude: chọn từng chỉ số theo tên hoặc mẫu glob (*,?,[a-z], cú pháppath.Match, khớp toàn tên).
yaml
metrics:
include: [] # rỗng: lấy mọi chỉ số mặc định. Khác rỗng: chỉ lấy các chỉ số khớp
exclude:
- net_*_drops_per_sec # bỏ gói rơi
- mem_slab_bytes
- psi_*Quy tắc:
| Tình huống | Kết quả |
|---|---|
include rỗng, exclude rỗng | Mọi chỉ số mặc định bật (cột Mặc định là bật) |
include khác rỗng | Chỉ các chỉ số khớp include (cộng chỉ số bắt buộc) |
Khớp cả include lẫn exclude | exclude thắng |
exclude trúng chỉ số bắt buộc (nhóm agent) | Chỉ số vẫn được gửi, agent ghi cảnh báo metric selection vào log và metrics list in cảnh báo |
| Mẫu không khớp chỉ số nào, hoặc sai cú pháp glob | Lỗi cấu hình (mã thoát 3), thông báo liệt kê toàn bộ tên hợp lệ |
| Mọi chỉ số của một bộ thu bị loại | Agent không chạy bộ thu đó (không tốn CPU, không đọc /proc) |
Chỉ số bị loại không bao giờ được tạo ra, không vào WAL, không cộng vào agent_dropped_samples_total (đó là bỏ có chủ đích, không phải mất dữ liệu). Chỉ số planned (kế hoạch) có trong danh mục nhưng chưa được phát ra.
Chỉ số bắt buộc là toàn bộ nhóm agent: collector và Access Hub dựa vào chúng để biết agent còn khỏe, độ lệch đồng hồ và mẫu bị bỏ. Lý do thiết kế ở ADR 0006.
Lưu ý: metrics.net.include, metrics.net.exclude (regex chọn giao diện mạng) và metrics.disk.* (chọn mount) là bộ lọc theo nhãn, khác với metrics.include, metrics.exclude (chọn theo tên chỉ số).
Danh mục theo nhóm
Cột Mặc định: bật gửi mặc định, kế hoạch đã vào danh mục nhưng chưa phát ra. Cột Biểu đồ dự kiến là chỗ Access Hub dùng chỉ số trên trang Sức khỏe của máy chủ (tham khảo, không ràng buộc hợp đồng). Tắt một chỉ số thì biểu đồ dùng nó sẽ trống.
Nhóm cpu
| Chỉ số | Nhãn | Đơn vị | Mặc định | Bắt buộc | Nền tảng | Biểu đồ dự kiến | Ý nghĩa |
|---|---|---|---|---|---|---|---|
cpu_usage_percent | % | bật | không | Linux, Windows | Gauge nhanh, Cơ bản | Sử dụng CPU tổng (100 trừ idle) | |
cpu_mode_percent | mode | % | bật | không | Linux, Windows | CPU theo chế độ | Tỷ lệ CPU theo chế độ: user, nice, system, idle, iowait, irq, softirq, steal (Linux). Windows chỉ có user, system, idle |
cpu_load1 | - | bật | không | Linux | Tải trung bình | Tải trung bình 1 phút | |
cpu_load5 | - | bật | không | Linux | Tải trung bình | Tải trung bình 5 phút | |
cpu_load15 | - | bật | không | Linux | Tải trung bình | Tải trung bình 15 phút | |
load_per_core_5m | - | bật | không | Linux | Gauge nhanh | cpu_load5 chia số lõi logic | |
cpu_cores | - | bật | không | Linux, Windows | Thông tin máy | Số lõi logic |
Nhóm memory
| Chỉ số | Nhãn | Đơn vị | Mặc định | Bắt buộc | Nền tảng | Biểu đồ dự kiến | Ý nghĩa |
|---|---|---|---|---|---|---|---|
mem_total_bytes | bytes | bật | không | Linux, Windows | Bộ nhớ xếp chồng, Thông tin máy | Tổng RAM | |
mem_used_bytes | bytes | bật | không | Linux, Windows | Bộ nhớ xếp chồng | RAM đã dùng (tổng trừ khả dụng) | |
mem_available_bytes | bytes | bật | không | Linux, Windows | Bộ nhớ xếp chồng | RAM khả dụng (MemAvailable) | |
mem_used_percent | % | bật | không | Linux, Windows | Gauge nhanh, Cơ bản | Phần trăm RAM đã dùng | |
mem_free_bytes | bytes | bật | không | Linux | Bộ nhớ xếp chồng | RAM hoàn toàn trống (MemFree) | |
mem_cached_bytes | bytes | bật | không | Linux | Bộ nhớ xếp chồng | Bộ nhớ đệm tệp (Cached) | |
mem_buffers_bytes | bytes | bật | không | Linux | Bộ nhớ xếp chồng | Bộ đệm khối (Buffers) | |
mem_slab_bytes | bytes | bật | không | Linux | Bộ nhớ xếp chồng | Bộ nhớ slab của kernel (Slab) | |
mem_page_tables_bytes | bytes | bật | không | Linux | Bộ nhớ xếp chồng | Bảng trang (PageTables) | |
swap_total_bytes | bytes | bật | không | Linux, Windows | Thông tin máy | Tổng swap (Windows: page file) | |
swap_used_bytes | bytes | bật | không | Linux, Windows | Bộ nhớ xếp chồng | Swap đã dùng | |
swap_used_percent | % | bật | không | Linux, Windows | Gauge nhanh | Phần trăm swap đã dùng | |
swap_cached_bytes | bytes | bật | không | Linux | Bộ nhớ xếp chồng | Swap còn nằm trong RAM (SwapCached) |
Nhóm disk
| Chỉ số | Nhãn | Đơn vị | Mặc định | Bắt buộc | Nền tảng | Biểu đồ dự kiến | Ý nghĩa |
|---|---|---|---|---|---|---|---|
disk_total_bytes | mount, fstype | bytes | bật | không | Linux, Windows | Thông tin máy | Dung lượng mount |
disk_used_bytes | mount, fstype | bytes | bật | không | Linux, Windows | Đĩa theo mount | Dung lượng đã dùng |
disk_used_percent | mount, fstype | % | bật | không | Linux, Windows | Gauge nhanh, Đĩa theo mount, Cơ bản | Phần trăm dùng theo cách df tính |
disk_inodes_used_percent | mount, fstype | % | bật | không | Linux | Đĩa theo mount | Phần trăm inode đã dùng |
disk_read_bytes_per_sec | device | bytes/s | kế hoạch | không | Linux, Windows | Đĩa I/O | Thông lượng đọc của đĩa |
disk_write_bytes_per_sec | device | bytes/s | kế hoạch | không | Linux, Windows | Đĩa I/O | Thông lượng ghi của đĩa |
disk_io_util_percent | device | % | kế hoạch | không | Linux, Windows | Đĩa I/O | Thời gian bận của đĩa |
Nhóm net
| Chỉ số | Nhãn | Đơn vị | Mặc định | Bắt buộc | Nền tảng | Biểu đồ dự kiến | Ý nghĩa |
|---|---|---|---|---|---|---|---|
net_rx_bytes_per_sec | iface | bytes/s | bật | không | Linux, Windows | Mạng (byte), Cơ bản | Byte nhận mỗi giây |
net_tx_bytes_per_sec | iface | bytes/s | bật | không | Linux, Windows | Mạng (byte), Cơ bản | Byte gửi mỗi giây |
net_rx_packets_per_sec | iface | 1/s | bật | không | Linux, Windows | Mạng (gói) | Gói nhận mỗi giây |
net_tx_packets_per_sec | iface | 1/s | bật | không | Linux, Windows | Mạng (gói) | Gói gửi mỗi giây |
net_rx_errors_per_sec | iface | 1/s | bật | không | Linux, Windows | Mạng (lỗi) | Lỗi nhận mỗi giây |
net_tx_errors_per_sec | iface | 1/s | bật | không | Linux, Windows | Mạng (lỗi) | Lỗi gửi mỗi giây |
net_rx_drops_per_sec | iface | 1/s | bật | không | Linux, Windows | Mạng (rơi) | Gói nhận bị rơi mỗi giây |
net_tx_drops_per_sec | iface | 1/s | bật | không | Linux, Windows | Mạng (rơi) | Gói gửi bị rơi mỗi giây |
Nhóm system
| Chỉ số | Nhãn | Đơn vị | Mặc định | Bắt buộc | Nền tảng | Biểu đồ dự kiến | Ý nghĩa |
|---|---|---|---|---|---|---|---|
uptime_seconds | s | bật | không | Linux, Windows | Thông tin máy | Thời gian từ lần khởi động cuối | |
boot_time_seconds | s | bật | không | Linux, Windows | Thông tin máy | Thời điểm khởi động (epoch) | |
procs_total | - | bật | không | Linux | - | Tổng số tiến trình, không chi tiết | |
open_fds_percent | % | kế hoạch | không | Linux | - | Phần trăm mô tả tệp mở toàn hệ thống | |
psi_cpu_some_percent | % | bật | không | Linux | Áp lực PSI | Áp lực CPU (PSI some, trung bình 10 giây): phần thời gian có tác vụ phải chờ CPU | |
psi_memory_some_percent | % | bật | không | Linux | Áp lực PSI | Áp lực bộ nhớ (PSI some, trung bình 10 giây) | |
psi_io_some_percent | % | bật | không | Linux | Áp lực PSI | Áp lực I/O (PSI some, trung bình 10 giây) |
Nhóm checks
| Chỉ số | Nhãn | Đơn vị | Mặc định | Bắt buộc | Nền tảng | Biểu đồ dự kiến | Ý nghĩa |
|---|---|---|---|---|---|---|---|
service_up | name | 0/1 | bật | không | Linux, Windows | - | 1 nếu dịch vụ đang chạy |
port_up | port, proto | 0/1 | bật | không | Linux, Windows | - | 1 nếu có tiến trình lắng nghe cổng |
tcp_connect_up | target | 0/1 | bật | không | Linux, Windows | - | 1 nếu kết nối TCP thành công |
tcp_connect_seconds | target | s | bật | không | Linux, Windows | - | Thời gian kết nối TCP |
http_up | target | 0/1 | bật | không | Linux, Windows | - | 1 nếu HTTP trả mã mong đợi |
http_duration_seconds | target | s | bật | không | Linux, Windows | - | Thời gian phản hồi HTTP |
http_status_code | target | - | bật | không | Linux, Windows | - | Mã trạng thái HTTP gần nhất |
cert_days_left | target | days | bật | không | Linux, Windows | - | Số ngày còn lại của chứng chỉ TLS |
Nhóm agent
| Chỉ số | Nhãn | Đơn vị | Mặc định | Bắt buộc | Nền tảng | Biểu đồ dự kiến | Ý nghĩa |
|---|---|---|---|---|---|---|---|
agent_cpu_percent | % | bật | có | Linux, Windows | - | CPU agent dùng | |
agent_rss_bytes | bytes | bật | có | Linux, Windows | - | RSS của agent | |
agent_goroutines | - | bật | có | Linux, Windows | - | Số goroutine | |
agent_wal_bytes | bytes | bật | có | Linux, Windows | - | Dung lượng WAL hiện tại | |
agent_wal_batches | - | bật | có | Linux, Windows | - | Số lô chờ trong WAL | |
agent_send_failures_total | - | bật | có | Linux, Windows | - | Tổng số lần gửi lỗi (gauge tích lũy trong đời tiến trình) | |
agent_dropped_samples_total | - | bật | có | Linux, Windows | - | Mẫu bị bỏ do WAL đầy hoặc vượt giới hạn | |
agent_collect_duration_seconds | s | bật | có | Linux, Windows | - | Thời gian một chu kỳ thu thập | |
agent_collector_errors | collector | - | bật | có | Linux, Windows | - | Số bộ thu lỗi ở chu kỳ vừa rồi |
agent_clock_skew_seconds | s | bật | có | Linux, Windows | - | Độ lệch đồng hồ so với collector | |
agent_info | version, proto, os | - | bật | có | Linux, Windows | - | Luôn bằng 1, nhãn version, proto, os |
Chỉ số ở nhóm checks chỉ có khi quản trị viên khai báo check tương ứng. Giá trị nhãn name, target, port lấy từ định nghĩa check (danh sách hữu hạn, không phát sinh tự do).
Ngân sách series mỗi máy
| Nguồn | Series | Giới hạn cứng |
|---|---|---|
cpu | 14 (1 tổng, 8 chế độ, 3 tải, 1 tải mỗi lõi, 1 số lõi) | |
memory | 13 (4 RAM, 5 chi tiết, 4 swap) | |
disk | 4 mỗi mount | 40 mount = 160 |
net | 8 mỗi giao diện (byte, gói, lỗi, rơi, mỗi chiều) | 20 giao diện = 160 |
uptime | 3 | |
pressure | 3 (chỉ khi kernel có PSI) | |
agent | khoảng 11 | 16 được giữ chỗ riêng |
checks | 1 đến 3 mỗi check | 50 check |
Máy điển hình (2 mount, 2 giao diện, không check): khoảng 68 series. Giới hạn chung limits.max_series mặc định 500, vượt thì cắt từ cuối và agent_* vẫn được giữ chỗ. Muốn giảm cardinality thì exclude các chỉ số ít dùng (ví dụ net_*_drops_per_sec, net_*_packets_per_sec, mem_slab_bytes).
Bộ lọc mặc định
| Đối tượng | Bỏ | Giữ |
|---|---|---|
| Hệ thống tệp | tmpfs, devtmpfs, overlay, squashfs, proc, sysfs, cgroup, nsfs, mount dưới /var/lib/docker, /var/lib/containers, /snap, /run | ext2/3/4, xfs, btrfs, zfs, nfs* (cấu hình), vfat trên /boot |
| Windows | Ổ đĩa quang, ổ mạng chưa kết nối | Ổ cố định (DRIVE_FIXED), cấu hình ổ mạng |
| Giao diện mạng | lo, veth*, docker*, br-*, virbr*, cali*, flannel*, tunl*, vxlan* | Còn lại. Cấu hình net.include, net.exclude theo regex |
| Thiết bị đĩa | loop*, ram*, dm-* (tùy chọn), sr* | sd*, nvme*, vd*, xvd* |
Cấu hình cho phép quản trị viên thêm, bớt. Danh sách lọc là nguồn chủ yếu kiểm soát cardinality (xem collector 04-data-model).
Nguồn dữ liệu
Linux
| Chỉ số | Nguồn |
|---|---|
| CPU | /proc/stat (hiệu hai lần đọc), /proc/loadavg |
| RAM, swap | /proc/meminfo (MemAvailable, MemFree, Cached, Buffers, Slab, PageTables, SwapCached) |
| Áp lực (PSI) | /proc/pressure/cpu, /proc/pressure/memory, /proc/pressure/io, dòng some, giá trị avg10. Kernel không có PSI (trước 4.20, hoặc tắt) thì không có chỉ số, không báo lỗi |
| Đĩa | /proc/self/mountinfo (danh sách mount), statfs(2) (dung lượng, inode), /proc/diskstats (I/O) |
| Mạng | /proc/net/dev (hiệu hai lần đọc: byte, gói, lỗi, rơi) |
| Uptime | /proc/uptime, /proc/stat (btime) |
| Tiến trình | Đếm thư mục số trong /proc (không đọc cmdline) |
| FD | /proc/sys/fs/file-nr |
| Dịch vụ | systemd qua D-Bus hoặc systemctl is-active (GĐ 2) |
| Port | /proc/net/tcp, /proc/net/tcp6, /proc/net/udp (trạng thái LISTEN) |
Container hoặc cgroup v2 không được xử lý ở giai đoạn này (ngoài phạm vi).
Windows
Theo ADR 0007 bộ thu Windows chỉ dùng API trực tiếp, không dùng PDH nên không phụ thuộc ngôn ngữ hiển thị và không cần nhóm Performance Monitor Users.
| Chỉ số | Nguồn |
|---|---|
| CPU | GetSystemTimes (idle, kernel gồm idle, user). system = kernel trừ idle |
| Số lõi | runtime.NumCPU |
| RAM, page file | GlobalMemoryStatusEx. Page file là ước lượng: kích thước = giới hạn commit trừ RAM, mức dùng = commit vượt phần RAM đang dùng, chặn vào [0, kích thước] |
| Đĩa | GetLogicalDrives, GetDriveType (cố định, tháo rời, mạng), GetVolumeInformation (fstype), GetDiskFreeSpaceEx. Nhãn mount là C:. Ổ quang và volume gắn vào thư mục bị bỏ |
| Mạng | GetIfTable2 (bộ đếm 64 bit). Nhãn iface là tên kết nối. Bỏ loopback, tunnel, giao diện không Up, tên trùng lấy cái đầu |
| Uptime | GetTickCount64 |
| Agent | GetProcessTimes (CPU), K32GetProcessMemoryInfo (working set làm RSS) |
| Dịch vụ | Service Control Manager (OpenSCManager quyền connect, OpenService quyền query, QueryServiceStatus). Dịch vụ không tồn tại thì service_up = 0 |
| Port | GetExtendedTcpTable (listener, IPv4 và IPv6), GetExtendedUdpTable |
Chưa có trên Windows: tải trung bình (cpu_load*, load_per_core_5m), procs_total, inode, I/O đĩa, và các chỉ số bộ nhớ chi tiết của Linux. I/O đĩa và page file chính xác sẽ cần PDH (ADR 0004), làm sau.
Công thức chính
| Chỉ số | Công thức |
|---|---|
cpu_usage_percent | 100 * (1 - Δidle / Δtotal), giữ trong [0, 100]. Mặc định (include_iowait_in_usage: false) iowait được tính là idle (CPU đang chờ đĩa không bị coi là bận). Đặt true để tính iowait là bận. cpu_mode_percent{mode=iowait} luôn cho thấy phần chờ đĩa |
mem_used_bytes | MemTotal - MemAvailable |
cpu_mode_percent{mode} | 100 * Δmode / Δtotal, đủ 8 chế độ nên tổng các chế độ bằng 100 (dùng được cho biểu đồ xếp chồng). user không gồm nice, system không gồm irq, softirq |
psi_*_some_percent | Giá trị avg10 của dòng some (phần trăm thời gian ít nhất một tác vụ phải chờ tài nguyên, trung bình 10 giây) |
disk_used_percent | used / (used + available_to_nonroot) theo cách df tính (không tính phần dự trữ root) |
net_*_per_sec | Δbộ đếm / Δt (byte, gói, lỗi, rơi), Δt từ đồng hồ đơn điệu, bộ đếm quay vòng được xử lý |
load_per_core_5m | cpu_load5 / cpu_cores |
Quy tắc thêm chỉ số mới
- Thêm một dòng vào
internal/catalog/catalog.go(nhóm, đơn vị, nhãn, bộ thu, nền tảng, mặc định, mô tả vi và en). Danh sách nhãn trắng của engine tự sinh từ đó. - Thêm dòng tương ứng vào bảng nhóm ở trên (kiểm thử đồng bộ sẽ báo nếu lệch).
- Đánh giá tác động cardinality (tối đa bao nhiêu series mỗi máy) và cập nhật bảng ngân sách series.
- Cập nhật
metrics.yamlcủa collector, danh sách nhãn trắng, rollup, vàseriesallow-list bên Access Hub nếu trang Sức khỏe cần vẽ. - Thêm kiểm thử fixture cho từng nền tảng.
- Ghi nhật ký thay đổi và phiên bản catalog (
catalog_versiontrongagent_info).
Hành vi triển khai (Linux)
- Mẫu đầu tiên của mọi chỉ số dạng tốc độ (
cpu_usage_percent,cpu_mode_percent,net_*_per_sec,agent_cpu_percent) bị bỏ, chu kỳ thứ hai mới có giá trị. Bộ đếm 32 bit quay vòng được cộng bù, bộ đếm 64 bit giảm được coi là reset và bỏ mẫu. Tốc độ vượt1e12/s bị loại. procs_total,uptime_seconds,boot_time_secondsdo bộ thuuptimetạo ra, nên tắtmetrics.uptimecũng tắtprocs_total.- Kernel cũ không có
MemAvailable(trước 3.14): dùngMemFree + Buffers + Cached. - Đĩa: tối đa 40 mount (4 series mỗi mount), mount bind trùng thiết bị chỉ báo một lần. Mạng: tối đa 20 giao diện (8 series mỗi giao diện), sắp theo tên.
disk_io_*chưa có (GĐ 2). - Bộ lọc mặc định: hệ thống tệp ảo và
nfs*,cifs... bị loại, mount dưới/var/lib/docker,/var/lib/containers,/snap,/run,/sys,/proc,/devbị loại.include_fstypeskhông rỗng thay thế toàn bộ danh sách mặc định,exclude_fstypesvàexclude_mountsluôn thắng. Giao diện:net.includekhông rỗng thay thế danh sách loại mặc định,net.excludeluôn thắng. - Nhãn tĩnh (
labels) trùng nhãn dành riêng bị bỏ khi gửi, giá trị nhãn cắt còn 128 byte. - Khi vượt
limits.max_series, các chỉ số thường bị cắt từ cuối, chỉ sốagent_*được giữ chỗ riêng (tối đa 16 series).