Khắc phục sự cố BQL Server

Trang này liệt kê các sự cố thường gặp khi triển khai và vận hành BQL Server, kèm cách xác định và khắc phục.

Checklist khi server không hoạt động

• [ ] Container/process đang chạy (docker ps hoặc systemctl status bql-server)
• [ ] Port 9090 đã được publish/mở firewall
• [ ] OpenSearch truy cập được từ phía BQL Server (không phải từ máy dev)
• [ ] Client gửi đúng opensearch_url (dùng tên service trong Docker network, không phải localhost)
• [ ] Truy vấn có mệnh đề from <index>
• [ ] Truy vấn có time range (timerange hoặc earliest_unix/latest_unix)
• [ ] Xem log với RUST_LOG=debug

Lỗi thường gặp

connection refused khi grpcurl

Triệu chứng:

Failed to dial target host "localhost:9090": connection refused

Nguyên nhân: Server chưa chạy, hoặc port không được publish ra ngoài container.

Khắc phục:

# Kiểm tra container
docker ps | grep bql-server

# Kiểm tra port mapping
docker port bql-server

# Xem log
docker logs -f bql-server

Nếu chạy bằng Docker, đảm bảo có -p 9090:9090 (hoặc ports: ["9090:9090"] trong compose).

Code = InvalidArgument — thiếu mệnh đề from

Triệu chứng:

ERROR: Code = InvalidArgument desc = Query must include a 'from' clause to specify the data source

Nguyên nhân: BQL Server yêu cầu truy vấn xác định rõ nguồn dữ liệu — không có from, engine không biết truy vấn index nào.

Khắc phục:

- "bql": "search status=200 | head 10"
+ "bql": "from logs-* search status=200 | head 10"

Code = FailedPrecondition — thiếu time range

Triệu chứng:

ERROR: Code = FailedPrecondition desc = Query requires a time range. Add a timerange command to your BQL query...

Nguyên nhân: Engine chặn full scan — truy vấn phải có time range (mệnh đề timerange trong BQL, hoặc earliest_unix/latest_unix trong request).

Khắc phục: Thêm time range vào request:

{
  "bql": "from logs-* | head 10",
  "opensearch_url": "http://localhost:9200",
  "earliest_unix": -3600,
  "latest_unix": 0
}

📝

`earliest_unix`/`latest_unix` dùng số âm = tương đối so với hiện tại (`-3600` = 1 giờ trước), `0` = hiện tại. Server tự inject `timerange` vào pipeline nếu truy vấn chưa có.

Code = FailedPrecondition — index không được phép

Triệu chứng:

ERROR: Code = FailedPrecondition desc = Access denied: index 'logs-*' is not in the allowed indexes list

Nguyên nhân: Index trong from không khớp với bất kỳ IndexInfo nào trong allowed_indexes.

Khắc phục: Kiểm tra allowed_indexes trong request:

{
  "bql": "from logs-* | head 10",
  "opensearch_url": "http://localhost:9200",
  "earliest_unix": -3600,
  "latest_unix": 0,
  "allowed_indexes": [
    {"name": "logs-*", "prefix": "tenant_a"}
  ]
}

Lưu ý: với prefix: "tenant_a", index thực tế được truy vấn là tenant_a_logs-*. Nếu không có prefix nào, dùng "".

Code = Internal — OpenSearch execution failed

Triệu chứng:

ERROR: Code = Internal desc = OpenSearch execution failed: <detail>. Check that OpenSearch is reachable and the index exists

Nguyên nhân: OpenSearch không truy cập được từ BQL Server, index không tồn tại, hoặc credential sai.

Khắc phục:

1. Kiểm tra từ trong container (không phải máy host):

docker exec bql-server wget -qO- http://opensearch:9200

2. Nếu dùng Docker Compose, dùng tên service thay vì localhost:

{
  "opensearch_url": "http://opensearch:9200"
}

3. Kiểm tra index tồn tại:

curl "http://localhost:9200/_cat/indices?v" -u 'admin:admin'

Timeout — kết quả PARTIAL

Triệu chứng: Stream kết thúc với:

{
  "completion": {
    "kind": "PARTIAL",
    "partial_reason": "TIMEOUT"
  }
}

Nguyên nhân: Truy vấn chạy quá timeout_ms đã đặt.

Khắc phục:

• Tăng timeout_ms trong request nếu truy vấn hợp lệ.
• Thắt chặt truy vấn: hẹp time range hơn, thêm filter, giới hạn head.

Server dừng giữa chừng không rõ lý do

Kiểm tra:

# Docker
docker logs --tail 100 bql-server

# systemd
journalctl -u bql-server -f

Lưu ý: PIT cache nằm trong bộ nhớ — restart server làm mất cache, các request phân trang search_after cũ sẽ cần bắt đầu lại từ trang đầu.

Liên kết liên quan

• Tổng quan BQL Server
• Triển khai BQL Server
• Cấu hình BQL Server
• Vận hành BQL Server
• Thông báo lỗi BQL