HQbird geliştiriciler için
Uygulama geliştiricileri için
Önce hangi sorgu optimize edilmeli? Hatayı hangi kod aldı? Bir çakışmada kaydı kim tutuyor? Ajan, yanıtları sunucunun kendisindeki trace ve istatistiklerden toplar. Geliştirici bunları bir tarayıcıda görür ve sunucuya giriş yapmaz.
- 1 dk trace dosyaları
- Günde 3 pencere performans raporu
- Plana göre sorgu gruplama
- 15 dk çakışma araması
- REST betikler ve CI için yerel API
trace · process_traces · perf report
Performans raporu
Ajan sürekli açık bir trace oturumu tutar. Her dakika çıktıyı bir dosyaya sıkıştırır ve her sorgu için toplamları hesaplar. Bir pencere sona erdiğinde ajan dakikaları bir raporda birleştirir: en yavaş sorgular ve fetch, okuma ve yazma açısından en ağır olanlar. Her sorgu, çalıştırılma sayısını gösterir.
- 1Trace oturumufbtracemgr sürekli çalışır; bir watchdog kaybolan oturumu yeniden başlatır
- 2Dakika dosyasıdakikada bir sıkıştırılmış trace çıktısı
- 3Dakika toplamlarıher sorgu için: çalıştırmalar, süre, fetch, okuma, yazma, işaretler
- 4Pencere raporupencere bittikten sonra 5 dakika içinde; her sıralamada en fazla 20 sorgu
- 5✓ HQ MonitorPerf Report sayfası; sağlık raporundan bağlantı
Neden plana göre gruplama
Bir program değerleri doğrudan SQL metnine koyarsa, her değer yeni bir metin oluşturur. Gerçek bir durumda, farklı metinlerin sayısı dakikada 204'ten 83.825'e çıktı. Binlerce "farklı" sorgu aslında tek plana sahip tek bir sorgudur. Bu nedenle ajan varsayılan olarak sorguları bir anahtara göre gruplar: yorumlar olmadan SQL'in ilk 10 karakteri ve çalıştırma planı. Planı olmayan bir sorgu tam metnini korur. Modu ajan ayarlarında, "Perf group by" alanında değiştirirsiniz: plana göre veya tam SQL metnine göre. Metne göre dosyalar ve raporlar çok daha büyük olur. Aşağıdaki örnekte modu değiştirin ve sıralamaları karşılaştırın.
Bir dakikadaki sorgular
Fetch'e göre sıralama
| Rapor tablosu | Ne gösterir |
|---|---|
| Süreye göre en iyi SQL | En yavaş çalıştırmalar: süre ve kayıt sayısı. |
| Fetch, okuma, yazmaya göre en iyi SQL | Pencere toplamları: çalıştırmalar, süre, fetch, okuma, yazma, işaretler; tüm pencerenin payı; çalıştırma başına ortalama ve maksimum. |
| Süreçler ve Adresler | Programa ve istemci adresine göre yük: bağlantılar, süre, farklı plan ve sorgu sayısı. |
| Sorgu satırı | Tam SQL, PLAN, parametreler ve tablo başına istatistikler: natural, index, update, insert, delete, backout, purge, expunge. |
| Sekmelerde on sıralama | Süre, sıklık, toplam süre, fetch, okuma, yazma, planlar, etiketler, prosedürler ve tetikleyiciler. Her metrik için değerlerin dağılımını görürsünüz. |
| Örnek çalıştırma | Ne zaman çalıştı, hangi istemci ve hangi adresten, hangi veritabanında. Çalıştırma bir hatayla sona erdiyse bunu görürsünüz; her sorgunun başarısız çalıştırma sayacı vardır. |
| Saate göre çalıştırmalar | Sorgunun pencerenin her saatinde kaç kez ve ne kadar süre çalıştığı. |
| Veritabanları | Sunucunun veritabanlarına ve her sorgunun ana veritabanlarına göre toplamlar. |
Karşılaştırma, geçmiş ve istek üzerine rapor
Pencere raporu "bugün ne ağırdı" sorusunu yanıtlar. Üç yeni işlev "ne değişti" ve "bu saatte ne oldu" sorularını yanıtlar.
- İki pencereyi karşılaştırmaYan yana iki rapor: hangi sorgular yavaşladı, hangileri ortaya çıktı ve hangileri kayboldu.
- 30 günlük sorgu geçmişiBir sorgunun süresinin ve çalıştırma sayısının pencereden pencereye nasıl değiştiği.
- Veritabanına göre filtreYalnızca bir veritabanı için rapor. Veritabanı sayfasındaki bir bağlantı rapor sayfasına götürür.
- Dakikanın trace'lerineRapordaki bir sorgudan, çalıştığı dakikanın trace'lerine.
- İstek üzerine raporBuild report… düğmesi 24 saate kadar herhangi bir aralık için rapor oluşturur. Filtreler: veritabanı, minimum süre, program. Ajan aynı anda yalnızca bir böyle rapor oluşturur ve son 20'yi saklar.
- Arama ve indirmeSorgu metni için bir arama alanı. Raporun kaynak dosyasını indirebilirsiniz.
- Eksik rapor işaretlenirBazı trace dosyaları henüz gelmediyse rapor eksik olarak işaretlenir. Rapor her sıralamanın yalnızca en üstünü saklar, bu nedenle sayfa "çalışmadı" değil "sıralamada değil" der.
- Prosedürler ve tetikleyicilerBu sıralamalar, trace ayarları prosedür ve tetikleyici bitişinin günlüğe kaydedilmesini açtığında dolar. Varsayılan olarak bu günlükleme kapalıdır.
- Sağlık raporundanPerf report düğmesi doğru pencereyi açar. Sorgu satırları işaretlidir ve ilki zaten genişletilmiştir.
- Sorgu ve tablogstat istatistiklerinin Queries sekmesi, sorguları okudukları tablolara ve dizinlere bağlar.
- Veritabanı grafiğinde bir dakikaBir dakikaya tıklamak, trace'ten ağır sorguları ve o dakikanın tüm bağlantılarını gösterir.
- SQL'i kopyalaParametrelerle veya parametresiz, doğrudan kendi aracınıza. Demo modunda düğmeler gizlenir.
trace · Errors
İstemci verileriyle SQL hataları
Bir kullanıcı "program hata verdi" der. Errors sayfası trace'ten her Firebird hatasını gösterir: zaman, bağlantı, veritabanı, metin ve istemci. Program adı, adres ve Firebird işleviyle hatayı kodunuzda kolayca bulabilirsiniz.
Trace'teki hata bloğu
Errors sayfasındaki satır
- Aynı hatalar — tek satırDakika, veritabanı ve hata türü başına bir satır, ×N sayısıyla. Bir ipucu ilk ve son zamanı ve bağlantı sayısını gösterir.
- FiltrelerMetin, veritabanı, program, adres ve işleve göre Include ve Exclude. Bir program veya adrese tıklamak yalnızca onun hatalarını tutar.
- CSV dışa aktarmaFiltreler uygulanmış tüm satırlar, BOM'lu UTF-8 olarak: Excel dosyayı hemen sütunlarda açar.
- Program yoksaBirçok JDBC ve .NET sürücüsü program adını göndermez. O zaman istemci satırı daha kısadır.
trace_monitor_conflicts · find_deadlocks
Çakışmalar ve deadlock'lar
"update conflicts with concurrent update" hatası tek başına pek bir şey söylemez. Diğer işlemin ne yaptığını bilmeniz gerekir. Bunun için ajan, veri değişiklikleri ve hatalar için ayarlanmış ikinci bir trace oturumu tutar. Her 15 dakikada bir çakışmaları arar ve bir rapor oluşturur.
Rapor nasıl okunur
Solda çakışmaların olduğu dakikaların listesi var. Her grup, çakışmalara neden olan bir işlemdir: işlem numarası ve hata zamanı.
Sol sütun hataları gösterir: bağlantı, program, Firebird kodları ve başarısız olan sorgu. Sağ sütun, rakip işlemin başarılı sorgularını gösterir: zaman, bağlantı, işlem numarası, program. Her sorgunun SQL'i, parametreleri, istatistikleri ve tabloları vardır.
Sayfa adresi tarihi ve dakikayı korur. Bağlantıyı bir meslektaşınıza gönderebilirsiniz.
| Parametre | Varsayılan | Anlamı |
|---|---|---|
| Çakışma araması | her 15 dakikada bir | Son dakika atlanır: trace hâlâ onu yazıyor. |
| Arama derinliği | 3 saat | Diğer işlemin sorgularını ararken çakışmadan önceki ne kadar geçmişe bakılacağı. |
| Ham trace saklama | 6 saat | Çakışma oturumunun ham dosyaları sunucuda birikmez. Raporlar saklanır ve HQ Monitor'a gönderilir. |
gstat · indeksler · meta veri
Veritabanı nasıl değişir
Ajan günde bir kez tam gstat istatistiklerini alır. HQ Monitor dosyayı ayrıştırır: tabloların ve indekslerin boyutu, kayıt sürümleri, BLOB'lar, indeks derinliği. "Analiz ve öneriler" sekmesi neyin yanlış olduğunu ve ne yapılması gerektiğini söyler.
| Sekme | Geliştiriciye ne kazandırır |
|---|---|
| Tablolar | Veri, indeks ve BLOB boyutu, kayıt sayısı, kayıt sürümleri ve bir kaydın maksimum sürümleri. |
| İndeksler | Derinlik, sayfalar, benzersiz değerler, yinelenenler. Derinlik 4 sarı satırdır, 5 ve üzeri kırmızıdır. |
| Sorgular ve Bağlantılar | Hangi sorguların bir tabloyu veya indeksi okuduğu. Anlık görüntüye zaman olarak yakın performans raporlarından alınan veriler. |
| Eğilimler | 5, 10, 20 veya 30 anlık görüntünün karşılaştırılması; değişim eşiği %10, %2 veya %0,5. Üç veya daha fazla anlık görüntüden "+25%" tahmini. |
| Dışa aktarma | Ölçümleri içeren JSON ve tam analizi içeren Excel. |
- İndeks istatistikleriVarsayılan olarak kapalıdır; ajan ayarlarından açarsınız. Ardından ajan her 6 saatte bir etkin olmayan indeksleri ve zayıf seçiciliğe sahip indeksleri sayar. Geri yüklemeden sonra oluşturulmamış bir indeks, sağlık raporunda ciddi bir sorundur.
- Büyüme tahminiVeritabanı tablosundaki "+25%" etiketi, en hızlı büyüyen tabloyu veya indeksi gösterir ve tahmini açar.
- Şema dışa aktarmaAjan, veritabanı meta verilerini
isql -xile dışa aktarır ve arşivleri tarihe göre saklar. - Meta veri izlemeVarsayılan olarak kapalıdır; ajan ayarlarından açarsınız. Ajan her 6 saatte bir yeni şema dışa aktarımını öncekiyle karşılaştırır ve şemanın ne zaman değiştiğini kaydeder.
LWM · MON$ · istemciler
Bağlantılar: uzun işlemler ve istemci sürümleri
Unutulmuş tek bir işlem tüm veritabanını yavaşlatır: kayıt sürümleri birikir ve çöp toplama durur.
Ajan her dakika işlem sayaçlarını ve bağlantı verilerini yazar. Veritabanı grafiğinde, bir işlem uzun süre açık kalırsa Next − OAT büyür. O dakikaya ait bağlantı tablosu, Act.Tran'a göre sıralanmış olarak, işlemi tutan programı, adresi ve süreci gösterir. Sayaçlar hakkında daha fazlası sunucu sağlığı sayfasında.
Ajan günde bir kez hangi istemci kütüphanelerinin veritabanına bağlandığını ve her birinin kaç bağlantısı olduğunu okur. "Algılanmadı. Eski sürüm mü?" satırı genellikle eski bir istemci kütüphanesi anlamına gelir.
- MON$ metrikleriSaatte bir: programa göre bellek, en fazla belleğe sahip 5 bağlantı ve en yüksek yüke sahip 5 bağlantı.
- Yanlış alarm olmadan eski istemciler"Eski istemciler" bulgusu yalnızca fbclient kütüphanelerini sayar. fbclient olmadan çalışan sürücüler buna dahil edilmez.
- Rapordaki uzun işlemlerSağlık raporu uzun işlemleri ve Next − OAT büyümesini işaretler. Bulgu, kullanıcıyı, programı ve adresi belirtir ve bağlantıyı kesmek için hazır bir komut verir.
Yerel API · Prometheus · HQbird MCP
Betikleriniz, CI ve yapay zekâ asistanınız
HQ Monitor'da gördüğünüz her şey kendi araçlarınızdan erişilebilir. Ajanın Yerel API'si yalnızca loopback üzerinde dinler ve her istek bir Bearer token taşır. Ağır işler eşzamansız çalışır: yanıt bir işlem numarası verir ve durumu bu numarayla okursunuz. Ajan, sunucuyu değiştiren her isteği ve her 401 veya 403 reddini denetim günlüğüne yazar. Okuma istekleri günlüğe gitmez.
# Yerel API portu = 10000 + Firebird portu: burada Firebird 3055 kullanıyor, yani 13055 # sunucu durumu: sağlık raporundakiyle aynı anlık görüntü curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:13055/v1/status # en son performans raporu ve en son çakışma raporu 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 # CI'da geçişten önce yedek al ve sonucu bekle 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>
| Yol | Ne verir |
|---|---|
/v1/status | Sunucu durumunun anlık görüntüsü, tamamı veya bölüm bazında, örneğin yedeklemeler. |
/v1/databases | Etkin veritabanlarının listesi. |
/v1/artifacts/… | Ajan verileri: dakika başına LWM (Light-weight Monitoring), gstat, indeks istatistikleri, metrikler, en son şema dışa aktarımı, trace raporları. |
/v1/jobs/{job}/run | Bir iş çalıştır: yedekleme, geri yükleme, sweep, veritabanı denetimi, indeks istatistiklerinin yeniden hesaplanması, SQL betiği. Aynı anahtarla tekrar, işi iki kez çalıştırmaz. |
Prometheus metrikleri Yerel API'den geçmez. Kendi adresleri vardır: varsayılan olarak 127.0.0.1, port 25000 + Firebird portu. Kendi Bearer token'ları vardır. Dışa aktarma varsayılan olarak kapalıdır; ajan ayarlarından açarsınız. Metrikler: LWM, CPU ve bellek, diskler, işletim sistemi limitleri, geçici dosyalar.
IDE'de yapay zekâ asistanı
HQbird MCP, Firebird'ü ve ajan verilerini Claude Code, Cursor, Codex ve diğer MCP istemcilerine bağlar. Asistan ajan raporlarını görür ve veritabanıyla insan denetimi altında çalışır: tehlikeli eylemleri bir kişi onaylar.
Plan ve indeks
Sorgu planı ve indeks önerisi, indeks oluşturulduktan sonra planın yeniden kontrolüyle. Sorgunun çalıştırılmadan önce derleme kontrolü.
İki veritabanını karşılaştır
Şema ve veri farkları, örneğin geliştirme ile test ortamı arasında.
Planla, onayla, geri al
Planı, tek onayı ve geri alma planı olan bir geçiş.
← HQbird 2027 genel bakışına dön · Sunucu sağlığı ayrıntılı olarak →