本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 透過 HTTP 端點記錄擷取 Amazon CloudWatch Logs 提供 HTTP 端點，可讓您使用簡單的 HTTP POST 請求將日誌直接傳送至 CloudWatch Logs。這些端點同時支援 SigV4 和承載字符身分驗證。 **重要** 我們建議對可以整合 AWS SDK 的所有生產工作負載使用 SigV4 身分驗證。SigV4 使用短期登入資料，並提供最強大的安全狀態。承載字符 (API 金鑰） 身分驗證適用於 SigV4 不可行的情況，例如不支援 AWS SDK 整合的第三方日誌轉送器。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[長期存取金鑰的替代方案](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles)。 CloudWatch Logs 支援下列 HTTP 擷取端點： | Endpoint | 路徑 | 內容類型 | 格式 | | --- | --- | --- | --- | | [OpenTelemetry Logs](CWL_HTTP_Endpoints_OTLP.md) | /v1/logs | application/json 或 application/x-protobuf | OTLP JSON 或 Protobuf | | [HLC Logs](CWL_HLC_Endpoint.md) | /services/collector/event | application/json | HLC 格式 | | [ND-JSON Logs](CWL_HTTP_Endpoints_NDJSON.md) | /ingest/bulk | application/json 或 application/x-ndjson | 換行分隔的 JSON | | [Structured JSON Logs](CWL_HTTP_Endpoints_StructuredJSON.md) | /ingest/json | application/json | JSON 物件或陣列 | ## 常見行為 所有 HTTP 擷取端點都共用下列行為： **身分驗證** 所有端點都支援 SigV4 和承載字符身分驗證： + **SigV4 （建議）** – 標準 AWS 簽章第 4 版簽署。每當您的應用程式或基礎設施支援 AWS SDK 或 可以簽署請求時，請使用 SigV4。SigV4 使用短期憑證，是最安全的身分驗證方法。 + **承載字符** – 使用 `Authorization: Bearer `標頭。 + 權杖必須是有效的 ACWL 承載權杖。如需設定說明，請參閱 [設定承載字符身分驗證](CWL_HTTP_Endpoints_BearerTokenAuth.md)。 + 需要 `logs:PutLogEvents`和 `logs:CallWithBearerToken` IAM 許可。 **日誌群組和日誌串流** + 透過標頭提供： `x-aws-log-group`和 `x-aws-log-stream` + 除了 `?logGroup=&logStream=` OTLP 之外，所有端點也支援查詢參數。 + 您無法對相同的參數同時使用查詢參數和標頭。 + 日誌群組和日誌串流都是必要的。 **回應** + 成功：`HTTP 200`使用內文 `{}` + 驗證錯誤： `HTTP 400` + 驗證失敗： `HTTP 401` # 設定承載字符身分驗證 在使用承載字符身分驗證與任何 HTTP 擷取端點傳送日誌之前，您需要： + 使用 CloudWatch Logs 許可建立 IAM 使用者 + 產生服務特定的登入資料 （承載字符） + 建立日誌群組和日誌串流 + 在日誌群組上啟用承載字符身分驗證 **重要** 我們建議針對所有工作負載使用 SigV4 身分驗證搭配短期登入資料，以達成此目的。SigV4 提供最強大的安全狀態。限制在短期憑證型身分驗證不可行的情況下使用 API 金鑰 （承載字符）。當您準備好將 CloudWatch Logs 納入具有更高安全需求的應用程式時，您應該切換到短期憑證。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[長期存取金鑰的替代方案](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles)。 ## 選項 1：使用 AWS 主控台快速開始使用 AWS 管理主控台提供簡化的工作流程，為 HTTP 端點存取產生 API 金鑰。 **使用主控台設定 HTTP 端點存取** 1. 登入 AWS 管理主控台。 1. 導覽至 **CloudWatch** > **設定** > **日誌**。 1. 在 API 金鑰區段中，選擇**產生 API 金鑰**。 1. 對於 **API 金鑰過期**，請執行下列其中一項操作： + 選取 **1**、**5**、**30**、**90** 或 **365** 天的 API 金鑰過期持續時間。 + 選擇**自訂持續時間**以指定自訂 API 金鑰過期日期。 + 選取**永不過期** （不建議）。 1. 選擇**產生 API 金鑰**。 主控台會自動： + 建立具有適當許可的新 IAM 使用者 + 連接 [CloudWatchLogsAPIKeyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) 受管政策 （包含 `logs:PutLogEvents`和 `logs:CallWithBearerToken`許可） + 產生服務特定的登入資料 (API 金鑰） 1. 複製並安全地儲存顯示的登入資料： + **API 金鑰 ID** （服務特定的登入資料 ID) + **API 金鑰秘密** （承載字符） **重要** 立即儲存 API 金鑰秘密。它稍後無法擷取。如果遺失，您將需要產生新的 API 金鑰。 1. 建立將存放日誌的日誌群組和日誌串流： ``` # 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. 在日誌群組上啟用承載字符身分驗證： ``` aws logs put-bearer-token-authentication \ --log-group-identifier /aws/hlc-logs/my-application \ --bearer-token-authentication-enabled \ --region us-east-1 ``` 驗證組態： ``` aws logs describe-log-groups \ --log-group-name-prefix /aws/hlc-logs/my-application \ --region us-east-1 ``` **包含的許可：**自動建立的 IAM 使用者將具有下列許可： + `logs:PutLogEvents` – 將日誌事件傳送至 CloudWatch Logs + `logs:CallWithBearerToken` – 使用承載字符進行驗證 + `kms:Describe*`、`kms:GenerateDataKey*`、 `kms:Decrypt` – 存取 KMS 加密日誌群組 （具有限制為日誌服務的條件） ## 選項 2：手動設定 如果您偏好對 IAM 組態進行更多控制，或需要自訂許可，您可以手動設定 HTTP 端點存取。 ### 步驟 1：建立 IAM 使用者 建立將用於日誌擷取的 IAM 使用者： 1. 登入 AWS 管理主控台並導覽至 IAM。 1. 在左側導覽窗格中，選擇 **Users (使用者)**。 1. 選擇 **Create user** (建立使用者)。 1. 輸入使用者名稱 （例如 `cloudwatch-logs-hlc-user`)。 1. 選擇**下一步**。 1. 連接下列其中一個 IAM 政策： **選項 A：使用 受管政策 （建議）** 連接 [CloudWatchLogsAPIKeyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) 受管政策。 **選項 B：建立自訂政策** 建立並連接下列 IAM 政策： ``` { "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. 選擇**下一步**，然後選擇**建立使用者**。 **注意** 如果您計劃將日誌傳送至 KMS 加密的日誌群組，則需要 KMS 許可。條件限制 KMS 只能存取透過 CloudWatch Logs 服務使用的金鑰。 ### 步驟 2：產生服務特定的登入資料 (API 金鑰） 使用 [CreateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceSpecificCredential.html) API 產生 CloudWatch Logs API 金鑰。您也可以使用 [create-service-specific-credential](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/create-service-specific-credential.html) CLI 命令。對於憑證存留期，您可以指定介於 1–36600 天之間的值。如果未指定憑證存留期，則 API 金鑰將不會過期。 若要產生過期 30 天的 API 金鑰： ``` aws iam create-service-specific-credential \ --user-name cloudwatch-logs-hlc-user \ --service-name logs.amazonaws.com \ --credential-age-days 30 ``` 回應是 [ServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ServiceSpecificCredential.html) 物件。`ServiceCredentialSecret` 值是您的 CloudWatch Logs API 金鑰 （承載字符）。 **重要** 請妥善儲存 `ServiceCredentialSecret` 值，因為您之後將無法再擷取它。如果遺失，您將需要產生新的 API 金鑰。 ### 步驟 3：建立日誌群組和日誌串流 建立將存放日誌的日誌群組和日誌串流： ``` # 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 ``` ### 步驟 4：啟用承載字符身分驗證 在日誌群組上啟用承載字符身分驗證： ``` aws logs put-bearer-token-authentication \ --log-group-identifier /aws/hlc-logs/my-application \ --bearer-token-authentication-enabled \ --region us-east-1 ``` 驗證組態： ``` aws logs describe-log-groups \ --log-group-name-prefix /aws/hlc-logs/my-application \ --region us-east-1 ``` ## 控制產生和使用 CloudWatch Logs API 金鑰的許可 CloudWatch Logs API 金鑰的產生和使用由 CloudWatch Logs 和 IAM 服務中的動作和條件金鑰控制。 ### 控制 CloudWatch Logs API 金鑰的產生 [iam：CreateServiceSpecificCredential](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsidentityandaccessmanagementiam.html#awsidentityandaccessmanagementiam-actions-as-permissions) 動作會控制產生服務特定的金鑰 （例如 CloudWatch Logs API 金鑰）。您可以將此動作的範圍限定為 IAM 使用者，以此限制可以為其產生金鑰的使用者。 您可以使用下列條件索引鍵，對 `iam:CreateServiceSpecificCredential` 動作的許可施加條件： + [iam:ServiceSpecificCredentialAgeDays](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) – 可讓您在條件中指定金鑰的過期時間，以天為單位。例如，您可以使用此條件索引鍵，僅允許建立有效期為 90 天的 API 金鑰。 + [iam:ServiceSpecificCredentialServiceName](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_iam-condition-keys.html#ck_ServiceSpecificCredentialAgeDays) – 可讓您在條件中指定服務的名稱。例如，您可以使用此條件金鑰來僅允許為 CloudWatch Logs 建立 API 金鑰，而非其他 服務。 ### 控制 CloudWatch Logs API 金鑰的使用 `logs:CallWithBearerToken` 動作控制 CloudWatch Logs API 金鑰的使用。若要防止身分使用 CloudWatch Logs API 金鑰，請將拒絕`logs:CallWithBearerToken`動作的政策連接至與金鑰相關聯的 IAM 使用者。 ### 政策範例 #### 防止身分產生和使用 CloudWatch Logs API 金鑰 ``` { "Version": "2012-10-17", "Statement": [ { "Sid": "DenyCWLAPIKeys", "Effect": "Deny", "Action": [ "iam:CreateServiceSpecificCredential", "logs:CallWithBearerToken" ], "Resource": "*" } ] } ``` **警告** 此政策將防止為所有支援建立服務特定登入資料的 AWS 服務建立登入資料。如需詳細資訊，請參閱 [IAM 使用者的服務特定憑證](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_service-specific-creds.html)。 #### 防止身分使用 CloudWatch Logs API 金鑰 ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "logs:CallWithBearerToken", "Resource": "*" } ] } ``` #### 只有在 CloudWatch Logs 金鑰在 90 天內過期時，才允許建立金鑰 ``` { "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" } } } ] } ``` ## 輪換 API 金鑰 定期輪換您的 API 金鑰可降低未經授權的存取風險。我們建議您建立符合您組織安全政策的輪換排程。 ### 輪換程序 若要在不中斷日誌交付的情況下輪換 API 金鑰，請遵循下列程序： 1. 為 IAM 使用者建立新的 （次要） 登入資料： ``` aws iam create-service-specific-credential \ --user-name cloudwatch-logs-hlc-user \ --service-name logs.amazonaws.com \ --credential-age-days 90 ``` 1. （選用） 將新登入資料存放在 中， AWS Secrets Manager 以安全擷取和自動輪換。 1. 將新登入資料匯入廠商的入口網站，或更新您的應用程式組態以使用新的 API 金鑰。 1. 將原始登入資料設定為非作用中： ``` aws iam update-service-specific-credential \ --user-name cloudwatch-logs-hlc-user \ --service-specific-credential-id ACCA1234EXAMPLE1234 \ --status Inactive ``` 1. 在 CloudWatch `IncomingBytes` 中監控日誌群組的指標，確認日誌交付未受到影響。如需詳細資訊，請參閱[使用 CloudWatch 指標監控使用量](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/CloudWatch-Logs-Monitoring-CloudWatch-Metrics.html)。 1. 使用新金鑰確認成功交付後，請刪除先前的登入資料： ``` aws iam delete-service-specific-credential \ --service-specific-credential-id ACCA1234EXAMPLE1234 ``` ### 監控金鑰過期 若要檢查現有 API 金鑰的建立日期和狀態，請使用 [list-service-specific-credentials](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/list-service-specific-credentials.html) 命令： ``` aws iam list-service-specific-credentials \ --user-name cloudwatch-logs-hlc-user \ --service-name logs.amazonaws.com ``` 回應包含每個登入`Status`資料的 `CreateDate`和 。使用此資訊來識別即將到期或已處於作用中狀態超過輪換政策允許的金鑰。 ## 回應遭入侵的 API 金鑰 如果您懷疑 API 金鑰已洩露，請立即採取下列步驟： 1. **立即停用金鑰**以防止進一步未經授權的使用： ``` aws iam update-service-specific-credential \ --user-name cloudwatch-logs-hlc-user \ --service-specific-credential-id ACCA1234EXAMPLE1234 \ --status Inactive ``` 1. **檢閱 CloudTrail 日誌**以判斷未經授權的存取範圍。如需如何啟用 API 金鑰用量的稽核[使用 CloudTrail 記錄 API 金鑰用量](#CWL_HTTP_Endpoints_CloudTrail_Logging)，請參閱 。 1. 依照中所述的輪換程序**建立替換金鑰**[輪換程序](#CWL_HTTP_Endpoints_Rotation_Process)。 1. 取代完成後**刪除遭入侵的金鑰**： ``` aws iam delete-service-specific-credential \ --service-specific-credential-id ACCA1234EXAMPLE1234 ``` 1. 如果您需要在調查時立即封鎖 IAM 使用者的所有承載字符存取，請**連接拒絕政策**： ``` { "Version": "2012-10-17", "Statement": { "Effect": "Deny", "Action": "logs:CallWithBearerToken", "Resource": "*" } } ``` **注意** 若要透過 API 執行這些動作，您必須使用 AWS 登入資料進行驗證，而不是使用 CloudWatch Logs API 金鑰進行驗證。 您也可以使用下列 IAM API 操作來管理遭到入侵的金鑰： + [ResetServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResetServiceSpecificCredential.html) – 重設金鑰以產生新密碼，而不刪除登入資料。金鑰不得已過期。 ## API 金鑰的安全最佳實務 遵循這些最佳實務來保護您的 CloudWatch Logs API 金鑰： + **切勿在原始程式碼中嵌入 API 金鑰。**請勿在應用程式程式碼中硬式編碼 API 金鑰，或將其遞交至版本控制系統。如果金鑰意外遞交到公有儲存庫， AWS 自動化掃描可能會標記它，您應該立即輪換金鑰。 + **使用秘密管理員。**將 API 金鑰存放在 [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)或同等的秘密管理解決方案中。這可啟用集中式存取控制、稽核記錄和自動輪換。 + **在所有金鑰上設定過期。**建立 API 金鑰時，請務必指定`--credential-age-days`值。若要在整個組織中強制執行最長金鑰生命週期，請使用 IAM `iam:ServiceSpecificCredentialAgeDays` 條件金鑰。如需範例，請參閱 [只有在 CloudWatch Logs 金鑰在 90 天內過期時，才允許建立金鑰](#CWL_HTTP_Endpoints_Allow_Expire_90)。 + **套用最低權限許可。**僅將 IAM 使用者的許可範圍限定為所需的日誌群組和動作。使用 受管 [CloudWatchLogsAPIKeyAccess](https://docs.aws.amazon.com/aws-managed-policy/latest/reference/CloudWatchLogsAPIKeyAccess.html) 政策作為起點，並視需要進一步限制。 + **啟用 CloudTrail 記錄。**透過啟用 的 CloudTrail 資料事件來稽核 API 金鑰用量`AWS::Logs::LogGroupAuthorization`。請參閱 [使用 CloudTrail 記錄 API 金鑰用量](#CWL_HTTP_Endpoints_CloudTrail_Logging)。 + **使用 IAM Access Analyzer 監控 。**使用 [IAM Access Analyzer](https://docs.aws.amazon.com/IAM/latest/UserGuide/what-is-access-analyzer.html) 識別未使用的登入資料，以及與您的 API 金鑰 IAM 使用者相關聯的過度寬鬆政策。 + **定期輪換金鑰。**建立輪換排程並遵循中所述的程序[輪換 API 金鑰](#CWL_HTTP_Endpoints_Rotating_Keys)。 ## 使用 CloudTrail 記錄 API 金鑰用量 您可以使用 AWS CloudTrail 記錄 CloudWatch Logs API 金鑰用量的資料事件。CloudWatch Logs 會發出`CallWithBearerToken`呼叫`AWS::Logs::LogGroupAuthorization`的資料事件，讓您稽核何時及如何使用 API 金鑰傳送日誌。 若要為 CloudWatch Logs API 金鑰用量啟用 CloudTrail 記錄： CloudWatch **注意** 您為線索指定的 S3 儲存貯體必須具有允許 CloudTrail 將日誌檔案寫入其中的儲存貯體政策。如需詳細資訊，請參閱 [ CloudTrail 的 Amazon S3 儲存貯體政策](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/create-s3-bucket-policy-for-cloudtrail.html)。 1. 建立線索： ``` aws cloudtrail create-trail \ --name cloudwatch-logs-api-key-audit \ --s3-bucket-name my-cloudtrail-bucket \ --region us-east-1 ``` 1. 設定進階事件選取器以擷取 CloudWatch Logs 日誌群組授權事件： ``` 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. 開始追蹤記錄： ``` aws cloudtrail start-logging \ --name cloudwatch-logs-api-key-audit \ --region us-east-1 ``` # 使用 OTLP 端點傳送日誌 (OpenTelemetry Logs) OpenTelemetry Logs 端點 (`/v1/logs`) 接受 JSON 或 Protobuf 編碼中的 OpenTelemetry Protocol (OTLP) 日誌資料。如需 OTLP 端點的詳細資訊，包括組態和用量，請參閱[使用 OpenTelemetry 將指標和追蹤傳送至 CloudWatch](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-OTLPEndpoint.html)。 如果您使用承載字符身分驗證，請先完成 中的設定步驟，[設定承載字符身分驗證](CWL_HTTP_Endpoints_BearerTokenAuth.md)再繼續。 ## 要求格式 + 方法： `POST` + Content-Type： `application/json`或 `application/x-protobuf` + 日誌群組：僅限 `x-aws-log-group` 標頭 （不支援查詢參數） + 日誌串流：`x-aws-log-stream`標頭 ## 範例請求 ``` 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" } } ] } ] } ] } ] }' ``` ## 回應 **成功 （接受所有事件）：** ``` HTTP 200 OK {} ``` **部分成功 （部分事件遭到拒絕）：** ``` { "partialSuccess": { "rejectedLogRecords": 5, "errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}" } } ``` 當請求 Content-Type 為 時`application/x-protobuf`，回應會以具有相同欄位的序列化 `ExportLogsServiceResponse` protobuf 訊息傳回。 ## OTLP 特定行為 下列行為是 OTLP 端點特有的行為，不會出現在其他 HTTP 擷取端點上： + **Retry-After 標頭** – 包含在 503 和 429 回應上，指出用戶端何時應重試。 # 使用 HLC 端點傳送日誌 (HLC 日誌） HLC Logs 端點 (`/services/collector/event`) 是以 HTTP Log Collector (HLC) 格式為基礎。 如果您使用承載字符身分驗證，請先完成 中的設定步驟，[設定承載字符身分驗證](CWL_HTTP_Endpoints_BearerTokenAuth.md)再繼續。 ## 輸入模式 每個事件都是具有必要`"event"`欄位的 JSON 物件。選用中繼資料欄位：`"time"`、`"host"`、`"source"`、`"sourcetype"`、`"index"`。 **單一事件：** ``` {"event":"Hello world!","time":1486683865.0} ``` **事件的 JSON 陣列：** ``` [ {"event":"msg1","time":1486683865.0}, {"event":"msg2","time":1486683866.0} ] ``` **串連/批次事件 （無陣列包裝函式）：** ``` {"event":"msg1","time":1486683865.0}{"event":"msg2","time":1486683866.0} ``` ## 事件欄位 （必要） 欄位為必要`"event"`欄位。其值可以是任何 JSON 類型： ``` {"event":"a string message"} {"event":{"message":"structured data","severity":"INFO"}} {"event":42} {"event":true} ``` 無 `"event"` 欄位的物件會無提示地略過： ``` {"message":"this is skipped — no event field"} ``` ## 時間欄位 （選用） `"time"` 欄位以 epoch 秒 （非毫秒） 為單位，選用小數表示次秒精確度。 | 格式 | 範例 | 解譯為 | | --- | --- | --- | | Float | "time":1486683865.500 | 1486683865500 毫秒 | | Integer | "time":1486683865 | 1486683865000 毫秒 | | 字串 （浮點數） | "time":"1486683865.500" | 1486683865500 毫秒 | | 字串 （整數） | "time":"1486683865" | 1486683865000 毫秒 | | 缺少 | （無時間欄位） | 伺服器目前時間 | | 無效 | "time":"invalid" | 伺服器目前時間 | ## 內容類型 僅接受 `application/json` 。 ## 接受的 JSON 值類型 | 最上層類型 | Behavior (行為) | | --- | --- | | 具有 的物件 "event" | 已接受 | | 沒有 的物件 "event" | 略過 | | 物件的陣列 | 個別處理的每個元素 | | 串連物件 | 個別處理的每個物件 | | 基本 （字串、數字、布林值、 null) | 略過 | ## 端點格式 HLC 端點 URL 遵循此格式： ``` https://logs..amazonaws.com/services/collector/event?logGroup=&logStream=[&entityName=&entityEnvironment=] ``` **必要參數：** + `` – AWS Region （例如，`us-east-1`、`eu-west-1`) + `logGroup` – URL 編碼的日誌群組名稱 + `logStream` – URL 編碼的日誌串流名稱 **選用參數：** 您可以選擇性地將日誌事件與`Service`實體建立關聯，方法是包含下列查詢參數。由於透過 HLC 端點傳送的日誌是自訂遙測，因此不會自動與實體建立關聯。透過提供這些參數，CloudWatch Logs 會建立將 `KeyAttributes.Type` 設定為 的實體，`Service`並將其與您的日誌事件建立關聯。這可讓 CloudWatch 中的**探索相關**功能將這些日誌與來自相同服務的其他遙測 （指標、追蹤和日誌） 建立關聯，讓您更輕鬆地疑難排解和監控不同訊號類型的應用程式。如需實體和相關遙測的詳細資訊，請參閱[將相關資訊新增至自訂遙測](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/adding-your-own-related-telemetry.html)。 + `entityName` – 要與日誌事件建立關聯的服務實體名稱。此值會儲存為實體 `KeyAttributes.Name`（例如 `my-application`或 `api.myservice.com`)。 + `entityEnvironment` – 託管服務或其所屬的環境。此值會儲存為實體 `KeyAttributes.Environment`（例如 `production`、 `ec2:default`或 `eks:my-cluster/default`)。 ## 要求格式 使用 HTTP POST 搭配下列標頭和內文來傳送日誌： **標頭：** + `Authorization: Bearer ` + `Content-Type: application/json` **內文格式：** 請求內文應為 JSON 格式，其中包含一系列事件： ``` { "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" } ] } ``` **欄位描述：** + `time` – 以秒為單位的 Unix epoch 時間戳記，選用小數表示次秒精確度 （選用） + `event` – 日誌訊息或事件資料 （必要） + `host` – 來源主機名稱或識別符 （選用） + `source` – 日誌來源識別符 （選用） 您可以視需要包含其他自訂欄位。 ## 範例請求 ``` 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"}' ``` ## 最佳實務 ### 批次處理事件 為了獲得更好的效能和效率： + 盡可能在單一請求中批次處理多個事件 + 建議的批次大小：每個請求 10–100 個事件 + 請求大小上限：1 MB ### 錯誤處理 在應用程式中實作適當的錯誤處理。常見的 HTTP 狀態碼： + `200 OK` – 日誌已成功擷取 + `400 Bad Request` – 無效的請求格式或參數 + `401 Unauthorized` – 承載字符無效或過期 + `403 Forbidden` – 許可不足 + `404 Not Found` – 日誌群組或串流不存在 + `429 Too Many Requests` – 超過速率限制 + `500 Internal Server Error` – 服務錯誤 （以指數退避重試） ## 限制 + 事件大小上限：每個事件 256 KB + 請求大小上限：1 MB + 每個請求的事件上限：10，000 + 日誌群組名稱必須遵循 CloudWatch Logs 命名慣例 + 如果使用承載字符身分驗證，則必須在日誌群組上啟用承載字符身分驗證。 # 使用 NDJSON 端點傳送日誌 (ND-JSON 日誌） ND-JSON Logs 端點 (`/ingest/bulk`) 接受 [NDJSON （換行分隔 JSON) 格式的](https://github.com/ndjson/ndjson-spec)日誌。每一行只包含一個 JSON 值，以換行字元分隔。 如果您使用承載字符身分驗證，請先完成 中的設定步驟，[設定承載字符身分驗證](CWL_HTTP_Endpoints_BearerTokenAuth.md)再繼續。 ## 要求格式 每行傳送一個 JSON 值，以 `\n`(LF) 或 `\r\n`(CRLF) 分隔。空白行會被無提示地忽略。 ``` {"timestamp":1771007942000,"message":"event one","level":"INFO"} {"timestamp":1771007943000,"message":"event two","level":"ERROR"} {"timestamp":1771007944000,"message":"event three","level":"DEBUG"} ``` `application/json` 和 都`application/x-ndjson`被接受為 Content-Type。 ## 接受的 JSON 值類型 根據 NDJSON 規格 (RFC 8259)，每行接受任何有效的 JSON 值。 **JSON 物件 （最常見）：** ``` {"timestamp":1771007942000,"message":"User logged in","service":"auth"} {"timestamp":1771007943000,"error":"Connection timeout","service":"api"} ``` **JSON 陣列 （扁平化為個別事件）：** ``` [{"timestamp":1000,"message":"a"},{"timestamp":2000,"message":"b"}] ``` 此單行會產生 2 個事件。每個陣列元素都會成為個別的日誌事件。 **基本值：** ``` "a plain string log message" 42 true null ``` 每個基本會成為具有伺服器目前時間戳記的專屬事件。 **混合類型：** ``` {"timestamp":1771007942000,"message":"structured event"} "unstructured string message" 42 {"timestamp":1771007943000,"error":"something failed"} ``` 所有 4 行都被接受為有效事件。 | 行內容 | Behavior (行為) | | --- | --- | | JSON 物件 | 已接受，如果有的話擷取時間戳記 | | JSON 陣列 | 平面化 – 每個元素都會成為個別的事件 | | 空陣列 [] | 已接受，會產生 0 個事件 | | JSON 字串 | 接受為事件訊息 | | JSON 號碼 | 接受為事件訊息 | | JSON 布林值 | 接受為事件訊息 | | JSON null | 接受為事件訊息 | | 無效的 JSON | 已略過 （已計算，處理會繼續） | | 空行 | 已忽略 （未計為略過） | ## 時間戳記欄位 `"timestamp"` 欄位以 epoch 毫秒 （非秒） 為單位。 | 格式 | 範例 | 解譯為 | | --- | --- | --- | | 數值 （毫秒） | "timestamp":1771007942000 | 1771007942000 毫秒 | | 缺少 | （無時間戳記欄位） | 伺服器目前時間 | | 非數值 | "timestamp":"invalid" | 伺服器目前時間 | | 非物件行 | "hello", 42, true | 伺服器目前時間 | ## 無效的行 非有效 JSON 的行會無提示地略過並計數。處理會繼續進行下一行。 ``` {"message":"valid event"} this is not valid json {"message":"another valid event"} ``` 結果：擷取 2 個事件，略過 1 個事件。傳回 `HTTP 200`。 如果所有行都無效， 會傳回 `HTTP 400`與 `"All events were invalid"`。 ## 範例請求 ``` 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"}' ``` ## 回應 **成功 （接受所有事件）：** ``` HTTP 200 OK {} ``` **部分成功 （部分事件遭到拒絕）：** ``` { "partialSuccess": { "rejectedLogRecords": 5, "errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}" } } ``` `rejectedLogRecords` 欄位是已拒絕事件的總數。`errorMessage` 欄位包含依拒絕原因分類的 JSON 編碼明細： + `tooOldLogEventCount` – 時間戳記早於保留期間的事件 + `tooNewLogEventCount` – 未來時間戳記太久的事件 + `expiredLogEventCount` – 處理期間過期的事件 ## 最佳實務 ### 批次處理事件 為了獲得更好的效能和效率： + 盡可能在單一請求中批次處理多個事件 + 建議的批次大小：每個請求 10–100 個事件 + 請求大小上限：1 MB ### 錯誤處理 在應用程式中實作適當的錯誤處理。常見的 HTTP 狀態碼： + `200 OK` – 日誌已成功擷取 + `400 Bad Request` – 無效的請求格式或參數 + `401 Unauthorized` – 承載字符無效或過期 + `403 Forbidden` – 許可不足 + `404 Not Found` – 日誌群組或串流不存在 + `429 Too Many Requests` – 超過速率限制 + `500 Internal Server Error` – 服務錯誤 （以指數退避重試） ## 限制 + 事件大小上限：每個事件 256 KB + 請求大小上限：1 MB + 每個請求的事件上限：10，000 + 日誌群組名稱必須遵循 CloudWatch Logs 命名慣例 + 如果使用承載字符身分驗證，則必須在日誌群組上啟用承載字符身分驗證。 # 使用結構化 JSON 端點傳送日誌 （結構化 JSON 日誌） 結構化 JSON Logs 端點 (`/ingest/json`) 接受標準 JSON – 單一 JSON 物件或物件的 JSON 陣列。此端點專為結構式日誌資料而設計，其中每個事件都是 JSON 物件。 如果您使用承載字符身分驗證，請先完成 中的設定步驟，[設定承載字符身分驗證](CWL_HTTP_Endpoints_BearerTokenAuth.md)再繼續。 ## 要求格式 僅`application/json`接受 做為 Content-Type。 **單一 JSON 物件：** ``` {"timestamp":1771007942000,"message":"single event","level":"INFO"} ``` **物件的 JSON 陣列：** ``` [ {"timestamp":1771007942000,"message":"event one","level":"INFO"}, {"timestamp":1771007943000,"message":"event two","level":"ERROR"} ] ``` ## 接受的 JSON 值類型 此端點很嚴格 – 僅接受 JSON 物件做為事件。 | Input | Behavior (行為) | | --- | --- | | 單一 JSON 物件 | 接受為一個事件 | | 物件的 JSON 陣列 | 每個物件都會成為個別的事件 | | 空陣列 [] | 已接受，會產生 0 個事件 | | 陣列中的非物件 （字串、數字等） | 略過 | | 最上層基本 ("hello"、42) | 略過 | | 串連物件 \$1...\$1\$1...\$1 | 僅剖析第一個物件 | **範例 – 混合類型的陣列：** ``` [ {"timestamp":1771007942000,"message":"valid object"}, "just a string", 42, {"timestamp":1771007943000,"message":"another valid object"} ] ``` 結果：擷取 2 個事件 （物件）、略過 2 個事件 （字串和數字）。 ## 時間戳記欄位 `"timestamp"` 欄位以 epoch 毫秒為單位，與 NDJSON 端點相同。 | 格式 | 範例 | 解譯為 | | --- | --- | --- | | 數值 （毫秒） | "timestamp":1771007942000 | 1771007942000 毫秒 | | 缺少 | （無時間戳記欄位） | 伺服器目前時間 | | 非數值 | "timestamp":"invalid" | 伺服器目前時間 | ## 範例請求 ``` 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"}]' ``` ## 回應 **成功 （接受所有事件）：** ``` HTTP 200 OK {} ``` **部分成功 （部分事件遭到拒絕）：** ``` { "partialSuccess": { "rejectedLogRecords": 5, "errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}" } } ``` `rejectedLogRecords` 欄位是已拒絕事件的總數。`errorMessage` 欄位包含依拒絕原因分類的 JSON 編碼明細： + `tooOldLogEventCount` – 時間戳記早於保留期間的事件 + `tooNewLogEventCount` – 未來時間戳記太久的事件 + `expiredLogEventCount` – 處理期間過期的事件 ## 最佳實務 ### 批次處理事件 為了獲得更好的效能和效率： + 盡可能在單一請求中批次處理多個事件 + 建議的批次大小：每個請求 10–100 個事件 + 請求大小上限：1 MB ### 錯誤處理 在應用程式中實作適當的錯誤處理。常見的 HTTP 狀態碼： + `200 OK` – 日誌已成功擷取 + `400 Bad Request` – 無效的請求格式或參數 + `401 Unauthorized` – 承載字符無效或過期 + `403 Forbidden` – 許可不足 + `404 Not Found` – 日誌群組或串流不存在 + `429 Too Many Requests` – 超過速率限制 + `500 Internal Server Error` – 服務錯誤 （以指數退避重試） ## 限制 + 事件大小上限：每個事件 256 KB + 請求大小上限：1 MB + 每個請求的事件上限：10，000 + 日誌群組名稱必須遵循 CloudWatch Logs 命名慣例 + 如果使用承載字符身分驗證，則必須在日誌群組上啟用承載字符身分驗證。 ## HTTP 擷取端點的比較 | 功能 | HLC 日誌 | ND-JSON 日誌 | 結構化 JSON 日誌 | OpenTelemetry 日誌 | | --- | --- | --- | --- | --- | | 路徑 | /services/collector/event | /ingest/bulk | /ingest/json | /v1/logs | | 內容類型 | application/json | application/json 或 application/x-ndjson | application/json | application/json 或 application/x-protobuf | | 時間戳記欄位 | "time" （秒） | "timestamp" （毫秒） | "timestamp" （毫秒） | "timeUnixNano" （奈秒） | | 必要欄位 | "event" | 無 | 無 | OTLP 結構 ("resourceLogs") | | 部分成功回應 | 否 | 是 | 是 | 是 | | 查詢參數支援 | 是 | 是 | 是 | 否 （僅限標頭） | | 實體中繼資料 | 是 | 是 | 是 | 否 | | 接受基本概念 | 否 | 是 | 否 | 否 | | 行型剖析 | 否 | 是 | 否 | 否 | | Protobuf 支援 | 否 | 否 | 否 | 是 | | Retry-After 標頭 | 否 | 否 | 否 | 是 | ## 選擇端點 + **使用 HLC 格式？** 使用 HLC 日誌。您現有的 HLC 承載會以最少的變更運作。 + **line-by-line串流日誌？** 使用 ND-JSON 日誌。最適合每行發出一個事件的日誌管道。最靈活 – 接受任何 JSON 值類型。 + **傳送結構化 JSON 承載？** 使用結構化 JSON 日誌。最適合產生格式正確的 JSON 物件或陣列的應用程式。 + **已使用 OpenTelemetry？** 使用 OpenTelemetry Logs。接受 OTLP JSON 或 Protobuf 格式，並支援部分成功回應與重試語意。