Giám sát trạng thái Source và Sink với mz_cli
Bước đầu tiên để kiểm soát hệ thống là xác minh trạng thái hoạt động của các luồng dữ liệu đầu vào (Source) và đầu ra (Sink) bằng công cụ dòng lệnh tích hợp sẵn.
Chạy lệnh mz source show để liệt kê toàn bộ nguồn dữ liệu đã được định nghĩa trong cluster, bao gồm cả trạng thái "Ready" hay "Error".
Command này truy vấn catalog của Materialize để trả về danh sách các source, giúp bạn nhanh chóng phát hiện nếu có source nào bị dừng hoặc bị lỗi cấu hình.
mz source show
Kết quả mong đợi: Một bảng hiển thị cột Name, Schema, Type, và Status. Các source đang hoạt động tốt sẽ có trạng thái "Ready".
Tương tự, thực hiện lệnh mz sink show để kiểm tra trạng thái của các sink đang đẩy dữ liệu ra Kafka hoặc các hệ thống đích khác.
Việc này giúp xác nhận liệu quá trình stream-out có đang diễn ra liên tục hay bị tắc nghẽn do lỗi kết nối hoặc lỗi schema.
mz sink show
Kết quả mong đợi: Bảng liệt kê các sink với trạng thái "Ready". Nếu xuất hiện trạng thái "Error", cần kiểm tra log chi tiết ở bước tiếp theo.
Để xem chi tiết lỗi của một source hoặc sink cụ thể, sử dụng lệnh mz describe [tên_object] thay vì chỉ liệt kê chung.
Lệnh này trả về toàn bộ định nghĩa SQL và các thông số cấu hình, bao gồm cả thông báo lỗi nếu object đang ở trạng thái không ổn định.
mz describe public.orders_source
Kết quả mong đợi: Hiển thị câu lệnh CREATE SOURCE/SINK đầy đủ kèm theo phần "Status" hoặc "Error message" nếu có sự cố.
Phân tích log sự kiện và lỗi của Materialize
Truy xuất log từ container Docker
Materialize lưu trữ log sự kiện quan trọng vào stdout của container, cần sử dụng Docker để trích xuất và lọc các dòng này.
Thực hiện lệnh docker logs --tail 200 materialize | grep -i "error\|warn" để xem 200 dòng log gần nhất, lọc chỉ các dòng chứa từ khóa lỗi hoặc cảnh báo.
Phương pháp này giúp loại bỏ nhiễu từ các log thông tin (info) và tập trung vào các vấn đề cần xử lý ngay lập tức như lỗi kết nối Kafka, lỗi parsing schema, hay lỗi memory.
docker logs --tail 200 materialize | grep -i "error\|warn"
Kết quả mong đợi: Danh sách các dòng log có màu đỏ hoặc cam (tùy terminal) mô tả nguyên nhân lỗi cụ thể, ví dụ: "failed to fetch schema from registry" hoặc "connection refused to kafka broker".
Sử dụng lệnh mz log để lọc sự kiện theo thời gian
Để phân tích sâu hơn, hãy sử dụng công cụ mz log (nếu đã cài đặt trong container) hoặc truy cập trực tiếp vào file log nếu đã cấu hình persistent logging.
Trong môi trường Docker, log thường nằm trong stdout, nhưng bạn có thể định tuyến chúng vào file bằng cách chỉnh sửa docker-compose.yml nếu cần lưu trữ lâu dài.
Tuy nhiên, với cấu hình mặc định, cách nhanh nhất để xem log theo thời gian thực là dùng docker logs -f materialize.
docker logs -f materialize
Kết quả mong đợi: Dòng log được cập nhật liên tục theo thời gian thực, cho phép bạn quan sát ngay lập tức khi có sự cố xảy ra trong hệ thống stream.
Để tìm các sự kiện liên quan đến một Source cụ thể, kết hợp grep với tên source.
docker logs -f materialize | grep "orders_source"
Kết quả mong đợi: Chỉ hiển thị các log có chứa tên source "orders_source", giúp cô lập vấn đề trong luồng dữ liệu đó.
Cấu hình Prometheus và Grafana để giám sát Metric
Triển khai Prometheus trong Docker Compose
Bước tiếp theo là tích hợp Prometheus để thu thập các metric hiệu năng từ Materialize thông qua endpoint /metrics.
Materialize tự động phơi bày các metric dưới dạng Prometheus format tại địa chỉ http://localhost:6878/metrics (cổng mặc định của cluster).
Chúng ta sẽ tạo file cấu hình /opt/mz-monitoring/prometheus.yml để định nghĩa job thu thập metric từ container Materialize.
cat > /opt/mz-monitoring/prometheus.yml
Kết quả mong đợi: File prometheus.yml được tạo thành công với cấu hình job kết nối đến container Materialize qua tên service trong Docker network.
Sau đó, cập nhật file docker-compose.yml để thêm service Prometheus và liên kết nó với network của Materialize.
# Thêm vào docker-compose.yml
services:
prometheus:
image: prom/prometheus:latest
ports:
- "9090:9090"
volumes:
- /opt/mz-monitoring/prometheus.yml:/etc/prometheus/prometheus.yml
command:
- '--config.file=/etc/prometheus/prometheus.yml'
depends_on:
- materialize
networks:
- mz_network
Kết quả mong đợi: Khi chạy docker-compose up -d, container Prometheus sẽ khởi động và bắt đầu scrape metric từ Materialize.
Verify kết quả bằng cách truy cập giao diện web của Prometheus tại http://localhost:9090/targets.
Trang này sẽ hiển thị trạng thái "UP" của target "materialize", xác nhận việc thu thập metric thành công.
Cấu hình Grafana để trực quan hóa dữ liệu
Sử dụng Grafana để tạo dashboard trực quan từ các metric đã thu thập được từ Prometheus.
Đầu tiên, thêm service Grafana vào docker-compose.yml và mount thư mục dữ liệu để lưu trữ dashboard.
# Thêm vào docker-compose.yml
grafana:
image: grafana/grafana:latest
ports:
- "3000:3000"
environment:
- GF_SECURITY_ADMIN_PASSWORD=admin
volumes:
- /opt/mz-monitoring/grafana:/var/lib/grafana
depends_on:
- prometheus
networks:
- mz_network
Kết quả mong đợi: Container Grafana chạy và có thể truy cập tại http://localhost:3000 với tài khoản admin/password là "admin".
Trong giao diện Grafana, vào Connections -> Data sources, chọn Prometheus và nhập URL là http://prometheus:9090.
Nhấn Save & Test để xác nhận kết nối. Nếu thành công, sẽ hiện thông báo "Data source is working".
Tiếp theo, import dashboard dành riêng cho Materialize bằng cách tải file JSON hoặc nhập Dashboard ID (nếu có trong thư viện cộng đồng) hoặc tạo dashboard thủ công.
Để tạo dashboard thủ công nhanh chóng, vào Dashboards -> New -> Add visualization, chọn Prometheus làm nguồn dữ liệu.
# Ví dụ query để vẽ biểu đồ thông lượng (Throughput)
mz_source_records_in_total
Kết quả mong đợi: Biểu đồ đường (Line graph) hiển thị số lượng record được xử lý theo thời gian thực từ source Kafka.
Thêm thêm các panel quan trọng như mz_memory_usage_bytes để theo dõi bộ nhớ và mz_source_lag_records để phát hiện độ trễ.
# Query để vẽ biểu đồ độ trễ (Lag)
mz_source_lag_records
Kết quả mong đợi: Dashboard hiển thị đầy đủ các chỉ số hiệu năng, giúp sysadmin phát hiện nhanh các điểm nghẽn (bottleneck) trong pipeline stream.
Verify toàn bộ hệ thống giám sát bằng cách truy cập http://localhost:3000/dashboards và xem biểu đồ có cập nhật số liệu theo thời gian thực hay không.
Điều hướng series:
Mục lục: Series: Triển khai Database Stream-native với Materialize trên Ubuntu 24.04
« Phần 6: Quản lý phiên bản và kiểm soát dữ liệu với Envelope
Phần 8: Troubleshooting và các mẹo nâng cao cho sản xuất »