G-BlackHole Documentation

Appearance

Cách đọc trang này ​

Mỗi mục dưới đây đều có cùng một cấu trúc: Triệu chứng → Nguyên nhân → Giải pháp → Xác minh. Lỗi và lệnh trong trang này lấy trực tiếp từ phiên bản hiện tại của Agent, nên bạn so sánh được đúng chữ trên màn hình với chữ trong tài liệu.

📝
Trước khi bắt đầu, hãy xác định thư mục làm việc của Agent. Mọi đường dẫn log trong trang này là tương đối so với thư mục đó.

Mục lục ​

NhómVấn đề
Khởi độngAgent không chạy trên máy
Khởi độngAgent thoát ngay, không ghi log
Khởi độngKhông tìm thấy file cấu hình chính
Khởi độngStartup bị chặn vì tài nguyên
ServiceCài lại service thất bại
ServiceService đã cài nhưng không chạy
ServiceService chạy nhưng dùng nhầm file cấu hình
LogKhông tìm ra file log
LogTăng mức chi tiết của log
LogLog chiếm quá nhiều dung lượng
LogAgent thoát mà không có thông báo
Cấu hìnhThiếu địa chỉ API của Registry
Cấu hìnhTrùng section khi gộp file cấu hình
Cấu hìnhLỗi liên kết giữa các transform
Cấu hìnhKhoảng thời gian quét SCA sai định dạng
Cấu hìnhWindows Event Log không nhận channel nào
Dòng dữ liệuChạy nhưng không thu thập dữ liệu
Dòng dữ liệuPipeline im lặng khi đang tải
Dòng dữ liệuSửa cấu hình nhưng không có gì thay đổi
Dòng dữ liệuThay đổi local không được áp dụng
RegistryLệnh auth báo không có Registry
RegistryPush khi chưa xác thực
RegistryKhông truy cập được Registry
Hiệu suấtRAM hoặc CPU cao hơn mong đợi

Lỗi khởi động ​

Agent không chạy trên máy ​

Triệu chứng: Binary kết thúc ngay khi chạy, không in gì ra màn hình. Trên Linux có thể thấy Permission denied hoặc Exec format error; trên Windows cửa sổ đóng ngay.

Nguyên nhân: Dự án chỉ phát hành bản x86_64. Không có bản ARM64 và không có bản 32-bit, nên binary dựng cho sai kiến trúc sẽ không chạy được.

Giải pháp:

  1. Kiểm tra kiến trúc máy:
    bash
    uname -m    # Linux, mong đợi x86_64
    powershell
    # Windows
$env:PROCESSOR_ARCHITECTURE
  2. Tải lại binary x86_64 đúng bản release mà bạn đang dùng, xem Cài đặt.
  3. Trên Linux, đảm bảo file được phép thực thi: chmod +x blackhole-agt.

Xác minh:

bash
blackhole-agt --version

Lệnh in ra phiên bản và không báo lỗi.

Agent thoát ngay, không ghi log ​

Triệu chứng: Bạn chạy blackhole-agt với -c trỏ tới một file, chương trình thoát ngay, file log không có dòng nào, chỉ thấy trên console:

Failed to read file for hashing: blackhole-agt.yml

Nguyên nhân: File không tồn tại ở đường dẫn bạn truyền vào. Agent đọc và băm (SHA-256) file cấu hình ngay lúc khởi động để phục vụ hot-reload, và việc đọc này luôn được thực hiện kể cả khi file không có, nên tiến trình dừng trước khi kịp ghi log.

Giải pháp:

  1. Kiểm tra file có thật và đúng đường dẫn:
    bash
    ls -la ./blackhole-agt.yml
  2. Nếu bỏ qua -c, Agent tự tìm file theo thứ tự trong thư mục làm việc: blackhole-agt.yml, rồi ./config.yml, rồi ./config.yaml. Hãy chọn một trong ba tên đó hoặc chỉ định rõ bằng -c.
  3. Khởi động lại với đường dẫn đúng:
    bash
    blackhole-agt -c ./blackhole-agt.yml start

Xác minh:

bash
grep "Failed to read file for hashing" logs/default.log || echo "config OK"

Kết quả là config OK, và logs/default.log có các dòng khởi động.

Không tìm thấy file cấu hình chính ​

Triệu chứng: Bạn truyền --config-dir trỏ tới một thư mục, Agent không chạy và in ra:

No config file (config.yml or config.yaml) found in directory: ...

Nguyên nhân: Khi dùng --config-dir, Agent chỉ nhận file có tên config.yml hoặc config.yaml trong thư mục đó. blackhole-agt.yml không được tìm thấy theo cơ chế này.

Giải pháp:

  1. Đổi tên file cấu hình thành config.yml (hoặc config.yaml) trong thư mục đó.
  2. Hoặc bỏ --config-dir và chỉ định trực tiếp:
    bash
    blackhole-agt -c ./blackhole-agt.yml start
  3. Kiểm tra lại nội dung thư mục trước khi chạy:
    bash
    ls -la <thư mục cấu hình>

Xác minh:

bash
blackhole-agt --config-dir <thư mục cấu hình> start

Agent khởi động mà không còn dòng No config file ... found in directory.

Startup bị chặn vì tài nguyên ​

Triệu chứng: Agent từ chối khởi động trên máy đang tải cao và log có một trong hai dòng:

Startup blocked due to resource constraints: CPU usage (x%) is at or above threshold (80.00%)
Cannot start orchestrator: system resources are overloaded.

Nguyên nhân: Resource guard chặn khởi động khi một chỉ số đang bật (mặc định là CPU) đạt ngưỡng cho phép (80%). Đây là hành vi có chủ đích để Agent không giành tài nguyên với dịch vụ khác lúc máy đã bận.

Giải pháp:

  1. Chờ tải của máy giảm rồi khởi động lại:
    bash
    blackhole-agt -c <config> start
  2. Hoặc giảm tải trước khi khởi động: dừng bớt tiến trình nặng, tăng interval của các collector đang chạy dày đặc.
  3. Nếu môi trường của bạn vốn luôn tải cao, đổi ngưỡng trong mục resources_threshold của file cấu hình. Mục này không áp dụng khi hot-reload, nên bạn phải khởi động lại Agent sau khi sửa.

Xác minh:

bash
grep -E "Startup blocked due to resource constraints|Cannot start orchestrator" logs/default.log || echo "startup OK"

Kết quả là startup OK.

Lỗi service ​

Tên service là blackhole-agt. Trên Linux, unit nằm ở /etc/systemd/system/blackhole-agt.service.

📝
Service chạy bằng root (Linux) hoặc LocalSystem (Windows). Agent không có tính năng hạ quyền cho service account. Hạ quyền đang là mục trên lộ trình, không phải cấu hình bạn có thể bật ngay bây giờ.

Cài lại service thất bại ​

Triệu chứng: Bạn chạy lại blackhole-agt service install và nhận:

Service already exists. Use --force to overwrite.

Nguyên nhân: Service blackhole-agt đã được cài từ trước. Lệnh cài từ chối ghi đè để tránh làm mất cấu hình service đang chạy.

Giải pháp:

  1. Nếu bạn muốn ghi đè bản cũ:
    bash
    blackhole-agt service install --force
  2. Nếu không chắc, kiểm tra trạng thái trước rồi hãy cài lại:
    bash
    blackhole-agt service status
  3. Nhớ rằng service install cũng khởi động service ngay sau khi cài.

Xác minh:

bash
blackhole-agt service status

Kết quả là ✅ Service is running.

Service đã cài nhưng không chạy ​

Triệu chứng: service install báo xong nhưng service không chạy, hoặc lệnh in:

Timed out waiting for service to start. Last status: ...

Nguyên nhân: Quá trình chờ service lên vượt thời gian cho phép. Nguyên nhân thường gặp: file cấu hình không có ở chỗ service tìm, Agent bị resource guard chặn lúc khởi động, cấu hình không parse được, hoặc bạn thiếu quyền (Administrator trên Windows, root trên Linux).

Giải pháp:

  1. Hỏi thẳng service xem nó ở trạng thái nào:
    bash
    blackhole-agt service status
    Bốn kết quả có thể gặp:
    • ✅ Service is running
    • ❌ Service is not installed
    • ⏹️ Service is stopped because: ...
    • ❌ Service not found or error: ...
  2. Đặt file cấu hình vào thư mục chứa executable, nơi service tự tìm (xem mục Service chạy nhưng dùng nhầm file cấu hình).
  3. Xem log thật sự nói gì (xem mục Không tìm ra file log):
    bash
    grep -E "ERROR|WARN" <working-directory>/logs/default-error.log
  4. Cài lại với quyền đủ:
    bash
    # Linux, chạy với root
sudo blackhole-agt service install --force
    powershell
    # Windows, chạy PowerShell bằng Administrator
blackhole-agt service install --force

Xác minh:

bash
blackhole-agt service status

Kết quả là ✅ Service is running, và file log tiếp tục được ghi thêm sau vài giây.

Service chạy nhưng dùng nhầm file cấu hình ​

Triệu chứng: Bạn sửa một file cấu hình ở chỗ khác, khởi động lại service, mọi thứ vẫn như cũ. Hoặc service dùng một file cấu hình khác với file bạn thường sửa.

Nguyên nhân: --config truyền lúc service install không được lưu lại. Service được ghi nhận chính xác là <exe> --service --service-name blackhole-agt, tức là nó tự tìm cấu hình trong thư mục của chính nó theo thứ tự blackhole-agt.yml, rồi config.yml, rồi config.yaml.

Giải pháp:

  1. Tìm đường dẫn executable:
    powershell
    (Get-Process blackhole-agt).Path
    bash
    # Linux
systemctl show blackhole-agt -p ExecStart
  2. Đặt file cấu hình vào thư mục chứa executable đó, với một trong ba tên được hỗ trợ.
  3. Khởi động lại service để nó đọc lại:
    bash
    blackhole-agt service stop
blackhole-agt service start

Xác minh:

bash
ls <thư mục chứa executable>/*.yml
blackhole-agt service status

File cấu hình nằm đúng chỗ và service ở trạng thái ✅ Service is running.

Log và gỡ lỗi ​

Không tìm ra file log ​

Triệu chứng: Bạn tìm khắp đĩa mà không thấy file log nào của Agent. Chạy dưới service thì journalctl -u blackhole-agt gần như rỗng, xem Event Viewer cũng không có gì.

Nguyên nhân: Tên file thật là default.log và default-error.log, nằm trong logging.dir với giá trị mặc định ./logs, được giải tương đối so với thư mục làm việc. Khi chạy dưới Windows service hoặc systemd, thư mục làm việc là chính thư mục chứa executable. Ở chế độ service, stdout bị chặn nên file log là nơi duy nhất có đầu ra, còn journalctl chỉ nhận phần service manager ghi. Agent cũng không đăng ký nguồn Windows Event Log nào, nên không có log nào trong Event Viewer.

Giải pháp:

  1. Xác định thư mục làm việc trước khi grep:
    powershell
    # Windows: executable ở đâu thì log ở đó
$dir = Split-Path (Get-Process blackhole-agt).Path
Get-ChildItem "$dir\logs"
    bash
    # Linux dưới systemd
systemctl show blackhole-agt -p WorkingDirectory
ls -la <working-directory>/logs
    bash
    # Linux chạy foreground: thư mục làm việc là shell hiện tại
ls -la "$(pwd)/logs"
  2. Đọc log chính và log lỗi:
    powershell
    Get-Content "$dir\logs\default.log" -Tail 100
Get-Content "$dir\logs\default-error.log" -Tail 100
    bash
    tail -n 100 <working-directory>/logs/default.log
tail -n 100 <working-directory>/logs/default-error.log
  3. Nếu chạy foreground để gỡ lỗi, log cũng ra console ngay tại đó.

Xác minh:

bash
ls <working-directory>/logs

Thư mục chứa default.log và default-error.log.

Tăng mức chi tiết của log ​

Triệu chứng: Log chỉ có các dòng mức cao, bạn cần biết thêm chi tiết về collector hay sink nào đó.

Nguyên nhân: logging.level đang ở mức quá cao, hoặc bạn đang chạy dưới service nên không thêm cờ lệnh được.

Giải pháp:

  1. Khi chạy foreground, thêm -v hoặc --verbose:
    bash
    blackhole-agt -c <config> -v start
  2. Trong file cấu hình, đổi mức ghi log:
    yaml
    logging:
  dir: ./logs
  level: debug
    level nhận trace, debug, info, warn, error, và cả chỉ dẫn theo mục tiêu như collectors=trace khi bạn chỉ muốn chi tiết cho một phần.
  3. Khởi động lại Agent. logging không thuộc diện hot-reload nên sửa xong phải chạy lại.
⚠️
Không có cờ nào đổi mức log cho bạn lúc chạy. Chỉ có `-v`/`--verbose` trên lệnh và `logging.level` trong file cấu hình.

Xác minh:

bash
grep -E "DEBUG|TRACE" <working-directory>/logs/default.log | head

Có dòng DEBUG/TRACE xuất hiện.

Log chiếm quá nhiều dung lượng ​

Triệu chứng: Thư mục log ngày càng lớn, đĩa đầy.

Nguyên nhân: Xoay log luôn bật, không có cờ để tắt. Log chính giữ 5 file, mỗi file bằng max_size_mb / 5; log lỗi giữ 10 file, mỗi file bằng max_size_mb. Kích thước tổng do logging.max_size_mb quyết định.

Giải pháp:

  1. Xem kích thước hiện tại:
    bash
    du -sh <working-directory>/logs
  2. Quyết định kích thước hợp lý cho logging.max_size_mb trong file cấu hình. Đây là lever duy nhất:
    yaml
    logging:
  max_size_mb: 50
  3. Khởi động lại Agent để áp dụng (mục logging không hot-reload).

Xác minh:

bash
ls -lh <working-directory>/logs

Tổng dung lượng nằm trong mức bạn đã cấu hình và các file cũ bị thay thế theo chu kỳ.

Agent thoát mà không có thông báo ​

Triệu chứng: Tiến trình biến mất giữa chừng, log không có dòng nào mô tả lỗi, cũng không có stack trace.

Nguyên nhân: Bản build dùng cho phát hành được dựng với panic = "abort" và đã cắt ký hiệu, nên khi có panic, tiến trình kết thúc ngay mà không in backtrace.

Giải pháp:

  1. Xem dòng cuối cùng trước khi tiến trình chết:
    bash
    tail -n 50 <working-directory>/logs/default-error.log
  2. Chạy lại ở foreground với -v để bắt thông báo panic ngay trên console:
    bash
    blackhole-agt -c <config> -v start
  3. Ghi lại thời điểm thoát và nội dung console lúc đó để báo lỗi.

Xác minh:

bash
blackhole-agt -c <config> -v start; echo "exit=$?"

Nếu có panic, thông báo hiện ra trước khi tiến trình kết thúc, kèm mã thoát.

Lỗi cấu hình ​

📝
Không có lệnh `validate` hay chế độ thử cấu hình trước khi áp dụng. Cấu hình sai được phát hiện ngay lúc khởi động dưới dạng lỗi parse trong log. Để hỗ trợ gõ đúng khi soạn thảo, dùng `blackhole-agt configure schema` để sinh file `config.jsonschema`, rồi gắn schema đó vào editor của bạn.

Thiếu địa chỉ API của Registry ​

Triệu chứng: Lệnh auth từ chối và báo:

No registry configured

Nguyên nhân: File cấu hình không có mục registry:, hoặc có registry: nhưng thiếu trường api_url (khi thiếu trường này, lỗi parse là missing field `api_url` ).

Giải pháp:

  1. Thêm hoặc bổ sung mục registry trong file cấu hình:
    yaml
    registry:
  api_url: "https://<registry-host>"
  2. Khởi động lại Agent rồi xác thực lại:
    bash
    blackhole-agt auth --key <KEY>

Xác minh:

bash
blackhole-agt auth --key <KEY>

Lệnh không còn in No registry configured.

Trùng section khi gộp file cấu hình ​

Triệu chứng: Khi nạp cấu hình, Agent báo:

configuration conflict(s) detected:

kèm danh sách khóa và file xung đột.

Nguyên nhân: Cùng một section xuất hiện ở nhiều file cấu hình được gộp với nhau (thường là cấu hình .blh.yml từ Registry gộp đè lên cấu hình local), nên Agent không biết lấy bản nào.

Giải pháp:

  1. Đọc danh sách khóa và file mà Agent liệt kê trong dòng lỗi.
  2. Gộp phần trùng thành một chỗ duy nhất, hoặc bỏ phần khai báo ở file không dùng đến.
  3. Khởi động lại Agent.

Xác minh:

bash
grep "configuration conflict(s) detected" <working-directory>/logs/default-error.log || echo "no conflict"

Kết quả là no conflict và Agent khởi động bình thường.

Lỗi liên kết giữa các transform ​

Triệu chứng: Agent không khởi động và báo một trong hai lỗi:

Configuration error: Transform 'foo' inputs unknown id '...'
Cycle detected in transforms graph!

Nguyên nhân: Đồ thị transform không hợp lệ. Lỗi thứ nhất: một transform trỏ vào inputs của một id không tồn tại. Lỗi thứ hai: có vòng lặp giữa các transform, mỗi transform lại nhận đầu ra của nhau.

Giải pháp:

  1. Kiểm tra mọi giá trị inputs của các transform và chắc chắn chúng trỏ tới id của source hoặc transform có thật.
  2. Cắt vòng lặp: chọn một transform làm đầu của chuỗi và không cho transform khác trỏ ngược về nó.
  3. Khởi động lại để Agent chạy lại bước kiểm tra cấu hình.

Xác minh:

bash
grep -E "Configuration error|Cycle detected in transforms graph" <working-directory>/logs/default-error.log || echo "graph OK"

Kết quả là graph OK.

Khoảng thời gian quét SCA sai định dạng ​

Triệu chứng: Sau khi thêm source sca, Agent từ chối khởi động và log trỏ tới sources.sca.scan_interval.

Nguyên nhân: sources.sca.scan_interval (bí danh scan_interval_secs) là một chuỗi thời gian, ví dụ "86400s". Nếu bạn viết thành số không có dấu ngoặc kép, bước parse cấu hình sẽ thất bại.

Giải pháp:

  1. Mở file cấu hình, đặt giá trị có dấu ngoặc kép và đơn vị:
    yaml
    sources:
  sca:
    scan_interval: "86400s"
  2. Lưu file và khởi động lại Agent.

Xác minh:

bash
grep "scan_interval" <working-directory>/logs/default-error.log || echo "sca config OK"

Kết quả là sca config OK.

Windows Event Log không nhận channel nào ​

Triệu chứng: Agent chạy bình thường nhưng không có sự kiện nào từ Windows Event Log, hoặc cấu hình bị báo lỗi khi khởi động.

Nguyên nhân: sources.windows_event.channels là danh sách các object, không phải danh sách chuỗi. Khai báo dạng - "Application" sẽ không đúng định dạng.

Giải pháp:

  1. Sửa lại phần channels theo đúng cấu trúc object:
    yaml
    sources:
  windows_event:
    type: windows_event
    channels:
      - name: "Application"
        ids: []
      - name: "Security"
        ids: []
  2. Chạy Agent với quyền Administrator, vì đọc channel Security bắt buộc cần quyền này.
  3. Khởi động lại Agent.

Xác minh:

powershell
# Trong PowerShell
Get-WinEvent -LogName Application -MaxEvents 5

Sự kiện xuất hiện ở source và được đẩy ra sink bạn đã cấu hình, đồng thời default.log không còn báo lỗi cấu hình cho windows_event.

Dòng dữ liệu ​

Chạy nhưng không thu thập dữ liệu ​

Triệu chứng: Service ở trạng thái ✅ Service is running, tiến trình vẫn sống, nhưng không có sự kiện nào ra sink. Trong log có dòng:

Device is not active, no collectors will be started

Nguyên nhân: File cấu hình có mục registry: nên Agent chạy theo chế độ quản lý từ xa, nhưng thiết bị chưa được xác thực nên chưa active, và Agent không khởi động collector nào.

Giải pháp:

  1. Xác thực thiết bị:
    bash
    blackhole-agt auth --key <KEY>
  2. Hoặc, nếu bạn muốn chạy hoàn toàn local, bỏ mục registry: khỏi file cấu hình.
  3. Khởi động lại service để nó dựng lại pipeline:
    bash
    blackhole-agt service stop
blackhole-agt service start

Xác minh:

bash
grep "Device is not active, no collectors will be started" <working-directory>/logs/default.log || echo "collectors running"

Kết quả là collectors running, và sự kiện bắt đầu xuất hiện ở sink.

Pipeline im lặng khi đang tải ​

Triệu chứng: Dưới tải cao, Agent vẫn sống nhưng ngừng gửi dữ liệu. Trong log xuất hiện:

... has been above threshold ... - TRIGGERING PAUSE

Nguyên nhân: Resource guard tạm dừng pipeline khi chỉ số theo dõi vượt ngưỡng. Hàng đợi lúc này đã được xả, tiến trình không thoát, chỉ là ngừng nhận và gửi cho tới khi tài nguyên ổn định.

Giải pháp:

  1. Giảm tải cho máy: giảm số collector đang bật, tăng interval quét, hoặc xử lý bớt backend đang chậm.
  2. Đợi resource guard tự thả, log sẽ có dòng:
    RESUMING ORCHESTRATOR - resources have stabilized
  3. Nếu môi trường của bạn luôn ở ngưỡng đó, xem lại ngưỡng trong resources_threshold (cần khởi động lại để áp dụng).

Xác minh:

bash
grep -E "TRIGGERING PAUSE|RESUMING ORCHESTRATOR" <working-directory>/logs/default.log

Bạn thấy dòng TRIGGERING PAUSE trước và RESUMING ORCHESTRATOR sau, rồi sự kiện lại chảy.

Sửa cấu hình nhưng không có gì thay đổi ​

Triệu chứng: Bạn sửa file cấu hình, log có dòng Local config reloaded successfully, nhưng collector hay sink vẫn hành xử y như cũ.

Nguyên nhân: Hot-reload chỉ phát hiện thay đổi bằng cách băm SHA-256 mỗi hot_reload.poll_interval_ms (mặc định 5000 ms) với debounce_ms 1000 ms, rồi đọc lại cấu hình vào bộ nhớ và ghi đè file .blackhole-resolved.yaml. Nó không dựng lại collector hay sink, nên thay đổi về cấu trúc pipeline chưa bao giờ được áp dụng.

Giải pháp:

  1. Với thay đổi về pipeline (thêm/bớt source, sink, transform), khởi động lại Agent:
    bash
    blackhole-agt service stop
blackhole-agt service start
  2. Với thay đổi muốn áp dụng từ xa, đẩy cấu hình lên Registry bằng blackhole-agt configure push.
  3. Các mục không thuộc diện hot-reload: logging, hot_reload, registry, resources_threshold, channel_buffers. Sửa những mục này thì bắt buộc phải khởi động lại.
  4. Nếu lần đọc lại không parse được, Agent ghi một dòng warning và giữ nguyên cấu hình cũ. Hãy xem default-error.log nếu bạn nghi ngờ cấu hình mới bị bỏ.

Xác minh:

bash
grep "Local config reloaded successfully" <working-directory>/logs/default.log
grep "parse" <working-directory>/logs/default-error.log || echo "reload OK"

Dòng Local config reloaded successfully xuất hiện, không có warning nào, và sau khi khởi động lại thì hành vi mới có hiệu lực.

Thay đổi local không được áp dụng ​

Triệu chứng: Bạn sửa file local nhưng log báo:

Remote config is active — ignoring local config change

Hoặc sau khi đã đẩy cấu hình một lần, log cảnh báo:

Local config file ... has changed since last push. Please push config again or changes will not be applied

Nguyên nhân: Cấu hình từ Registry đang chi phối, nên mọi chỉnh sửa local bị bỏ qua. Trong trường hợp thứ hai, hash của file local đã khác với bản đã push lần trước.

Giải pháp:

  1. Nếu bạn muốn thay đổi có hiệu lực, đẩy lại cấu hình:
    bash
    blackhole-agt configure push
  2. Nếu muốn làm việc local thuần, dừng việc dùng cấu hình từ Registry và khởi động lại để Agent đọc file local.
  3. Sau khi push, đừng tiếp tục sửa file local, vì mỗi lần sửa sẽ lại tạo cảnh báo mới.

Xác minh:

bash
grep "has changed since last push" <working-directory>/logs/default-error.log || echo "config in sync"

Kết quả là config in sync, và thay đổi của bạn xuất hiện trong .blackhole-resolved.yaml.

Registry và xác thực ​

Lệnh auth báo không có Registry ​

Triệu chứng: blackhole-agt auth --key <KEY> in ra:

No registry configured

Nguyên nhân: File cấu hình không khai báo registry: kèm api_url, nên Agent không biết đích nào để xác thực.

Giải pháp:

  1. Thêm registry.api_url vào file cấu hình (xem Thiếu địa chỉ API của Registry).
  2. Khởi động lại Agent.
  3. Chạy lại lệnh auth với key bạn nhận được.

Xác minh:

bash
blackhole-agt auth --key <KEY>

Lệnh không còn in No registry configured và ghi nhận token.

Push khi chưa xác thực ​

Triệu chứng: blackhole-agt configure push từ chối với thông điệp:

device token not available, you need to authenticate first

Nguyên nhân: Thiết bị chưa có token, tức là bạn chưa chạy auth (hoặc token cũ đã bị thu hồi).

Giải pháp:

  1. Xác thực trước:
    bash
    blackhole-agt auth --key <KEY>
  2. Chạy lại lệnh push:
    bash
    blackhole-agt configure push

Xác minh:

bash
blackhole-agt configure push

Lệnh không còn in device token not available, you need to authenticate first.

Không truy cập được Registry ​

Triệu chứng: Log có dòng khi khởi động:

Failed to pull remote config: ...

Hoặc khi đang chạy, cứ mỗi khoảng pull lại thấy:

Failed to fetch remote configuration: ...

Nguyên nhân: Mạng, DNS, TLS hoặc chính Registry không tới được. Đây không là lỗi fatal: Agent cảnh báo rồi tiếp tục chạy bằng cấu hình local hiện có, và lần chạy sẽ tự thử lại theo chu kỳ.

Giải pháp:

  1. Kiểm tra mạng tới api_url khai báo trong registry:
    bash
    curl -v <api_url>
  2. Kiểm tra DNS:
    bash
    nslookup <host của api_url>
  3. Nếu Registry tạm thời chết, không cần làm gì. Agent vẫn chạy bằng cấu hình local; chỉ cần biết rằng thay đổi từ xa sẽ chưa tới được cho tới khi kết nối phục hồi.

Xác minh:

bash
curl -v <api_url>
grep -E "Failed to pull remote config|Failed to fetch remote configuration" <working-directory>/logs/default-error.log || echo "registry OK"

Kết nối thành công và log không còn dòng lỗi Registry.

Hiệu suất và tài nguyên ​

RAM hoặc CPU cao hơn mong đợi ​

Triệu chứng: Tiến trình blackhole-agt chiếm nhiều RAM hoặc CPU hơn bạn kỳ vọng.

Nguyên nhân: Agent không áp một ngưỡng RAM, disk hay CPU tối thiểu nào. Những con số sau là giá trị mặc định, không phải giới hạn cứng:

Thông sốGiá trị mặc định
Channel buffer100.000 sự kiện ở mỗi phía (collector và shipper)
Gói gửi (batch)500 message / 1000 ms / 10 MB
Persistent queueTối đa 100.000 message hoặc 256 MB
Database cache512 MB

Càng nhiều collector chạy song song và càng nhiều event/giây, mức sử dụng càng tăng. Khi vượt ngưỡng, pipeline bị tạm dừng, xem Pipeline im lặng khi đang tải.

Giải pháp:

  1. Đo thật trước khi phán đoán:
    bash
    ps -o pid,rss,vsz,cmd -p $(pgrep blackhole-agt)
    powershell
    Get-Process blackhole-agt | Select-Object WS, CPU
  2. Giảm số collector đang bật, hoặc tăng interval quét của các source nặng.
  3. Hạ logging.level về info nếu bạn đang để debug/trace lâu, vì mức chi tiết cao làm tăng đáng kể lượng ghi.
  4. Với backend chậm, kiểm tra lại cấu hình batch và hàng đợi của sink để chúng khớp với tốc độ thực tế.

Xác minh:

bash
ps -o pid,rss,vsz,cmd -p $(pgrep blackhole-agt)

Mức RSS và CPU về mức bạn mong đợi, và sự kiện vẫn chảy đều ra sink.

📝
Agent không mở cổng nghe nào và không có metrics endpoint. Muốn theo dõi tài nguyên, bạn dùng log của Agent và công cụ của hệ điều hành như trên.

Thu thập thông tin khi báo lỗi ​

Khi phải mở yêu cầu hỗ trợ, hãy chuẩn bị:

  • Phiên bản Agent: blackhole-agt --version
  • File default.log và default-error.log đầy đủ từ thời điểm bắt đầu lỗi
  • File cấu hình, đã ẩn thông tin nhạy cảm (key, token, mật khẩu)
  • Hệ điều hành và phiên bản: uname -a (Linux) hoặc systeminfo (Windows)
  • Các bước tái hiện lỗi, kèm đúng thông điệp bạn thấy trên console hoặc trong log

Xem thêm ​

Released under the MIT License.

Copyright © 2024 G-BlackHole