pg_stat_statements, PostgreSQL’in çalıştırdığı her sorgu tipi için çağrı sayısını, toplam ve ortalama süreyi, okunan sayfa sayısını ve dönen satır sayısını biriktiren resmi bir eklentidir. Veritabanı yavaşladığında “hangi sorgu?” sorusunun cevabını tahmin yerine veriyle verir. Ben bir PostgreSQL sunucusunda performans çalışmasına başlarken ilk baktığım yer burasıdır.

Bu yazıda eklentiyi nasıl açacağınızı, sonuçları hangi sıraya göre okumanız gerektiğini ve en sık yapılan yorum hatalarını anlatacağım.

pg_stat_statements neden gerekli?

Yavaş sorgu logları (log_min_duration_statement) tek tek yavaş sorguları yakalar. Bu faydalıdır ama resmin yarısıdır.

Bir sorgu 3 ms sürüyor ve dakikada 50.000 kez çağrılıyorsa, hiçbir zaman yavaş sorgu loguna düşmez. Ama veritabanının toplam zamanının büyük kısmını o tüketiyordur. Tersine, ayda bir çalışan 40 saniyelik bir rapor sorgusu logda göze çarpar ama toplam yükte önemsizdir.

pg_stat_statements bu ikisini aynı tabloda gösterir. Sorgular normalize edilir: WHERE id = 42 ve WHERE id = 97 aynı satırda WHERE id = $1 olarak toplanır. Böylece aynı sorgunun binlerce farklı parametreyle çalışması tek bir kayıtta birikir.

Kurulum nasıl yapılır?

Eklenti PostgreSQL ile birlikte gelir ama varsayılan olarak yüklenmez. İki adım gerekir.

Önce postgresql.conf içinde paylaşımlı kütüphane olarak eklenir. Bu değişiklik yeniden başlatma gerektirir:

shared_preload_libraries = 'pg_stat_statements'
pg_stat_statements.track = top
pg_stat_statements.max = 10000

Sonra veritabanında eklenti oluşturulur:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

Yönetilen servislerde, örneğin Amazon RDS, Cloud SQL veya Azure Database for PostgreSQL’de, eklenti genellikle parametre grubu üzerinden açılır ve çoğunda varsayılan olarak yüklü gelir.

Ek yükü düşüktür. Ben production sunucularında kapalı tutmak için geçerli bir sebep görmedim. Asıl risk, kapalı olduğu için bir performans probleminde elinizde hiçbir veri olmamasıdır.

Hangi kolonlar ne anlatır?

Görünümde onlarca kolon var. Günlük kullanımda baktığım kolonlar sınırlı. Aşağıdaki isimler PostgreSQL 13 ve sonrası içindir. Daha eski sürümlerde total_time gibi farklı adlar kullanılıyordu.

KolonAnlamı
callsSorgunun kaç kez çalıştığı
total_exec_timeBütün çalıştırmaların toplam süresi, ms
mean_exec_timeOrtalama süre, ms
stddev_exec_timeSürenin standart sapması
rowsDönen veya etkilenen toplam satır
shared_blks_hitBellekten okunan sayfa sayısı
shared_blks_readDiskten okunan sayfa sayısı
temp_blks_writtenBellek yetmediği için diske yazılan geçici sayfalar

temp_blks_written kolonu sık atlanır ama değerlidir. Sıfırdan büyükse sorgu, sıralama veya hash işlemi için work_mem sınırını aşmış ve geçici dosya kullanmıştır. Bu hem diski yorar hem de sorguyu yavaşlatır.

rows kolonunu calls değerine bölmek, sorgunun her çalıştırmada ortalama kaç satır döndürdüğünü verir. Bir liste ekranı için çalışan sorgunun her seferinde 50.000 satır döndürdüğünü görmek, pagination eksikliğini veya uygulama tarafında filtreleme yapıldığını gösterir.

shared_blks_hit ve shared_blks_read toplamını rows değerine bölmek de faydalı bir oran. Döndürülen satır başına okunan sayfa sayısı çok yüksekse, sorgu ihtiyacından çok daha fazla veriyi geziyor demektir.

Sonuçlar hangi sıraya göre okunmalı?

Aynı veri farklı sıralamalarla farklı sorular cevaplar. Ben genellikle dört sorgu çalıştırıyorum.

Toplam süreye göre

Veritabanının zamanını en çok nereye harcadığını gösterir. Optimizasyon için en değerli sıralama budur.

SELECT
  round(total_exec_time::numeric, 0) AS total_ms,
  calls,
  round(mean_exec_time::numeric, 2) AS mean_ms,
  round(100 * total_exec_time / sum(total_exec_time) OVER (), 1) AS pct,
  left(query, 120) AS query
FROM pg_stat_statements
ORDER BY total_exec_time DESC
LIMIT 20;

pct kolonu, sorgunun toplam süre içindeki payını gösterir. Listenin ilk birkaç satırı çoğu zaman toplam sürenin yarısından fazlasını oluşturur. Optimizasyona oradan başlamak, en az eforla en fazla etkiyi verir.

Ortalama süreye göre

Tek başına yavaş olan sorguları gösterir. Kullanıcının beklediği bir ekranın arkasındaki sorgu burada çıkıyorsa, toplam yükte küçük görünse bile önemlidir.

Çağrı sayısına göre

Beklenmedik derecede sık çalışan sorguları ortaya çıkarır. Bir sayfa yüklemesinde aynı sorgunun yüzlerce kez çalışması, genellikle ORM kaynaklı bir N+1 probleminin işaretidir. Bu kalıbı N+1 problemi yazısında ayrıntılı anlatmıştım.

Okunan sayfa sayısına göre

shared_blks_read ve shared_blks_hit kolonları, sorgunun bellekten mi diskten mi okuduğunu gösterir. Çok sayfa okuyup az satır döndüren sorgular, eksik index için en güçlü adaylardır.

SıralamaCevapladığı soruTipik bulgu
total_exec_timeVeritabanı zamanını nereye harcıyor?Sık çalışan, orta hızda sorgular
mean_exec_timeTek başına hangi sorgu yavaş?Rapor ve arama sorguları
callsHangi sorgu beklenenden sık çalışıyor?N+1, gereksiz kontrol sorguları
shared_blks_readHangi sorgu en çok disk okuyor?Eksik index, büyük taramalar

Bir sorguyu bulduktan sonra ne yapmalı?

pg_stat_statements size hangi sorguya bakmanız gerektiğini söyler. Neden yavaş olduğunu söylemez.

Normalize edilmiş sorgudaki $1, $2 parametrelerini gerçekçi değerlerle doldurup EXPLAIN (ANALYZE, BUFFERS) ile çalıştırmak bir sonraki adımdır. Plan okumanın ayrıntılarını EXPLAIN ANALYZE nasıl okunur yazısında anlattım.

Parametre seçimi önemli. Çarpık dağılıma sahip verilerde, bir müşteri için hızlı çalışan sorgu başka bir müşteri için çok yavaş olabilir. Gerçek uygulama trafiğinden örnek parametreler almak, test değerleriyle çalışmaktan daha doğru sonuç verir.

Sık yapılan yorum hataları

Ortalamaya güvenmek. mean_exec_time bir ortalama. Sorgunun çoğu zaman 2 ms, bazen 4 saniye sürdüğü durumları gizler. stddev_exec_time ve max_exec_time kolonları bu dağılım hakkında fikir verir. Ortalamanın neden yanıltıcı olduğunu yanıt süresi yüzdelikleri yazısında anlatmıştım.

İstatistiklerin ne zamandan beri biriktiğini bilmemek. Değerler sunucu başladığından veya son sıfırlamadan beri birikir. Üç ay önce düzeltilmiş bir sorgu, hâlâ listenin başında görünebilir. Bir optimizasyonun etkisini ölçmek için öncesinde pg_stat_statements_reset() çalıştırıp belirli bir süre sonra tekrar bakmak gerekir.

Planlama süresini görmezden gelmek. track_planning açıksa planlama süresi de görülür. Çok karmaşık ve çok sık çalışan sorgularda planlama süresi, çalışma süresine yaklaşabilir.

Tek bir anlık görüntüye bakmak. Bugünün değerleri tek başına trend göstermez. Değerleri düzenli olarak bir metrik sistemine aktarmak, bir deploy’dan sonra hangi sorgunun yavaşladığını görmeyi sağlar.

Değerleri izleme sistemine almak

pg_stat_statements kümülatif sayaçlar tutar. Prometheus’un postgres_exporter aracı bu sayaçları metrik olarak dışa aktarabilir. Grafana’da sorgu bazında saniyedeki çağrı sayısını ve süre değişimini görmek, “dün akşam deploy’dan sonra ne değişti?” sorusunu cevaplamayı kolaylaştırır.

Uygulama tarafındaki metriklerle birleştirildiğinde resim tamamlanır. Endpoint bazında yanıt süresi artışı ile veritabanında belirli bir sorgunun süresinin artışını aynı zaman ekseninde görmek, kök sebebi bulmayı hızlandırır. Bu üç sinyali birlikte kullanma yaklaşımını log, metric ve trace yazısında anlatmıştım.

Gerçek bir örnek

Bir projede veritabanı CPU’su sürekli yüzde 80’in üzerindeydi. Yavaş sorgu loglarında dikkat çeken bir şey yoktu.

pg_stat_statements’ı toplam süreye göre sıraladığımızda ilk satırda şu vardı:

total_ms  calls     mean_ms  pct   query
2841920   9184220   0.31     38.4  SELECT ... FROM user_settings WHERE user_id = $1

Tek çalıştırmada 0,3 ms süren masum bir sorgu, veritabanı zamanının yüzde 38’ini tüketiyordu. Her API isteğinde, birkaç farklı yerden, kullanıcı ayarları tekrar tekrar okunuyordu.

Çözüm veritabanında değil uygulamadaydı. Ayarları istek başına bir kez okuyup taşımak ve sık değişmeyen veriyi kısa süreli local cache içinde tutmak, CPU kullanımını yüzde 45 civarına indirdi.

Bu örnek bence pg_stat_statements’ın asıl değerini gösteriyor. Tek tek hızlı görünen ama toplamda pahalı olan şeyleri görünür kılıyor.

pg_stat_statements’ın sınırları nelerdir?

Eklenti çok faydalı ama her şeyi göstermez. Sınırlarını bilmek, yanlış sonuç çıkarmayı engeller.

Kilit beklemeleri ayrı görünmez. Bir sorgunun süresi, satır kilidi için beklediği zamanı da içerir. Ortalama süresi aniden artan bir UPDATE sorgusu yavaşlamamış, sadece başka bir transaction’ı bekliyor olabilir. Bu durumda pg_stat_activity ve pg_locks görünümleri anlık durumu gösterir.

Sınırlı sayıda sorgu tutulur. pg_stat_statements.max değerinden fazla farklı sorgu oluştuğunda, en az çalışanlar listeden düşer. Sorgu metni dinamik olarak üretiliyorsa, örneğin IN listesindeki eleman sayısı her seferinde farklıysa, aynı sorgu yüzlerce farklı kayıt olarak görünebilir. PostgreSQL 18 bu konuda iyileştirme getirdi ama eski sürümlerde dikkat etmek gerekir.

Hangi uygulamadan geldiği belli değildir. Görünüm kullanıcıyı ve veritabanını gösterir ama hangi servisin veya endpoint’in sorguyu çalıştırdığını göstermez. Her servis için ayrı bir veritabanı kullanıcısı tanımlamak veya sorgulara yorum satırıyla kaynak bilgisi eklemek bu boşluğu kapatır.

Uygulama tarafındaki süreyi göstermez. Bir isteğin 900 ms sürmesinin 30 ms’si veritabanında geçiyorsa, sorun veritabanında değildir. Ama sadece pg_stat_statements’a bakarak bunu anlayamazsınız. Uygulama tarafındaki connection bekleme süresini de ölçmek gerekir. Connection havuzunun yanlış boyutlandırılmasının nasıl bir darboğaz yarattığını connection pool boyutlandırma yazısında anlatmıştım.

Kontrol listesi

  • shared_preload_libraries içinde eklentiyi aç, CREATE EXTENSION ile oluştur.
  • İlk olarak total_exec_time sırasına bak, toplam sürenin yüzdesini hesapla.
  • Çağrı sayısı beklenmedik derecede yüksek sorguları N+1 açısından incele.
  • Bulunan sorguyu gerçekçi parametrelerle EXPLAIN ANALYZE ile çalıştır.
  • Optimizasyondan önce istatistikleri sıfırla, sonra aynı süre boyunca tekrar ölç.
  • Değerleri bir metrik sistemine aktarıp trendleri izle.

Eklentinin bütün kolonlarının açıklaması PostgreSQL’in resmi pg_stat_statements dokümantasyonunda yer alıyor. Kolon adları sürümler arasında değiştiği için, kendi sürümünüze ait sayfaya bakmanızı öneririm.

Performans çalışmasında en pahalı hata, yanlış sorguyu optimize etmektir. pg_stat_statements, doğru sorguyu bulmanın en ucuz yolu.