HTTP NEL Header

Typ

Der NEL-Header ist ein HTTP-Response-Header, der Network Error Logging im Browser aktiviert, um Netzwerkfehler automatisch an einen Collector-Endpunkt zu melden.

Syntax

Der NEL-Header enthält eine JSON-Struktur mit Konfigurationsparametern für das Fehlerreporting, einschließlich Report-URL, maximaler Gültigkeitsdauer und optionaler Fehlerrate-Sampling.

NEL: {"report_to":"network-errors","max_age":86400,"include_subdomains":true,"success_fraction":0.01,"failure_fraction":1.0}

Direktiven

Der NEL-Header definiert mehrere Direktiven zur Steuerung des Network Error Logging-Verhaltens für API-Zugriffe und CDN-Auslieferungen.

Beispiele

Die folgenden Beispiele zeigen typische NEL-Konfigurationen für API-Monitoring, CDN-Fehlertracking und unterschiedliche Sampling-Strategien für Production-Umgebungen.

HTTP/1.1 200 OK
NEL: {"report_to":"api-errors","max_age":2592000,"include_subdomains":false,"failure_fraction":1.0}
Report-To: {"group":"api-errors","max_age":2592000,"endpoints":[{"url":"https://monitoring.example.com/api/v1/nel"}]}
Content-Type: application/json

{
  "status": "success",
  "data": {
    "orders": []
  }
}

HTTP/1.1 200 OK
NEL: {"report_to":"cdn-network","max_age":86400,"include_subdomains":true,"success_fraction":0.05,"failure_fraction":1.0}
Report-To: {"group":"cdn-network","max_age":86400,"endpoints":[{"url":"https://cdn-analytics.example.com/collect/nel"}]}
Cache-Control: public, max-age=3600
Content-Type: application/javascript

// JavaScript resource

HTTP/1.1 200 OK
NEL: {"report_to":"service-monitoring","max_age":604800,"include_subdomains":false,"success_fraction":0.01,"failure_fraction":0.5}
Report-To: {"group":"service-monitoring","max_age":604800,"endpoints":[{"url":"https://telemetry.example.com/v2/nel-reports"}]}
Content-Type: application/json

{
  "userId": "12345",
  "profile": {}
}

Network Error Logging Flow

Der Ablauf zeigt, wie Browser Netzwerkfehler sammeln und asynchron an Monitoring-Endpunkte senden, unabhängig vom ursprünglichen API-Request-Lifecycle.

@startuml
actor Client
participant Browser
participant "API Server" as API
participant "NEL Collector" as Collector

Client -> Browser: Request API Resource
Browser -> API: GET /api/v1/orders
API --> Browser: 200 OK\nNEL: {"report_to":"api-errors",...}
Browser -> Browser: Store NEL Policy

alt Network Error Occurs
    Client -> Browser: Request API Resource
    Browser -> API: GET /api/v1/products
    Browser <-- API: Connection Timeout
    Browser -> Browser: Generate NEL Report
    Browser -> Collector: POST /api/v1/nel\n[NEL Report JSON]
    Collector --> Browser: 204 No Content
end

alt Successful Request (with sampling)
    Client -> Browser: Request API Resource
    Browser -> API: GET /api/v1/users/123
    Browser <-- API: 200 OK
    Browser -> Browser: Sample Success (5% chance)
    Browser -> Collector: POST /api/v1/nel\n[Success Report]
    Collector --> Browser: 204 No Content
end

@enduml

Vorteile für die Systemarchitektur

Spezifikation

Der NEL-Header ist in der W3C Network Error Logging Specification definiert und ermöglicht Browser-natives Sammeln von Netzwerkfehlern für verbesserte API-Zuverlässigkeitsanalyse.

Weitere Spezifikationen

Report-To Header, Reporting-Endpoints Header