翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# HTTP エンドポイントを介したログ取り込み
Amazon CloudWatch Logs には、シンプルな HTTP POST リクエストを使用して CloudWatch Logs に直接ログを送信できる HTTP エンドポイントが用意されています。これらのエンドポイントは、SigV4 トークン認証とベアラートークン認証の両方をサポートしています。
**重要**
AWS SDK 統合が可能なすべての本稼働ワークロードには、SigV4 認証を使用することをお勧めします。SigV4 は短期認証情報を使用し、最も強力なセキュリティ体制を提供します。ベアラートークン (API キー) 認証は、 AWS SDK 統合をサポートしていないサードパーティーのログフォワーダーなど、SigV4 が不可能なシナリオを対象としています。詳細については、*IAM ユーザーガイド*[の「長期アクセスキーの代替](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#bp-workloads-use-roles)」を参照してください。
CloudWatch Logs は、次の HTTP 取り込みエンドポイントをサポートしています。
| Endpoint | パス | Content-Type | 形式 |
| --- | --- | --- | --- |
| [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** > **Settings** > **Logs** に移動します。
1. API キー セクションで、**API キーの生成** を選択します。
1. **API キーの有効期限**について、以下のいずれかを実行します。
+ API キーの有効期限として **1**、**5**、**30**、**90**、または **365** 日を選択します。
+ **カスタム期間**を選択して、カスタム 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. 左のナビゲーションペインで、**[ユーザー]** を選択します。
1. **[ユーザーの作成]** を選択します。
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. **Next** を選択し、Create **user **を選択します。
**注記**
KMS で暗号化されたロググループにログを送信する場合は、KMS アクセス許可が必要です。この条件は、CloudWatch Logs サービスを介して使用されるキーのみに KMS アクセスを制限します。
### ステップ 2: サービス固有の認証情報を生成する (API キー)
CreateServiceSpecificCredential API を使用して CloudWatch Logs API キーを生成します。 [CreateServiceSpecificCredential](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateServiceSpecificCredential.html) [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 キーの使用を制御します。ID が CloudWatch Logs API キーを使用しないようにするには、キーに関連付けられた IAM ユーザーに`logs:CallWithBearerToken`アクションを拒否するポリシーをアタッチします。
### ポリシーの例
#### ID が 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)」を参照してください。
#### ID が 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 を使用してこれらのアクションを実行するには、CloudWatch Logs API キーではなく AWS 認証情報で認証する必要があります。
次の 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 CloudTrail ログ記録を有効にするには:
**注記**
証跡に指定する 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`) は、OpenTelemetry Protocol (OTLP) ログデータを JSON エンコードまたは Protobuf エンコードで受け入れます。設定や使用状況など、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" }
}
]
}
]
}
]
}
]
}'
```
## レスポンス
**Success (すべてのイベントが受け入れられる):**
```
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 Logs)
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"` フィールドはエポック秒 (ミリ秒ではなく) で、オプションで 10 進数は 1 秒未満の精度です。
| 形式 | 例 | 次のように解釈されます |
| --- | --- | --- |
| 浮動小数点数 | "time":1486683865.500 | 1486683865500 ミリ秒 |
| 整数 | "time":1486683865 | 1486683865000 ミリ秒 |
| 文字列 (浮動小数点) | "time":"1486683865.500" | 1486683865500 ミリ秒 |
| 文字列 (整数) | "time":"1486683865" | 1486683865000 ミリ秒 |
| Missing (見つからない) | (時間フィールドなし) | サーバーの現在の時刻 |
| 無効 | "time":"invalid" | サーバーの現在の時刻 |
## Content-Type
のみが受け入れられ`application/json`ます。
## 許容される JSON 値タイプ
| 最上位タイプ | 行動 |
| --- | --- |
| を使用したオブジェクト "event" | 承諾 |
| なしのオブジェクト "event" | スキップ済み |
| オブジェクトの配列 | 各要素は個別に処理されます |
| 連結オブジェクト | 個別に処理される各オブジェクト |
| プリミティブ (文字列、数値、ブール値、null) | スキップ済み |
## エンドポイントフォーマット
HLC エンドポイント URL は次の形式に従います。
```
https://logs..amazonaws.com/services/collector/event?logGroup=&logStream=[&entityName=&entityEnvironment=]
```
**必須パラメータ:**
+ `` – AWS リージョン (例: `us-east-1`、`eu-west-1`)
+ `logGroup` – URL エンコードされたロググループ名
+ `logStream` – URL エンコードされたログストリーム名
**オプションのパラメータ:**
オプションで、次のクエリパラメータを含めることで、ログイベントを`Service`エンティティに関連付けることができます。HLC エンドポイントを介して送信されるログはカスタムテレメトリであるため、自動的にエンティティに関連付けられません。これらのパラメータを指定することで、CloudWatch Logs は を `KeyAttributes.Type`に設定してエンティティを作成し`Service`、ログイベントに関連付けます。これにより、CloudWatch の **Explore 関連**機能は、これらのログを同じサービスの他のテレメトリ (メトリクス、トレース、ログ) と関連付けることができるため、さまざまなシグナルタイプのアプリケーションのトラブルシューティングとモニタリングが容易になります。エンティティおよび関連するテレメトリの詳細については、[「カスタムテレメトリへの関連情報の追加](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` (、、 など`ec2:default``eks:my-cluster/default`) `production`として保存されます。
## リクエストの形式
次のヘッダーと本文を含む 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 エポックタイムスタンプを秒単位で、オプションで 10 進数を秒未満の精度で指定 (オプション)
+ `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"}'
```
## ベストプラクティス
### イベントのバッチ処理
パフォーマンスと効率を向上させるには:
+ 可能であれば、1 つのリクエストで複数のイベントをバッチ処理する
+ 推奨バッチサイズ: リクエストあたり 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 Logs)
ND-JSON Logs エンドポイント (`/ingest/bulk`) は、[NDJSON (Newline Delimited JSON) ](https://github.com/ndjson/ndjson-spec)形式のログを受け入れます。各行には、改行文字で区切られた 1 つの JSON 値のみが含まれます。
ベアラートークン認証を使用している場合は、続行する[ベアラートークン認証の設定](CWL_HTTP_Endpoints_BearerTokenAuth.md)前に のセットアップステップを完了してください。
## リクエストの形式
(LF) または `\n` (CRLF) で区切って、行ごとに 1 つの `\r\n` JSON 値を送信します。空の行はサイレントに無視されます。
```
{"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"}]
```
この 1 行は 2 つのイベントを生成します。各配列要素は個別のログイベントになります。
**プリミティブ値:**
```
"a plain string log message"
42
true
null
```
各プリミティブは、サーバーの現在のタイムスタンプを持つ独自のイベントになります。
**混合型:**
```
{"timestamp":1771007942000,"message":"structured event"}
"unstructured string message"
42
{"timestamp":1771007943000,"error":"something failed"}
```
4 行はすべて有効なイベントとして受け入れられます。
| 行の内容 | 行動 |
| --- | --- |
| JSON オブジェクト | 受け入れられ、存在する場合はタイムスタンプが抽出されます |
| JSON 配列 | フラット化 – 各要素は個別のイベントになります |
| 空の配列 [] | 受け入れられ、0 個のイベントが生成されます |
| JSON 文字列。 | イベントメッセージとして受け入れられました |
| JSON 数値 | イベントメッセージとして受け入れられました |
| JSON ブール値 | イベントメッセージとして受け入れられました |
| JSON null | イベントメッセージとして受け入れられました |
| JSON が無効です | スキップ (カウント、処理続行) |
| 空の行 | 無視 (スキップとしてカウントされません) |
## タイムスタンプフィールド
`"timestamp"` フィールドはエポックミリ秒 (秒ではなく) です。
| 形式 | 例 | 次のように解釈されます |
| --- | --- | --- |
| 数値 (ミリ) | "timestamp":1771007942000 | 1771007942000 ミリ秒 |
| Missing (見つからない) | (タイムスタンプフィールドなし) | サーバーの現在の時刻 |
| 数値以外 | "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"}'
```
## レスポンス
**Success (すべてのイベントが受け入れられる):**
```
HTTP 200 OK
{}
```
**部分的な成功 (一部のイベントが拒否):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
`rejectedLogRecords` フィールドは、拒否されたイベントの総数です。`errorMessage` フィールドには、拒否理由別の JSON エンコードされた内訳が含まれます。
+ `tooOldLogEventCount` – タイムスタンプが保持期間より古いイベント
+ `tooNewLogEventCount` – タイムスタンプが遠すぎるイベント
+ `expiredLogEventCount` – 処理中に期限切れになったイベント
## ベストプラクティス
### イベントのバッチ処理
パフォーマンスと効率を向上させるには:
+ 可能であれば、1 つのリクエストで複数のイベントをバッチ処理する
+ 推奨バッチサイズ: リクエストあたり 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 ログエンドポイント (`/ingest/json`) は、単一の JSON オブジェクトまたはオブジェクトの JSON 配列の標準 JSON を受け入れます。このエンドポイントは、各イベントが JSON オブジェクトである構造化ログデータ用に設計されています。
ベアラートークン認証を使用している場合は、続行する[ベアラートークン認証の設定](CWL_HTTP_Endpoints_BearerTokenAuth.md)前に のセットアップステップを完了してください。
## リクエストの形式
Content-Type としてのみ`application/json`受け入れられます。
**単一の 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 | 行動 |
| --- | --- |
| 単一の JSON オブジェクト | 1 つのイベントとして受け入れられました |
| オブジェクトの 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"` フィールドは、NDJSON エンドポイントと同じエポックミリ秒単位です。
| 形式 | 例 | 次のように解釈されます |
| --- | --- | --- |
| 数値 (ミリ秒) | "timestamp":1771007942000 | 1771007942000 ミリ秒 |
| Missing (見つからない) | (タイムスタンプフィールドなし) | サーバーの現在の時刻 |
| 数値以外 | "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"}]'
```
## レスポンス
**Success (すべてのイベントが受け入れられる):**
```
HTTP 200 OK
{}
```
**部分的な成功 (一部のイベントが拒否):**
```
{
"partialSuccess": {
"rejectedLogRecords": 5,
"errorMessage": "{\"tooOldLogEventCount\": 3, \"tooNewLogEventCount\": 1, \"expiredLogEventCount\": 1}"
}
}
```
`rejectedLogRecords` フィールドは、拒否されたイベントの総数です。`errorMessage` フィールドには、拒否理由別の JSON エンコードされた内訳が含まれます。
+ `tooOldLogEventCount` – タイムスタンプが保持期間より古いイベント
+ `tooNewLogEventCount` – タイムスタンプが遠すぎるイベント
+ `expiredLogEventCount` – 処理中に期限切れになったイベント
## ベストプラクティス
### イベントのバッチ処理
パフォーマンスと効率を向上させるには:
+ 可能であれば、1 つのリクエストで複数のイベントをバッチ処理する
+ 推奨バッチサイズ: リクエストあたり 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 |
| Content-Type | 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 ログを使用します。1 行に 1 つのイベントを出力するログパイプラインに最適です。最も柔軟性が高い — 任意の JSON 値タイプを受け入れます。
+ **構造化された JSON ペイロードを送信しますか?** 構造化 JSON ログを使用します。正しい形式の JSON オブジェクトまたは配列を生成するアプリケーションに最適です。
+ **OpenTelemetry を既に使用していますか?** OpenTelemetry Logs を使用します。OTLP JSON または Protobuf 形式を受け入れ、再試行セマンティクスを使用した部分的な成功レスポンスをサポートします。