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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| Service không start | Thiếu quyền hoặc file không tồn tại | Kiểm tra quyền và đường dẫn file |
| ”Access Denied” | Không có quyền administrator/root | Chạy với quyền admin/root |
| ”File not found” | Binary không tồn tại hoặc sai đường dẫn | Kiểm tra đường dẫn cài đặt |
| ”Port already in use” | Port bị chiếm dụng | Thay đổ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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| ”Invalid YAML” | Cú pháp YAML sai | Validate cấu hình với YAML parser |
| ”Missing required field” | Thiếu trường bắt buộc | Kiể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ạn | Kiể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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| ”Connection refused” | Registry server down | Kiểm tra trạng thái server |
| ”SSL/TLS error” | Certificate không hợp lệ | Kiểm tra certificate |
| ”Timeout” | Network latency cao | Tăng timeout settings |
| ”Authentication failed” | API key sai | Kiể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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| ”Connection lost” | Network không ổn định | Kiểm tra kết nối mạng |
| ”Authentication failed” | Username/password sai | Kiểm tra credentials |
| ”Client ID conflict” | Client ID bị trùng | Thay đổi client ID |
| ”Topic not allowed” | Không có quyền publish | Kiể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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| ”Broker not available” | Kafka cluster down | Kiểm tra trạng thái cluster |
| ”Topic not found” | Topic chưa được tạo | Tạo topic trước |
| ”SASL authentication failed” | Credentials sai | Kiểm tra SASL config |
| ”Serialization error” | Message format sai | Kiể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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| ”No metrics collected” | Collector không start | Kiểm tra collector status |
| ”High CPU usage” | Interval quá thấp | Tăng collection interval |
| ”Memory leak” | Collector không cleanup | Restart collector |
| ”Permission denied” | Không có quyền đọc system info | Chạ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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| ”File not found” | File không tồn tại | Kiểm tra đường dẫn file |
| ”Permission denied” | Không có quyền đọc file | Kiểm tra file permissions |
| ”Log rotation not detected” | File rotation không được phát hiện | Kiểm tra file watcher config |
| ”High memory usage” | Quá nhiều file được watch | Giả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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| ”Event log access denied” | Không có quyền đọc event log | Chạy với quyền admin |
| ”Channel not found” | Event channel không tồn tại | Kiể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 events | Filter 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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| Memory usage > 1GB | Queue quá lớn | Giảm queue size |
| Memory leak | Collector không cleanup | Restart Agent |
| Too many files | Quá nhiều file được watch | Giảm file patterns |
| Large log files | Log files quá lớn | Enable 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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| CPU usage > 50% | Collection interval quá thấp | Tăng interval |
| Too many collectors | Quá nhiều collector chạy | Giảm số collector |
| Inefficient patterns | File patterns không tối ưu | Tối ưu patterns |
| Network issues | Retry logic chạy liên tục | Kiể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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| Queue backlog | Sink không kịp xử lý | Tăng sink throughput |
| Network latency | Kết nối mạng chậm | Tối ưu network |
| Large messages | Message size quá lớn | Giảm message size |
| Serialization overhead | Serialization chậm | Tố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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| ”Invalid API key” | API key sai hoặc hết hạn | Kiểm tra API key |
| ”Token expired” | Device token hết hạn | Re-authenticate |
| ”SSL certificate error” | Certificate không hợp lệ | Cập nhật certificate |
| ”Proxy authentication failed” | Proxy credentials sai | Kiể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ứng | Nguyên nhân khả dĩ | Cách khắc phục |
|---|
| ”Permission denied” | Không có quyền truy cập | Kiểm tra permissions |
| ”File access denied” | Không có quyền đọc file | Cấp quyền đọc |
| ”Service account issues” | Service account không đúng | Kiểm tra service account |
| ”Directory access denied” | Không có quyền truy cập thư mục | Cấ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 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
- Phiên bản Agent:
blackhole-agt --version
- Hệ điều hành:
uname -a (Linux) hoặc systeminfo (Windows)
- File log đầy đủ: Từ thời điểm bắt đầu lỗi
- Cấu hình: File config (ẩn thông tin nhạy cảm)
- Mô tả chi tiết: Các bước dẫn đến lỗi
- Screenshot: Nếu có lỗi hiển thị trên UI