翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# HLC エンドポイントを使用したログの送信 (HLC Logs)
<a name="CWL_HLC_Endpoint"></a>

HLC Logs エンドポイント (`/services/collector/event`) は、HTTP Log Collector (HLC) 形式に基づいています。

ベアラートークン認証を使用している場合は、続行する[ベアラートークン認証の設定](CWL_HTTP_Endpoints_BearerTokenAuth.md)前に のセットアップステップを完了してください。

## 入力モード
<a name="CWL_HLC_Input_Modes"></a>

各イベントは、`"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}
```

## イベントフィールド (必須)
<a name="CWL_HLC_Event_Field"></a>

`"event"` フィールドは必須です。その値は任意の JSON タイプにすることができます。

```
{"event":"a string message"}
{"event":{"message":"structured data","severity":"INFO"}}
{"event":42}
{"event":true}
```

`"event"` フィールドのないオブジェクトはサイレントにスキップされます。

```
{"message":"this is skipped — no event field"}
```

## 時間フィールド (オプション)
<a name="CWL_HLC_Time_Field"></a>

`"time"` フィールドはエポック秒 (ミリ秒ではなく) で、オプションで 10 進数は 1 秒未満の精度です。


| 形式 | 例 | 次のように解釈されます | 
| --- | --- | --- | 
| 浮動小数点数 | "time":1486683865.500 | 1486683865500 ミリ秒 | 
| 整数 | "time":1486683865 | 1486683865000 ミリ秒 | 
| 文字列 (浮動小数点) | "time":"1486683865.500" | 1486683865500 ミリ秒 | 
| 文字列 (整数) | "time":"1486683865" | 1486683865000 ミリ秒 | 
| Missing (見つからない) | (時間フィールドなし) | サーバーの現在の時刻 | 
| 無効 | "time":"invalid" | サーバーの現在の時刻 | 

## Content-Type
<a name="CWL_HLC_Content_Type"></a>

のみが受け入れられ`application/json`ます。

## 許容される JSON 値タイプ
<a name="CWL_HLC_Accepted_Types"></a>


| 最上位タイプ | 行動 | 
| --- | --- | 
| を使用したオブジェクト "event" | 承諾 | 
| なしのオブジェクト "event" | スキップ済み | 
| オブジェクトの配列 | 各要素は個別に処理されます | 
| 連結オブジェクト | 個別に処理される各オブジェクト | 
| プリミティブ (文字列、数値、ブール値、null) | スキップ済み | 

## エンドポイントフォーマット
<a name="CWL_HLC_Endpoint_Format"></a>

HLC エンドポイント URL は次の形式に従います。

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

**必須パラメータ:**
+ `<region>` – 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`として保存されます。

## リクエストの形式
<a name="CWL_HLC_Request_Format"></a>

次のヘッダーと本文を含む HTTP POST を使用してログを送信します。

**ヘッダー:**
+ `Authorization: Bearer <your-bearer-token>`
+ `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` – ログソース識別子 (オプション)

必要に応じて、追加のカスタムフィールドを含めることができます。

## リクエスト例
<a name="CWL_HLC_Example_Request"></a>

```
curl -X POST "https://logs.<region>.amazonaws.com/services/collector/event?logGroup=MyLogGroup&logStream=MyStream" \
  -H "Authorization: Bearer ACWL<token>" \
  -H "Content-Type: application/json" \
  -d '{"event":{"message":"User logged in","user_id":"u-123"},"time":1486683865.0,"host":"web-01","source":"auth-service"}'
```

## ベストプラクティス
<a name="CWL_HLC_Best_Practices"></a>

### イベントのバッチ処理
<a name="CWL_HLC_Batching"></a>

パフォーマンスと効率を向上させるには:
+ 可能であれば、1 つのリクエストで複数のイベントをバッチ処理する
+ 推奨バッチサイズ: リクエストあたり 10～100 イベント
+ 最大リクエストサイズ: 1 MB

### エラー処理
<a name="CWL_HLC_Error_Handling"></a>

アプリケーションに適切なエラー処理を実装します。一般的な HTTP ステータスコード:
+ `200 OK` – 正常に取り込まれたログ
+ `400 Bad Request` – 無効なリクエスト形式またはパラメータ
+ `401 Unauthorized` — 無効または期限切れのベアラートークン
+ `403 Forbidden` – アクセス許可が不十分
+ `404 Not Found` – ロググループまたはストリームが存在しません
+ `429 Too Many Requests` – レート制限を超えました
+ `500 Internal Server Error` – サービスエラー (エクスポネンシャルバックオフで再試行)

## 制限事項
<a name="CWL_HLC_Limitations"></a>
+ 最大イベントサイズ: イベントあたり 256 KB
+ 最大リクエストサイズ: 1 MB
+ リクエストあたりの最大イベント数: 10,000
+ ロググループ名は CloudWatch Logs の命名規則に従う必要があります
+ ベアラートークン認証を使用する場合は、ロググループでベアラートークン認証を有効にする必要があります。