Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich. # Senden von Protokollen über den HLC-Endpunkt (HLC Logs) Der HLC Logs-Endpunkt (`/services/collector/event`) basiert auf dem HTTP Log Collector (HLC) -Format. Wenn Sie die Bearer-Token-Authentifizierung verwenden, schließen Sie die Einrichtungsschritte unter ab, bevor Sie fortfahren. [Einrichtung der Bearer-Token-Authentifizierung](CWL_HTTP_Endpoints_BearerTokenAuth.md) ## Eingabemodi Jedes Ereignis ist ein JSON-Objekt mit einem erforderlichen `"event"` Feld. Optionale Metadatenfelder: `"time"``"host"`,`"source"`,,`"sourcetype"`,`"index"`. **Einzelnes Ereignis:** ``` {"event":"Hello world!","time":1486683865.0} ``` **JSON-Array von Ereignissen:** ``` [ {"event":"msg1","time":1486683865.0}, {"event":"msg2","time":1486683866.0} ] ``` **Verkettete/gebündelte Ereignisse (kein Array-Wrapper):** ``` {"event":"msg1","time":1486683865.0}{"event":"msg2","time":1486683866.0} ``` ## Feld „Ereignis“ (erforderlich) Das `"event"` Feld ist ein Pflichtfeld. Sein Wert kann ein beliebiger JSON-Typ sein: ``` {"event":"a string message"} {"event":{"message":"structured data","severity":"INFO"}} {"event":42} {"event":true} ``` Objekte ohne `"event"` Feld werden stillschweigend übersprungen: ``` {"message":"this is skipped — no event field"} ``` ## Zeitfeld (optional) Das `"time"` Feld wird in Epochensekunden (nicht in Millisekunden) angegeben, mit optionaler Dezimalzahl für eine Genauigkeit unter einer Sekunde. | Format | Beispiel | Interpretiert als | | --- | --- | --- | | Gleitkommazahl | "time":1486683865.500 | 1486683865500 ms | | Ganzzahl | "time":1486683865 | 1486683865000 ms | | Zeichenfolge (Float) | "time":"1486683865.500" | 1486683865500 ms | | Zeichenfolge (Ganzzahl) | "time":"1486683865" | 1486683865000 ms | | Fehlen | (kein Zeitfeld) | Aktuelle Uhrzeit des Servers | | Ungültig | "time":"invalid" | Aktuelle Uhrzeit des Servers | ## Content-Type Nur `application/json` wird akzeptiert. ## Akzeptierte JSON-Werttypen | Typ der obersten Ebene | Behavior | | --- | --- | | Objekt mit "event" | Accepted (Akzeptiert) | | Objekt ohne "event" | Übersprungen | | Array von -Objekten. | Jedes Element wird einzeln verarbeitet | | Verkettete Objekte | Jedes Objekt wird einzeln verarbeitet | | Primitiv (Zeichenfolge, Zahl, Boolean, Null) | Übersprungen | ## Endpunkt-Format Die URL des HLC-Endpunkts folgt diesem Format: ``` https://logs..amazonaws.com/services/collector/event?logGroup=&logStream=[&entityName=&entityEnvironment=] ``` **Erforderliche Parameter:** + ``— AWS Region (zum Beispiel`us-east-1`,`eu-west-1`) + `logGroup`— URL-codierter Name der Protokollgruppe + `logStream`— URL-codierter Name des Protokolldatenstroms **Optionale Parameter:** Sie können Ihre Protokollereignisse optional einer `Service` Entität zuordnen, indem Sie die folgenden Abfrageparameter angeben. Da es sich bei den über den HLC-Endpunkt gesendeten Protokollen um benutzerdefinierte Telemetrie handelt, werden sie nicht automatisch einer Entität zugeordnet. Durch die Angabe dieser Parameter erstellt CloudWatch Logs eine Entität mit der `KeyAttributes.Type` Einstellung auf `Service` und ordnet sie Ihren Protokollereignissen zu. Auf diese Weise kann die **zugehörige CloudWatch Explore-Funktion** diese Protokolle mit anderen Telemetriedaten (Metriken, Traces und Logs) desselben Dienstes korrelieren, was die Fehlerbehebung und Überwachung Ihrer Anwendungen bei verschiedenen Signaltypen erleichtert. Weitere Informationen zu Entitäten und verwandter Telemetrie finden Sie unter [Hinzufügen verwandter Informationen zur](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html) benutzerdefinierten Telemetrie. + `entityName`— Der Name der Dienstentität, die den Protokollereignissen zugeordnet werden soll. Dieser Wert wird als Entität gespeichert `KeyAttributes.Name` (z. B. `my-application` oder`api.myservice.com`). + `entityEnvironment`— Die Umgebung, in der der Dienst gehostet wird oder zu der er gehört. Dieser Wert wird als Entität gespeichert `KeyAttributes.Environment` (z. B.`production`,`ec2:default`, oder`eks:my-cluster/default`). ## Anforderungsformat Senden Sie Protokolle mithilfe von HTTP POST mit den folgenden Headern und dem folgenden Hauptteil: **Kopfzeilen:** + `Authorization: Bearer ` + `Content-Type: application/json` **Körperformat:** Der Hauptteil der Anfrage sollte im JSON-Format mit einer Reihe von Ereignissen vorliegen: ``` { "event": [ { "time": 1730141374.001, "event": "Application started successfully", "host": "web-server-1", "source": "application.log", "severity": "info" }, { "time": 1730141374.457, "event": "User login successful", "host": "web-server-1", "source": "auth.log", "user": "john.doe" } ] } ``` **Feldbeschreibungen:** + `time`— Zeitstempel der Unix-Epoche in Sekunden, mit optionaler Dezimalzahl für eine Genauigkeit unter einer Sekunde (optional) + `event`— Die Protokollnachricht oder die Ereignisdaten (erforderlich) + `host`— Hostname oder Kennung der Quelle (optional) + `source`— Kennung der Protokollquelle (optional) Zusätzliche benutzerdefinierte Felder können nach Bedarf hinzugefügt werden. ## Beispielanforderung ``` curl -X POST "https://logs..amazonaws.com/services/collector/event?logGroup=MyLogGroup&logStream=MyStream" \ -H "Authorization: Bearer ACWL" \ -H "Content-Type: application/json" \ -d '{"event":{"message":"User logged in","user_id":"u-123"},"time":1486683865.0,"host":"web-01","source":"auth-service"}' ``` ## Best Practices ### Ereignisse stapeln Für mehr Leistung und Effizienz: + Wenn möglich, mehrere Ereignisse in einer einzigen Anfrage bündeln + Empfohlene Batchgröße: 10—100 Ereignisse pro Anfrage + Maximale Anforderungsgröße: 1 MB ### Fehlerbehandlung Implementieren Sie die richtige Fehlerbehandlung in Ihrer Anwendung. Allgemeine HTTP-Statuscodes: + `200 OK`— Protokolle wurden erfolgreich aufgenommen + `400 Bad Request`— Ungültiges Anforderungsformat oder ungültige Parameter + `401 Unauthorized`— Ungültiges oder abgelaufenes Inhaber-Token + `403 Forbidden`— Unzureichende Berechtigungen + `404 Not Found`— Protokollgruppe oder Stream existiert nicht + `429 Too Many Requests`— Ratenlimit überschritten + `500 Internal Server Error`— Servicefehler (erneuter Versuch mit exponentiellem Backoff) ## Einschränkungen + Maximale Ereignisgröße: 256 KB pro Ereignis + Maximale Anforderungsgröße: 1 MB + Maximale Anzahl von Ereignissen pro Anfrage: 10.000 + Die Namen der Protokollgruppen müssen den Benennungskonventionen für CloudWatch Protokolle entsprechen + Wenn die Bearer-Token-Authentifizierung verwendet wird, muss die Bearer-Token-Authentifizierung für die Protokollgruppe aktiviert sein.