Mengirim log menggunakan titik akhir JSON Terstruktur (Log JSON Terstruktur) - CloudWatch Log Amazon
Format permintaanJenis nilai JSON yang diterimaBidang stempel waktuContoh permintaanResponsPraktik terbaikBatasan

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Mengirim log menggunakan titik akhir JSON Terstruktur (Log JSON Terstruktur)

Titik akhir JSON Logs Terstruktur (/ingest/json) menerima JSON standar — baik objek JSON tunggal atau array objek JSON. Endpoint ini dirancang untuk data log terstruktur di mana setiap peristiwa adalah objek JSON.

Jika Anda menggunakan otentikasi token pembawa, selesaikan langkah-langkah penyiapan Menyiapkan otentikasi token pembawa sebelum melanjutkan.

Format permintaan

Hanya application/json diterima sebagai Content-Type.

Objek JSON tunggal:

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

JSON array objek:

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

Jenis nilai JSON yang diterima

Titik akhir ini ketat — hanya objek JSON yang diterima sebagai peristiwa.

Input Perilaku
Objek JSON tunggal Diterima sebagai salah satu acara
JSON array objek Setiap objek menjadi peristiwa yang terpisah
Array kosong [] Diterima, menghasilkan 0 acara
Non-objek dalam array (string, angka, dll.) Dilewati
Primitif tingkat atas ("hello",) 42 Dilewati
Objek yang digabungkan {...}{...} Hanya objek pertama yang diuraikan

Contoh - array dengan tipe campuran:

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

Hasil: 2 peristiwa tertelan (objek), 2 dilewati (string dan angka).

Bidang stempel waktu

"timestamp"Bidang ini dalam milidetik epoch, sama seperti titik akhir NDJSON.

format Contoh Ditafsirkan sebagai
Numerik (millis) "timestamp":1771007942000 1771007942000 ms
Hilang (tidak ada bidang stempel waktu) Waktu server saat ini
Non-numerik "timestamp":"invalid" Waktu server saat ini

Contoh permintaan

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"}]'

Respons

Sukses (semua acara diterima):

HTTP 200 OK
{}

Keberhasilan sebagian (beberapa acara ditolak):

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

rejectedLogRecordsBidang adalah jumlah total peristiwa yang ditolak. errorMessageBidang berisi rincian yang dikodekan JSON dengan alasan penolakan:

  • tooOldLogEventCount— Acara dengan stempel waktu yang lebih tua dari periode retensi

  • tooNewLogEventCount— Acara dengan stempel waktu terlalu jauh di masa depan

  • expiredLogEventCount— Acara yang kedaluwarsa selama pemrosesan

Praktik terbaik

Acara batching

Untuk kinerja dan efisiensi yang lebih baik:

  • Batch beberapa peristiwa dalam satu permintaan bila memungkinkan

  • Ukuran batch yang disarankan: 10—100 acara per permintaan

  • Ukuran permintaan maksimal: 1 MB

Penanganan kesalahan

Menerapkan penanganan kesalahan yang tepat dalam aplikasi Anda. Kode status HTTP umum:

  • 200 OK— Log berhasil dicerna

  • 400 Bad Request— Format atau parameter permintaan tidak valid

  • 401 Unauthorized— Token pembawa tidak valid atau kedaluwarsa

  • 403 Forbidden— Izin tidak mencukupi

  • 404 Not Found— Grup log atau aliran tidak ada

  • 429 Too Many Requests— Batas tarif terlampaui

  • 500 Internal Server Error— Kesalahan layanan (coba lagi dengan backoff eksponensial)

Batasan

  • Ukuran acara maksimal: 256 KB per acara

  • Ukuran permintaan maksimal: 1 MB

  • Maksimum acara per permintaan: 10.000

  • Nama grup log harus mengikuti konvensi penamaan CloudWatch Log

  • Otentikasi token pembawa harus diaktifkan pada grup log jika otentikasi token pembawa digunakan.