Stavové reporty a health endpoint

Report všetkých monitorovaných kontrol zostavíte cez Health::report(), report kontrol jedného vlastníka cez Health::for($owner)->report() — oba voliteľne filtrované podľa tagov, obmedzené na obdobie cez since: a na naplánované kontroly cez scheduledOnly: true:

use RoundlyConsulting\Alerts\Facades\Health;

$report = Health::report();                  // HealthReport across every monitored check
$report->overall();                          // worst Status across all checks (skipped never outranks ok)
$report->isHealthy();                        // bool

foreach ($report->checks() as $check) {
    // CheckStatus: key, name, status, lastAlertAt, message, tags, uptime, p95LatencyMs, muted, meta
}

Health::status();                            // Status roll-up
Health::report(['critical']);                // only checks tagged with one of these (row tags or the check's tags())
Health::report(since: now()->subDay());      // uptime and p95 over the last day only
Health::report(scheduledOnly: true);         // leave out the on-demand rows run() creates
Health::for($team)->report(['critical']);    // one owner, optionally tag-filtered
Health::for($team)->status();                // that owner's roll-up
$report->whereTag('db');                     // filter an in-memory report

Report sa zostavuje z riadkov health_checks v poradí podľa id — vrátane riadkov na požiadanie, pokiaľ nezadáte scheduledOnly: true —, nie z registra. Stav každého riadka je stav jeho najnovšieho otvoreného alertu, alebo ok, ak žiadny otvorený nie je — zlyhania pod failAfter() preto stále vyzerajú ako ok a zlyhaný beh na požiadanie sa počíta, kým úspešný run() tej istej kontroly pre daného vlastníka jeho alert nezatvorí (alebo unmonitor() riadok neodstráni). Otvorený alert sa riadi posledným zlyhaným výsledkom, takže varovanie, ktoré prejde do zlyhania, sa vykáže ako failed. overall() je najhorší stav podľa závažnosti, pričom skipped sa neberie do úvahy — report s kontrolami ok a skipped, alebo len skipped, je ok — a isHealthy() je true, keď nič nevyžaduje alert.

• Health::report(['critical']) aj Health::for($team)->report(['critical']) ponechajú riadky označené niektorým zo zadaných tagov — na riadku alebo cez tags() kontroly; status(), alerts:status --tag aj /health?tag= filtrujú rovnako.
• $report->whereTag('db') filtruje hotový report podľa efektívnych tagov — tagov riadka zlúčených s tags() triedy kontroly.
• HealthReport::toArray() a CheckStatus::toArray() vždy vrátia úplnú štruktúru vrátane meta; endpoint z nej vypíše len presne vymedzený zoznam polí (nižšie).

Obdobie, štatistiky a počet dopytov

since: obmedzí uptime a p95LatencyMs na behy od daného okamihu vrátane; bez neho pokrývajú celú uchovanú históriu. Riadok bez behu v danom období — alebo úplne bez behov, prípadne s vypnutým history.enabled — vráti obe hodnoty ako null, takže kontrola, ktorá nikdy nebežala, už nevyzerá bezchybne. status() obdobie neprijíma a nezmenil sa.

Bez ohľadu na počet riadkov a behov si report vystačí s pevným počtom dopytov — najviac piatimi: riadky, ich otvorené alerty, jeden súhrn behov, jedno načítanie p95 metódou nearest-rank cez okennú funkciu a jedna snímka stlmení, pričom id riadkov sa posielajú po dávkach 1000. Dopyty na behy sa pri vypnutej histórii vynechajú a snímka pri vypnutom stlmení. JSON endpoint aj alerts:status zostavujú report pri každom volaní, takže zostanú lacné.

Cache reportu

Pre cache, ktorá ukladá len polia (cache.serializable_classes vypnuté), uložte toArray() a späť ho načítajte cez HealthReport::tryFromArray() — alebo CheckStatus::tryFromArray() pre jeden riadok. Pri obsahu, ktorý nevedia prečítať, vrátia null — výpadok cache, nikdy chybu — a uložený celkový status sa ignoruje a vypočíta znova:

use Illuminate\Support\Facades\Cache;
use RoundlyConsulting\Alerts\Facades\Health;
use RoundlyConsulting\Alerts\Status\HealthReport;

$report = HealthReport::tryFromArray(Cache::get('health'))
    ?? tap(Health::report(since: now()->subDay(), scheduledOnly: true),
        fn (HealthReport $r) => Cache::put('health', $r->toArray(), 60));

V príkazovom riadku

Súhrn v CLI, ktorý skončí nenulovým kódom, keď niečo vyžaduje alert — praktické v CI alebo pri sondách dostupnosti:

php artisan alerts:status
php artisan alerts:status --tag=db   # filter by tag

JSON endpoint

Voliteľný endpoint vracia 200, keď je všetko v poriadku, inak 503. Zaregistrujte ho z vlastného súboru rout — balík predvolene žiadne routy nepridáva:

// routes/web.php
use RoundlyConsulting\Alerts\Facades\Health;

Health::routes();   // GET /health            -> { "status": "...", "checks": [...] }
                    // GET /health?tag=critical -> only checks tagged "critical" (on the row or by the check's tags())

// Or on your own URI, behind your own middleware (routes() returns the Route):
Health::routes('internal/health')->middleware('auth.basic');

{
    "status": "warning",
    "checks": [
        {
            "key": "http_ping_check",
            "name": "Http Ping Check",
            "status": "warning",
            "uptime": 99.31,
            "p95_latency_ms": 840
        }
    ]
}

Predvolene vypíše pri každej kontrole len key, name, status, uptime a p95_latency_ms — uptime a p95_latency_ms sú pri kontrole bez behov null. Nastavením route.details (ALERTS_ROUTE_DETAILS=true) pridáte message, tags, last_alert_at a muted. Ide o presne vymedzený zoznam: surové meta alertu sa tu nevypíšu nikdy, s detailmi ani bez nich. Detaily aj tak držte za middlewarom — pri zapnutom store_exception_details môže uložená správa alertu obsahovať surový text výnimky, napríklad hostiteľov či názvy databáz.

Endpoint nemá autentifikáciu, kým na Route, ktorú vráti routes(), nepripojíte middleware. Vypisuje všetky monitorované kontroly všetkých vlastníkov, takže zlyhaná kontrola jedného vlastníka prepne celý endpoint na 503 — zúžte ho cez ?tag=. URI a názov routy sú predvolene route.uri a route.name z konfigurácie.