Performance Budget Aşıldığında Otomatik Uyarı Nasıl Kurulur?

Performance budget izleme ne zaman işe yarar, ne zaman gereksizdir?

Bütçe izleme, her projeye aynı faydayı sağlamaz. Tek geliştirici tarafından yönetilen küçük bir statik site için CI entegrasyonu, kazandırdığından fazla zaman harcatabilir. Ama birden fazla geliştirici tarafından beslenen, sık deployment alan bir projede bütçe otomasyonu, regresyonu yakalayan temel güvenlik ağına dönüşür.

En çok değer ürettiği durumlar şunlardır: ekibin birden fazla özelliği paralel geliştirdiği ortamlarda, üçüncü taraf script veya paket ekleme sıklığının yüksek olduğu projelerde ve sayfa yüklenme hızının doğrudan dönüşüme etki ettiği e-ticaret gibi bağlamlarda. Ters etki yapabileceği durum ise eşiklerin, gerçek hedeflere göre değil mevcut projenin anlık durumuna göre belirlenmesidir: bu yaklaşım, var olan sorunları meşrulaştıran bir bütçe yaratır.

Bütçe kurulmadan önce temel metrikler ölçülmeli ve hedef kitle ile içerik yapısına uygun eşikler seçilmelidir. Örneğin mobil ağırlıklı bir kitleye sahip haber sitesinin JavaScript bütçesi, masaüstü odaklı bir SaaS uygulamasından çok daha düşük tutulabilir. Aylık site hızı takibi nasıl kurulur sorusuna verilen yanıtlar, bu temel ölçüm adımlarını netleştirir ve bütçe eşiklerini gerçek verilere dayandırmak için iyi bir başlangıç noktası sunar.

Lighthouse CI nedir ve projeye nasıl eklenir?

Lighthouse CI, Lighthouse aracını CI/CD pipeline'larında çalıştırmak için tasarlanmış bir komut satırı aracıdır. Her commit ya da pull request'te Lighthouse analizi yaparak performans, erişilebilirlik ve SEO metriklerini raporlar; tanımladığınız bütçe kurallarına göre geçer ya da başarısız sayılır.

Kurulum için Node.js ortamı yeterlidir:

npm install -g @lhci/cli

Projenin kök dizinine bir .lighthouserc.js veya lighthouserc.json dosyası ekleyerek yapılandırma tamamlanır. Bu dosya, hangi URL'lerin analiz edileceğini, kaç çalıştırma yapılacağını ve hangi assert kurallarının uygulanacağını belirtir.

Lighthouse CI'ın üretim ortamına ihtiyaç duymadığını belirtmek gerekir: yerel bir geliştirme sunucusu ya da staging ortamı üzerinde çalışabilir. autorun komutu, sunucuyu başlatıp analizi yapıp ardından kapatacak şekilde yapılandırılabilir. Bu esneklik, statik sitelerden sunucu taraflı render eden uygulamalara kadar geniş bir kullanım aralığı sunar. Tek bir sayfayı değil, kritik birkaç sayfayı birden analiz etmek istiyorsanız yapılandırma dosyasına birden fazla URL ekleyebilirsiniz; Lighthouse CI her birini sırayla çalıştırır ve tüm assert sonuçlarını birleştirir.

lighthouserc dosyasıyla bütçe kuralları tanımlamak

Bütçe kuralları, yapılandırma dosyasının assert bölümünde tanımlanır. İki ayrı kural mekanizması vardır: önceden tanımlanmış preset'ler ve elle yazılan assert kuralları.

Preset kullanmak hızlı bir başlangıç noktasıdır; ama genellikle kendi projenizin önceliklerine göre özelleştirme şarttır:

{
  "ci": {
    "collect": {
      "url": ["http://localhost:3000", "http://localhost:3000/urunler"],
      "numberOfRuns": 3
    },
    "assert": {
      "preset": "lighthouse:recommended",
      "assertions": {
        "first-contentful-paint": ["error", { "maxNumericValue": 2000 }],
        "largest-contentful-paint": ["error", { "maxNumericValue": 2500 }],
        "cumulative-layout-shift": ["error", { "maxNumericValue": 0.1 }],
        "interactive": ["warn", { "maxNumericValue": 5000 }],
        "total-byte-weight": ["warn", { "maxNumericValue": 512000 }]
      }
    }
  }
}

error seviyesi CI'ın başarısız sayılması anlamına gelir. warn ise geçer ama log'a uyarı düşer. Hangi metriğin hangi seviyeyle işaretleneceği, ekibin geliştirme sürecini ne ölçüde kısıtlamak istediğine bağlıdır. LCP ve CLS gibi kullanıcı deneyimini doğrudan etkileyen metrikler genellikle error seviyesinde tutulur; toplam byte ağırlığı gibi dolaylı metrikler ise warn ile başlayıp zamanla sıkılaştırılabilir.

Sayı bazlı eşikler milisaniye cinsindendir: maxNumericValue: 2500, 2.5 saniyelik LCP sınırına karşılık gelir. CLS için bu değer 0 ile 1 arasında ondalık sayıdır. numberOfRuns: 3 ayarı, tek ölçümün tesadüfi dalgalanmalardan etkilenmesini azaltmak için analizi üç kez yapıp ortalamasını alır.

GitHub Actions iş akışını kurmak

GitHub Actions ile Lighthouse CI'ı entegre etmek için .github/workflows dizinine bir YAML dosyası eklenir. Temel bir iş akışı şöyle görünür:

name: Lighthouse CI
on: [push, pull_request]

jobs:
  lhci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - run: npm run build
      - name: Run Lighthouse CI
        run: |
          npm install -g @lhci/cli
          lhci autorun
        env:
          LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}

LHCI_GITHUB_APP_TOKEN olmadan da çalışır; ancak bu token, PR'a doğrudan durum bildirimi (status check) eklemek için gereklidir. Token olmadan sonuçlar yalnızca Actions logunda görünür ve PR üzerinde görsel bir gösterge oluşmaz. Token almak için GitHub Marketplace'teki Lighthouse CI uygulaması kurulur ve repo'ya yetki verilir.

lhci autorun komutu yapılandırma dosyasını okuyarak sunucuyu başlatır, analizleri yapar ve assert kurallarını uygular. Kural ihlali olduğunda adım başarısız sayılır; branch koruma kuralları aktifse bu ihlal PR'ın birleştirilmesini doğrudan engeller. Next.js gibi framework'lerde build çıktısı farklı bir dizinde oluşabileceğinden staticDistDir yapılandırması .lighthouserc.js dosyasına eklenir. Next.js projelerinde performans darboğazı nasıl bulunur konusunda bu yapılandırma ayrıntılarına yer verilmiştir.

Bundle boyutunu CI'da ayrıca kontrol etmek

Lighthouse, toplam kaynak boyutunu genel olarak raporlar; ama JavaScript bundle'ını dosya bazında izlemek için ayrı bir araç kullanmak daha etkilidir. size-limit, her dosya için bağımsız eşik tanımlamanıza ve hangi dosyanın ne kadar yer kapladığını net biçimde görmenize olanak tanır.

npm install --save-dev @size-limit/preset-small-lib

package.json dosyasına kural ekleme:

{
  "size-limit": [
    {
      "path": "./dist/main.js",
      "limit": "150 KB"
    },
    {
      "path": "./dist/vendor.js",
      "limit": "200 KB"
    }
  ]
}

GitHub Actions iş akışına bu adım eklenir:

- name: Check bundle size
  run: npx size-limit

Tanımlanan boyut sınırı aşıldığında CI başarısız sayılır ve her yeni paket eklentisi otomatik olarak denetlenir. Birden fazla dosya tanımlamak, hangi chunk'ın büyüdüğünü anlamak açısından değerlidir: genel toplamdan ziyade spesifik dosya bazlı eşikler, sorumluluğu netleştirir.

Ters etki yapabileceği durum şudur: meşru bir özellik geliştirmesi ciddi bir bundle artışı gerektiriyorsa, limit güncellenmeden CI sürekli başarısız sayılır. Bu durumda limiti bilinçli ve açıkça güncellemek, otomasyonu kör bir engel olarak değil bilgi kaynağı olarak kullanmak demektir. Limiti kimse fark etmeden gevşetmek yerine PR açıklamasında "bundle limiti şu nedenden artırıldı" şeklinde not düşmek, izleme sürecinin değerini korur.

Slack webhook ile bildirim göndermek

CI başarısız sayıldığında bu bilginin Actions logunda kalması ekip içinde yeterli olmayabilir. Özellikle asenkron çalışan takımlarda bir iletişim kanalına bildirim göndermek, müdahale süresini kısaltır. Bildirim kanalı olarak Slack yaygın tercih olmakla birlikte aynı yaklaşım Discord veya e-posta için de uygulanabilir.

Slack webhook kurmak için Slack uygulaması yönetim panelinden Incoming Webhooks aktif edilir ve bir webhook URL'si oluşturulur. Bu URL, GitHub repository'sine secret olarak eklenir:

SLACK_WEBHOOK_URL: https://hooks.slack.com/services/T.../B.../...

İş akışına bildirim adımı:

- name: Notify Slack on failure
  if: failure()
  uses: slackapi/[email protected]
  with:
    payload: |
      {
        "text": ":warning: Performans bütçesi aşıldı",
        "blocks": [
          {
            "type": "section",
            "text": {
              "type": "mrkdwn",
              "text": "*${{ github.repository }}* - `${{ github.ref_name }}`\nCommit: ${{ github.sha }}"
            }
          }
        ]
      }
  env:
    SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}

if: failure() koşulu, yalnızca önceki adım başarısız olduğunda tetiklenmesini sağlar. Başarılı build'lerde bildirim gitmez; kanal gereksiz mesajlarla dolmaz. github.sha ve github.ref_name gibi bağlam değişkenleri, bildirimi hangi commit'in tetiklediğini anında anlamayı sağlar; böylece log'a bakma adımı atlınabilir.

Daha ayrıntılı bildirimler için hangi assert kuralının kırıldığını da mesaja eklemek mümkündür; Lighthouse CI çıktısını parse edip JSON formatında bir özet oluşturan özel bir script bu amaçla kullanılabilir. Ama bu derinliğe ihtiyaç duyulmadan önce temel entegrasyonun doğru çalıştığını doğrulamak önce gelir.

PR'ı engellemek mi, yalnızca uyarmak mı?

Her bütçe aşımını engelleyici hata olarak tanımlamak cazip görünür, ama pratikte bu yaklaşım sürtünme yaratabilir. Geliştirici deneyimi olumsuz etkilenirse ekip, bütçe kurallarını devre dışı bırakmaya ya da eşikleri gerçeği yansıtmayan biçimde gevşetmeye yönelir; bu da sistemin amacını tersine çevirir.

Yeterli. İkili bir strateji daha işlevsel sonuç verir.

LCP ve CLS gibi kullanıcı deneyimi açısından kritik metrikler error seviyesinde tutulur ve PR'ın birleştirilmesini engeller. JavaScript toplam boyutu veya Time to Interactive (TTI) gibi bağlama göre yorumlanan metrikler warn seviyesinde bırakılır; CI geçer ama Slack bildirimi gider ve ekip konuyu tartışır. Bu ayrım, neyin mutlak sınır, neyin hedef olduğunu netleştirir.

Zaman içinde kuralları gözden geçirmek de gereklidir. Başlangıçta warn olan bir kural, ekip o metriği yeterince iyileştirdikten sonra error'a taşınabilir. Meşru bir yeni özellik kalıcı bir bundle artışı gerektiriyorsa limiti kasıtlı ve belgelenmiş biçimde güncellemek, şeffaflığı korur. Performans sorununda neye önce bakılır sorusuna verilen yanıt, bütçe ihlali geldiğinde hangi metriğin önce ele alınacağını belirlemek için de rehberlik eder.

Branch koruma kuralları aktif edildiğinde, bütçe ihlali içeren bir branch'in doğrudan main'e birleştirilmesi teknik olarak mümkün olmaz. Ama admin yetkisine sahip biri kuralı atlayabilir; bu durum bilinçli bir karar gibi görünse de iz bırakır ve ekip içi farkındalığı yüksek tutar.