Giới thiệu
BlackHole Agent (binary blackhole-agt) là thành phần thu thập dữ liệu chạy trên máy chủ và endpoint. Nó đọc log từ các nguồn trên máy rồi gửi (ship) về backend như gRPC, Kafka, MQTT hoặc OpenSearch.
Agent chỉ có vai trò gửi đi. Không có embedded server và không mở port lắng nghe nào: Agent kết nối ra ngoài tới sink đã cấu hình, không chờ kết nối vào. Muốn gom dữ liệu từ nhiều máy rồi xử lý trung gian, đặt một Forwarder phía trước Agent.
Agent chạy độc lập với config local, hoặc nhận config từ Registry khi đã xác thực.
Tính năng chính
Thu thập dữ liệu
| Collector | Mô tả |
|---|---|
file | Đọc log từ file, tự xử lý log rotation của hệ thống |
apm | System metrics: CPU, memory, disk, network, process (chỉ có ở Agent) |
sca | Đánh giá cấu hình bảo mật theo schedule |
windows_event | Windows Event Log channels (chỉ Windows) |
Tích hợp
| Sink | Mô tả |
|---|---|
grpc | Gửi dữ liệu qua gRPC |
kafka | Gửi tới Kafka topic |
mqtt | Publish tới MQTT broker |
blackhole | Gửi indexing tới OpenSearch / BlackHole |
file | Ghi ra file (gỡ rối hoặc lưu local) |
alert | Kích hoạt cảnh báo |
- Registry: nhận cấu hình từ server trung tâm (tùy chọn, cần
auth --key) - TLS/SSL: mã hóa mọi kết nối ra ngoài, hỗ trợ HTTP/HTTPS proxy
- Service: chạy như Windows Service hoặc systemd service
Vận hành
- Hot-reload: đọc lại file cấu hình khi đang chạy. Lưu ý phạm vi của hot-reload có giới hạn, xem ./operation.
- Persistent queue: message chưa gửi được nằm trong database local, gửi lại ở lần khởi động sau.
- Resource guard: theo dõi CPU/memory/disk, tạm dừng pipeline khi quá tải thay vì làm sập process.
- Log rotation: luôn bật, không có công tắc tắt.
Nền tảng hỗ trợ
| Nền tảng | Chi tiết |
|---|---|
| Windows | Windows 10/11, Windows Server 2016 trở về sau. Kiến trúc x86_64. |
| Linux | Ubuntu, Debian, CentOS, RHEL, Alpine. Kiến trúc x86_64. Alpine dùng musl libc. |
Yêu cầu hệ thống
| Hạng mục | Giá trị mặc định | Ý nghĩa |
|---|---|---|
| Channel buffer | 100.000 event mỗi bên | Bộ đệm giữa các chặng của pipeline |
| Batch gửi đi | 500 message / 1000 ms / 10 MB | Ngưỡng gộp lô của sink |
| Persistent queue | 100.000 message hoặc 256 MB | Giới hạn queue local trước khi chặn ghi |
| Database cache | 512 MB | Cache của database local blackhole-agt.db |
| Log | max_size_mb 10 MB | Dung lượng log, xem ./operation |
Càng nhiều collector chạy song song và càng nhiều event/giây, càng cần CPU và RAM lớn hơn. Khi vượt ngưỡng resource guard, pipeline bị tạm dừng, xem ./operation.
Bảo mật
- Xác thực với Registry bằng API key (
auth --key), sau đó dùng device token - TLS/SSL cho các kết nối backend
- Hỗ trợ HTTP/HTTPS proxy
- Cấu hình (
blackhole-agt.yml) chứa credential, cần giới hạn quyền đọc file
Logging
| Trường | Mặc định | Mô tả |
|---|---|---|
level | info | trace, debug, info, warn, error, hỗ trợ cả per-target như collectors=trace |
dir | ./logs | Thư mục log, resolve tương đối so với thư mục làm việc |
file | default.log | Log chính |
error_file | default-error.log | Log lỗi |
max_size_mb | 10 | Tổng dung lượng log, quyết định kích thước mỗi file rotation |
File log thực tế là logs/default.log và logs/default-error.log (relative tới thư mục làm việc của process). Rotation luôn bật. Ở chế độ service, stdout bị tắt nên file log là nơi duy nhất có output.
Chi tiết cách tìm thư mục log và đọc log, xem ./operation.
Xem thêm
- ./quickstart - Chạy Agent lần đầu
- ./install - Cài đặt và cài service
- ./configuration - Tham chiếu cấu hình
- ./operation - Vận hành hằng ngày
- ./troubleshooting - Khắc phục sự cố
- /components/forwarder/overview - Forwarder là gì