HeraclesQL: A Python DSL for Writing Alerts

Hudson River Trading · 2025 · 3. Quy mô lớn · Độ khó: Trung bình — bài gốc

Bối cảnh

• Đội Systems Dev của HRT làm công cụ cho các kỹ sư hệ thống, mạng, datacenter. VictoriaMetrics là phần quan trọng của stack giám sát (2025); hàng nghìn alert viết bằng MetricsQL (gần như PromQL) trên hàng chục team.
• Ba vấn đề khi số team tăng: trùng lặp (không chia sẻ được gì giữa các alert; hai team cùng alert dung lượng đĩa với ngưỡng khác phải viết gần như hai alert giống nhau; templating bằng text dễ sai), khó diễn đạt khi query phức tạp, và bẫy ngầm.

Thay đổi chính

• HeraclesQL: một DSL Python sinh MetricsQL, vai trò giống SQLAlchemy với SQL; mở mã nguồn (MIT). Cú pháp gần MetricsQL, kiểu tĩnh kiểm bằng MyPy/Pyright (ví dụ truyền instant vector vào rate bị báo lỗi trong editor). Biểu diễn nội bộ là AST; sinh file rule gốc của VictoriaMetrics.
• Chống trùng lặp: hàm có tham số thay cho copy-paste; một hàm alert gắn nhiều decorator để đăng ký nhiều biến thể; cú pháp extends để team khác mở rộng; recording rule khai báo gọn bằng rules.record.
• Meta-alert từ AST: bẫy hay gặp nhất là series không tồn tại (metric đăng ký động, ví dụ job chưa chạy lần nào) nên alert không bao giờ bắn. Context AlertForMissingData duyệt AST và tự sinh alert absent() cho từng selector. Theo HRT, trước đó alert hiếm khi xử lý đúng việc thiếu series. Phép + giữa hai vector vừa là cộng vừa là lọc theo nhãn; annotation no_cardinality_change sinh meta-alert khi số series thay đổi ngoài ý muốn.
• Ví dụ Jenkins: plugin xuất hai metric kết quả build với mã khác nhau (bản ordinal lấy 0 là thành công); team dùng lẫn lộn, quên kiểm absent, kiểm sai mã. Gói thành một enum Python và một hàm alert dùng chung.
• Công cụ phát triển: Delos (nhúng UI VictoriaMetrics, nạp query từ code HeraclesQL để lặp nhanh), Hermes (test alert bằng code trên VictoriaMetrics thật với dữ liệu tổng hợp).

Vì sao

• Alert là code: dùng được biến, hàm, kiểu, test; lỗi bắt được trước khi lên production. HRT định thay toàn bộ alert MetricsQL bằng HeraclesQL.

Bài học cho SWE

• Khi số alert tới hàng nghìn, cấu hình dạng text phẳng không scale; cần ngôn ngữ thật với kiểu và tái sử dụng.
• Alert "không bắn vì không có dữ liệu" là lỗi im lặng phổ biến; sinh kiểm tra absence tự động thay vì trông vào kỷ luật.
• Đi kèm DSL là công cụ lặp nhanh và test, nếu không người dùng sẽ quay lại viết tay.

Liên quan

• Hudson River Trading 2021 · Zerodha 2020 (DSL nghiệp vụ → ngôn ngữ thật) · Zerodha 2020 (cũng dùng VictoriaMetrics)
• Observability và monitoring