HQbird dành cho nhà phát triển
Dành cho lập trình viên ứng dụng
Nên tối ưu truy vấn nào trước? Đoạn mã nào gây ra lỗi? Ai đang giữ bản ghi trong một xung đột? Agent thu thập câu trả lời từ trace và thống kê ngay trên máy chủ. Lập trình viên xem chúng trên trình duyệt mà không cần đăng nhập vào máy chủ.
- 1 phút tệp trace
- 3 khung giờ một ngày báo cáo hiệu năng
- theo plan nhóm truy vấn
- 15 phút tìm kiếm xung đột
- REST Local API cho script và CI
trace · process_traces · perf report
Báo cáo hiệu năng
Agent luôn giữ một phiên trace mở. Mỗi phút nó nén đầu ra vào một tệp và tính tổng cho từng truy vấn. Khi một khung giờ kết thúc, agent gộp các phút lại thành một báo cáo: các truy vấn chậm nhất và các truy vấn nặng nhất theo fetches, reads và writes. Mỗi truy vấn hiển thị số lần thực thi.
- 1Phiên tracefbtracemgr chạy liên tục; một watchdog khởi động lại phiên bị mất
- 2Tệp theo phútđầu ra trace được nén mỗi phút một lần
- 3Tổng theo phútcho từng truy vấn: số lần thực thi, thời gian, fetches, reads, writes, marks
- 4Báo cáo khung giờtrong vòng 5 phút sau khi khung giờ kết thúc; tối đa 20 truy vấn trong mỗi bảng xếp hạng
- 5✓ HQ MonitorTrang Perf Report; liên kết từ báo cáo tình trạng
Tại sao nhóm theo plan
Nếu một chương trình đưa giá trị trực tiếp vào văn bản SQL, mỗi giá trị tạo ra một văn bản mới. Trong một trường hợp thực tế, số lượng văn bản khác nhau tăng từ 204 lên 83.825 mỗi phút. Hàng nghìn truy vấn “khác nhau” thực chất là một truy vấn với một plan. Vì vậy theo mặc định, agent nhóm các truy vấn theo một khóa: 10 ký tự đầu của SQL không có chú thích, cộng với execution plan. Một truy vấn không có plan giữ nguyên toàn bộ văn bản. Bạn thay đổi chế độ trong cài đặt agent, trường “Perf group by”: theo plan hoặc theo toàn bộ văn bản SQL. Nếu theo văn bản, các tệp và báo cáo sẽ lớn hơn nhiều. Hãy chuyển chế độ trong ví dụ bên dưới và so sánh các bảng xếp hạng.
Truy vấn trong một phút
Xếp hạng theo fetches
| Bảng báo cáo | Nội dung hiển thị |
|---|---|
| Top SQL theo thời lượng | Các lần thực thi chậm nhất: thời gian và số bản ghi. |
| Top SQL theo fetches, reads, writes | Tổng cho khung giờ: số lần thực thi, thời gian, fetches, reads, writes, marks; tỷ lệ trên toàn khung giờ; trung bình và tối đa mỗi lần thực thi. |
| Tiến trình và Địa chỉ | Tải theo chương trình và theo địa chỉ client: kết nối, thời gian, số plan và truy vấn khác nhau. |
| Dòng truy vấn | SQL đầy đủ, PLAN, tham số và thống kê theo từng bảng: natural, index, update, insert, delete, backout, purge, expunge. |
| Mười bảng xếp hạng trong các tab | Thời lượng, tần suất, tổng thời gian, fetches, reads, writes, plans, tags, procedures và triggers. Với mỗi chỉ số, bạn thấy sự phân bố của các giá trị. |
| Một lần thực thi mẫu | Khi nào nó chạy, client nào và từ địa chỉ nào, trong cơ sở dữ liệu nào. Nếu lần thực thi kết thúc bằng lỗi, bạn thấy lỗi đó; mỗi truy vấn có một bộ đếm số lần thực thi thất bại. |
| Số lần thực thi theo giờ | Truy vấn đã chạy bao nhiêu lần và trong bao lâu ở mỗi giờ của khung giờ. |
| Cơ sở dữ liệu | Tổng theo cơ sở dữ liệu của máy chủ và các cơ sở dữ liệu chính của mỗi truy vấn. |
So sánh, lịch sử và báo cáo theo yêu cầu
Báo cáo khung giờ trả lời câu hỏi “hôm nay cái gì nặng”. Ba chức năng mới trả lời các câu hỏi “cái gì đã thay đổi” và “chuyện gì đã xảy ra trong giờ này”.
- So sánh hai khung giờHai báo cáo cạnh nhau: truy vấn nào trở nên chậm hơn, truy vấn nào mới xuất hiện và truy vấn nào đã biến mất.
- Lịch sử truy vấn trong 30 ngàyThời gian và số lần thực thi của một truy vấn đã thay đổi thế nào qua từng khung giờ.
- Lọc theo cơ sở dữ liệuBáo cáo chỉ cho một cơ sở dữ liệu. Một liên kết trên trang cơ sở dữ liệu dẫn đến trang báo cáo.
- Đến trace của phútTừ một truy vấn trong báo cáo đến trace của phút khi nó chạy.
- Báo cáo theo yêu cầuNút Build report… tạo báo cáo cho bất kỳ khoảng thời gian nào tối đa 24 giờ. Bộ lọc: cơ sở dữ liệu, thời lượng tối thiểu, chương trình. Agent tạo một báo cáo như vậy tại một thời điểm và giữ 20 báo cáo gần nhất.
- Tìm kiếm và tải xuốngMột trường tìm kiếm cho văn bản truy vấn. Bạn có thể tải xuống tệp nguồn của báo cáo.
- Báo cáo chưa đầy đủ được đánh dấuNếu một số tệp trace chưa đến, báo cáo được đánh dấu là chưa đầy đủ. Báo cáo chỉ giữ phần đầu của mỗi bảng xếp hạng, nên trang ghi “không có trong bảng xếp hạng”, chứ không phải “không chạy”.
- Procedures và triggersCác bảng xếp hạng này được điền khi cài đặt trace bật ghi log kết thúc procedure và trigger. Theo mặc định, việc ghi log này bị tắt.
- Từ báo cáo tình trạngNút Perf report mở đúng khung giờ. Các dòng truy vấn được đánh dấu, và dòng đầu tiên đã được mở rộng sẵn.
- Truy vấn và bảngTab Queries của thống kê gstat liên kết các truy vấn với các bảng và chỉ mục mà chúng đọc.
- Một phút trên biểu đồ cơ sở dữ liệuNhấp vào một phút sẽ hiển thị các truy vấn nặng từ trace và tất cả các kết nối của phút đó.
- Sao chép SQLCó hoặc không có tham số, thẳng vào công cụ của riêng bạn. Ở chế độ demo, các nút bị ẩn.
trace · Errors
Lỗi SQL kèm dữ liệu client
Người dùng nói “chương trình báo lỗi”. Trang Errors hiển thị từng lỗi Firebird từ trace: thời gian, kết nối, cơ sở dữ liệu, văn bản và client. Với tên chương trình, địa chỉ và hàm Firebird, bạn có thể dễ dàng tìm ra lỗi trong mã của mình.
Khối lỗi trong trace
Dòng trên trang Errors
- Cùng lỗi — một dòngMột dòng cho mỗi phút, cơ sở dữ liệu và loại lỗi, với số đếm ×N. Một gợi ý hiển thị thời gian đầu tiên và cuối cùng cùng số lượng kết nối.
- Bộ lọcInclude và Exclude theo văn bản, cơ sở dữ liệu, chương trình, địa chỉ và hàm. Nhấp vào một chương trình hoặc địa chỉ sẽ chỉ giữ lại các lỗi của nó.
- Xuất CSVTất cả các dòng với bộ lọc đã áp dụng, ở định dạng UTF-8 có BOM: Excel mở tệp thành các cột ngay lập tức.
- Nếu không có chương trìnhNhiều driver JDBC và .NET không gửi tên chương trình. Khi đó dòng client ngắn hơn.
trace_monitor_conflicts · find_deadlocks
Xung đột và deadlock
Lỗi “update conflicts with concurrent update” tự nó nói lên rất ít. Bạn cần biết giao dịch kia đã làm gì. Để làm điều này, agent giữ một phiên trace thứ hai được thiết lập cho các thay đổi dữ liệu và lỗi. Cứ 15 phút nó tìm kiếm xung đột và tạo một báo cáo.
Cách đọc báo cáo
Bên trái là danh sách các phút có xung đột. Mỗi nhóm là một giao dịch đã gây ra xung đột: số giao dịch và thời điểm xảy ra lỗi.
Cột bên trái hiển thị các lỗi: kết nối, chương trình, mã Firebird và truy vấn bị lỗi. Cột bên phải hiển thị các truy vấn thành công của giao dịch cạnh tranh: thời gian, kết nối, số giao dịch, chương trình. Mỗi truy vấn có SQL, tham số, thống kê và bảng của nó.
Địa chỉ trang giữ ngày và phút. Bạn có thể gửi liên kết cho đồng nghiệp.
| Tham số | Mặc định | Ý nghĩa |
|---|---|---|
| Tìm kiếm xung đột | mỗi 15 phút | Phút cuối cùng bị bỏ qua: trace vẫn đang ghi phút đó. |
| Độ sâu tìm kiếm | 3 giờ | Lượng lịch sử trước xung đột cần xem xét khi tìm các truy vấn của giao dịch kia. |
| Lưu giữ trace thô | 6 giờ | Các tệp thô của phiên xung đột không tích tụ trên máy chủ. Báo cáo được lưu giữ và gửi đến HQ Monitor. |
gstat · chỉ mục · metadata
Cơ sở dữ liệu thay đổi như thế nào
Mỗi ngày một lần, agent thu thập thống kê gstat đầy đủ. HQ Monitor phân tích tệp: kích thước bảng và chỉ mục, phiên bản bản ghi, BLOB, độ sâu chỉ mục. Tab “Phân tích và khuyến nghị” cho biết vấn đề là gì và cần làm gì.
| Tab | Nó mang lại gì cho nhà phát triển |
|---|---|
| Bảng | Kích thước dữ liệu, chỉ mục và BLOB, số bản ghi, phiên bản bản ghi và số phiên bản tối đa của một bản ghi. |
| Chỉ mục | Độ sâu, trang, giá trị duy nhất, bản trùng. Độ sâu 4 là hàng vàng, 5 trở lên là đỏ. |
| Truy vấn và Liên kết | Truy vấn nào đọc một bảng hoặc chỉ mục. Dữ liệu từ các báo cáo hiệu năng gần thời điểm ảnh chụp. |
| Xu hướng | So sánh 5, 10, 20 hoặc 30 ảnh chụp; ngưỡng thay đổi 10%, 2% hoặc 0,5%. Dự báo “+25%” từ ba ảnh chụp trở lên. |
| Xuất | JSON với các số đo và Excel với phân tích đầy đủ. |
- Thống kê chỉ mụcMặc định tắt; bạn bật nó trong cài đặt agent. Sau đó mỗi 6 giờ agent đếm các chỉ mục không hoạt động và các chỉ mục có độ chọn lọc kém. Một chỉ mục không được xây dựng lại sau khi khôi phục là vấn đề nghiêm trọng trong báo cáo sức khỏe.
- Dự báo tăng trưởngChip “+25%” trong bảng cơ sở dữ liệu hiển thị bảng hoặc chỉ mục tăng nhanh nhất và mở dự báo.
- Xuất schemaAgent xuất metadata của cơ sở dữ liệu bằng
isql -xvà lưu trữ theo ngày. - Theo dõi metadataMặc định tắt; bạn bật nó trong cài đặt agent. Mỗi 6 giờ agent so sánh bản xuất schema mới với bản trước đó và ghi lại thời điểm schema thay đổi.
LWM · MON$ · máy khách
Kết nối: giao dịch dài và phiên bản máy khách
Một giao dịch bị bỏ quên làm chậm toàn bộ cơ sở dữ liệu: các phiên bản bản ghi tích tụ, và việc thu gom rác dừng lại.
Mỗi phút agent ghi các bộ đếm giao dịch và dữ liệu kết nối. Trên biểu đồ cơ sở dữ liệu, Next − OAT tăng nếu một giao dịch mở quá lâu. Bảng kết nối của phút đó, sắp xếp theo Act.Tran, hiển thị chương trình, địa chỉ và tiến trình đang giữ giao dịch. Thông tin thêm về các bộ đếm có trên trang sức khỏe máy chủ.
Mỗi ngày một lần, agent đọc thư viện máy khách nào kết nối đến cơ sở dữ liệu và mỗi thư viện có bao nhiêu kết nối. Hàng “Không phát hiện. Phiên bản cũ?” thường có nghĩa là thư viện máy khách cũ.
- Số liệu MON$Mỗi giờ một lần: bộ nhớ theo chương trình, 5 kết nối dùng nhiều bộ nhớ nhất và 5 kết nối có tải cao nhất.
- Máy khách cũ không báo động giảPhát hiện “máy khách cũ” chỉ đếm các thư viện fbclient. Các driver hoạt động không cần fbclient không được tính vào đó.
- Giao dịch dài trong báo cáoBáo cáo sức khỏe đánh dấu các giao dịch dài và sự tăng của Next − OAT. Phát hiện này nêu tên người dùng, chương trình và địa chỉ và cung cấp lệnh sẵn sàng để ngắt kết nối.
Local API · Prometheus · HQbird MCP
Script, CI và trợ lý AI của bạn
Mọi thứ bạn thấy trong HQ Monitor đều có thể truy cập từ các công cụ của riêng bạn. Local API của agent chỉ lắng nghe trên loopback, và mỗi yêu cầu mang một Bearer token. Các tác vụ nặng chạy bất đồng bộ: phản hồi trả về số thao tác, và bạn đọc trạng thái theo số đó. Agent ghi mỗi yêu cầu thay đổi máy chủ, và mỗi lần từ chối 401 hoặc 403, vào nhật ký kiểm toán. Các yêu cầu đọc không được ghi vào nhật ký.
# Cổng Local API = 10000 + cổng Firebird: ở đây Firebird dùng 3055, nên là 13055 # trạng thái máy chủ: cùng ảnh chụp như trong báo cáo sức khỏe curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/status # báo cáo hiệu năng mới nhất và báo cáo xung đột mới nhất curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/perf-report/latest curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/artifacts/server/traces/deadlocks/latest # chạy sao lưu trước khi migration trong CI và chờ kết quả curl -X POST -H "Authorization: Bearer $TOKEN" -d '{"job_id":"nightly","reason":"before migration"}' \ http://127.0.0.1:13055/v1/jobs/vbackup/run curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/runs/<run_id>
| Đường dẫn | Nó mang lại gì |
|---|---|
/v1/status | Ảnh chụp trạng thái máy chủ, toàn bộ hoặc theo phần, ví dụ sao lưu. |
/v1/databases | Danh sách các cơ sở dữ liệu đang hoạt động. |
/v1/artifacts/… | Dữ liệu agent: LWM (Light-weight Monitoring) theo phút, gstat, thống kê chỉ mục, số liệu, bản xuất schema mới nhất, báo cáo trace. |
/v1/jobs/{job}/run | Chạy một tác vụ: sao lưu, khôi phục, sweep, kiểm tra cơ sở dữ liệu, tính lại thống kê chỉ mục, script SQL. Lặp lại với cùng khóa không chạy tác vụ hai lần. |
Số liệu Prometheus không đi qua Local API. Chúng có địa chỉ riêng: mặc định 127.0.0.1, cổng 25000 + cổng Firebird. Chúng có Bearer token riêng. Việc xuất mặc định tắt; bạn bật nó trong cài đặt agent. Số liệu: LWM, CPU và bộ nhớ, ổ đĩa, giới hạn OS, tệp tạm.
Trợ lý AI trong IDE
HQbird MCP kết nối Firebird và dữ liệu agent với Claude Code, Cursor, Codex và các máy khách MCP khác. Trợ lý xem các báo cáo của agent và làm việc với cơ sở dữ liệu dưới sự kiểm soát của con người: một người xác nhận các hành động nguy hiểm.
Kế hoạch và chỉ mục
Kế hoạch truy vấn và lời khuyên về chỉ mục, với việc kiểm tra lại kế hoạch sau khi chỉ mục được tạo. Kiểm tra biên dịch truy vấn trước khi nó chạy.
So sánh hai cơ sở dữ liệu
Khác biệt về schema và dữ liệu, ví dụ giữa môi trường phát triển và môi trường kiểm thử.
Lập kế hoạch, xác nhận, hoàn tác
Một migration với kế hoạch, một lần xác nhận và kế hoạch hoàn tác.
← Quay lại tổng quan HQbird 2027 · Tình trạng máy chủ chi tiết →