Senden von Protokollen mithilfe des strukturierten JSON-Endpunkts (Strukturierte JSON-Protokolle) - CloudWatch Amazon-Protokolle
AnforderungsformatAkzeptierte JSON-WerttypenFeld „Zeitstempel“BeispielanforderungAntwortenBest PracticesEinschränkungen

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 mithilfe des strukturierten JSON-Endpunkts (Strukturierte JSON-Protokolle)

Der Endpunkt Structured JSON Logs (/ingest/json) akzeptiert Standard-JSON — entweder ein einzelnes JSON-Objekt oder ein JSON-Array von Objekten. Dieser Endpunkt ist für strukturierte Protokolldaten konzipiert, bei denen jedes Ereignis ein JSON-Objekt ist.

Wenn Sie die Bearer-Token-Authentifizierung verwenden, schließen Sie die Einrichtungsschritte unter ab, Einrichtung der Bearer-Token-Authentifizierung bevor Sie fortfahren.

Anforderungsformat

application/jsonWird nur als Content-Type akzeptiert.

Einzelnes JSON-Objekt:

{"timestamp":1771007942000,"message":"single event","level":"INFO"}

JSON-Array von Objekten:

[
  {"timestamp":1771007942000,"message":"event one","level":"INFO"},
  {"timestamp":1771007943000,"message":"event two","level":"ERROR"}
]

Akzeptierte JSON-Werttypen

Dieser Endpunkt ist streng — nur JSON-Objekte werden als Ereignisse akzeptiert.

Input Behavior
Einzelnes JSON-Objekt Als ein Ereignis akzeptiert
JSON-Array von Objekten Jedes Objekt wird zu einem separaten Ereignis
Leeres Array [] Akzeptiert, erzeugt 0 Ereignisse
Kein Objekt im Array (Zeichenfolge, Zahl usw.) Übersprungen
Primitiv der obersten Ebene ("hello",) 42 Übersprungen
Verkettete Objekte {...}{...} Nur das erste Objekt wurde analysiert

Beispiel — Array mit gemischten Typen:

[
  {"timestamp":1771007942000,"message":"valid object"},
  "just a string",
  42,
  {"timestamp":1771007943000,"message":"another valid object"}
]

Ergebnis: 2 Ereignisse wurden aufgenommen (die Objekte), 2 übersprungen (die Zeichenfolge und die Zahl).

Feld „Zeitstempel“

Das "timestamp" Feld wird in Epochen-Millisekunden angegeben, genau wie der NDJSON-Endpunkt.

Format Beispiel Interpretiert als
Numerisch (Millis) "timestamp":1771007942000 1771007942000 ms
Fehlen (kein Zeitstempelfeld) Aktuelle Uhrzeit des Servers
Nicht numerisch "timestamp":"invalid" Aktuelle Uhrzeit des Servers

Beispielanforderung

curl -X POST "https://logs.<region>.amazonaws.com/ingest/json?logGroup=MyLogGroup&logStream=MyStream" \
  -H "Authorization: Bearer ACWL<token>" \
  -H "Content-Type: application/json" \
  -d '[{"timestamp":1771007942000,"message":"User logged in","user_id":"u-123"},{"timestamp":1771007943000,"message":"Order placed","order_id":"o-456"}]'

Antworten

Erfolgreich (alle Ereignisse wurden akzeptiert):

HTTP 200 OK
{}

Teilweise erfolgreich (einige Ereignisse wurden abgelehnt):

{
  "partialSuccess": {
    "rejectedLogRecords": 5,
    "errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
  }
}

Das rejectedLogRecords Feld gibt die Gesamtzahl der abgelehnten Ereignisse an. Das errorMessage Feld enthält eine JSON-kodierte Aufschlüsselung nach Ablehnungsgründen:

  • tooOldLogEventCount— Ereignisse, deren Zeitstempel älter als der Aufbewahrungszeitraum sind

  • tooNewLogEventCount— Ereignisse mit Zeitstempeln, die zu weit in der future liegen

  • expiredLogEventCount— Ereignisse, die während der Verarbeitung abgelaufen sind

Best Practices

Ereignisse werden gebündelt

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 Trägertoken

  • 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.