Trước khi bắt đầu
Trang này dành cho vận hành hằng ngày: khởi động, dừng, đọc log, hot-reload, chặn tài nguyên, sao lưu và kiểm tra phiên bản. Cài đặt và cài service lần đầu xem ./install, chạy thử xem ./quickstart, tham chiếu từng trường cấu hình xem ./configuration.
Một vài điểm cần nhớ khi vận hành Agent:
- Agent không mở port nào để nghe, không có endpoint giám sát, không có giao diện người dùng. Nó chỉ gửi dữ liệu đi.
- Agent không có embedded server nên không mở port lắng nghe nào. Về transform: Agent vẫn nhận section
transforms:trong file cấu hình, nhưng đây không phải vai trò chính của Agent — tham khảo danh sách transform để biết các loại và tham số. - Metric hệ thống (CPU, memory, disk) đến từ collector
apm, đó là dữ liệu Agent gửi đi, không phải bề mặt giám sát của Agent.
Các lệnh dưới đây dùng tên binary blackhole-agt (Windows là .\blackhole-agt.exe). Khi làm việc với service, chạy terminal bằng quyền administrator/root.
| Thao tác | Lệnh |
|---|---|
| Chạy foreground | blackhole-agt start |
| Cài và khởi động service | blackhole-agt service install |
| Dừng service | blackhole-agt service stop |
| Trạng thái service | blackhole-agt service status |
| Xác thực với Registry | blackhole-agt auth --key <KEY> |
| Xem phiên bản | blackhole-agt --version |
Khởi động và dừng Agent
Chạy ở foreground
# Linux, chạy trong thư mục chứa binary
./blackhole-agt start# Windows (PowerShell)
.\blackhole-agt.exe startChỉ định file cấu hình bằng cờ toàn cục -c, đặt trước lệnh start:
# Đặt trước lệnh start, thay bằng đường dẫn thực tế
./blackhole-agt -c /path/to/blackhole-agt.yml start.\blackhole-agt.exe -c "D:\blackhole\blackhole-agt.yml" startKhông truyền -c thì Agent tìm file theo thứ tự: blackhole-agt.yml trong thư mục làm việc, rồi ./config.yml, rồi ./config.yaml.
Failed to read file for hashing: blackhole-agt.ymlMuốn log chi tiết hơn cho một lần chạy, dùng -v (tương đương --verbose), nó buộc logging.level sang debug cho lần chạy đó:
./blackhole-agt -v startXác minh:
pgrep -x blackhole-agt # Linux, in ra PID của tiến trình
tail -n 20 logs/default.log # thấy các dòng khởi động của pipelineGet-Process blackhole-agt # Windows, có dòng trả về PID
Get-Content .\logs\default.log -Tail 20 # có dòng log mớiKỳ vọng pgrep in ra một PID, Get-Process liệt kê process blackhole-agt, và logs/default.log có dòng mới.
Chạy như service
./blackhole-agt service install # cài đặt và khởi động luôn
./blackhole-agt service status.\blackhole-agt.exe service install
.\blackhole-agt.exe service statusTên service là blackhole-agt. Trên Linux, file unit là /etc/systemd/system/blackhole-agt.service với Restart=on-failure, cài service cần quyền root và systemd hoặc OpenRC.
Cài lại khi service đã tồn tại phải thêm --force, nếu không sẽ nhận:
Service already exists. Use --force to overwrite.Xác minh:
systemctl status blackhole-agtGet-Service -Name blackhole-agtKỳ vọng Active: active (running) trên Linux hoặc Status: Running trên Windows, và log ghi nhận các collector đã khởi động.
Dừng Agent
Dừng foreground bằng Ctrl+C trong terminal, hoặc gửi tín hiệu kết thúc tới PID:
kill -TERM $(pgrep -x blackhole-agt)Stop-Process -Name blackhole-agtDừng service:
./blackhole-agt service stop
# Hoặc
sudo systemctl stop blackhole-agt.\blackhole-agt.exe service stop
# Hoặc
Stop-Service -Name blackhole-agtAgent không có lệnh khởi động lại service. Muốn khởi động lại thì service stop rồi service start, hoặc systemctl restart blackhole-agt trên Linux.
Xác minh:
pgrep -x blackhole-agt || echo "da dung" # kỳ vọng in ra "da dung"
systemctl status blackhole-agt # kỳ vọng Active: inactive (dead)Get-Service -Name blackhole-agt # kỳ vọng Status: StoppedTìm cấu hình và thư mục làm việc
Gần như mọi đường dẫn runtime đều resolve tương đối so với thư mục làm việc:
- Chạy foreground: thư mục bạn đứng khi gọi lệnh.
- Chạy service: thư mục chứa binary, trên cả Windows service và systemd.
Xác định thư mục làm việc của service trên Linux:
systemctl show blackhole-agt -p WorkingDirectory --value
# Hoặc đọc trực tiếp file unit
grep WorkingDirectory /etc/systemd/system/blackhole-agt.serviceKỳ vọng in ra thư mục chứa binary, tức là nơi bạn đặt file blackhole-agt.
Trên Windows, đối chiếu với thư mục chứa blackhole-agt.exe, rồi tìm file snapshot cấu hình được ghi bên cạnh file cấu hình đang dùng:
$exe = (Get-Process blackhole-agt).Path | Split-Path
Get-ChildItem -Path $exe -Recurse -Force -Filter ".blackhole-resolved.yaml"find . -name ".blackhole-resolved.yaml"Kỳ vọng thấy một file .blackhole-resolved.yaml, thời điểm sửa đổi được cập nhật sau mỗi lần nạp lại cấu hình. File này nằm cạnh file cấu hình đang dùng, nên nó cũng là cách để biết Agent đang đọc file nào.
Các tập tin vận hành:
| Tập tin | Vị trí | Ý nghĩa |
|---|---|---|
| Cấu hình | ./blackhole-agt.yml trong thư mục làm việc, hoặc đường dẫn -c | Nguồn cấu hình chính |
| Snapshot cấu hình | .blackhole-resolved.yaml cạnh file cấu hình | Bản đã resolve, ghi lại mỗi lần nạp |
| Local database | ./blackhole-agt.db | Chứa hàng đợi tin nhắn bền vững |
| Log chính | ./logs/default.log | Log của process |
| Log lỗi | ./logs/default-error.log | Log lỗi riêng |
| JSON schema | ./config.jsonschema cạnh file cấu hình | Tạo bằng configure schema |
Xác minh:
ls -la blackhole-agt.yml blackhole-agt.db logs/Get-ChildItem -Force blackhole-agt.yml, blackhole-agt.db, logsKỳ vọng thấy đủ ba mục, nếu thiếu file cấu hình thì đó là file mà start sẽ tìm đầu tiên.
Xem log
Cấu hình log
| Trường | Mặc định | Ghi chú |
|---|---|---|
level | info | trace, debug, info, warn, error, cả per-target như collectors=trace |
dir | ./logs | 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, quyết định kích thước mỗi file rotation |
dir mặc định là ./logs, tức là trong thư mục làm việc. Agent không tự tạo một thư mục log riêng ở cấp hệ điều hành. Khi chạy service, thư mục làm việc là thư mục binary nên đường dẫn thực tế là <thư-mục-binary>\logs\default.log trên Windows và $(WorkingDirectory)/logs/default.log trên systemd. Dùng lệnh ở mục Tìm cấu hình và thư mục làm việc để xác nhận.
Xem log trực tiếp
WD=$(systemctl show blackhole-agt -p WorkingDirectory --value)
ls -lh "$WD/logs"
tail -f "$WD/logs/default.log"
grep -E "ERROR|WARN" "$WD/logs/default-error.log"$exe = (Get-Process blackhole-agt).Path | Split-Path
Get-ChildItem "$exe\logs"
Get-Content "$exe\logs\default.log" -Tail 50 -Wait
Select-String -Path "$exe\logs\default-error.log" -Pattern "ERROR|WARN"Mức log và verbose
Đổi logging.level trong file cấu hình rồi nạp lại theo hot-reload, hoặc chạy với -v để buộc debug trong lần chạy đó.
./blackhole-agt -v start
grep -c "DEBUG" logs/default.logKỳ vọng số lớn hơn 0. Với logging.level mặc định là info và không chạy -v, kết quả là 0.
Dung lượng và rotation
Rotation luôn bật, không có công tắc tắt.
| Log | Số file rotation | Dung lượng mỗi file |
|---|---|---|
default.log | 5 | max_size_mb / 5, mặc định 10 MB nên mỗi file khoảng 2 MB |
default-error.log | 10 | max_size_mb, mặc định 10 MB nên tổng có thể tới khoảng 100 MB |
Xác minh:
du -sh logs/
ls -lh logs/$exe = (Get-Process blackhole-agt).Path | Split-Path
Get-ChildItem "$exe\logs" | Measure-Object -Property Length -SumKỳ vọng tổng dung lượng nhóm default.log* dừng lại quanh mức max_size_mb, còn nhóm default-error.log* có thể lớn hơn gấp nhiều lần vì mỗi file riêng đã bằng max_size_mb.
Khi process chết bất thường
Bản release được build với panic = "abort" và không giữ ký hiệu symbol, nên khi process chết vì lỗi nội bộ sẽ không có backtrace nào được in ra. Các dòng log cuối cùng là bằng chứng duy nhất.
Get-Content "$exe\logs\default-error.log" -Tail 30tail -n 30 "$WD/logs/default-error.log"Hot-reload
Agent phát hiện thay đổi cấu hình local bằng cách poll SHA-256 mỗi hot_reload.poll_interval_ms (mặc định 5000 ms), kèm debounce_ms 1000 ms, và enabled mặc định là true. Không dùng inotify, không có tín hiệu SIGHUP.
Sửa file cấu hình local làm được gì
- Đọc lại file cấu hình vào bộ nhớ của process đang chạy.
- Ghi lại snapshot
.blackhole-resolved.yaml. - Ghi log
Local config reloaded successfully.
Nếu file mới không parse được hoặc không validate, Agent ghi warning và tiếp tục chạy với cấu hình cũ.
Các trường hợp khác
| Tình huống | Kết quả |
|---|---|
| Nguồn cấu hình đang dùng là Registry | Chỉnh local bị bỏ qua hoàn toàn, log Remote config is active — ignoring local config change |
| Update đẩy từ Registry | Thực hiện diff theo identifier, thêm, gỡ hoặc restart từng component riêng lẻ |
| File local mới sai cú pháp hoặc sai validation | Warning, giữ nguyên cấu hình cũ, process không dừng |
Không hot-reload được, bắt buộc restart
| Section | Lý do |
|---|---|
logging | Đã áp ngay khi process khởi động |
hot_reload | Chính cài đặt poll này |
registry | Kết nối với Registry dựng lúc khởi động |
resources_threshold | Ngưỡng chỉ đọc một lần lúc khởi động |
channel_buffers | Kích thước channel dựng lúc khởi động |
Những section này không được áp dụng khi đang chạy, dù chỉnh local hay nhận từ Registry.
Xác minh:
tail -f logs/default.log | grep -E "Local config reloaded|Remote config is active"Chỉnh file cấu hình (thêm một dòng chú thích là đủ) và chờ khoảng 6 giây, kỳ vọng thấy Local config reloaded successfully, đồng thời không có dòng nào báo restart component, vì pipeline vẫn giữ cấu hình cũ.
Chặn tài nguyên (resource guard)
Agent theo dõi CPU, memory và disk theo section resources_threshold:
| Thông số | Mặc định | Ghi chú |
|---|---|---|
cpu.threshold_percentage | 80.0 | Bật giám sát CPU |
memory.threshold_percentage | 80.0 | Bật giám sát memory |
disk.threshold_percentage | 101.0 | Trên 100 nên giám sát disk bị tắt mặc định |
sustained_secs | 60 | Thời gian vượt ngưỡng liên tục trước khi tạm dừng |
check_interval | 10 | Chu kỳ kiểm tra, tính bằng giây |
Một metric chỉ được bật khi threshold_percentage <= 100. Cú pháp cấu hình chi tiết xem ./configuration.
Tại thời điểm khởi động
Nếu một metric đang bật có giá trị tại hoặc trên ngưỡng, Agent từ chối khởi động:
Startup blocked due to resource constraints: CPU usage (x%) is at or above threshold (80.00%)Lỗi được đưa ra ở mức cao hơn:
Cannot start orchestrator: system resources are overloaded.Xác minh:
grep -E "Startup blocked|Cannot start orchestrator" logs/default.log
./blackhole-agt service statusKỳ vọng thấy dòng lỗi trong log và service ở trạng thái failed hoặc dừng.
Trong lúc đang chạy
Khi một metric bật vượt ngưỡng liên tục đủ sustained_secs (60 giây), guard tạm dừng pipeline: tất cả collector, transform và shipper dừng, hàng đợi bền vững được flush. Sự kiện không bị drop và process không thoát.
Khi tài nguyên ổn định trở lại
Agent khởi động lại các component và ghi log:
RESUMING ORCHESTRATOR - resources have stabilizedNhận biết pipeline đang tạm dừng
service statusvẫn báo process đang chạy, vì process không thoát.- Log không còn ghi nhận hoạt động của collector và shipper.
- Tìm dòng vượt ngưỡng và dòng resume trong log:
grep -E "Startup blocked|RESUMING ORCHESTRATOR" logs/default.logKỳ vọng sau khi tải hạ, log xuất hiện RESUMING ORCHESTRATOR - resources have stabilized và dữ liệu tiếp tục được gửi từ hàng đợi.
Kết nối Registry và xác thực
Xác thực
./blackhole-agt auth --key "<API_KEY>"Lệnh này cần section registry: với ít nhất api_url, thiếu thì báo No registry configured. Khi thành công, Agent đăng ký thiết bị rồi đẩy cấu hình local lên Registry.
Xác minh:
./blackhole-agt auth --key "<API_KEY>"
./blackhole-agt configure pushKỳ vọng không có lỗi. Nếu đẩy cấu hình trước khi xác thực, bạn sẽ nhận device token not available, you need to authenticate first.
Hành vi khi registry: đã cấu hình
| Tình huống | Hành vi | Log |
|---|---|---|
| Chưa xác thực | Process chạy nhưng không start collector nào | Device is not active, no collectors will be started |
| Registry không liên lạc được lúc khởi động | Warning, tiếp tục chạy với cấu hình local | Dòng warning kết nối |
| Sau khởi động | Retry theo interval, process không bao giờ thoát vì lỗi Registry | Dòng warning lặp lại |
Xác minh:
grep -E "Device is not active|no collectors" logs/default.logNếu gặp dòng này nghĩa là Agent đang chạy nhưng không thu thập gì, hãy chạy lại auth --key rồi restart.
Cấu hình từ xa
# Tải cấu hình từ Registry và ghi ra file để kiểm tra
./blackhole-agt configure pull --output ./pulled-config.yml
# Không truyền --output thì cấu hình được lưu nội bộ, không có file nào được ghi
./blackhole-agt configure pull
# Đẩy cấu hình local lên Registry, cần đã auth
./blackhole-agt configure push
# Tạo JSON schema cạnh file cấu hình
./blackhole-agt configure schemaXác minh:
./blackhole-agt configure pull --output ./pulled-config.yml
ls -l pulled-config.yml # file tồn tại, có dung lượngKỳ vọng lệnh in Configuration file pulled to: <đường dẫn>. Khi chạy configure pull không có --output, log là Remote configuration pulled and persisted (no output file requested). Với configure schema, kiểm tra config.jsonschema nằm cạnh file cấu hình:
ls -l config.jsonschemaBackup và khôi phục
Nội dung cần sao lưu
| Thành phần | Đường dẫn | Ghi chú |
|---|---|---|
| File cấu hình | ./blackhole-agt.yml hoặc đường dẫn -c | Bắt buộc |
| Snapshot cấu hình | .blackhole-resolved.yaml | Tự ghi lại khi chạy, optional |
| Local database | ./blackhole-agt.db | Chứa hàng đợi tin nhắn |
| JSON schema | ./config.jsonschema | Tạo lại được bằng configure schema |
Dừng service trước khi sao lưu database, vì file này đang được ghi liên tục.
Sao lưu
Chạy các lệnh trong thư mục làm việc của Agent, tức là thư mục chứa binary.
.\blackhole-agt.exe service stop
New-Item -ItemType Directory -Force -Path ".\backup" | Out-Null
Copy-Item ".\blackhole-agt.yml" ".\backup\blackhole-agt.yml.$(Get-Date -Format yyyyMMdd)"
Copy-Item ".\blackhole-agt.db" ".\backup\blackhole-agt.db" -Recurse
.\blackhole-agt.exe service start./blackhole-agt service stop
tar -czf ~/blackhole-backup-$(date +%Y%m%d).tar.gz blackhole-agt.yml blackhole-agt.db
./blackhole-agt service startXác minh:
Get-ChildItem .\backuptar -tzf ~/blackhole-backup-$(date +%Y%m%d).tar.gz
./blackhole-agt service statusKỳ vọng thấy file cấu hình và database trong bản sao lưu, service chạy lại bình thường sau khi start.
Khôi phục
Chạy trong thư mục làm việc của Agent:
./blackhole-agt service stop
tar -xzf ~/blackhole-backup-20250101.tar.gz -C .
./blackhole-agt service start.\blackhole-agt.exe service stop
Copy-Item ".\backup\blackhole-agt.yml" ".\blackhole-agt.yml" -Force
Copy-Item ".\backup\blackhole-agt.db" ".\blackhole-agt.db" -Recurse -Force
.\blackhole-agt.exe service startXác minh:
./blackhole-agt service status
tail -f logs/default.logKỳ vọng service ở trạng thái chạy và log ghi nhận các collector khởi động lại với cấu hình vừa khôi phục.
Nâng cấp binary
./blackhole-agt service stop
# sao lưu cấu hình như trên, rồi thay binary trong thư mục cài đặt
./blackhole-agt service start
./blackhole-agt --versionKỳ vọng lệnh cuối in ra phiên bản mới. Agent không có chức năng tự cập nhật từ xa, nên việc thay binary luôn làm thủ công.
Kiểm tra phiên bản
blackhole-agt --version
# Hoặc
blackhole-agt -VKỳ vọng in ra phiên bản của binary đang dùng. Đối chiếu với phiên bản trong ./install trước khi nâng cấp, và đính kèm phiên bản này khi báo lỗi theo ./troubleshooting.
blackhole-agt --helpKỳ vọng in ra danh sách lệnh đầy đủ: configure, service, auth, start. Nếu lệnh bạn định dùng không có trong danh sách, nghĩa là lệnh đó không tồn tại.
Xem thêm
- ./overview - Tổng quan Agent
- ./quickstart - Chạy Agent lần đầu
- ./install - Cài đặt và cài service
- ./configuration - Tham chiếu cấu hình
- ./troubleshooting - Khắc phục sự cố
- /components/forwarder/overview - Forwarder là gì