Thu thập thông tin

”Thông tin cần thiết” Khi báo lỗi, vui lòng cung cấp:
  • Phiên bản Agent: blackhole-agt --version
  • File log đầy đủ
  • Cấu hình hiện tại (ẩn thông tin nhạy cảm)
  • Hệ điều hành và phiên bản
  • Mô tả chi tiết các bước dẫn đến lỗi

Lỗi khởi động

Agent không khởi động được

Triệu chứngNguyên nhân khả dĩCách khắc phục
Service không startThiếu quyền hoặc file không tồn tạiKiểm tra quyền và đường dẫn file
”Access Denied”Không có quyền administrator/rootChạy với quyền admin/root
”File not found”Binary không tồn tại hoặc sai đường dẫnKiểm tra đường dẫn cài đặt
”Port already in use”Port bị chiếm dụngThay đổi port hoặc dừng service khác

Khắc phục chi tiết

Windows:
# Kiểm tra quyền
Get-Acl "C:\Program Files\BlackHole Agent" | Format-List

# Kiểm tra file tồn tại
Test-Path "C:\Program Files\BlackHole Agent\blackhole-agt.exe"

# Kiểm tra port
netstat -an | findstr :1883

# Chạy với quyền admin
Start-Process PowerShell -Verb RunAs
Linux:
# Kiểm tra quyền
ls -la /opt/blackhole-agent/blackhole-agt

# Kiểm tra file tồn tại
test -f /opt/blackhole-agent/blackhole-agt

# Kiểm tra port
sudo netstat -tlnp | grep :1883

# Chạy với quyền root
sudo systemctl start blackhole-agent

Lỗi cấu hình

Triệu chứngNguyên nhân khả dĩCách khắc phục
”Invalid YAML”Cú pháp YAML saiValidate cấu hình với YAML parser
”Missing required field”Thiếu trường bắt buộcKiểm tra cấu hình mẫu
”Invalid URL”URL không hợp lệKiểm tra format URL
”Authentication failed”API key sai hoặc hết hạnKiểm tra API key

Khắc phục chi tiết

# Kiểm tra cú pháp YAML
python -c "import yaml; yaml.safe_load(open('config.yml'))"

# Tạo cấu hình mới
blackhole-agt configure --path config-new.yml default

# So sánh với cấu hình mẫu
diff config.yml config-new.yml

Lỗi kết nối

Registry Connection Issues

Triệu chứngNguyên nhân khả dĩCách khắc phục
”Connection refused”Registry server downKiểm tra trạng thái server
”SSL/TLS error”Certificate không hợp lệKiểm tra certificate
”Timeout”Network latency caoTăng timeout settings
”Authentication failed”API key saiKiểm tra API key

Khắc phục chi tiết

# Test kết nối đến Registry
curl -k https://blackhole.glabs.one/health

# Test với verbose
curl -v -k https://blackhole.glabs.one/health

# Kiểm tra DNS
nslookup blackhole.glabs.one

# Test với telnet
telnet blackhole.glabs.one 443

MQTT Connection Issues

Triệu chứngNguyên nhân khả dĩCách khắc phục
”Connection lost”Network không ổn địnhKiểm tra kết nối mạng
”Authentication failed”Username/password saiKiểm tra credentials
”Client ID conflict”Client ID bị trùngThay đổi client ID
”Topic not allowed”Không có quyền publishKiểm tra ACL

Khắc phục chi tiết

# Test MQTT connection
mosquitto_pub -h blackhole.glabs.one -p 8883 -t "test" -m "hello" --cafile ca.crt

# Test với authentication
mosquitto_pub -h blackhole.glabs.one -p 8883 -t "test" -m "hello" -u "username" -P "password"

# Kiểm tra MQTT broker status
mosquitto_sub -h blackhole.glabs.one -p 8883 -t "#" -v

Kafka Connection Issues

Triệu chứngNguyên nhân khả dĩCách khắc phục
”Broker not available”Kafka cluster downKiểm tra trạng thái cluster
”Topic not found”Topic chưa được tạoTạo topic trước
”SASL authentication failed”Credentials saiKiểm tra SASL config
”Serialization error”Message format saiKiểm tra serializer config

Khắc phục chi tiết

# Test Kafka connection
kafka-console-producer.sh --bootstrap-server kafka.company.com:9092 --topic test

# List topics
kafka-topics.sh --bootstrap-server kafka.company.com:9092 --list

# Test với SASL
kafka-console-producer.sh --bootstrap-server kafka.company.com:9092 --topic test --producer-property security.protocol=SASL_SSL --producer-property sasl.mechanism=PLAIN

Lỗi thu thập dữ liệu

APM Collector Issues

Triệu chứngNguyên nhân khả dĩCách khắc phục
”No metrics collected”Collector không startKiểm tra collector status
”High CPU usage”Interval quá thấpTăng collection interval
”Memory leak”Collector không cleanupRestart collector
”Permission denied”Không có quyền đọc system infoChạy với quyền admin

Khắc phục chi tiết

# Kiểm tra collector status
grep "APM" /var/log/blackhole-agent/agent.log

# Kiểm tra system metrics
top -p $(pgrep blackhole-agt)

# Test system info access
cat /proc/meminfo
cat /proc/cpuinfo

File Watcher Issues

Triệu chứngNguyên nhân khả dĩCách khắc phục
”File not found”File không tồn tạiKiểm tra đường dẫn file
”Permission denied”Không có quyền đọc fileKiểm tra file permissions
”Log rotation not detected”File rotation không được phát hiệnKiểm tra file watcher config
”High memory usage”Quá nhiều file được watchGiảm số lượng file patterns

Khắc phục chi tiết

# Kiểm tra file permissions
ls -la /var/log/auth.log

# Test file access
cat /var/log/auth.log

# Kiểm tra file watcher
grep "FileWatcher" /var/log/blackhole-agent/agent.log

# Test file rotation
mv /var/log/auth.log /var/log/auth.log.old
touch /var/log/auth.log

Windows Event Log Issues

Triệu chứngNguyên nhân khả dĩCách khắc phục
”Event log access denied”Không có quyền đọc event logChạy với quyền admin
”Channel not found”Event channel không tồn tạiKiểm tra channel name
”Event ID not found”Event ID không hợp lệKiểm tra event ID list
”High CPU usage”Quá nhiều eventsFilter event IDs

Khắc phục chi tiết

# Kiểm tra event log permissions
Get-EventLog -List

# Test event log access
Get-EventLog -LogName Application -Newest 5

# Kiểm tra event channels
Get-WinEvent -ListLog * | Where-Object {$_.LogName -like "*Application*"}

# Test specific event ID
Get-WinEvent -FilterHashtable @{LogName='Application'; ID=1000}

Lỗi hiệu suất

High Memory Usage

Triệu chứngNguyên nhân khả dĩCách khắc phục
Memory usage > 1GBQueue quá lớnGiảm queue size
Memory leakCollector không cleanupRestart Agent
Too many filesQuá nhiều file được watchGiảm file patterns
Large log filesLog files quá lớnEnable log rotation

Khắc phục chi tiết

# Kiểm tra memory usage
ps -o pid,ppid,cmd,%mem,%cpu --sort=-%mem | grep blackhole

# Kiểm tra queue size
grep "queue_size" /var/log/blackhole-agent/agent.log

# Giảm queue size trong config
inventory:
  max_messages: 50000  # Giảm từ 100000
  max_bytes: 134217728  # Giảm từ 256MB

High CPU Usage

Triệu chứngNguyên nhân khả dĩCách khắc phục
CPU usage > 50%Collection interval quá thấpTăng interval
Too many collectorsQuá nhiều collector chạyGiảm số collector
Inefficient patternsFile patterns không tối ưuTối ưu patterns
Network issuesRetry logic chạy liên tụcKiểm tra network

Khắc phục chi tiết

# Kiểm tra CPU usage
top -p $(pgrep blackhole-agt)

# Kiểm tra collection interval
grep "interval" /etc/blackhole-agent/config.yml

# Tăng interval
sources:
  apm_system:
    interval: 60  # Tăng từ 30 giây

Slow Data Processing

Triệu chứngNguyên nhân khả dĩCách khắc phục
Queue backlogSink không kịp xử lýTăng sink throughput
Network latencyKết nối mạng chậmTối ưu network
Large messagesMessage size quá lớnGiảm message size
Serialization overheadSerialization chậmTối ưu serializer

Khắc phục chi tiết

# Kiểm tra queue backlog
grep "backlog" /var/log/blackhole-agent/agent.log

# Tăng batch size
sinks:
  mqtt_sink:
    rate_limit:
      batch_size: 1000  # Tăng từ 100
      batch_interval: 500  # Giảm từ 1000

Lỗi bảo mật

Authentication Issues

Triệu chứngNguyên nhân khả dĩCách khắc phục
”Invalid API key”API key sai hoặc hết hạnKiểm tra API key
”Token expired”Device token hết hạnRe-authenticate
”SSL certificate error”Certificate không hợp lệCập nhật certificate
”Proxy authentication failed”Proxy credentials saiKiểm tra proxy config

Khắc phục chi tiết

# Re-authenticate
blackhole-agt auth --key "new-api-key"

# Kiểm tra certificate
openssl s_client -connect blackhole.glabs.one:8883 -servername blackhole.glabs.one

# Test proxy
curl --proxy http://proxy.company.com:8080 https://blackhole.glabs.one/health

Permission Issues

Triệu chứngNguyên nhân khả dĩCách khắc phục
”Permission denied”Không có quyền truy cậpKiểm tra permissions
”File access denied”Không có quyền đọc fileCấp quyền đọc
”Service account issues”Service account không đúngKiểm tra service account
”Directory access denied”Không có quyền truy cập thư mụcCấp quyền thư mục

Khắc phục chi tiết

# Kiểm tra permissions
ls -la /opt/blackhole-agent/
ls -la /etc/blackhole-agent/
ls -la /var/log/blackhole-agent/

# Cấp quyền
sudo chown -R blackhole-agent:blackhole-agent /opt/blackhole-agent
sudo chmod 750 /opt/blackhole-agent

Debug Commands

Verbose Logging

# Chạy với debug logging
blackhole-agt start --verbose --log-level debug

# Windows
.\blackhole-agt.exe start --verbose --log-level debug

Connection Testing

# Test Registry connection
curl -k https://blackhole.glabs.one/health

# Test MQTT connection
mosquitto_pub -h blackhole.glabs.one -p 8883 -t "test" -m "hello"

# Test Kafka connection
kafka-console-producer.sh --bootstrap-server kafka.company.com:9092 --topic test

System Information

# System info
uname -a
cat /etc/os-release

# Agent version
blackhole-agt --version

# Process info
ps aux | grep blackhole-agt

# Network info
netstat -tlnp | grep blackhole

Log Analysis

Common Log Patterns

# Lỗi kết nối
grep "connection" /var/log/blackhole-agent/agent.log

# Lỗi authentication
grep "auth" /var/log/blackhole-agent/agent.log

# Lỗi file access
grep "permission" /var/log/blackhole-agent/agent.log

# Performance issues
grep "slow" /var/log/blackhole-agent/agent.log

Log Levels

  • ERROR: Lỗi nghiêm trọng cần xử lý ngay
  • WARN: Cảnh báo, có thể ảnh hưởng hiệu suất
  • INFO: Thông tin hoạt động bình thường
  • DEBUG: Thông tin chi tiết để debug

Escalation

Khi nào cần hỗ trợ

  • Lỗi không có trong danh sách này
  • Đã thử tất cả giải pháp nhưng vẫn lỗi
  • Lỗi ảnh hưởng đến production
  • Cần hỗ trợ cấu hình phức tạp

Thông tin cần cung cấp

  1. Phiên bản Agent: blackhole-agt --version
  2. Hệ điều hành: uname -a (Linux) hoặc systeminfo (Windows)
  3. File log đầy đủ: Từ thời điểm bắt đầu lỗi
  4. Cấu hình: File config (ẩn thông tin nhạy cảm)
  5. Mô tả chi tiết: Các bước dẫn đến lỗi
  6. Screenshot: Nếu có lỗi hiển thị trên UI