perfcheck

Documentation

Overview

Package perfcheck — performans bütçesinin SAF çekirdeği (v0.10.116, docs/perf/perf-budget-2026-08-28.md AŞAMA 3).

cmd/perfcheck ölçer (HTTP + httptrace), bu paket karar verir: yüzdelik, bütçe eşiği, önceki koşuyla kıyas, veri-seti sapması. Ağ YOK, saat YOK — her karar tablo-testli. Aynı JSON şekli hem çıktı hem kıyas girdisidir, yani "önceki koşu" = bir önceki çıktı dosyası.

Karar kuralı (operatör onaylı, 2026-08-28):

• karar MEDYAN üzerinden (p95 bilgi amaçlı — 5 koşuda p95 = max, gürültüyü ölçer, bütçeyi değil);
• FAIL = medyan ulaşılabilir eşiği aşıyor VE (önceki koşu yok YA DA önceki medyana göre +tolerans% üstünde) — yani hem "yavaş" hem "daha da yavaşladı";
• WARN = ikisinden yalnız biri;
• veri-seti (24h span sayısı) önceki koşudan %drift'ten çok sapmışsa kıyas UYARIya düşer, fail üretmez — farklı veriyle kıyas yalan söyler.

Index

• func DatasetDriftPct(cur, prev Dataset) float64
• func IndexPrev(prev *Report) map[string]Result
• func Lines(rep Report) []string
• func Percentile(sorted []float64, p float64) float64
• func ValidateCold(samples []Sample, expectBypass bool) (string, string)
• type Budget
• type Dataset
• type Point
  • func (p Point) Key() string
• type Report
• type Result
  • func Evaluate(r Result, prev *Result, rules Rules, driftWarn bool) Result
  • func (r Result) Key() string
• type Rules
• type Sample
• type Stats
  • func Summarize(ttfbMs []float64) Stats
• type Summary
  • func Tally(points []Result) Summary

Functions

func DatasetDriftPct

func DatasetDriftPct(cur, prev Dataset) float64

DatasetDriftPct — 24h span sayısının önceki koşuya göre mutlak sapma yüzdesi; önceki bilinmiyorsa 0.

func IndexPrev

func IndexPrev(prev *Report) map[string]Result

IndexPrev — önceki raporun noktalarını kimliğe göre indeksler.

func Lines

func Lines(rep Report) []string

Lines — terminal özeti: nokta başına tek satır, insan okur.

func Percentile

func Percentile(sorted []float64, p float64) float64

Percentile — SIRALI dilimde nearest-rank yüzdelik. p ∈ (0,100].

func ValidateCold

func ValidateCold(samples []Sample, expectBypass bool) (string, string)

ValidateCold — soğuk koşu sözleşmesi: her örnek 2xx ve X-Cache BYPASS (serveCached'siz uçlarda X-Cache yok — boş kabul). Bozuksa (status, gerekçe) ile invalid.

Types

type Budget

type Budget struct {
	AchievableMs   float64 `json:"achievableMs"`
	AspirationalMs float64 `json:"aspirationalMs,omitempty"`
	// MaxBytes — gövde boyutu tavanı (0 = yok); dashboard bundle gibi
	// "hızlı ama 1,7 MB" noktaları için.
	MaxBytes int64 `json:"maxBytes,omitempty"`
}

Budget — bir ölçüm noktasının eşikleri (ms; 0 = eşik yok).

type Dataset

type Dataset struct {
	Spans24h int64  `json:"spans24h"`
	Services int    `json:"services"`
	Version  string `json:"version"`
}

Dataset — ölçüm anındaki veri-seti parmak izi.

type Point

type Point struct {
	Name     string `json:"name"`
	Scenario string `json:"scenario"`
	Method   string `json:"method,omitempty"` // boş = GET
	// Path — sorgu dizisi dahil; {from} {to} (ns), {service}, {traceIds}
	// yer tutucuları cmd tarafında doldurulur.
	Path string `json:"path"`
	// Window — {from}/{to} için pencere ("1h", "6h", "24h").
	Window string `json:"window,omitempty"`
	// BodyFromDashboard — POST gövdesi bu dashboard'un panellerinden
	// kurulur (cmd tarafı); boş = gövdesiz.
	BodyFromDashboard string `json:"bodyFromDashboard,omitempty"`
	// Cold — refresh=1 ile soğuk yol (X-Cache BYPASS beklenir).
	Cold   bool   `json:"cold"`
	Budget Budget `json:"budget"`
	Note   string `json:"note,omitempty"`
}

Point — budget.json'daki bir ölçüm noktası. Name = self-telemetry span adı (`GET /api/traces`) — spanmetrics_1m.name ile AYNI yazım, prod p95'iyle aynı tabloda kıyaslanabilsin. Scenario = senaryo eki.

func (Point) Key

func (p Point) Key() string

Key — bir noktanın kimliği (kıyas eşlemesi için).

type Report

type Report struct {
	Schema    int      `json:"schema"`
	StartedAt string   `json:"startedAt"`
	BaseURL   string   `json:"baseUrl"`
	Runs      int      `json:"runs"`
	Dataset   Dataset  `json:"dataset"`
	Points    []Result `json:"points"`
	Summary   Summary  `json:"summary"`
	Notes     []string `json:"notes,omitempty"`
}

Report — çıktı dosyasının tamamı.

type Result

type Result struct {
	Name     string   `json:"name"`
	Scenario string   `json:"scenario"`
	Cold     Stats    `json:"cold"`
	Warm     *Stats   `json:"warm,omitempty"`
	Bytes    int64    `json:"bytes"`
	XCache   []string `json:"xcache,omitempty"`
	Budget   Budget   `json:"budget"`
	Status   string   `json:"status"` // pass | warn | fail | invalid
	Reason   string   `json:"reason,omitempty"`
	DeltaPct *float64 `json:"deltaPct,omitempty"` // önceki koşuya göre soğuk p50 farkı
	Samples  []Sample `json:"samples,omitempty"`
}

Result — bir noktanın sonucu (çıktı JSON'unun `points[]` öğesi).

func Evaluate

func Evaluate(r Result, prev *Result, rules Rules, driftWarn bool) Result

Evaluate — bir noktanın kararı. prev nil = ilk koşu (kıyas yok). driftWarn=true → kıyas güvenilmez: fail yerine warn, gerekçede yazar.

Karar tablosu:

geçerli değil (soğuk koşuda BYPASS yok / 2xx değil) → invalid
p50 ≤ eşik  ve  (prev yok | Δ ≤ tol)                → pass
p50 > eşik  ve  (prev yok | Δ > tol)                → fail
yalnız biri                                         → warn
gövde > MaxBytes                                    → en az warn (eşikle birlikte fail)
driftWarn                                           → fail → warn (kıyas güvenilmez)

func (Result) Key

func (r Result) Key() string

Key — Result için aynı kimlik.

type Rules

type Rules struct {
	TolerancePct        float64 `json:"tolerancePct"`        // önceki koşuya göre izin verilen artış
	DatasetDriftWarnPct float64 `json:"datasetDriftWarnPct"` // veri-seti sapma eşiği
}

Rules — karar parametreleri (budget.json başlığı).

type Sample

type Sample struct {
	TTFBMs float64 `json:"ttfbMs"`
	Status int     `json:"status"`
	Bytes  int64   `json:"bytes"`
	XCache string  `json:"xcache,omitempty"`
}

Sample — bir koşunun ölçümü.

type Stats

type Stats struct {
	N     int     `json:"n"`
	P50Ms float64 `json:"p50Ms"`
	P95Ms float64 `json:"p95Ms"`
	MinMs float64 `json:"minMs"`
	MaxMs float64 `json:"maxMs"`
}

Stats — koşuların özeti.

func Summarize

func Summarize(ttfbMs []float64) Stats

Summarize — TTFB'lerden Stats. Boş → sıfır. Yüzdelik en-yakın-sıra (nearest-rank): 5 koşuda p95 = max, 20 koşuda 19. sıra.

type Summary

type Summary struct {
	Pass    int  `json:"pass"`
	Warn    int  `json:"warn"`
	Fail    int  `json:"fail"`
	Invalid int  `json:"invalid"`
	OK      bool `json:"ok"`
}

Summary — sayım + çıkış kodu kararı.

func Tally

func Tally(points []Result) Summary

Tally — özet + çıkış kararı: fail varsa OK=false; invalid nokta da başarısızlıktır (ölçülemeyen bütçe "geçti" sayılamaz).