本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 HLC 端點將日誌傳送至 CloudWatch Logs

Amazon CloudWatch Logs 支援 HTTP Log Collector (HLC) 端點，可讓您使用簡單的 HTTP 型通訊協定將日誌直接傳送至 CloudWatch Logs。此功能可簡化應用程式和服務的記錄擷取，而不需要 AWS SDK 整合。

HLC 端點功能可讓您：

先決條件

在使用 HLC 端點傳送日誌之前，您需要：

選項 1：使用 AWS 主控台簡化設定 （建議）

AWS 管理主控台提供簡化的工作流程，為 HLC 端點存取產生 API 金鑰。

包含的許可：自動建立的 IAM 使用者將具有下列許可：

選項 2：手動設定

如果您偏好對 IAM 組態進行更多控制，或需要自訂許可，您可以手動設定 HLC 端點。

步驟 1：建立 IAM 使用者

建立將用於日誌擷取的 IAM 使用者：

步驟 2：產生服務特定的登入資料 (API 金鑰）

使用 CreateServiceSpecificCredential API 產生 CloudWatch Logs API 金鑰。您也可以使用 create-service-specific-credential 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 物件。ServiceCredentialSecret 值是您的 CloudWatch Logs 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

將日誌傳送至 HLC 端點

端點格式

HLC 端點 URL 遵循此格式：

https://logs.<region>.amazonaws.com/services/collector/event?logGroup=<name>&logStream=<name>[&entityName=<name>&entityEnvironment=<environment>]

必要參數：

選用參數：

您可以選擇性地將日誌事件與Service實體建立關聯，方法是包含下列查詢參數。由於透過 HLC 端點傳送的日誌是自訂遙測，因此不會自動與實體建立關聯。透過提供這些參數，CloudWatch Logs 會建立將 KeyAttributes.Type 設定為 的實體，Service並將其與您的日誌事件建立關聯。這可讓 CloudWatch 中的探索相關功能將這些日誌與來自相同服務的其他遙測 （指標、追蹤和日誌） 建立關聯，讓您更輕鬆地疑難排解和監控不同訊號類型的應用程式。如需實體和相關遙測的詳細資訊，請參閱將相關資訊新增至自訂遙測。

要求格式

使用 HTTP POST 搭配下列標頭和內文來傳送日誌：

標頭：

內文格式：

請求內文應為 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"
        }
    ]
}

欄位描述：

您可以視需要包含其他自訂欄位。

範例請求

curl -X POST \
    'https://logs.<region>.amazonaws.com/services/collector/event?logGroup=/aws/hlc-logs/my-application&logStream=application-stream-001' \
    -H "Authorization: Bearer <your-bearer-token>" \
    -H "Content-Type: application/json" \
    -d '{
        "event": [
            {
                "time": 1730141374.001,
                "event": "Application started",
                "host": "web-server-1",
                "severity": "info"
            }
        ]
    }'

控制產生和使用 CloudWatch Logs API 金鑰的許可

CloudWatch Logs API 金鑰的產生和使用由 CloudWatch Logs 和 IAM 服務中的動作和條件金鑰控制。

控制 CloudWatch Logs API 金鑰的產生

iam：CreateServiceSpecificCredential 動作會控制產生服務特定的金鑰 （例如 CloudWatch Logs API 金鑰）。您可以將此動作的範圍限定為 IAM 使用者，以此限制可以為其產生金鑰的使用者。

您可以使用下列條件索引鍵，對 iam:CreateServiceSpecificCredential 動作的許可施加條件：

控制 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": "*"
        }
    ]
}

防止身分使用 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"
                }
            }
        }
    ]
}

處理遭入侵的 CloudWatch Logs API 金鑰

如果您的 API 金鑰已洩露，您應該撤銷使用它的許可。您可以使用下列 IAM API 操作來管理遭到入侵的金鑰：

變更 CloudWatch Logs API 金鑰的狀態

若要停用金鑰，請使用 update-service-specific-credential 命令：

aws iam update-service-specific-credential \
    --user-name cloudwatch-logs-hlc-user \
    --service-specific-credential-id ACCA1234EXAMPLE1234 \
    --status Inactive

若要重新啟用金鑰，請將狀態變更為 Active。

重設 CloudWatch Logs API 金鑰

如果金鑰的值已洩露或您不再擁有，請使用 reset-service-specific-credential 命令將其重設。金鑰必須尚未過期。如果已過期，請刪除金鑰並建立新的金鑰。

aws iam reset-service-specific-credential \
    --service-specific-credential-id ACCA1234EXAMPLE1234

刪除 CloudWatch Logs API 金鑰

如果您不再需要金鑰或金鑰已過期，請使用 delete-service-specific-credential 命令將其刪除：

aws iam delete-service-specific-credential \
    --service-specific-credential-id ACCA1234EXAMPLE1234

連接 IAM 政策以移除使用 CloudWatch Logs API 金鑰的許可

若要防止身分使用 CloudWatch Logs API 金鑰進行呼叫，請將下列政策連接至與金鑰相關聯的 IAM 使用者：

{
    "Version": "2012-10-17",
    "Statement": {
        "Effect": "Deny",
        "Action": "logs:CallWithBearerToken",
        "Resource": "*"
    }
}

使用 CloudTrail 記錄 API 金鑰用量

您可以使用 AWS CloudTrail 記錄 CloudWatch Logs API 金鑰用量的資料事件。CloudWatch Logs 會發出CallWithBearerToken呼叫AWS::Logs::LogGroupAuthorization的資料事件，讓您稽核何時及如何使用 API 金鑰傳送日誌。

若要為 CloudWatch Logs API 金鑰用量啟用 CloudTrail 記錄： CloudWatch

最佳實務

批次處理事件

為了獲得更好的效能和效率：

錯誤處理

在應用程式中實作適當的錯誤處理。常見的 HTTP 狀態碼：

限制