Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Log konsumsi melalui titik akhir HTTP Amazon CloudWatch Logs menyediakan endpoint HTTP yang memungkinkan Anda mengirim log langsung ke CloudWatch Log menggunakan permintaan HTTP POST sederhana. Titik akhir ini mendukung otentikasi token sigV4 dan pembawa. **penting** Sebaiknya gunakan otentikasi SiGv4 untuk semua beban kerja produksi yang memungkinkan integrasi AWS SDK. SiGv4 menggunakan kredensil jangka pendek dan memberikan postur keamanan terkuat. Otentikasi token pembawa (kunci API) ditujukan untuk skenario di mana SigV4 tidak layak, seperti penerusan log pihak ketiga yang tidak mendukung integrasi SDK. AWS Untuk informasi selengkapnya, lihat [Alternatif untuk kunci akses jangka panjang](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles) di *Panduan Pengguna IAM*. CloudWatch Log mendukung titik akhir konsumsi HTTP berikut: | Titik akhir | Jalan | Content-Type | Format | | --- | --- | --- | --- | | [OpenTelemetry Logs](CWL_HTTP_Endpoints_OTLP.md) | /v1/logs | application/json atau application/x-protobuf | OTLP JSON atau Protobuf | | [HLC Logs](CWL_HLC_Endpoint.md) | /services/collector/event | application/json | Format HLC | | [ND-JSON Logs](CWL_HTTP_Endpoints_NDJSON.md) | /ingest/bulk | application/json atau application/x-ndjson | JSON yang dibatasi baris baru | | [Structured JSON Logs](CWL_HTTP_Endpoints_StructuredJSON.md) | /ingest/json | application/json | JSON objek atau array | ## Perilaku umum Semua titik akhir konsumsi HTTP berbagi perilaku berikut: **Autentikasi** Semua titik akhir mendukung otentikasi SIgV4 dan token pembawa: + **SiGv4 (disarankan)** - AWS Penandatanganan Versi Tanda Tangan Standar 4. Gunakan SiGv4 setiap kali aplikasi atau infrastruktur Anda mendukung AWS SDK atau dapat menandatangani permintaan. SiGv4 menggunakan kredensil jangka pendek dan merupakan metode otentikasi yang paling aman. + **Token pembawa** — Gunakan `Authorization: Bearer ` header. + Token harus berupa token pembawa ACWL yang valid. Untuk petunjuk penyiapan, lihat[Menyiapkan otentikasi token pembawa](CWL_HTTP_Endpoints_BearerTokenAuth.md). + Memerlukan izin `logs:PutLogEvents` dan `logs:CallWithBearerToken` IAM. **Grup log dan aliran log** + Disediakan melalui header: `x-aws-log-group` dan `x-aws-log-stream` + Parameter kueri juga `?logGroup=&logStream=` didukung pada semua titik akhir kecuali OTLP. + Anda tidak dapat menggunakan parameter kueri dan header untuk parameter yang sama. + Baik grup log dan aliran log diperlukan. **Respons** + Sukses: `HTTP 200` dengan tubuh `{}` + Kesalahan validasi: `HTTP 400` + Kegagalan autentikasi: `HTTP 401` # Menyiapkan otentikasi token pembawa Sebelum Anda dapat mengirim log menggunakan otentikasi token pembawa dengan salah satu titik akhir penyerapan HTTP, Anda perlu: + Buat pengguna IAM dengan izin CloudWatch Log + Hasilkan kredenal khusus layanan (token pembawa) + Buat grup log dan aliran log + Aktifkan otentikasi token pembawa pada grup log **penting** Sebaiknya gunakan otentikasi SiGv4 dengan kredensi jangka pendek untuk semua beban kerja jika memungkinkan. SiGv4 memberikan postur keamanan terkuat. Batasi penggunaan kunci API (token pembawa) ke skenario di mana otentikasi berbasis kredensial jangka pendek tidak layak dilakukan. Ketika Anda siap untuk memasukkan CloudWatch Log ke dalam aplikasi dengan persyaratan keamanan yang lebih besar, Anda harus beralih ke kredensi jangka pendek. Untuk informasi selengkapnya, lihat [Alternatif untuk kunci akses jangka panjang](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles) di *Panduan Pengguna IAM*. ## Opsi 1: Mulai cepat menggunakan AWS konsol AWS Management Console menyediakan alur kerja yang efisien untuk menghasilkan kunci API untuk akses titik akhir HTTP. **Untuk mengatur akses titik akhir HTTP menggunakan konsol** 1. Masuk ke Konsol AWS Manajemen. 1. Arahkan **CloudWatch**ke> **Pengaturan>** **Log**. 1. Di bagian API Keys, pilih **Generate API key**. 1. Untuk **kedaluwarsa kunci API**, lakukan salah satu hal berikut: + Pilih durasi kedaluwarsa kunci API **1**, **5**, **30**, **90**, atau **365 hari**. + Pilih **Durasi kustom** untuk menentukan tanggal kedaluwarsa kunci API kustom. + Pilih **Jangan pernah kedaluwarsa** (tidak disarankan). 1. Pilih **Hasilkan kunci API**. Konsol secara otomatis: + Membuat pengguna IAM baru dengan izin yang sesuai + Melampirkan kebijakan terkelola [CloudWatchLogsAPIKeyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) (termasuk `logs:PutLogEvents` dan `logs:CallWithBearerToken` izin) + Menghasilkan kredensi khusus layanan (kunci API) 1. Salin dan simpan kredenal yang ditampilkan dengan aman: + **ID Kunci API (ID** kredensi khusus layanan) + **Rahasia Kunci API** (Token pembawa) **penting** Simpan Rahasia Kunci API segera. Hal itu tidak dapat diambil lagi nanti. Jika Anda kehilangannya, Anda harus membuat kunci API baru. 1. Buat grup log dan aliran log tempat log Anda akan disimpan: ``` # Create the log group aws logs create-log-group \ --log-group-name /aws/hlc-logs/my-application \ --region us-east-1 # Create the log stream aws logs create-log-stream \ --log-group-name /aws/hlc-logs/my-application \ --log-stream-name application-stream-001 \ --region us-east-1 ``` 1. Aktifkan otentikasi token pembawa pada grup log: ``` aws logs put-bearer-token-authentication \ --log-group-identifier /aws/hlc-logs/my-application \ --bearer-token-authentication-enabled \ --region us-east-1 ``` Verifikasi konfigurasi: ``` aws logs describe-log-groups \ --log-group-name-prefix /aws/hlc-logs/my-application \ --region us-east-1 ``` **Izin disertakan:** Pengguna IAM yang dibuat secara otomatis akan memiliki izin berikut: + `logs:PutLogEvents`— Kirim peristiwa log ke CloudWatch Log + `logs:CallWithBearerToken`— Otentikasi menggunakan token pembawa + `kms:Describe*`,`kms:GenerateDataKey*`, `kms:Decrypt` — Akses grup log terenkripsi KMS (dengan kondisi membatasi layanan log) ## Opsi 2: Pengaturan manual Jika Anda lebih suka kontrol lebih atas konfigurasi IAM atau perlu menyesuaikan izin, Anda dapat mengatur akses titik akhir HTTP secara manual. ### Langkah 1: Buat pengguna IAM Buat pengguna IAM yang akan digunakan untuk log ingestion: 1. Masuk ke AWS Management Console dan navigasikan ke IAM. 1. Pada panel navigasi kiri, pilih **Pengguna**. 1. Pilih **Create user** (Buat pengguna). 1. Masukkan nama pengguna (misalnya,`cloudwatch-logs-hlc-user`). 1. Pilih **Berikutnya**. 1. Lampirkan salah satu kebijakan IAM berikut: **Opsi A: Gunakan kebijakan terkelola (disarankan)** Lampirkan kebijakan terkelola [CloudWatchLogsAPIKeyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html). **Opsi B: Buat kebijakan khusus** Buat dan lampirkan kebijakan IAM berikut: ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "LogsAPIs", "Effect": "Allow", "Action": [ "logs:CallWithBearerToken", "logs:PutLogEvents" ], "Resource": "*" }, { "Sid": "KMSAPIs", "Effect": "Allow", "Action": [ "kms:Describe*", "kms:GenerateDataKey*", "kms:Decrypt" ], "Condition": { "StringEquals": { "kms:ViaService": [ "logs.*.amazonaws.com" ] } }, "Resource": "arn:aws:kms:*:*:key/*" } ] } ``` 1. Pilih **Berikutnya** dan kemudian **Buat pengguna**. **catatan** Izin KMS diperlukan jika Anda berencana untuk mengirim log ke grup log terenkripsi KMS. Kondisi ini membatasi akses KMS ke hanya kunci yang digunakan melalui layanan CloudWatch Log. ### Langkah 2: Hasilkan kredenal khusus layanan (kunci API) Buat kunci API CloudWatch Log menggunakan [CreateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceSpecificCredential.html)API. Anda juga dapat menggunakan perintah [create-service-specific-credential](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/create-service-specific-credential.html)CLI. Untuk usia kredenal, Anda dapat menentukan nilai antara 1—36600 hari. Jika Anda tidak menentukan usia kredensi, kunci API tidak akan kedaluwarsa. Untuk membuat kunci API dengan masa kedaluwarsa 30 hari: ``` aws iam create-service-specific-credential \ --user-name cloudwatch-logs-hlc-user \ --service-name logs.amazonaws.com \ --credential-age-days 30 ``` Responsnya adalah [ServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ServiceSpecificCredential.html)objek. `ServiceCredentialSecret`Nilainya adalah kunci API CloudWatch Log Anda (token pembawa). **penting** Simpan `ServiceCredentialSecret` nilainya dengan aman, karena Anda tidak dapat mengambilnya nanti. Jika Anda kehilangannya, Anda harus membuat kunci API baru. ### Langkah 3: Buat grup log dan aliran log Buat grup log dan aliran log tempat log Anda akan disimpan: ``` # Create the log group aws logs create-log-group \ --log-group-name /aws/hlc-logs/my-application \ --region us-east-1 # Create the log stream aws logs create-log-stream \ --log-group-name /aws/hlc-logs/my-application \ --log-stream-name application-stream-001 \ --region us-east-1 ``` ### Langkah 4: Aktifkan otentikasi token pembawa Aktifkan otentikasi token pembawa pada grup log: ``` aws logs put-bearer-token-authentication \ --log-group-identifier /aws/hlc-logs/my-application \ --bearer-token-authentication-enabled \ --region us-east-1 ``` Verifikasi konfigurasi: ``` aws logs describe-log-groups \ --log-group-name-prefix /aws/hlc-logs/my-application \ --region us-east-1 ``` ## Izin kontrol untuk membuat dan menggunakan kunci API CloudWatch Log Pembuatan dan penggunaan kunci API CloudWatch Log dikendalikan oleh tindakan dan kunci kondisi di layanan CloudWatch Log dan IAM. ### Mengontrol pembuatan kunci API CloudWatch Log CreateServiceSpecificCredentialTindakan [iam:](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsidentityandaccessmanagementiam.html#awsidentityandaccessmanagementiam-actions-as-permissions) mengontrol pembuatan kunci khusus layanan (seperti kunci API CloudWatch Log). Anda dapat memberikan cakupan tindakan ini kepada pengguna IAM sebagai sumber daya untuk membatasi pengguna yang kuncinya dapat dibuat. Anda dapat menggunakan tombol kondisi berikut untuk memaksakan kondisi pada izin untuk `iam:CreateServiceSpecificCredential` tindakan: + [iam: ServiceSpecificCredentialAgeDays](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) — Memungkinkan Anda menentukan, dalam kondisi, waktu kedaluwarsa kunci dalam beberapa hari. Misalnya, Anda dapat menggunakan kunci kondisi ini untuk hanya mengizinkan pembuatan kunci API yang kedaluwarsa dalam 90 hari. + [iam: ServiceSpecificCredentialServiceName](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) — Memungkinkan Anda menentukan, dalam kondisi, nama layanan. Misalnya, Anda dapat menggunakan kunci kondisi ini untuk hanya mengizinkan pembuatan kunci API untuk CloudWatch Log dan bukan layanan lainnya. ### Mengontrol penggunaan kunci API CloudWatch Log `logs:CallWithBearerToken`Tindakan ini mengontrol penggunaan kunci API CloudWatch Log. Untuk mencegah identitas menggunakan kunci API CloudWatch Logs, lampirkan kebijakan yang menolak `logs:CallWithBearerToken` tindakan tersebut ke pengguna IAM yang terkait dengan kunci tersebut. ### Contoh kebijakan #### Mencegah identitas membuat dan menggunakan kunci API CloudWatch Log ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "DenyCWLAPIKeys", "Effect": "Deny", "Action": [ "iam:CreateServiceSpecificCredential", "logs:CallWithBearerToken" ], "Resource": "*" } ] } ``` **Awas** Kebijakan ini akan mencegah pembuatan kredensi untuk semua AWS layanan yang mendukung pembuatan kredensi khusus layanan. Untuk informasi selengkapnya, lihat [Kredensi khusus layanan](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_service-specific-creds.html) untuk pengguna IAM. #### Mencegah identitas menggunakan kunci API CloudWatch Log ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "logs:CallWithBearerToken", "Resource": "*" } ] } ``` #### Izinkan pembuatan kunci CloudWatch Log hanya jika mereka kedaluwarsa dalam 90 hari ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:CreateServiceSpecificCredential", "Resource": "arn:aws:iam::123456789012:user/username", "Condition": { "StringEquals": { "iam:ServiceSpecificCredentialServiceName": "logs.amazonaws.com" }, "NumericLessThanEquals": { "iam:ServiceSpecificCredentialAgeDays": "90" } } } ] } ``` ## Memutar kunci API Memutar kunci API Anda secara teratur mengurangi risiko akses yang tidak sah. Sebaiknya buat jadwal rotasi yang sesuai dengan kebijakan keamanan organisasi Anda. ### Proses rotasi Untuk memutar kunci API tanpa mengganggu pengiriman log, ikuti prosedur ini: 1. Buat kredensi baru (sekunder) untuk pengguna IAM: ``` aws iam create-service-specific-credential \ --user-name cloudwatch-logs-hlc-user \ --service-name logs.amazonaws.com \ --credential-age-days 90 ``` 1. (Opsional) Simpan kredensi baru AWS Secrets Manager untuk pengambilan aman dan rotasi otomatis. 1. Impor kredensi baru ke portal vendor Anda atau perbarui konfigurasi aplikasi Anda untuk menggunakan kunci API baru. 1. Setel kredensi asli menjadi tidak aktif: ``` aws iam update-service-specific-credential \ --user-name cloudwatch-logs-hlc-user \ --service-specific-credential-id ACCA1234EXAMPLE1234 \ --status Inactive ``` 1. Verifikasi bahwa pengiriman log tidak terpengaruh dengan memantau `IncomingBytes` metrik untuk grup log Anda. CloudWatch Untuk informasi selengkapnya, lihat [Memantau dengan CloudWatch metrik](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html). 1. Setelah mengonfirmasi pengiriman yang berhasil dengan kunci baru, hapus kredensi sebelumnya: ``` aws iam delete-service-specific-credential \ --service-specific-credential-id ACCA1234EXAMPLE1234 ``` ### Memantau kedaluwarsa kunci Untuk memeriksa tanggal pembuatan dan status kunci API yang ada, gunakan [list-service-specific-credentials](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/list-service-specific-credentials.html)perintah: ``` aws iam list-service-specific-credentials \ --user-name cloudwatch-logs-hlc-user \ --service-name logs.amazonaws.com ``` Tanggapan tersebut mencakup `CreateDate` dan `Status` untuk setiap kredensi. Gunakan informasi ini untuk mengidentifikasi kunci yang mendekati kedaluwarsa atau telah aktif lebih lama dari yang diizinkan oleh kebijakan rotasi Anda. ## Menanggapi kunci API yang disusupi Jika Anda mencurigai bahwa kunci API telah disusupi, segera lakukan langkah-langkah berikut: 1. **Nonaktifkan kunci segera** untuk mencegah penggunaan tidak sah lebih lanjut: ``` aws iam update-service-specific-credential \ --user-name cloudwatch-logs-hlc-user \ --service-specific-credential-id ACCA1234EXAMPLE1234 \ --status Inactive ``` 1. **Tinjau CloudTrail log** untuk menentukan ruang lingkup akses yang tidak sah. Lihat [Pencatatan penggunaan kunci API dengan CloudTrail](#CWL_HTTP_Endpoints_CloudTrail_Logging) cara mengaktifkan audit penggunaan kunci API. 1. **Buat kunci pengganti** mengikuti proses rotasi yang dijelaskan dalam[Proses rotasi](#CWL_HTTP_Endpoints_Rotation_Process). 1. **Hapus kunci yang disusupi** setelah penggantian dilakukan: ``` aws iam delete-service-specific-credential \ --service-specific-credential-id ACCA1234EXAMPLE1234 ``` 1. **Lampirkan kebijakan penolakan** jika Anda perlu segera memblokir semua akses token pembawa untuk pengguna IAM saat Anda menyelidiki: ``` { "Version": "2012-10-17", "Statement": { "Effect": "Deny", "Action": "logs:CallWithBearerToken", "Resource": "*" } } ``` **catatan** Untuk melakukan tindakan ini melalui API, Anda harus mengautentikasi dengan AWS kredensi dan bukan dengan kunci API CloudWatch Log. Anda juga dapat menggunakan operasi IAM API berikut untuk mengelola kunci yang dikompromikan: + [ResetServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResetServiceSpecificCredential.html)— Setel ulang kunci untuk menghasilkan kata sandi baru tanpa menghapus kredensialnya. Kuncinya tidak boleh kedaluwarsa. ## Praktik keamanan terbaik untuk kunci API Ikuti praktik terbaik berikut ini untuk melindungi kunci API CloudWatch Log Anda: + **Jangan pernah menyematkan kunci API dalam kode sumber.** Jangan kode keras kunci API dalam kode aplikasi atau komit ke sistem kontrol versi. Jika kunci secara tidak sengaja berkomitmen ke repositori publik, pemindaian AWS otomatis dapat menandainya dan Anda harus segera memutar kunci tersebut. + **Gunakan manajer rahasia.** Simpan kunci API di [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)atau solusi manajemen rahasia yang setara. Ini memungkinkan kontrol akses terpusat, pencatatan audit, dan rotasi otomatis. + **Tetapkan kedaluwarsa pada semua tombol.** Selalu tentukan `--credential-age-days` nilai saat membuat kunci API. Untuk menerapkan masa pakai kunci maksimum di seluruh organisasi Anda, gunakan kunci kondisi `iam:ServiceSpecificCredentialAgeDays` IAM. Sebagai contoh, lihat [Izinkan pembuatan kunci CloudWatch Log hanya jika mereka kedaluwarsa dalam 90 hari](#CWL_HTTP_Endpoints_Allow_Expire_90). + **Terapkan izin hak istimewa paling sedikit.** Cakupan izin pengguna IAM hanya untuk grup log dan tindakan yang diperlukan. Gunakan kebijakan [CloudWatchLogsAPIKeyAkses](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) terkelola sebagai titik awal dan batasi lebih lanjut sesuai kebutuhan. + **Aktifkan CloudTrail logging.** Audit penggunaan kunci API dengan mengaktifkan peristiwa CloudTrail data untuk`AWS::Logs::LogGroupAuthorization`. Lihat [Pencatatan penggunaan kunci API dengan CloudTrail](#CWL_HTTP_Endpoints_CloudTrail_Logging). + **Monitor dengan IAM Access Analyzer.** Gunakan [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html) untuk mengidentifikasi kredensi yang tidak digunakan dan kebijakan yang terlalu permisif yang terkait dengan pengguna IAM kunci API Anda. + **Putar tombol secara teratur.** Tetapkan jadwal rotasi dan ikuti proses yang dijelaskan dalam[Memutar kunci API](#CWL_HTTP_Endpoints_Rotating_Keys). ## Pencatatan penggunaan kunci API dengan CloudTrail Anda dapat menggunakan AWS CloudTrail untuk mencatat peristiwa data untuk penggunaan kunci API CloudWatch Log. CloudWatch Log memancarkan peristiwa `AWS::Logs::LogGroupAuthorization` data untuk `CallWithBearerToken` panggilan, memungkinkan Anda untuk mengaudit kapan dan bagaimana kunci API digunakan untuk mengirim log. Untuk mengaktifkan CloudTrail logging untuk penggunaan kunci API CloudWatch Log: **catatan** Bucket S3 yang Anda tentukan untuk jejak harus memiliki kebijakan bucket yang memungkinkan CloudTrail untuk menulis file log ke dalamnya. Untuk informasi selengkapnya, lihat [kebijakan bucket Amazon S3](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/create-s3-bucket-policy-for-cloudtrail.html) untuk. CloudTrail 1. Buat jejak: ``` aws cloudtrail create-trail \ --name cloudwatch-logs-api-key-audit \ --s3-bucket-name my-cloudtrail-bucket \ --region us-east-1 ``` 1. Konfigurasikan pemilih acara lanjutan untuk menangkap peristiwa otorisasi grup CloudWatch log Log: ``` aws cloudtrail put-event-selectors \ --region us-east-1 \ --trail-name cloudwatch-logs-api-key-audit \ --advanced-event-selectors '[{ "Name": "CloudWatch Logs API key authorization events", "FieldSelectors": [ { "Field": "eventCategory", "Equals": ["Data"] }, { "Field": "resources.type", "Equals": ["AWS::Logs::LogGroupAuthorization"] } ] }]' ``` 1. Mulai pencatatan jejak: ``` aws cloudtrail start-logging \ --name cloudwatch-logs-api-key-audit \ --region us-east-1 ``` # Mengirim log menggunakan titik akhir OTLP (Log) OpenTelemetry Endpoint Logs (`/v1/logs`) menerima data OpenTelemetry log OpenTelemetry Protocol (OTLP) baik dalam pengkodean JSON atau Protobuf. Untuk informasi rinci tentang titik akhir OTLP, termasuk konfigurasi dan penggunaan, lihat [Mengirim metrik dan](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html) jejak ke with. CloudWatch OpenTelemetry Jika Anda menggunakan otentikasi token pembawa, selesaikan langkah-langkah penyiapan [Menyiapkan otentikasi token pembawa](CWL_HTTP_Endpoints_BearerTokenAuth.md) sebelum melanjutkan. ## Format permintaan + Metode: `POST` + Tipe Konten: atau `application/json` `application/x-protobuf` + Grup log: hanya `x-aws-log-group` header (parameter kueri tidak didukung) + Aliran log: `x-aws-log-stream` header ## Contoh permintaan ``` curl -X POST "https://logs..amazonaws.com/v1/logs" \ -H "Authorization: Bearer ACWL" \ -H "Content-Type: application/json" \ -H "x-aws-log-group: MyLogGroup" \ -H "x-aws-log-stream: MyLogStream" \ -d '{ "resourceLogs": [ { "resource": { "attributes": [ { "key": "service.name", "value": { "stringValue": "my-service" } } ] }, "scopeLogs": [ { "scope": { "name": "my-library", "version": "1.0.0" }, "logRecords": [ { "timeUnixNano": "1741900000000000000", "severityNumber": 9, "severityText": "INFO", "body": { "stringValue": "User logged in successfully" }, "attributes": [ { "key": "user.id", "value": { "stringValue": "12345" } } ] } ] } ] } ] }' ``` ## Respons **Sukses (semua acara diterima):** ``` HTTP 200 OK {} ``` **Keberhasilan sebagian (beberapa acara ditolak):** ``` { "partialSuccess": { "rejectedLogRecords": 5, "errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}" } } ``` Ketika permintaan Content-Type adalah`application/x-protobuf`, respon dikembalikan sebagai pesan `ExportLogsServiceResponse` protobuf serial dengan bidang yang sama. ## Perilaku khusus OTLP Perilaku berikut khusus untuk titik akhir OTLP dan tidak ada pada titik akhir konsumsi HTTP lainnya: + **Retry-After header** - Termasuk pada 503 dan 429 tanggapan untuk menunjukkan kapan klien harus mencoba lagi. # Mengirim log menggunakan titik akhir HLC (Log HLC) Titik akhir HLC Logs (`/services/collector/event`) didasarkan pada format HTTP Log Collector (HLC). Jika Anda menggunakan otentikasi token pembawa, selesaikan langkah-langkah penyiapan [Menyiapkan otentikasi token pembawa](CWL_HTTP_Endpoints_BearerTokenAuth.md) sebelum melanjutkan. ## Mode masukan Setiap peristiwa adalah objek JSON dengan `"event"` bidang wajib. Bidang metadata opsional:`"time"`,,`"host"`,`"source"`,`"sourcetype"`. `"index"` **Acara tunggal:** ``` {"event":"Hello world!","time":1486683865.0} ``` **JSON array acara:** ``` [ {"event":"msg1","time":1486683865.0}, {"event":"msg2","time":1486683866.0} ] ``` **Acara bergabung/batch (tidak ada pembungkus array):** ``` {"event":"msg1","time":1486683865.0}{"event":"msg2","time":1486683866.0} ``` ## Bidang acara (wajib) `"event"`Bidang itu wajib. Nilainya dapat berupa jenis JSON: ``` {"event":"a string message"} {"event":{"message":"structured data","severity":"INFO"}} {"event":42} {"event":true} ``` Objek tanpa `"event"` bidang dilewati secara diam-diam: ``` {"message":"this is skipped — no event field"} ``` ## Bidang waktu (opsional) `"time"`Bidang ini dalam detik epoch (bukan milidetik), dengan desimal opsional untuk presisi sub-detik. | format | Contoh | Ditafsirkan sebagai | | --- | --- | --- | | Desimal | "time":1486683865.500 | 1486683865500 ms | | Bilangan Bulat | "time":1486683865 | 1486683865000 ms | | String (mengapung) | "time":"1486683865.500" | 1486683865500 ms | | String (bilangan bulat) | "time":"1486683865" | 1486683865000 ms | | Hilang | (tidak ada bidang waktu) | Waktu server saat ini | | Tidak valid | "time":"invalid" | Waktu server saat ini | ## Content-Type Hanya `application/json` diterima. ## Jenis nilai JSON yang diterima | Tipe tingkat atas | Perilaku | | --- | --- | | Objek dengan "event" | Diterima | | Objek tanpa "event" | Dilewati | | Array objek | Setiap elemen diproses secara individual | | Objek yang digabungkan | Setiap objek diproses secara individual | | Primitif (string, angka, boolean, null) | Dilewati | ## Format titik akhir URL titik akhir HLC mengikuti format ini: ``` https://logs..amazonaws.com/services/collector/event?logGroup=&logStream=[&entityName=&entityEnvironment=] ``` **Parameter yang diperlukan:** + ``— AWS Wilayah (misalnya,`us-east-1`,`eu-west-1`) + `logGroup`— Nama grup log yang dikodekan URL + `logStream`— Nama aliran log yang dikodekan URL **Parameter opsional:** Anda dapat secara opsional mengaitkan peristiwa log Anda dengan `Service` entitas dengan menyertakan parameter kueri berikut. Karena log yang dikirim melalui titik akhir HLC adalah telemetri khusus, mereka tidak secara otomatis terkait dengan entitas. Dengan menyediakan parameter ini, CloudWatch Log membuat entitas dengan `KeyAttributes.Type` set ke `Service` dan mengaitkannya dengan peristiwa log Anda. Ini memungkinkan fitur **terkait Jelajahi** CloudWatch untuk menghubungkan log ini dengan telemetri lain (metrik, jejak, dan log) dari layanan yang sama, sehingga memudahkan pemecahan masalah dan memantau aplikasi Anda di berbagai jenis sinyal. Untuk informasi selengkapnya tentang entitas dan telemetri terkait, lihat [Menambahkan informasi terkait ke telemetri kustom](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html). + `entityName`— Nama entitas layanan untuk dikaitkan dengan peristiwa log. Nilai ini disimpan sebagai entitas `KeyAttributes.Name` (misalnya, `my-application` atau`api.myservice.com`). + `entityEnvironment`— Lingkungan tempat layanan di-host atau milik apa. Nilai ini disimpan sebagai entitas `KeyAttributes.Environment` (misalnya,, `production``ec2:default`, atau`eks:my-cluster/default`). ## Format permintaan Kirim log menggunakan HTTP POST dengan header dan badan berikut: **Header:** + `Authorization: Bearer ` + `Content-Type: application/json` **Format tubuh:** Badan permintaan harus dalam format JSON dengan array peristiwa: ``` { "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" } ] } ``` **Deskripsi bidang:** + `time`- Stempel waktu epoch Unix dalam hitungan detik, dengan desimal opsional untuk presisi sub-detik (opsional) + `event`— Pesan log atau data peristiwa (wajib) + `host`— Nama host sumber atau pengenal (opsional) + `source`— Pengidentifikasi sumber log (opsional) Bidang kustom tambahan dapat dimasukkan sesuai kebutuhan. ## Contoh permintaan ``` 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"}' ``` ## 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. # Mengirim log menggunakan titik akhir NDJSON (ND-JSON Logs) Titik akhir ND-JSON Logs (`/ingest/bulk`) menerima log dalam format [NDJSON (Newline Delimited JSON](https://github.com/ndjson/ndjson-spec)). Setiap baris berisi persis satu nilai JSON, dipisahkan oleh karakter baris baru. Jika Anda menggunakan otentikasi token pembawa, selesaikan langkah-langkah penyiapan [Menyiapkan otentikasi token pembawa](CWL_HTTP_Endpoints_BearerTokenAuth.md) sebelum melanjutkan. ## Format permintaan Kirim satu nilai JSON per baris, dipisahkan oleh `\n` (LF) atau `\r\n` (CRLF). Baris kosong diabaikan secara diam-diam. ``` {"timestamp":1771007942000,"message":"event one","level":"INFO"} {"timestamp":1771007943000,"message":"event two","level":"ERROR"} {"timestamp":1771007944000,"message":"event three","level":"DEBUG"} ``` Keduanya `application/json` dan `application/x-ndjson` diterima sebagai Content-Type. ## Jenis nilai JSON yang diterima Per spesifikasi NDJSON (RFC 8259), nilai JSON yang valid diterima pada setiap baris. **Objek JSON (paling umum):** ``` {"timestamp":1771007942000,"message":"User logged in","service":"auth"} {"timestamp":1771007943000,"error":"Connection timeout","service":"api"} ``` **Array JSON (diratakan menjadi peristiwa individual):** ``` [{"timestamp":1000,"message":"a"},{"timestamp":2000,"message":"b"}] ``` Baris tunggal ini menghasilkan 2 peristiwa. Setiap elemen array menjadi peristiwa log terpisah. **Nilai primitif:** ``` "a plain string log message" 42 true null ``` Setiap primitif menjadi acaranya sendiri dengan stempel waktu server saat ini. **Jenis campuran:** ``` {"timestamp":1771007942000,"message":"structured event"} "unstructured string message" 42 {"timestamp":1771007943000,"error":"something failed"} ``` Semua 4 baris diterima sebagai acara yang valid. | Konten baris | Perilaku | | --- | --- | | Objek JSON | Diterima, stempel waktu diekstraksi jika ada | | Array JSON | Diratakan - setiap elemen menjadi acara yang terpisah | | Array kosong [] | Diterima, menghasilkan 0 acara | | String JSON | Diterima sebagai pesan acara | | Nomor JSON | Diterima sebagai pesan acara | | Boolean JSON | Diterima sebagai pesan acara | | JSON nol | Diterima sebagai pesan acara | | JSON tidak valid | Dilewati (dihitung, pemrosesan berlanjut) | | Baris kosong | Diabaikan (tidak dihitung sebagai dilewati) | ## Bidang stempel waktu `"timestamp"`Bidang ini dalam milidetik epoch (bukan detik). | 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 | | Garis non-objek | "hello", 42, true | Waktu server saat ini | ## Baris tidak valid Baris yang tidak valid JSON dilewati dan dihitung secara diam-diam. Pemrosesan berlanjut dengan baris berikutnya. ``` {"message":"valid event"} this is not valid json {"message":"another valid event"} ``` Hasil: 2 acara tertelan, 1 dilewati. Pengembalian`HTTP 200`. Jika semua baris tidak valid, kembali `HTTP 400` dengan. `"All events were invalid"` ## Contoh permintaan ``` curl -X POST "https://logs..amazonaws.com/ingest/bulk?logGroup=MyLogGroup&logStream=MyStream" \ -H "Authorization: Bearer ACWL" \ -H "Content-Type: application/x-ndjson" \ -d '{"timestamp":1771007942000,"message":"User logged in","level":"INFO"} {"timestamp":1771007943000,"message":"Query took 42ms","level":"DEBUG"} {"timestamp":1771007944000,"error":"Connection refused","level":"ERROR"}' ``` ## Respons **Sukses (semua acara diterima):** ``` HTTP 200 OK {} ``` **Keberhasilan sebagian (beberapa acara ditolak):** ``` { "partialSuccess": { "rejectedLogRecords": 5, "errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}" } } ``` `rejectedLogRecords`Bidang adalah jumlah total peristiwa yang ditolak. `errorMessage`Bidang 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. # 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](CWL_HTTP_Endpoints_BearerTokenAuth.md) 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 \$1...\$1\$1...\$1 | 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..amazonaws.com/ingest/json?logGroup=MyLogGroup&logStream=MyStream" \ -H "Authorization: Bearer ACWL" \ -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}" } } ``` `rejectedLogRecords`Bidang adalah jumlah total peristiwa yang ditolak. `errorMessage`Bidang 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. ## Perbandingan titik akhir konsumsi HTTP | Fitur | Log HLC | Log ND-JSON | Log JSON Terstruktur | OpenTelemetry Log | | --- | --- | --- | --- | --- | | Jalan | /services/collector/event | /ingest/bulk | /ingest/json | /v1/logs | | Content-Type | application/json | application/json atau application/x-ndjson | application/json | application/json atau application/x-protobuf | | Bidang stempel waktu | "time"(detik) | "timestamp"(milidetik) | "timestamp"(milidetik) | "timeUnixNano"(nanodetik) | | Bidang yang diperlukan | "event" | Tidak ada | Tidak ada | Struktur OTLP () "resourceLogs" | | Respon keberhasilan sebagian | Tidak | Ya | Ya | Ya | | Dukungan parameter kueri | Ya | Ya | Ya | Tidak (hanya header) | | Metadata entitas | Ya | Ya | Ya | Tidak | | Menerima primitif | Tidak | Ya | Tidak | Tidak | | Penguraian berbasis garis | Tidak | Ya | Tidak | Tidak | | Dukungan Protobuf | Tidak | Tidak | Tidak | Ya | | Retry-After header | Tidak | Tidak | Tidak | Ya | ## Memilih titik akhir + **Menggunakan format HLC?** Gunakan Log HLC. Muatan HLC Anda yang ada berfungsi dengan sedikit perubahan. + ** line-by-lineLog streaming?** Gunakan Log ND-JSON. Terbaik untuk saluran pipa log yang memancarkan satu peristiwa per baris. Paling fleksibel - menerima jenis nilai JSON apa pun. + **Mengirim muatan JSON terstruktur?** Gunakan Log JSON Terstruktur. Terbaik untuk aplikasi yang menghasilkan objek atau array JSON yang terbentuk dengan baik. + **Sudah menggunakan OpenTelemetry?** Gunakan OpenTelemetry Log. Menerima format OTLP JSON atau Protobuf dan mendukung respons keberhasilan sebagian dengan semantik coba lagi.