Amazon OpenSearch Ingestion 101: 主要メトリクスに対する CloudWatch アラームの設定

本記事は 2026 年 2 月 5 日 に公開された「Amazon OpenSearch Ingestion 101: Set CloudWatch alarms for key metrics」を翻訳したものです。

Amazon OpenSearch Ingestion は、Amazon OpenSearch Service や OpenSearch Serverless コレクションへのデータ取り込みを簡素化する、フルマネージドのサーバーレスデータパイプラインです。主要な概念は以下のとおりです。

• Source – パイプラインがデータを取り込む方法を指定する入力コンポーネントです。各パイプラインには 1 つの Source があり、プッシュベースまたはプルベースのいずれかです。
• Processors – 配信前にレコードのフィルタリング、変換、エンリッチメントを行う中間処理ユニットです。
• Sink – パイプラインがデータを発行する宛先を指定する出力コンポーネントです。1 つ以上の宛先にレコードを発行できます。
• Buffer – Source と Sink の間のレイヤーです。イベントの一時的なストレージとして機能し、Source を下流の Processors や Sink から分離します。Amazon OpenSearch Ingestion では、プッシュベースの Source 向けに永続バッファオプションも提供しています。
• Dead-letter queues (DLQs) – Sink への書き込みに失敗したレコードをキャプチャするために Amazon Simple Storage Service (Amazon S3) を設定し、エラー処理やトラブルシューティングに活用できます。

このエンドツーエンドのデータ取り込みサービスにより、インフラストラクチャを管理せずに、OpenSearch 環境へのデータ収集、処理、配信ができます。

本記事では、OpenSearch Ingestion パイプラインに対する Amazon CloudWatch アラームの設定を詳しく説明します。推奨アラームにとどまらず、パイプラインのボトルネックが Sink、データ送信先の OpenSearch クラスター、Processors、Source からの取り込み不足のいずれにあるかを特定する方法を解説します。OpenSearch Ingestion パイプラインの監視やトラブルシューティングに役立ちます。

概要

OpenSearch Ingestion パイプラインの監視は、問題の早期発見と対処に欠かせません。主要なメトリクスを理解し、適切なアラームを設定することで、データ取り込みワークフローの健全性とパフォーマンスを管理できます。以降のセクションでは、Source、Processor、Sink のアラームメトリクスを詳しく説明します。アラームに使用するしきい値、期間、アラームのデータポイント数は、個々のユースケースや要件に応じて異なります。

前提条件

OpenSearch Ingestion パイプラインの作成については、Amazon OpenSearch Ingestion パイプラインの作成を参照してください。CloudWatch アラームの作成については、静的しきい値に基づく CloudWatch アラームの作成を参照してください。

OpenSearch Ingestion パイプラインのログ記録を有効にすると、パイプラインの操作や取り込みアクティビティ中のエラー、警告、情報メッセージなどのログがキャプチャされます。パイプラインログの有効化と監視の詳細は、パイプラインログの監視を参照してください。

Sources

パイプラインのエントリポイントは、監視を開始すべき場所です。Source コンポーネントに適切なアラームを設定することで、取り込みのボトルネックや接続の問題を迅速に特定できます。以下の表に、Source ごとの主要なアラームメトリクスをまとめます。

Processors

以下の表に、Processor ごとのアラームメトリクスの詳細を示します。

Sink と DLQ

以下の表に、Sink と DLQ のアラームメトリクスの詳細を示します。

Buffer

以下の表に、Buffer のアラームメトリクスの詳細を示します。

リファレンスガイド

パイプラインの一般的な問題を解決するためのガイダンスです。

REF-001: WARN レベルのログ確認

パイプラインログの WARN レベルのログを確認して、例外の詳細を特定してください。

REF-002: ERROR レベルのログ確認

パイプラインログの ERROR レベルのログを確認して、例外の詳細を特定してください。

REF-003: S3 オブジェクトの失敗

s3ObjectsFailed.count の値が増加している場合のトラブルシューティングでは、以下のメトリクスを監視して根本原因を絞り込んでください。

• s3ObjectsAccessDenied.count – パイプラインが S3 オブジェクトの読み取り時に Access Denied または Forbidden エラーが発生した場合にインクリメントされます。一般的な原因は以下のとおりです。
• パイプラインロールの権限不足。
• パイプラインロールのアクセスを許可しない制限的な S3 バケットポリシー。
• クロスアカウントの S3 バケットの場合、bucket_owners マッピングの設定が正しくない。
• s3ObjectsNotFound.count – パイプラインが S3 オブジェクトの読み取りを試みた際に Not Found エラーを受信した場合にインクリメントされます。

推奨アクションについてさらにサポートが必要な場合は、AWS サポートにお問い合わせください。

REF-004: Amazon DynamoDB Source の totalOpenShards.max と activeShardsInProcessing.value の差分アラームの設定

1. https://console.aws.amazon.com/cloudwatch/ で CloudWatch コンソールを開きます。
2. ナビゲーションペインで Alarms、All alarms を選択します。
3. Create alarm を選択します。
4. Select Metric を選択します。
5. Source を選択します。
6. Source で、<sub-pipeline-name>、<pipeline-name>、<region> を更新した以下の JSON を使用できます。

   {
       "metrics": [
           [ { "expression": "m1-e1", "label": "Expression2", "id": "e2", "period": 900 } ],
           [ { "expression": "FLOOR((m2/15)+0.5)", "label": "Expression1", "id": "activeShardsInProcessing", "visible": false, "period": 900 } ],
           [ "AWS/OSIS", "<sub-pipeline-name>.dynamodb.totalOpenShards.max", "PipelineName", "<pipeline-name>", { "stat": "Maximum", "id": "m1", "visible": false } ],
           [ ".", "<sub-pipeline name>.dynamodb.activeShardsInProcessing.value", ".", ".", { "stat": "Average", "id": "m2", "visible": false } ]
       ],
       "view": "timeSeries",
       "stacked": false,
       "period": 900,
       "region": "<region>"
   }

上記のメトリクスに基づくいくつかのシナリオを見てみましょう。

シナリオ 1 – パイプラインレイテンシーの理解と低減

パイプライン内のレイテンシーは、主に 3 つの要素で構成されます。

• バルクリクエストで OpenSearch にドキュメントを送信するのにかかる時間
• データがパイプラインの Processor を通過するのにかかる時間
• データがパイプラインバッファに滞留する時間

バルクリクエストと Processor (上記リストの最初の 2 つ) が、バッファの蓄積とレイテンシーの根本原因です。

バッファに格納されているデータ量を監視するには、bufferUsage.value メトリクスを監視します。バッファ内のレイテンシーを低減する唯一の方法は、ボトルネックの所在に応じて、パイプラインの Processor と Sink のバルクリクエストレイテンシーを最適化することです。

bulkRequestLatency メトリクスは、リトライを含むバルクリクエストの実行時間を測定し、OpenSearch Sink への書き込みパフォーマンスの監視に使用できます。このメトリクスが異常に高い値を示す場合、OpenSearch Sink が過負荷状態にあり、処理時間が増加していることを示します。さらに調査するには、bulkRequestNumberOfRetries.count メトリクスを確認して、高レイテンシーがスロットリング (429 エラー) などによる OpenSearch からのリジェクトに起因するリトライによるものかどうかを確認してください。ドキュメントエラーがある場合は、設定済みの DLQ を調べて、失敗したドキュメントの詳細を確認してください。また、パイプライン設定で max_retries パラメータを設定してリトライ回数を制限できます。ただし、documentErrors メトリクスがゼロ、bulkRequestNumberOfRetries.count もゼロで、bulkRequestLatency が高いままの場合は、OpenSearch Sink が過負荷状態である可能性が高いです。この場合は、宛先のメトリクスを確認して詳細を調べてください。

bulkRequestLatency メトリクスが低く (例: 1.5 秒未満)、bulkRequestNumberOfRetries メトリクスが 0 の場合、ボトルネックはパイプラインの Processor にある可能性が高いです。Processor のパフォーマンスを監視するには、<processorName>.timeElapsed.avg メトリクスを確認してください。このメトリクスは、Processor がレコードのバッチ処理を完了するのにかかった時間を報告します。例えば、Grok Processor が他の Processor よりも timeElapsed の値が大幅に高い場合、Grok パターンが遅いことが原因である可能性があり、ユースケースに応じてパターンの最適化やより高性能な Processor への置き換えを検討できます。

シナリオ 2 – OpenSearch へのドキュメントエラーの理解と解決

documentErrors.count メトリクスは、バルクリクエストで送信に失敗したドキュメントの数を追跡します。失敗は、マッピングの競合、無効なデータ形式、スキーマの不一致など、さまざまな原因で発生する可能性があります。このメトリクスがゼロ以外の値を報告する場合、一部のドキュメントが OpenSearch によって拒否されていることを示します。根本原因を特定するには、設定済みの Dead Letter Queue (DLQ) を調べてください。DLQ には、失敗したドキュメントとエラーの詳細がキャプチャされています。DLQ は、不正なフィールドタイプ、必須フィールドの欠落、サイズ制限を超えるデータなどのパターンを特定するための情報を提供します。例えば、一般的な問題のサンプル DLQ オブジェクトを以下に示します。

Mapper parsing exception:

{"dlqObjects": [{
        "pluginId": "opensearch",
        "pluginName": "opensearch",
        "pipelineName": "<PipelineName>",
        "failedData": {
            "index": "<IndexName>",
            "indexId": null,
            "status": 400,
            "message": "failed to parse field [<fieldname>] of type [integer] in document with id '<DocumentId>'. Preview of field's value: 'N/A' caused by For input string: \"N/A\"",
            "document": {<OriginalDocument>}
        },
        "timestamp": "…"
    }]}

ここでは、OpenSearch が数値専用のフィールドにテキスト文字列「N/A」を格納できないため、ドキュメントを拒否して DLQ に格納しています。

Limit of total fields exceeded:

{"dlqObjects": [{
        "pluginId": "opensearch",
        "pluginName": "opensearch",
        "pipelineName": "<PipelineName>",
        "failedData": {
            "index": "<IndexName>",
            "indexId": null,
            "status": 400,
            "message": "Limit of total fields [<field limit>] has been exceeded",
            "document": {<OriginalDocument>}
        },
        "timestamp": "…"
    }]}

index.mapping.total_fields.limit 設定は、インデックスマッピングで許可されるフィールドの最大数を制御するパラメータで、この制限を超えるとインデックス操作が失敗します。すべてのフィールドが必要かどうかを確認するか、OpenSearch Ingestion が提供するさまざまな Processor を活用してデータを変換してください。

問題を特定したら、ソースデータを修正するか、パイプライン設定を調整してデータを適切に変換するか、OpenSearch のインデックスマッピングを変更して受信データの形式に対応してください。

クリーンアップ

OpenSearch Ingestion パイプラインの監視用アラームを設定する際は、発生する可能性のあるコストに注意してください。設定する各アラームには、CloudWatch の料金モデルに基づいて料金が発生します。

不要な費用を避けるため、アラームの要件を慎重に評価して適切に設定してください。ユースケースに不可欠なアラームのみを設定し、アラーム設定を定期的に見直して、未使用または冗長なアラームを特定して削除してください。

まとめ

本記事では、CloudWatch アラームによる OpenSearch Ingestion パイプラインの監視について、Source、Processor、Sink の主要なメトリクスを取り上げて解説しました。本記事では最も重要なメトリクスを取り上げましたが、さらに詳しい情報については以下のリソースを参照してください。

• 推奨 CloudWatch アラーム
• Amazon OpenSearch Ingestion パイプラインでサポートされるプラグインとオプション
• パイプラインメトリクスの監視

CloudWatch アラームで取り込みパイプラインの健全性を維持し、最適なデータフローを確保しましょう。

著者について

この記事は Kiro が翻訳を担当し、Solutions Architect の 榎本 貴之 がレビューしました。