<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Güngör Akbıyık on Medium]]></title>
        <description><![CDATA[Stories by Güngör Akbıyık on Medium]]></description>
        <link>https://medium.com/@gungor.akbiyik?source=rss-3597415c14fc------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*HJrxS8nQ7HAnYcRk</url>
            <title>Stories by Güngör Akbıyık on Medium</title>
            <link>https://medium.com/@gungor.akbiyik?source=rss-3597415c14fc------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Wed, 18 Nov 2026 07:18:47 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@gungor.akbiyik/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Idle in Transaction: Connection Pool’u Asıl Tüketen Java+Spring Kalıpları]]></title>
            <link>https://medium.com/@gungor.akbiyik/idle-in-transaction-connection-poolu-as%C4%B1l-t%C3%BCketen-java-spring-kal%C4%B1plar%C4%B1-702dca1aa16f?source=rss-3597415c14fc------2</link>
            <guid isPermaLink="false">https://medium.com/p/702dca1aa16f</guid>
            <dc:creator><![CDATA[Güngör Akbıyık]]></dc:creator>
            <pubDate>Fri, 24 Jul 2026 06:46:36 GMT</pubDate>
            <atom:updated>2026-07-24T06:46:36.469Z</atom:updated>
            <content:encoded><![CDATA[<p>Connection pool metrikleri kırmızıya döndü. Active connections tavanda, yeni istekler connection bekliyor, uygulama yavaşladı.</p><p>İlk refleks “yavaş sorgu var” olur. pg_stat_activity&#39;ye bakarsınız, ama çalışan bir sorgu yok. Bütün o connection&#39;lar idle in transaction state&#39;inde duruyor. Kimse bir şey sormuyor, sadece bir transaction açık, commit ya da rollback gelmemiş.</p><p>PostgreSQL’in buna karşı tek satırlık bir savunması var: idle_in_transaction_session_timeout. Ama o ayar asıl soruyu cevaplamıyor. Bu transaction&#39;lar neden açık kalıyor? Cevap neredeyse hiç PostgreSQL&#39;de değil, Java tarafında, @Transactional sınırının nasıl çizildiğinde.</p><h3>PostgreSQL Tarafı: Semptom ve Emniyet Valfi</h3><p>Bir connection’ın idle in transaction olması şu demek: bir transaction başlamış, en az bir sorgu çalışmış, ama transaction henüz commit ya da rollback ile kapanmamış. O connection&#39;ı artık pool&#39;a geri veremezsiniz, çünkü üstünde açık iş var.</p><p>Görmek için:</p><pre>SELECT pid, state, now() - state_change AS idle_duration, query<br>FROM pg_stat_activity<br>WHERE state = &#39;idle in transaction&#39;<br>ORDER BY idle_duration DESC;</pre><p>query sütunu transaction&#39;ın son çalıştırdığı sorguyu gösterir, o an çalışan bir şey değil. idle_duration uzunsa (birkaç saniyeden fazlaysa), bir yerde kod transaction&#39;ı açık tutup başka bir şey bekliyor demektir.</p><p>PostgreSQL’in kendi savunması tek satır:</p><pre>ALTER SYSTEM SET idle_in_transaction_session_timeout = &#39;30s&#39;;</pre><p>Bu süreden uzun idle kalan transaction’ı veritabanı kendisi rollback eder, connection’ı serbest bırakır. Ama bunu çözüm gibi görmeyin. Bu bir emniyet valfi, yangın söndükten sonra devreye giren bir şey. Asıl mesele transaction’ın neden o kadar uzun açık kaldığı, ve o sorunun cevabı neredeyse her zaman uygulama kodunda.</p><h3>Java+Spring Tarafı: Asıl Üreten Kalıplar</h3><h3>Transaction Sınırına Sızan Harici Çağrı</h3><p>En yaygın kalıp bu: @Transactional metodun içinde bir HTTP çağrısı, bir Kafka producer send&#39;i, bir S3 upload&#39;u.</p><pre>@Transactional<br>public void placeOrder(Order order) {<br>    orderRepository.save(order);<br>    PaymentResult result = paymentClient.charge(order); // HTTP cagrisi, transaction icinde<br>    order.markPaid(result);<br>    orderRepository.save(order);<br>}</pre><p>paymentClient.charge 300 ms de sürer, 3 saniye de. O sürenin tamamında connection pool&#39;da tutulan bir connection, açık bir transaction ve idle in transaction bekliyor demektir. Ödeme servisi yavaşladığı gün, connection pool&#39;unuz o yavaşlığın faturasını öder.</p><p>Kural basit: transaction sadece veritabanı işlemini sarmalı. Ağ üzerinden giden hiçbir çağrı transaction sınırının içinde olmamalı.</p><h3>Self-Invocation’ın Gizli Genişlemesi</h3><p>Bu tuzak daha sinsi, çünkü niyet doğru ama Spring’in proxy mekanizması niyeti boşa çıkarıyor.</p><pre>@Service<br>public class OrderBatchProcessor {<br><br>    @Transactional<br>    public void processAll(List&lt;Long&gt; orderIds) {<br>        for (Long id : orderIds) {<br>            this.processOne(id); // ayni proxy uzerinden gitmiyor<br>        }<br>    }<br><br>    @Transactional(propagation = Propagation.REQUIRES_NEW)<br>    public void processOne(Long id) {<br>        Order order = repository.findById(id).orElseThrow();<br>        PaymentResult result = paymentClient.charge(order);<br>        order.markProcessed(result);<br>    }<br>}</pre><p>Niyet şu: her sipariş kendi kısa transaction’ında işlensin (REQUIRES_NEW), aralarda connection serbest kalsın. Gerçek şu: this.processOne(id) çağrısı aynı sınıfın içinden yapıldığı için Spring&#39;in AOP proxy&#39;sini bypass eder. REQUIRES_NEW hiç tetiklenmez, çağrı sadece processAll&#39;un zaten açık olan transaction&#39;ı içinde devam eder. Sonuç: N sipariş için yapılan harici ödeme çağrısı, tek ve dev bir transaction&#39;ın içinde art arda dizilir. Connection, batch&#39;in tamamı bitene kadar açık kalır.</p><p>Çözüm, processOne&#39;ı ayrı bir bean&#39;e taşımak (self-injection ya da ayrı bir servis sınıfı). Böylece çağrı gerçek proxy üzerinden geçer, REQUIRES_NEW gerçekten çalışır.</p><h3>Class-Level Geniş @Transactional</h3><p>Sınıfın tepesine @Transactional koymak, o sınıftaki her public metodu transactional yapar. Bu, batch orkestrasyonu yapan, dosya işleyen ya da harici servis çağıran bir metodu da farkında olmadan transaction sınırının içine sokar. Kural: @Transactional&#39;ı sınıfa değil, gerçekten veritabanı işlemi yapan metotlara koyun.</p><h3>Uzun Batch Döngüleri</h3><p>Tek transaction içinde binlerce satır işleyen bir döngü, her satırda biraz hesap yapıyorsa ya da ara sıra harici bir kontrol çağırıyorsa, transaction süresi satır sayısıyla birlikte büyür. Bunu sayfalama (Pageable) ile küçük parçalara bölüp her parçayı kendi kısa transaction&#39;ında işlemek, tek dev transaction&#39;dan daha sağlıklıdır.</p><h3>Open-in-View: İlgili Ama Farklı Bir Sorun</h3><p>spring.jpa.open-in-view (default true) Hibernate session&#39;ını isteğin sonuna, view render edilene kadar açık tutar. Sık yanlış anlaşılan nokta şu: bu, transaction&#39;ı isteğin tamamı boyunca açık tutmaz. Transaction&#39;lar hâlâ @Transactional sınırlarında başlar ve biter. OSIV&#39;in asıl bedeli farklı bir yerde: view render sırasında bir lazy-loaded alana dokunulursa, orijinal transaction çoktan kapanmış olsa bile yeni bir sorgu (yeni bir kısa transaction, yeni bir connection round-trip) sessizce tetiklenir. Yani OSIV doğrudan idle in transaction üretmez, ama katmanlar arası disiplini bozar ve N+1&#39;i view&#39;a kadar taşır. open-in-view: false yapıp bu sızıntıyı en azından geliştirme zamanında görünür kılmak, hâlâ doğru varsayılan.</p><h3>Tespit</h3><p>Üç katmanlı bir tespit yeter.</p><p>pg_stat_activity sorgusu, en direkt kanıt. idle_duration uzun ve tekrarlıysa, aynı application_name&#39;den geliyorsa, suçlu orada.</p><p>HikariCP’nin kendi leak dedektörü:</p><pre>spring:<br>  datasource:<br>    hikari:<br>      leak-detection-threshold: 15000   # 15 sn&#39;den uzun tutulan connection loglanir</pre><p>Bu, connection’ı kim aldıysa onu stack trace ile gösterir. idle in transaction&#39;ın kaynağını koddan bulmanın en hızlı yolu budur.</p><p>Actuator/Micrometer tarafında hikaricp.connections.active ve hikaricp.connections.pending metriklerinin birlikte yükselmesi, pool&#39;un dolduğunun ama sorgu yükünün artmadığının işareti.</p><h3>Çözüm Katmanları</h3><p><strong>Transaction scope’unu cerrahi tutun.</strong> Harici çağrıyı transaction dışına taşıyın, gerekiyorsa TransactionTemplate ile sadece veritabanı işlemini saran dar bir blok açın.</p><pre>public void placeOrder(Order order) {<br>    PaymentResult result = paymentClient.charge(order); // once, transaction disinda<br>    transactionTemplate.executeWithoutResult(status -&gt; {<br>        orderRepository.save(order.withPayment(result));<br>    });<br>}</pre><p><strong>@Transactional(timeout = ...) ile bir üst sınır koyun.</strong> Beklenenden uzun süren her transaction&#39;ı uygulama seviyesinde kesin, PostgreSQL&#39;e bırakmayın.</p><pre>@Transactional(timeout = 2) // saniye<br>public void applyDiscount(Long orderId) {<br>    // ...<br>}</pre><p><strong>open-in-view: false yapın.</strong> Doğrudan idle-in-transaction&#39;ı çözmez ama session/connection disiplinini görünür kılar.</p><p><strong>PostgreSQL ve HikariCP ayarlarını uyumlu tutun.</strong> idle_in_transaction_session_timeout ve statement_timeout sunucu tarafında son savunma olarak dursun. Bu timeout&#39;lardan biri bir session&#39;ı kopardığında Hikari&#39;nin elindeki connection ölü çıkar; pool bunu ancak bir sonraki kullanımda fark eder — loglarda &quot;connection is closed&quot; görürseniz sebebi bu olabilir. Ayrıca max-lifetime&#39;ı altyapıdaki bağlantı ömrü sınırlarından (ör. load balancer idle timeout, PgBouncer server_lifetime) kısa tutun ki sunucunun sessizce kapattığı bir connection&#39;ı Hikari sağlıklı sanmasın.</p><p>Katman kuralı net: uygulama önce, veritabanı timeout’u güvenlik ağı. idle_in_transaction_session_timeout sizi üretimde ayakta tutar, ama onu tetikleyen kod hâlâ orada durur, siz onu bulup düzeltene kadar.</p><h3>Kapanış: Küçük Bir Checklist</h3><ul><li>Her @Transactional metodun içinde ağ üzerinden giden bir çağrı var mı? Varsa dışarı taşı.</li><li>Class-level @Transactional kullanıyor musun? Metot seviyesine indir.</li><li>Bir metodun kendi transaction’ında (REQUIRES_NEW) çalışmasını bekliyorsun ama this. ile mi çağırıyorsun? Ayrı bean&#39;e taşı.</li><li>open-in-view açık mı? Kapat, ne çıktığını gör.</li><li>leak-detection-threshold tanımlı mı? Değilse ekle, prod&#39;da sessizce biriken tuzakları erken yakala.</li><li>PostgreSQL’de idle_in_transaction_session_timeout var mı? Yoksa ekle, ama tek başına yeterli sanma.</li></ul><h3>Kaynaklar</h3><ul><li><a href="https://www.postgresql.org/docs/current/runtime-config-client.html">PostgreSQL — Server Configuration: idle_in_transaction_session_timeout</a></li><li><a href="https://github.com/brettwooldridge/HikariCP#gear-configuration-knobs-baby">HikariCP — Configuration (leakDetectionThreshold, maxLifetime)</a></li><li><a href="https://docs.spring.io/spring-boot/appendix/application-properties/index.html">Spring Boot — Application Properties (spring.jpa.open-in-view)</a></li><li><a href="https://docs.spring.io/spring-framework/reference/data-access/transaction/programmatic.html">Spring Framework — Programmatic Transaction Management (TransactionTemplate)</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=702dca1aa16f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[TimeLimiter’ı Doğru Kurmak: Neden Sadece CompletableFuture’da Çalışır ve İşi Neden Durdurmaz]]></title>
            <link>https://medium.com/@gungor.akbiyik/timelimiter%C4%B1-do%C4%9Fru-kurmak-neden-sadece-completablefuture-da-%C3%A7al%C4%B1%C5%9F%C4%B1r-ve-i%CC%87%C5%9Fi-neden-durdurmaz-94acb0f8d3cb?source=rss-3597415c14fc------2</link>
            <guid isPermaLink="false">https://medium.com/p/94acb0f8d3cb</guid>
            <dc:creator><![CDATA[Güngör Akbıyık]]></dc:creator>
            <pubDate>Sun, 19 Jul 2026 03:40:58 GMT</pubDate>
            <atom:updated>2026-07-19T03:40:58.005Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MEAuppphvwdRdoJnj3FOuw.png" /></figure><p><a href="https://medium.com/@gungor.akbiyik/redis-down-kolay-senaryo-as%C4%B1l-katil-yava%C5%9F-redis-606ff189525c">Redis-down yazısında</a> bir timeout piramidi kurmuştuk. Her bağımlılığın kendi client timeout’u vardı ve bunlar iç içe geçiyordu: Lettuce commandTimeout 100 ms, DB sorgusu 1-2 saniye, endpoint 5 saniye, LB 30 saniye. Her katman bir alttakini kapsıyordu. O yazının okuru haklı bir soru sorabilirdi: her bağımlılığın zaten kendi timeout&#39;u varken, Resilience4j&#39;nin TimeLimiter&#39;ı ne işe yarar?</p><p>Bu yazı o sorunun cevabı. Ama cevap göründüğünden ince, çünkü TimeLimiter çoğu insanın sandığı şeyi yapmıyor. İki yanılgı üzerine kurulu bir araç: birincisi “senkron bir metodu da korur” sanılır, oysa yalnızca CompletableFuture dönen metotlarda çalışır. İkincisi &quot;timeout atınca işi durdurur&quot; sanılır, oysa sadece beklemeyi bırakır, iş arkada koşmaya devam eder. Bu iki yanılgıyı dağıtmak yazının belkemiği.</p><p>Serinin <a href="https://medium.com/@gungor.akbiyik/circuit-breaker%C4%B1-do%C4%9Fru-kurmak-state-machine-den-production-tuning-e-d998755ec722">circuit breaker</a> yazısında “art arda başarısızlık görürsen bir süre hiç deneme” mantığını kurmuştuk. TimeLimiter daha alt bir seviyede durur: tek bir çağrının süresini sınırlar ve o sınırı circuit breaker’a bağlar. Timeout, circuit breaker, bulkhead ve rate limiter’dan sonra bu, serinin dördüncü halkası. Önce TimeLimiter’ın çalışma modelini kuracağız, sonra en sinsi tuzağını açacağız, ayarları göreceğiz, Spring Boot’a bağlayacağız, circuit breaker’la kombinasyonunu netleştireceğiz ve en sonunda client timeout ile arasındaki iş bölümünü bir kurala oturtacağız.</p><h3>Client Timeout Varken TimeLimiter Neye Yarar</h3><p>Redis-down yazısındaki kural netti: her bağımlılığın kendi timeout’u olsun. Lettuce’ın commandTimeout&#39;u tek bir Redis komutunu keser. JDBC&#39;nin queryTimeout&#39;u tek bir SQL sorgusunu keser. HTTP client&#39;ın read timeout&#39;u tek bir HTTP çağrısını keser. Hepsi transport seviyesinde, çağrının kaynağında çalışır: soketi kapatır, işi orada durdurur.</p><p>Öyleyse TimeLimiter’a ne kalıyor? Üç boşluk kalıyor.</p><p><strong>Birincisi, timeout ayarı olmayan çağrılar.</strong> Her bağımlılığın client’ı size bir timeout knob’ı vermez. Elinizde bir üçüncü parti kütüphane, bir SDK, bir legacy bloklayan çağrı var ve içine timeout enjekte edemiyorsunuz. TimeLimiter, kontrol edemediğiniz bir çağrının etrafına dışarıdan bir süre sınırı koymanın yoludur.</p><p><strong>İkincisi, uçtan uca süre bütçesi.</strong> Client timeout tek bir I/O operasyonunu bağlar. Ama bir use-case genelde birden çok alt çağrının toplamıdır: bir dış fiyatlandırma servisine REST çağrısı, arkasından iki DB sorgusu, arasında biraz hesap. Her birinin kendi timeout’u 800 ms, 1 saniye, 1 saniye olabilir ama toplam bütçeniz “bu endpoint 2 saniyeyi geçmesin” olabilir. Tek tek client timeout’ların toplamı bu bütçeyi garanti etmez, çünkü 800 ms artı 1 saniye artı 1 saniye zaten 2.8 saniye eder. TimeLimiter, iş biriminin tümüne tek bir tavan koyar.</p><p><strong>Üçüncüsü, tek tip politika ve resilience stack’e entegrasyon.</strong> TimeLimiter’ın attığı TimeoutException, aynı Resilience4j ekosistemindeki circuit breaker&#39;ı besleyebilir, fallback&#39;e düşebilir, Micrometer metriğine yansır. Client timeout&#39;un fırlattığı exception ise dağınıktır: Lettuce&#39;ın kendi exception&#39;ı, JDBC&#39;nin SQLTimeoutException&#39;ı, HTTP client&#39;ın timeout&#39;u. TimeLimiter bunları tek bir kapıya, tek bir exception tipine indirger.</p><p>Kural şimdiden şekilleniyor ama tam halini sona saklayalım. Şu kadarını söyleyelim: client timeout ile TimeLimiter alternatif değil, tamamlayıcıdır. Biri işi kaynağında keser, öteki iş birimine tavan koyar. En sağlam kurulum ikisini birlikte kullanır ve bunun neden böyle olması gerektiği, TimeLimiter’ın çalışma modelini görünce netleşecek.</p><h3>Çalışma Modeli: Bir Future’ı Bekleyen Zamanlayıcı</h3><p>TimeLimiter’ın kalbini bir cümlede anlamak, sonraki her şeyi kolaylaştırır: TimeLimiter senkron bir metodu kesmez, bir Future&#39;ı bekler ve bekleme süresi dolunca vazgeçer.</p><p>Resilience4j’nin TimeLimiter&#39;ı CompletionStage, Future ve CompletableFuture sarar. İki çalışma varyantı var:</p><ul><li><strong>executeFutureSupplier(...)</strong>, bloklayan varyant. Ona bir Supplier&lt;Future&lt;T&gt;&gt; verirsiniz, o da altta future.get(timeoutDuration, MILLISECONDS) çağırır. Süre dolarsa get bir TimeoutException atar, TimeLimiter da bunu yakalayıp yeniden fırlatır.</li><li><strong>executeCompletionStage(...)</strong>, bloklamayan varyant. Bir ScheduledExecutorService ile timeout&#39;u zamanlar, süre dolunca sonuç future&#39;ını exceptionally tamamlar. Reactive ve async akışta kullanılan budur, ve birazdan göreceğimiz gibi Spring&#39;in @TimeLimiter annotation&#39;ının kullandığı yol da tam olarak burasıdır.</li></ul><p>Her iki varyantta da ortak nokta şu: işin bir Future olması gerekir, yani başka bir thread&#39;de koşuyor olması gerekir. TimeLimiter&#39;ın yaptığı iş, o future&#39;ın sonucunu belli bir süre beklemek ve süre dolunca beklemeyi bırakmaktır. Beklemeyi bıraktığında çağıran thread serbest kalır ve TimeoutException yoluyla fallback&#39;e düşer.</p><p>Buradaki inceliği baştan görün: TimeLimiter bir başka thread’de koşan işi bekler. O iş senkron ve tek thread’liyse, ortada beklenecek bir future yoksa, TimeLimiter’ın koyacağı bir yer yoktur. Bu yüzden Spring tarafında @TimeLimiter&#39;lı metot CompletableFuture dönmek zorundadır. Metot düz bir String dönerse, metot çağrıldığı anda zaten senkron olarak sonuna kadar çalışmış olur ve TimeLimiter&#39;ın araya gireceği hiçbir an kalmaz. İşte birinci yanılgının kaynağı burası: senkron bir metoda @TimeLimiter koyup korunduğunu sanmak. Bunu az sonra Spring bölümünde net kurala bağlayacağız.</p><h3>Timeout Attı Ama İş Arkada Koşuyor</h3><p>Bu bölüm yazının en önemli parçası, çünkü sahada en çok yanlış anlaşılan yer burası ve ikinci yanılgının kaynağı.</p><p>TimeLimiter bir TimeoutException attığında, çağıran thread&#39;iniz kurtulur. Ama arkada koşan iş otomatik olarak durmaz. TimeLimiter süreyi ölçer ve dolunca &quot;ben artık beklemiyorum&quot; der. Altta ayrı thread&#39;de koşan işin durup durmayacağı bambaşka bir sorudur.</p><figure><img alt="TimeLimiter timeout attıktan sonra caller kurtulur ama alttaki iş DB connection’ını iş bitene kadar tutmaya devam eder: caller 2. saniyede fallback alır, sorgu 8. saniyeye kadar connection ve thread işgal eder" src="https://cdn-images-1.medium.com/max/1024/1*RmVzFHOywiu_4P0qHY4Ksw.png" /></figure><p>Devreye cancelRunningFuture ayarı girer, ama davranışı kullandığınız varyanta göre değişir ve burada çoğu kaynağın atladığı bir ayrım var. Önce Future varyantını (executeFutureSupplier, örneğin bir ExecutorService.submit&#39;ten dönen Future) ele alalım. Orada cancelRunningFuture=true iken (default budur) TimeLimiter, timeout anında future.cancel(true) çağırır. Buradaki true argümanı mayInterruptIfRunning demektir: future&#39;ı çalıştıran thread&#39;e bir interrupt sinyali gönderir.</p><p>Ve işte tuzak: interrupt bir rica, emir değil. Çalışan iş ancak interrupt’a saygı gösteriyorsa durur. Java’da interrupt şu durumlarda işe yarar:</p><ol><li>İş Thread.sleep(), wait(), BlockingQueue.take() gibi interruptible bir bloklama noktasındaysa. Bu çağrılar interrupt&#39;ı InterruptedException atarak yakalar ve iş orada kesilir.</li><li>İş, Thread.currentThread().isInterrupted()&#39;ı düzenli kontrol edip kendini durduran döngü koduysa.</li></ol><p>Ama gerçek dünyadaki bloklayan çağrıların çoğu bu iki kategoriye girmez. Klasik örnek bir JDBC sorgusudur: soket üzerinde veritabanının cevabını bekleyen bir read() çağrısı, JVM&#39;in interrupt bayrağına genelde bakmaz. Bir InputStream.read(), bir native call, timeout&#39;suz bir HTTP client. Bunlar interrupt&#39;ı görmezden gelir ve iş, veritabanı ya da uzak servis cevap verene (veya kendi client timeout&#39;u patlayana) kadar arkada koşmaya devam eder.</p><p>Şimdi asıl kritik nokta, çünkü Spring tarafında neredeyse her zaman kullandığınız yol bu değil. @TimeLimiter annotation&#39;ı CompletableFuture (yani CompletionStage) döndüren metotları sarar ve Resilience4j bu yolda tamamen farklı bir implementasyon (decorateCompletionStage) kullanır. Orada cancelRunningFuture hiç okunmaz. TimeLimiter timeout anında altta koşan işe cancel bile çağırmaz, yalnızca sonucu tutan future&#39;ı completeExceptionally(TimeoutException) ile tamamlar. Üstüne, CompletableFuture.cancel(true) çağrılsaydı bile Java semantiğinde mayInterruptIfRunning bayrağı CompletableFuture için yok sayılır, yani hiçbir interrupt gitmez. İki neden de aynı kapıya çıkar: annotation yolunda arkadaki iş her zaman kendi doğal sonuna kadar koşar (sonucu sessizce çöpe atılır), iş interrupt&#39;a saygılı olsa bile.</p><p>Somut senaryo bunu bir yere oturtur. TimeLimiter’a 2 saniye verdiniz, altta JDBC üzerinden 8 saniye süren bir rapor sorgusu koşuyor ve o sorgu için queryTimeout koymamışsınız. 2. saniyede TimeLimiter TimeoutException atar, kullanıcıya fallback döner, herkes mutlu görünür. Ama o sorgu 8. saniyeye kadar bir DB connection&#39;ını ve bir thread&#39;i işgal etmeye devam eder. Trafik altında bu, &quot;timeout koydum ama bağlantı havuzum yine de tükeniyor&quot; şikayetinin tam kaynağıdır. TimeLimiter beklemeyi bıraktı, kaynağı bırakmadı.</p><p>Yazının çıkarımı net: TimeLimiter işi kaynağında durduramaz, sadece beklemeyi bırakır. İşin gerçekten durması için altta çalışan çağrının kendi client timeout’una sahip olması gerekir (yalnızca Future varyantında ayrıca interrupt&#39;a saygılı olması da işe yarar, annotation yolunda o kapı bile kapalı). Bu yüzden ilk bölümdeki söz burada kanıtlanıyor: TimeLimiter, client timeout&#39;un yerine geçmez. queryTimeout, commandTimeout, HTTP read timeout işi kaynağında keser. TimeLimiter iş birimine tavan koyar ama arkadaki işi ancak kaynak timeout&#39;u varsa gerçekten durdurur.</p><h3>Ayarlar: timeoutDuration ve cancelRunningFuture</h3><p>TimeLimiter’ın konfigürasyonu circuit breaker’a göre çok sade. İki ayar var:</p><pre>TimeLimiterConfig config = TimeLimiterConfig.custom()<br>        .timeoutDuration(Duration.ofSeconds(2))<br>        .cancelRunningFuture(true)<br>        .build();</pre><p><strong>timeoutDuration.</strong> İşin tamamlanması için tanınan süre. future.get() bu süre içinde dönmezse TimeoutException fırlar. Default Duration.ofSeconds(1)&#39;dir, yani 1 saniye. Bu değeri, korunan iş biriminin kabul edilebilir en uzun süresine göre seçin. Client timeout&#39;larının toplamından mantıklı biçimde büyük olmalı, yoksa TimeLimiter normal işleyişte bile durmadan tetiklenir.</p><p><strong>cancelRunningFuture.</strong> Timeout anında future.cancel(true) çağrılıp çağrılmayacağı. Default true&#39;dur. Ama bu ayar yalnızca Future varyantında (executeFutureSupplier) etkilidir: true iken TimeLimiter timeout anında future.cancel(true) ile interrupt gönderir (bir önceki bölümdeki tüm uyarılar geçerli, interrupt ancak iş saygı gösteriyorsa durdurur), false iken arkadaki future&#39;a hiç dokunulmaz. Kritik nokta şu: Spring&#39;in @TimeLimiter annotation&#39;ının kullandığı CompletableFuture yolunda bu ayar hiç okunmaz, orada timeout her zaman yalnızca completeExceptionally ile gerçekleşir ve arkadaki iş cancel edilmez. Yani true bırakın ama unutmayın: annotation yolunda true sihir bir yana, hiçbir şey yapmaz.</p><p>İki ayar bu kadar. Circuit breaker’ın sliding window’u, eşikleri, state machine’i gibi bir karmaşıklık yok. TimeLimiter bilinçli olarak dar kapsamlı bir araç: tek işi, bir future’ın beklemesine tavan koymak.</p><h3>Spring Boot ile Kullanım: CompletableFuture Şartı</h3><p>Programmatic API’yi gördük. Spring Boot entegrasyonu üç şey ekler: YAML konfigürasyonu, @TimeLimiter annotation&#39;ı ve annotation&#39;ın en katı kuralı olan CompletableFuture dönüş tipi zorunluluğu.</p><p>Bağımlılıklar circuit breaker’daki üçlünün aynısı: resilience4j-spring-boot3, spring-boot-starter-aop ve actuator. AOP starter&#39;ı yoksa annotation sessizce hiçbir şey yapmaz, bu tuzak TimeLimiter için de aynen geçerli.</p><p>YAML konfigürasyonu circuit breaker’daki gibi iki katmanlı: configs altında yeniden kullanılabilir tabanlar, instances altında isimli limiter&#39;lar.</p><pre>resilience4j:<br>  timelimiter:<br>    configs:<br>      default:<br>        timeoutDuration: 2s<br>        cancelRunningFuture: true<br>    instances:<br>      reportService:                    # @TimeLimiter&#39;dan bu isimle çağrılır<br>        baseConfig: default<br>      externalPricing:<br>        baseConfig: default<br>        timeoutDuration: 800ms          # bu bağımlılık için daha sıkı bütçe</pre><p>Annotation ile kullanım, çalışma modelinin doğrudan sonucu olan bir kurala bağlı:</p><pre>@Service<br>public class ReportService {<br>    @TimeLimiter(name = &quot;reportService&quot;, fallbackMethod = &quot;reportTimeout&quot;)<br>    public CompletableFuture&lt;Report&gt; buildReport(long id) {<br>        return CompletableFuture.supplyAsync(() -&gt; repository.heavyReport(id));<br>    }<br><br>    // fallback: aynı parametreler + sonda exception, aynı dönüş tipi<br>    private CompletableFuture&lt;Report&gt; reportTimeout(long id, TimeoutException e) {<br>        return CompletableFuture.completedFuture(Report.partial(id));<br>    }<br>}</pre><p>Buradaki en kritik kural şu: @TimeLimiter&#39;lı metot CompletableFuture (veya CompletionStage) dönmek zorundadır. Sebebi çalışma modelinde: TimeLimiter bir future&#39;ın beklemesine tavan koyar, ortada future yoksa yapacak işi yoktur. Diğer Resilience4j anotasyonları (@CircuitBreaker, @Retry, @RateLimiter, @Bulkhead) hem senkron hem asenkron dönüş tiplerini destekler, ama TimeLimiter bu konuda katıdır ve async tip ister. Metot senkron bir tip dönerse, Spring aspect&#39;i &quot;CompletionStage expected&quot; hatası verir.</p><p>Dikkat edilecek nokta metodun gerçekten asenkron olmasıdır. supplyAsync ile işi ayrı bir thread pool&#39;a atmak zorundasınız. Metot içinde senkron bloklayan bir çağrı yapıp sonucu completedFuture ile sarmak işe yaramaz: o durumda bloklama, metot CompletableFuture dönmeden önce olur, TimeLimiter&#39;ın araya gireceği an geçmiştir. Future, çağıran thread&#39;den farklı bir thread&#39;de koşmalı ki TimeLimiter beklerken çağıran thread serbest kalabilsin. Bir de bir önceki bölümün sonucunu unutmayın: bu annotation yolunda cancelRunningFuture devre dışıdır, yani heavyReport timeout&#39;tan sonra da thread pool&#39;da çalışmaya devam eder ve altında bir queryTimeout yoksa DB connection&#39;ını iş bitene kadar tutar. Onu gerçekten durduracak tek şey heavyReport&#39;un içindeki kaynak timeout&#39;udur.</p><p>Fallback imzası circuit breaker’daki kuralın aynısı: orijinal metotla aynı parametreler, sonuna eklenmiş bir exception parametresi (TimeoutException ya da daha genel Throwable), aynı dönüş tipi. İmza tutmazsa hata çalışma zamanında çıkar, derlemede değil.</p><h3>Circuit Breaker ile Kombinasyon</h3><p>TimeLimiter tek başına yavaş bir çağrının o örneğini keser ama circuit breaker gibi bir hafızası yoktur: her istek timeout acısını sıfırdan yaşar. Redis-down yazısındaki mantık burada da geçerli. Timeout bireysel savunma, breaker kolektif. İkisini birleştirmek istersiniz: TimeLimiter yavaşlığı tespit etsin, ürettiği timeout’lar breaker’ı beslesin, yeterince timeout birikince breaker açılıp bir süre hiç denemesin.</p><p>Bunun çalışması aspect sırasına bağlı. Resilience4j’nin default sarma sırası dıştan içe şöyledir:</p><pre>Retry ( CircuitBreaker ( RateLimiter ( TimeLimiter ( Bulkhead ( metot ) ) ) ) )</pre><p>TimeLimiter, CircuitBreaker’ın içinde. Yani önce TimeLimiter süreyi ölçer, timeout olursa TimeoutException atar, bu exception dışarı doğru CircuitBreaker katmanından geçer. CircuitBreaker onu gören dış katman olduğu için timeout&#39;u bir failure olarak kaydedebilir. Sıra ters olsaydı (CB içte) breaker timeout&#39;u hiç görmezdi. Bu sıra Resilience4j default&#39;udur ve aspect-order property&#39;leriyle değiştirilebilir, ama değiştirmeye gerek kalmadan doğru yönde gelir.</p><p>Kağıt üzerinde geri kalanı basit: circuit breaker’ın recordExceptions listesi default&#39;ta boştur ve boş liste &quot;tüm exception&#39;lar failure sayılır&quot; demektir. TimeoutException da bir exception olduğuna göre, default konfigürasyonda breaker&#39;a failure olarak yazılır. Yani teorik olarak @TimeLimiter artı @CircuitBreaker kombinasyonu ekstra bir ayar gerektirmeden timeout&#39;ları breaker&#39;a beslemeli.</p><p>Bu “kağıt üzerinde” kısmı gerçek bir Maven projesinde tatbikatla doğruladım (Resilience4j 2.3.0 artı Spring Boot 3.5.0). Düşük eşikli bir breaker (COUNT_BASED, slidingWindowSize=4, minimumNumberOfCalls=4, failureRateThreshold=50) ve 500 ms&#39;lik TimeLimiter&#39;ın arkasına 2 saniyelik iş kondu: ilk üç çağrı TimeoutException ile failure yazdı, dördüncü çağrıda failure rate yüzde 100 olup breaker OPEN&#39;a geçti, beşinciden itibaren istekler metoda hiç girmeden CallNotPermittedException ile reddedildi. Aspect order&#39;lar da bytecode&#39;dan teyitli: circuitBreakerAspectOrder değeri timeLimiterAspectOrder&#39;dan küçük, yani daha dış katman, sarım gerçekten CircuitBreaker(TimeLimiter(metot)). Kombinasyon annotation yolunda ekstra ayarsız, kutudan çıktığı gibi çalışıyor.</p><p>Peki Resilience4j’deki bilinen “timeout’lar oluyor ama breaker CLOSED’da kalıyor” raporları neyin nesi? Bu sürüm ve kurulumda reprodüke edilemedi. En öğretici kök sebep programmatic Decorators kullanımındaki sıra tuzağı ve tatbikatta birebir görüldü. .withTimeLimiter().withCircuitBreaker() (CB dış katman) annotation ile aynı doğru davranışı verir. Ters sıra (.withCircuitBreaker().withTimeLimiter(), CB iç katman) caller&#39;a her seferinde 500 ms&#39;de TimeoutException döndürür ama breaker hiç açılmaz. Çünkü içteki CB, TimeLimiter&#39;ın vazgeçtiği 2 saniyelik future&#39;ın kendisini izler. O future arkada sonunda başarıyla biter (bir önceki bölümü hatırlayın: annotation yolunda iş sonuna kadar koşar) ve CB hepsini success yazar. Dört çağrı sonunda metrik failed=0, success=4, state=CLOSED. Dışarıda timeout yağarken breaker&#39;ın kılını kıpırdatmaması tam bu tablodur. Diğer klasik sebepler: metodun gerçekten async olmaması, recordExceptions&#39;ın daraltılıp TimeoutException&#39;ın liste dışı kalması, ya da aspect-order property&#39;lerinin elle ters çevrilmesi.</p><p>Pratik sonuç değişmez: bu kombinasyonu varsayımla production’a almayın, kendi sürümünüzde tatbikatla doğrulayın. Staging’de yapay gecikme enjekte edin (redis-down yazısındaki Toxiproxy latency toxic’i), timeout’ların oluştuğunu görün ve resilience4j_circuitbreaker_failure_rate metriğinin arttığını, breaker&#39;ın OPEN&#39;a geçtiğini gözlerinizle doğrulayın.</p><h3>Client Timeout vs TimeLimiter: Hangisi Ne Zaman</h3><p>Şimdi ilk bölümde açtığımız soruyu bir kurala oturtabiliriz. İkisi de bir süreyi sınırlar ama farklı seviyelerde ve farklı garantilerle.</p><figure><img alt="İki katman: client timeout işi transport seviyesinde, kaynağında keser ve soketi serbest bırakır. TimeLimiter uygulama seviyesinde, use-case bütçesine dışarıdan tavan koyar ama arkadaki işi durdurmaz" src="https://cdn-images-1.medium.com/max/1024/1*jOdKdQxqfiFxEeoh_AiSPA.png" /></figure><figure><img alt="Client timeout vs TimeLimiter karşılaştırma tablosu: seviye (transport vs uygulama), neyi keser (I/O operasyonu kaynağında vs future beklemesi dışarıdan), işi durdurur mu (evet vs hayır), kapsam (tek çağrı vs uçtan uca bütçe), örnekler ve exception tipleri. Kural: önce client timeout, üstüne TimeLimiter" src="https://cdn-images-1.medium.com/max/1024/1*lydh9a8dRD-u7VxOhzJWEg.png" /></figure><p>Kural üç maddede:</p><ol><li><strong>Bağımlılığın kendi timeout ayarı varsa, önce onu koyun.</strong> commandTimeout, queryTimeout, HTTP client read timeout işi kaynağında keser ve kaynağı (soket, connection, thread) gerçekten serbest bırakır. Bu, TimeLimiter&#39;ın yapamadığı şeydir. Bunu atlarsanız &quot;timeout attı ama connection havuzu tükeniyor&quot; tuzağına düşersiniz.</li><li><strong>TimeLimiter’ı iki durum için ekleyin:</strong> timeout ayarı olmayan ya da kontrol edemediğiniz bir çağrının etrafına dışarıdan süre sınırı koymak, ve birden çok alt çağrıyı kapsayan bir use-case’e tek bir uçtan uca tavan koyup bunu circuit breaker artı fallback artı metrikle entegre etmek.</li><li><strong>En sağlam kurulum ikisini birlikte kullanır.</strong> Client timeout kaynak sızıntısını önler (işi durdurur), TimeLimiter genel bütçeyi dayatır ve resilience stack’e bağlar.</li></ol><p>Redis-down piramidine oturtalım. Oradaki hiyerarşi Redis komutu (~100 ms) küçüktür DB sorgusu (~1–2 sn) küçüktür endpoint (~5 sn) küçüktür LB (~30 sn) idi. Bu piramitteki her kademe bir client/katman timeout’uydu. TimeLimiter bu piramidin neresine oturur? “Endpoint” seviyesine, yani use-case bütçesine. Alt katmanların (Redis, DB) kendi client timeout’ları işi kaynağında keserken, TimeLimiter tüm use-case’in toplam süresine tavan koyar ve o tavana çarpıldığında circuit breaker’ı besler. Client timeout’lar tek tek tuğlaları bağlar, TimeLimiter binanın tamamına bir üst sınır çizer.</p><p>Buradan pratik bir sonuç çıkar ki TimeLimiter’ın nereye ait olmadığını da gösterir: tek bir Redis komutunu tek başına @TimeLimiter&#39;a sarmak marjinal değer katar, çünkü Lettuce&#39;ın commandTimeout&#39;u o komutu zaten ~100 ms&#39;de kaynağında kesiyor ve soketi bırakıyor. Aynı şey kendi read timeout&#39;unu koyduğunuz tekil bir HTTP çağrısı için de geçerli. TimeLimiter asıl değerini başka yerde kazanır: kendi timeout&#39;u zayıf ya da hiç olmayan çağrıları (timeout knob&#39;ı vermeyen bir SDK, bloklayan legacy kütüphane, client timeout&#39;u eksik yavaş bir üçüncü parti API) dışarıdan bir süreyle sarmakta ve birden çok alt çağrıyı kapsayan use-case&#39;e uçtan uca tavan koymakta.</p><h3>Tuning Rehberi ve Klasik Hatalar</h3><p>Ayar değerleri korunan iş biriminin karakterine göre seçilir. Pratik akıl yürütme:</p><ol><li><strong>timeoutDuration’ı use-case’in kabul edilebilir en uzun süresine göre seçin,</strong> alt çağrıların toplamının biraz üstünde. Çok sıkı tutarsanız normal işleyişte bile timeout üretir ve breaker’ı boş yere açar. Çok gevşek tutarsanız TimeLimiter’ın koruması geç devreye girer.</li><li><strong>Async thread pool’unu boyutlandırın.</strong> @TimeLimiter metodu supplyAsync ile ayrı bir executor&#39;da koşar. Default ForkJoinPool.commonPool() sınırlıdır ve başka işlerle paylaşılır. Yük altında kendi executor&#39;ınızı tanımlayın, yoksa TimeLimiter&#39;ın koruması thread açlığına dönüşür.</li><li><strong>Altta mutlaka bir kaynak timeout’u olsun.</strong> “Timeout attı ama iş arkada koşuyor” bölümünün dersi: TimeLimiter’ın kestiği iş interruptible değilse (ve annotation yolunda hiç değilse) arkada koşmaya devam eder. TimeLimiter’ı client timeout olmadan tek başına koymak, kaynak sızıntısını gizler ama çözmez.</li></ol><p>Sahada en sık görülen hatalar:</p><ol><li><strong>@TimeLimiter&#39;lı metodun senkron dönüş tipi dönmesi.</strong> Metot Report dönerse (CompletableFuture değil) TimeLimiter&#39;ın araya gireceği an yoktur, Spring aspect&#39;i &quot;CompletionStage expected&quot; ile şikayet eder. Async dönüş tipi zorunlu. İlk yanılgı.</li><li><strong>İşi gerçekten async’e atmadan </strong><strong>completedFuture ile sarmak.</strong> Bloklama metot dönmeden önce olur, TimeLimiter geç kalır. supplyAsync ile ayrı thread&#39;e atmak şart.</li><li><strong>TimeLimiter’ı client timeout’un yerine koymak.</strong> “TimeLimiter koydum, artık queryTimeout&#39;a gerek yok&quot; yanılgısı. Connection sızıntısı tam bu yüzden olur. TimeLimiter beklemeyi bırakır, işi durdurmaz. İkinci yanılgı.</li><li><strong>CB kombinasyonunda kurulum hatası.</strong> Annotation yolu default’ta doğru çalışır ama programmatic Decorators&#39;ta sıra ters kurulursa (CB içte) breaker timeout&#39;ları hiç görmez, gecikmeli başarıları success yazar ve asla açılmaz. recordExceptions&#39;ı daralttıysanız timeout listeden düşmüş olabilir. Tatbikatla failure_rate&#39;in arttığını görmeden güvenmeyin.</li><li><strong>cancelRunningFuture’ı sihir sanmak.</strong> Future varyantında true interrupt gönderir ve yalnızca interrupt&#39;a saygılı işleri temizler, native/bloklayan işlere dokunmaz. Spring&#39;in @TimeLimiter artı CompletableFuture yolunda ise ayar hiç okunmaz, hiçbir cancel/interrupt olmaz. Her iki durumda da tek gerçek savunma alttaki kaynak timeout&#39;udur.</li></ol><h3>Kapanış</h3><p>TimeLimiter’ın özü tek cümle: başka bir thread’de koşan bir işin beklemesine tavan koy ve süre dolunca beklemeyi bırak. İşi kaynağında durdurmaz, sadece vazgeçer. Bu yüzden client timeout’un rakibi değil, tamamlayıcısıdır: client timeout işi kaynağında keser ve kaynağı serbest bırakır, TimeLimiter iş birimine uçtan uca bir bütçe koyar ve o bütçeyi circuit breaker artı fallback artı metrikle bütünleştirir.</p><p>Baştaki iki yanılgıya dönelim, çünkü yazının bütünü onların üstüne kuruldu. Birincisi, TimeLimiter senkron bir metodu korumaz. Yalnızca CompletableFuture dönen, gerçekten ayrı thread&#39;de koşan metotlarda çalışır, çünkü koyacağı bir bekleme ancak o zaman vardır. İkincisi, TimeLimiter işi durdurmaz. Caller&#39;ı kurtarır ama arkadaki iş, özellikle Spring&#39;in kullandığı CompletableFuture yolunda, kendi sonuna kadar koşar ve altında bir kaynak timeout&#39;u yoksa connection&#39;ı tutmaya devam eder.</p><p>Serideki yerini de netleştirelim. Redis-down yazısında timeout hiyerarşisi (katman 1) her bağımlılığa kendi client timeout’unu koyuyordu. TimeLimiter o piramidin üstüne, use-case seviyesine oturur: alt katmanlar tuğlaları kaynağında bağlarken TimeLimiter binanın tamamına üst sınır çizer ve çarptığında circuit breaker’ı (katman 2) besler. Serinin bir sonraki ve son halkası retry, tek bir çağrının anlık hıçkırığına ikinci şans verir. Timeout, circuit breaker, bulkhead, rate limiter, time limiter ve retry birbirinin alternatifi değil, katmanlı savunmanın parçalarıdır.</p><h3>Kaynaklar</h3><ul><li><a href="https://resilience4j.readme.io/docs/timeout">Resilience4j — TimeLimiter</a> — çalışma modeli, executeFutureSupplier / executeCompletionStage, config alanları</li><li><a href="https://resilience4j.readme.io/docs/getting-started-3">Resilience4j — Spring Boot 3 Getting Started</a> — @TimeLimiter, aspect sırası, fallback</li><li><a href="https://github.com/resilience4j/resilience4j/blob/master/resilience4j-timelimiter/src/main/java/io/github/resilience4j/timelimiter/TimeLimiterConfig.java">TimeLimiterConfig kaynağı (GitHub)</a> — default’lar: timeoutDuration 1s, cancelRunningFuture true</li><li><a href="https://github.com/resilience4j/resilience4j/blob/master/resilience4j-timelimiter/src/main/java/io/github/resilience4j/timelimiter/internal/TimeLimiterImpl.java">TimeLimiterImpl kaynağı (GitHub)</a> — decorateCompletionStage’in cancelRunningFuture’ı okumadığı, timeout’u completeExceptionally ile gerçekleştirdiği yer</li><li><a href="https://medium.com/@gungor.akbiyik/circuit-breaker%C4%B1-do%C4%9Fru-kurmak-state-machine-den-production-tuning-e-d998755ec722">Circuit Breaker’ı Doğru Kurmak</a> — kombinasyonun öteki yarısı: state machine, sliding window, recordExceptions</li><li><a href="https://medium.com/@gungor.akbiyik/bulkheadi-do%C4%9Fru-kurmak-i%CC%87zolasyondan-production-tuning-e-0b6c53c62a83">Bulkhead’i Doğru Kurmak</a> — serinin ikinci halkası: izolasyon, semaphore vs thread pool, maxWaitDuration</li><li><a href="https://medium.com/@gungor.akbiyik/redis-down-kolay-senaryo-as%C4%B1l-katil-yava%C5%9F-redis-606ff189525c">Redis Down Kolay Senaryo. Asıl Katil: Yavaş Redis</a> — bu yazının bağlamı: timeout hiyerarşisi ve katmanlı savunmanın bütünü</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=94acb0f8d3cb" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Rate Limiter’ı Doğru Kurmak: Cycle ve Permission’dan Dağıtık Sınırın Ötesine]]></title>
            <link>https://medium.com/@gungor.akbiyik/rate-limiter%C4%B1-do%C4%9Fru-kurmak-cycle-ve-permission-dan-da%C4%9F%C4%B1t%C4%B1k-s%C4%B1n%C4%B1r%C4%B1n-%C3%B6tesine-a8f759ee698a?source=rss-3597415c14fc------2</link>
            <guid isPermaLink="false">https://medium.com/p/a8f759ee698a</guid>
            <dc:creator><![CDATA[Güngör Akbıyık]]></dc:creator>
            <pubDate>Sat, 18 Jul 2026 05:13:42 GMT</pubDate>
            <atom:updated>2026-07-18T05:13:42.902Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ufzvU7DMDF6Yqe02Zi56tw.png" /></figure><p>Üçüncü parti bir API ile çalışıyorsunuz. Servis sağlıklı, hızlı, ortada hiçbir arıza yok. Ama sözleşmede tek bir satır var: saniyede en fazla 100 istek, fazlasına 429. Trafiğiniz büyüdüğü ilk gün o sınırı aşıyorsunuz ve sağlayıcı bir süreliğine sizi komple kapının dışına koyuyor. Sorun bir yavaşlık değil, bir arıza da değil. Sorun sizin <em>çıkış hızınız</em>.</p><p>Serinin <a href="https://medium.com/@gungor.akbiyik/circuit-breaker%C4%B1-do%C4%9Fru-kurmak-state-machine-den-production-tuning-e-d998755ec722">circuit breaker</a> ve bulkhead yazılarının kardeşi olarak düşünün bunu. Circuit breaker “kaybedeceği belli bahsi oynama” diyordu, bulkhead “aynı anda kaç bahis oynayabileceğini sınırla” diyordu. Rate limiter üçüncü bir soruya cevap veriyor: birim zamanda kaç bahis oynayabilirsin? Üçü de resilience ailesinin farklı üyeleri ve sık sık birbirine karıştırılırlar. Bu yazıda hem rate limiter’ı sıfırdan kuruyoruz hem de o karışıklığı netleştiriyoruz.</p><h3>Neden Hızı Sınırlamak Gerekir?</h3><p>Elinizde çalışan bir bağımlılık var. Bozuk değil, yavaş değil, gayet sağlıklı. Ama bir kuralı var: “bana saniyede en fazla 100 istek gönderebilirsin, fazlasına 429 dönerim.” Üçüncü parti bir API’nin quota’sı, iş ortağının rate limit’i, ya da kendi altyapınızdaki paylaşılan bir kaynağın koruması. Circuit breaker burada işe yaramaz. Ortada arıza yok ki devre açasınız.</p><p>Ya da tam tersi yöndesiniz. Siz bir servissiniz ve gelen trafiği kısmak istiyorsunuz. Bir endpoint’e dakikada 10&#39;dan fazla istek gelmesin, çünkü arkasında pahalı bir hesaplama var ve kötü niyetli ya da hatalı bir client sistemi boğmasın.</p><p>Her iki senaryonun ortak paydası zaman. Circuit breaker geçmiş çağrıların <em>sonucuna</em> bakar (kaçı başarısız). Rate limiter geçmiş çağrıların <em>sayısına ve zamanlamasına</em> bakar (birim zamanda kaç tane). Biri sağlık ölçer, öteki hız.</p><p>Bu yazının ağırlığı ilk senaryoda: kendi çıkış trafiğinizi bir quota’ya sığdırmak. Buna client-side rate limiting denir ve Resilience4j’nin tipik kullanımı budur. İleride gelen trafiği kısan server-side yönüne ve dağıtık dünyaya da değineceğiz, ama önce tek JVM içindeki bu çekirdek durumu tam oturtalım.</p><h3>Çalışma Modeli: Cycle ve Permission</h3><p>Resilience4j’nin rate limiter’ı iki kavram üzerine kurulu: <strong>cycle</strong> (döngü) ve <strong>permission</strong> (izin).</p><p>Zaman, limitRefreshPeriod uzunluğunda eşit dilimlere bölünür. Her dilim bir cycle&#39;dır. Her cycle&#39;ın başında rate limiter, kullanılabilir permission sayısını limitForPeriod&#39;a sıfırlar. Bir çağrı yapmak istediğinizde bir permission harcarsınız. Cycle içindeki permission&#39;lar bittiğinde yeni çağrılar bir sonraki cycle&#39;ı bekler.</p><p>Somut örnek. limitForPeriod = 100, limitRefreshPeriod = 1s dediniz. Saat 12:00:00.000&#39;da cycle başlar, elinizde 100 permission var. İlk 100 çağrı sorunsuz geçer. 101. çağrı geldiğinde permission kalmamıştır. 12:00:01.000&#39;da yeni cycle başlar, sayaç yine 100&#39;e sıfırlanır ve bekleyen çağrı geçer.</p><figure><img alt="Cycle ve permission modeli: zaman limitRefreshPeriod uzunluğunda dilimlere bölünür, her dilim başında permission havuzu limitForPeriod’a sıfırlanır, havuz boşsa çağrı bir sonraki cycle’dan rezervasyon yapıp bekler" src="https://cdn-images-1.medium.com/max/1024/1*ZH6TGWpxfmCmtNl6oWF9nw.png" /></figure><p>Default implementasyon AtomicRateLimiter&#39;dır ve içinde tuttuğu state üç alandan ibarettir:</p><ul><li><strong>activeCycle</strong> — son çağrının denk geldiği cycle numarası.</li><li><strong>activePermissions</strong> — o an kalan permission sayısı. Dikkat: bu sayı <em>negatif</em> olabilir. Bir thread henüz gelmemiş bir cycle’ın permission’ını rezerve edip onu beklemeye geçebilir.</li><li><strong>nanosToWait</strong> — son çağrının bir permission için ne kadar beklemesi gerektiği.</li></ul><p>Bu üçlünün tamamı tek bir immutable nesnede tutulur ve her çağrıda atomik bir compare-and-set ile güncellenir. Kilit yok, senkronizasyon bloğu yok. Rate limiter’ın yüksek trafik altında ucuz olmasının sebebi bu.</p><p>Buradaki en önemli nüans <strong>rezervasyon</strong> mekanizmasıdır. Permission bittiğinde thread hemen reddedilmez. Rate limiter, gelecekteki bir cycle’dan bir permission ödünç alır (activePermissions negatife düşer), o permission’ın ne zaman “olgunlaşacağını” hesaplar (nanosToWait) ve thread’i o kadar bekletir. Bu yüzden Resilience4j’nin rate limiter’ı sadece “geçeni geçir, kalanı reddet” yapan kaba bir sayaç değildir. Trafiği zamana <strong>yayar</strong>, kuyruğa alır. Bu davranışın sınırını timeoutDuration belirler, ki birazdan kendi bölümünü hak edecek kadar önemli.</p><h3>Hangi Algoritma? Token Bucket’a En Yakın</h3><p>Rate limiting’in kitabında dört klasik algoritma vardır. Resilience4j’yi doğru yere koymak için önce bunları kısaca tanıyalım.</p><p><strong>Token bucket.</strong> Bir kova düşünün, içinde token’lar var. Token’lar sabit bir hızla kovaya damlar (saniyede N tane) ve kovanın bir kapasite tavanı vardır. Her istek bir token harcar, token yoksa reddedilir. Kova dolu beklediği için ani bir yük geldiğinde kapasitesi kadar <strong>burst</strong>’e izin verir, sonra damlama hızına oturur. Damlama sürekli ve akışkandır.</p><p><strong>Leaky bucket.</strong> Bu sefer kova bir kuyruk gibidir, altında sabit hızda akan bir delik var. İstekler kovaya girer, delikten sabit hızla çıkar (işlenir). Kova taşarsa yeni istekler reddedilir. Token bucket burst’e izin verir, leaky bucket vermez: çıkış hızı her zaman sabittir, trafiği düzleştirir.</p><p><strong>Fixed window.</strong> Zamanı sabit pencerelere böl (her saniye, her dakika), her pencerede bir sayaç tut, sayaç limiti geçince pencere bitene kadar reddet. Basittir ama bir kusuru vardır: pencere sınırında <strong>çift burst</strong>. Bir pencerenin son anında limit kadar, hemen ardından yeni pencerenin ilk anında yine limit kadar istek geçebilir. Kısa bir anda limitin iki katı trafik sızar.</p><p><strong>Sliding window.</strong> Fixed window’un sınır problemini kayan bir pencere ile yumuşatır. Sabit takvim dilimleri yerine “şu andan geriye N saniye” penceresine bakar. Daha adildir ama tutması daha pahalıdır.</p><p>Resilience4j’nin modeli tam olarak bunların hangisi? Dürüst cevap: hiçbirinin ders kitabı hali değil, ama en çok token bucket’ın <em>kullanım hissini</em> verir. Her cycle başında permission’ların toptan limitForPeriod&#39;a sıfırlanması mekanik olarak fixed window&#39;a benzer (damlama değil, cycle sınırında toplu yenileme). Ama bir önceki bölümdeki rezervasyon mekanizması, fixed window&#39;un o çirkin çift-burst kusurunu kapatır: permission bittiğinde thread anında reddedilip yeni pencerede tekrar patlamaz, gelecek cycle&#39;dan rezervasyon yapıp bekler ve trafik zamana yayılır. Bu bekletme boyutu leaky bucket&#39;ın kuyruk mantığına yakındır.</p><p>Yani pratikte davranışı şöyle özetleyebilirsiniz: periyodik olarak yenilenen bir permission havuzu, üstüne “havuz boşsa sıradaki dolumu bekleyebilirsin” pacing’i. Kullanırken token bucket gibi düşünmek en az yanıltıcı olanıdır: her periyotta N hakkın var, bittiyse bir sonraki dolumu bekleyebilirsin.</p><h3>Ayarlar Tek Tek</h3><p>Rate limiter’ın konfigürasyonu circuit breaker’a kıyasla çok daha küçük. Üç ana ayar ve iki yardımcı. Önce kod, sonra satır satır:</p><pre>RateLimiterConfig config = RateLimiterConfig.custom()<br>        // --- çekirdek üçlü ---<br>        .limitForPeriod(100)                            // periyot başına izin sayısı<br>        .limitRefreshPeriod(Duration.ofSeconds(1))      // periyot uzunluğu<br>        .timeoutDuration(Duration.ofMillis(500))        // izin için bekleme üst sınırı <br>  <br>        // --- yardımcılar ---<br>        .writableStackTraceEnabled(false)               // exception stack trace&#39;i yaz/yazma<br>        .drainPermissionsOnResult(response -&gt;           // sonuca göre kalan izinleri boşalt<br>                response.statusCode() == 429)<br>        .build();</pre><p><strong>limitForPeriod.</strong> Bir cycle içinde kaç çağrıya izin verildiği. Rate limit’inizin sayısal karşılığı. Quota’nız “saniyede 100” ise bu 100&#39;dür. <strong>Default 50.</strong> Bu ayar tek başına anlamsızdır, çünkü “50” sorusunun tamamı “hangi süre içinde 50” ile tamamlanır. Bir sonraki ayarla çift olarak düşünülür.</p><p><strong>limitRefreshPeriod.</strong> Cycle’ın uzunluğu, yani permission havuzunun ne sıklıkla yenilendiği. limitForPeriod ile birlikte gerçek hızı verir: limitForPeriod / limitRefreshPeriod. Saniyede 100 için 100 / 1s, dakikada 20 için 20 / 60s. <strong>Default </strong><strong>Duration.ofNanos(500)</strong>, yani 500 nanosaniye. Bu default&#39;a iyi bakın: 500 nanosaniyede 50 permission, saniyede yaklaşık yüz milyon çağrı demektir. Yani pratikte sınırsız. Bu bilinçli bir tasarım. Default konfigürasyon hiçbir şeyi kısmaz, rate limiter&#39;ı gerçekten kullanmak istiyorsanız bu iki değeri <strong>mutlaka</strong> kendiniz vermek zorundasınız. Circuit breaker&#39;daki minimumNumberOfCalls tuzağının rate limiter&#39;daki karşılığı budur: değerleri set etmeyi unutursanız koruma sessizce devre dışı kalır, hata da vermez.</p><p><strong>timeoutDuration.</strong> Permission yokken thread’in ne kadar bekleyeceğinin üst sınırı. Rate limiter’ın en karakteristik ayarı ve bir sonraki bölümde tek başına ele alacağım kadar önemli. <strong>Default </strong><strong>Duration.ofSeconds(5).</strong> Kısaca: permission hazır değilse thread bu süre kadar bekler, süre içinde bir permission açılırsa geçer, açılmazsa RequestNotPermitted fırlatılır.</p><p><strong>writableStackTraceEnabled.</strong> RequestNotPermitted fırlatıldığında stack trace üretilsin mi. <strong>Default true.</strong> Neden false yapmak isteyesiniz? Çünkü rate limit&#39;e takılan çağrı <em>beklenen</em> bir durumdur, bir bug değil. Yüksek trafikte saniyede binlerce RequestNotPermitted fırlıyorsa, her birinin stack trace&#39;ini doldurmak ölçülebilir bir CPU maliyetidir ve log&#39;ları da şişirir. Rate limit&#39;in sık tetiklendiği yollarda false yapmak makul bir optimizasyondur.</p><p><strong>drainPermissionsOnResult.</strong> İnce ve az bilinen bir ayar. Çağrının sonucuna bakıp “bu cycle’da kalan tüm permission’ları hemen boşalt” kararı verir. <strong>Default, her zaman false dönen bir predicate</strong>, yani hiçbir zaman boşaltmaz. Ne işe yarar? Rate limiter’ınız saniyede 100&#39;e ayarlı ama karşı taraf yine de 429 döndüyse, demek ki sizin saydığınızla onun saydığı tutmuyor (saat kayması, paylaşılan quota, başka bir client). Böyle bir cevap geldiğinde kalan permission’ları boşaltarak o periyodun geri kalanında karşı tarafa hiç gitmemeyi seçebilirsiniz. Karşı tarafın sinyalini kendi sayacınıza geri besleme mekanizması.</p><h3>timeoutDuration: Bekle ya da Reddet</h3><p>Rate limiter’ı circuit breaker’dan ve bulkhead’den ayıran asıl davranış bu ayarda saklı, o yüzden kendi bölümünü hak ediyor.</p><p>Permission bittiğinde rate limiter’ın iki seçeneği var: bekleyen çağrıyı hemen reddetmek ya da bir sonraki dolumu bekletmek. timeoutDuration bu ikilemi tek sayıyla ayarlar.</p><figure><img alt="timeoutDuration ikilemi: permission bittiğinde 0 ise çağrı anında RequestNotPermitted alır (fail fast), 0&#39;dan büyükse bir sonraki cycle’ın dolumunu bekler ve permission açılınca geçer (kuyruğa gir)" src="https://cdn-images-1.medium.com/max/1024/1*CgBddLAij7L2wjuavA8vVA.png" /></figure><p><strong>timeoutDuration = 0.</strong> Beklemek yok. Permission yoksa çağrı anında RequestNotPermitted alır. Bu &quot;fail fast&quot; modudur. Ne zaman istersiniz? Latency&#39;ye duyarlı, kullanıcının beklemesinin anlamsız olduğu yollarda. Bir web isteğini rate limit&#39;e takıldı diye 3 saniye askıda tutmaktansa hemen 429 dönüp client&#39;a &quot;sonra dene&quot; demek daha dürüsttür.</p><p><strong>timeoutDuration &gt; 0.</strong> Beklemek var. Permission bir sonraki cycle’da açılacaksa ve bu bekleme timeoutDuration’ın içindeyse, thread bloke olur ve permission açılınca geçer. Bu “kuyruğa gir” modudur. Ne zaman istersiniz? Arka plan işlerinde, batch çağrılarında, üçüncü parti bir API’nin quota’sına uyarken. Orada amaç isteği kaybetmemek, sadece hızı quota’ya sığdırmak. 5 saniye beklemek sorun değil, isteği düşürmek sorun.</p><p>Değeri seçerken şu dengeye bakılır: timeoutDuration ne kadar uzunsa o kadar az istek reddedilir ama bekleyen thread’ler o kadar birikir. Senkron bir servlet thread modelinde uzun timeout, tüm thread pool’unun rate limiter kuyruğunda beklerken tükenmesine yol açabilir. O yüzden “kaç istek kaybını tolere ederim” ile “kaç thread’i bekletmeyi tolere ederim” arasında seçim yaparsınız.</p><h3>Bulkhead ile Farkı</h3><p>Bu noktada rate limiter, bulkhead ile sık karıştırılır. İkisi de “çok fazla” durumunu engeller ama farklı boyutta.</p><p><strong>Bulkhead eş zamanlılığı sınırlar: aynı anda en fazla N çağrı.</strong> Bir kaynağa aynı anda 10 çağrının içeride olmasına izin verir, 11.’si ya bekler ya reddedilir. Ölçtüğü şey <em>o an içeride kaç tane var</em>. Çağrılar ne kadar sürüyorsa o kadar uzun yer tutarlar.</p><p><strong>Rate limiter hızı sınırlar: birim zamanda en fazla N çağrı.</strong> Saniyede 100 çağrının <em>başlamasına</em> izin verir. Bir çağrının ne kadar sürdüğü umurunda değildir, sadece başlama hızını sayar.</p><p>Örnekle netleşir. Saniyede 100 istek yapan ama her biri 10 saniye süren bir yol düşünün. Rate limiter (saniyede 100) bundan hiç rahatsız olmaz, hız kuralına uyuluyor. Ama bir anda içeride 1000 çağrı birikmiş olur (100/sn × 10sn), bu da bağlantı havuzunu ya da thread’leri tüketebilir. Burada bulkhead (aynı anda en fazla 50) devreye girer ve eş zamanlı sayıyı tutar. İki koruma dik boyutlarda çalışır, biri diğerinin yerini tutmaz. Circuit breaker dersindeki sarma sırasını hatırlayın: Retry(CircuitBreaker(RateLimiter(TimeLimiter(Bulkhead(metot))))). Rate limiter ve bulkhead aynı zincirde, ayrı halkalar, çünkü ayrı şeyleri ölçerler.</p><h3>Spring Boot ile Kullanım</h3><p>Programmatic API’yi gördük. Gerçek projede Spring entegrasyonu aynı circuit breaker’daki üç şeyi ekler: YAML’dan konfigürasyon, annotation ile kullanım, actuator ile gözlem.</p><h3>Bağımlılıklar</h3><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;io.github.resilience4j&lt;/groupId&gt;<br>    &lt;artifactId&gt;resilience4j-spring-boot3&lt;/artifactId&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>    &lt;artifactId&gt;spring-boot-starter-aop&lt;/artifactId&gt;   &lt;!-- annotation&#39;lar AOP ile çalışır --&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>    &lt;artifactId&gt;spring-boot-starter-actuator&lt;/artifactId&gt;  &lt;!-- health + events + metrics --&gt;<br>&lt;/dependency&gt;</pre><p>Circuit breaker’daki aynı tuzak burada da geçerli. AOP starter’ı unutulursa @RateLimiter annotation&#39;ı sessizce hiçbir şey yapmaz. Exception yok, uyarı yok, koruma yok.</p><h3>YAML Konfigürasyonu</h3><pre>resilience4j:<br>  ratelimiter:<br>    configs:<br>      default:                                  # paylaşılan taban konfigürasyon<br>        limitForPeriod: 100<br>        limitRefreshPeriod: 1s<br>        timeoutDuration: 500ms<br>        registerHealthIndicator: true<br>        eventConsumerBufferSize: 100<br>    instances:<br>      externalApi:                              # bu isimle @RateLimiter&#39;dan çağrılır<br>        baseConfig: default<br>      reportExport:<br>        baseConfig: default<br>        limitForPeriod: 10                       # ağır endpoint, dakikada 10<br>        limitRefreshPeriod: 60s<br>        timeoutDuration: 0                        # beklemeden reddet</pre><p>Yapı circuit breaker’la birebir aynı iki katmanlı: configs altında yeniden kullanılabilir tabanlar, instances altında isimli limiter&#39;lar. Her instance bir tabandan miras alıp (baseConfig) istediği alanı ezer. Örnekte externalApi taban değerleri aynen kullanırken, reportExport ağır bir endpoint olduğu için hem hızı düşürüyor hem timeoutDuration&#39;ı 0 yapıp fail-fast&#39;e geçiyor.</p><p>Granülarite kuralı da aynı: <strong>limiter’lar korunan kaynak başına ayrılır.</strong> Her farklı quota’nın kendi limiter’ı olur. İki bağımsız üçüncü parti API aynı limiter’ı paylaşırsa birinin trafiği ötekinin quota’sını tüketir.</p><h3>Annotation ile Kullanım</h3><pre>@Service<br>public class WeatherApiClient {<br><br>    @RateLimiter(name = &quot;externalApi&quot;, fallbackMethod = &quot;rateLimited&quot;)<br>    public WeatherReport fetch(String city) {<br>        return restClient.get()<br>                .uri(&quot;/weather?q={city}&quot;, city)<br>                .retrieve()<br>                .body(WeatherReport.class);<br>    }<br><br>    // fallback: aynı parametreler + sonda RequestNotPermitted, aynı dönüş tipi<br>    private WeatherReport rateLimited(String city, RequestNotPermitted ex) {<br>        return WeatherReport.unavailable(city);   // quota doldu, bayat/boş veri dön<br>    }<br>}</pre><p>name = &quot;externalApi&quot; YAML&#39;daki instance&#39;a bağlanır. Fallback imza kuralı circuit breaker&#39;daki ile aynıdır: orijinal metotla aynı parametreler, sonuna eklenmiş bir exception parametresi, aynı dönüş tipi. Buradaki exception RequestNotPermitted&#39;dır, yani &quot;hızın aşıldı&quot; sinyali. İmza tutmazsa hata derleme zamanında değil çalışma zamanında patlar.</p><p>Fallback tanımlamak zorunda değilsiniz. Vermezseniz rate limit aşıldığında RequestNotPermitted çağıran koda kadar yükselir ve orada yakalanır. Fallback&#39;in olduğu senaryo genelde &quot;quota doldu, çağrıyı yumuşakça geçiştir&quot; istediğiniz yerdir. Fail-fast istediğiniz yerde ise fallback yerine exception&#39;ı bir @ControllerAdvice ile 429&#39;a çevirmek daha temizdir.</p><h3>Programmatic Kullanım (Spring İçinde)</h3><p>Annotation her yere uymaz: dinamik limiter ismi gerekiyor, lambda içindesiniz, ya da AOP’nin self-invocation tuzağından kaçınmak istiyorsunuz. Starter bir RateLimiterRegistry bean&#39;i verir:</p><pre>@Service<br>public class WeatherApiClient {<br>    private final RateLimiter limiter;<br><br>    public WeatherApiClient(RateLimiterRegistry registry) {<br>        this.limiter = registry.rateLimiter(&quot;externalApi&quot;);   // YAML&#39;daki instance<br>    }<br><br>    public WeatherReport fetch(String city) {<br>        try {<br>            return limiter.executeSupplier(() -&gt; callApi(city));<br>        } catch (RequestNotPermitted ex) {<br>            return WeatherReport.unavailable(city);   // quota doldu<br>        }<br>    }<br>}</pre><p>Circuit breaker dersindeki self-invocation uyarısı burada da aynen geçerli. @RateLimiter AOP proxy&#39;si üzerinden çalışır, aynı class içinden this.fetch(city) çağrısı proxy&#39;yi bypass eder ve limiter devreye girmez. Böyle durumda ya çağrıyı başka bean&#39;e taşırsınız ya bu programmatic yola dönersiniz.</p><h3>Kullanıcı Bazında Rate Limit — Olur mu?</h3><p>Buraya kadar limiter’lar hep sabit isimli tekil kaynaklardı: externalApi, smsProvider. Peki &quot;her kullanıcıya dakikada 10 istek&quot; gibi anahtar bazlı bir limit Resilience4j ile kurulabilir mi? Teknik olarak evet, çünkü registry aslında isimden limiter&#39;a giden bir map&#39;tir ve isim herhangi bir string olabilir:</p><pre>RateLimiter userLimiter = registry.rateLimiter(&quot;user:&quot; + userId, &quot;perUser&quot;);<br>userLimiter.executeSupplier(() -&gt; handle(request));</pre><p>İlk çağrıda user:42 için yeni bir limiter yaratılır (kendi bağımsız token bucket&#39;ı ile), sonraki çağrılar aynısını bulur. İkinci parametre YAML&#39;daki configs.perUser tabanına bağlar. Bunu vermezseniz her kullanıcı bulkhead dersindeki hayalet-instance tuzağının aynısıyla default config&#39;ten doğar. Annotation yolu bile destekler, çünkü name alanı SpEL kabul eder ve tam bu senaryo için bir configuration alanı vardır:</p><pre>@RateLimiter(name = &quot;#a0&quot;, configuration = &quot;perUser&quot;)   // #a0 = ilk parametre (userId)<br>public Response handle(String userId, Request request) { ... }</pre><p>Ama “yapılabilir” ile “yapmalısınız” arasında iki ciddi mesafe var. <strong>Birincisi ölçek ve bellek.</strong> Her farklı anahtar registry’de kalıcı bir instance yaratır: state, event publisher, health/metrik kaydı ile birlikte. Registry’de otomatik eviction yoktur. On binlerce kullanıcıda bu hem bellek sızıntısına hem Micrometer’da tag cardinality patlamasına dönüşür (her limiter ayrı metrik serisi). Temizlik isterseniz registry.remove(name) ile elle yapmanız gerekir. <strong>İkincisi dağıtıklık.</strong> Resilience4j tamamen JVM içi çalışır. Üç instance&#39;lı bir deployment&#39;ta &quot;dakikada 10&quot; aslında &quot;dakikada 30&quot;dur, üstelik load balancer&#39;ın o an nereye düşürdüğüne göre adaletsizce dağılır.</p><p>Bu yüzden pratik kural şu: anahtar kümesi <strong>küçük ve sınırlıysa</strong> (tenant başına, API client tier başına, birkaç düzine partner başına) Resilience4j’nin registry-as-map yaklaşımı gayet meşrudur. Anahtar kümesi <strong>kullanıcı kadar genişse ve deployment çok instance’lıysa</strong>, doğru araç paylaşımlı sayaçtır: Redis üzerinde atomic increment + TTL (ya da bunu paketleyen Bucket4j’nin Redis backend’i) veya işi hiç uygulamaya sokmadan API gateway seviyesinde limit. Resilience4j’nin rate limiter’ı kendi süreçindeki kaynağı korur. Kullanıcı-bazlı adil kullanım kotası dağıtık bir problemdir ve dağıtık state ister.</p><h3>Diğer Anotasyonlarla Sıralama</h3><p>Circuit breaker dersinden hatırlayın, birden fazla resilience anotasyonu aynı metoda konursa default sarma sırası dıştan içe şöyledir:</p><pre>Retry ( CircuitBreaker ( RateLimiter ( TimeLimiter ( Bulkhead ( metot ) ) ) ) )</pre><p>RateLimiter, CircuitBreaker’ın içinde ve Bulkhead’in dışındadır. Pratik anlamı: bir çağrı önce breaker’ın açık olup olmadığına bakılır, breaker kapalıysa rate limiter’a girer. Yani devre zaten açıksa çağrı rate limiter’ı hiç meşgul etmeden CallNotPermittedException alır. Retry en dışta olduğu için de her retry denemesi rate limiter&#39;dan ayrı ayrı geçer, yani retry&#39;lar da quota&#39;dan yer. Bu genelde istediğiniz şeydir ama retry + rate limiter birlikte kullanılırken quota&#39;nın retry&#39;ları da kapsadığını akılda tutmak gerekir.</p><h3>Gözlem: Kısılan Trafiği Görmek</h3><p>Rate limiter kurmak işin yarısı. Ne kadar sık devreye girdiğini görmek öteki yarısı, çünkü sürekli dolu bir limiter ya quota’nızın gerçek ihtiyacın altında olduğunu ya da bir yerde beklenenden çok trafik ürediğini söyler.</p><p><strong>Health endpoint.</strong> registerHealthIndicator: true ile her limiter health&#39;e yansır:</p><pre>GET /actuator/health<br>→ &quot;rateLimiters&quot;: { &quot;externalApi&quot;: { &quot;status&quot;: &quot;UP&quot;,<br>     &quot;details&quot;: { &quot;availablePermissions&quot;: 42, &quot;numberOfWaitingThreads&quot;: 0 } } }</pre><p><strong>Ratelimiters endpoint.</strong> Kayıtlı limiter’ların anlık durumu:</p><pre>GET /actuator/ratelimiters<br>→ kayıtlı tüm limiter&#39;lar ve konfigürasyonları</pre><p><strong>Events endpoint.</strong> Son olayların kaydı, izin verilen ve reddedilen çağrılar:</p><pre>GET /actuator/ratelimiterevents/externalApi<br>→ SUCCESSFUL_ACQUIRE, FAILED_ACQUIRE ...</pre><p>Reddedilen çağrıların ne zaman yoğunlaştığını buradan görürsünüz. Aynı olaylara kod içinden de abone olunabilir (limiter.getEventPublisher().onFailure(...)), reddedilen çağrıyı log&#39;a ve alarma bağlamanın yolu bu.</p><p><strong>Micrometer metrikleri.</strong> Starter, Prometheus’a iki temel metrik verir:</p><ul><li>resilience4j_ratelimiter_available_permissions — o an kalan permission sayısı. Sürekli sıfıra yapışıksa limiter kronik dolu demektir.</li><li>resilience4j_ratelimiter_waiting_threads — o an permission bekleyen thread sayısı. Bu sayının yükselişi, timeoutDuration &gt; 0 modunda thread birikimini gösterir ve bir uyarı işaretidir. Bekleyen thread&#39;ler tükendiğinde servisin geri kalanı da yavaşlar.</li></ul><p>Kurulacak asıl alarm bu ikincisinde: waiting_threads bir eşiği geçince haber ver, çünkü o an rate limiter servisin önünde bir kuyruk büyütüyor demektir.</p><h3>Sınırın Ötesi: Dağıtık Rate Limiting</h3><p>İki ayrımı netleştirmeden konu eksik kalır.</p><p><strong>Client-side vs server-side.</strong> Şimdiye kadar anlattığımız client-side’dı: kendi <em>çıkış</em> trafiğinizi bir quota’ya sığdırmak. Resilience4j’nin tipik kullanımı budur. Server-side ise gelen trafiği kısmaktır: kendi endpoint’inize gelen isteklere limit koymak. Resilience4j’yi bir controller’ın önüne @RateLimiter ile koyarak server-side de yapabilirsiniz, ama burada kritik bir sınır var.</p><p><strong>Resilience4j rate limiter tek JVM içindir.</strong> Permission sayacı o process’in belleğinde durur. Uygulamanız tek instance çalışıyorsa sorun yok. Ama üç pod çalışıyorsa, her pod kendi ayrı sayacını tutar. “Saniyede 100” dediyseniz gerçekte saniyede 300&#39;e izin vermiş olursunuz (pod başına 100).</p><figure><img alt="Tek JVM içi limiter dağıtımda çarpılır: üç pod’un her biri kendi saniyede-100 sayacını tutar, toplam saniyede 300 olur. Global bir limit için sayaç pod’ların dışında, paylaşılan bir Redis’te tek olmalı" src="https://cdn-images-1.medium.com/max/1024/1*EvXGmsU3ngm23ov_v4VXbw.png" /></figure><p>Client-side’da bu sapma genelde kabul edilebilir: limitin amacı karşı tarafı ezmemek, kesin bir sayı tutturmak değil. Ama server-side’da, özellikle gerçek bir global quota (tüm cluster için toplam saniyede 100) dayatmak istediğinizde bu model yeterli değildir.</p><p>Global bir limit için sayacın pod’ların dışında, paylaşılan bir yerde durması gerekir. Burası Redis tabanlı çözümlerin dünyası. <strong>Bucket4j</strong> bu alanın en bilinen kütüphanesidir. Token bucket algoritmasını uygular ve sayacı Redis, Hazelcast gibi dağıtık bir backend’de tutabildiği için tüm cluster genelinde tek bir global limit dayatabilir. Üç pod da aynı Redis sayacına danışır, toplam saniyede 100 gerçekten 100 olur.</p><p>Bu ayrı bir dünya ve bu yazının sınırının ötesi. Aklınızda kalması gereken tek cümle şu: <strong>tek JVM içinde, kendi çıkış trafiğinizi kısıyorsanız Resilience4j. Cluster geneli global bir limit, özellikle gelen trafik için, gerekliyse Redis tabanlı bir çözüm (Bucket4j gibi).</strong> İkisini karıştırmak, “saniyede 100” ayarının aslında pod sayısı kadar katına çıktığını fark etmemek en sık yapılan hatadır.</p><h3>Tuning Rehberi ve Klasik Hatalar</h3><p>Değerler kopyala-yapıştır ile değil, sığmaya çalıştığınız quota’ya ve trafiğin karakterine göre seçilir. Pratik akıl yürütme sırası:</p><ol><li><strong>Gerçek quota’yı öğrenin ve altına oturun.</strong> Karşı taraf “saniyede 100” diyorsa limitForPeriod’u 100 değil, 90 civarı seçin. Saat kaymaları ve cycle sınırı etkileri yüzünden tam 100&#39;e ayarlamak arada 429 yemenize yol açar. Küçük bir emniyet payı bırakın.</li><li><strong>limitRefreshPeriod’u quota’nın birimine uydurun.</strong> “Dakikada 1000” quota’sını limitForPeriod: 1000, limitRefreshPeriod: 60s ile mi yoksa limitForPeriod: 17, limitRefreshPeriod: 1s ile mi karşılarsınız? İkisi ortalama olarak aynı hızı verir, ama ilki dakikanın ilk saniyesinde 1000 çağrılık bir burst&#39;e izin verirken ikincisi trafiği saniyelere yayar. Karşı taraf burst&#39;e toleranslıysa ilki, değilse ikincisi.</li><li><strong>timeoutDuration’ı çağrının doğasına göre seçin.</strong> Kullanıcıyı bekleten senkron yol ise küçük ya da sıfır (fail-fast). Arka plan/batch işi ise cömert (kuyruğa al, isteği kaybetme).</li><li><strong>waiting_threads metriğini izleyin.</strong> timeoutDuration &gt; 0 seçtiyseniz bu metrik thread tükenmesinin erken uyarısıdır.</li></ol><p>Sahada en sık görülen hatalar:</p><ol><li><strong>limitRefreshPeriod’un set edilmemesi.</strong> Default 500 nanosaniye, yani pratikte sınırsız. İki çekirdek değeri vermezseniz limiter kurulur ama hiçbir şeyi kısmaz. Sessiz ve yaygın, tıpkı circuit breaker’ın minimumNumberOfCalls tuzağı gibi.</li><li><strong>Rate limiter’ı bulkhead sanmak.</strong> Saniyede N ile aynı anda N’i karıştırmak. Uzun süren çağrıların olduğu bir yolda rate limiter eş zamanlılığı hiç tutmaz, orada bulkhead gerekir. İki koruma ayrı boyutlardadır.</li><li><strong>Çok pod’da tek-JVM limiter’ıyla global limit sanmak.</strong> “Saniyede 100” ayarının gerçekte pod sayısı kadar katına çıktığını fark etmemek. Global limit gerekiyorsa dağıtık çözüm şart.</li><li><strong>timeoutDuration’ı düşünmeden default’ta bırakmak.</strong> Default 5 saniye. Senkron bir web yolunda bu, rate limit’e takılan her isteğin 5 saniye askıda kalıp thread işgal etmesi demektir. Yüksek trafikte thread pool bu kuyrukta tükenir. Web yollarında bilinçli olarak küçültün ya da sıfırlayın.</li><li><strong>AOP starter’ının unutulması / self-invocation.</strong> Circuit breaker’daki ile aynı tuzak: annotation var, koruma yok, kimse fark etmiyor.</li></ol><h3>Kapanış</h3><p>Rate limiter’ın özü tek cümle: birim zamanda kaç çağrıya izin verildiğini say ve fazlasını ya beklet ya reddet. Circuit breaker geçmiş çağrıların <em>sonucuna</em> (sağlık) bakarken rate limiter <em>sayısına ve zamanlamasına</em> (hız) bakar. Model iki kavram üzerine kurulu, cycle ve permission: her cycle başında permission havuzu limitForPeriod’a sıfırlanır, havuz boşsa çağrı timeoutDuration kadar bekleyebilir. Üç ayar bütün işi yapar. limitForPeriod ile limitRefreshPeriod hızı belirler, timeoutDuration ise “bekle mi reddet mi” ikilemini çözer.</p><p>Resilience ailesindeki yerini de netleştirelim. Timeout tek isteğin zararını sınırlar. Circuit breaker zararın tekrarını keser. Bulkhead eş zamanlılığı tutar (aynı anda N). Rate limiter hızı tutar (birim zamanda N). Dördü birbirinin alternatifi değil, dik boyutlarda çalışan tamamlayıcılardır. Ve unutmayın, hepsi tek JVM içindir. Cluster geneli global bir limit gerektiğinde iş Redis tabanlı bir dünyaya (Bucket4j gibi) taşınır.</p><h3>Kaynaklar</h3><ul><li><a href="https://resilience4j.readme.io/docs/ratelimiter">Resilience4j — RateLimiter Core</a> — çalışma modeli, AtomicRateLimiter, config alanları ve default’lar</li><li><a href="https://resilience4j.readme.io/docs/getting-started-3">Resilience4j — Spring Boot 3 Getting Started</a> — starter, YAML, annotation, aspect sırası</li><li><a href="https://github.com/resilience4j/resilience4j/blob/master/resilience4j-ratelimiter/src/main/java/io/github/resilience4j/ratelimiter/RateLimiterConfig.java">RateLimiterConfig.java (kaynak)</a> — default sabitlerin birebir doğrulaması</li><li><a href="https://bucket4j.com/">Bucket4j</a> — dağıtık, Redis tabanlı token bucket rate limiting (sınırın ötesi)</li><li><a href="https://medium.com/@gungor.akbiyik/circuit-breaker%C4%B1-do%C4%9Fru-kurmak-state-machine-den-production-tuning-e-d998755ec722">Circuit Breaker’ı Doğru Kurmak: State Machine’den Production Tuning’e</a> — serinin ilk yazısı, zamana bakan savunma</li><li><a href="https://medium.com/@gungor.akbiyik/redis-down-kolay-senaryo-as%C4%B1l-katil-yava%C5%9F-redis-606ff189525c">Redis Down Kolay Senaryo. Asıl Katil: Yavaş Redis</a> — serinin çıkış yazısı, katmanlı savunmanın bütünü</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a8f759ee698a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Bulkhead’i Doğru Kurmak: İzolasyondan Production Tuning’e]]></title>
            <link>https://medium.com/@gungor.akbiyik/bulkheadi-do%C4%9Fru-kurmak-i%CC%87zolasyondan-production-tuning-e-0b6c53c62a83?source=rss-3597415c14fc------2</link>
            <guid isPermaLink="false">https://medium.com/p/0b6c53c62a83</guid>
            <dc:creator><![CDATA[Güngör Akbıyık]]></dc:creator>
            <pubDate>Fri, 17 Jul 2026 04:24:26 GMT</pubDate>
            <atom:updated>2026-07-17T04:24:26.417Z</atom:updated>
            <content:encoded><![CDATA[<p>Ürün detay sayfası çöktü diye bakıyorsunuz, ama ürün detay endpoint’inde hiçbir sorun yok. Sorun kargo ücreti hesaplayan üçüncü parti serviste: o servis yavaşladı, ona giden istekler Tomcat’in worker thread’lerinin çoğunu bloke etti ve geri kalan thread azlığı yüzünden ürün detayı da, arama da, sepet de aynı anda cevap veremez oldu. Hiç ilgisi olmayan bir servisin yavaşlığı yüzünden bağımsız bir endpoint’in ölmesi böyle bir şey.</p><p><a href="https://medium.com/@gungor.akbiyik/redis-down-kolay-senaryo-as%C4%B1l-katil-yava%C5%9F-redis-606ff189525c">Redis-down yazısında</a> bu tarz bir senaryoyu beş katmanlı bir savunmanın parçası olarak ele almıştım. Bulkhead orada üçüncü katmandı, tek bir @ConcurrencyLimit(20) satırıyla veritabanını cache-miss selinden koruyordu. Burada işin mantığını sıfırdan kuruyoruz: iki farklı bulkhead tipini (semaphore ve thread pool) ayırıyoruz, her ayarı tek tek görüyoruz, Spring Boot ile gerçek kullanımı uçtan uca yazıyoruz. Serinin circuit breaker yazısının kardeşi olarak düşünün: o yazı &quot;kaybedeceği belli bahsi oynama&quot; diyordu, bu yazı &quot;aynı anda kaç bahis oynayabileceğini sınırla&quot; diyor.</p><h3>Problem: Bir Yavaş Bağımlılık Bütün Havuzu Nasıl Rehin Alır?</h3><p>Redis-down yazısının açılış matematiğini hatırlayın. Tomcat’te 200 worker thread var, her istek bir Redis okuması yapıyor ve Redis 2 saniye gecikmeli cevap veriyor. Bir thread saniyede en fazla 0,5 istek işleyebilir, 200 thread saniyede 100 istek kapasite demek. Gelen trafik 500 istek/sn ise her saniye 400 istek kuyruğa yığılır ve kuyruk saniyeler içinde taşar.</p><p>Buradaki asıl felaket, taşan endpoint’in Redis’e giden endpoint olmaması. Uygulamanızda onlarca farklı endpoint var: ürün detayı, arama, sepet, profil, ödeme. Bunların hepsi <strong>aynı</strong> thread havuzunu paylaşır. Redis’e giden tek bir yavaş endpoint 200 thread’in tamamını sömürdüğünde, Redis’e hiç dokunmayan “kullanıcı profili” endpoint’i de cevap veremez. Çünkü ona düşecek thread kalmamıştır. Bir bağımlılığın yavaşlığı, onunla hiç ilgisi olmayan işlevleri de yere serer.</p><p>İsim gemicilikten geliyor. Büyük gemilerin gövdesi su geçirmez <strong>bölmelere</strong> (bulkhead) ayrılır. Bir bölme delinip su alsa bile, bölme duvarları suyun diğer bölmelere geçmesini engeller. Gemi bir bölmeyi kaybeder ama batmaz. Titanic’in trajedisi tam olarak buydu: bölmeler vardı ama duvarlar yeterince yüksek değildi, su bir bölmeden diğerine taştı ve izolasyon çöktü. Yazılımdaki karşılığı da aynı: her bağımlılığa ayrı bir thread/permit bütçesi ayır ki biri boğulunca ötekiler nefes almaya devam etsin.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HnYg_M5GTJDm45yfN2tOcA.png" /></figure><h3>Circuit Breaker ile Farkı</h3><p>İki desen sık karıştırılır çünkü ikisi de “bozuk bağımlılık” problemine bakar. Ama farklı sorulara cevap verirler.</p><p>Circuit breaker <strong>geçmişe</strong> bakar. Son N çağrının sonucunu biriktirir, hata veya yavaşlık oranı eşiği aşınca devreyi açar ve bir süre <strong>hiç</strong> çağrı geçirmez. Zaman ekseninde çalışır: “bu yol son zamanlarda kötüydü, bir süre uğrama.”</p><p>Bulkhead <strong>şu ana</strong> bakar. Geçmişle ilgilenmez, oran hesaplamaz. Sadece “şu anda bu bağımlılıkta kaç çağrı eş zamanlı çalışıyor?” sorusunu sorar ve bir tavan koyar. Eş zamanlılık ekseninde çalışır: “bu yolda aynı anda en fazla 20 çağrı olsun, 21.’si ya bekler ya reddedilir.”</p><p>İkisi alternatif değil, <strong>tamamlayıcı</strong>. Circuit breaker henüz açılmadan önce (hata oranı eşiğe ulaşmadan, ilk yavaşlama dalgasında) thread havuzu çoktan dolabilir. Bulkhead o ilk dalgada devreye girer ve hasarı tek bir bağımlılığın bütçesiyle sınırlar. Circuit breaker sonra devreye girip o bağımlılığa hiç uğramamaya başlar. Redis-down yazısındaki katmanlı savunmada ikisi yan yanaydı: circuit breaker (katman 2) zararın tekrarını keser, bulkhead (katman 3) fallback trafiğinin veritabanını ezmesini önler.</p><h3>İki Tip: Semaphore vs Thread Pool Bulkhead</h3><p>Resilience4j iki ayrı bulkhead implementasyonu sunar ve aralarındaki fark yüzeysel değil, çağrının hangi thread’de koştuğuyla ilgili köklü bir fark.</p><p><strong>SemaphoreBulkhead.</strong> Çağrıyı <strong>çağıran thread’de</strong> çalıştırır. Ekstra thread yaratmaz. İçeride bir sayaç tutar ve bu sayaç mecazi değil, Java concurrency’den bildiğimiz java.util.concurrent.Semaphore&#39;un kendisidir: başlangıçta N permit vardır, her çağrı girişte bir permit alır (tryAcquire), çıkışta try/finally ile geri verir (release). Permit kalmadıysa çağrı ya bekler ya reddedilir. Resilience4j&#39;nin eklediği şey mantık değil ambalajdır: timeout&#39;u config&#39;e bağlar, doluluğu BulkheadFullException&#39;a çevirir, metrik ve event yayınlar. Yani çağrı Tomcat worker thread&#39;inde koşmaya devam eder, bulkhead sadece &quot;kaç tanenizin aynı anda içeri girmesine izin veriyorum&quot; der. Hafif, ucuz, davranışı öngörülebilir.</p><p><strong>FixedThreadPoolBulkhead.</strong> Çağrıyı <strong>kendi ayrı thread havuzunda</strong> çalıştırır. Korunan işi çağıran thread’den alır, kendi bounded thread pool’una devreder ve önünde bounded bir queue tutar. Çağıran thread (Tomcat worker) hemen serbest kalır, işi ayrı havuz yürütür. Bu tam bir <strong>izolasyon</strong>dur: bağımlılık bütünüyle ayrı bir thread grubuna hapsedilir, ana havuza hiç dokunmaz. Bedeli, her çağrının bir thread’den diğerine devredilmesi (context switch) ve dönüşün asenkron olması.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ygiEidFd2LyaYYSEV8a3iA.png" /></figure><p>Hangisi ne zaman? Pratik ayrım şu:</p><p><strong>Semaphore</strong> varsayılan tercihtir. Çağrı senkron çalışıyorsa ve tek istediğiniz aynı anda kaç çağrının içeri girdiğini sınırlamaksa semaphore yeter. Çağrı, çağıran (Tomcat) thread’inde koşmaya devam eder, siz sadece kaç worker’ın o bağımlılıkta aynı anda bloke olabileceğine tavan koyarsınız. Bulkhead’in sahadaki en yaygın hâli budur: yavaş bir dış REST çağrısına 20 permit verip, o servis tıkandığında en fazla 20 worker’ın bloke olmasını, kalan 180&#39;inin başka endpoint’lere hizmet vermeye devam etmesini garantilemek. Redis-down yazısındaki DB koruması da aynı kategoriden: senkron sorgu, tek dert aynı anda 20&#39;den fazlasının girmemesi. Ekstra thread havuzuna gerek yok.</p><p><strong>Thread pool</strong> izolasyonun kendisinin kıymetli olduğu yerde kazanır. Korunan çağrı uzun sürüyorsa ve onu çağıran thread’i (özellikle sınırlı Tomcat worker’larını) bloke etmek istemiyorsanız, işi ayrı havuza atmak worker’ı hemen serbest bırakır. Ama bir uyarı: thread pool bulkhead CompletableFuture döner ve kendi thread&#39;inde koştuğu için ThreadLocal&#39;a bağlı şeyler (Spring Security context, transaction, MDC log context) otomatik taşınmaz. Bu, çoğu senkron web akışında istenmeyen bir karmaşıklık. Bu yüzden pratikte semaphore çok daha sık kullanılır, thread pool ise özellikle asenkron akışlarda ya da gerçekten izole bir off-loading gerektiğinde seçilir.</p><p>Bir de reactive dünya var: WebFlux/Reactor akışında zaten thread bloke edilmediği için thread pool bulkhead anlamsızlaşır, orada semaphore tipi operatörler kullanılır. Bu yazı senkron Spring MVC dünyasına odaklanıyor.</p><h3>Ayarlar Tek Tek</h3><p>İki tipin ayarları farklı olduğu için ikisini ayrı ele alalım.</p><h3>Semaphore Bulkhead</h3><pre>BulkheadConfig config = BulkheadConfig.custom()<br>        .maxConcurrentCalls(20)<br>        .maxWaitDuration(Duration.ZERO)<br>        .build();</pre><p><strong>maxConcurrentCalls.</strong> Aynı anda içeri alınacak maksimum çağrı sayısı. Semaphore’un başlangıç permit sayısı budur. Default <strong>25</strong>. Bu sayı bulkhead’in bütün kararının kalbi. Çok düşük tutarsanız sağlıklı günde bile gereksiz reddetme/bekleme yaratırsınız, çok yüksek tutarsanız koruma anlamını yitirir (havuzun tamamı yine dolabilir). Doğru değer korunan bağımlılığın <strong>gerçek kapasitesidir</strong>: veritabanının cache’siz kaldırabildiği eş zamanlı sorgu sayısı, downstream servisin connection pool boyutu gibi. Bu ölçümle bulunur, tahminle değil.</p><p><strong>maxWaitDuration.</strong> Bulkhead doluyken bir çağrının permit için ne kadar bekleyeceği. Default <strong>0</strong>. Bu tek satır, bulkhead’in kişiliğini belirler ve ayrı bir bölümü hak edecek kadar önemli (aşağıda). Kısaca: 0 ise permit yoksa çağrı <strong>anında reddedilir</strong> (BulkheadFullException fırlar), 0&#39;dan büyükse çağrı o süre kadar bekler ve süre içinde permit boşalmazsa yine reddedilir.</p><p>Bulkhead dolduğunda ve bekleme de bittiğinde fırlatılan exception BulkheadFullException&#39;dır. Circuit breaker&#39;ın CallNotPermittedException&#39;ıyla aynı ruhta bir sinyal: &quot;bu çağrıyı denemedik bile, kapasite doluydu.&quot;</p><h3>Thread Pool Bulkhead</h3><pre>ThreadPoolBulkheadConfig config = ThreadPoolBulkheadConfig.custom()<br>        .coreThreadPoolSize(10)<br>        .maxThreadPoolSize(20)<br>        .queueCapacity(50)<br>        .keepAliveDuration(Duration.ofMillis(20))<br>        .build();</pre><p><strong>coreThreadPoolSize.</strong> Havuzun taban thread sayısı, sürekli hazır tutulan thread’ler. Default Runtime.getRuntime().availableProcessors() - 1.</p><p><strong>maxThreadPoolSize.</strong> Havuzun büyüyebileceği tavan. Yük artınca core’dan max’a kadar yeni thread açılır. Default Runtime.getRuntime().availableProcessors().</p><p><strong>queueCapacity.</strong> Bütün thread’ler meşgulken bekleyecek işlerin queue kapasitesi. Default <strong>100</strong>. Burada standart ThreadPoolExecutor&#39;dan farklı ve önemli bir davranış var: iş önce queue&#39;ya değil, thread açmaya gider. Core dolu ama max&#39;a ulaşılmadıysa yeni thread açılır, max da doluysa queue&#39;ya girilir, queue da doluysa BulkheadFullException fırlar.</p><p><strong>keepAliveDuration.</strong> Core’un üstündeki (max’a doğru açılmış) fazla idle thread’lerin, iş kalmayınca kapatılmadan önce bekleme süresi. Default <strong>20 ms</strong>.</p><p><strong>writableStackTraceEnabled.</strong> Bulkhead exception’ı fırlatıldığında stack trace üretilsin mi. Default <strong>true</strong>. Yüksek reddetme hacminde stack trace üretimi ölçülebilir CPU maliyeti yaratabildiği için, sık reddedilen yollarda false yapmak bir performans mikro-optimizasyonudur.</p><p>Dikkat çeken nokta: thread pool bulkhead’in queue’su latency’yi <strong>gizleyebilir</strong>. queueCapacity’yi 100 gibi cömert tutarsanız, bağımlılık yavaşladığında çağrılar reddedilmek yerine queue’da sessizce birikir ve orada beklerken kullanıcı yine timeout yer, ama metriklerinizde “bulkhead full” görünmez. Bu yüzden thread pool bulkhead’de queue’yu bilinçli ve genelde <strong>küçük</strong> tutmak gerekir. Bu tuzağa ilerideki Tuning Rehberi bölümünde tekrar döneceğiz.</p><h3>Spring Boot ile Kullanım</h3><p>Programmatic API’yi (BulkheadConfig.custom()... hâli) gördük. Spring entegrasyonu üç şey ekler: YAML&#39;dan konfigürasyon, annotation ile kullanım, actuator ile gözlem. Serinin circuit breaker yazısındaki iskeletin aynısı.</p><p>Bir çerçeve düzeltmesi de yapalım. Bulkhead’in piyasadaki en tipik kullanımı tek bir cache ya da DB koruması değil, latency’si sizin kontrolünüzde olmayan bağımlılıkları izole etmektir. Tomcat worker’larını en çok rehin alan sınırlar bunlardır: ödeme sağlayıcısı ve üçüncü parti REST API’leri, yavaşlayabilen komşu mikroservisler, bir de rapor ya da dışa aktarma gibi ağır iç yollar. Bulkhead ezici çoğunlukla bu sınırlarda durur, çünkü mantık hep aynıdır: bu yavaş bağımlılığa aynı anda en fazla N worker bloke olsun, gerisi başka endpoint’lere kalsın. Bu bölümün örnekleri de bu ağırlığa göre seçildi. Semaphore örneği yavaş bir dış servis çağrısı, thread pool örneği ağır bir rapor işi, DB cache-miss koruması ise redis-down bağlantısını sürdüren ikincil örnek.</p><h3>Bağımlılıklar</h3><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;io.github.resilience4j&lt;/groupId&gt;<br>    &lt;artifactId&gt;resilience4j-spring-boot3&lt;/artifactId&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>    &lt;artifactId&gt;spring-boot-starter-aop&lt;/artifactId&gt;   &lt;!-- annotation&#39;lar AOP ile calisir --&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>    &lt;artifactId&gt;spring-boot-starter-actuator&lt;/artifactId&gt;  &lt;!-- events + metrics --&gt;<br>&lt;/dependency&gt;</pre><p>AOP starter’ı unutulursa annotation’lar sessizce hiçbir şey yapmaz. Circuit breaker’da olduğu gibi, koruma yokmuş gibi çalışır ama hata da vermez. Entegrasyonun bir numaralı tuzağı budur.</p><h3>YAML Konfigürasyonu</h3><p>İki tipin YAML ağacı ayrıdır. Semaphore için resilience4j.bulkhead, thread pool için resilience4j.thread-pool-bulkhead:</p><pre>resilience4j:<br>  bulkhead:                                   # SEMAPHORE tipi<br>    configs:<br>      default:<br>        maxConcurrentCalls: 20<br>        maxWaitDuration: 0<br>    instances:<br>      shippingProvider:                       # yavas dis REST, birincil ornek<br>        baseConfig: default                   # bu isimle @Bulkhead&#39;den cagrilir<br>      inventoryService:                       # komsu mikroservis, farkli karakter<br>        baseConfig: default<br>        maxConcurrentCalls: 40<br>        maxWaitDuration: 50ms                  # kisa tepeyi yutmak icin ufak bekleme<br>      productDb:                              # DB cache-miss korumasi (redis-down)<br>        baseConfig: default<br><br>  thread-pool-bulkhead:                       # THREADPOOL tipi<br>    instances:<br>      reportExport:                           # agir ic yol, tam izolasyon<br>        coreThreadPoolSize: 5<br>        maxThreadPoolSize: 10<br>        queueCapacity: 20</pre><p>Yapı circuit breaker’daki gibi iki katmanlı: configs altında yeniden kullanılabilir tabanlar, instances altında isimli bulkhead&#39;ler, her instance bir tabandan miras alıp (baseConfig) istediği alanı ezebilir.</p><p>Bir davranışı baştan bilin: <strong>YAML’da tanımlı olmayan bir isim istendiğinde hata fırlamaz, default değerlerle yeni bir bulkhead yaratılır.</strong> Registry’lerin get-or-create semantiği bu: @Bulkhead(name = &quot;x&quot;) veya registry.bulkhead(&quot;x&quot;) ismi bulamazsa default config&#39;le instance açar (kaynakta debug log&#39;u kelimesiyle söyler: &quot;Created or retrieved&quot;). Default&#39;lar da masum değil: semaphore için 25 permit + bekleme 0, thread pool için CPU çekirdek sayısı kadar max thread (core = çekirdek − 1) + 100 kapasiteli queue. Bunun iki pratik sonucu var. Birincisi, isimde yapılan bir yazım hatası sessizce yutulur: YAML&#39;daki özenli config&#39;iniz boşta kalır, trafik default ayarlı hayalet bulkhead&#39;den geçer ve her şey çalışıyor görünür. İkincisi, teşhis yolu metriklerdir: resilience4j_bulkhead_* metriklerinde beklemediğiniz bir instance ismi görüyorsanız, büyük ihtimalle bir typo ya da unutulmuş YAML tanımı buldunuz demektir. Bu davranış bulkhead&#39;e özgü değil, Resilience4j&#39;nin bütün registry&#39;leri (circuit breaker dahil) aynı şekilde çalışır.</p><p>Buradaki tasarım kuralı da circuit breaker’la aynı: <strong>bulkhead’ler bağımlılık başına ayrılır.</strong> Ödeme/dış sağlayıcı, komşu servis ve veritabanı ayrı bulkhead’ler almalı. Hepsini tek bulkhead’e koyarsanız birinin doluluğu ötekilerini de reddettirir, ki bu tam olarak bulkhead’in önlemeye çalıştığı şeyin kendisi. Tersi aşırılık da var: her metoda ayrı bulkhead açmak yönetilemez hale gelir. Doğru granülarite “arıza birimi başına bir bulkhead”dır.</p><h3>Annotation ile Kullanım</h3><p>En yaygın senaryo üzerinden gidelim: latency’si bizde olmayan, yavaşlayabilen bir dış REST bağımlılığı (kargo/tarife sağlayıcısı gibi). Semaphore bulkhead burada “aynı anda en fazla 20 worker bu sağlayıcıda bloke olsun” der, geri kalan worker’lar diğer endpoint’lere kalır.</p><pre>@Service<br>public class ShippingRateClient {<br><br>    private final RestClient restClient;   // dis servis, latency&#39;si bizde degil<br><br>    @Bulkhead(name = &quot;shippingProvider&quot;, fallbackMethod = &quot;cachedRate&quot;)<br>    public ShippingRate quote(CartWeight weight) {<br>        return restClient.post().uri(&quot;/v1/rates&quot;)<br>                .body(weight)<br>                .retrieve()<br>                .body(ShippingRate.class);<br>    }<br><br>    // fallback: ayni parametreler + sonda exception, ayni donus tipi<br>    private ShippingRate cachedRate(CartWeight weight, BulkheadFullException e) {<br>        return ShippingRate.lastKnown(weight);   // kapasite dolu: son bilinen tarife<br>    }<br>}</pre><p>name = &quot;shippingProvider&quot; YAML&#39;daki instance&#39;a bağlanır. type belirtilmezse default Bulkhead.Type.SEMAPHORE&#39;dur. Fallback imzası circuit breaker&#39;daki kuralla aynı: orijinal metotla aynı parametreler, sonuna eklenmiş bir exception parametresi, aynı dönüş tipi. Burada fallback&#39;i özellikle BulkheadFullException tipine bağladım, çünkü &quot;kapasite doluydu&quot; ile &quot;sağlayıcı gerçekten hata verdi&quot; farklı olaylar ve genelde farklı degrade cevabı isterler. İkincisini (timeout, 5xx) da yakalamak isterseniz Throwable alan ikinci bir fallback overload&#39;u eklenir.</p><p>Thread pool tipini kullanmak istersek imza değişir, çünkü thread pool bulkhead CompletableFuture döndürmek <strong>zorundadır</strong>:</p><pre>@Bulkhead(name = &quot;reportExport&quot;, type = Bulkhead.Type.THREADPOOL)<br>public CompletableFuture&lt;Report&gt; exportAsync(long id) {<br>    return CompletableFuture.completedFuture(reportService.build(id));<br>}</pre><p>Senkron dönüş tipiyle type = THREADPOOL kullanırsanız çalışmaz. Bu, iki tipin annotation seviyesindeki en görünür farkı.</p><p>Peki YAML’da instance’ı zaten thread-pool-bulkhead ağacına koymuşken annotation&#39;da neden bir daha type beyan ediyoruz? Çünkü YAML ile annotation birbirinin type bilgisini görmez. resilience4j.bulkhead ağacı BulkheadRegistry&#39;yi (semaphore), thread-pool-bulkhead ağacı ayrı bir ThreadPoolBulkheadRegistry&#39;yi doldurur ve aynı isim ikisinde birden var olabilir. Annotation&#39;daki type, aspect&#39;e hangi registry&#39;de arayacağını söyler. Aspect YAML ağaçlarını taramaz. Tuzak da burada: type&#39;ı unutursanız hata almazsınız. Aspect default&#39;a (SEMAPHORE) düşer, semaphore registry&#39;de &quot;reportExport&quot; bulamaz ve registry&#39;lerin standart davranışıyla <strong>default config&#39;le (25 permit) yeni bir semaphore bulkhead yaratılır</strong>. İş onun içinden geçer, YAML&#39;daki thread pool config&#39;iniz sessizce kullanılmadan kalır. AOP starter&#39;ı unutma tuzağıyla aynı aile: görünürde çalışır, istediğiniz koruma yoktur.</p><h3>Programmatic Kullanım (Spring İçinde)</h3><p>Annotation her yere uymaz (lambda içi, dinamik isim, AOP self-invocation tuzağından kaçınma). Spring Boot starter’ı bir BulkheadRegistry bean&#39;i verir. Örnek olarak ikincil bağımlılığımızı, redis-down yazısındaki DB cache-miss korumasını alalım:</p><pre>@Service<br>public class ProductDbGate {<br><br>    private final Bulkhead bulkhead;<br><br>    public ProductDbGate(BulkheadRegistry registry) {<br>        this.bulkhead = registry.bulkhead(&quot;productDb&quot;);   // YAML&#39;daki instance<br>    }<br><br>    public ProductView loadFromDb(long id) {<br>        try {<br>            return bulkhead.executeSupplier(() -&gt; repository.loadProductView(id));<br>        } catch (BulkheadFullException e) {<br>            return ProductView.placeholder(id);   // kapasite dolu: degrade<br>        }<br>    }<br>}</pre><p>@Bulkhead annotation&#39;ı da AOP proxy üzerinden çalıştığı için circuit breaker&#39;daki self-invocation tuzağı burada da geçerli. Aynı sınıf içinden this.loadFromDb(id) çağrısı proxy&#39;yi bypass eder ve bulkhead devreye girmez. Böyle durumda ya çağrıyı ayrı bir bean&#39;e taşırsınız ya da bu programmatic API&#39;ye dönersiniz.</p><h3>Spring Framework 7 Alternatifi: @ConcurrencyLimit</h3><p>Spring Framework 7, core’a kendi resilience anotasyonlarını getirdi ve bunlardan biri semaphore bulkhead’e çok benziyor: @ConcurrencyLimit. Redis-down yazısında DB korumasını bununla yazmıştık:</p><pre>@Service<br>public class ProductDbGate {<br><br>    @ConcurrencyLimit(20)   // ayni anda en fazla 20 giris<br>    public ProductView loadFromDb(long id) {<br>        return repository.loadProductView(id);<br>    }<br>}</pre><p>Etkinleştirmek için @EnableResilientMethods eklenir (ya da bir ConcurrencyLimitBeanPostProcessor bean&#39;i tanımlanır). Limit sabit yerine property/SpEL&#39;den de gelebilir (@ConcurrencyLimit(limitString = &quot;${db.concurrency}&quot;)). Altında Spring 1.0&#39;dan beri var olan ConcurrencyThrottleInterceptor çalışır.</p><p>Resilience4j Bulkhead ile arasındaki <strong>kritik davranış farkı</strong> şu: @ConcurrencyLimit limit dolduğunda çağrıyı reddetmez, <strong>bekletir</strong>. Dokümanın kendi ifadesiyle &quot;bloke eder&quot; (thread pool ya da connection pool&#39;un limit dolunca erişimi bloke etmesi gibi). Yani maxWaitDuration&#39;ı sonsuz olan bir semaphore bulkhead gibi davranır: slot boşalana kadar bekler, asla BulkheadFullException fırlatmaz. Reddetme davranışı, &quot;anında degrade et&quot; seçeneği yoktur.</p><p>İkisi arasında seçim:</p><ul><li><strong>Sadece eş zamanlılığı sınırlamak</strong> ve slot boşalana kadar beklemek yeterliyse, ekstra bağımlılık istemiyorsanız (özellikle Virtual Thread kullanıyorsanız, ki Spring bu anotasyonu tam da virtual thread çağı için öne çıkarıyor: thread havuzu limiti olmayan bir dünyada eş zamanlılık sınırı koymanın yolu), @ConcurrencyLimit sade ve yeterli.</li><li><strong>Anında reddetme (</strong>maxWaitDuration=0<strong>), sınırlı bekleme, fallback, metrik ve YAML&#39;dan tam kontrol</strong> istiyorsanız Resilience4j Bulkhead daha zengin. Redis-down yazısında &quot;bekletme değil hemen reddet, çünkü bekleyen istek de thread tutar&quot; davranışı istediğimizde Resilience4j&#39;nin maxWaitDuration(Duration.ZERO) versiyonuna geçmiştik. Bu, @ConcurrencyLimit&#39;in veremediği davranış.</li></ul><p>Not: circuit breaker Spring 7&#39;nin bu setine dahil <strong>değil</strong>. Bulkhead benzeri @ConcurrencyLimit var ama circuit breaker için hâlâ Resilience4j doğru adres.</p><h3>maxWaitDuration=0 vs Bekletme: İki Ayrı Felsefe</h3><p>Semaphore bulkhead’in en önemli tek kararı maxWaitDuration ve bu karar teknik değil neredeyse ürünsel. İki uç var.</p><p><strong>maxWaitDuration = 0 (anında red).</strong> Permit yoksa çağrı beklemeden BulkheadFullException alır ve fallback/degrade yoluna düşer. Avantajı: bekleyen çağrı yok demek, tutulan thread yok demek. Redis-down senaryosunun tam istediği bu. Orada mantık şuydu: veritabanı zaten sınırdaysa, 21. isteği bekletmek onu da bir thread&#39;e oturtup beklemeye zorlamak olur ve o thread yavaş yavaş yine tükenir. Onun yerine 21. isteği anında reddedip bir alt katmana (L1 cache, degrade cevap) yönlendirmek hem thread&#39;i serbest bırakır hem kullanıcıya hızlı bir cevap verir. Aynı mantık birincil örneğimizdeki yavaş dış servis için de aynen işler: sağlayıcı tıkandığında 21. çağrıyı bekletmek yerine anında reddedip son bilinen tarifeye düşmek, worker&#39;ı hemen boşa çıkarır. &quot;Kaldıramayacağım işi hızlıca geri çevir&quot; felsefesi.</p><p><strong>maxWaitDuration &gt; 0 (bekletme).</strong> Permit yoksa çağrı bir süre (mesela 50 ms) kuyrukta bekler, o sürede slot açılırsa girer, açılmazsa reddedilir. Avantajı: bağımlılık <strong>anlık</strong> bir tepe yaşıyorsa (20 slot doldu ama çağrılar hızlı bitiyor), kısa bir bekleme çoğu isteği reddetmeden kurtarır. Kısa süreli dalgalanmayı yumuşatır. Dezavantajı: bekleyen her istek bir thread tutar. Bekleme süresini uzun tutarsanız, bulkhead’in önlemeye çalıştığı “thread rehin alınması” problemini kendi elinizle geri getirirsiniz.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JTUiScgBMUb2nEKtTVYMCg.png" /></figure><p>Pratik kural: fallback’iniz ucuz ve anlamlıysa (cache miss, degrade liste, placeholder) maxWaitDuration=0 seçin ve reddedileni fallback&#39;e verin. Fallback&#39;iniz yoksa veya reddetmenin maliyeti yüksekse (işlem kaybı), kısa bir maxWaitDuration (10-50 ms) anlık tepeleri yutar. Uzun bekleme (yüzlerce ms ve üzeri) neredeyse her zaman yanlıştır, bulkhead&#39;i thread tutan bir kuyruğa çevirir.</p><h3>Gözlem: Dolu Bulkhead’i Görmek</h3><p>Bulkhead kurmak işin yarısı. Dolduğunu <strong>görmek</strong> öteki yarısı, çünkü dolu bulkhead reddedilen isteklerin arkasında sessizce çalışır ve fallback devredeyken kullanıcı hissetmeyebilir.</p><p><strong>Events endpoint.</strong> Son bulkhead olaylarının kaydı:</p><pre>GET /actuator/bulkheadevents/productDb<br>→ CALL_PERMITTED, CALL_REJECTED, CALL_FINISHED ...</pre><p>CALL_REJECTED olaylarının varlığı ve sıklığı, bulkhead&#39;in gerçekten devreye girip girmediğinin en doğrudan kanıtı. Hiç CALL_REJECTED görmüyorsanız ya bulkhead hiç dolmuyor (limit fazla cömert olabilir) ya da bağlanmamış.</p><p><strong>Micrometer metrikleri.</strong> Semaphore bulkhead için Prometheus’a iki metrik gider:</p><ul><li>resilience4j_bulkhead_available_concurrent_calls — o an kalan boş permit sayısı. Bu sıfıra dayandığında bulkhead doludur. Alarm buraya kurulur (available uzun süre 0&#39;a yakınsa bağımlılık sınırında demektir).</li><li>resilience4j_bulkhead_max_allowed_concurrent_calls — yapılandırılmış tavan (maxConcurrentCalls). available/max oranı doluluğu verir.</li></ul><p>Thread pool bulkhead için beş metrik:</p><ul><li>resilience4j_bulkhead_queue_depth — queue&#39;da bekleyen iş sayısı. Bu tırmanıyorsa latency gizleniyor demektir.</li><li>resilience4j_bulkhead_queue_capacity — queue tavanı.</li><li>resilience4j_bulkhead_thread_pool_size — havuzun anlık boyutu.</li><li>resilience4j_bulkhead_core_thread_pool_size — taban boyut.</li><li>resilience4j_bulkhead_max_thread_pool_size — tavan boyut.</li></ul><p>Gözlemde en kritik gösterge semaphore tarafında available_concurrent_calls&#39;un sürekli sıfıra yapışması, thread pool tarafında queue_depth&#39;in dolmaya başlaması. İkisi de &quot;bu bağımlılık kapasitesinin üstünde yük alıyor&quot; sinyalidir ve genelde ya limiti yükseltmek ya da bir üst katmanda (circuit breaker, degrade) yükü kesmek gerektiğini söyler.</p><h3>Tuning Rehberi ve Klasik Hatalar</h3><p>Bulkhead ayarları da kopyala-yapıştır ile değil, korunan bağımlılığın gerçek kapasitesine göre seçilir. Pratik akıl yürütme sırası:</p><ol><li><strong>Bağımlılığın gerçek eş zamanlı kapasitesini ölç.</strong> Veritabanı için: connection pool boyutu ve cache’siz kaldırabildiği eş zamanlı sorgu (load test’te çıkar). Downstream servis için: onun kabul ettiği eş zamanlılık. maxConcurrentCalls bu sayının biraz altına konur, üstüne değil.</li><li><strong>Fallback’in maliyetine göre maxWaitDuration seç.</strong> Ucuz fallback varsa 0 (anında red). Fallback acıysa kısa bir bekleme (10–50 ms).</li><li><strong>Semaphore mi thread pool mu?</strong> Senkron ve kısa çağrıda semaphore. Uzun/izolasyon-kritik/asenkron işte thread pool, ama ThreadLocal ve CompletableFuture bedelini bilerek.</li><li><strong>Circuit breaker’la birlikte konumlandır.</strong> Bulkhead anlık koruma, circuit breaker kalıcı kesme. İkisi aynı bağımlılıkta yan yana durabilir ve durmalı.</li></ol><p>Ve sahada en sık görülen hatalar:</p><ol><li><strong>Limiti ölçmeden koymak.</strong> maxConcurrentCalls&#39;a &quot;50 iyi görünür&quot; diye rastgele değer vermek. Çok düşükse sağlıklı günde bile reddeder, çok yüksekse hiç korumaz. Bu sayı bağımlılığın ölçülmüş kapasitesidir, tahmin değil.</li><li><strong>Tüm bağımlılıklara tek bulkhead.</strong> Veritabanı, arama ve ödeme aynı bulkhead’i paylaşırsa birinin doluluğu ötekilerini reddettirir. Bu, bulkhead’in önlemeye çalıştığı çapraz bulaşmanın ta kendisi. Bağımlılık başına ayrı bulkhead.</li><li><strong>Thread pool queue’sunun latency’yi gizlemesi.</strong> Cömert queueCapacity (100 gibi), yavaşlama anında çağrıları reddetmek yerine queue&#39;da biriktirir. Kullanıcı yine timeout yer ama &quot;bulkhead full&quot; metriği ötmez, sorun görünmez kalır. Thread pool bulkhead&#39;de queue&#39;yu bilinçli olarak küçük tutun.</li><li><strong>Uzun maxWaitDuration.</strong> Yüzlerce ms bekleten bir semaphore bulkhead, bekleyen isteklerle thread havuzunu yine doldurur ve tam olarak önlemek istediği problemi geri getirir. Bekleme kısa olmalı ya da hiç olmamalı.</li><li><strong>Bulkhead’in hiç test edilmemesi.</strong> Reddetme yolunun çalıştığının tek kanıtı onu bilerek tetiklemektir. Staging’de bağımlılığa yapay latency enjekte edip (Toxiproxy) eş zamanlı yük bindirin, available_concurrent_calls&#39;un sıfıra indiğini, CALL_REJECTED olaylarının aktığını ve fallback&#39;in devreye girdiğini gözle görün. Bir kez izleyen, hangi limitin ne yaptığını bir daha unutmaz.</li><li><strong>YAML’da olmayan isme güvenmek (typo / yanlış type).</strong> Registry, tanımsız ismi hata yerine default config’le (25 permit) sessizce yaratır. Annotation’daki isim YAML’dakiyle birebir aynı olmalı, thread pool instance’ında type = THREADPOOL unutulmamalı. Teşhis: metriklerde beklenmedik instance ismi = hayalet bulkhead.</li></ol><h3>Kapanış</h3><p>Bulkhead’in özü tek cümle: bir bağımlılığa aynı anda kaç çağrının girebileceğini sınırla ki o bağımlılık boğulunca kaynak tükenmesi bütün sisteme yayılmasın. Semaphore tipi çağıran thread’de sayar ve hafiftir, thread pool tipi ayrı havuzda tam izolasyon verir ama context switch ve CompletableFuture bedeli taşır. maxConcurrentCalls kapasiteyi, maxWaitDuration ise reddetme-mi-bekletme-mi felsefesini belirler. Spring tarafında iş üç parça: YAML&#39;da instance tanımla, @Bulkhead(name, fallbackMethod) ile bağla ya da Spring 7&#39;nin @ConcurrencyLimit&#39;iyle sade sürümü kur, actuator + Micrometer ile izle.</p><p>Redis-down yazısıyla bağı da netleştirelim: orada bulkhead, beş katmanlı savunmanın üçüncü katmanıydı. Timeout (katman 1) tek isteğin zararını sınırlar, circuit breaker (katman 2) zararın tekrarını keser, bulkhead (katman 3) circuit breaker açılıp fallback trafiği veritabanına aktığında o trafiğin veritabanını ezmesini önler. Üçü birbirinin alternatifi değil, tamamlayıcısıdır. Serinin circuit breaker yazısı zamana bakan savunmayı anlatıyordu, bu yazı eş zamanlılığa bakan savunmayı. Bir sonraki halka bunların üstüne kurulan timeout ve retry hiyerarşisi.</p><h3>Kaynaklar</h3><ul><li><a href="https://resilience4j.readme.io/docs/bulkhead">Resilience4j — Bulkhead Core</a> — SemaphoreBulkhead vs FixedThreadPoolBulkhead, tüm config alanları ve default’ları</li><li><a href="https://resilience4j.readme.io/docs/getting-started-3">Resilience4j — Spring Boot 3 Getting Started</a> — starter, YAML, @Bulkhead annotation, aspect sırası</li><li><a href="https://resilience4j.readme.io/docs/micrometer">Resilience4j — Micrometer Metrics</a> — bulkhead metrik isimleri</li><li><a href="https://docs.spring.io/spring-framework/reference/core/resilience.html">Spring Framework 7 — Resilience Features</a> — @ConcurrencyLimit, ConcurrencyThrottleInterceptor, Virtual Thread bağlamı</li><li><a href="https://medium.com/@gungor.akbiyik/circuit-breaker%C4%B1-do%C4%9Fru-kurmak-state-machine-den-production-tuning-e-d998755ec722">Serinin circuit breaker yazısı</a> — kardeş yazı: zamana bakan savunma</li><li><a href="https://medium.com/@gungor.akbiyik/redis-down-kolay-senaryo-as%C4%B1l-katil-yava%C5%9F-redis-606ff189525c">Redis Down Kolay Senaryo. Asıl Katil: Yavaş Redis</a> — bu yazının bağlamı: katmanlı savunmanın bütünü</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=0b6c53c62a83" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Circuit Breaker’ı Doğru Kurmak: State Machine’den Production Tuning’e]]></title>
            <link>https://medium.com/@gungor.akbiyik/circuit-breaker%C4%B1-do%C4%9Fru-kurmak-state-machine-den-production-tuning-e-d998755ec722?source=rss-3597415c14fc------2</link>
            <guid isPermaLink="false">https://medium.com/p/d998755ec722</guid>
            <dc:creator><![CDATA[Güngör Akbıyık]]></dc:creator>
            <pubDate>Thu, 16 Jul 2026 04:33:33 GMT</pubDate>
            <atom:updated>2026-07-16T04:33:33.411Z</atom:updated>
            <content:encoded><![CDATA[<p>Ödeme sağlayıcınıza giden her istek 30 saniye timeout’a kadar bekliyor. Sağlayıcı incident yaşıyor ama sizin sisteminiz bunu bilmiyor. Sipariş servisindeki thread’ler tükeniyor, kuyruk büyüyor, müşteriler yarım dakika bekleyip “işlem tamamlanamadı” hatası alıyor. Arka planda hâlâ deneme üstüne deneme gidiyor, tükenmiş sağlayıcıya.</p><p><a href="https://medium.com/@gungor.akbiyik/redis-down-kolay-senaryo-as%C4%B1l-katil-yava%C5%9F-redis-606ff189525c">Önceki yazıda</a> bu problemi Redis bağlamında ele almış, beş katmanlı savunmanın ikinci katmanı olarak circuit breaker’ı tek bir config bloğu ve iki paragrafla geçiştirmiştim. Burada işin mantığını sıfırdan kuruyoruz: state machine nasıl işler, her ayar ne yapar, Spring Boot’ta gerçek kullanım nasıl olur, sahada hangi tuzaklara en sık düşülür.</p><h3>Neden Böyle Bir Şeye İhtiyaç Var?</h3><p>Uzak bir bağımlılığa (Redis, başka bir mikroservis, ödeme sağlayıcısı) çağrı yapıyorsunuz. Bağımlılık sağlıklıyken her şey güzel. Bağımlılık bozulduğunda üç seçeneğiniz var:</p><ol><li><strong>Beklemek.</strong> Timeout’a kadar. Her istek, kaybedeceği belli olan bir bahsi sonuna kadar oynar. Timeout 100 ms bile olsa, saniyede 500 istekte bu saniyede 50 saniyelik toplam bekleme demek. Thread’ler boşa yanar.</li><li><strong>Retry etmek.</strong> Daha kötü. Zaten zorlanan bağımlılığa daha çok yük bindirirsiniz. Bozulan sisteme retry fırtınası göndermek, boğulan adama kova ile su atmaktır.</li><li><strong>Denemeyi bırakmak.</strong> Bağımlılığın bozuk olduğunu <em>hatırlamak</em> ve bir süre hiç uğramamak. İşte circuit breaker bu üçüncü seçeneğin kendisi.</li></ol><p>İsim elektrik tesisatından geliyor. Evdeki sigorta, hattan aşırı akım geçtiğinde devreyi fiziksel olarak açar. Amaç hattı cezalandırmak değil, evi yangından korumaktır. Yazılımdaki karşılığı da aynı: art arda yeterince başarısızlık gördüysen devreyi aç, istekleri o yola hiç sokma, sistemin geri kalanını koru.</p><p>Buradaki kritik kavram şu: circuit breaker bir <strong>hafıza</strong>dır. Timeout tek bir isteğin ne kadar bekleyeceğini söyler ama her istek aynı acıyı sıfırdan yaşar. Circuit breaker ise geçmiş isteklerin sonucunu toplar ve “bu yol şu an bozuk” bilgisini <em>sonraki</em> isteklere taşır. Timeout bireysel savunmadır, circuit breaker kolektif.</p><h3>State Machine: Üç Durum, Dört Geçiş</h3><p>Circuit breaker’ın kalbi üç durumlu bir state machine:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*51-K1lVPh82Cm7gH4bqx1g.png" /></figure><p><strong>CLOSED (kapalı devre).</strong> Normal hâl. İsimlendirme kafa karıştırır: kapalı = akım geçiyor = istekler Redis’e/servise gidiyor. Elektrik metaforunu hatırlayın: devre kapalıyken lamba yanar. Bu durumda breaker sadece izler: her çağrının sonucunu (başarılı, hatalı, yavaş) kaydeder ve oranları hesaplar.</p><p><strong>OPEN (açık devre).</strong> Eşik aşıldı, sigorta attı. Artık istekler korunan koda <strong>hiç girmez</strong>. Breaker anında CallNotPermittedException fırlatır. Maliyet neredeyse sıfırdır: ne network çağrısı var, ne timeout beklemesi, ne thread işgali. Sadece bir exception ve fallback yolu.</p><p><strong>HALF_OPEN (yarı açık).</strong> Açık durumda sonsuza kadar kalınmaz, bağımlılık belki düzelmiştir. Bekleme süresi dolunca breaker sınırlı sayıda “keşif çağrısına” izin verir. Bu çağrılar gerçek isteklerdir ama sayıları kısıtlıdır: 10 tanesine izin verilir mesela, gerisi yine reddedilir. Keşif çağrıları iyi giderse devre kapanır (normale dönüş), kötü giderse tekrar açılır (bekleme yeniden başlar).</p><p>HALF_OPEN’ın varlığı, önceki yazıda bahsettiğim <strong>flapping</strong> modunun ilacıdır. Half-open olmasaydı iki kötü seçenek kalırdı: ya devre bir kez açılınca elle müdahaleye kadar açık kalır (Redis düzelse bile cache kullanılmaz), ya da bekleme bitince tam trafik geri döner (Redis daha tam toparlanmadan 500 istek/sn yer ve tekrar çöker). Half-open, dönüşü <strong>kademeli</strong> yapar: önce 10 istekle nabız yoklanır.</p><p><strong>İki özel durum ve manuel kontrol.</strong> Bu üç durum otomatik akışın tamamı ama API iki durum daha tanır. FORCED_OPEN devreyi elle açık kilitler (hiçbir çağrı geçmez, otomatik half-open geçişi de yapılmaz), DISABLED ise breaker’ı tamamen bypass eder (her çağrı geçer, hiçbir kayıt tutulmaz). İkisine de yalnızca elle geçilir. CircuitBreaker arayüzü bu geçişleri transitionToOpenState(), transitionToClosedState(), transitionToForcedOpenState(), transitionToDisabledState() ve reset() ile açar. Kullanım yerleri somut: bakıma alınacak bir bağımlılığı FORCED_OPEN ile önden devre dışı bırakmak, ya da testte devreyi elle açıp fallback yolunun gerçekten çalıştığını doğrulamak. İki durum metriklerde de görünür, state etiketinin forced_open ve disabled değerleri olarak.</p><h3>Karar Mekanizması: Sliding Window</h3><p>Breaker “eşik aşıldı” kararını neye göre veriyor? Son çağrıların kayıtlarını tutan bir <strong>sliding window</strong> üzerinden. İki tip var:</p><p><strong>COUNT_BASED:</strong> son N çağrıya bakar. slidingWindowSize(50) dediyseniz, hafızada son 50 çağrının sonucu durur ve oranlar bu 50 üzerinden hesaplanır. 51. çağrı geldiğinde en eski kayıt düşer.</p><p><strong>TIME_BASED:</strong> son N saniyeye bakar. slidingWindowSize(60) + TIME_BASED = son 60 saniyedeki tüm çağrılar.</p><p>Hangisi ne zaman? Trafiği düzensiz endpoint’lerde TIME_BASED yanıltabilir: gece trafik azken 60 saniyede 3 çağrı olur ve 2&#39;si hata verirse oran %66 görünür. COUNT_BASED “son 50 çağrı” dediği için trafik hızından bağımsızdır, cache gibi sürekli çağrılan yollar için genelde daha öngörülebilirdir. Önceki yazıdaki örnek bu yüzden COUNT_BASED.</p><p>Window’daki her kayıt üç sonuçtan biridir:</p><ul><li><strong>Başarılı</strong> — çağrı normal döndü, süresi de eşiğin altında.</li><li><strong>Hatalı</strong> — exception fırladı (hangi exception’ların sayılacağı ayarlanabilir, birazdan).</li><li><strong>Yavaş</strong> — çağrı <em>başarılı</em> döndü ama süresi slowCallDurationThreshold&#39;u aştı. Bu ayrı bir kategori ve circuit breaker&#39;ın en az bilinen, en değerli özelliği. Bağımlılıklar çoğu zaman temiz düşmez, yavaşlar: GC pause yaşayan komşu mikroservis, kapasitesi dolan üçüncü parti API, &quot;down değil slow&quot; moddaki Redis. Hepsine karşı tek otomatik savunma bu.</li></ul><p>İki ayrı oran hesaplanır ve <strong>ikisinden biri</strong> eşiği aşarsa devre açılır:</p><pre>failureRate = hatalı / (window&#39;daki toplam)     ≥ failureRateThreshold  → OPEN<br>slowCallRate = yavaş / (window&#39;daki toplam)     ≥ slowCallRateThreshold → OPEN</pre><p>Bir de sigorta payı var: minimumNumberOfCalls. Window&#39;da en az bu kadar çağrı birikmeden hiçbir oran hesaplanmaz. Sebebi istatistiksel: uygulama yeni açıldı, ilk 2 çağrının 1&#39;i hata verdi diye %50&#39;ye ulaşıp devreyi açmak saçma olur. Default 100&#39;dür ve bu default, &quot;circuit breaker&#39;ım hiç açılmıyor&quot; şikayetlerinin bir numaralı sebebidir: window size 10 yaptıysanız ama minimumNumberOfCalls 100&#39;de kaldıysa, COUNT_BASED window&#39;da aynı anda en fazla 10 kayıt olur ve 100&#39;e asla ulaşılmaz. Devre matematiksel olarak hiç açılamaz. Bu ikiliyi her zaman birlikte ayarlayın.</p><h3>Ayarlar Tek Tek</h3><p>Resilience4j’nin tam konfigürasyonu üzerinden gidelim. Önce kod, sonra satır satır:</p><pre>CircuitBreakerConfig config = CircuitBreakerConfig.custom()<br>        // --- karar penceresi ---<br>        .slidingWindowType(SlidingWindowType.COUNT_BASED)<br>        .slidingWindowSize(50)<br>        .minimumNumberOfCalls(20)<br><br>        // --- açılma eşikleri ---<br>        .failureRateThreshold(50)                            // yüzde<br>        .slowCallDurationThreshold(Duration.ofMillis(150))<br>        .slowCallRateThreshold(50)                           // yüzde<br><br>        // --- open → half-open geçişi ---<br>        .waitDurationInOpenState(Duration.ofSeconds(5))<br>        .automaticTransitionFromOpenToHalfOpenEnabled(true)<br><br>        // --- half-open davranışı ---<br>        .permittedNumberOfCallsInHalfOpenState(10)<br>        .maxWaitDurationInHalfOpenState(Duration.ZERO)<br><br>        // --- neyin &quot;hata&quot; sayılacağı ---<br>        .recordExceptions(IOException.class, TimeoutException.class)<br>        .ignoreExceptions(BusinessException.class)<br>        .build();</pre><p><strong>slidingWindowSize + minimumNumberOfCalls.</strong> Window ne kadar küçükse breaker o kadar hızlı tepki verir ama gürültüye de o kadar açıktır (3–4 tesadüfi timeout devreyi açabilir). Ne kadar büyükse o kadar kararlıdır ama tepkisi gecikir. Cache gibi yüksek hacimli bir yol için 50–100 makul bir orta yol. minimumNumberOfCalls’u window size’ın altında veya eşit tutun, yoksa Karar Mekanizması bölümünde anlattığım “hiç açılmayan devre” tuzağına düşersiniz.</p><p><strong>failureRateThreshold.</strong> Yüzde cinsinden. Default 50. Bunu düşürmek breaker’ı agresifleştirir. Cache için agresif olmak mantıklı (miss zaten tolere edilebilir, erken açılmanın maliyeti düşük). Ödeme servisi gibi “fallback’i olmayan” bir bağımlılık için tersine, devre açmak = işlem kaybı demek olduğundan daha tutucu bir eşik seçilir.</p><p><strong>slowCallDurationThreshold + slowCallRateThreshold.</strong> Önceki yazının baş düşmanını yakalayan ikili. “Kaç ms üstü yavaş sayılır” + “yavaşların oranı kaçı geçerse açılır”. Threshold’u, korunan bağımlılığın <em>normal</em> latency’sinin belirgin üstüne ama timeout’unun altına koyun. Redis örneği: normal cevap &lt; 5 ms, command timeout 100 ms, slow eşiği 150 ms (timeout’lu çağrılar zaten hata sayılır, bu eşik timeout’a <em>yaklaşan ama yetişmeyen</em> çağrıları yakalar). Aynı akıl servisler arası REST çağrısı için: p99 latency 400 ms, timeout 2 sn ise slow eşiği 1 sn civarı makuldür. Bu iki satır atlanırsa breaker yalnızca exception sayar ve yavaş-ama-cevap-veren bağımlılığa karşı kördür. Çoğu örnekte, çoğu üründe atlanır.</p><p><strong>waitDurationInOpenState.</strong> Devre açıldıktan sonra half-open denemesine kadar bekleme. Kısa tutarsanız (1–2 sn) bozuk bağımlılığı sık sık dürtersiniz, uzun tutarsanız (60 sn) bağımlılık düzeldiği hâlde dakikalarca fallback’te kalırsınız. Doğru değer bağımlılığın tipik toparlanma süresidir. Cache için 5–10 saniye iyi bir denge: Redis’in kısa network kesintileri saniyeler içinde affedilir, gerçek arızada da dürtme yükü ihmal edilebilir. Komşu bir mikroservisin toparlanması genelde bir pod restart’ı veya rolling deploy’dur (30–60 sn). Orada 15–30 sn daha gerçekçidir. Üçüncü parti API’lerin incident’ları ise dakikalarla ölçülür, 30–60 sn wait yaygındır.</p><p><strong>automaticTransitionFromOpenToHalfOpenEnabled.</strong> İnce ama önemli bir detay: süre dolduğunda HALF_OPEN’a geçişi kimin tetiklediğini belirler. Default <strong>false</strong>’tur ve false’ken breaker’da kronometre yoktur, sadece “ne zaman açıldığını” bilir. Geçiş, süre dolduktan sonra gelen <em>ilk çağrının anında</em> olur (çağrı gelir, breaker süreye bakar, dolmuşsa o anda geçer ve çağrıyı keşif çağrısı olarak alır). true yaparsanız breaker kendi zamanlayıcısını kurar ve süre dolduğu an, çağrı gelmese bile, kendiliğinden HALF_OPEN’a geçer.</p><p>Somut fark düşük trafikte görünür. Devre 10:00:00&#39;da açıldı, wait 5 sn, sonraki çağrı 10:02:00&#39;da geliyor. false’ta 10:00:00–10:02:00 arası state metrikte ve health’te OPEN görünmeye devam eder. Bağımlılık çoktan düzelmiş olsa bile. Davranışsal zarar yok (çağrı yoksa denenecek şey de yok) ama “state OPEN’a alarm kur” yaklaşımı için resim yanıltıcıdır: alarm, arıza bittiği hâlde trafik gelene kadar susmaz. true’da state 10:00:05&#39;te kendiliğinden HALF_OPEN olur, dashboard gerçeği söyler. İki modda da çağrıların kaderi aynıdır (süre dolmadan gelen reddedilir, sonrası girer). Fark yalnızca gözlemde.</p><p><strong>permittedNumberOfCallsInHalfOpenState.</strong> Keşif çağrısı sayısı. Bu N çağrının sonucuna göre kapanma/yeniden açılma kararı verilir. Çok küçük (1–2) olursa tek şanslı çağrı devreyi erken kapatabilir, çok büyük olursa bozuk bağımlılığa half-open’da bile ciddi trafik gider. 5–10 tipik.</p><p><strong>maxWaitDurationInHalfOpenState.</strong> Half-open’da sonuç bekleme üst sınırı. Default 0, yani sınırsız: N çağrının tamamlanması beklenir. Sıfırdan büyük bir değer verirseniz, o süre içinde N çağrı tamamlanmadıysa breaker beklemekten vazgeçip tekrar open’a döner. Düşük trafikli yollarda half-open’da asılı kalmayı önler.</p><p><strong>recordExceptions / ignoreExceptions.</strong> Neyin “hata” sayılacağı. Bu liste düşünülmeden bırakılırsa breaker yanlış şeye tepki verir. Klasik hata: HTTP client’ta 404&#39;ün veya validation hatasının failure sayılması. Ürün bulunamadı diye devre açılmaz, o bir <em>iş sonucu</em>dur, altyapı arızası değil. Kural şu: <strong>bağımlılığın sağlığı hakkında bilgi taşıyan exception’lar kaydedilir</strong> (IOException, TimeoutException, connection hataları), iş mantığı exception’ları ignore edilir. ignoreExceptions’a giren exception’lar window’a hiç yazılmaz, orana da girmez.</p><p>Az bilinen bir yan etki var: recordExceptions&#39;ı doldurduğunuz an anlam tersine döner. Liste boşken (default) ignoreExceptions dışındaki her exception failure sayılır. Ama recordExceptions&#39;a tek bir sınıf bile yazarsanız, artık <strong>sadece</strong> o listedekiler failure sayılır, listede olmayan her exception başarı (success) muamelesi görür. Yani recordExceptions&#39;ı doldurup bir hata tipini eklemeyi unutmak, o hatayı sessizce &quot;başarılı çağrı&quot; diye window&#39;a yazar ve devrenin açılmasını engeller. Genelde ikisinden birini seçmek daha güvenli: ya sadece ignoreExceptions ile &quot;şunlar hariç her şey failure&quot;, ya sadece recordExceptions ile &quot;sadece şunlar failure&quot;. İkisini birden kullanırken listelerin kapsamını iyi düşünün.</p><h3>Spring Boot ile Kullanım</h3><p>Programmatic API’yi (önceki yazıdaki CircuitBreaker.of(...) hâli) gördük. Gerçek projede Spring entegrasyonu üç şey ekler: YAML&#39;dan konfigürasyon, annotation ile kullanım, actuator ile gözlem.</p><p>Bir çerçeve düzeltmesi de yapalım: piyasada breaker’ın en yoğun kullanıldığı yer cache değil, <strong>servisler arası HTTP çağrılarıdır</strong>. Sipariş servisinin stok servisine gitmesi, ödeme sağlayıcısına (iyzico, Stripe) yapılan REST çağrısı, SMS/e-posta/KYC gibi üçüncü parti entegrasyonlar. Breaker’ların ezici çoğunluğu bu sınırlarda durur, çünkü en kırılgan yer başkasının kontrolündeki network sınırıdır. Bu bölümün örnekleri de bu ağırlığa göre seçildi: annotation örneği bir ödeme sağlayıcısı çağrısı, programmatic örnek ise önceki yazıda gördüğümüz cache okuması bağlantısı.</p><h3>Bağımlılıklar</h3><pre>&lt;dependency&gt;<br>    &lt;groupId&gt;io.github.resilience4j&lt;/groupId&gt;<br>    &lt;artifactId&gt;resilience4j-spring-boot3&lt;/artifactId&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>    &lt;artifactId&gt;spring-boot-starter-aop&lt;/artifactId&gt;   &lt;!-- annotation&#39;lar AOP ile çalışır --&gt;<br>&lt;/dependency&gt;<br>&lt;dependency&gt;<br>    &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;<br>    &lt;artifactId&gt;spring-boot-starter-actuator&lt;/artifactId&gt;  &lt;!-- health + events + metrics --&gt;<br>&lt;/dependency&gt;</pre><p>AOP starter’ı unutulursa annotation’lar <strong>sessizce hiçbir şey yapmaz</strong>. Exception yok, uyarı yok, sadece koruma yok. Bu, entegrasyonun bir numaralı tuzağıdır.</p><h3>YAML Konfigürasyonu</h3><pre>resilience4j:<br>  circuitbreaker:<br>    configs:<br>      default:                                  # paylaşılan taban konfigürasyon<br>        slidingWindowType: COUNT_BASED<br>        slidingWindowSize: 50<br>        minimumNumberOfCalls: 20<br>        failureRateThreshold: 50<br>        slowCallDurationThreshold: 150ms<br>        slowCallRateThreshold: 50<br>        waitDurationInOpenState: 5s<br>        automaticTransitionFromOpenToHalfOpenEnabled: true<br>        permittedNumberOfCallsInHalfOpenState: 10<br>        registerHealthIndicator: true<br>        ignoreExceptions:<br>          - com.example.BusinessException<br>    instances:<br>      redisCache:                               # bu isimle @CircuitBreaker&#39;dan çağrılır<br>        baseConfig: default<br>      inventoryService:                         # komşu mikroservis (REST)<br>        baseConfig: default<br>        slowCallDurationThreshold: 1s<br>        waitDurationInOpenState: 15s            # toparlanma = pod restart / deploy<br>      paymentProvider:<br>        baseConfig: default<br>        failureRateThreshold: 70                # ödeme için daha tutucu<br>        slowCallDurationThreshold: 2s<br>        waitDurationInOpenState: 30s</pre><p>Yapı iki katmanlı: configs altında yeniden kullanılabilir tabanlar, instances altında isimli breaker&#39;lar. Her instance bir tabandan miras alıp (baseConfig) istediği alanı ezebilir. Bu, &quot;her bağımlılığın kendi breaker&#39;ı olsun ama konfigürasyon çoğaltılmasın&quot; dengesinin çözümü. Üç instance&#39;ın farklılaşması tesadüf değil, karakter farkı: cache hızlı ve fallback&#39;i ucuz (agresif eşik, kısa wait), komşu servis orta hızlı ve deploy&#39;la toparlanıyor (orta değerler), ödeme sağlayıcısı yavaş, dışarıda ve fallback&#39;i acı (tutucu eşik, uzun wait).</p><p>Burada bir tasarım kuralı: <strong>breaker’lar bağımlılık başına ayrılır, uygulama başına değil.</strong> Redis ile ödeme sağlayıcısı aynı breaker’ı paylaşırsa, Redis’in arızası ödeme yolunu da fallback’e düşürür. Tersi aşırılık da var: her metoda ayrı breaker açmak window’ları böler ve hiçbirinde istatistiksel anlamlılık birikmez. Doğru granülarite genelde “arıza birimi başına bir breaker”dır: redisCache, inventoryService, paymentProvider.</p><h3>Annotation ile Kullanım</h3><p>En yaygın senaryo üzerinden gidelim: dış bir ödeme sağlayıcısına REST çağrısı.</p><pre>@Service<br>public class PaymentClient {<br><br>    private final RestClient restClient;   // WebClient veya Feign de olabilir, breaker umursamaz<br><br>    @CircuitBreaker(name = &quot;paymentProvider&quot;, fallbackMethod = &quot;providerUnavailable&quot;)<br>    public PaymentResult charge(ChargeRequest request) {<br>        return restClient.post()<br>                .uri(&quot;/v1/charges&quot;)<br>                .body(request)<br>                .retrieve()<br>                .body(PaymentResult.class);<br>    }<br><br>    // fallback: aynı parametreler + sonda exception parametresi, aynı dönüş tipi<br>    private PaymentResult providerUnavailable(ChargeRequest request, Throwable t) {<br>        // ödeme &quot;miss sayılıp geçilemez&quot;: işlemi beklemeye al, kullanıcıya dürüst cevap dön<br>        return PaymentResult.pending(request.orderId());<br>    }<br>}</pre><p>name = &quot;paymentProvider&quot; YAML&#39;daki instance&#39;a bağlanır. Fallback metodunun imzası kurallıdır: orijinal metotla <strong>aynı parametreler</strong>, sonuna eklenmiş bir exception parametresi, <strong>aynı dönüş tipi</strong>. İmza tutmazsa çalışma zamanında NoSuchMethodException benzeri bir hatayla karşılaşırsınız, derleme zamanında değil.</p><p>Fallback’in içeriği bağımlılığın karakterine göre değişir ve bu, breaker kurmanın asıl düşünme işidir: cache’te fallback “miss say, DB’ye git” kadar ucuzdur. Stok servisinde “son bilinen değeri göster” veya “stok bilgisi şu an yok” olabilir. Ödemede ise işlemi sessizce kaybetmek yasak olduğundan fallback genelde “beklemeye al / kuyruğa yaz / kullanıcıya açıkça bildir”dir.</p><p>İnce ayrım: fallback yalnızca devre açıkken değil, <strong>her exception’da</strong> çalışır. Devre kapalıyken sağlayıcıdan timeout gelirse de providerUnavailable döner. Exception tipine göre farklı fallback da yazılabilir (biri CallNotPermittedException alan, biri Throwable alan iki overload): breaker açıkken loglamayı kısmak için kullanışlı, yoksa devre açıkkenki her istek &quot;provider error&quot; logu basar ve log sisteminizi boğar.</p><p>Annotation yaklaşımının sınırı da bilinsin: AOP proxy’si üzerinden çalıştığı için <strong>self-invocation’da devreye girmez.</strong> Aynı class içinden this.charge(request) çağrısı proxy&#39;yi bypass eder, breaker&#39;ı da. Bu klasik Spring AOP tuzağı burada da geçerli. Böyle durumda ya çağrıyı başka bean&#39;e taşırsınız ya da programmatic API&#39;ye dönersiniz.</p><h3>Programmatic Kullanım (Spring İçinde)</h3><p>Annotation her yere uymaz: lambda içindesiniz, dinamik isim gerekiyor, ya da AOP tuzaklarından uzak durmak istiyorsunuz. Spring Boot starter’ı bir CircuitBreakerRegistry bean&#39;i verir, breaker&#39;ı oradan çekersiniz. Örnek, önceki yazıdaki cache okuması:</p><pre>@Service<br>public class ProductCacheClient {<br><br>    private final CircuitBreaker breaker;<br><br>    public ProductCacheClient(CircuitBreakerRegistry registry) {<br>        this.breaker = registry.circuitBreaker(&quot;redisCache&quot;);   // YAML&#39;daki instance<br>    }<br><br>    public Optional&lt;ProductView&gt; fromCache(long id) {<br>        try {<br>            return breaker.executeSupplier(() -&gt;<br>                    Optional.ofNullable(readFromRedis(&quot;product:&quot; + id)));<br>        } catch (CallNotPermittedException e) {<br>            return Optional.empty();   // devre açık: denemeden miss<br>        } catch (Exception e) {<br>            return Optional.empty();   // gerçek hata: miss<br>        }<br>    }<br>}</pre><p>İki catch bloğunun ayrı olması bilinçli: CallNotPermittedException &quot;denemedik bile&quot; demek, diğerleri &quot;denedik, olmadı&quot;. Metrikte ve logda bu ikisini ayırmak istersiniz, çünkü ilki breaker&#39;ın <em>çalıştığının</em>, ikincisi bağımlılığın <em>bozuk olduğunun</em> kanıtı.</p><h3>Diğer Resilience4j Anotasyonlarıyla Sıralama</h3><p>Resilience4j’de circuit breaker tek annotation değil. Aynı ailede @Retry, @RateLimiter, @TimeLimiter, @Bulkhead de var ve aynı metoda <strong>alt alta</strong> yazılabilirler:</p><pre>@Retry(name = &quot;inventoryService&quot;)<br>@CircuitBreaker(name = &quot;inventoryService&quot;, fallbackMethod = &quot;stockUnknown&quot;)<br>public StockInfo stock(long productId) {<br>    return restClient.get().uri(&quot;/stock/{id}&quot;, productId)<br>            .retrieve().body(StockInfo.class);<br>}</pre><p>Kaynakta düz duran bu annotation’ların her biri çalışma zamanında metodu saran bir AOP katmanıdır. İki katman aynı metodu sarınca biri mecburen diğerinin dışında kalır, matruşka gibi. Soru şu: kim kimi sarıyor? Cevap yazım sırasından <strong>bağımsızdır</strong>. Resilience4j’nin default aspect sırası dıştan içe şöyle:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3NMNuPEQ1bMOSPnhYwQyZg.png" /></figure><p>Bunun anlamını yukarıdaki örnekte bir çağrının hayatıyla izleyelim (maxAttempts: 3, stok servisi bozuk). Çağrı önce Retry&#39;a girer, Retry &quot;1. deneme&quot; deyip içerideki breaker&#39;a iletir. Breaker devre kapalı olduğundan geçirir, metot IOException fırlatır. Exception içeriden dışarı çıkarken önce breaker&#39;dan geçer ve window&#39;a bir &quot;hatalı&quot; kaydı düşer, sonra Retry&#39;a ulaşır. Retry 2. ve 3. denemeyi yapar, her biri yine breaker&#39;dan geçip window&#39;a ayrı kayıt yazar. Sonuç: kullanıcının tek çağrısı, breaker&#39;ın gözünde üç ayrı çağrıdır. Çoğu zaman istediğiniz de budur. Bozuk bağımlılıkta denemeler istatistiği hızla besler, devre daha çabuk açılır.</p><p>Sıranın öteki sonucu devre açıkken görünür: Retry en dışta olduğundan üç denemenin üçü de breaker duvarına çarpıp anında CallNotPermittedException alır. Deneme yapılır ama hiçbiri network&#39;e çıkmaz, maliyet üç exception&#39;dan ibaret. Sıra ters olsaydı (breaker dışta) breaker üç denemeyi tek çağrı olarak görürdü: window 3 kat yavaş dolar, devre geç açılır. Default sıra bu yüzden bilinçli bir seçim. İstisnai ihtiyaçta resilience4j.retry.retryAspectOrder gibi property&#39;lerle değiştirilebilir ama nadiren gerekir.</p><p>Cache okumasında zaten retry kullanmıyoruz (önceki yazıdaki kural: miss say, yola devam). Retry’ın anlamlı olduğu yerler idempotent yazma ve kritik okumadır. Oralarda da bu default sıra doğru davranışın kendisidir.</p><h3>Gözlem: Açılan Devreyi Görmek</h3><p>Breaker kurmak işin yarısı. Devrenin <em>ne zaman açıldığını görmek</em> öteki yarısı, çünkü açılan devre bir arızanın işaretidir ve fallback sayesinde kullanıcı hissetmiyor diye sessiz kalmamalı.</p><p><strong>Health endpoint.</strong> Health’e yansıma iki ayara birden bağlı. Config tarafında registerHealthIndicator: true breaker&#39;ı health contributor olarak kaydeder. Management tarafında management.health.circuitbreakers.enabled: true de gerekir, bu Spring Boot 3&#39;te default kapalıdır ve unutulursa breaker health&#39;te hiç görünmez. İkisi birlikte açıkken:</p><pre>GET /actuator/health<br>→ &quot;redisCache&quot;: { &quot;status&quot;: &quot;UP&quot;, &quot;details&quot;: { &quot;state&quot;: &quot;CLOSED&quot;, &quot;failureRate&quot;: &quot;2.0%&quot;, ... } }</pre><p>State’ten status’e eşleme şöyle: CLOSED → UP, OPEN → DOWN, HALF_OPEN → UNKNOWN. OPEN’ın DOWN raporlaması burada kritik. Bu health, Kubernetes <strong>liveness</strong> probe’una bağlanırsa önceki yazıda saydığım ayak bağı #1&#39;i yaratırsınız: Redis arızası pod restart fırtınasına döner. Breaker health’i insan/dashboard içindir, liveness için değil.</p><p>State’ten status’e eşleme şöyle: CLOSED → UP, OPEN → DOWN, HALF_OPEN → UNKNOWN. OPEN’ın DOWN raporlaması burada kritik. Bu health, Kubernetes <strong>liveness</strong> probe’una bağlanırsa önceki yazıda saydığım ayak bağı #1&#39;i yaratırsınız: Redis arızası pod restart fırtınasına döner. Breaker health’i insan/dashboard içindir, liveness için değil.</p><p><strong>Events endpoint.</strong> Son olayların kaydı:</p><pre>GET /actuator/circuitbreakerevents/redisCache→ STATE_TRANSITION: CLOSED → OPEN, ERROR, SLOW_CALL_RATE_EXCEEDED ...</pre><p>Arıza sonrası “devre ne zaman, neden açıldı” sorusunun cevabı burada. Aynı olaylara kod içinden de abone olunabilir (breaker.getEventPublisher().onStateTransition(...)): state geçişini log&#39;a ve alarma bağlamanın yolu bu.</p><p><strong>Micrometer metrikleri.</strong> Starter, Prometheus’a şunları verir:</p><ul><li>resilience4j_circuitbreaker_state — anlık durum (alarm buraya kurulur: state == OPEN)</li><li>resilience4j_circuitbreaker_failure_rate / slow_call_rate — oranların seyri</li><li>resilience4j_circuitbreaker_calls_seconds — sonuç tipine göre (successful/failed/ignored) çağrı süreleri</li><li>resilience4j_circuitbreaker_not_permitted_calls_total — devre açıkken reddedilen çağrı sayısı</li></ul><p>Önceki yazının kapanışında sorduğum üçüncü sorunun (“Redis yavaşlarsa hangi alarm öter?”) somut cevabı: slow_call_rate üzerine kurulmuş bir alarm + state OPEN&#39;a geçince tetiklenen bir bildirim.</p><h3>Tuning Rehberi ve Klasik Hatalar</h3><p>Ayar değerleri kopyala-yapıştır ile değil, korunan bağımlılığın karakterine göre seçilir. Pratik akıl yürütme sırası:</p><ol><li><strong>Normal latency’yi ölç.</strong> slowCallDurationThreshold bunun belirgin üstü, timeout’un altı.</li><li><strong>Trafik hacmine göre window seç.</strong> Saniyede yüzlerce çağrı alan yol için COUNT_BASED 50–100 saniyeler içinde dolar ve hızlı tepki verir. Dakikada 5 çağrı alan yolda aynı window’un dolması 10–20 dakika sürer: orada window’u küçültmek veya TIME_BASED’e geçmek gerekir.</li><li><strong>Fallback’in maliyetine göre eşik seç.</strong> Fallback ucuzsa (cache miss) agresif eşik, fallback acıysa (işlem reddi) tutucu eşik.</li><li><strong>waitDuration’ı bağımlılığın tipik toparlanma süresine göre seç.</strong> Redis failover penceresi 10–30 sn ise 5 sn’lik wait, failover boyunca birkaç kez half-open deneyip tekrar açılır: sorun değil, maliyeti 10&#39;ar keşif çağrısı. Komşu servisin tipik toparlanması bir rolling deploy ise wait’i 15–30 sn’ye çekin. Üçüncü parti API’nin incident geçmişi dakikalarla ölçülüyorsa daha da uzatın.</li></ol><p>Ve sahada en sık görülen beş hata:</p><ol><li><strong>minimumNumberOfCalls &gt; slidingWindowSize</strong> (COUNT_BASED’de): devre matematiksel olarak asla açılamaz. Sessiz, sinsi, yaygın.</li><li><strong>slowCall ayarlarının atlanması</strong>: breaker yalnızca exception görür, yavaş bağımlılığa kör kalır. Down’ı yakalar, asıl katili kaçırır.</li><li><strong>İş exception’larının failure sayılması</strong>: 404 fırtınası veya validation hataları devreyi açar, sağlıklı bağımlılık fallback’e düşer. recordExceptions/ignoreExceptions’ı bilinçli doldurun.</li><li><strong>AOP starter’ının unutulması / self-invocation</strong>: annotation var, koruma yok, kimse fark etmiyor. İlk tatbikatta ortaya çıkar, tatbikat yapılmıyorsa production’da.</li><li><strong>Breaker’ın hiç test edilmemesi</strong>: state machine’in çalıştığının tek kanıtı, onu bilerek tetiklemektir. Staging’de Toxiproxy ile 500 ms latency enjekte edin ve şu döngüyü gözle görün: CLOSED → (slow rate eşiği) → OPEN → (wait) → HALF_OPEN → (Redis düzelince) → CLOSED. Bu döngüyü bir kez izleyen, konfigürasyonun her satırının ne işe yaradığını bir daha unutmaz.</li></ol><h3>Kapanış</h3><p>Circuit breaker’ın özü tek cümle: geçmiş çağrıların sonucunu hatırla ve kaybedeceği belli bahsi oynamayı bırak. State machine (CLOSED/OPEN/HALF_OPEN) bu hafızanın iskeleti, sliding window karar verisi, eşikler de hassasiyet ayarı. Spring tarafında iş üç parça: YAML’da instance tanımla, @CircuitBreaker(name, fallbackMethod) ile bağla, actuator + Micrometer ile izle.</p><p>Bu yazının örnek yelpazesi de aynı mesajı taşıyor: cache (redisCache), komşu mikroservis (inventoryService), dış ödeme sağlayıcısı (paymentProvider). Üçünün eşikleri, bekleme süreleri ve fallback’leri farklı, çünkü arıza karakterleri ve hatanın maliyeti farklı. Konfigürasyon kopyalanmaz, bağımlılığın karakterinden türetilir.</p><p>Önceki yazıyla bağı da netleştirelim: orada breaker, beş katmanlı savunmanın ikinci katmanıydı. Timeout (katman 1) tek isteğin zararını sınırlar, breaker (katman 2) zararın <em>tekrarını</em> keser, bulkhead (katman 3) fallback trafiğinin DB’yi ezmesini önler. Üçü birbirinin alternatifi değil, tamamlayıcısıdır.</p><h3>Kaynaklar</h3><ul><li><a href="https://resilience4j.readme.io/docs/circuitbreaker">Resilience4j — CircuitBreaker Core</a> — state machine, sliding window, tüm config alanları</li><li><a href="https://resilience4j.readme.io/docs/getting-started-3">Resilience4j — Spring Boot 3 Getting Started</a> — starter, YAML, annotation, aspect sırası</li><li><a href="https://resilience4j.readme.io/docs/micrometer">Resilience4j — Micrometer Metrics</a> — metrik isimleri</li><li><a href="https://martinfowler.com/bliki/CircuitBreaker.html">Martin Fowler — CircuitBreaker</a> — desenin klasik tanımı</li><li><a href="https://medium.com/@gungor.akbiyik/redis-down-kolay-senaryo-as%C4%B1l-katil-yava%C5%9F-redis-606ff189525c">Redis Down Kolay Senaryo. Asıl Katil: Yavaş Redis</a> — bu yazının bağlamı: katmanlı savunmanın bütünü</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d998755ec722" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Redis Down Kolay Senaryo. Asıl Katil: Yavaş Redis]]></title>
            <link>https://medium.com/@gungor.akbiyik/redis-down-kolay-senaryo-as%C4%B1l-katil-yava%C5%9F-redis-606ff189525c?source=rss-3597415c14fc------2</link>
            <guid isPermaLink="false">https://medium.com/p/606ff189525c</guid>
            <dc:creator><![CDATA[Güngör Akbıyık]]></dc:creator>
            <pubDate>Wed, 15 Jul 2026 06:41:20 GMT</pubDate>
            <atom:updated>2026-07-15T06:41:20.831Z</atom:updated>
            <content:encoded><![CDATA[<p>Salı sabahı, trafik normal. Bir alarm öttü: p99 latency 8 saniye. Dashboard’a bakıyorsunuz: uygulama thread’leri tavanda, istek kuyruğu büyüyor, kullanıcılar timeout yiyor.</p><p>İlginç olan şu: PostgreSQL paneli bomboş. CPU %4, sorgu yok denecek kadar az. Redis paneli de yeşil: process ayakta, bağlantılar açık, PING cevap veriyor.</p><p>Her şey “up” görünüyor ve sistem ölüyor.</p><p>Sebep, hiçbir sağlık kontrolünün yakalamadığı bir şey: Redis <em>down</em> değil, <em>yavaş</em>. Diskteki bir AOF rewrite, komşu VM’in CPU’yu yemesi ya da bir KEYS * çalıştıran iyi niyetli birisi. Redis artık mikrosaniyede değil, 2 saniyede cevap veriyor. Ve uygulamanız her istekte o 2 saniyeyi sonuna kadar bekliyor.</p><p><a href="https://medium.com/@gungor.akbiyik/cache-stampede-redis-ayakta-veritaban%C4%B1-yerde-db112abc69b0">Bir önceki yazıda</a> cache’in kendi içindeki fırtınayı konuşmuştuk: cache çalışıyor ama key’ler topluca ölüyor. Bu yazı bir sonraki soruyu soruyor: <strong>cache’in kendisi giderse, ya da daha kötüsü gitmeden yavaşlarsa, sistem nasıl ayakta kalır?</strong></p><p>Plan şu: önce masum görünen konfigürasyondaki bombayı bulacağız, sonra dört arıza modunu ayıracağız, sonra da savunmayı katman katman kuracağız: timeout hiyerarşisi, circuit breaker, DB koruması, L1 cache ve degrade merdiveni. Hepsi Java + Spring koduyla.</p><h3>Masum Görünen Konfigürasyon</h3><p>Şu bean’e bakın. Muhtemelen sizde de buna benzer bir tane var, belki auto-configuration’ın arkasına saklanmış:</p><pre>@Bean<br>public LettuceConnectionFactory redisConnectionFactory() {<br>    return new LettuceConnectionFactory(<br>            new RedisStandaloneConfiguration(&quot;redis-prod&quot;, 6379));<br>}</pre><p>Temiz görünüyor. Çalışıyor da. Bomba, görünmeyen bir default’ta:</p><p><strong>Lettuce’ın komut timeout’u 60 saniyedir.</strong></p><p>Redis normal gününde mikrosaniyelerde cevap verdiği için bu default yıllarca hiçbir şeye mal olmaz. Ta ki Redis yavaşlayana kadar. O gün her GET, cevap gelmezse tam 60 saniye bekler. Ve o beklerken bir uygulama thread&#39;ini elinde tutar.</p><p>Matematik acımasız. Diyelim Tomcat’te 200 worker thread var, her istek bir Redis okuması yapıyor ve Redis 2 saniye gecikmeli cevap veriyor:</p><ul><li>Bir thread saniyede en fazla 0,5 istek işleyebilir (2 sn/istek).</li><li>200 thread × 0,5 = <strong>saniyede 100 istek kapasite.</strong></li><li>Gelen trafik 500 istek/sn ise, her saniye 400 istek kuyruğa yığılır.</li></ul><p>Kuyruk saniyeler içinde taşar. İstekler daha thread’e ulaşamadan LB timeout’una takılır. Uygulamanız Redis yüzünden değil, <strong>Redis’i beklemekten</strong> ölür. Veritabanına tek bir sorgu bile düşmeden.</p><p>Bu, “Redis giderse ne olur” planlarının neden çoğu zaman işe yaramadığının cevabı: herkes <em>down</em> senaryosuna plan yapar. Sistemler <em>slow</em> senaryosundan ölür.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DsuNQLddYqN40OlM6tfc8w.png" /></figure><h3>Dört Arıza Modu — Hepsi Aynı Şey Değil</h3><p>“Redis gitti” tek bir olay değil. Dört farklı mod var ve her birinin davranışı, tehlikesi ve ilacı farklı:</p><p><strong>1 — Down (bağlantı reddi).</strong> Process öldü, port kapalı. connection refused milisaniyede döner, kodunuz anında fallback yoluna düşer. Paradoks ama bu <strong>en kolay</strong> mod: hızlı fail eden şeye karşı savunma kurmak kolaydır.</p><p><strong>2 — Slow (yavaş cevap).</strong> Process ayakta, bağlantılar açık, ama cevaplar 100 kat gecikiyor. Health check’ler yeşil, alarm yok. Ve yukarıdaki thread matematiği işliyor. <strong>En tehlikeli</strong> mod: görünmez ve thread rehin alır.</p><p><strong>3 — Flapping (gidip gelme).</strong> Ağ ya da Redis, saniyeler arayla düşüp kalkıyor. Her kopuşta client’lar topluca reconnect dener. Reconnect fırtınası Redis’e ekstra yük bindirir, o yük yeni kopuşları tetikler. Circuit breaker’ın half-open mekaniği tam bu mod için vardır.</p><p><strong>4 — Failover penceresi.</strong> Redis aslında “gitmedi”. Sentinel ya da Cluster, ölen master’ın yerine yenisini seçiyor. Bu seçim saniyeler sürer (birazdan sayıları vereceğim) ve o pencerede yazmalar hata alır, okumalar belirsizleşir. HA kurulumu bu pencereyi <strong>yok etmez, kısaltır.</strong> Savunma katmanlarınız en sık bu modda tetiklenir.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*SsHrLur5h9v8v-i70IDLew.png" /></figure><h3>Kendi Elinizle Tam Kesinti: Dört Ayak Bağı</h3><p>Savunmalara geçmeden, tersini görelim. Aşağıdaki dört alışkanlık, kısmi bir Redis arızasını tam kesintiye çevirir. Dördü de production’da bolca görülür:</p><p><strong>1 — Liveness probe’a Redis’i bağlamak.</strong> Kubernetes liveness check’iniz Redis’e PING atıyorsa, Redis düştüğünde <em>sağlıklı uygulama pod&#39;larınız</em> restart döngüsüne girer. Redis arızası, uygulama kesintisine terfi eder. Cache bir bağımlılıktır ama <em>hayati</em> bağımlılık değildir: liveness&#39;tan çıkarın. En fazla readiness&#39;ta &quot;degraded&quot; olarak raporlayın.</p><p><strong>2–60 saniyelik default timeout.</strong> Yukarıda gördük. Tek satırlık düzeltmesi birazdan.</p><p><strong>3 — Naif fail-open.</strong> “Cache hatası alırsam DB’den okurum” refleksi masum görünür. Ama hit rate %98 olan bir sistemde Redis gittiği an DB, alışık olduğu trafiğin <strong>50 katını</strong> yer. Ve DB’niz yıllar içinde o %2&#39;ye göre boyutlandığı için (kimse kullanılmayan kapasiteye para vermez) bu yük onu da devirir. Naif fail-open, kendi veritabanınıza kendi elinizle düzenlenmiş bir DDoS’tur.</p><p>Burada sinsi bir korelasyon var: <strong>hit rate ne kadar iyiyse, Redis kaybı o kadar ölümcül.</strong> Cache iyileştikçe veritabanı atrofiye uğrar: alçıdaki bacak kası gibi, yük görmedikçe zayıflar.</p><p><strong>4 — Session’ı cache’le aynı yere koymak.</strong> Redis’te hem cache hem HTTP session (ya da sepet, rate-limit sayacı, dağıtık kilit) tutuyorsanız, Redis artık cache değil <strong>kayıt deposudur</strong> ve bu yazının “cache giderse yaşarız” varsayımı sizin için geçerli değildir. Cache kaybı = yavaşlık. Store kaybı = veri/oturum kaybı. İkisini aynı instance’ta tutmak, iki farklı riski tek arıza noktasında birleştirmek demek. Ya ayırın, ya da store tarafının HA’sına cache’ten çok daha ciddi yatırım yapın.</p><p>Şimdi savunmayı kuralım.</p><h3>Birinci Katman: Timeout Hiyerarşisi</h3><p>En ucuz ve en etkili düzeltme:</p><pre>@Bean<br>public LettuceConnectionFactory redisConnectionFactory() {<br>    LettuceClientConfiguration clientConfig = LettuceClientConfiguration.builder()<br>            .commandTimeout(Duration.ofMillis(100))   // Redis için 100 ms bile cömert<br>            .build();<br><br>    return new LettuceConnectionFactory(<br>            new RedisStandaloneConfiguration(&quot;redis-prod&quot;, 6379), clientConfig);<br>}</pre><p>Properties tarafında karşılığı:</p><pre>spring.data.redis.timeout=100ms<br>spring.data.redis.connect-timeout=250ms</pre><p>Sağlıklı bir Redis’ten cevap mikrosaniyelerde, aynı bölgede ağ üzerinden en kötü birkaç milisaniyede gelir. 100 ms’lik bir sınır, normal işleyişte asla dokunulmayan ama yavaşlama gününde uygulamanızın hayatını kurtaran bir tampondur: en kötü senaryoda her istek 60 saniye değil, 100 milisaniye kaybeder.</p><p>Genel kural, timeout’ların <strong>iç içe geçen bir piramit</strong> oluşturması:</p><pre>Redis komutu        ~100 ms     (en içteki, en kısa)<br>  &lt; DB sorgusu      ~1-2 sn<br>    &lt; endpoint       ~5 sn<br>      &lt; LB/gateway   ~30 sn     (en dıştaki, en uzun)</pre><p>İçteki bir bağımlılığın timeout’u dıştakinden uzunsa (60 sn Redis &gt; 30 sn LB gibi), dıştaki sınır her zaman önce patlar ve içerideki bekleme hiçbir işe yaramadan kaynak tüketir.</p><p>Ama dürüst olalım: timeout tek başına yetmez. Redis yavaşken her istek yine de o 100 ms’yi öder. 500 istek/sn’de bu, saniyede 50 saniyelik toplam bekleme demek. Thread havuzunuz yaşar ama gereksiz yere terler. Kaybedeceğini baştan bildiğin bahsi neden her seferinde oynayasın?</p><h3>İkinci Katman: Circuit Breaker — Kaybedilmiş Bahsi Oynamayı Bırak</h3><p>Circuit breaker’ın fikri tek cümle: art arda yeterince başarısızlık gördüysen, bir süre <strong>hiç deneme</strong>. Elektrik sigortası gibi: devre açılır, istekler Redis’e uğramadan fallback yoluna gider, arada bir “düzeldi mi?” diye kontrol edilir (half-open), düzeldiyse devre kapanır.</p><p>Resilience4j ile:</p><pre>CircuitBreakerConfig config = CircuitBreakerConfig.custom()<br>        .slidingWindowType(SlidingWindowType.COUNT_BASED)<br>        .slidingWindowSize(50)                              // son 50 çağrıya bak<br>        .failureRateThreshold(50)                           // %50&#39;si hataysa → devreyi aç<br>        .slowCallDurationThreshold(Duration.ofMillis(150))  // 150 ms üstü = &quot;yavaş çağrı&quot;<br>        .slowCallRateThreshold(50)                          // %50&#39;si yavaşsa → devreyi aç<br>        .waitDurationInOpenState(Duration.ofSeconds(5))     // 5 sn sonra half-open dene<br>        .permittedNumberOfCallsInHalfOpenState(10)<br>        .build();<br><br>CircuitBreaker redisBreaker = CircuitBreaker.of(&quot;redis-cache&quot;, config);</pre><p>Dikkat: bu config Redis’e dair hiçbir şey bilmez. redisBreaker sadece durum tutan bir sayaç kutusudur. Korunacak çağrıyı ancak kullanım anında, executeSupplier&#39;a verdiğiniz lambda ile tanır (birazdan göreceğiz).</p><p>Buradaki en değerli iki satır, çoğu örnekte atlanan slowCall* çifti. failureRateThreshold yalnızca <em>hataları</em> sayar, yani down modunu yakalar. slowCallRateThreshold<strong> ise cevap gelse bile süresine bakar</strong> ve tam olarak bu yazının baş düşmanını, yavaş Redis&#39;i yakalar. Redis tek bir hata bile döndürmeden devre açılır.</p><p>Cache okuma yolu şuna dönüşür:</p><pre>public Optional&lt;ProductView&gt; fromCache(long id) {<br>    try {<br>        return redisBreaker.executeSupplier(() -&gt;<br>                Optional.ofNullable(readFromRedis(&quot;product:&quot; + id)));<br>    } catch (CallNotPermittedException e) {<br>        return Optional.empty();   // devre açık: Redis&#39;i DENEMEDEN miss say<br>    } catch (Exception e) {<br>        return Optional.empty();   // timeout / bağlantı hatası: miss say<br>    }<br>}</pre><p>Devre açıkken maliyet sıfıra iner: ne 100 ms bekleme var ne bağlantı denemesi. Redis düzelene kadar sistem, cache’i hiç yokmuş gibi (ama kontrollü biçimde) çalışır.</p><p>İki not:</p><ul><li><strong>Cache okumasına retry koymayın.</strong> Retry, gecikmeyi katlar ve yavaş Redis’e daha çok yük bindirir. Cache’in doğası gereği bir miss zaten tolere edilebilir. Başarısız okumayı miss sayıp yola devam etmek her zaman daha ucuzdur.</li><li>Spring Framework 7 ile core’a gelen resilience anotasyonlarını (@Retryable, @ConcurrencyLimit) merak edenler için: <strong>circuit breaker bu sete dahil değil.</strong> CB için bugün hâlâ Resilience4j doğru adres. Spring 7&#39;nin setinden @ConcurrencyLimit&#39;i birazdan başka bir katmanda kullanacağız.</li></ul><h3>Üçüncü Katman: Veritabanını Kendi Trafiğinden Koru</h3><p>Devre açıldı, istekler DB yoluna düşüyor. Şimdi ayak bağı #3 ile yüzleşme zamanı: DB o trafiği kaldıramaz. Naif fail-open’ı <strong>rate-limited fail-open</strong>’a çevirmemiz gerekiyor: DB’nin kaldırabileceği kadarını geçir, fazlasını degrade et.</p><p>Spring Framework 7&#39;nin yeni anotasyonu tam bu iş için:</p><pre>@Service<br>public class ProductDbGate {<br><br>    @ConcurrencyLimit(20)   // DB&#39;ye aynı anda en fazla 20 cache-miss sorgusu<br>    public ProductView loadFromDb(long id) {<br>        return repository.loadProductView(id);<br>    }<br>}</pre><p>@ConcurrencyLimit(20), bu metoda eş zamanlı girişi 20 ile sınırlar. 21. istek, bir slot boşalana kadar bekler. Bu, bekleyen istekler için latency demek. Ama DB ayakta kalır ve sıra herkese gelir. Klasik <strong>bulkhead</strong> deseni: gemiyi bölmelere ayır ki bir bölme su alınca gemi batmasın.</p><p>“Bekletme, hemen reddet” davranışı istiyorsanız (bekleyen istek de thread tutar), Resilience4j Bulkhead ile sıfır beklemeli versiyonu kurulur:</p><pre>BulkheadConfig dbGate = BulkheadConfig.custom()<br>        .maxConcurrentCalls(20)<br>        .maxWaitDuration(Duration.ZERO)   // slot yoksa bekleme: anında reddet → degrade<br>        .build();</pre><p>Reddedilen istek hata sayfasına değil, bir sonraki katmana düşer: elimizde hâlâ L1 cache ve degrade merdiveni var.</p><p>Sınır sayısını (20? 50?) tahminle değil ölçümle koyun: DB’nizin cache’siz kaldırabildiği eş zamanlı sorgu sayısı, load test’te çıkar. Bilmiyorsanız muhafazakâr başlayın. Sınırın düşük olması latency yaratır, olmaması kesinti yaratır.</p><h3>Dördüncü Katman: L1 — JVM İçinde Küçük Bir Can Yeleği</h3><p>İki katmanlı cache (L1 in-memory + L2 Redis) genelde hız için önerilir: L1&#39;den okuma, Redis’e ağ turundan bile ucuzdur. Doğru. Ama bence asıl değeri başka yerde: <strong>L1, Redis öldüğü gün sistemde kalan tek cache’tir.</strong></p><p>Caffeine ile:</p><pre>Cache&lt;String, ProductView&gt; l1 = Caffeine.newBuilder()<br>        .maximumSize(10_000)                       // en sıcak 10K kayıt — heap&#39;i düşünerek<br>        .expireAfterWrite(Duration.ofSeconds(45))  // kısa TTL: bayatlık sınırı<br>        .build();</pre><p>Okuma yolu artık üç duraklı. Tüm katmanlar tek metotta birleşiyor:</p><pre>public ProductView getProduct(long id) {<br>    String key = &quot;product:&quot; + id;<br><br>    ProductView v = l1.getIfPresent(key);<br>    if (v != null) {<br>        return v;                                   // L1 hit: Redis&#39;e hiç gitmedik<br>    }<br><br>    Optional&lt;ProductView&gt; l2 = cacheClient.fromCache(id);   // CB korumalı Redis<br>    if (l2.isPresent()) {<br>        l1.put(key, l2.get());<br>        return l2.get();<br>    }<br><br>    ProductView fresh = dbGate.loadFromDb(id);      // bulkhead korumalı DB<br>    l1.put(key, fresh);<br>    cacheClient.tryStore(key, fresh);               // Redis yazılabiliyorsa yaz; yazılamıyorsa sessiz geç<br>    return fresh;<br>}</pre><p>Redis tamamen gittiğinde ne olur? En sıcak 10.000 kayıt hâlâ her pod’un belleğinde. 45 saniyelik TTL ile bile bu, DB’ye inecek trafiğin büyük bölümünü emer, çünkü trafik güç yasasına uyar: okumaların ezici çoğunluğu küçük bir sıcak kümeye gider. Stampede yazısındaki %98&#39;lik hit rate’in anlamı buydu. L1 o sıcak kümenin fotokopisini JVM içinde tutar.</p><p>İki uyarı:</p><ul><li><strong>L1 tutarlılık pahasına gelir.</strong> Her pod’un kendi kopyası var. Bir pod’daki güncelleme diğerinin L1&#39;ini görmez. Bu yüzden TTL kısa tutulur (30–60 sn): “en fazla 45 saniye bayat” çoğu okuma verisi için kabul edilebilir bir sözleşmedir. Değilse (fiyat, bakiye), o veri zaten L1&#39;e girmemeli.</li><li>maximumSize<strong> şart.</strong> Sınırsız L1, Redis arızası gününde heap&#39;i şişirip OOM getirir. Bir arızayı başka arızayla değiştirmiş olursunuz.</li></ul><p>Bu arada Caffeine’in refreshAfterWrite&#39;ı ile L1&#39;e stale-while-revalidate davranışı da eklenebilir. O mekanizmanın detayı önceki yazıda var.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ngAxaEKoDmHW_h0cB_5hLw.png" /></figure><h3>Beşinci Katman: Degrade Merdiveni — Teknik Değil, Ürün Kararı</h3><p>Buraya kadarki katmanlar “isteği nasıl yine de cevaplarız” sorusuna teknik cevaplar verdi. Son katman farklı bir soru sorar: <strong>cevaplayamıyorsak ne gösteririz?</strong></p><p>Bu sorunun cevabı veri türüne göre değişir ve teknik ekipten çok ürün masasına aittir:</p><ul><li><strong>Öneri / kişiselleştirme:</strong> boş dönmek yerine statik bir “en popülerler” listesi dönün. Kullanıcı farkı zor fark eder. Degrade’in en tatlı hali.</li><li><strong>Ürün detayı / katalog:</strong> L1&#39;deki (belki bayat) kopya gayet iyi. “45 saniye önceki açıklama” kimseyi üzmez.</li><li><strong>Arama / listeleme:</strong> DB’den, bulkhead sınırı içinde, belki kısıtlı (ilk N sonuç). Yavaş ama doğru.</li><li><strong>Fiyat, bakiye, stok — para ve doğruluk:</strong> degrade YOK. Bayat bakiye göstermek, bakiye gösterememekten kötüdür. Bu istekler ya taze veriyle cevaplanır ya da açıkça hata döner.</li><li><strong>Rate-limit sayacı Redis’teyse:</strong> karar anı: fail-open (sayaç yok, herkesi geçir) kötüye kullanım riski. Fail-closed (kimseyi geçirme) kesinti demek. Çoğu iş için doğru cevap fail-open + alarm. Güvenlik-kritik uçlar (login denemesi, OTP) için fail-closed.</li></ul><p>Kritik olan şu: bu kararların <strong>arıza anında değil, sakin bir salı öğleden sonrasında</strong> verilmiş olması. Arıza sırasında “bakiyede stale dönebilir miyiz?” tartışması yapılmaz. O karar çoktan kodda yazılı olmalı.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NFw-j40k52ItvCI93ogpXA.png" /></figure><h3>Failover Gerçekliği: HA Pencereyi Kapatmaz, Kısaltır</h3><p>“Bizde Sentinel/Cluster var, bu senaryolar bizi ilgilendirmez” diyorsanız, sayılara bakalım:</p><ul><li><strong>Sentinel:</strong> master’ın öldüğüne karar vermek için down-after-milliseconds bekler. <strong>Default 30 saniye.</strong> Sonra quorum anlaşması + yeni master seçimi + client&#39;ların yeni topolojiyi öğrenmesi. Agresif tune edilmiş kurulumlarda ~10 saniye, default&#39;larla rahat 30-60 saniye.</li><li><strong>Cluster:</strong> cluster-node-timeout default 15 saniye + failover seçimi. Benzer bant.</li><li><strong>Managed servisler</strong> (ElastiCache ve benzerleri, Multi-AZ): tipik 30–60 saniyelik failover pencereleri dokümante edilir.</li></ul><p>Yani en iyi ihtimalle <strong>on saniyeler boyunca</strong> master yok: yazmalar hata alır, bağlantılar kopar. 500 istek/sn’lik bir sistemde 30 saniye = 15.000 istek. O 15.000 isteğin kaderini, yukarıda kurduğumuz katmanlar belirler. HA, savunma katmanlarını gereksiz kılmaz. <strong>Onların en sık tetikleneceği anı tanımlar.</strong></p><p>Client tarafında failover penceresini yumuşatan bir ayar da var, okumaları replica’ya yönlendirmek:</p><p>java</p><pre>LettuceClientConfiguration clientConfig = LettuceClientConfiguration.builder()<br>        .commandTimeout(Duration.ofMillis(100))<br>        .readFrom(ReadFrom.REPLICA_PREFERRED)   // okuma varsa replica&#39;dan; master seçimi sürerken bile<br>        .build();</pre><p>Master seçimi sürerken replica’lar okumaya devam edebilir. Cache okumaları (zaten bayatlığa toleranslı) için mantıklı bir takas. Bedeli replication lag: yazdığınızı bir an sonra okuyamayabilirsiniz. Cache için genelde kabul edilebilir, ama bilerek seçin.</p><h3>Tatbikat: Cevabı Production’dan Önce Siz Öğrenin</h3><p>Bütün bu katmanların çalışıp çalışmadığının tek kanıtı vardır: <strong>denemek.</strong> İki ayrı tatbikat gerekir, çünkü iki ayrı arıza modu test ediyoruz:</p><p><strong>Tatbikat 1 — Down:</strong> staging’de Redis’i kapatın.</p><pre>docker stop redis</pre><p><strong>Tatbikat 2 — Slow:</strong> Redis’i öldürmeyin, <em>yavaşlatın</em>. Toxiproxy ile araya gecikme sokun:</p><pre>toxiproxy-cli toxic add redis-proxy --type latency --attribute latency=500</pre><p>İkinci tatbikatı neredeyse kimse yapmaz. Ve bu yazının bütün tezi, asıl katilin o senaryoda saklandığıydı.</p><p>Her iki tatbikatta izlenecekler:</p><ul><li>p99 latency ne yaptı? (hedef: sınırlı bir sıçrama, sonra plato, sonsuz tırmanış değil)</li><li>Thread havuzu doluluk? (hedef: tavana yapışmıyor)</li><li>DB QPS? (hedef: bulkhead sınırında plato, üstü yok)</li><li>Degrade oranı? (kaç istek fallback cevap aldı, bu metriğin <em>var olması</em> bile başlı başına kazanım)</li><li>Circuit breaker state geçişleri? (closed → open → half-open → closed döngüsü temiz mi)</li><li>Ve Redis geri geldiğinde: stampede yazısındaki soğuk cache deseni tetiklendi mi, warm-up/jitter işledi mi?</li></ul><p>Son madde iki yazıyı birbirine bağlar: Redis’in <em>dönüşü</em> de bir arıza modudur. Boş cache’e tam trafik, stampede yazısının üçüncü deseniydi. Oradaki warm-up + jitter, bu yazının kapanış halkasıdır.</p><h3>Kapanış: Üç Soru</h3><p>Bu yazıdan tek şey kalacaksa şu üç soru kalsın. Üçü de bugün, production’a dokunmadan cevaplanabilir:</p><ol><li><strong>Redis komut timeout’unuz kaç?</strong> Bilmiyorsanız, büyük ihtimalle 60 saniye. Ve ilk yavaşlama gününde bunu thread havuzunuzdan öğrenirsiniz.</li><li><strong>Staging’de Redis’i en son ne zaman kapattınız?</strong> Hiç kapatmadıysanız, ilk tatbikatı production sizin yerinize yapacak.</li><li><strong>Redis yavaşlarsa hangi alarm öter?</strong> “Down” alarmınız var, eminim. Peki slowCallRate ya da Redis komut latency&#39;si üstüne kurulmuş bir alarm?</li></ol><p>Down’a herkes plan yapar. Sistemler slow’dan ölür.</p><h3>Kaynaklar</h3><ul><li><a href="https://medium.com/@gungor.akbiyik/cache-stampede-redis-ayakta-veritaban%C4%B1-yerde-db112abc69b0">Cache Stampede: Redis Ayakta, Veritabanı Yerde</a> — bu yazının öncülü: cache çalışırken kopan fırtınalar</li><li><a href="https://redis.github.io/lettuce/advanced-usage/client-options/">Lettuce Reference — Client Options</a> — command timeout ve default değerler</li><li><a href="https://resilience4j.readme.io/docs/circuitbreaker">Resilience4j — CircuitBreaker</a> — slow call threshold’ları dahil konfigürasyon</li><li><a href="https://docs.spring.io/spring-framework/reference/core/resilience.html">Spring Framework 7 — Resilience Features</a> — @Retryable, @ConcurrencyLimit</li><li><a href="https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/">Redis Sentinel Documentation</a> — down-after-milliseconds, failover mekaniği</li><li><a href="https://redis.io/docs/latest/operate/oss_and_stack/management/scaling/">Redis Cluster Specification</a> — cluster-node-timeout</li><li><a href="https://github.com/ben-manes/caffeine">Caffeine</a> — L1 cache</li><li><a href="https://github.com/Shopify/toxiproxy">Toxiproxy</a> — latency injection ile kaos tatbikatı</li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=606ff189525c" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Cache Stampede: Redis Ayakta, Veritabanı Yerde]]></title>
            <link>https://medium.com/@gungor.akbiyik/cache-stampede-redis-ayakta-veritaban%C4%B1-yerde-db112abc69b0?source=rss-3597415c14fc------2</link>
            <guid isPermaLink="false">https://medium.com/p/db112abc69b0</guid>
            <dc:creator><![CDATA[Güngör Akbıyık]]></dc:creator>
            <pubDate>Sun, 12 Jul 2026 06:21:46 GMT</pubDate>
            <atom:updated>2026-07-12T06:21:46.942Z</atom:updated>
            <content:encoded><![CDATA[<p>Trafik zirvesindeki bir platform düşünün: saniyede binlerce okuma, önünde Redis. Cache paneli gayet iyi: hit rate %98&#39;in üzerinde, bellek rahat, latency mikrosaniyelerde.</p><p>Ama PostgreSQL paneli her beş dakikada bir aynı deseni çiziyor: CPU duvara vuruyor, connection pool kuyruğa giriyor, p99 tavan yapıyor. Sonra her şey normale dönüyor — bir sonraki beş dakikaya kadar.</p><p>Beş dakika. Tanıdık bir sayı, değil mi?</p><p>En popüler birkaç kaydın cache TTL’i tam olarak beş dakika. Cache var, çalışıyor, hit rate mükemmel — ve veritabanını düzenli aralıklarla yere seren şey cache’in ta kendisi.</p><p>Bunun adı <strong>cache stampede</strong> (önbellek izdihamı). Bu yazıda önce ne olduğunu koddan ve zaman çizelgesinden okuyacağız, sonra dört savunma katmanını Java + Spring koduyla tek tek kuracağız: TTL jitter, single-flight lock, probabilistic early expiration ve stale-while-revalidate.</p><h3>Masum Görünen Kod</h3><p>Şu servise bakın. Muhtemelen sizin kod tabanınızda da bir benzeri var:</p><pre>@Service<br>public class ProductService {<br><br>    private final ProductRepository repository;<br><br>    @Cacheable(cacheNames = &quot;products&quot;, key = &quot;#id&quot;)<br>    public ProductView getProduct(long id) {<br>        // pahalı iş: birkaç join, biraz hesap, ~150 ms<br>        return repository.loadProductView(id);<br>    }<br>}</pre><p>Konfigürasyon da klasik:</p><pre>@Bean<br>public RedisCacheManager cacheManager(RedisConnectionFactory factory) {<br>    RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()<br>            .entryTtl(Duration.ofMinutes(5));   // herkesin yazdığı satır<br><br>    return RedisCacheManager.builder(factory)<br>            .cacheDefaults(config)<br>            .build();<br>}</pre><p>Temiz görünüyor. Code review’dan yorum almadan geçer. Testleri yeşil.</p><p>Ama bu iki parça kodun içinde, yük altında patlayan üç ayrı bomba var. Üçünün de fitili aynı satırda: entryTtl(Duration.ofMinutes(5)).</p><h3>Stampede’in Anatomisi: Üç Ayrı Kaza</h3><p>“Cache stampede” tek bir hatanın adı değil — üç farklı yük deseninin ortak adı. Bu ayrımı yapmak önemli, çünkü birazdan göreceğiz: <strong>her çözüm bu üç desenden yalnızca birini ya da ikisini çözüyor.</strong> Hangi desende olduğunuzu bilmeden çözüm seçerseniz, yanlış ilacı içersiniz.</p><h3>Desen 1 — Dogpile: Tek popüler key, aynı anda bin istek</h3><p>product:42 platformun en çok bakılan kaydı olsun. Saniyede 500 istek alıyor. TTL&#39;i doldu ve expire oldu. Milisaniye milisaniye ne olur:</p><pre>14:00:00.000   product:42 expire oldu<br>14:00:00.002   İstek A → cache MISS → DB&#39;ye gitti<br>14:00:00.004   İstek B → cache MISS → DB&#39;ye gitti   (A henüz dönmedi)<br>14:00:00.007   İstek C → cache MISS → DB&#39;ye gitti   (A ve B hâlâ dönmedi)<br>      ...<br>14:00:00.180   A&#39;nın sorgusu bitti, cache doldu<br>14:00:00.181   Artık gelen istekler HIT alıyor</pre><p>Hesap arasında olan 180 milisaniyede gelen <strong>her</strong> istek cache’te hiçbir şey bulamadı ve DB’ye gitti. 500 istek/sn × 0.18 sn = <strong>90 eş zamanlı, birbirinin aynısı sorgu.</strong> Doksanı da aynı cevabı hesaplıyor; seksen dokuzu tamamen boşa.</p><p>Daha kötüsü: DB bu 90 sorgu yüzünden yavaşladıkça hesap süresi 180 ms’den 500 ms’ye, 500&#39;den 2 saniyeye uzar. Pencere büyüdükçe içine düşen istek sayısı da büyür. Connection pool dolar, cache ile ilgisi olmayan sorgular da kuyrukta bekler. Kartopu.</p><p>Cache’in koruması gereken veritabanı, tam da en çok korunmaya muhtaç anda çıplak kalıyor.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XGxeNS9iQwPPkKJYWzkK-A.png" /></figure><h3>Desen 2 — Toplu Expire: Aynı anda doğan key’ler aynı anda ölür</h3><p>Sabah 09:00&#39;da deploy ettiniz. Uygulama ayağa kalkarken warm-up job’ı 50.000 key’i cache’e doldurdu. Hepsinin TTL’i 1 saat.</p><p>Saat 10:00&#39;da ne olur?</p><p>50.000 key aynı dakika içinde expire olur. Bu sefer tek bir sıcak key değil, koca bir <strong>dalga</strong> veritabanını vurur. Sonra herkes yeniden cache’lenir — yine aynı TTL ile. 11:00&#39;de dalga tekrar gelir.</p><p>Girişteki “her beş dakikada bir” deseni tam olarak bu: aynı anda yazılan popüler kayıtlar, senkronize bir kalp atışı gibi birlikte ölüp birlikte diriliyor.</p><h3>Desen 3 — Soğuk Cache: Sıfırdan başlamak</h3><p>Redis yeniden başladı. Ya da failover oldu, ya da birisi yanlış ortamda FLUSHDB çalıştırdı (oluyor). Cache tamamen boş — ve production trafiği tam gaz devam ediyor.</p><p>Hit rate %98 olan bir sistemde bu, veritabanına giden yükün <strong>50 kat</strong> artması demek. Cache’e güvenerek boyutlandırdığınız DB, cache’siz trafiği kaldıramaz. Kaldıramadığı için yavaşlar; yavaşladığı için cache geç dolar; cache geç dolduğu için yük sürer. Sistem kendi kendini boğar.</p><h3>“TTL’i uzatalım” neden çözüm değil</h3><p>Bu tabloyu ilk gören herkesin refleksi aynıdır: TTL’i 5 dakikadan 1 saate çıkarmak.</p><p>Bu, hiçbir deseni çözmez. Dogpile penceresi yine açılır — sadece daha seyrek. Toplu expire dalgası yine gelir — sadece daha geç ve muhtemelen daha büyük (bir saatte daha çok key birikir). Üstüne bir de bayat veri süresini 12 katına çıkarmış olursunuz.</p><p>Seyrekleştirilmiş bir felaket, hâlâ bir felakettir. Şimdi gerçek savunmalara geçelim.</p><h3>Birinci Savunma: TTL Jitter — Expire Anlarını Yay</h3><p>Toplu expire’ın çözümü utanç verici derecede basit: key’lere aynı TTL’i vermeyin.</p><p>Sabit 5 dakika yerine 5 dakika ± %10 rastgelelik verin. 50.000 key artık aynı dakikada değil, bir dakikalık banda yayılarak ölür. Dalga, çizgiye dönüşür.</p><p>Spring Data Redis 3.2 ile bu, cache konfigürasyonuna doğrudan takılabiliyor — RedisCacheWriter.TtlFunction arayüzü tam bunun için var:</p><pre>public class JitteredTtl implements RedisCacheWriter.TtlFunction {<br><br>    private final Duration base;<br>    private final double jitterRatio;   // 0.10 → ±%10<br><br>    public JitteredTtl(Duration base, double jitterRatio) {<br>        this.base = base;<br>        this.jitterRatio = jitterRatio;<br>    }<br><br>    @Override<br>    public Duration getTimeToLive(Object key, Object value) {<br>        long baseMillis = base.toMillis();<br>        long band = (long) (baseMillis * jitterRatio);<br>        // 300s ± 30s → her key 270-330s arasında rastgele bir ömre doğar<br>        long jitter = ThreadLocalRandom.current().nextLong(-band, band + 1);<br>        return Duration.ofMillis(baseMillis + jitter);<br>    }<br>}</pre><p>Konfigürasyonda tek satır değişiyor:</p><pre>RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()<br>        .entryTtl(new JitteredTtl(Duration.ofMinutes(5), 0.10));</pre><p>Hepsi bu. Bir sınıf, bir satır değişiklik — ve deploy sonrası senkronize expire dalgası ortadan kalktı:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*0nyr_XZ4hC02gEpPCX3fbA.png" /></figure><p>@Cacheable kullanmıyorsanız, RedisTemplate ile manuel yazdığınız her yerde aynı ilke:</p><pre>void put(String key, String json) {<br>    long ttlSeconds = 300 + ThreadLocalRandom.current().nextLong(-30, 31);<br>    redis.opsForValue().set(key, json, Duration.ofSeconds(ttlSeconds));<br>}</pre><p><strong>Ne çözer:</strong> Desen 2&#39;yi (toplu expire) kökünden çözer. Maliyeti sıfıra yakın; bu yüzden <em>her</em> cache kurulumunda taban katman olarak durmalı.</p><p><strong>Ne çözmez:</strong> Dogpile’ı. product:42 hâlâ tek başına bir anda expire oluyor ve o milisaniyedeki 90 istek hâlâ hep birlikte DB&#39;ye gidiyor. Jitter dalgayı yayar; tek key&#39;in etrafındaki izdihamı dağıtamaz.</p><p>Onun için sıradaki katmanlar gerekiyor.</p><h3>İkinci Savunma: Single-Flight — Hesabı Tek Kişi Yapsın</h3><p>Dogpile’daki asıl saçmalık şu: 90 istek aynı değeri hesaplıyor. Doğal çözüm de kendini yazıyor — <strong>bir kişi hesaplasın, 89 kişi beklesin.</strong></p><p>Bu desene single-flight denir (Go dünyasındaki singleflight paketinden gelen isim). Java + Spring&#39;de üç seviyesi var.</p><h3>Seviye 1: @Cacheable(sync = true) — tek satırlık, tek JVM&#39;lik</h3><p>Spring’in cache abstraction’ında bu davranış hazır geliyor ve çoğu insan varlığından habersiz:</p><pre>@Cacheable(cacheNames = &quot;products&quot;, key = &quot;#id&quot;, sync = true)<br>public ProductView getProduct(long id) {<br>    return repository.loadProductView(id);<br>}</pre><p>sync = true ile aynı key için gelen eş zamanlı çağrılardan yalnızca biri metodu çalıştırır; diğerleri sonucu bekler. Dogpile&#39;ın 90 sorgusu 1&#39;e iner.</p><p>Ama iki incelik var:</p><p>Birincisi, bu kilit <strong>JVM içi</strong>dir. Spring, senkronizasyonu cache provider’a delege eder ve Redis söz konusu olduğunda bu, instance-lokal bir kilittir — Redis üzerinde dağıtık bir kilit <em>değildir</em>. 20 pod’unuz varsa, en kötü durumda 20 eş zamanlı hesap yaparsınız. Dikkat edin: bu genellikle <em>yeterlidir</em>. 90 sorgu → 20 sorgu hâlâ büyük kazanç, ve karmaşıklık maliyeti sıfır.</p><p>İkincisi, sync = true bazı kombinasyonları kabul etmez — örneğin unless ile birlikte kullanılamaz. Basit tutulmuş bilinçli bir kısıt.</p><p>Tek satırlık bu değişiklik, çoğu sistemde dogpile şikâyetini bitirir. Önce bunu deneyin.</p><h3>Seviye 2: Dağıtık kilit — SET NX ile kendi ellerinizle</h3><p>20 pod’un 20 sorgusu bile fazlaysa (hesap gerçekten pahalıysa: ağır aggregate, dış servis çağrısı), kilidin Redis’e taşınması gerekir. Çekirdeği tek bir atomik komut: SET key value NX PX.</p><pre>@Component<br>public class SingleFlightCache {<br><br>    private final StringRedisTemplate redis;<br>    private final ObjectMapper mapper;<br><br>    private static final String UNLOCK_LUA = &quot;&quot;&quot;<br>            if redis.call(&#39;get&#39;, KEYS[1]) == ARGV[1] then<br>                return redis.call(&#39;del&#39;, KEYS[1])<br>            else<br>                return 0<br>            end&quot;&quot;&quot;;<br><br>    public &lt;T&gt; T get(String key, Class&lt;T&gt; type,<br>                     Supplier&lt;T&gt; loader, Duration ttl) {<br>        String cached = redis.opsForValue().get(key);<br>        if (cached != null) {<br>            return deserialize(cached, type);<br>        }<br><br>        String lockKey = &quot;lock:&quot; + key;<br>        String token = UUID.randomUUID().toString();   // kilidin sahibi benim kanıtı<br><br>        Boolean acquired = redis.opsForValue()<br>                .setIfAbsent(lockKey, token, Duration.ofSeconds(10)); // SET NX PX<br><br>        if (Boolean.TRUE.equals(acquired)) {<br>            try {<br>                T fresh = loader.get();                 // pahalı hesabı yapan tek istek<br>                redis.opsForValue().set(key, serialize(fresh), ttl);<br>                return fresh;<br>            } finally {<br>                // kilidi sadece sahibi bırakabilir — token karşılaştırması Lua ile atomik<br>                redis.execute(new DefaultRedisScript&lt;&gt;(UNLOCK_LUA, Long.class),<br>                        List.of(lockKey), token);<br>            }<br>        }<br><br>        // Kilidi alamadık: biri zaten hesaplıyor. Kısa aralıklarla cache&#39;e tekrar bak.<br>        for (int i = 0; i &lt; 50; i++) {<br>            sleep(100);<br>            cached = redis.opsForValue().get(key);<br>            if (cached != null) {<br>                return deserialize(cached, type);<br>            }<br>        }<br>        // Hesaplayan öldü ya da çok yavaş — son çare: kendin hesapla<br>        return loader.get();<br>    }<br>}</pre><p>Bu kodun her satırı bir yara izidir, üçüne dikkat:</p><ul><li><strong>Token + Lua unlock.</strong> Kilidi DEL ile körlemesine silmek yanlış: 10 saniyelik kilit süreniz dolduysa ve kilit başka bir isteğe geçtiyse, sizin DEL&#39;iniz <em>onun</em> kilidini siler. GET + karşılaştır + DEL üçlüsünün tek atomik adımda olması şart — o yüzden Lua.</li><li><strong>Kilide de TTL.</strong> PX olmadan, hesap sırasında ölen bir pod kilidi sonsuza dek tutar ve o key bir daha asla yenilenmez.</li><li><strong>Bekleyenlerin kaderi bir üründür.</strong> Kilidi alamayan istek ne yapacak? Yukarıda polling ile bekliyor. Alternatifler: eski (stale) değeri dönmek — birazdan geleceğiz — ya da degrade bir cevap vermek. Bu bir mühendislik kararıdır ve kodda <em>açıkça</em> görünmelidir.</li></ul><h3>Seviye 3: Redisson — aynı şey, üretim cilası ile</h3><p>Bu mekaniği elle yazmak eğitici, ama üretimde çoğu ekip Redisson’a bırakır (redisson-spring-boot-starter):</p><pre>public ProductView getProduct(long id) {<br>    String cacheKey = &quot;product:&quot; + id;<br>    ProductView cached = readFromCache(cacheKey);<br>    if (cached != null) return cached;<br><br>    RLock lock = redisson.getLock(&quot;lock:&quot; + cacheKey);<br>    try {<br>        // en fazla 200 ms kilidi bekle, alırsan 10 sn&#39;de otomatik bırakılsın<br>        if (lock.tryLock(200, 10_000, TimeUnit.MILLISECONDS)) {<br>            try {<br>                cached = readFromCache(cacheKey);   // double-check: beklerken dolmuş olabilir<br>                if (cached != null) return cached;<br>                ProductView fresh = repository.loadProductView(id);<br>                writeToCache(cacheKey, fresh);<br>                return fresh;<br>            } finally {<br>                lock.unlock();<br>            }<br>        }<br>        // kilidi süresinde alamadık — burada bekleme/stale/degrade kararı verilir<br>        return repository.loadProductView(id);<br>    } catch (InterruptedException e) {<br>        Thread.currentThread().interrupt();<br>        throw new IllegalStateException(e);<br>    }<br>}</pre><p>Token yönetimi, kilit yenileme (watchdog), reentrancy — hepsi Redisson’ın içinde. Kilidi aldıktan sonraki double-check satırına dikkat: beklediğiniz sürede başkası cache&#39;i doldurmuş olabilir; kontrol etmeden hesaplarsanız single-flight&#39;ın anlamı kalmaz.</p><p><strong>Ne çözer:</strong> Dogpile’ı, reaktif olarak. Miss fırtınası koptuğunda hasarı 1 sorguya indirir.</p><p><strong>Bedeli:</strong> Karmaşıklık ve bekleme. Kilidi alamayan istekler ya bekler (latency), ya vazgeçer (hata/degrade). Ve dağıtık kilit, dağıtık sistemlerin bütün klasik dertlerini getirir: sahibi ölen kilit, süresi dolan kilit, ağ bölünmesi. Bu bedeli ödemeden önce bir sonraki katmana bakın — belki miss fırtınasını hiç koparmamak mümkündür.</p><h3>Üçüncü Savunma: Probabilistic Early Expiration — Zar Atan Cache</h3><p>Buraya kadar hep <em>tepki</em> verdik: key öldü, izdiham başladı, izdihamı yönettik. Şimdi soruyu değiştirelim:</p><p><strong>Key ölmeden önce yenilesek, izdiham hiç başlamasa?</strong></p><p>İlk akla gelen yol — arka planda cron’la yenilemek — sıcak key’lerin listesini bilmeyi gerektirir, ayrı bir altyapıdır, ve soğuyan key’leri sonsuza dek yenilemeye devam eder. Daha zarif bir yol var ve bir formüle sığıyor.</p><p>Fikir şu: her okuma, “acaba değeri şimdiden yenileyeyim mi?” diye bir zar atar. Expire uzaksa zar neredeyse hiç tutmaz. Expire yaklaştıkça tutma olasılığı üstel olarak artar. Sonuç: expire gelmeden <em>hemen önce</em>, okumalardan <strong>biri</strong> gönüllü olarak değeri yeniler — geri kalanı bu sırada cache’ten okumaya devam eder. Key hiçbir zaman gerçekten ölmez, izdiham penceresi hiçbir zaman açılmaz.</p><p>Buna <strong>probabilistic early expiration</strong> deniyor; formülün adı <strong>XFetch</strong> ve Vattani, Chierichetti &amp; Lowenstein’ın <em>Optimal Probabilistic Cache Stampede Prevention</em> (VLDB 2015) makalesinden geliyor:</p><pre>yenile,  eğer:  now − Δ · β · ln(rand()) ≥ expiry</pre><ul><li>Δ (delta): değeri son hesaplamanın kaç milisaniye sürdüğü</li><li>β (beta): agresiflik katsayısı — 1.0 makaledeki optimal; büyütürseniz daha erken yeniler</li><li>rand(): (0,1] arası uniform rastgele sayı — ln&#39;i negatif, yani sol taraf now&#39;ın <em>ilerisi</em></li></ul><p>Formülün güzelliği şurada: Δ içeride olduğu için, <strong>hesabı pahalı olan key daha erken yenilenir</strong> (çünkü onun izdihamı daha yıkıcı olur). Sık okunan key saniyede yüzlerce zar atar, biri mutlaka tutar; nadir okunan key belki hiç erken yenilenmez — ki buna gerek de yoktur, izdihamı olmaz.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*uul9-rmYrFa-im07tDxBUA.png" /></figure><p>Sisteme oturması için değerin yanında iki meta alan saklamamız gerekiyor: Δ ve mantıksal expire zamanı. Bunun için değeri meta alanlarıyla birlikte paketleyen küçük bir sarmalayıcı — bir &quot;zarf&quot; — yazalım. Generic bir record; cache&#39;e artık değerin kendisi değil, bu zarf yazılıp okunacak:</p><pre>public record CachedEntry&lt;T&gt;(<br>        T value,<br>        long deltaMillis,          // son hesap süresi<br>        long expiryEpochMillis     // mantıksal son kullanma tarihi<br>) {<br><br>    public boolean shouldRecomputeEarly(double beta) {<br>        // 1.0 - nextDouble() → (0,1] : log(0) = -Infinity koruması<br>        double r = 1.0 - ThreadLocalRandom.current().nextDouble();<br>        double gap = deltaMillis * beta * Math.log(r);   // her zaman &lt;= 0<br>        return System.currentTimeMillis() - gap &gt;= expiryEpochMillis;<br>    }<br>}</pre><p>Servis tarafı:</p><pre>@Service<br>public class ProductService {<br><br>    private static final Duration LOGICAL_TTL = Duration.ofMinutes(5);<br>    private static final Duration GRACE = Duration.ofMinutes(2);<br>    private static final double BETA = 1.0;<br><br>    public ProductView getProduct(long id) {<br>        CachedEntry&lt;ProductView&gt; entry = readEntry(&quot;product:&quot; + id);<br><br>        if (entry == null || entry.shouldRecomputeEarly(BETA)) {<br>            return recomputeAndStore(id);   // zarı kaybeden (!) şanslı istek maliyeti öder<br>        }<br>        return entry.value();<br>    }<br><br>    private ProductView recomputeAndStore(long id) {<br>        long start = System.nanoTime();<br>        ProductView fresh = repository.loadProductView(id);      // pahalı hesap<br>        long delta = (System.nanoTime() - start) / 1_000_000;<br><br>        CachedEntry&lt;ProductView&gt; entry = new CachedEntry&lt;&gt;(<br>                fresh, delta, System.currentTimeMillis() + LOGICAL_TTL.toMillis());<br><br>        // Fiziksel TTL, mantıksal olandan UZUN: erken yenileme bir şekilde kaçarsa<br>        // bile Redis&#39;te hâlâ dönebileceğimiz bir kopya kalsın<br>        redis.opsForValue().set(&quot;product:&quot; + id,<br>                serialize(entry), LOGICAL_TTL.plus(GRACE));<br>        return fresh;<br>    }<br>}</pre><p>İki tasarım detayı:</p><ul><li><strong>Mantıksal ve fiziksel expire ayrıldı.</strong> Redis’teki gerçek TTL (LOGICAL_TTL + GRACE) formülün kullandığı expiryEpochMillis&#39;ten uzun. Zar mekanizması normal şartlarda fiziksel expire&#39;a hiç ulaştırmaz; ulaşırsa da (trafik kesildi, kimse zar atmadı) sistem klasik cache miss&#39;e düşer — felaket değil, geri dönüş.</li><li><strong>Kusursuz değil, yeterince iyi.</strong> İki okuma aynı milisaniyede zarı “kazanıp” ikisi de yenileyebilir. Olasılık düşük ve sonuç zararsız (iki sorgu, doksan değil). Matematiksel kesinlik istiyorsanız recomputeAndStore&#39;u ikinci savunmanın tryLock&#39;ı ile sarın — iki katman birbirini tamamlar.</li></ul><p><strong>Ne çözer:</strong> Dogpile’ı, proaktif olarak — kimseyi bekletmeden, kilitsiz, koordinasyonsuz. Sıcak ve pahalı key’ler için bilinen en zarif çözüm.</p><p><strong>Bedeli:</strong> Zarf tipi yüzünden @Cacheable&#39;ın konforundan çıkıp cache erişimini kendiniz yazıyorsunuz; her okumada birkaç nanosaniyelik bir formül dönüyor. Karşılığında dağıtık kilidin bütün dertlerinden muaf kalıyorsunuz.</p><h3>Dördüncü Savunma: Stale-While-Revalidate — Önce Dön, Sonra Yenile</h3><p>Son katman, soruyu bir kez daha değiştiriyor: <strong>kullanıcı taze veriyi beklemek zorunda mı?</strong></p><p>Çoğu veri için cevap hayır. Ürün açıklaması, kategori ağacı, konfigürasyon, istatistik özeti — 30 saniye bayat olmaları kimsenin hayatını değiştirmez. O zaman şu pazarlık masaya gelir: expire olmuş değeri <strong>anında</strong> dön, tazesini <strong>arka planda</strong> hazırla.</p><p>HTTP dünyası bunu yıllardır yapıyor — Cache-Control: stale-while-revalidate (RFC 5861). Aynı deseni Redis üstünde iki katlı TTL ile kuruyoruz: <strong>soft TTL</strong> (mantıksal tazelik sınırı) ve <strong>hard TTL</strong> (Redis&#39;teki fiziksel ömür).</p><pre>public record SwrEntry&lt;T&gt;(T value, long softExpiryEpochMillis) {<br>    public boolean isStale() {<br>        return System.currentTimeMillis() &gt;= softExpiryEpochMillis;<br>    }<br>}</pre><pre>@Service<br>public class ProductService {<br><br>    private final ProductCacheRefresher refresher;<br><br>    public ProductView getProduct(long id) {<br>        SwrEntry&lt;ProductView&gt; entry = readEntry(&quot;product:&quot; + id);<br><br>        if (entry == null) {<br>            return refresher.recomputeAndStore(id);   // gerçek miss: beklemekten kaçış yok<br>        }<br>        if (entry.isStale()) {<br>            refresher.refreshAsync(id);               // arka plana at...<br>        }<br>        return entry.value();                         // ...ve eldekini ANINDA dön<br>    }<br>}</pre><pre>@Component<br>public class ProductCacheRefresher {<br><br>    private static final Duration SOFT_TTL = Duration.ofMinutes(5);   // tazelik sınırı<br>    private static final Duration HARD_TTL = Duration.ofMinutes(30);  // fiziksel ömür<br><br>    @Async(&quot;cacheRefreshExecutor&quot;)<br>    public void refreshAsync(long id) {<br>        // single-flight: aynı key&#39;i yalnızca bir pod yenilesin<br>        Boolean acquired = redis.opsForValue()<br>                .setIfAbsent(&quot;refresh:product:&quot; + id, &quot;1&quot;, Duration.ofSeconds(30));<br>        if (!Boolean.TRUE.equals(acquired)) {<br>            return;   // başka bir pod zaten yeniliyor — sessizce çekil<br>        }<br>        try {<br>            recomputeAndStore(id);<br>        } finally {<br>            redis.delete(&quot;refresh:product:&quot; + id);<br>        }<br>    }<br><br>    public ProductView recomputeAndStore(long id) {<br>        ProductView fresh = repository.loadProductView(id);<br>        SwrEntry&lt;ProductView&gt; entry = new SwrEntry&lt;&gt;(<br>                fresh, System.currentTimeMillis() + SOFT_TTL.toMillis());<br>        redis.opsForValue().set(&quot;product:&quot; + id, serialize(entry), HARD_TTL);<br>        return fresh;<br>    }<br>}</pre><p>@Async&#39;li metodun <strong>ayrı bir bean&#39;de</strong> olması tesadüf değil, zorunluluk: refreshAsync servisin kendi içinde olsaydı, this.refreshAsync(id) çağrısı Spring proxy&#39;sini atlar ve @Async sessizce devre dışı kalırdı — @Transactional self-invocation tuzağının birebir aynısı. Proxy ailesinin bütün annotation&#39;ları aynı kurala tabidir.</p><p>Akışı okuyalım: soft TTL dolduğunda değer “bayat” damgası yer ama Redis’te durmaya devam eder. Bayat değeri gören ilk okuma bir arka plan yenilemesi tetikler ve <em>beklemeden</em> eldekini döner. Yenileme bitene kadar herkes bayatı okur; bitince herkes tazeyi. Hard TTL’e (gerçek silinmeye) normal işleyişte hiç ulaşılmaz — o, “bu veri artık dönülemeyecek kadar eski” sınırıdır.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1m2jfz4TZRFwvTDz9bOViw.png" /></figure><p>refreshAsync içindeki SET NX satırı kritik: o olmadan, bayat pencerede gelen her istek ayrı bir arka plan yenilemesi tetikler ve dogpile&#39;ı ön kapıdan kovup arka kapıdan içeri almış olursunuz. Dördüncü savunmanın içinde ikinci savunmanın bir minyatürü çalışıyor — bu katmanlar gerçekten birbirinin üstüne biniyor.</p><p>İki uyarıyı masaya koyalım:</p><ul><li><strong>Bilinçli tutarsızlık.</strong> Kullanıcı, siz “bayat ama hızlı” dediğiniz için bayat veri görüyor. Ürün açıklamasında sorun değil; bakiye, stok adedi, fiyat gibi anlık-kritik veride bu deseni kullanmak üründen onay gerektirir. Bu teknik bir detay değil, bir ürün kararıdır.</li><li><strong>Executor’ı boğmayın.</strong> @Async havuzunuz sınırlı ve kuyruğu dolu olmalı (bounded queue + CallerRunsPolicy yerine discard tercih edilir — yenileme kaçarsa bir sonraki okuma tekrar tetikler). Sınırsız kuyruk, trafiği DB&#39;den alıp kendi executor&#39;ınıza taşımanın süslü bir yoludur.</li></ul><p>Bu arada bu desen size tanıdık geldiyse: Caffeine’in refreshAfterWrite&#39;ı, aynı fikrin in-memory cache&#39;teki hazır hali —</p><pre>LoadingCache&lt;Long, ProductView&gt; local = Caffeine.newBuilder()<br>        .refreshAfterWrite(Duration.ofMinutes(4))   // soft TTL<br>        .expireAfterWrite(Duration.ofMinutes(5))    // hard TTL<br>        .build(repository::loadProductView);        // arka plan yenileyici</pre><p>— yani JVM içi cache’te SWR’yi bedavaya alıyorsunuz. Redis’te elle kurduğumuz her şeyi bu iki satır lokalde yapıyor. (İki katmanlı cache — Caffeine önde, Redis arkada — ayrı bir yazının konusu.)</p><p><strong>Ne çözer:</strong> Dogpile’ı <em>ve</em> kullanıcı gecikmesini. Dört çözüm içinde son kullanıcının hayatını görünür biçimde iyileştiren tek katman bu: p99&#39;daki “cache yenileme dişleri” tamamen kaybolur.</p><p><strong>Bedeli:</strong> Bayatlık penceresi + zarf tipi + async altyapı. Ve tutarlılık kararının artık kodda değil, ürün masasında verilmesi gerektiği gerçeği.</p><h3>Soğuk Başlangıç: Isıtmadan Trafiğe Çıkmayın</h3><p>Üçüncü desen (boş cache + tam trafik) için yukarıdaki katmanlar yetmez — ölü key tek tek dirilirken tüm miss’ler yine DB’ye gider. Çözüm sıkıcı ama etkili: <strong>cache’i trafiğe açılmadan önce doldurun.</strong></p><pre>@Component<br>public class CacheWarmer {<br><br>    @EventListener(ApplicationReadyEvent.class)<br>    public void warmUp() {<br>        // En sıcak N key — dünkü erişim istatistiğinden, analitikten, ya da<br>        // en kaba haliyle &quot;en popüler 1000 ürün&quot; sorgusundan<br>        List&lt;Long&gt; hotIds = hotKeyRegistry.topProductIds(1000);<br><br>        for (Long id : hotIds) {<br>            productService.getProduct(id);   // cache&#39;i normal yoldan doldurur<br>        }<br>    }<br>}</pre><p>Üç pratik not:</p><ul><li>Warm-up <strong>jitter’lı TTL ile yazmalı</strong> (birinci savunma zaten cache konfigürasyonundaysa bedavaya gelir) — yoksa ısıttığınız 1000 key bir saat sonra hep birlikte ölür ve Desen 2&#39;yi kendi elinizle yaratırsınız. Girişteki “her beş dakikada bir” senaryosunun kökü tam olarak budur.</li><li>Readiness probe’u warm-up bitmeden yeşile döndürmeyin (ApplicationReadyEvent + probe sıralamasına dikkat) — pod, cache&#39;i boşken trafik almasın.</li><li>Redis’in kendisi giderse warm-up sizi kurtarmaz; o senaryonun cevabı circuit breaker + degrade cevaplar + DB’nin “cache’siz kısa süre hayatta kalacak kadar” boyutlandırılması. Cache bir hızlandırıcıdır; tek dayanak haline geldiyse mimari başka bir yazının konusu olan bir sorun biriktiriyor demektir.</li></ul><h3>Hangi Desen, Hangi Savunma?</h3><p>Baştaki tezi kapatalım: cache stampede tek hata değil, üç desen — ve her savunma belli desenlere karşılık geliyor:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Akn5-j0-YSbw4i1fTg8blA.png" /></figure><p>Gerçek sistemlerde bunlar seçenek değil, <strong>katman</strong>dır. Olgun bir kurulumun tipik resmi şudur: jitter tabanda, her key’de; en sıcak ve en pahalı bir avuç key’de erken yenileme ya da stale-while-revalidate; soğuk başlangıç için warm-up. Tek bir gümüş kurşun yok — dört küçük, sıkıcı, birbirini tamamlayan karar var.</p><h3>Sabit TTL Bir Karar Değil, Varsayılandır</h3><p>entryTtl(Duration.ofMinutes(5)) yazan satır masumdur — ta ki trafiğiniz onu masum olmaktan çıkarana kadar.</p><p>Bugün production’ınızda şu üç soruya bakmaya değer:</p><ol><li>En popüler key’iniz expire olduğunda kaç eş zamanlı istek DB’ye iniyor? (APM’de cache-miss anındaki DB sorgu sayısına bakın — dogpile oradadır.)</li><li>Key’leriniz TTL’e aynı anda mı doğuyor? (Deploy/warm-up sonrası DB grafiğinde periyodik dişler varsa cevap evet.)</li><li>Redis boşken sisteminiz ayakta kalır mı? (Cevabı bilmiyorsanız, staging’de deneyin — production kendisi denemeden önce.)</li></ol><p>Cevaplar rahatsız ediciyse, sıralama bellidir: önce jitter (bedava), sonra sync = true (tek satır), sonra ihtiyaca göre XFetch ya da stale-while-revalidate. Cache&#39;iniz en çok, tam da ona en çok ihtiyaç duyduğunuz anda test edilir — sınavın tarihini expire anları belirler, hazırlığın tarihini siz.</p><h3>Kaynaklar</h3><ul><li>Vattani, Chierichetti &amp; Lowenstein — <a href="https://cseweb.ucsd.edu/~avattani/papers/cache_stampede.pdf">Optimal Probabilistic Cache Stampede Prevention</a> (VLDB 2015) — XFetch formülünün kaynağı</li><li><a href="https://www.rfc-editor.org/rfc/rfc5861">RFC 5861 — HTTP Cache-Control Extensions for Stale Content</a> — stale-while-revalidate’in HTTP’deki tanımı</li><li><a href="https://docs.spring.io/spring-data/redis/reference/redis/redis-cache.html">Spring Data Redis — Cache Abstraction &amp; TtlFunction</a> (TtlFunction, 3.2.0+)</li><li><a href="https://redisson.pro/docs/data-and-services/locks-and-synchronizers/">Redisson — Distributed Locks</a></li><li><a href="https://github.com/ben-manes/caffeine/wiki/Refresh">Caffeine — refreshAfterWrite</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=db112abc69b0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[EXPLAIN ANALYZE]]></title>
            <link>https://medium.com/@gungor.akbiyik/explain-analyze-414f342fe068?source=rss-3597415c14fc------2</link>
            <guid isPermaLink="false">https://medium.com/p/414f342fe068</guid>
            <dc:creator><![CDATA[Güngör Akbıyık]]></dc:creator>
            <pubDate>Wed, 08 Jul 2026 09:12:38 GMT</pubDate>
            <atom:updated>2026-07-08T09:12:38.616Z</atom:updated>
            <content:encoded><![CDATA[<h3>EXPLAIN ANALYZE Bir Hız Göstergesi Değil, Muhasebe Defteridir</h3><p>Production’da bir rapor sorgusu var. Dün 20 milisaniyeydi. Bugün 150.</p><p>Sorgu değişmedi. Index’ler yerinde. Deploy yok. Ama sorgu yavaş — ve ekipte birileri çoktan “index mi eksik acaba” demeye başladı.</p><p>Bu refleksi kökünden sorgulayacağız. Elimde Docker’da çalışan gerçek bir PostgreSQL 18 var: 1 milyon satırlık orders, 100 bin satırlık customers. Buradaki her çıktı o makineden alındı — hiçbiri kurgu değil. Kurulumu da aşağıda paylaşıyorum; isterseniz her deneyi kendi makinenizde birebir tekrarlayabilirsiniz. (Milisaniye değerleri koşudan koşuya doğal olarak oynar; kalıcı olan page sayıları ve plan şekilleridir.)</p><h3>Oyun Alanının Kurulumu</h3><p>Gerçekçi bir senaryo istiyorum: bir e-ticaret sisteminin customers ve orders tabloları. İki bilinçli tercih yaptım:</p><p><strong>Birincisi, primary key dışında hiç index yok.</strong> Gerçek hayatta tablolar böyle doğar — kimse ilk gün “ileride bu kolona göre sorgulayacağız” diye index koymaz. Foreign key kolonu customer_id&#39;de bile index yok; bu, production&#39;da en sık görülen eksiklerden biridir ve yazının ilk yarısının ana malzemesi olacak.</p><p><strong>İkincisi, </strong><strong>status dağılımı bilerek çarpık:</strong> siparişlerin %90&#39;ı DELIVERED, sadece %2&#39;si PENDING. Bu çarpıklık &quot;index koydum ama kullanmıyor&quot; dersinin temelini oluşturacak.</p><p>Container:</p><pre>docker run -d --name pg-playground -e POSTGRES_PASSWORD=playground -p 5433:5432 postgres:18</pre><p>Şema ve veri:</p><pre>CREATE TABLE customers (<br>  id         bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,<br>  name       text NOT NULL,<br>  email      text NOT NULL,<br>  country    text NOT NULL,<br>  created_at timestamptz NOT NULL<br>);<br><br>CREATE TABLE orders (<br>  id           bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,<br>  customer_id  bigint NOT NULL REFERENCES customers(id),<br>  status       text NOT NULL,<br>  total_amount numeric(12,2) NOT NULL,<br>  created_at   timestamptz NOT NULL<br>);<br><br>-- 100.000 müşteri<br>INSERT INTO customers (name, email, country, created_at)<br>SELECT &#39;Customer &#39; || i,<br>       &#39;user&#39; || i || &#39;@example.com&#39;,<br>       (ARRAY[&#39;TR&#39;,&#39;DE&#39;,&#39;NL&#39;,&#39;US&#39;,&#39;GB&#39;])[1 + floor(random()*5)::int],<br>       now() - (random() * interval &#39;730 days&#39;)<br>FROM generate_series(1, 100000) i;<br><br>-- 1.000.000 sipariş — status dağılımı bilerek çarpık<br>INSERT INTO orders (customer_id, status, total_amount, created_at)<br>SELECT 1 + floor(random()*100000)::int,<br>       CASE WHEN r &lt; 0.90 THEN &#39;DELIVERED&#39;<br>            WHEN r &lt; 0.95 THEN &#39;SHIPPED&#39;<br>            WHEN r &lt; 0.98 THEN &#39;CANCELLED&#39;<br>            ELSE &#39;PENDING&#39; END,<br>       round((random()*500 + 5)::numeric, 2),<br>       now() - (random() * interval &#39;730 days&#39;)<br>FROM (SELECT random() AS r FROM generate_series(1, 1000000)) t;<br><br>ANALYZE customers;<br>ANALYZE orders;</pre><p>Dağılımın kontrolü:</p><pre>status   | count  | pct<br>-----------+--------+------<br> DELIVERED | 899764 | 90.0<br> SHIPPED   |  50210 |  5.0<br> CANCELLED |  29896 |  3.0<br> PENDING   |  20130 |  2.0</pre><blockquote><strong><em>Not — deneyleri kendi makinenizde baştan oynatacaksanız:</em></strong><em> Adım 2&#39;de iki index ekleyeceğiz. Adım 1&#39;i sonradan tek başına tekrar etmek isterseniz önce onları düşürün, Adım 2&#39;ye gelince yeniden kurarsınız:</em></blockquote><blockquote><strong><em>DROP</em></strong><em> </em><strong><em>INDEX</em></strong><em> </em><strong><em>IF</em></strong><em> </em><strong><em>EXISTS</em></strong><em> idx_orders_customer_id; <br></em><strong><em>DROP</em></strong><em> </em><strong><em>INDEX</em></strong><em> </em><strong><em>IF</em></strong><em> </em><strong><em>EXISTS</em></strong><em> idx_orders_status;</em></blockquote><h3>Zemin: Heap, Page, TID, Index</h3><p>Konuya girmeden dört kavramı masaya koyalım — çünkü bundan sonraki her çıktıyı bu dille okuyacağız.</p><p><strong>Heap</strong>, tablonun diskteki veri alanıdır. Satırlar oraya sırasız yığılır: eklenme sırasına, ya da VACUUM’un boşalttığı yerlere göre. Adı da buradan gelir — düzenli bir yapı değil, yığındır. Her tablonun bir heap’i vardır.</p><p><strong>Page</strong>, heap’in (ve index’in) 8 kB’lık dilimidir ve PostgreSQL’in okuma/yazma <strong>birimidir</strong>. Tek bir satır bile isteseniz, o satırın bulunduğu page’in tamamı okunur. cost, Buffers, Heap Blocks — yazı boyunca göreceğiniz bütün muhasebe satırları page sayar. Bu yazının en sık tekrar edeceği cümlenin sebebi de bu: performans satır meselesi değil, page meselesidir.</p><p><strong>TID</strong> (tuple identifier), bir satırın fiziksel adresidir: (page numarası, page içindeki slot). Index&#39;in heap&#39;e uzattığı el budur — index size satırı değil, satırın TID&#39;ini verir.</p><p><strong>B-tree index</strong>, heap’ten ayrı, <strong>sıralı</strong> bir yapıdır: tepede bir root page, altında dallanan internal page’ler, en altta leaf page’ler. Leaf’te sıralı değerler ve her değerin yanında TID durur. Bir index araması root’tan leaf’e iner (tipik olarak 3–4 page), TID’i alır, heap’teki page’e gider. Index de page’lerden oluşur — “index okumak” da page okumaktır ve aynı muhasebeye yazılır.</p><h3>Adım 1 — EXPLAIN ile EXPLAIN ANALYZE Arasındaki Fark</h3><p>İlk soru şu: 42 numaralı müşterinin siparişlerini istiyorum. customer_id kolonunda index yok. PostgreSQL bu işi nasıl yapmayı planlıyor?</p><pre>EXPLAIN SELECT * FROM orders WHERE customer_id = 42;</pre><pre>QUERY PLAN<br>--------------------------------------------------------------------------<br> Gather  (cost=1000.00..15467.43 rows=11 width=39)<br>   Workers Planned: 2<br>   -&gt;  Parallel Seq Scan on orders  (cost=0.00..14466.33 rows=5 width=39)<br>         Filter: (customer_id = 42)<br>(4 rows)</pre><p>Burada kritik bir şey var: <strong>bu sorgu çalışmadı.</strong> EXPLAIN tek başına sadece planner&#39;ın niyetini gösterir — &quot;ben olsam şöyle yapardım&quot; der, elini veriye sürmez. Çıktıda gerçek süre, gerçek satır sayısı yok; her şey tahmin.</p><p>Sorguyu gerçekten çalıştırıp tahminlerin yanına gerçeği koymak için ANALYZE eklenir:</p><pre>EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_id = 42;</pre><pre>QUERY PLAN<br>-------------------------------------------------------------------------------------------------------------------------<br> Gather  (cost=1000.00..15467.43 rows=11 width=39) (actual time=1.158..18.210 rows=4.00 loops=1)<br>   Workers Planned: 2<br>   Workers Launched: 2<br>   Buffers: shared hit=9258<br>   -&gt;  Parallel Seq Scan on orders  (cost=0.00..14466.33 rows=5 width=39) (actual time=7.549..14.765 rows=1.33 loops=3)<br>         Filter: (customer_id = 42)<br>         Rows Removed by Filter: 333332<br>         Buffers: shared hit=9258<br> Planning Time: 0.058 ms<br> Execution Time: 18.223 ms<br>(10 rows)</pre><p>“Gerçekten çalıştırır” ifadesinin tehlikeli bir sonucu var. EXPLAIN ANALYZE UPDATE ... yazarsanız UPDATE <strong>gerçekten olur</strong> — satırlar değişir. Production&#39;da bir DML&#39;i analiz etmeniz gerekiyorsa refleks şu olmalı:</p><pre>BEGIN;<br>  EXPLAIN ANALYZE UPDATE orders SET status = &#39;CANCELLED&#39; WHERE id = 42;<br>ROLLBACK;</pre><p>Planı görürsünüz, veri değişmeden geri alınır.</p><h3>Çıktıyı satır satır okumak</h3><p>En üst satırı parçalayalım:</p><pre>Gather  (cost=1000.00..15467.43 rows=11 width=39) (actual time=1.158..18.210 rows=4.00 loops=1)</pre><p><strong>cost=1000.00..15467.43</strong> — iki sayı var: ilki <em>startup cost</em> (ilk satırı üretebilmek için gereken maliyet), ikincisi <em>total cost</em>. Buradaki 1000, Gather node&#39;unun paralel worker&#39;ları ayağa kaldırma bedeli. Birim milisaniye <strong>değil</strong> — soyut bir ölçü. Referans noktası şu: diskten sıralı okunan bir page = 1.0. Yani cost&#39;lar ancak birbirleriyle kıyaslanır; &quot;15467 cost = 15 saniye&quot; gibi bir çeviri yoktur. Planner alternatif planların cost&#39;unu hesaplar ve en düşüğünü seçer — bu kadar.</p><p><strong>rows=11</strong> — planner&#39;ın tahmini: &quot;bu node&#39;dan 11 satır çıkar.&quot; <strong>actual ... rows=4.00</strong> — gerçekte 4 çıktı. Tahmin ile gerçek aynı mertebede; bu, istatistiklerin sağlıklı olduğunu gösterir. Bu ikili, tüm EXPLAIN ANALYZE okumalarının <strong>ana sağlık göstergesidir</strong>: fark 10 katı, hele 100 katı aştığında asıl problemi bulmuşsunuz demektir — planner yanlış bilgiyle plan yapıyor. (Bunun nasıl bozulduğunu ve nasıl düzeltildiğini Adım 4&#39;te ayrıca işleyeceğiz.)</p><p><strong>width=39</strong> — bu node&#39;dan çıkan ortalama satır genişliği, byte cinsinden. SELECT * çektiğimiz için satırın tamamı taşınıyor.</p><p><strong>actual time=1.158..18.210</strong> — gerçek süre, milisaniye: ilk satır 1.158&#39;de geldi, son satır 18.210&#39;da. Toplam yürütme ~18 ms.</p><p><strong>loops=1</strong> — bu node bir kez çalıştı. Asıl önemi bir alt satırda ortaya çıkıyor.</p><p>İç node’a inelim:</p><pre>-&gt;  Parallel Seq Scan on orders  (cost=0.00..14466.33 rows=5 width=39) (actual time=7.549..14.765 rows=1.33 loops=3)<br>      Filter: (customer_id = 42)<br>      Rows Removed by Filter: 333332</pre><p><strong>loops=3</strong> — tablo üç paralel akış tarafından tarandı: leader process + 2 worker. Ve burada EXPLAIN ANALYZE&#39;ın en çok insan yanıltan kuralı devreye giriyor: <strong>actual içindeki değerler loop başına ortalamadır.</strong> rows=1.33, &quot;her akış ortalama 1.33 satır buldu&quot; demek; gerçek toplam 1.33 × 3 ≈ 4. PostgreSQL 18&#39;in satır sayısını ondalıklı göstermesinin sebebi de bu ortalama. Aynı kural süre için de geçerli. Bu kuralı aklınızda tutun — ileride loops=50000 gibi bir değer gördüğünüzde, o node&#39;un elli bin kez döndüğünü ve yanındaki zamanın <em>tek dönüşün</em> süresi olduğunu bileceksiniz. N+1 problemlerinin plan çıktısındaki yüzü tam olarak budur.</p><p><strong>Rows Removed by Filter: 333332</strong> — yazının ilk kırmızı bayrağı. Ve üstüne basa basa söyleyeyim: <strong>bu sayı da loop başına ortalamadır.</strong> Her loop&#39;ta ~333.332 satır filter tarafından elendi; toplam elenen 333.332 × 3 = 999.996 satır, artı eşleşen 4 satır = <strong>tam 1.000.000</strong>. Yani üç akış toplamda tablonun tamamını okudu ve bunun sadece 4 tanesi işe yaradı. Aritmetiğin böyle kuruşu kuruşuna oturması tesadüf değil — ortalamanın kanıtı çıktının kendi içinde. Bu satırı production&#39;da bir planda gördüğünüzde bakılacak yer bellidir: filtredeki kolonda kullanılabilir bir index var mı? Yoksa bu kadar israf normaldir; varsa ama kullanılmıyorsa, sebep ya sorgunun yazımındadır ya da planner haklıdır — ikisini de Adım 2&#39;de göreceğiz.</p><p><strong>Buffers: shared hit=9258</strong> — sorgu 9.258 page&#39;e dokundu. Bir page 8 kB olduğuna göre ~72 MB veri elden geçti. hit bu page&#39;lerin cache&#39;te (shared buffers) bulunduğunu söylüyor; diskten okunsalardı read olarak görünürdü. Bu ayrımın teşhisteki yeri Adım 5&#39;in konusu. Küçük bir sürüm notu: PostgreSQL 18&#39;den itibaren BUFFERS çıktısı EXPLAIN ANALYZE&#39;da varsayılan; 17 ve öncesinde EXPLAIN (ANALYZE, BUFFERS) diye açıkça istemek gerekiyor.</p><p>Son iki satır: <strong>Planning Time</strong> planın kurulma süresi, <strong>Execution Time</strong> yürütmenin tamamı. Planlama 0.058 ms — önemsiz. Ama karmaşık sorgularda (çok join, çok index adayı) planlamanın kendisi de maliyet olabilir; ikisini ayrı görmek bu yüzden değerli.</p><h3>Kıyas: index’in olduğu dünya</h3><p>Aynı tablo, bu kez primary key ile arama:</p><pre>EXPLAIN ANALYZE SELECT * FROM orders WHERE id = 42;</pre><pre>QUERY PLAN<br>------------------------------------------------------------------------------------------------------------------------<br> Index Scan using orders_pkey on orders  (cost=0.42..8.44 rows=1 width=39) (actual time=0.017..0.018 rows=1.00 loops=1)<br>   Index Cond: (id = 42)<br>   Index Searches: 1<br>   Buffers: shared hit=7<br> Planning:<br>   Buffers: shared hit=4<br> Planning Time: 0.127 ms<br> Execution Time: 0.028 ms<br>(8 rows)</pre><p>İki sorguyu yan yana koyunca hikaye kendini anlatıyor:</p><p>customer_id = 42 (index yok)id = 42 (PK index)PlanParallel Seq ScanIndex ScanOkunan page9.258 (~72 MB)<strong>7</strong> (~56 kB)Süre18.22 ms<strong>0.028 ms</strong></p><p>Index’in yaptığı şey mistik değil: <strong>9.258 page yerine 7 page okumak.</strong> B-tree’nin root’undan leaf’ine in (3–4 page), satırın TID’ini al, heap’ten o page’i çek. EXPLAIN ANALYZE’ın işi de bu sayıları önünüze koymak — nereye baktığınızı bilirseniz.</p><h3>Adım 2 — Scan Tipleri: Planner Veriye Dört Farklı Yoldan Gider</h3><p>PostgreSQL’in bir tabloya erişmek için dört temel yolu var. Dördü de bu adımda gerçek çıktılarla karşımıza çıkacak:</p><p>Scan tipiNe yapar<strong>Seq Scan</strong>Heap’i baştan sona okur<strong>Index Scan</strong>Index’te bulur, her eşleşme için heap’e zıplar<strong>Index Only Scan</strong>Cevabı yalnızca index’ten verir, heap’e hiç gitmez<strong>Bitmap Index + Heap Scan</strong>Index’ten tüm eşleşen adresleri toplar, page sırasına dizer, heap’i sıralı gezer</p><h3>Index’i canlı ekliyoruz</h3><p>Adım 1&#39;in sonunda customer_id = 42 sorgusu 9.258 page okuyup ~18 ms sürüyordu. Index ekleyip aynı sorguyu tekrar çalıştıralım:</p><pre>CREATE INDEX idx_orders_customer_id ON orders(customer_id);<br>EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_id = 42;</pre><pre>QUERY PLAN<br>-----------------------------------------------------------------------------------------------------------------------------------<br> Bitmap Heap Scan on orders  (cost=4.51..47.51 rows=11 width=39) (actual time=0.059..0.066 rows=4.00 loops=1)<br>   Recheck Cond: (customer_id = 42)<br>   Heap Blocks: exact=4<br>   Buffers: shared hit=7 read=3<br>   -&gt;  Bitmap Index Scan on idx_orders_customer_id  (cost=0.00..4.51 rows=11 width=0) (actual time=0.050..0.050 rows=4.00 loops=1)<br>         Index Cond: (customer_id = 42)<br>         Index Searches: 1<br>         Buffers: shared hit=3 read=3<br> Planning:<br>   Buffers: shared hit=54 read=1<br> Planning Time: 0.326 ms<br> Execution Time: 0.100 ms<br>(12 rows)</pre><p>18 ms → <strong>0.1 ms</strong>; 9.258 page → <strong>10 page</strong> (hit=7 read=3). Ama dikkat: planner düz Index Scan değil, <strong>Bitmap Heap Scan</strong> seçti. Neden?</p><p>Önce şunu netleştirelim: düz Index Scan de sadece gereken page’leri okur — bitmap’in farkı <strong>hangi</strong> page’lerin okunduğunda değil, <strong>nasıl</strong> okunduğunda. Düz Index Scan index’in sırasıyla ilerler ve her eşleşme için heap’e ayrı ayrı zıplar: 11 satır 11 farklı page’deyse 11 rastgele sıçrama; iki eşleşme aynı page’deyse o page <strong>iki kez</strong> ziyaret edilebilir. Bitmap ise iki fazlı çalışır: önce <strong>Bitmap Index Scan</strong> index’i tarayıp eşleşen tüm TID’leri bir bitmap’te toplar; sonra <strong>Bitmap Heap Scan</strong> bu adresleri <em>fiziksel page sırasına dizip</em> heap’i düzenli gezer. Kazanç iki bacaklıdır: <strong>(a)</strong> her gereken page, üstünde kaç eşleşme olursa olsun, tam bir kez okunur; <strong>(b)</strong> rastgele sıçramalar yerine fiziksel sıraya yakın, diskin sevdiği bir erişim deseni oluşur. Benzetmek gerekirse: reyonlara aklınıza estikçe koşturmak yerine, markete girmeden alışveriş listesini reyon sırasına göre yazmak.</p><p>Çıktıdaki Heap Blocks: exact=4 bunu doğruluyor — 4 satır için 4 page ziyaret edildi, her biri bir kez.</p><p>Recheck Cond satırına gelince: bu satır her Bitmap Heap Scan planında yazılır, ama bu koşulun her satırda yeniden test edildiği anlamına gelmez. Bitmap <strong>exact</strong> olduğu sürece (her eşleşmenin tam TID&#39;i belliyken) recheck hiç çalışmaz; satır sadece &quot;gerekirse bu koşulu satır üzerinde yeniden kontrol ederim&quot; beyanıdır. Fiilen çalıştığı an, bitmap&#39;in work_mem&#39;e sığmayıp page granülaritesine düştüğü andır: artık &quot;bu page&#39;de eşleşme var&quot;dan fazlası bilinmediği için, o page&#39;lerden gelen her satır koşula karşı yeniden test edilir. Bunu çıktıda Heap Blocks: ... lossy=... ve Rows Removed by Index Recheck satırlarından tanırsınız — work_mem konusuna geldiğimizde bilerek tetikleyeceğiz.</p><h3>Heap’e hiç gitmeden: Index Only Scan</h3><p>Fikir şu: sorgunun istediği her kolon zaten index’in içindeyse (leaf’lerde yazılıysa), heap’ten okunacak hiçbir şey kalmaz — cevap doğrudan index’ten verilir; heap ziyareti yalnızca satırın görünürlüğünden emin olunamadığında gerekir (Heap Fetches).</p><p>Aynı filtreyle ama SELECT * yerine yalnızca index&#39;in içindeki kolonu isteyelim:</p><pre>EXPLAIN ANALYZE SELECT customer_id FROM orders WHERE customer_id = 42;</pre><pre>QUERY PLAN<br>----------------------------------------------------------------------------------------------------------------------------------------<br> Index Only Scan using idx_orders_customer_id on orders  (cost=0.42..4.62 rows=11 width=8) (actual time=0.021..0.022 rows=4.00 loops=1)<br>   Index Cond: (customer_id = 42)<br>   Heap Fetches: 0<br>   Index Searches: 1<br>   Buffers: shared hit=7<br> Planning:<br>   Buffers: shared hit=33<br> Planning Time: 0.141 ms<br> Execution Time: 0.043 ms<br>(9 rows)</pre><p>İstediğim her şey (sadece customer_id) zaten index&#39;in leaf&#39;inde yazılı — heap&#39;e gitmeye gerek kalmadı. 10 page 7&#39;ye, 0.1 ms 0.043 ms&#39;ye indi. width=39&#39;un width=8&#39;e düşmesi de aynı hikayeyi anlatıyor: satırın tamamı değil, 8 byte&#39;lık bir bigint taşınıyor.</p><p>Buradaki nöbetçi <strong>Heap Fetches</strong> satırıdır. &quot;Index-only&quot; sözü ancak <em>visibility map</em> güncelse tutulur: PostgreSQL, MVCC gereği bir satırın tüm transaction&#39;lara görünür olduğundan emin olamazsa, emin olmak için yine heap&#39;e gider. Heap Fetches: 0 temiz durumu gösteriyor. Production&#39;da bu sayıyı binlerle görüyorsanız, tablo yoğun UPDATE/DELETE trafiği yemiş ve VACUUM geride kalmış demektir — ilk bakılacak yer pg_stat_user_tables&#39;da son autovacuum zamanı, çözüm de vakumun kendisidir. Index Only Scan bekleyip Heap Fetches yüksek gören biri, sorunun sorguda değil tablonun bakımında olduğunu bilmeli.</p><p>Bir de şunu not edin: burada Index Only Scan’i biraz şansa yakaladık — sorgunun istediği kolon tesadüfen index’in kendisiydi. Bunu bilinçli bir tasarıma çevirmenin yolu var: aranmayan kolonu INCLUDE ile index&#39;in leaf&#39;ine iliştirmek (covering index). Vaka 5&#39;te tam bunu yapacağız.</p><h3>Row selectivity ile page selectivity aynı şey değil</h3><p>Şimdi çarpık status dağılımını sahneye alalım. Önce index, sonra %2&#39;lik dilim olan PENDING:</p><pre>CREATE INDEX idx_orders_status ON orders(status);<br>EXPLAIN ANALYZE SELECT * FROM orders WHERE status = &#39;PENDING&#39;;</pre><pre>QUERY PLAN<br>---------------------------------------------------------------------------------------------------------------------------------------<br> Bitmap Heap Scan on orders  (cost=226.91..9734.07 rows=19933 width=39) (actual time=2.365..9.841 rows=20130.00 loops=1)<br>   Recheck Cond: (status = &#39;PENDING&#39;::text)<br>   Heap Blocks: exact=8220<br>   Buffers: shared hit=8220 read=20<br>   -&gt;  Bitmap Index Scan on idx_orders_status  (cost=0.00..221.92 rows=19933 width=0) (actual time=1.182..1.182 rows=20130.00 loops=1)<br>         Index Cond: (status = &#39;PENDING&#39;::text)<br>         Index Searches: 1<br>         Buffers: shared read=20<br> Planning:<br>   Buffers: shared hit=27 read=1<br> Planning Time: 0.210 ms<br> Execution Time: 10.623 ms<br>(12 rows)</pre><p>Ders kitabı bakışıyla %2 son derece seçici bir filtredir ve index’ten mucize beklersiniz. Gerçeğe bakın: 20.130 satır bulundu, ama Heap Blocks: exact=8220 — tablonun 9.258 page&#39;inden <strong>8.220&#39;sine</strong> dokunuldu. Page&#39;lerin <strong>%89&#39;u</strong>. Neden? Siparişler tabloya <em>zaman sırasıyla</em> yazıldı, status&#39;a göre değil. PENDING satırlar heap&#39;in her yerine serpilmiş durumda; satır bazında %2, page bazında %89.</p><p>Buradan yazının en önemli mental modellerinden biri çıkıyor: <strong>planner satır saymaz, page sayar</strong> — maliyet I/O’dur ve I/O’nun birimi page’dir. Bir kolon satır bazında ne kadar seçici olursa olsun, eşleşen satırlar fiziksel olarak dağınıksa index size beklediğiniz kazancı vermez. Satırların fiziksel dizilişi ile mantıksal sıralanışı arasındaki ilişkiye <em>correlation</em> denir ve planner bunu istatistiklerde tutar — Adım 4&#39;te bu değeri okuyacağız.</p><h3>Index vardı, planner kullanmadı — ve haklıydı</h3><p>Aynı index, bu kez %90&#39;lık dilim:</p><pre>EXPLAIN ANALYZE SELECT * FROM orders WHERE status = &#39;DELIVERED&#39;;</pre><pre>QUERY PLAN<br>-------------------------------------------------------------------------------------------------------------------<br> Seq Scan on orders  (cost=0.00..21758.00 rows=901133 width=39) (actual time=0.010..45.292 rows=899764.00 loops=1)<br>   Filter: (status = &#39;DELIVERED&#39;::text)<br>   Rows Removed by Filter: 100236<br>   Buffers: shared hit=9258<br> Planning:<br>   Buffers: shared hit=106<br> Planning Time: 0.266 ms<br> Execution Time: 63.846 ms<br>(8 rows)</pre><p>Index duruyor, planner görmezden geldi ve tabloyu baştan sona taradı. İlk refleks “PostgreSQL bozuk, index’imi kullanmıyor” olabilir. Planner’ın haklı olup olmadığını test etmenin yolu var — Seq Scan’i (teşhis amaçlı) yasaklayıp aynı sorguyu zorlayalım:</p><pre>SET enable_seqscan = off;<br>EXPLAIN ANALYZE SELECT * FROM orders WHERE status = &#39;DELIVERED&#39;;<br>RESET enable_seqscan;</pre><pre>QUERY PLAN<br>------------------------------------------------------------------------------------------------------------------------------------------<br> Bitmap Heap Scan on orders  (cost=10092.21..30614.37 rows=901133 width=39) (actual time=7.742..40.111 rows=899764.00 loops=1)<br>   Recheck Cond: (status = &#39;DELIVERED&#39;::text)<br>   Heap Blocks: exact=9258<br>   Buffers: shared hit=10030<br>   -&gt;  Bitmap Index Scan on idx_orders_status  (cost=0.00..9866.92 rows=901133 width=0) (actual time=7.047..7.048 rows=899764.00 loops=1)<br>         Index Cond: (status = &#39;DELIVERED&#39;::text)<br>         Index Searches: 1<br>         Buffers: shared hit=772<br> Planning Time: 0.052 ms<br> Execution Time: 56.865 ms<br>(10 rows)</pre><p>Sayıları dürüstçe okuyalım. Page muhasebesi net: satırların %90&#39;ı isteniyorsa heap’in zaten her page’i okunacak (Heap Blocks: exact=9258 — tamamı). Index bu duruma hiçbir şey kazandırmıyor; üstüne 772 page&#39;lik index okuma yükü bindiriyor (Buffers: shared hit=10030 = 9.258 heap + 772 index). Planner iki planın cost&#39;unu hesaplamıştı — Seq Scan 21.758, Bitmap 30.614 — ve ucuz olanı seçti. Kronometreye gelince: bu koşuda ikisi de sıcak cache&#39;te aynı banda düştü (57-64 ms; tekrarlarda sıra değişebiliyor), çünkü fazladan 772 page cache&#39;ten geldiğinde bedeli milisaniyeye zor yansır. Fark, cache soğukken ya da tablo cache&#39;e sığmazken açılır — o 772 page&#39;in her biri gerçek bir I/O olduğunda. Ders şu: <strong>kronometre koşullara göre konuşur, page muhasebesi her koşulda aynı gerçeği söyler.</strong></p><p>Bu deneyden iki kalıcı ders çıkıyor. Birincisi: “index koydum ama kullanmıyor” şikayetinde ilk bakılacak şey sorgunun tablodan <strong>yüzde kaç satır istediğidir</strong>; oran yüksekse planner büyük ihtimalle haklıdır ve uğraşılması gereken index değil, sorgunun kendisidir — bu sorgu gerçekten 900 bin satır döndürmeli mi? İkincisi: enable_seqscan = off yalnızca bir <strong>teşhis aracıdır</strong> — planner&#39;ın kararını sınamak için laboratuvarda kullanılır, production&#39;da asla bırakılmaz.</p><p>Kaba bir pusula, kanun değil: sorgu tablonun <strong>%1&#39;inden azını</strong> istiyorsa Index Scan, <strong>%1–5 arasını</strong> istiyorsa Bitmap, <strong>%5–10&#39;dan fazlasını</strong> istiyorsa muhtemelen Seq Scan kazanır. Sınırlar satırların page dağılımına göre kayar — PENDING örneğinde gördüğümüz gibi.</p><h3>Adım 3 — Join Tipleri: Üç Algoritma, Tek Doğru Yok</h3><p>PostgreSQL iki tabloyu birleştirmek için üç algoritma bilir: <strong>Nested Loop</strong>, <strong>Hash Join</strong>, <strong>Merge Join</strong>. Aralarında “en iyisi” yoktur — her biri belli bir girdi profilinde kazanır ve planner, tahminlerine bakarak her sorgu için yeniden seçim yapar. Bu adımda üçünü de canlı tetikleyeceğiz ve sonunda loops kuralının büyük ödemesini alacağız: N+1 probleminin plan çıktısındaki yüzünü.</p><h3>Nested Loop — az satırın join’i</h3><p>Bir müşterinin siparişlerini e-posta adresinden bulalım:</p><pre>EXPLAIN ANALYZE<br>SELECT c.name, o.id, o.total_amount<br>FROM customers c<br>JOIN orders o ON o.customer_id = c.id<br>WHERE c.email = &#39;user42@example.com&#39;;</pre><pre>QUERY PLAN<br>-----------------------------------------------------------------------------------------------------------------------------------------<br> Nested Loop  (cost=4.51..2328.62 rows=10 width=28) (actual time=0.079..5.547 rows=4.00 loops=1)<br>   Buffers: shared hit=1038<br>   -&gt;  Seq Scan on customers c  (cost=0.00..2281.00 rows=1 width=22) (actual time=0.051..5.501 rows=1.00 loops=1)<br>         Filter: (email = &#39;user42@example.com&#39;::text)<br>         Rows Removed by Filter: 99999<br>         Buffers: shared hit=1031<br>   -&gt;  Bitmap Heap Scan on orders o  (cost=4.51..47.51 rows=11 width=22) (actual time=0.026..0.040 rows=4.00 loops=1)<br>         Recheck Cond: (c.id = customer_id)<br>         Heap Blocks: exact=4<br>         Buffers: shared hit=7<br>         -&gt;  Bitmap Index Scan on idx_orders_customer_id  (cost=0.00..4.51 rows=11 width=0) (actual time=0.009..0.009 rows=4.00 loops=1)<br>               Index Cond: (customer_id = c.id)<br>               Index Searches: 1<br>               Buffers: shared hit=3<br> Planning:<br>   Buffers: shared hit=247 read=2 dirtied=1<br> Planning Time: 0.811 ms<br> Execution Time: 5.608 ms<br>(18 rows)</pre><p>Nested Loop’un mantığı ilkokul seviyesinde basit: <strong>dış (outer) taraftan bir satır al, iç (inner) tarafta eşleşenleri bul; dış tarafta satır kaldıkça tekrarla.</strong> Plan çıktısında dış taraf her zaman üstte, iç taraf altta yazar. Burada dış taraf tek satır döndürdü (aradığımız müşteri), iç taraf da onun için bir kez çalıştı. Dış taraf az satır üretiyorsa ve iç tarafta index varsa, Nested Loop rakipsizdir — hash tablosu kurmanın, sıralamanın hiçbir hazırlık maliyeti yok.</p><p>Bu arada çıktıda gözünüze bir şey takılmış olmalı: Seq Scan on customers ve Rows Removed by Filter: 99999. E-posta ile müşteri aramak için 100 bin satır taradık — çünkü email kolonunda index yok. Sürenin 5.6 ms&#39;sinin 5.5&#39;i bu tarama. Adım 1&#39;in kırmızı bayrağı, bu kez bir join&#39;in içinde karşımıza çıktı. Şimdilik not edin; Adım 7&#39;de bu sorunla (ve lower(email) tuzağıyla) hesaplaşacağız.</p><h3>loops kuralının geri dönüşü</h3><p>Dış tarafı büyütelim — 300 müşterilik bir dilimin sipariş sayıları:</p><pre>EXPLAIN ANALYZE<br>SELECT c.id, count(o.id)<br>FROM customers c<br>JOIN orders o ON o.customer_id = c.id<br>WHERE c.id BETWEEN 1 AND 300<br>GROUP BY c.id;</pre><pre>QUERY PLAN<br>------------------------------------------------------------------------------------------------------------------------------------------------------------------------<br> Finalize GroupAggregate  (cost=10192.73..10255.53 rows=296 width=16) (actual time=6.485..8.241 rows=300.00 loops=1)<br>   Group Key: c.id<br>   Buffers: shared hit=5013 read=3<br>   -&gt;  Gather Merge  (cost=10192.73..10250.06 rows=503 width=16) (actual time=6.481..8.192 rows=300.00 loops=1)<br>         Workers Planned: 1<br>         Workers Launched: 1<br>         Buffers: shared hit=5013 read=3<br>         -&gt;  Sort  (cost=9192.72..9193.46 rows=296 width=16) (actual time=5.013..5.021 rows=150.00 loops=2)<br>               Sort Key: c.id<br>               Sort Method: quicksort  Memory: 31kB<br>               Buffers: shared hit=5013 read=3<br>               Worker 0:  Sort Method: quicksort  Memory: 28kB<br>               -&gt;  Partial HashAggregate  (cost=9177.61..9180.57 rows=296 width=16) (actual time=4.965..4.980 rows=150.00 loops=2)<br>                     Group Key: c.id<br>                     Batches: 1  Memory Usage: 48kB<br>                     Buffers: shared hit=5005 read=3<br>                     Worker 0:  Batches: 1  Memory Usage: 48kB<br>                     -&gt;  Nested Loop  (cost=0.42..9168.91 rows=1741 width=16) (actual time=0.058..4.822 rows=1539.00 loops=2)<br>                           Buffers: shared hit=5005 read=3<br>                           -&gt;  Parallel Seq Scan on customers c  (cost=0.00..1913.35 rows=174 width=8) (actual time=0.008..1.803 rows=150.00 loops=2)<br>                                 Filter: ((id &gt;= 1) AND (id &lt;= 300))<br>                                 Rows Removed by Filter: 49850<br>                                 Buffers: shared hit=1031<br>                           -&gt;  Index Scan using idx_orders_customer_id on orders o  (cost=0.42..41.59 rows=11 width=16) (actual time=0.003..0.019 rows=10.26 loops=300)<br>                                 Index Cond: (customer_id = c.id)<br>                                 Index Searches: 300<br>                                 Buffers: shared hit=3974 read=3<br> Planning:<br>   Buffers: shared hit=32<br> Planning Time: 0.192 ms<br> Execution Time: 8.354 ms<br>(31 rows)</pre><p>İşte Adım 1&#39;de öğrendiğimiz kuralın sahnesi: iç taraftaki Index Scan <strong>loops=300</strong> — dış taraf 300 müşteri üretti, iç taraf her biri için bir kez, toplam 300 kez çalıştı (Index Searches: 300 da aynı şeyi söylüyor). rows=10.26 ise loop başına ortalama: her müşterinin ~10 siparişi var, toplam 300 × 10.26 ≈ 3.078 satır. Süreler de loop başınadır — tek bir index araması ~0.02 ms, ama bunu 300&#39;le çarpmak gerekir.</p><p>300 ucuz index araması için Nested Loop hâlâ doğru seçim. Peki bu sayı 300 değil de 300.000 olsaydı? O zaman planner’ın başka bir alete uzanması gerekirdi. Uzanmadıysa — yani kocaman bir dış tarafla Nested Loop görüyorsanız — neredeyse her zaman bir <strong>tahmin hatası</strong> vardır: planner dış tarafı küçük sanmıştır. Doğrulaması basit: dış taraftaki rows tahminiyle actual rows&#39;u karşılaştırın. Uçurum varsa problem join&#39;de değil, istatistiklerdedir (Adım 4).</p><h3>Hash Join — büyük kümelerin join’i</h3><p>Şimdi filtresiz, iki tablonun tamamını ilgilendiren bir soru: ülke bazında ciro.</p><pre>EXPLAIN ANALYZE<br>SELECT c.country, sum(o.total_amount)<br>FROM customers c<br>JOIN orders o ON o.customer_id = c.id<br>GROUP BY c.country;</pre><pre>QUERY PLAN<br>-----------------------------------------------------------------------------------------------------------------------------------------------------------------<br> Finalize GroupAggregate  (cost=19956.48..19958.03 rows=5 width=35) (actual time=96.341..98.749 rows=5.00 loops=1)<br>   Group Key: c.country<br>   Buffers: shared hit=10305<br>   -&gt;  Gather Merge  (cost=19956.48..19957.87 rows=12 width=35) (actual time=96.332..98.738 rows=15.00 loops=1)<br>         Workers Planned: 2<br>         Workers Launched: 2<br>         Buffers: shared hit=10305<br>         -&gt;  Sort  (cost=18956.45..18956.47 rows=5 width=35) (actual time=94.930..94.933 rows=5.00 loops=3)<br>               Sort Key: c.country<br>               Sort Method: quicksort  Memory: 25kB<br>               Buffers: shared hit=10305<br>               Worker 0:  Sort Method: quicksort  Memory: 25kB<br>               Worker 1:  Sort Method: quicksort  Memory: 25kB<br>               -&gt;  Partial HashAggregate  (cost=18956.33..18956.39 rows=5 width=35) (actual time=94.904..94.907 rows=5.00 loops=3)<br>                     Group Key: c.country<br>                     Batches: 1  Memory Usage: 32kB<br>                     Buffers: shared hit=10289<br>                     Worker 0:  Batches: 1  Memory Usage: 32kB<br>                     Worker 1:  Batches: 1  Memory Usage: 32kB<br>                     -&gt;  Parallel Hash Join  (cost=2354.54..16873.00 rows=416667 width=9) (actual time=6.246..65.626 rows=333333.33 loops=3)<br>                           Hash Cond: (o.customer_id = c.id)<br>                           Buffers: shared hit=10289<br>                           -&gt;  Parallel Seq Scan on orders o  (cost=0.00..13424.67 rows=416667 width=14) (actual time=0.008..11.490 rows=333333.33 loops=3)<br>                                 Buffers: shared hit=9258<br>                           -&gt;  Parallel Hash  (cost=1619.24..1619.24 rows=58824 width=11) (actual time=5.980..5.981 rows=33333.33 loops=3)<br>                                 Buckets: 131072  Batches: 1  Memory Usage: 5760kB<br>                                 Buffers: shared hit=1031<br>                                 -&gt;  Parallel Seq Scan on customers c  (cost=0.00..1619.24 rows=58824 width=11) (actual time=0.006..1.948 rows=33333.33 loops=3)<br>                                       Buffers: shared hit=1031<br> Planning:<br>   Buffers: shared hit=42 read=1 dirtied=1<br> Planning Time: 0.644 ms<br> Execution Time: 98.798 ms<br>(33 rows)</pre><p>Hash Join iki fazda çalışır. Önce <strong>build</strong>: küçük tarafı (burada 100 bin satırlık customers) okuyup bellekte bir hash tablosuna koyar — Parallel Hash node&#39;u bu, Memory Usage: 5760kB de tablonun bedeli. Sonra <strong>probe</strong>: büyük tarafı (1 milyon satırlık orders) akıtır ve her satır için hash tablosuna bakar. Her iki tablo da <strong>bir kez</strong> okunur; Nested Loop&#39;taki gibi satır başına tekrar yoktur. Büyük × büyük join&#39;lerin standart aleti budur.</p><p>Çıktıda nöbet tutulacak satır: <strong>Batches: 1</strong>. Hash tablosu work_mem&#39;e sığdı, tek seferde kuruldu. Sığmasaydı Batches: 8 gibi bir değer görürdünüz — tablo parçalara bölünüp diske taşınıyor demektir ve maliyet sıçrar. Bunu Adım 5&#39;te bilerek tetikleyeceğiz.</p><p>Bir incelik: “küçük taraf” tablonun kendisi değil, <strong>join’e giren satır kümesidir.</strong> Birazdan N+1 kıyasında göreceksiniz — filtreli orders (8.250 satır) build tarafı olacak, 100 bin satırlık customers probe. Planner build tarafını hep daha küçük kümeden seçmeye çalışır; hash tablosu ne kadar küçükse o kadar iyi.</p><h3>Merge Join — sıralı girdilerin join’i</h3><p>Üçüncü algoritmayı planner bu veriyle kendiliğinden seçmiyor, çünkü elimizdeki senaryolarda hash daha ucuz. Laboratuvar modunda zorlayalım (bunlar da enable_seqscan gibi teşhis anahtarları — production&#39;da yeri yok):</p><pre>SET enable_hashjoin = off;<br>SET enable_nestloop = off;<br>EXPLAIN ANALYZE<br>SELECT c.country, sum(o.total_amount)<br>FROM customers c JOIN orders o ON o.customer_id = c.id<br>GROUP BY c.country;<br>RESET enable_hashjoin;<br>RESET enable_nestloop;</pre><pre>QUERY PLAN<br>--------------------------------------------------------------------------------------------------------------------------------------------------------------------------<br> Finalize GroupAggregate  (cost=62914.90..62916.45 rows=5 width=35) (actual time=206.612..207.531 rows=5.00 loops=1)<br>   Group Key: c.country<br>   Buffers: shared hit=1003428 read=1124<br>   -&gt;  Gather Merge  (cost=62914.90..62916.29 rows=12 width=35) (actual time=206.605..207.522 rows=15.00 loops=1)<br>         Workers Planned: 2<br>         Workers Launched: 2<br>         Buffers: shared hit=1003428 read=1124<br>         -&gt;  Sort  (cost=61914.87..61914.89 rows=5 width=35) (actual time=205.123..205.124 rows=5.00 loops=3)<br>               Sort Key: c.country<br>               Sort Method: quicksort  Memory: 25kB<br>               Buffers: shared hit=1003428 read=1124<br>               Worker 0:  Sort Method: quicksort  Memory: 25kB<br>               Worker 1:  Sort Method: quicksort  Memory: 25kB<br>               -&gt;  Partial HashAggregate  (cost=61914.75..61914.82 rows=5 width=35) (actual time=205.102..205.103 rows=5.00 loops=3)<br>                     Group Key: c.country<br>                     Batches: 1  Memory Usage: 32kB<br>                     Buffers: shared hit=1003412 read=1124<br>                     Worker 0:  Batches: 1  Memory Usage: 32kB<br>                     Worker 1:  Batches: 1  Memory Usage: 32kB<br>                     -&gt;  Merge Join  (cost=2.21..59831.42 rows=416667 width=9) (actual time=0.038..172.819 rows=333333.33 loops=3)<br>                           Merge Cond: (o.customer_id = c.id)<br>                           Buffers: shared hit=1003412 read=1124<br>                           -&gt;  Parallel Index Scan using idx_orders_customer_id on orders o  (cost=0.42..50737.52 rows=416667 width=14) (actual time=0.014..131.617 rows=333333.33 loops=3)<br>                                 Index Searches: 1<br>                                 Buffers: shared hit=999495 read=1124<br>                           -&gt;  Index Scan using customers_pkey on customers c  (cost=0.29..3638.29 rows=100000 width=11) (actual time=0.013..6.614 rows=99913.33 loops=3)<br>                                 Index Searches: 3<br>                                 Buffers: shared hit=3917<br> Planning:<br>   Buffers: shared hit=263<br> Planning Time: 0.378 ms<br> Execution Time: 207.608 ms<br>(32 rows)</pre><p>Merge Join’in şartı: <strong>iki girdi de join kolonuna göre sıralı olmalı.</strong> Sıra ya index’ten bedavaya gelir (burada olduğu gibi — iki taraf da Index Scan) ya da açık bir Sort node&#39;uyla satın alınır. İki sıralı listeyi fermuar gibi kapatır; çok büyük, sıralı-gelen kümelerde hash&#39;in bellek maliyetine katlanmadan çalışır.</p><p>Ama sayılara bakın: 207.6 ms — Hash Join 98.8 ms’ydi. Ve Buffers: shared hit=999495: <strong>bir milyon page erişimi!</strong> Nedeni öğretici: orders&#39;ı &quot;index sırasıyla&quot; okumak, index&#39;in her kaydı için heap&#39;e ayrı zıplamak demek. Satırlar heap&#39;te customer_id sırasında durmuyor (Adım 2&#39;deki correlation meselesi) — her zıplama farklı bir page&#39;e düştü. Planner iki planın cost&#39;unu zaten hesaplamıştı: Merge 59.831, Hash 16.873. Yine haklıydı; kronometre bu kez tereddütsüz onayladı.</p><h3>Büyük final: N+1&#39;in plan çıktısındaki yüzü</h3><p>Şimdi aynı işi iki şekilde yazacağız. Önce correlated subquery ile — yani “her sipariş için müşteri adını ayrıca sor” diyerek:</p><pre>EXPLAIN ANALYZE<br>SELECT o.id,<br>       (SELECT c.name FROM customers c WHERE c.id = o.customer_id) AS customer_name<br>FROM orders o<br>WHERE o.created_at &gt; now() - interval &#39;7 days&#39;;</pre><pre>QUERY PLAN<br>-------------------------------------------------------------------------------------------------------------------------------------------<br> Gather  (cost=1000.00..79094.05 rows=7318 width=40) (actual time=0.075..28.759 rows=8250.00 loops=1)<br>   Workers Planned: 2<br>   Workers Launched: 2<br>   Buffers: shared hit=34008<br>   -&gt;  Parallel Seq Scan on orders o  (cost=0.00..16549.67 rows=3049 width=16) (actual time=0.015..24.162 rows=2750.00 loops=3)<br>         Filter: (created_at &gt; (now() - &#39;7 days&#39;::interval))<br>         Rows Removed by Filter: 330583<br>         Buffers: shared hit=9258<br>   SubPlan 1<br>     -&gt;  Index Scan using customers_pkey on customers c  (cost=0.29..8.31 rows=1 width=14) (actual time=0.001..0.001 rows=1.00 loops=8250)<br>           Index Cond: (id = o.customer_id)<br>           Index Searches: 8250<br>           Buffers: shared hit=24750<br> Planning:<br>   Buffers: shared hit=17<br> Planning Time: 0.088 ms<br> Execution Time: 28.943 ms<br>(17 rows)</pre><p>SubPlan 1 altındaki satırı okuyun: <strong>loops=8250</strong>. Son 7 günde 8.250 sipariş bulundu ve müşteri adı için <strong>8.250 ayrı index araması</strong> yapıldı (Index Searches: 8250). Her arama 0.001 ms — tek başına kusursuz. Ama 8.250 tanesi, Buffers toplamını 34.008 page&#39;e şişirdi. İşte &quot;her sorgu hızlı ama toplam yavaş&quot; durumunun anatomisi.</p><p>Aynı iş, JOIN ile:</p><pre>EXPLAIN ANALYZE<br>SELECT o.id, c.name AS customer_name<br>FROM orders o<br>JOIN customers c ON c.id = o.customer_id<br>WHERE o.created_at &gt; now() - interval &#39;7 days&#39;;</pre><pre>QUERY PLAN<br>--------------------------------------------------------------------------------------------------------------------------------------------<br> Gather  (cost=17587.78..20397.93 rows=7318 width=22) (actual time=43.872..50.031 rows=8250.00 loops=1)<br>   Workers Planned: 1<br>   Workers Launched: 1<br>   Buffers: shared hit=10289<br>   -&gt;  Parallel Hash Join  (cost=16587.78..18666.13 rows=4305 width=22) (actual time=42.925..47.475 rows=4125.00 loops=2)<br>         Hash Cond: (c.id = o.customer_id)<br>         Buffers: shared hit=10289<br>         -&gt;  Parallel Seq Scan on customers c  (cost=0.00..1619.24 rows=58824 width=22) (actual time=0.007..1.589 rows=50000.00 loops=2)<br>               Buffers: shared hit=1031<br>         -&gt;  Parallel Hash  (cost=16549.67..16549.67 rows=3049 width=16) (actual time=42.813..42.814 rows=4125.00 loops=2)<br>               Buckets: 8192  Batches: 1  Memory Usage: 480kB<br>               Buffers: shared hit=9258<br>               -&gt;  Parallel Seq Scan on orders o  (cost=0.00..16549.67 rows=3049 width=16) (actual time=0.027..42.292 rows=4125.00 loops=2)<br>                     Filter: (created_at &gt; (now() - &#39;7 days&#39;::interval))<br>                     Rows Removed by Filter: 495875<br>                     Buffers: shared hit=9258<br> Planning:<br>   Buffers: shared hit=254<br> Planning Time: 0.474 ms<br> Execution Time: 50.217 ms<br>(20 rows)</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*G6XhAeNB6_ZL70NkYcrBcg.png" /></figure><p>Tabloyu dürüstçe okuyalım, çünkü bir sürprizi var. Page muhasebesi net konuşuyor: subquery 3.3 kat fazla page’e dokundu (34.008&#39;e karşı 10.289) — JOIN, planner’a küme bazlı düşünme fırsatı verdi, o da satır satır sormak yerine hash kurdu. Ama kronometre bu koşuda <strong>ters</strong> söylüyor: sıcak cache’te 8.250 index araması o kadar ucuz ki (araması 0.001 ms), subquery hash build’in sabit maliyetini yenip 28.9 ms’de bitti. Bu, Adım 6&#39;da kural olarak koyacağımız şeyin canlı kanıtı: <strong>süre koşullara göre konuşur, page sayısı yalan söylemez.</strong> O 3.3 kat fark faturaya üç durumda döner: cache soğuduğunda (her page erişimi gerçek I/O olur), tablo büyüdüğünde, ve en acısı — bu desen uygulama katına taşındığında. ORM’in lazy loading’i her siparişin müşterisi için <strong>network üzerinden ayrı sorgu</strong> atarsa, 0.001 ms’lik index araması başına bir de ~1–80 ms’lik network round-trip ödersiniz; 8.250 arama artık 8.250 network turu demektir. Adım 1&#39;deki cümlenin tamamlanışı: plan çıktısında loops=8250 ya da Index Searches: 8250 gördüğünüzde, N+1&#39;i suçüstü yakalamışsınızdır — bazen veritabanının içinde, çoğu zaman da uygulamanızın sorgu deseninde.</p><h3>Adım 4 — İstatistikler: Planner’ın Kristal Küresi ve Onu Kör Etmenin Yolu</h3><p>Buraya kadar planner hep tutarlı çıktı — Seq Scan tercihinde, join seçiminde, hepsinde. Bu güvenin tek bir kaynağı var: <strong>istatistikler.</strong> Planner sorguyu çalıştırmadan maliyet hesaplıyor; hesabın girdisi de ANALYZE&#39;ın topladığı örneklem verisi. Bu adımda önce o veriyi okuyacağız, sonra bilerek bozacağız ve planner&#39;ın nasıl felaket bir karar verdiğini kronometreyle izleyeceğiz.</p><h3>Planner’ın gördüğü dünya: pg_stats</h3><pre>SELECT attname, n_distinct, round(correlation::numeric, 3) AS correlation,<br>       most_common_vals, most_common_freqs<br>FROM pg_stats<br>WHERE tablename = &#39;orders&#39; AND attname IN (&#39;id&#39;,&#39;status&#39;,&#39;customer_id&#39;,&#39;created_at&#39;);</pre><pre>attname   | n_distinct | correlation |           most_common_vals            |              most_common_freqs<br>-------------+------------+-------------+---------------------------------------+---------------------------------------------<br> status      |          4 |       0.813 | {DELIVERED,SHIPPED,CANCELLED,PENDING} | {0.90113336,0.050433334,0.0285,0.019933334}<br> id          |         -1 |       1.000 |                                       |<br> customer_id |      93886 |      -0.008 |                                       |<br> created_at  |         -1 |      -0.006 |                                       |<br>(4 rows)</pre><p>Bu tablo, planner’ın veritabanı hakkında bildiği <em>her şeyin</em> özeti. Satır satır:</p><p><strong>n_distinct</strong> — kolondaki farklı değer sayısı. -1 özel bir değer: &quot;her satır benzersiz&quot; demek (id ve created_at için doğru). status için 4 — planner dört değer olduğunu biliyor. customer_id için 93.886 — gerçekte 100.000; örneklemden gelen makul bir sapma.</p><p><strong>most_common_vals / </strong><strong>most_common_freqs</strong> — en sık değerler ve oranları. Bu iki liste <strong>paraleldir</strong>: most_common_vals[i]&#39;nin frekansı most_common_freqs[i]&#39;dir ve liste frekansa göre büyükten küçüğe sıralıdır — DELIVERED 0.901, SHIPPED 0.050, CANCELLED 0.029, PENDING 0.020. Planner&#39;ın status = &#39;DELIVERED&#39; sorgusuna &quot;901 bin satır gelir&quot; diyebilmesinin sırrı bu eşleşme: DELIVERED %90.1 olarak kayıtlı, tablo boyutuyla çarpıyor, bitti. Adım 2&#39;de Seq Scan tercihinin arkasındaki matematik buymuş — kristal küre değil, çarpım tablosu. Burada dört değerin toplamı ~1.0, çünkü kolonda zaten yalnızca 4 değer var ve hepsi listeye sığdı; çok değerli bir kolonda liste yalnızca en sık N değeri tutar (varsayılan tavan default_statistics_target = 100), listeye girmeyen değerler histogram + n_distinct üzerinden tahmin edilir. Bu detayı aklınızda tutun — birazdan tam bu mekanizmanın ters köşesine düşeceğiz.</p><p><strong>correlation</strong> — kolonun mantıksal sırası ile satırların fiziksel (heap&#39;teki) sırası arasındaki ilişki; -1 ile 1 arasında. id için 1.000: satırlar heap&#39;e id sırasıyla yazıldı. created_at için -0.006: seed&#39;de tarihleri rastgele ürettiğimiz için fiziksel sırayla hiçbir ilgisi yok. Adım 2&#39;deki &quot;PENDING satırlar neden 8.220 page&#39;e dağılmıştı&quot; sorusunun ölçülebilir cevabı işte bu sütunda. Planner correlation&#39;a bakarak &quot;index&#39;le gidersem kaç page zıplarım&quot;ı tahmin eder; düşük correlation, index&#39;in cazibesini azaltır.</p><h3>İstatistiği bilerek bozuyoruz</h3><p>Senaryo şu — production’da her hafta yaşanan cinsten: sisteme yeni bir kavram giriyor. İade süreci devreye alındı ve tabloya ilk kez REFUNDED statüsü yazılmaya başladı. Kısa sürede 150 bin iade birikti. ANALYZE henüz koşmadı (deneyde garantiye almak için tabloda autovacuum&#39;u kapattım):</p><pre>ALTER TABLE orders SET (autovacuum_enabled = false);<br><br>INSERT INTO orders (customer_id, status, total_amount, created_at)<br>SELECT 1 + floor(random()*100000)::int, &#39;REFUNDED&#39;,<br>       round((random()*500 + 5)::numeric, 2),<br>       now() - (random() * interval &#39;30 days&#39;)<br>FROM generate_series(1, 150000);<br><br>EXPLAIN ANALYZE SELECT * FROM orders WHERE status = &#39;REFUNDED&#39;;</pre><pre>QUERY PLAN<br>-----------------------------------------------------------------------------------------------------------------------------------<br> Index Scan using idx_orders_status on orders  (cost=0.43..5.80 rows=1 width=39) (actual time=0.007..7.997 rows=150000.00 loops=1)<br>   Index Cond: (status = &#39;REFUNDED&#39;::text)<br>   Index Searches: 1<br>   Buffers: shared hit=1382<br> Planning:<br>   Buffers: shared hit=28<br> Planning Time: 0.056 ms<br> Execution Time: 10.757 ms<br>(8 rows)</pre><p>rows=1 tahmin, rows=150000 gerçek. <strong>Yüz elli bin kat hata.</strong> Nedeni mekanik: planner MCV listesine baktı, REFUNDED orada yok; n_distinct=4 diyor ve dördü de listede — &quot;bu değerden yok denecek kadar az vardır&quot; sonucuna vardı ve minimum tahmin olan 1&#39;i yazdı. Planner&#39;ın dünyasında REFUNDED diye bir şey henüz mevcut değil.</p><p>Sorgunun kendisi yine de ~11 ms’de bitti — yeni satırlar heap’in sonuna arka arkaya yazıldığı için fiziksel olarak kümeliler, index scan’in zıplamaları hep aynı page’lere denk geldi (Buffers: shared hit=1382 — 150 bin satır için sadece 1.382 page). &quot;Tahmin yanlış ama sorgu hızlı; ne var bunda?&quot; diyebilirsiniz. Asıl tehlike şurada: <strong>yanlış tahmin yerel kalmaz — üzerine kurulan her kararı zehirler.</strong></p><h3>Felaketin zinciri: yanlış tahminin üstüne kurulan join</h3><p>İade raporu isteyelim — ülke bazında iade sayısı:</p><pre>EXPLAIN ANALYZE<br>SELECT c.country, count(*)<br>FROM orders o<br>JOIN customers c ON c.id = o.customer_id<br>WHERE o.status = &#39;REFUNDED&#39;<br>GROUP BY c.country;</pre><pre>QUERY PLAN<br>-------------------------------------------------------------------------------------------------------------------------------------------------------<br> GroupAggregate  (cost=14.12..14.14 rows=1 width=11) (actual time=140.085..146.918 rows=5.00 loops=1)<br>   Group Key: c.country<br>   Buffers: shared hit=451385<br>   -&gt;  Sort  (cost=14.12..14.13 rows=1 width=3) (actual time=138.371..141.742 rows=150000.00 loops=1)<br>         Sort Key: c.country<br>         Sort Method: quicksort  Memory: 4096kB<br>         Buffers: shared hit=451385<br>         -&gt;  Nested Loop  (cost=0.72..14.11 rows=1 width=3) (actual time=0.038..127.308 rows=150000.00 loops=1)<br>               Buffers: shared hit=451382<br>               -&gt;  Index Scan using idx_orders_status on orders o  (cost=0.43..5.80 rows=1 width=8) (actual time=0.024..9.046 rows=150000.00 loops=1)<br>                     Index Cond: (status = &#39;REFUNDED&#39;::text)<br>                     Index Searches: 1<br>                     Buffers: shared hit=1382<br>               -&gt;  Index Scan using customers_pkey on customers c  (cost=0.29..8.31 rows=1 width=11) (actual time=0.001..0.001 rows=1.00 loops=150000)<br>                     Index Cond: (id = o.customer_id)<br>                     Index Searches: 150000<br>                     Buffers: shared hit=450000<br> Planning:<br>   Buffers: shared hit=242<br> Planning Time: 0.427 ms<br> Execution Time: 147.067 ms<br>(21 rows)</pre><p>Zinciri takip edin. Planner “REFUNDED’dan 1 satır gelir” sanıyor → “1 satır için Nested Loop biçilmiş kaftan” diyor (sorgunun tamamına 14 birim cost biçmiş — bir page’lik iş bekliyordu!) → gerçekte dış taraftan 150.000 satır akıyor → iç taraf <strong>150.000 kez</strong> çalışıyor (loops=150000, Adım 3&#39;ün kırmızı bayrağı) → müşteri tablosuna 450.000 page erişimi → 147 ms.</p><p>Adım 3&#39;te sormuştuk: “kocaman dış tarafla Nested Loop görüyorsanız, neredeyse her zaman tahmin hatası vardır.” İşte kanıtı, laboratuvar koşullarında.</p><p>Bayatlığın production’daki teşhisi de tek sorgu:</p><pre>SELECT n_live_tup, n_mod_since_analyze, last_analyze, last_autoanalyze<br>FROM pg_stat_user_tables WHERE relname = &#39;orders&#39;;</pre><pre>n_live_tup | n_mod_since_analyze |         last_analyze          |       last_autoanalyze<br>------------+---------------------+-------------------------------+-------------------------------<br>    1150000 |              150000 | 2026-07-08 07:38:51.046483+00 | 2026-07-08 07:39:28.834107+00<br>(1 row)</pre><p>n_mod_since_analyze = 150000: son istatistik toplamadan beri 150 bin satır değişmiş. Bir planda tahmin/gerçek uçurumu gördüğünüzde ikinci bakacağınız yer burasıdır.</p><h3>Tamir: tek kelime</h3><pre>ANALYZE orders;</pre><p>Aynı iki sorguyu tekrar çalıştıralım. Önce scan:</p><pre>QUERY PLAN<br>------------------------------------------------------------------------------------------------------------------------------------------<br> Bitmap Heap Scan on orders  (cost=1682.18..14070.43 rows=150420 width=39) (actual time=1.547..7.964 rows=150000.00 loops=1)<br>   Recheck Cond: (status = &#39;REFUNDED&#39;::text)<br>   Heap Blocks: exact=1261<br>   Buffers: shared hit=1382<br>   -&gt;  Bitmap Index Scan on idx_orders_status  (cost=0.00..1644.58 rows=150420 width=0) (actual time=1.466..1.467 rows=150000.00 loops=1)<br>         Index Cond: (status = &#39;REFUNDED&#39;::text)<br>         Index Searches: 1<br>         Buffers: shared hit=121<br> Planning:<br>   Buffers: shared hit=51<br> Planning Time: 0.127 ms<br> Execution Time: 10.604 ms<br>(12 rows)</pre><p>Tahmin 150.420, gerçek 150.000 — planner artık görüyor ve plan da değişti: tek satır beklerken seçtiği Index Scan yerine, 150 bin satıra uygun Bitmap. Şimdi join:</p><pre>QUERY PLAN<br>------------------------------------------------------------------------------------------------------------------------------------------------------------------------<br> Finalize GroupAggregate  (cost=16806.20..16807.70 rows=5 width=11) (actual time=21.290..22.869 rows=5.00 loops=1)<br>   Group Key: c.country<br>   Buffers: shared hit=2429<br>   -&gt;  Gather Merge  (cost=16806.20..16807.59 rows=12 width=11) (actual time=21.285..22.863 rows=15.00 loops=1)<br>         Workers Planned: 2<br>         Workers Launched: 2<br>         Buffers: shared hit=2429<br>         -&gt;  Sort  (cost=15806.17..15806.18 rows=5 width=11) (actual time=19.904..19.909 rows=5.00 loops=3)<br>               Sort Key: c.country<br>               Sort Method: quicksort  Memory: 25kB<br>               Buffers: shared hit=2429<br>               Worker 0:  Sort Method: quicksort  Memory: 25kB<br>               Worker 1:  Sort Method: quicksort  Memory: 25kB<br>               -&gt;  Partial HashAggregate  (cost=15806.06..15806.11 rows=5 width=11) (actual time=19.879..19.884 rows=5.00 loops=3)<br>                     Group Key: c.country<br>                     Batches: 1  Memory Usage: 32kB<br>                     Buffers: shared hit=2413<br>                     Worker 0:  Batches: 1  Memory Usage: 32kB<br>                     Worker 1:  Batches: 1  Memory Usage: 32kB<br>                     -&gt;  Parallel Hash Join  (cost=4036.72..15492.69 rows=62675 width=3) (actual time=6.203..16.391 rows=50000.00 loops=3)<br>                           Hash Cond: (o.customer_id = c.id)<br>                           Buffers: shared hit=2413<br>                           -&gt;  Parallel Bitmap Heap Scan on orders o  (cost=1682.18..12973.62 rows=62675 width=8) (actual time=1.503..4.197 rows=50000.00 loops=3)<br>                                 Recheck Cond: (status = &#39;REFUNDED&#39;::text)<br>                                 Heap Blocks: exact=443<br>                                 Buffers: shared hit=1382<br>                                 Worker 0:  Heap Blocks: exact=418<br>                                 Worker 1:  Heap Blocks: exact=400<br>                                 -&gt;  Bitmap Index Scan on idx_orders_status  (cost=0.00..1644.58 rows=150420 width=0) (actual time=1.401..1.402 rows=150000.00 loops=1)<br>                                       Index Cond: (status = &#39;REFUNDED&#39;::text)<br>                                       Index Searches: 1<br>                                       Buffers: shared hit=121<br>                           -&gt;  Parallel Hash  (cost=1619.24..1619.24 rows=58824 width=11) (actual time=4.573..4.574 rows=33333.33 loops=3)<br>                                 Buckets: 131072  Batches: 1  Memory Usage: 5760kB<br>                                 Buffers: shared hit=1031<br>                                 -&gt;  Parallel Seq Scan on customers c  (cost=0.00..1619.24 rows=58824 width=11) (actual time=0.005..1.762 rows=33333.33 loops=3)<br>                                       Buffers: shared hit=1031<br> Planning:<br>   Buffers: shared hit=102<br> Planning Time: 0.194 ms<br> Execution Time: 22.896 ms<br>(41 rows)</pre><figure><img alt="" src="https://cdn-images-1.medium.com/proxy/1*uJo6RqZtmuZGg8Xn_1CzhA.png" /></figure><p>Sorgu değişmedi, index değişmedi, veri değişmedi. Değişen tek şey planner’ın <strong>bilgisi.</strong> “Bir sorgu dün hızlıydı, bugün yavaş” vakalarının büyük bölümü bu mekanizmadan çıkar: veri profili kaydı, istatistik geride kaldı, planner eski dünyaya göre plan kesmeye devam etti. Normal şartlarda autovacuum’un analyze bacağı bu açığı kendiliğinden kapatır (varsayılan eşik: tablonun ~%10&#39;u değişince); büyük tablolarda o %10&#39;a ulaşmak uzun sürebildiği için kritik tablolarda eşiği düşürmek (autovacuum_analyze_scale_factor) ya da büyük toplu yüklemelerden sonra elle ANALYZE koşmak yaygın pratiktir.</p><p>Deney bitti, autovacuum’u geri açtım: ALTER TABLE orders SET (autovacuum_enabled = true); — tablo artık 1.15 milyon satır; sonraki adımların sayıları buna göre okunmalı.</p><h3>Adım 5 — BUFFERS ve Bellek: Aynı Sorgu, Farklı Kader</h3><p>Şimdiye kadar Buffers satırını hep &quot;kaç page&#39;e dokunduk&quot; diye okuduk. Bu adımda önce satırın tam sözlüğünü çıkaracağız, sonra bileşenlerini tek tek canlı tetikleyeceğiz — ve sorgu belleğinin (work_mem) plan üzerindeki şaşırtıcı gücünü göreceğiz.</p><h3>Buffers sözlüğü ve cache’in yaşam döngüsü</h3><p>Buffers satırı, sorgunun page muhasebesidir: hangi page&#39;lere, nereden, ne pahasına dokunuldu. Görebileceğiniz bileşenler:</p><p>BileşenAnlamıshared hitPage, PostgreSQL&#39;in kendi cache&#39;inde (shared buffers) bulundu — en ucuz yolshared readPage cache&#39;te yoktu, dışarıdan getirildi (disk <strong>veya</strong> OS&#39;in page cache&#39;i — ayrımı PostgreSQL bilmez)shared dirtiedBu sorgu, <strong>temiz</strong> bir page&#39;i değiştirip kirlettishared writtenBu sorgu, yer açmak için kirli bir page&#39;i diske yazmak zorunda kaldılocal ...Aynı seri, temp tablolar içintemp read/writtenwork_mem&#39;e sığmayan sort/hash&#39;in temp dosya trafiği</p><p>Cache’in yaşam döngüsü de üç cümle: Page’ler cache’e <strong>ilk dokunuşta</strong> yüklenir (demand paging) — PostgreSQL’de her okuma shared buffers üzerinden geçer, page orada değilse önce getirilir (read işte o an). Tahliye zamanlayıcıyla değil <strong>yer ihtiyacıyla</strong> olur: alan dolunca clock-sweep algoritması (kullanım sayaçlı, yaklaşık-LRU) en az kullanılan page&#39;leri atar; atılacak page kirliyse önce diske yazılır — bu işi normalde background writer ve checkpoint yapar, sıkışıldığında sorgunun kendisi üstlenir (written sayacının kaynağı). Ve restart her şeyi sıfırlar — birazdan bilerek yapacağız.</p><p>dirtied en çok yanlış anlaşılanı, çünkü ilk bakışta &quot;SELECT page&#39;i nasıl kirletsin?&quot; diye sorarsınız. DML&#39;in kirletmesi bariz: INSERT yeni satır yazar; UPDATE, MVCC gereği üzerine yazmaz, yeni satır versiyonu ekleyip eskisini ölü işaretler; DELETE ölü işaretler. Ama <strong>salt SELECT de page kirletebilir</strong> — iki mekanizmayla: <strong>(1) Hint bit&#39;ler.</strong> Bir satırı yazan transaction commit olduktan sonra o satırı ilk okuyan sorgu, &quot;bu satırın yazarı commit&#39;lenmiş&quot; bilgisini commit log&#39;dan öğrenir ve bir daha bakmamak için satır başlığına bir bit olarak işler. Bit yazmak = page&#39;i değiştirmek. <strong>(2) HOT pruning.</strong> Okuyan sorgu, uğradığı page&#39;deki ölü satır versiyonlarını fırsatçı bir mini temizlikle ayıklayabilir — vacuum&#39;u beklemeden.</p><p>Kanıtlayalım. Taze bir tabloya 200 bin satır basıp salt count(*) atacağız — ama iki farklı senaryoda:</p><pre>CREATE TABLE hint_demo (id int, payload text);<br>INSERT INTO hint_demo SELECT g, md5(g::text) FROM generate_series(1, 200000) g;<br>EXPLAIN (ANALYZE, BUFFERS) SELECT count(*) FROM hint_demo;</pre><pre>QUERY PLAN<br>----------------------------------------------------------------------------------------------------------------------------------------------<br> Finalize Aggregate  (cost=4223.90..4223.91 rows=1 width=8) (actual time=7.450..8.205 rows=1.00 loops=1)<br>   Buffers: shared hit=1667<br>   -&gt;  Gather  (cost=4223.68..4223.89 rows=2 width=8) (actual time=7.423..8.203 rows=2.00 loops=1)<br>         Workers Planned: 1<br>         Workers Launched: 1<br>         Buffers: shared hit=1667<br>         -&gt;  Partial Aggregate  (cost=3223.68..3223.69 rows=1 width=8) (actual time=6.606..6.606 rows=1.00 loops=2)<br>               Buffers: shared hit=1667<br>               -&gt;  Parallel Seq Scan on hint_demo  (cost=0.00..2912.35 rows=124535 width=0) (actual time=0.006..4.242 rows=100000.00 loops=2)<br>                     Buffers: shared hit=1667<br> Planning:<br>   Buffers: shared hit=10 read=2<br> Planning Time: 0.078 ms<br> Execution Time: 8.222 ms<br>(14 rows)</pre><p>dirtied yok. Ama beklediğimizden değil: hint bit&#39;ler yazıldı — page&#39;ler INSERT&#39;ten beri <strong>zaten kirli</strong> olduğu için sayaç oynamadı. dirtied yalnızca <strong>temiz → kirli</strong> geçişini sayar. Şimdi aynı deney, araya bir CHECKPOINT sokarak (checkpoint kirli page&#39;leri diske yazar, hepsi temizlenir):</p><pre>CREATE TABLE hint_demo2 (id int, payload text);<br>INSERT INTO hint_demo2 SELECT g, md5(g::text) FROM generate_series(1, 200000) g;<br>CHECKPOINT;<br>EXPLAIN (ANALYZE, BUFFERS) SELECT count(*) FROM hint_demo2;</pre><pre>QUERY PLAN<br>-----------------------------------------------------------------------------------------------------------------------------------------------<br> Finalize Aggregate  (cost=4223.90..4223.91 rows=1 width=8) (actual time=12.020..12.942 rows=1.00 loops=1)<br>   Buffers: shared hit=1667 dirtied=1667<br>   -&gt;  Gather  (cost=4223.68..4223.89 rows=2 width=8) (actual time=11.970..12.939 rows=2.00 loops=1)<br>         Workers Planned: 1<br>         Workers Launched: 1<br>         Buffers: shared hit=1667 dirtied=1667<br>         -&gt;  Partial Aggregate  (cost=3223.68..3223.69 rows=1 width=8) (actual time=11.223..11.224 rows=1.00 loops=2)<br>               Buffers: shared hit=1667 dirtied=1667<br>               -&gt;  Parallel Seq Scan on hint_demo2  (cost=0.00..2912.35 rows=124535 width=0) (actual time=0.014..8.744 rows=100000.00 loops=2)<br>                     Buffers: shared hit=1667 dirtied=1667<br> Planning:<br>   Buffers: shared hit=12<br> Planning Time: 0.044 ms<br> Execution Time: 12.955 ms<br>(14 rows)</pre><p>İşte: salt bir SELECT count(*), tablonun 1.667 page&#39;inin <strong>tamamını</strong> kirletti (dirtied=1667) ve bedelini süreyle ödedi (~8 ms yerine ~13 ms). Hemen ardından ikinci kez çalıştırırsanız dirtied kaybolur ve süre 7.9 ms&#39;ye döner — hint bit işi bir kereliktir. Production&#39;daki karşılığı meşhur bir sürprizdir: büyük bir bulk load&#39;dan sonraki ilk büyük SELECT hem beklenenden yavaştır hem de disk&#39;e <em>yazar</em>. &quot;Okuma sorgum neden yazıyor?&quot; sorusunun cevabı çoğu zaman budur.</p><h3>Soğuk ve sıcak: hit ile read</h3><p>shared hit page&#39;in PostgreSQL&#39;in kendi cache&#39;inde (shared buffers) bulunduğunu, read ise orada olmayıp dışarıdan getirildiğini söyler. Farkı laboratuvarda görmenin en temiz yolu cache&#39;i boşaltmak — container&#39;ı yeniden başlattım ve ilk sorguyu attım:</p><pre>EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_id = 42;</pre><p>Soğuk (restart sonrası ilk çalıştırma):</p><pre>QUERY PLAN<br>-----------------------------------------------------------------------------------------------------------------------------------<br> Bitmap Heap Scan on orders  (cost=4.53..55.32 rows=13 width=39) (actual time=0.196..0.413 rows=7.00 loops=1)<br>   Recheck Cond: (customer_id = 42)<br>   Heap Blocks: exact=7<br>   Buffers: shared hit=3 read=10<br>   -&gt;  Bitmap Index Scan on idx_orders_customer_id  (cost=0.00..4.53 rows=13 width=0) (actual time=0.047..0.047 rows=7.00 loops=1)<br>         Index Cond: (customer_id = 42)<br>         Index Searches: 1<br>         Buffers: shared hit=3 read=3<br> Planning:<br>   Buffers: shared hit=72 read=26<br> Planning Time: 0.912 ms<br> Execution Time: 0.515 ms<br>(12 rows)</pre><p>Sıcak (hemen ardından ikinci çalıştırma):</p><pre>QUERY PLAN<br>-----------------------------------------------------------------------------------------------------------------------------------<br> Bitmap Heap Scan on orders  (cost=4.53..55.32 rows=13 width=39) (actual time=0.011..0.014 rows=7.00 loops=1)<br>   Recheck Cond: (customer_id = 42)<br>   Heap Blocks: exact=7<br>   Buffers: shared hit=10<br>   -&gt;  Bitmap Index Scan on idx_orders_customer_id  (cost=0.00..4.53 rows=13 width=0) (actual time=0.008..0.008 rows=7.00 loops=1)<br>         Index Cond: (customer_id = 42)<br>         Index Searches: 1<br>         Buffers: shared hit=3<br> Planning:<br>   Buffers: shared hit=3<br> Planning Time: 0.024 ms<br> Execution Time: 0.018 ms<br>(12 rows)</pre><p>Aynı sorgu, aynı plan: ilk seferde 10 page dışarıdan okundu (read=10), ikinci seferde hepsi cache&#39;ten geldi (hit=10) ve süre 0.515&#39;ten 0.018 ms&#39;ye — <strong>~29 kat</strong> — düştü. (Dikkatli göz şunu da yakalar: sorgu artık 4 değil <strong>7 satır</strong> döndürüyor — Adım 4&#39;ün 150 bin iadesinden üçü 42 numaralı müşteriye denk gelmiş. Playground yaşıyor.)</p><p>Büyük sorguda aynı deney: Adım 2&#39;de sıcak cache’le 10.6 ms süren PENDING sorgusu, restart sonrası soğuk cache’te:</p><pre>QUERY PLAN<br>---------------------------------------------------------------------------------------------------------------------------------------<br> Bitmap Heap Scan on orders  (cost=231.36..11057.94 rows=20507 width=39) (actual time=1.812..16.078 rows=20130.00 loops=1)<br>   Recheck Cond: (status = &#39;PENDING&#39;::text)<br>   Heap Blocks: exact=8220<br>   Buffers: shared read=8240<br>   -&gt;  Bitmap Index Scan on idx_orders_status  (cost=0.00..226.23 rows=20507 width=0) (actual time=1.024..1.024 rows=20130.00 loops=1)<br>         Index Cond: (status = &#39;PENDING&#39;::text)<br>         Index Searches: 1<br>         Buffers: shared read=20<br> Planning:<br>   Buffers: shared hit=73 read=28<br> Planning Time: 0.259 ms<br> Execution Time: 16.707 ms<br>(12 rows)</pre><p>Aynı plan, aynı veri — Buffers: shared read=8240: bu kez 8.240 page&#39;in <strong>tamamı</strong> dışarıdan geldi ve süre 10.6&#39;dan 16.7 ms&#39;ye çıktı. Fark bu koşuda ılımlı, çünkü kritik incelik şu: read &quot;diskten geldi&quot; garantisi değildir — PostgreSQL&#39;in cache&#39;inde yoktu demektir; bu deneyde page&#39;ler işletim sisteminin hâlâ sıcak olan kendi cache&#39;inden geldi. Page&#39;lerin gerçekten diskten okunduğu bir production sabahında (deploy sonrası, failover sonrası) aynı read=8240 satırı size 16 ms değil yüzlerce ms&#39;ye mal olur. Teşhis yönü her durumda aynıdır: &quot;sorgu normalde hızlı ama arada bir katlanıyor&quot; vakasında planı suçlamadan önce Buffers&#39;a bakın — yavaş çalıştırmalarda read domine ediyorsa sorun sorguda değil, cache&#39;in o veriyi tutamamasındadır (shared_buffers boyutu, rakip iş yükü, restart sonrası soğuk başlangıç).</p><h3>work_mem: Sort’un diske taşması</h3><p>work_mem, tek bir sort ya da hash operasyonunun kullanabileceği bellek tavanıdır — varsayılan mütevazı bir 4MB. 1.15 milyon satırı sıralamayı deneyelim:</p><pre>EXPLAIN ANALYZE SELECT * FROM orders ORDER BY total_amount;</pre><pre>QUERY PLAN<br>---------------------------------------------------------------------------------------------------------------------------<br> Sort  (cost=202907.34..205814.81 rows=1162987 width=39) (actual time=386.799..452.073 rows=1150000.00 loops=1)<br>   Sort Key: total_amount<br>   Sort Method: external merge  Disk: 63536kB<br>   Buffers: shared hit=8223 read=2288, temp read=15876 written=15900<br>   -&gt;  Seq Scan on orders  (cost=0.00..22137.87 rows=1162987 width=39) (actual time=0.014..61.529 rows=1150000.00 loops=1)<br>         Buffers: shared hit=8220 read=2288<br> Planning:<br>   Buffers: shared hit=125 read=6<br> Planning Time: 0.286 ms<br> Execution Time: 475.590 ms<br>(10 rows)</pre><p>İki satır her şeyi anlatıyor. <strong>Sort Method: external merge Disk: 63536kB</strong> — veri 4MB&#39;a sığmadı, sıralama 63.5 MB&#39;lık temp dosyalar üzerinden yapıldı. <strong>temp read=15876 written=15900</strong> — Buffers satırına yeni bir bileşen eklendi: temp dosya trafiği (sözlükteki son satır). Bu ikiliyi bir planda gördüğünüzde sorgunuz diskte sıralama yapıyor demektir.</p><p>Belleği açıp tekrar:</p><pre>SET work_mem = &#39;256MB&#39;;<br>EXPLAIN ANALYZE SELECT * FROM orders ORDER BY total_amount;<br>RESET work_mem;</pre><pre>QUERY PLAN<br>---------------------------------------------------------------------------------------------------------------------------<br> Sort  (cost=139305.34..142212.81 rows=1162987 width=39) (actual time=301.457..340.237 rows=1150000.00 loops=1)<br>   Sort Key: total_amount<br>   Sort Method: quicksort  Memory: 119233kB<br>   Buffers: shared hit=8314 read=2194<br>   -&gt;  Seq Scan on orders  (cost=0.00..22137.87 rows=1162987 width=39) (actual time=0.006..50.706 rows=1150000.00 loops=1)<br>         Buffers: shared hit=8314 read=2194<br> Planning Time: 0.035 ms<br> Execution Time: 360.671 ms<br>(8 rows)</pre><p>Sıralama tamamen bellekte (119 MB kullandı), temp trafiği sıfır. Süre farkına dürüstçe bakalım: 476 → 361 ms, yani ~%24 — “10 kat hızlandı” hikayesi yok. Modern NVMe üzerinde tek bir sorgunun spill cezası çoğu zaman böyle ılımlıdır. Asıl maliyet <strong>concurrency’de</strong> ortaya çıkar: bu sorguyu aynı anda 50 oturum çalıştırırsa, her biri ~64 MB temp dosya yazar — 3 GB’lık bir temp I/O fırtınası. Ve madalyonun öbür yüzü: work_mem oturum başına değil, <strong>operasyon başına</strong>dır; karmaşık bir sorguda üç sort + iki hash varsa beş kez tahsis edilebilir. Global olarak 256MB yapmak bu yüzden tehlikelidir — doğru pratik, ihtiyacı olan sorguya/oturuma özel SET work_mem vermektir. (Adım 3&#39;teki Hash Join&#39;in Batches: 1 satırı da aynı ailedendir: batch sayısı 1&#39;in üstüne çıktıysa hash tablosu work_mem&#39;e sığmamış, diske bölünmüş demektir.)</p><h3>Planner belleği fiyatlandırır: üç perdelik bir kovalamaca</h3><p>Bu bölümün en güzel sürprizi şu deneyde çıktı. Amacım basitti: work_mem&#39;i 64kB&#39;a kısıp PENDING bitmap&#39;ini kabalaştırmak (lossy). Ama planner&#39;ın buna cevabı bir ders niteliğinde.</p><p><strong>Perde 1:</strong> SET work_mem = &#39;64kB&#39; → sorguyu çalıştırdım. Planner bitmap&#39;i <strong>terk etti</strong>, düz Index Scan&#39;e döndü. Çünkü 20 bin satırlık bir bitmap 64kB&#39;a sığmaz; planner lossy bitmap + recheck maliyetini <em>önceden hesapladı</em> ve daha ucuz bulduğu Index Scan&#39;e kaçtı:</p><pre>QUERY PLAN<br>------------------------------------------------------------------------------------------------------------------------------------------<br> Index Scan using idx_orders_status on orders  (cost=0.43..12509.82 rows=20507 width=39) (actual time=0.016..8.476 rows=20130.00 loops=1)<br>   Index Cond: (status = &#39;PENDING&#39;::text)<br>   Index Searches: 1<br>   Buffers: shared hit=8240<br> Planning:<br>   Buffers: shared hit=106<br> Planning Time: 0.181 ms<br> Execution Time: 9.037 ms<br>(8 rows)</pre><p><strong>Perde 2:</strong> SET enable_indexscan = off → bu kez <strong>Seq Scan&#39;e</strong> kaçtı. Hâlâ bitmap&#39;ten ucuzdu:</p><pre>QUERY PLAN<br>------------------------------------------------------------------------------------------------------------------------------<br> Gather  (cost=1000.00..19615.92 rows=20507 width=39) (actual time=0.132..28.786 rows=20130.00 loops=1)<br>   Workers Planned: 2<br>   Workers Launched: 2<br>   Buffers: shared hit=8408 read=2100<br>   -&gt;  Parallel Seq Scan on orders  (cost=0.00..16565.22 rows=8545 width=39) (actual time=0.041..25.983 rows=6710.00 loops=3)<br>         Filter: (status = &#39;PENDING&#39;::text)<br>         Rows Removed by Filter: 376623<br>         Buffers: shared hit=8408 read=2100<br> Planning Time: 0.030 ms<br> Execution Time: 29.309 ms<br>(10 rows)</pre><p><strong>Perde 3:</strong> SET enable_seqscan = off — bitmap dışında kapı kalmadı:</p><pre>QUERY PLAN<br>---------------------------------------------------------------------------------------------------------------------------------------------<br> Gather  (cost=1231.36..19615.99 rows=20507 width=39) (actual time=0.872..18.810 rows=20130.00 loops=1)<br>   Workers Planned: 2<br>   Workers Launched: 2<br>   Buffers: shared hit=8280<br>   -&gt;  Parallel Bitmap Heap Scan on orders  (cost=231.36..16565.29 rows=8545 width=39) (actual time=0.299..15.186 rows=6710.00 loops=3)<br>         Recheck Cond: (status = &#39;PENDING&#39;::text)<br>         Rows Removed by Index Recheck: 272126<br>         Heap Blocks: exact=211 lossy=2987<br>         Buffers: shared hit=8280<br>         Worker 0:  Heap Blocks: exact=162 lossy=2278<br>         Worker 1:  Heap Blocks: exact=115 lossy=2467<br>         -&gt;  Bitmap Index Scan on idx_orders_status  (cost=0.00..226.23 rows=20507 width=0) (actual time=0.733..0.734 rows=20130.00 loops=1)<br>               Index Cond: (status = &#39;PENDING&#39;::text)<br>               Index Searches: 1<br>               Buffers: shared hit=20<br> Planning Time: 0.061 ms<br> Execution Time: 19.242 ms<br>(17 rows)</pre><p>İşte aradığımız çıktı. <strong>Heap Blocks: exact=211 lossy=2987</strong> — bitmap belleğe sığmayınca TID tutmayı bırakıp page numarası tutmaya düştü (kabalaştı). Page bazlı bitmap &quot;bu page&#39;de eşleşme var&quot; der ama hangi satırda olduğunu bilmez; bu yüzden <strong>Rows Removed by Index Recheck: 272126</strong> — o page&#39;lerdeki 272 bin alakasız satır tek tek yeniden filtrelendi. Adım 2&#39;de &quot;beyan&quot; dediğimiz Recheck Cond satırının fiilen çalıştığı an tam olarak budur.</p><p>Bu kovalamacanın kalıcı dersi şu: <strong>plan, sorgunun olduğu kadar konfigürasyonun da fonksiyonudur.</strong> Aynı sorgu, aynı veri, aynı index — sadece work_mem değişti ve planner üç farklı plan üretti. “Dün Bitmap’ti, bugün neden Seq Scan?” sorusunun cevabı bazen ne veride ne sorgudadır; birinin dokunduğu bir ayardadır.</p><h3>Adım 6 — Kırmızı Bayrak Kataloğu</h3><p>Beş adım boyunca her sinyali yaşayarak öğrendik; şimdi hepsini tek başvuru tablosunda topluyorum. Ama önce okuma yöntemi — çünkü katalog, sırayla bakmayı bilene hizmet eder.</p><p>Bir EXPLAIN ANALYZE çıktısını elime aldığımda sıram hep aynı: <strong>Önce tahmin/gerçek farkı</strong> — her node’da rows= ile actual rows=&#39;u kıyaslarım; 10 katı aşan fark varsa başka hiçbir şeye bakmadan istatistik izine giderim, çünkü yanlış tahmin üzerine kurulmuş bir planın diğer detaylarını tartışmak anlamsızdır (Adım 4&#39;te 147 ms&#39;lik Nested Loop bunu kanıtladı). <strong>Sonra Buffers</strong> — toplam page sayısı işin gerçek bedelidir; süre yanıltır (cache sıcaklığına ve makinenin o anki haline göre kat kat oynadığını, hatta kıyasları ters çevirdiğini gördük), page sayısı yalan söylemez. <strong>Sonra loops</strong> — binlerce tekrar eden bir iç node, tek başına masum görünen değerlerin çarpanıdır. <strong>En son node tipleri</strong> — Seq/Bitmap/Nested Loop tartışması, ancak ilk üçü temizse anlamlıdır.</p><p>Bu sıralama, genel performans teşhisinin bilinen ilkesinin sorgu-içi karşılığıdır: dışarıda önce APM izine, network’e, serialization’a bakılır, sorguya en son gelinir — çünkü suçlu çoğu zaman sorgu değildir. İçeride de aynısı geçerli: suçlu çoğu zaman node tipi değil, ona yanlış bilgi taşıyan istatistik ya da onu bin kez döndüren üst plandır.</p><h3>Katalog: ne görürsün → ne demektir → nereye bakarsın → ne yaparsın</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*dYYyLrFTADL-J31o2kFW3w.png" /></figure><p>Tablonun kullanım talimatı tek cümle: <strong>belirti → teşhis → kanıt → müdahale sırasını atlama.</strong> “Seq Scan gördüm, index atayım” refleksi 5. satırın sol yarısını okuyup sağını okumamaktır — Adım 2&#39;de planner’ın Seq Scan’le nasıl haklı çıktığını, Adım 5&#39;te aynı sorguya üç farklı planı nasıl bastığını gördük. Kanıt toplamadan müdahale, tuning değil kumardır.</p><h3>Adım 7 — Vaka Çalışmaları: Production Klasikleri</h3><p>Kapanış adımı. Her vaka aynı düzende: production’da nasıl görünür, planda hangi katalog satırı yanar, müdahale ne, kazanç kaç. (Deneylerden önce VACUUM ANALYZE koştum — visibility map ve istatistikler taze.)</p><h3>Vaka 1 — lower(email) tuzağı: index var, sorgu onu göremiyor</h3><p>Adım 3&#39;te not bırakmıştık: e-posta araması 100 bin satır tarıyordu. Index’i ekledik diyelim — ve uygulama, case-insensitive arama için kolonu lower()&#39;a sarıyor. Java tarafında son derece masum görünen bir satırdır bu (WHERE lower(email) = :email):</p><pre>CREATE INDEX idx_customers_email ON customers(email);<br>EXPLAIN ANALYZE SELECT * FROM customers WHERE lower(email) = &#39;user42@example.com&#39;;</pre><pre>QUERY PLAN<br>-------------------------------------------------------------------------------------------------------------<br> Seq Scan on customers  (cost=0.00..2531.00 rows=500 width=54) (actual time=0.056..16.502 rows=1.00 loops=1)<br>   Filter: (lower(email) = &#39;user42@example.com&#39;::text)<br>   Rows Removed by Filter: 99999<br>   Buffers: shared hit=1031<br> Planning:<br>   Buffers: shared hit=40 read=1<br> Planning Time: 0.099 ms<br> Execution Time: 16.521 ms<br>(8 rows)</pre><p>Index duruyor, planner Seq Scan seçti — katalogdaki 5. satır, “sargable olmayan predicate” kolu. Sebep mekanik: index email değerlerini sıralı tutuyor, lower(email) değerlerini değil. Kolonu bir fonksiyona sardığınız anda B-tree&#39;nin sıralaması sorgunuz için anlamsızlaşır ve planner&#39;ın elinde taramaktan başka yol kalmaz. Kıyas için fonksiyonsuz aynı arama:</p><pre>EXPLAIN ANALYZE SELECT * FROM customers WHERE email = &#39;user42@example.com&#39;;</pre><pre>QUERY PLAN<br>-----------------------------------------------------------------------------------------------------------------------------------<br> Index Scan using idx_customers_email on customers  (cost=0.42..8.44 rows=1 width=54) (actual time=0.021..0.021 rows=1.00 loops=1)<br>   Index Cond: (email = &#39;user42@example.com&#39;::text)<br>   Index Searches: 1<br>   Buffers: shared hit=1 read=3<br> Planning Time: 0.031 ms<br> Execution Time: 0.027 ms<br>(6 rows)</pre><p>16.5 ms’ye karşı 0.027 ms — <strong>~610 kat fark</strong>, tek bir lower() yüzünden.</p><p>Bir detay daha: tahmin rows=500, gerçek 1. Planner fonksiyonun çıktısı hakkında istatistik tutmadığından kör bir varsayım kullandı. Yanlış tahminin neleri zehirlediğini Adım 4&#39;ten biliyorsunuz.</p><p>Çözüm iki yönlü. Ya sorguyu düzeltirsiniz (veriyi zaten normalize kaydediyorsanız lower() gereksizdir) ya da index&#39;i sorguya uydurursunuz — <strong>expression index</strong>:</p><pre>CREATE INDEX idx_customers_email_lower ON customers(lower(email));<br>EXPLAIN ANALYZE SELECT * FROM customers WHERE lower(email) = &#39;user42@example.com&#39;;</pre><pre>QUERY PLAN<br>----------------------------------------------------------------------------------------------------------------------------------------<br> Bitmap Heap Scan on customers  (cost=16.29..879.92 rows=500 width=54) (actual time=0.017..0.018 rows=1.00 loops=1)<br>   Recheck Cond: (lower(email) = &#39;user42@example.com&#39;::text)<br>   Heap Blocks: exact=1<br>   Buffers: shared hit=1 read=3<br>   -&gt;  Bitmap Index Scan on idx_customers_email_lower  (cost=0.00..16.17 rows=500 width=0) (actual time=0.013..0.013 rows=1.00 loops=1)<br>         Index Cond: (lower(email) = &#39;user42@example.com&#39;::text)<br>         Index Searches: 1<br>         Buffers: shared read=3<br> Planning:<br>   Buffers: shared hit=19 read=1<br> Planning Time: 0.082 ms<br> Execution Time: 0.025 ms<br>(12 rows)</pre><p>16.5 ms → 0.025 ms. Expression index tam olarak lower(email) çıktılarını sıralar; sorgudaki ifadeyle birebir eşleştiği için planner kullanabilir. (Ve ince bir bonus: expression index oluşturulduktan sonraki ilk ANALYZE, o ifadenin <em>kendisi için</em> istatistik toplar — rows=500 körlüğü de zamanla düzelir.) Aynı ailenin diğer üyeleri: WHERE created_at::date = ..., WHERE amount * 1.18 &gt; ..., implicit tip dönüşümleri — kolon tarafında herhangi bir hesap varsa, katalog 5&#39;i hatırlayın.</p><h3>Vaka 2 — LIKE’ın üç hali</h3><p>Arama kutusu klasiği. Prefix araması ile başlayalım:</p><pre>EXPLAIN ANALYZE SELECT * FROM customers WHERE email LIKE &#39;user4200%&#39;;</pre><pre>QUERY PLAN<br>------------------------------------------------------------------------------------------------------------<br> Seq Scan on customers  (cost=0.00..2281.00 rows=10 width=54) (actual time=0.298..5.020 rows=11.00 loops=1)<br>   Filter: (email ~~ &#39;user4200%&#39;::text)<br>   Rows Removed by Filter: 99989<br>   Buffers: shared hit=1031<br> Planning:<br>   Buffers: shared hit=97 read=2<br> Planning Time: 0.889 ms<br> Execution Time: 5.088 ms<br>(8 rows)</pre><p>Sürpriz: email index&#39;i var, prefix araması sargable olmalı — ama Seq Scan. Sebep locale: veritabanı C dışında bir collation kullanıyorsa (bizde en_US.utf8), B-tree&#39;nin sıralaması LIKE&#39;ın byte-bazlı prefix mantığıyla uyuşmaz ve planner index&#39;i kullanamaz. Çözümü PostgreSQL&#39;in kendisi sağlar — pattern operatörleri için özel operator class:</p><pre>CREATE INDEX idx_customers_email_pattern ON customers(email text_pattern_ops);<br>EXPLAIN ANALYZE SELECT * FROM customers WHERE email LIKE &#39;user4200%&#39;;</pre><pre>QUERY PLAN<br>---------------------------------------------------------------------------------------------------------------------------------------------<br> Index Scan using idx_customers_email_pattern on customers  (cost=0.42..8.44 rows=10 width=54) (actual time=0.037..0.041 rows=11.00 loops=1)<br>   Index Cond: ((email ~&gt;=~ &#39;user4200&#39;::text) AND (email ~&lt;~ &#39;user4201&#39;::text))<br>   Filter: (email ~~ &#39;user4200%&#39;::text)<br>   Index Searches: 1<br>   Buffers: shared hit=3 read=3<br> Planning:<br>   Buffers: shared hit=67 read=1<br> Planning Time: 0.283 ms<br> Execution Time: 0.061 ms<br>(9 rows)</pre><p>Index Cond satırı planner&#39;ın zekâsını gösteriyor: LIKE &#39;user4200%&#39; ifadesini &gt;= &#39;user4200&#39; AND &lt; &#39;user4201&#39; aralığına çevirdi — prefix araması aslında bir range scan&#39;miş. 5.1 ms → 0.061 ms.</p><p>Ama LIKE &#39;%4200@exam%&#39; — başında wildcard olan arama — bambaşka bir hayvandır. Hiçbir B-tree bunu karşılayamaz; prefix yoksa sıralama işe yaramaz, planner mecburen tarar:</p><pre>EXPLAIN ANALYZE SELECT * FROM customers WHERE email LIKE &#39;%4200@exam%&#39;;</pre><pre>QUERY PLAN<br>------------------------------------------------------------------------------------------------------------<br> Seq Scan on customers  (cost=0.00..2281.00 rows=10 width=54) (actual time=0.200..4.718 rows=10.00 loops=1)<br>   Filter: (email ~~ &#39;%4200@exam%&#39;::text)<br>   Rows Removed by Filter: 99990<br>   Buffers: shared hit=1031<br> Planning Time: 0.018 ms<br> Execution Time: 4.722 ms<br>(6 rows)</pre><p>Burada devreye üçlü harf gruplarıyla (trigram) çalışan pg_trgm girer:</p><pre>CREATE EXTENSION pg_trgm;<br>CREATE INDEX idx_customers_email_trgm ON customers USING gin (email gin_trgm_ops);<br>EXPLAIN ANALYZE SELECT * FROM customers WHERE email LIKE &#39;%4200@exam%&#39;;</pre><pre>QUERY PLAN<br>---------------------------------------------------------------------------------------------------------------------------------------<br> Bitmap Heap Scan on customers  (cost=69.08..106.25 rows=10 width=54) (actual time=0.651..0.661 rows=10.00 loops=1)<br>   Recheck Cond: (email ~~ &#39;%4200@exam%&#39;::text)<br>   Rows Removed by Index Recheck: 1<br>   Heap Blocks: exact=11<br>   Buffers: shared hit=130<br>   -&gt;  Bitmap Index Scan on idx_customers_email_trgm  (cost=0.00..69.08 rows=10 width=0) (actual time=0.642..0.643 rows=11.00 loops=1)<br>         Index Cond: (email ~~ &#39;%4200@exam%&#39;::text)<br>         Index Searches: 1<br>         Buffers: shared hit=119<br> Planning:<br>   Buffers: shared hit=26<br> Planning Time: 0.095 ms<br> Execution Time: 0.672 ms<br>(13 rows)</pre><p>GIN index’i, aranan deseni trigram’lara bölüp aday satırları buldu; Rows Removed by Index Recheck: 1 satırı yöntemin doğasını ele veriyor — trigram eşleşmesi <em>yaklaşıktır</em>, kesin sonuç için adaylar gerçek desene karşı yeniden kontrol edilir. Adım 2&#39;deki recheck mekanizmasının ikinci tetikleyicisi budur: lossy bitmap değil, doğası gereği aday döndüren index. 4.7 ms → 0.67 ms; ve bu fark tablo büyüdükçe açılır, çünkü Seq Scan lineer büyür, trigram araması büyümez.</p><h3>Vaka 3 — Derin OFFSET: pagination’ın gizli faturası</h3><p>“Sayfa 25.001&#39;i göster” — LIMIT 20 OFFSET 500000:</p><pre>EXPLAIN ANALYZE SELECT * FROM orders ORDER BY id LIMIT 20 OFFSET 500000;</pre><pre>QUERY PLAN<br>----------------------------------------------------------------------------------------------------------------------------------------------<br> Limit  (cost=17557.39..17558.09 rows=20 width=39) (actual time=57.775..57.778 rows=20.00 loops=1)<br>   Buffers: shared hit=4372 read=1880<br>   -&gt;  Index Scan using orders_pkey on orders  (cost=0.43..40381.44 rows=1150000 width=39) (actual time=0.082..46.945 rows=500020.00 loops=1)<br>         Index Searches: 1<br>         Buffers: shared hit=4372 read=1880<br> Planning:<br>   Buffers: shared hit=122<br> Planning Time: 0.246 ms<br> Execution Time: 57.802 ms<br>(9 rows)</pre><p>İç node’un actual rows=500020 değeri suçüstü kanıtı: OFFSET atlamaz, <strong>sayar.</strong> 20 satır döndürmek için 500.020 satır index sırasıyla yürünüp çöpe atıldı — 6.252 page erişimi. OFFSET büyüdükçe maliyet lineer artar; son sayfalara yaklaşan kullanıcı, ilk sayfadaki kullanıcının yüzlerce katı bedel ödetir.</p><p>Müdahale, sayfa numarası yerine “son görülen kayıttan devam” — <strong>keyset pagination</strong>:</p><pre>EXPLAIN ANALYZE SELECT * FROM orders WHERE id &gt; 500000 ORDER BY id LIMIT 20;</pre><pre>QUERY PLAN<br>----------------------------------------------------------------------------------------------------------------------------------------<br> Limit  (cost=0.43..1.18 rows=20 width=39) (actual time=0.019..0.021 rows=20.00 loops=1)<br>   Buffers: shared hit=7 read=1<br>   -&gt;  Index Scan using orders_pkey on orders  (cost=0.43..24385.17 rows=648156 width=39) (actual time=0.018..0.020 rows=20.00 loops=1)<br>         Index Cond: (id &gt; 500000)<br>         Index Searches: 1<br>         Buffers: shared hit=7 read=1<br> Planning:<br>   Buffers: shared hit=3<br> Planning Time: 0.100 ms<br> Execution Time: 0.027 ms<br>(10 rows)</pre><p>WHERE id &gt; :son_gorulen index&#39;e doğrudan doğru noktadan girme imkânı verdi: 500.020 satır yerine <strong>20 satır</strong>, 6.252 page yerine <strong>8 page</strong>, 57.8 ms yerine <strong>0.027 ms</strong> — kaçıncı sayfada olduğunuzdan bağımsız, sabit maliyet. Bedeli API sözleşmesinde ödersiniz: &quot;rastgele sayfaya zıpla&quot; yerine &quot;sonraki sayfa&quot; modeli. Infinite scroll&#39;lu her arayüz için zaten doğru model budur.</p><h3>Vaka 4 — Partial index: tablonun ilgilendiğiniz dilimini indexleyin</h3><p>İş kuralı şu olsun: operasyon ekranı yalnızca bekleyen siparişleri listeliyor — status = &#39;PENDING&#39; (%2&#39;lik dilim), tarihe göre. Klasik refleks (status, created_at) composite&#39;idir; oysa sorgunun tek ilgilendiği dilim belliyken tablonun %98&#39;ini indexlemek israftır:</p><pre>CREATE INDEX idx_orders_pending_created ON orders(created_at) WHERE status = &#39;PENDING&#39;;</pre><p>Boyut kıyası kendi başına makale değerinde:</p><pre>relname           |  size<br>----------------------------+---------<br> orders                     | 82 MB<br> idx_orders_status          | 7856 kB<br> idx_orders_pending_created | 456 kB</pre><p>Tüm tabloyu kapsayan status index’i 7.8 MB; partial index <strong>456 kB</strong> — 17 kat küçük, çünkü yalnızca 20 bin PENDING satırı içeriyor. Küçük index demek: daha az disk, daha hızlı arama, ve en önemlisi <strong>daha ucuz yazma</strong> — DELIVERED’a dönen her sipariş bu index’ten düşer, yeni DELIVERED’lar hiç girmez.</p><pre>EXPLAIN ANALYZE<br>SELECT * FROM orders WHERE status = &#39;PENDING&#39; AND created_at &gt; now() - interval &#39;30 days&#39;;</pre><pre>QUERY PLAN<br>--------------------------------------------------------------------------------------------------------------------------------------------<br> Bitmap Heap Scan on orders  (cost=60.79..6900.15 rows=3161 width=39) (actual time=0.084..0.676 rows=799.00 loops=1)<br>   Recheck Cond: ((created_at &gt; (now() - &#39;30 days&#39;::interval)) AND (status = &#39;PENDING&#39;::text))<br>   Heap Blocks: exact=764<br>   Buffers: shared hit=764 read=4<br>   -&gt;  Bitmap Index Scan on idx_orders_pending_created  (cost=0.00..60.00 rows=3161 width=0) (actual time=0.045..0.046 rows=799.00 loops=1)<br>         Index Cond: (created_at &gt; (now() - &#39;30 days&#39;::interval))<br>         Index Searches: 1<br>         Buffers: shared read=4<br> Planning:<br>   Buffers: shared hit=19 read=1<br> Planning Time: 0.066 ms<br> Execution Time: 0.694 ms<br>(12 rows)</pre><p>Index Cond&#39;a dikkat: yalnızca created_at — status koşulu index&#39;in <em>tanımında</em> gömülü olduğu için aramaya hiç girmiyor. Planner, sorgunun WHERE&#39;i index&#39;in WHERE&#39;ini kapsıyorsa bu index&#39;i kullanabilir; kapsamıyorsa (örneğin status = &#39;SHIPPED&#39; sorarsanız) bu index yok hükmündedir. Partial index bir söz vermektir: &quot;yalnızca bu dilimi soracağım.&quot;</p><h3>Vaka 5 — Covering index: heap ziyaretini tamamen silmek</h3><p>Adım 2&#39;den biliyorsunuz: sorgunun istediği her kolon index’teyse heap ziyareti tamamen ortadan kalkar. Ama WHERE customer_id = ? → total_amount gibi bir sorguda total_amount&#39;u aramıyoruz — sadece <em>okuyoruz</em>. Onu index&#39;in arama yapısına (key&#39;e) koymak yerine, leaf&#39;ine iliştirmenin yolu var. Önce mevcut durum:</p><pre>EXPLAIN ANALYZE SELECT customer_id, total_amount FROM orders WHERE customer_id = 42;</pre><pre>QUERY PLAN<br>-----------------------------------------------------------------------------------------------------------------------------------<br> Bitmap Heap Scan on orders  (cost=4.52..51.45 rows=12 width=14) (actual time=0.018..0.134 rows=7.00 loops=1)<br>   Recheck Cond: (customer_id = 42)<br>   Heap Blocks: exact=7<br>   Buffers: shared hit=5 read=5<br>   -&gt;  Bitmap Index Scan on idx_orders_customer_id  (cost=0.00..4.52 rows=12 width=0) (actual time=0.014..0.014 rows=7.00 loops=1)<br>         Index Cond: (customer_id = 42)<br>         Index Searches: 1<br>         Buffers: shared read=3<br> Planning:<br>   Buffers: shared hit=5<br> Planning Time: 0.017 ms<br> Execution Time: 0.138 ms<br>(12 rows)</pre><p>Şimdi covering index:</p><pre>CREATE INDEX idx_orders_customer_covering ON orders(customer_id) INCLUDE (total_amount);<br>EXPLAIN ANALYZE SELECT customer_id, total_amount FROM orders WHERE customer_id = 42;</pre><pre>QUERY PLAN<br>-----------------------------------------------------------------------------------------------------------------------------------------------<br> Index Only Scan using idx_orders_customer_covering on orders  (cost=0.43..4.64 rows=12 width=14) (actual time=0.014..0.014 rows=7.00 loops=1)<br>   Index Cond: (customer_id = 42)<br>   Heap Fetches: 0<br>   Index Searches: 1<br>   Buffers: shared hit=1 read=3<br> Planning:<br>   Buffers: shared hit=19 read=1<br> Planning Time: 0.078 ms<br> Execution Time: 0.022 ms<br>(9 rows)</pre><p>INCLUDE kolonları aramaya katılmaz, sıralamaya girmez — sadece leaf&#39;te taşınır. Sonuç: Index Only Scan, Heap Fetches: 0, 10 page yerine 4. Bu ölçekte iki sorgu da zaten mikrosaniyeler mertebesinde; covering&#39;in gerçek getirisi, key başına çok satırın döndüğü ve heap&#39;in soğuk olduğu büyük tablolarda ortaya çıkar — her heap ziyareti bir rastgele I/O&#39;yken, hepsini birden silmek plan maliyetinin belkemiğini kırar.</p><p>Kapanış uyarısı, katalogdaki 12. satırın hatırlatması: bu yazı boyunca orders&#39;a beş index biriktirdik (pkey, customer_id, status, partial, covering). Her INSERT artık <strong>beşine birden</strong> yazıyor. Index bedava değildir — okuma hızını yazma maliyetiyle satın alırsınız. Kullanılmayan index&#39;i bulmanın yolu da hazır: pg_stat_user_indexes.idx_scan sıfırda sayan index, sadece yazmayı yavaşlatan ölü ağırlıktır.</p><h3>Kapanış — Tek Cümlelik Özet</h3><p>EXPLAIN ANALYZE bir hız göstergesi değil, <strong>muhasebe defteridir</strong>: planner neye inanıyordu (rows=), gerçekte ne oldu (actual), bedeli kim ödedi (Buffers), kaç kez ödendi (loops). Bu dört soruyu sırayla soran biri, &quot;yavaş sorgu&quot; ticketlarının çoğunu index bile eklemeden kapatır — çünkü Adım 4&#39;te gördük: bazen tek gereken şey planner&#39;a gerçeği söylemek.</p><p><strong>Playground sizde:</strong> kurulum bölümündeki iki komutla aynı ortamı kendi makinenizde kurabilir, buradaki her çıktıyı yeniden üretebilirsiniz. İşiniz bitince docker rm -f pg-playground yeter.</p><p>Ve pratik bir kapanış: production’unuzda “dün hızlıydı, bugün yavaş” bir sorgu varsa, ona index eklemeden önce pg_stat_user_tables.n_mod_since_analyze değerine bir bakın. Cevap oradaysa, tamir tek kelime.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=414f342fe068" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Pratikte DDD #3 — Aggregate Root — Geçersizi Test Etmek]]></title>
            <link>https://medium.com/@gungor.akbiyik/pratikte-ddd-3-aggregate-root-ge%C3%A7ersizi-test-etmek-b0b55b14be82?source=rss-3597415c14fc------2</link>
            <guid isPermaLink="false">https://medium.com/p/b0b55b14be82</guid>
            <dc:creator><![CDATA[Güngör Akbıyık]]></dc:creator>
            <pubDate>Wed, 17 Jun 2026 05:01:01 GMT</pubDate>
            <atom:updated>2026-06-17T05:01:01.598Z</atom:updated>
            <content:encoded><![CDATA[<p><em>transfer geçersiz bir kaydı yazdırmıyor — peki “geçersizi reddediyor” testini nasıl yazdım? Encapsulation testi öldürmedi.</em></p><p>DDD öğrenirken bir core banking sistemi yazıyorum. Öğrendiklerimi yazı yazı paylaşıyorum; bu, <em>Pratikte DDD</em> serisinin üçüncü yazısı.</p><p>Hatırlatma: bir Transaction (para hareketi) en az iki LedgerEntry (satır) tutar ve borç (debit) toplamı, alacak (credit) toplamına eşit olmak zorundadır. <a href="https://medium.com/@gungor.akbiyik/pratikte-ddd-2-aggregate-root-transaction-ledgerentry-ad128fa53fab">Bir önceki yazıda</a> bu kuralı korumak için iki şey yaptım: dış dünyaya yalnızca bir niyet-factory verdim (transfer), ve satırı kuran LedgerEntry.of&#39;u dışarıya kapattım.</p><p>Sonuç: <strong>dengesiz bir transaction yazmanın yolu kalmadı.</strong></p><p>Bu yazı tam o zaferin yarattığı sorunla ilgili. Çünkü o kapıyı kapattığım an, kendi test kodumu da dışarıda bıraktım.</p><h3>İkilem: geçersizi yazamıyorsan, geçersizi nasıl test edersin?</h3><p>Aggregate’in kalbinde bir invariant var: debit = credit, en az iki satır, tek para birimi. Bunları Transaction&#39;ın içinde kontrol ediyorum; ihlal varsa IllegalArgumentException.</p><p>İyi bir test bu kontrolün gerçekten çalıştığını kanıtlamalı: “dengesiz bir liste verince patlıyor mu?” Ama dış dünyanın elindeki tek araç transfer — ve transfer <strong>her zaman</strong> dengeli, iki satırlı, tek para birimli bir transaction üretiyor. Dengesiz bir tane kurmama izin vermiyor.</p><pre>Transaction.transfer(from, to, amount);   // her zaman geçerli. Bozuk üretmek imkânsız.</pre><p>Yani testimi yazmak için, dış dünyanın yapamadığı şeyi yapabilmem lazım: kasten geçersiz bir transaction kurmaya <strong>çalışmak.</strong> Encapsulation, geçersizi üretme aracını dış dünyadan aldı — ve test kodu da dış dünyada. Aracı testin elinden de almış oldum.</p><h3>Önce yanlış cevaplar</h3><p>Üç kolay çıkış var, üçü de kötü.</p><p><strong>1. Reflection ile private constructor’a zorla girmek.</strong> Çalışır, ama testi sınıfın iç yapısına çiviler; alan adını değiştirsem test kırılır. Kırılgan, kokulu. Hayır.</p><p><strong>2. Guard’ları hiç test etmemek.</strong> “Zaten dengesiz üretilemiyor, neyi test edeyim?” Cazip ama tehlikeli. O guard’lar bugün transfer için fazlalık görünebilir; ama yarın deposit, withdrawal, çok bacaklı işlemler eklediğimde onlar son savunma hattı. Test edilmemiş bir finansal invariant, zaman bombası. Hayır.</p><p><strong>3. </strong>of(List)<strong>&#39;i public yapmak.</strong> Geçen yazıda tam da bunu reddetmiştim — public bir liste-factory, dış dünyaya LedgerEntry kurma kapısını geri açar, &quot;dengesizi yazamazsın&quot; garantisini çöpe atar. Test uğruna mimariyi bozmak. Hayır.</p><h3>Doğru cevap: paket sınırı</h3><p>Java’da görünürlüğün ikili olmadığını hatırlayın — sadece public ve private yok. Arada <strong>package-private</strong> (hiçbir erişim belirteci yazmamak) var: aynı pakettekiler görür, dışarısı görmez.</p><p>Ve Maven/Gradle’ın standart yerleşiminde test sınıfı, ayrı bir kaynak kökünde (src/test/java) ama <strong>aynı paket adıyla</strong> durur. Derlendiğinde test, sınıfla aynı pakettedir:</p><p>java</p><pre>// src/main/java/.../domain/ledger/Transaction.java<br>package com.gungor.corebanking.domain.ledger;<br><br>// src/test/java/.../domain/ledger/TransactionTest.java<br>package com.gungor.corebanking.domain.ledger;   // aynı paket</pre><p>Demek ki ihtiyacım olan kapı, dışarıya kapalı ama teste açık olabilir. Transaction&#39;a package-private bir of(List) koydum:</p><p>java</p><pre>static Transaction of(List&lt;LedgerEntry&gt; entries) {   // public değil — package-private<br>    return new Transaction(TransactionId.newId(), entries, Instant.now());<br>}</pre><p>transfer bunu içeriden çağırıyor (dengeli çifti kurup veriyor). Dış dünya of&#39;u <strong>göremiyor</strong> — yani &quot;dengesizi yazamazsın&quot; garantisi bozulmadı. Ama aynı paketteki test <strong>görüyor</strong>, ve kasten bozuk listeler verebiliyor:</p><p>java</p><pre>@Test<br>void of_throws_whenUnbalanced() {<br>   assertThatIllegalArgumentException().isThrownBy(() -&gt; Transaction.of(List.of(<br>     entry(Direction.DEBIT, &quot;100.00&quot;, TRY),<br>     entry(Direction.CREDIT, &quot;90.00&quot;, TRY)))<br>    ); // debit ≠ credit<br>}<br>@Test<br>void of_throws_whenMixedCurrency() {<br> assertThatIllegalArgumentException().isThrownBy(() -&gt; Transaction.of(List.of(<br>   entry(Direction.DEBIT, &quot;100.00&quot;, TRY),<br>   entry(Direction.CREDIT, &quot;100.00&quot;, USD)))<br>  ); // iki para birimi<br>}<br>@Test<br>void of_throws_whenFewerThanTwoEntries() {<br> assertThatIllegalArgumentException().isThrownBy(() -&gt; Transaction.of(List.of(<br>   entry(Direction.DEBIT, &quot;100.00&quot;, TRY)))); // tek satır<br>}</pre><p>(entry(...) buradaki küçük bir test yardımcısı — verilen yön ve tutarda bir LedgerEntry üretir.)</p><p>İnvariant’ın her dalını artık tetikleyebiliyorum — çünkü test, dış dünyanın giremediği paketin içinden konuşuyor.</p><h3>İki kapı, iki sorumluluk</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/579/1*p4lPnoLrhv_6OZ7pplWY4g.png" /></figure><p>Test stratejisi böylece ikiye ayrıldı, ve bu ayrım hoşuma gidiyor:</p><ul><li><strong>Public kapı (</strong>transfer<strong>) → davranışı test eder.</strong> &quot;Doğru kullanım doğru sonucu veriyor mu?&quot; — iki satır üretiliyor mu, from borçlanıp to alacaklanıyor mu, tutarlar doğru mu.</li><li><strong>Package-private kapı (</strong>of<strong>) → invariant&#39;ı test eder.</strong> &quot;Yanlış kurulum reddediliyor mu?&quot; — dengesiz, çok para birimli, tek satır.</li></ul><p>Dış dünyanın gördüğü yüzeyi (transfer) onun göreceği gibi test ediyorum; koruduğum kuralları ise içeriden, onları gerçekten zorlayabildiğim yerden.</p><h3>“Bu, test için mimariye taviz değil mi?”</h3><p>Haklı bir itiraz: test ihtiyacı yüzünden bir metot eklemek, “test-induced design damage” olabilir. Burada neden değil:</p><p>of(List) dışarıya <strong>kapalı</strong> — encapsulation&#39;ın dış dünyaya verdiği söz hiç bozulmadı; dengesizi yazamazsın, hâlâ geçerli. Test, sınıfın <em>mahremiyetine</em> (private alanlarına) değil, aggregate&#39;in kendi <strong>güven bölgesine</strong> — paketine — erişiyor. O paket zaten Transaction ve LedgerEntry&#39;nin birlikte yaşadığı, birbirine güvendiği yer. Üstelik of(List) uydurma bir test kancası değil: ileride çok bacaklı işlemler için zaten ihtiyaç duyacağım meşru bir dahili API; test onu erken ortaya çıkardı, o kadar.</p><p>Yani encapsulation ile test edilebilirlik birbirinin düşmanı değil. Çatışıyormuş gibi göründüklerinde, çözüm çoğu zaman public/private arasında unuttuğumuz o üçüncü seviyede: <strong>doğru görünürlüğü seçmek.</strong></p><p><em>Sonraki adım: şimdiye kadar her şey bellekteydi. Bu aggregate’i veritabanından geri yükleyince — aynı kimlik, farklı alanlar — hâlâ “aynı” transaction mı? Entity ile Value Object arasındaki farkın asıl sınavı orada.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=b0b55b14be82" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Pratikte DDD #2 — Aggregate Root — Transaction & LedgerEntry]]></title>
            <link>https://medium.com/@gungor.akbiyik/pratikte-ddd-2-aggregate-root-transaction-ledgerentry-ad128fa53fab?source=rss-3597415c14fc------2</link>
            <guid isPermaLink="false">https://medium.com/p/ad128fa53fab</guid>
            <dc:creator><![CDATA[Güngör Akbıyık]]></dc:creator>
            <pubDate>Tue, 16 Jun 2026 04:30:46 GMT</pubDate>
            <atom:updated>2026-06-16T04:30:46.238Z</atom:updated>
            <content:encoded><![CDATA[<p><em>addEntry’yi yazmadığım için memnunum — geçersiz bir kaydı yazmanın yolu olmamalı.</em></p><p>DDD öğrenirken bir core banking sistemi yazıyorum. Öğrendiklerimi yazı yazı paylaşıyorum; bu, <em>Pratikte DDD</em> serisinin ikinci yazısı.</p><p>Önce kısa bir hatırlatma. Üç kavramla çalışıyorum: <strong>Account</strong> (bir hesap — kimliği olan, durumu zamanla değişen bir nesne), <strong>Transaction</strong> (bir para hareketi) ve <strong>LedgerEntry</strong> (o hareketin tek bir satırı: hangi hesap, ne kadar, borç mu alacak mı). Bu yazı son ikisine odaklanıyor.</p><p>Bu bölümde Transaction ile LedgerEntry’yi çift girişli muhasebe (double-entry) anlamıyla tanımlayacağım, sonra onları kodlarken durup düşündüğüm bir karara geleceğim: <strong>bir aggregate’i nasıl kurarsın ki geçersiz hâli hiç var olamasın.</strong></p><h3>Çift girişli muhasebe, iki cümlede</h3><p>Her para hareketi en az iki satırdır ve <strong>borç (debit) toplamı, alacak (credit) toplamına eşit olmak zorundadır.</strong> 100 lira bir hesaptan çıkıyorsa, bir yere 100 lira girmeli. Bu kural tutmazsa sistem para yaratmış ya da yok etmiş olur. Bakiyeyi de hiçbir yerde saklamıyorum — onu bu satırların toplamından türetiyorum. Tek doğruluk kaynağı, satırların kendisi.</p><h3>Bu kuralı kim tutuyor?</h3><p>Soruyu tersten sorayım: “debit = credit” kuralını hangi nesne tutuyor? Tek bir LedgerEntry tutamaz — bir satır kendi başına denge bilmez; o sadece &quot;şu hesap, şu kadar, şu yön&quot; der. Kural ancak bir hareketin <strong>bütün</strong> satırları bir arada görüldüğünde anlam kazanır.</p><p>İşte o bütünü tutan, kuralı koruyan nesneye <strong>aggregate root</strong> diyoruz: Transaction. LedgerEntry ise onun içinde yaşayan bir parça.</p><p>DDD’yi tek cümlede özetleyen şey de bu: <strong>aggregate, bir invariant’ın etrafına çizilir.</strong> Sınırı nereye çizeceğini sana invariant söyler. Burada invariant “debit = credit” olduğu için sınır, bir hareketin tüm satırlarını saran Transaction&#39;dır. Bunu aklında tut — birazdan bütün kararlar buradan akacak.</p><p>DDD öğrenirken bir core banking sistemi yazıyorum. Öğrendiklerimi yazı yazı paylaşıyorum; bu, <em>Pratikte DDD</em> serisinin ikinci yazısı.</p><p>Önce kısa bir hatırlatma. Üç kavramla çalışıyorum: <strong>Account</strong> (bir hesap — kimliği olan, durumu zamanla değişen bir nesne), <strong>Transaction</strong> (bir para hareketi) ve <strong>LedgerEntry</strong> (o hareketin tek bir satırı: hangi hesap, ne kadar, borç mu alacak mı). Bu yazı son ikisine odaklanıyor.</p><p>Bu bölümde Transaction ile LedgerEntry’yi çift girişli muhasebe (double-entry) anlamıyla tanımlayacağım, sonra onları kodlarken durup düşündüğüm bir karara geleceğim: <strong>bir aggregate’i nasıl kurarsın ki geçersiz hâli hiç var olamasın.</strong></p><h3>Çift girişli muhasebe, iki cümlede</h3><p>Her para hareketi en az iki satırdır ve <strong>borç (debit) toplamı, alacak (credit) toplamına eşit olmak zorundadır.</strong> 100 lira bir hesaptan çıkıyorsa, bir yere 100 lira girmeli. Bu kural tutmazsa sistem para yaratmış ya da yok etmiş olur. Bakiyeyi de hiçbir yerde saklamıyorum — onu bu satırların toplamından türetiyorum. Tek doğruluk kaynağı, satırların kendisi.</p><h3>Bu kuralı kim tutuyor?</h3><p>Soruyu tersten sorayım: “debit = credit” kuralını hangi nesne tutuyor? Tek bir LedgerEntry tutamaz — bir satır kendi başına denge bilmez; o sadece &quot;şu hesap, şu kadar, şu yön&quot; der. Kural ancak bir hareketin <strong>bütün</strong> satırları bir arada görüldüğünde anlam kazanır.</p><p>İşte o bütünü tutan, kuralı koruyan nesneye <strong>aggregate root</strong> diyoruz: Transaction. LedgerEntry ise onun içinde yaşayan bir parça.</p><p>DDD’yi tek cümlede özetleyen şey de bu: <strong>aggregate, bir invariant’ın etrafına çizilir.</strong> Sınırı nereye çizeceğini sana invariant söyler. Burada invariant “debit = credit” olduğu için sınır, bir hareketin tüm satırlarını saran Transaction&#39;dır. Bunu aklında tut — birazdan bütün kararlar buradan akacak.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/814/1*6LUcd-eJMZBObqc_bLYnYw.png" /></figure><h3>addEntry’yi neredeyse yazıyordum</h3><p>Transaction içinde bir LedgerEntry listesi tutuyor. Doğal refleksle düşündüm: satırları tek tek eklerim.</p><p>java</p><pre>Transaction tx = new Transaction();<br>tx.addEntry(fromAccount, amount, DEBIT);<br>tx.addEntry(toAccount, amount, CREDIT);</pre><p>Tanıdık geldi, değil mi? Parmağım klavyedeyken durdum. Şu satıra bakın:</p><pre>tx.addEntry(fromAccount, amount, DEBIT);   // tek satır eklendi</pre><p>Bu satırdan sonra, ikinci addEntry&#39;den önce, tx <strong>dengesizdir.</strong> İçinde 100 liralık bir borç var, karşılığı yok. Yani nesnem, hayatının bir anında, korumaya yemin ettiğim invariant&#39;ı ihlal eden bir durumda duruyor.</p><p>addEntry olduğu sürece bu kaçınılmaz, çünkü addEntry bir <strong>değiştirme</strong> (mutation) — nesneyi adım adım, geçersiz ara durumlardan geçirerek kuruyor. Oysa bir muhasebe kaydı atomiktir; &quot;yarım transaction&quot; diye bir şey yoktur.</p><p>Fark ettiğim şey şuydu: <strong>bir aggregate’i <em>kurmak</em> (construction) ile onu <em>değiştirmek</em> (mutation) aynı şey değil.</strong> Transaction dengeli <strong>doğmalı</strong> — ya da hiç doğmamalı.</p><p>java</p><pre>// satırlar topluca, tek seferde verilir; nesne ya geçerli doğar ya hiç<br>Transaction tx = Transaction.of(List.of(debit, credit));</pre><p>of içinde dengeyi bir kez kontrol ediyorum; geçmezse istisna. Geçerse nesne donuyor — listesi List.copyOf ile değiştirilemez hâle geliyor. addEntry yok, dengesiz ara durum yok.</p><h3>Peki bu satırları kim kuruyor?</h3><p>Daha sinsi bir sorun vardı. Yukarıdaki kod LedgerEntry&#39;leri <strong>dışarıda</strong> kuruyor:</p><pre>LedgerEntry debit  = LedgerEntry.of(from, amount, DEBIT);<br>LedgerEntry credit = LedgerEntry.of(to,   amount, CREDIT);<br>Transaction tx = Transaction.of(List.of(debit, credit));</pre><p>Az önce dedik ki LedgerEntry, Transaction&#39;ın sınırı içinde yaşar. Tek başına bir anlamı yok — daima dengeli bir hareketin satırıdır. Ama bu kod, onu sınırın <strong>dışında</strong> kurup içeri elden veriyor.</p><p>Aggregate root’un kuralı tam buna karşı: dış dünya iç parçaya doğrudan dokunamaz. Ders kitabı örneği Order ve OrderLine&#39;dır. Şunu yapmazsınız:</p><pre>OrderLine line = new OrderLine(product, qty);  // iç parçayı dışarıda kurmak<br>order.getLines().add(line);                     // root&#39;u atlamak</pre><p>Şunu yaparsınız:</p><pre>order.addLine(product, qty);   // root, satırı kendi kurar ve kuralını korur</pre><p>OrderLine&#39;ı Order doğurur. Bense LedgerEntry&#39;yi dışarıda kurup elden veriyordum — &quot;aggregate root tek giriş noktasıdır&quot; diyordum ama kendi koduma bir arka kapı bırakmıştım.</p><h3>Niyet-factory</h3><p>Çözüm, dış dünyaya LedgerEntry&#39;yi hiç göstermemekti. Dış dünya onun ne olduğunu bilmemeli; sadece <strong>ne yapmak istediğini</strong> söylemeli: &quot;şu hesaptan şu hesaba şu kadar.&quot;</p><pre>public static Transaction transfer(AccountId from, AccountId to, Money amount) {<br>    LedgerEntry debit  = LedgerEntry.of(from, amount, Direction.DEBIT);<br>    LedgerEntry credit = LedgerEntry.of(to,   amount, Direction.CREDIT);<br>    return of(List.of(debit, credit));<br>}</pre><p>Bu bir <strong>niyet-factory</strong> (intention-revealing static factory method) — adı, mekaniği değil amacı söyler. Ve LedgerEntry.of&#39;u <strong>package-private</strong> yaptım; artık sadece kendi paketindeki Transaction çağırabiliyor, dışarıdaki hiçbir kod kuramıyor:</p><pre>static LedgerEntry of(AccountId accountId, Money amount, Direction direction) { ... }</pre><p>Dış dünyanın gördüğü tek şey artık Transaction.transfer(...). Debit/credit mekaniği root&#39;un içinde saklı.</p><h3>Ödül: yazılamayan hata</h3><p>Asıl kazanç burada. transfer her zaman, kaçınılmaz olarak, dengeli bir çift üretir. Yani:</p><blockquote><em>Dengesiz bir muhasebe kaydını </em><strong><em>yazmanın yolu yok.</em></strong></blockquote><p>Geçersiz durumu kontrol edip reddetmiyorum sadece — geçersiz durumu ifade etmenin <strong>dilini ortadan kaldırıyorum.</strong> <em>Make illegal states unrepresentable.</em></p><p>Başa dönelim: aggregate, bir invariant’ın etrafına çizilir demiştik. O sınırın asıl işi bir veri kabı olmak değil; geçersiz bir gerçekliğin sisteme girebileceği kapıları tek tek kapatmak. addEntry o kapıları ardına kadar açıyordu. Onu yazmadığım için memnunum.</p><p><em>Bir sonraki yazıda bir ikilem var: bu kadar kapattıktan sonra invariant’ı nasıl test ediyorum? “Geçersiz bir transaction yazılamıyorsa”, onu deneyen test de yazılamıyor gibi görünüyor.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ad128fa53fab" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>