Amazon Kinesis Streams
開発者ガイド
Amazon Kinesis Streams 開発者ガイド
Amazon Kinesis Streams: 開発者ガイド
Copyright © 2017 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any
manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other
trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to,
or sponsored by Amazon.
Amazon Kinesis Streams 開発者ガイド
Table of Contents
Amazon Kinesis Streams とは? ...................................................................................................... 1
Streams の機能 .................................................................................................................... 1
Streams のメリット .............................................................................................................. 2
関連サービス ........................................................................................................................ 2
主要なコンセプト .................................................................................................................. 2
アーキテクチャの概要 ................................................................................................... 2
用語 ............................................................................................................................ 3
Streams ............................................................................................................................... 5
Amazon Kinesis Stream の初期サイズを決定する .............................................................. 5
ストリームの作成 .......................................................................................................... 6
プロデューサー ..................................................................................................................... 6
コンシューマー ..................................................................................................................... 7
制限 .................................................................................................................................... 7
はじめに ...................................................................................................................................... 9
セットアップ ........................................................................................................................ 9
AWS にサインアップする .............................................................................................. 9
ライブラリとツールをダウンロードする ......................................................................... 10
開発環境を設定する ..................................................................................................... 10
チュートリアル: ウェブトラフィックの可視化 ......................................................................... 10
Streams のデータ可視化サンプルアプリケーション .......................................................... 11
前提条件 .................................................................................................................... 11
ステップ 1: サンプルアプリケーションを起動する ........................................................... 11
ステップ 2: サンプルアプリケーションのコンポーネントを表示する ................................... 12
ステップ 3: サンプルアプリケーションを削除する ........................................................... 15
ステップ 4: 次のステップ ............................................................................................. 16
チュートリアル: CLI を使用した作業の開始 ............................................................................ 16
AWS CLI のインストールと設定 .................................................................................... 16
基本的なストリームオペレーションの実行 ...................................................................... 18
Amazon Kinesis Streams 開発の学習 ............................................................................................. 24
第 1 部: ストリーム、プロデューサー、およびコンシューマー ................................................... 24
前提条件 .................................................................................................................... 25
ステップ 1: ストリームを作成する ................................................................................. 26
ステップ 2: IAM ポリシーとユーザーを作成する .............................................................. 27
ステップ 3: 実装コードをダウンロードおよびビルドする .................................................. 30
ステップ 4: プロデューサーを実装する ........................................................................... 30
ステップ 5: コンシューマーを実装する ........................................................................... 33
ステップ 6: （オプション）コンシューマーを拡張する ..................................................... 36
ステップ 7: 終了する ................................................................................................... 37
Amazon Kinesis Streams の使用 ................................................................................................... 39
ストリームへのデータの書き込み .......................................................................................... 39
KPL の使用 ................................................................................................................ 39
API の使用 ................................................................................................................. 49
エージェントの使用 ..................................................................................................... 54
トラブルシューティング ............................................................................................... 63
高度なトピック ........................................................................................................... 64
ストリームからのデータの読み取り ....................................................................................... 66
KCL の使用 ................................................................................................................ 66
API の使用 ................................................................................................................. 82
トラブルシューティング ............................................................................................... 86
高度なトピック ........................................................................................................... 89
ストリームの管理 ................................................................................................................ 96
ストリームの作成 ........................................................................................................ 96
ストリームのリスト ..................................................................................................... 98
ストリームからシャードを取得する ............................................................................... 99
ストリームを削除する .................................................................................................. 99
iii
Amazon Kinesis Streams 開発者ガイド
ストリームをリシャーディングする ..............................................................................
データ保持期間の変更 ................................................................................................
モニタリング ....................................................................................................................
CloudWatch によるサービスのモニタリング ..................................................................
CloudWatch によるエージェントのモニタリング ............................................................
CloudTrail を使用した API 呼び出しのログ記録 ..............................................................
CloudWatch による KCL のモニタリング ......................................................................
CloudWatch による KPL のモニタリング ......................................................................
ストリームのタグ付け ........................................................................................................
タグの基本 ...............................................................................................................
タグ付けを使用したコストの追跡 .................................................................................
タグの制限 ...............................................................................................................
Streams コンソールを使用したストリームのタグ付け .....................................................
AWS CLI を使用したストリームのタグ付け ...................................................................
Streams API を使用したストリームのタグ付け ..............................................................
アクセスの制御 .................................................................................................................
ポリシー構文 ............................................................................................................
Streams のアクション ................................................................................................
Streams 用の Amazon リソースネーム（ARN） .............................................................
Streams のポリシー例 ................................................................................................
ドキュメント履歴 ......................................................................................................................
AWS の用語集 ..........................................................................................................................
iv
100
105
105
106
114
114
118
126
130
130
131
131
131
132
132
133
133
134
134
135
138
140
Amazon Kinesis Streams 開発者ガイド
Streams の機能
Amazon Kinesis Streams とは?
Amazon Kinesis Streams を使用して、データレコードの大量のストリームをリアルタイムで収集し、
処理します。
「Amazon Kinesis Streams application」と呼ばれるデータ処理アプリケーションを作成します。一
般的な Amazon Kinesis Streams application は、データを Amazon Kinesis stream からデータレコー
ドとして読み込みます。これらのアプリケーションは Amazon Kinesis Client Library を使用すること
も、Amazon EC2 インスタンスで実行することもできます。処理されたレコードは、ダッシュボー
ドに送信してアラートの生成や、料金設定と広告戦略の動的変更に使用できます。また、他のさま
ざまな AWS サービスにデータを送信できます。Streams の機能と料金については、Amazon Kinesis
Streams を参照してください。
Streams は Amazon Kinesis Firehose と共にストリーミングデータ プラットフォーム、Amazon
Kinesis の一部です。詳細については、「Amazon Kinesis Firehose 開発者ガイド」を参照してくださ
い。AWS ビッグデータソリューションの詳細については、ビッグデータを参照してください。AWS
ストリーミングデータソリューションの詳細については、「ストリーミングデータとは?」を参照して
ください。
Streams の機能
Streams を使用して、高速かつ継続的にデータの取り込みと集約を行うことができます。使用される
データのタイプには、IT インフラストラクチャのログデータ、アプリケーションのログ、ソーシャル
メディア、マーケットデータフィード、ウェブのクリックストリームデータなどがあります。データ
の取り込みと処理の応答時間はリアルタイムであるため、処理は一般的に軽量です。
以下に示しているのは、Streams の一般的なユースケースです。
ログとデータフィードの取り込みと処理の高速化
プロデューサーからストリームにデータを直接プッシュさせることができます。たとえば、シス
テムとアプリケーションのログをプッシュすると、数秒で処理可能になります。これにより、フ
ロントエンドサーバーやアプリケーションサーバーに障害が発生した場合に、ログデータが失わ
れることを防止できます。Streams では、取り込み用にデータを送信する前にサーバーでバッチ
処理しないため、データフィードの取り込みが加速されます。
リアルタイムのメトリックスとレポート作成
Streams に取り込んだデータを使用して、リアルタイムのデータ分析とレポート作成を簡単に行
うことができます。たとえば、データ処理アプリケーションは、バッチデータを受け取るまで待
1
Amazon Kinesis Streams 開発者ガイド
Streams のメリット
つのではなく、データのストリーミング中にシステムおよびアプリケーションのログに関するメ
トリックスやレポート作成を操作できます。
リアルタイムデータ分析
これにより、並行処理の能力がリアルタイムデータの価値と同時に得られます。たとえば、ウェ
ブサイトのクリックストリームをリアルタイムで処理し、さらに並行して実行される複数の異な
る Streams アプリケーションを使用して、サイトの使いやすさの関与を分析します。
複雑なストリーム処理
Amazon Kinesis Streams application とデータストリームの Directed Acyclic Graphs（DAG）を作
成できます。一般的に、ここでは複数の Amazon Kinesis Streams application から別のストリー
ムにデータを出力して、別の Amazon Kinesis Streams application により下流処理が行われるよ
うにします。
Streams のメリット
Streams は、さまざまなデータストリーミングの問題解決に使用できるだけでなく、一般的にはデー
タのリアルタイム集計にも使用できます。集計データはその後でデータウェアハウスや MapReduce
クラスターに読み込むことができます。
データは Amazon Kinesis streamに取り込むことができ、それによって耐久性と適応性が確保されま
す。レコードがストリームに取り込まれてから取得されるまでの遅延（入力から取得までの遅延）は
通常、1 秒未満です。つまり、Amazon Kinesis Streams applicationはデータが追加されてからほぼ瞬
時にストリームのデータを利用し始めることができます。Streams はマネージド型サービスであるた
め、データ取り込みパイプラインの作成と実行にかかわる運用負荷が軽くなります。MapReduce 型
のストリーム処理アプリケーションを作成できること、さらに Streams に適応性があることで、スト
リームをスケールアップまたはダウンできるため、データレコードを有効期限になる前に失うことが
なくなります。
複数の Amazon Kinesis Streams application が 1 つのストリームからデータを消費できるため、アー
カイブや処理のような複数のアクションを同時に独立して実行できます。たとえば、2 つのアプリ
ケーションが、同じストリームからデータを読み取ることができます。最初のアプリケーションは、
集計を実行して計算し、DynamoDB テーブルを更新します。2 番目のアプリケーションは、データを
圧縮して Amazon S3 などのデータストアにアーカイブします。集計実行中の DynamoDB テーブル
は、その後、最新レポート用にダッシュボードによって読み取られます。
Amazon Kinesis Client Library を使用すると、耐障害性を維持しながらストリームからデータを消費す
ることができ、Amazon Kinesis Streams application に対するスケーリングも可能になります。
関連サービス
Amazon EMR クラスターを使用して Amazon Kinesis stream を直接読み取って処理する方法の例につ
いては、『Amazon EMR 開発者ガイド』の「Analyze Streams Data」を参照してください。
Amazon Kinesis Streams の主要なコンセプト
Amazon Kinesis Streams の使用を開始すると、アーキテクチャーと用語を理解していることが強みに
なります。
Streams のアーキテクチャの概要
以下の図に、Streams のアーキテクチャの概要を示します。プロデューサーは継続的にデータを
Streams にプッシュし、コンシューマーはリアルタイムでデータを処理します。コンシューマーは
2
Amazon Kinesis Streams 開発者ガイド
用語
Amazon DynamoDB、Amazon Redshift、Amazon S3 などの AWS サービスを使用してその結果を保
存できます。
Streams の用語
Amazon Kinesis Stream
Amazon Kinesis stream は、データレコードの順序付けられたシーケンスです。ストリーム内の各レ
コードには、Streams によってシーケンス番号 (p. 4)が割り当てられます。ストリーム内のデータ
レコードはシャード (p. 4)に配分されます。
データレコード
データレコードは、Amazon Kinesis stream (p. 3) に格納されるデータの単位です。データレコー
ドは、シーケンス番号 (p. 4)、パーティションキー (p. 4)、データ BLOB（変更不可のバイト
シーケンス）で構成されます。Streams では、BLOB 内のデータが検査、解釈、変更されることはあ
りません。データ BLOB は 最大 1 MB にすることができます。
保持期間
ストリームに追加された後の、データレコードにアクセス可能な期間。ストリームの保持期間は、デ
フォルトで作成後 24 時間に設定されます。IncreaseStreamRetentionPeriod オペレーションを使用
して、保持期間を最大 168 時間（7 日）まで増やしたり、DecreaseStreamRetentionPeriod オペレー
ションを使用して最短の 24 時間に短縮したりできます。追加料金は 24 時間を超えて保持されたスト
リームに適用されます。詳細については、「Amazon Kinesis Streams 料金表」を参照してください。
プロデューサー
プロデューサはレコードを Amazon Kinesis Streams に入れます。たとえば、ストリームにログデー
タを送信するウェブサーバーはプロデューサーです。
コンシューマー
コンシューマーは、Amazon Kinesis Streams からレコードを取得して処理します。これらのコン
シューマーは Amazon Kinesis Streams Applications (p. 4) と呼ばれます。
3
Amazon Kinesis Streams 開発者ガイド
用語
Amazon Kinesis Streams Applications
Amazon Kinesis Streams application はストリームのコンシューマーで、一般的に複数の EC2 インス
タンスで実行されます。
Amazon Kinesis Streams application は、Amazon Kinesis Client Library または Streams API を使用し
て開発できます。
Amazon Kinesis Streams application の出力を別のストリームの入力にすることで、リアルタイムで
データを処理する複雑なトポロジを作成できます。アプリケーションは、さまざまな他の AWS サー
ビスにデータを送信することもできます。複数のアプリケーションが 1 つのストリームを使用して、
各アプリケーションが同時にかつ独立してストリームからデータを消費できます。
シャード
シャードは、ストリーム内のデータレコードの一意に識別されたグループです。ストリームは複数の
シャードで構成され、各シャードが容量の 1 単位になります。各シャードは 読み取りは最大 1 秒あた
り 5 件のトランザクション、データ読み取りの最大合計レートは 1 秒あたり 2 MB と 書き込みについ
ては最大 1 秒あたり 1,000 レコード、データの最大書き込み合計レートは 1 秒あたり 1 MB (パーティ
ションキーを含む) をサポートできます。ストリームのデータ容量は、ストリームに指定したシャード
の数によって決まります。ストリームの総容量はシャードの容量の合計です。
データの流量が増えた場合は、シャードを追加してストリームのサイズを増やします。同様に、デー
タの流量が減った場合は、シャードを削除できます。
パーティションキー
パーティションキーは、ストリーム内のデータをシャード単位でグループ化するために使用されま
す。Streams サービスでは、ストリームに属するデータレコードを複数のシャードに配分するとき、
各データレコードに関連付けられたパーティションキーを使用して、配分先のシャードを決定しま
す。パーティションキーは最大 256 バイト長の Unicode 文字列です。MD5 ハッシュ関数を使用して
パーティションキーを 128 ビットの整数値にマッピングし、関連付けられたデータレコードをシャー
ドにマッピングします。パーティションキーは、ストリームにデータを入力するアプリケーションに
よって指定されます。
シーケンス番号
各データレコードには一意のシーケンス番号があります。シーケンス番号は、client.putRecords
または client.putRecord によってストリームに書き込んだ後に、Streams によって割り当てられ
ます。同じパーティションキーのシーケンス番号は一般的に、時間の経過とともに大きくなります。
書き込みリクエスト間の期間が長くなるほど、シーケンス番号は大きくなります。
Note
シーケンス番号は、同じストリーム内の一連のデータのインデックスとして使用すること
はできません。一連のデータを論理的に区別するには、パーティションキーを使用するか、
データセットごとに個別のストリームを作成します。
Amazon Kinesis Client Library
Amazon Kinesis Client Library をアプリケーションにコンパイルすることで、耐障害性を維持しながら
ストリームからデータを消費できます。Amazon Kinesis Client Library により、シャードごとにその実
行と処理用のレコードプロセッサが確保されます。また、ストリームからのデータの読み取りが簡素
化されます。Amazon Kinesis Client Library は Amazon DynamoDB テーブルを使用して制御データを
格納します。また、データを処理するアプリケーションごとに 1 つのテーブルを作成します。
4
Amazon Kinesis Streams 開発者ガイド
Streams
アプリケーション名
Amazon Kinesis Streams application 名はアプリケーションを識別します。各アプリケーションには、
アプリケーションが使用する AWS アカウントとリージョンに限定される一意の名前が必要です。こ
の名前は、Amazon DynamoDB では制御テーブルの名前として、Amazon CloudWatch では名前空間
メトリックとして使用されます。
Amazon Kinesis Stream
Amazon Kinesis Streams は、大量のデータをリアルタイムで取り込み、そのデータを永続的に保存し
て、消費できるようにします。Streams サービスによって保存されるデータの単位は、データレコー
ドです。ストリームは、データレコードの順序付けられたシーケンスを意味します。ストリーム内の
データレコードはシャードに配分されます。
シャードは、ストリーム内のデータレコードのグループです。ストリームを作成するときに、スト
リームのシャード数を指定します。各シャードは 読み取りは最大 1 秒あたり 5 件のトランザクショ
ン、データ読み取りの最大合計レートは 1 秒あたり 2 MB と 書き込みについては最大 1 秒あたり
1,000 レコード、データの最大書き込み合計レートは 1 秒あたり 1 MB (パーティションキーを含む)
をサポートできます。ストリームの総容量はシャードの容量の合計です。必要に応じて、ストリーム
のシャードの数を増減することができます。ただし、シャード単位で請求されることにご注意くださ
い。
プロデューサー (p. 6)はシャードにデータレコードを送信し、コンシューマー (p. 7)はシャー
ドからデータレコードを取得します。
Amazon Kinesis Stream の初期サイズを決定する
ストリームの作成前に、ストリームの初期サイズを決定する必要があります。ストリームを作成した
後、Amazon Kinesis Streams application がストリームからデータを消費している間も、ストリームの
サイズを動的に変更したり、シャードの追加ゃ削除を行うことができます。
ストリームの初期サイズを決定するには、以下の入力値が必要です。
• ストリームに書き込まれるデータレコードの平均サイズ（近似の KB 単位まで切り上げられま
す）。つまり、データサイズ（average_data_size_in_KB）です。
• 1 秒間にストリームで読み書きされるデータレコードの数（records_per_second）です。
• ストリームから同時にかつ独立してデータを消費する Amazon Kinesis Streams application、つまり
コンシューマーの数（number_of_consumers）です。
• KB 単位での受信書き込み帯域幅（incoming_write_bandwidth_in_KB）です。
average_data_size_in_KB を records_per_second に乗算した値に等しくなります。
• KB 単位の送信読み取り帯域幅（outgoing_read_bandwidth_in_KB）です。
incoming_write_bandwidth_in_KB を number_of_consumers に乗算した値に等しくなりま
す。
決定した入力値を以下の式に使用して、ストリームに必要なシャードの初期数
（number_of_shards）を計算できます。
number_of_shards = max(incoming_write_bandwidth_in_KB/1000,
outgoing_read_bandwidth_in_KB/2000)
5
Amazon Kinesis Streams 開発者ガイド
ストリームの作成
ストリームの作成
Streams コンソール、Streams API、または AWS CLI を使用してストリームを作成できます。
コンソールを使用してストリームを作成するには
1.
https://console.aws.amazon.com/kinesis/ にある Streams コンソールを開きます。
2.
ナビゲーションバーで、リージョンセレクターを展開し、リージョンを選択します。
3.
[Create Stream] をクリックします。
4.
[Create Stream] ページで、ストリームの名前と必要なシャードの数を入力し、[Create] をクリッ
クします。
ストリームの作成中、[Stream List] ページでは、ストリームの [Status] は、[] です。CREATINGス
トリームを使用する準備ができると、[Status] は [ACTIVE] に変わります。
5.
ストリームの名前をクリックします。[Stream Details] ページには、ストリーム設定の概要とモニ
タリング情報が表示されます。
Streams API を使用してストリームを作成するには
Streams API を使用したストリームの作成については、「ストリームの作成 (p. 96)」を参照してく
ださい。
AWS CLI を使用してストリームを作成するには
AWS CLI を使用したストリームの作成については、create-stream コマンドを参照してください。
Amazon Kinesis Streams のプロデューサー
プロデューサーは Amazon Kinesis stream にデータレコードを送信します。たとえば、Amazon
Kinesis stream にログデータを送信するウェブサーバーはプロデューサーです。コンシュー
マー (p. 7)はストリームのデータレコードを処理します。
Important
データレコードはストリームに追加されてからデフォルトでは 24 時間アクセス可能です。こ
の期間は、保持期間と呼ばれ、24 時間から 168 時間 (1～7 日) まで 1 時間単位で設定できま
す。ストリームの保持期間の詳細については、「データ保持期間の変更 (p. 105)」を参照し
てください。
ストリームにデータを送信するには、ストリームの名前、パーティションキー、ストリームに追加す
るデータ BLOB を指定する必要があります。パーティションキーは、データレコードが追加されるス
トリーム内のシャードを決定するために使用されます。
シャード内のすべてのデータは、そのシャードを処理する同じワーカーに送信されます。使用す
るパーティションキーはアプリケーションのロジックによって異なります。パーティションキーの
数は、通常、シャード数よりかなり大きくする必要があります。これは、データレコードを特定の
シャードにマッピングする方法を決定するために、パーティションキーが使用されるからです。十分
なパーティションキーがある場合、ストリーム内のシャードに均等にデータを分散することができま
す。
詳細については、「ストリームへのデータの追加 (p. 50)」（Java のコード例を含む）、Streams
API の PutRecords と PutRecord オペレーション、または put-record コマンドを参照してください。
6
Amazon Kinesis Streams 開発者ガイド
コンシューマー
Amazon Kinesis Streams のコンシューマー
コンシューマー (p. 6)は、Amazon Kinesis Streams application と呼ばれる Amazon Kinesis
stream からデータレコードを取得して、ストリームからのデータを処理します。
Important
データレコードはストリームに追加されてからデフォルトでは 24 時間アクセス可能です。こ
の期間は、保持期間と呼ばれ、24 時間から 168 時間 (1～7 日) まで 1 時間単位で設定できま
す。ストリームの保持期間の詳細については、「データ保持期間の変更 (p. 105)」を参照し
てください。
コンシューマーは、それぞれ特定のシャードから、シャードイテレーターを使用して読み込みま
す。シャードイテレーターは、ストリーム内の位置を表し、コンシューマーはそこから読み込みま
す。ストリームからの読み取りを開始すると、コンシューマーはシャードイテレーターを取得しま
す。これは、コンシューマーがストリームから読み取る場所を変更できます。コンシューマーが読
み込み操作を実行するときは、シャードイテレーターによって指定された位置に基づいて、データレ
コードのバッチを受け取ります。
各コンシューマーには、アプリケーションが使用する AWS アカウントとリージョンに限定される一
意の名前が必要です。この名前は、Amazon DynamoDB では制御テーブルの名前として、Amazon
CloudWatch では名前空間メトリックとして使用されます。アプリケーションを起動すると、アプリ
ケーションの状態を格納する Amazon DynamoDB テーブルを作成し、指定されたストリームに接続し
て、ストリームからデータを消費し始めます。Streams メトリックスは、CloudWatch コンソールを
使用して表示できます。
EC2 インスタンスにコンシューマーをデプロイするには、AMI のいずれか 1 つに追加します。Auto
Scaling グループの複数の EC2 インスタンスで実行することにより、コンシューマーを拡張できま
す。Auto Scaling グループを使用すると、EC2 インスタンスに障害が発生した場合に新しいインスタ
ンスを自動的に起動するようにしたり、アプリケーションの負荷の経時変化に応じてインスタンス数
を柔軟にスケーリングすることもできます。Auto Scaling グループは、一定数の EC2 インスタンスが
常に実行されているようにします。Auto Scaling グループのスケーリングイベントをトリガーするに
は、CPU やメモリの使用率などのメトリックスを指定して、ストリームからのデータを処理する EC2
インスタンスの数を増減させることができます。詳細については、「Auto Scaling ユーザーガイド」
を参照してください。
Amazon Kinesis Client Library（KCL）を使用して、複数の EC2 インスタンスで複数のワーカーを動
作させることにより、ストリームの並行処理を簡素化できます。KCL により、ストリーム内のシャー
ドからデータを読み込むコードをより簡単に記述できるようになり、ストリーム内の各シャードに
ワーカーが確実に割り当てられます。KCL は、耐障害性に役立つチェックポイント機能も提供しま
す。KCL の使用を開始する場合、まずは「Amazon Kinesis Client Library を使用した Amazon Kinesis
Streams コンシューマーの開発 (p. 66)」の例を確認することをお勧めします。
Amazon Kinesis Streams の制限
Streams には次の制限があります。
• デフォルトのシャード制限は、次のリージョンのみ 50 シャードです。
• 米国東部（バージニア北部）
• 米国西部 (オレゴン)
• 欧州 (アイルランド)
その他のリージョンでは、デフォルトのシャード制限は 25 です。
ストリームまたはアカウント内のシャードの数に上限はありません。シャード制限の増加をリクエ
ストするには、「Streams Limits form」を使用します。
7
Amazon Kinesis Streams 開発者ガイド
制限
• データレコードはストリームに追加されてからデフォルトでは 24 時間アクセス可能です。この期
間は、保持期間と呼ばれ、24 時間から 168 時間 (1～7 日) まで 1 時間単位で設定できます。スト
リームの保持期間の詳細については、「データ保持期間の変更 (p. 105)」を参照してください。
• データ BLOB（Base64 エンコーディング前のデータペイロード）の最大サイズは、最大 1 MB で
す。
• CreateStream、DeleteStream、ListStreams は、1 秒間に最大 5 件のトランザクションを提供でき
ます。
• MergeShards と SplitShard は、1 秒間に最大 5 件のトランザクションを提供できます。
• DescribeStream は、1 秒間に最大 10 件のトランザクションを提供できます。
• GetShardIterator は、各オープンシャードで 1 秒間に最大 5 件のトランザクションを提供できま
す。
• GetRecords は、10 MBのデータを取得できます。
• 各シャードは、読み取りは最大 1 秒あたり 5 件のトランザクション、データ読み取りの最大合計
レートは 1 秒あたり 2 MBをサポートできます。
• 各シャードは、書き込みについては最大 1 秒あたり 1,000 レコード、データの最大書き込み合計
レートは 1 秒あたり 1 MB (パーティションキーを含む)をサポートできます。この書き込みの制限
は、PutRecord や PutRecords などのオペレーションに適用されます。
• GetShardIterator によって返されたシャードイテレーターは、使用されない場合、5 分後にタイムア
ウトになります。
読み取り制限は OPEN 状態のシャードの数に基づきます。シャードの状態の詳細については、「リ
シャーディング後のデータのルーティング、データの永続化、シャードの状態 (p. 104)」を参照して
ください。
これらの制限の多くは API アクションに関連するものです。詳細については、『Amazon Kinesis API
Reference』を参照してください。
8
Amazon Kinesis Streams 開発者ガイド
セットアップ
Amazon Kinesis Streams の使用開
始
このドキュメントは Amazon Kinesis Streams を使い始めるのに役立ちます。Streams を初めて利用
する場合は、Amazon Kinesis Streams とは? (p. 1) で説明されている概念と用語について理解するこ
とから始めてください。
トピック
• Amazon Kinesis Streams のセットアップ (p. 9)
• チュートリアル: Amazon Kinesis Streams を使用したウェブトラフィックの可視化 (p. 10)
• チュートリアル: AWS CLI を使用した Amazon Kinesis Streams の使用開始 (p. 16)
Amazon Kinesis Streams のセットアップ
Amazon Kinesis Streams を初めて使用する場合は、事前に以下のタスクをすべて実行してください。
タスク
• AWS にサインアップする (p. 9)
• ライブラリとツールをダウンロードする (p. 10)
• 開発環境を設定する (p. 10)
AWS にサインアップする
アマゾン ウェブ サービス（AWS）にサインアップすると、AWS アカウントが AWS 内のすべての
サービス（Streams など）に自動的にサインアップされます。料金が発生するのは、実際に使用した
サービスの分のみです。
既に AWS アカウントをお持ちの場合は次のタスクに進んでください。AWS アカウントをお持ちでな
い場合は、次に説明する手順にしたがってアカウントを作成してください。
サインアップして AWS アカウントを作成するには
1.
https://aws.amazon.com/ を開き、[AWS アカウントの作成] を選択します。
9
Amazon Kinesis Streams 開発者ガイド
ライブラリとツールをダウンロードする
2.
オンラインの手順に従います。
サインアップ手順の一環として、通話呼び出しを受け取り、電話のキーパッドを用いて PIN を入
力することが求められます。
ライブラリとツールをダウンロードする
以下のライブラリとツールは Streams での作業に役立ちます。
• Amazon Kinesis API Reference は、Streams でサポートされている基本的なオペレーションのセッ
トです。Java コードを使用した基本的なオペレーションの実行の詳細については、次を参照してく
ださい。
• Amazon Kinesis Streams API と AWS SDK for Java を使用した Amazon Kinesis Streams プロ
デューサーの開発 (p. 49)
• Amazon Kinesis Streams API および AWS SDK for Java を使用した Amazon Kinesis Streams コ
ンシューマーの開発 (p. 82)
• Amazon Kinesis Stream の管理 (p. 96)
• Java、JavaScript、.NET、Node.js、PHP、Python、Ruby 用の AWS SDK は、Streams をサポート
しており、サンプルが含まれています。AWS SDK for Java のお使いのバージョンに Streams のサ
ンプルが含まれていない場合は、GitHub からダウンロードできます。
• Amazon Kinesis Client Library（KCL）には、データ処理用の使いやすいプログラミングモデルが
用意されています。KCL は、Streams で Java、Node.js、.NET、Python、Ruby をすぐに使い始め
るのに役立ちます。詳細については、「Amazon Kinesis Client Library を使用した Amazon Kinesis
Streams コンシューマーの開発 (p. 66)」を参照してください。
• AWS Command Line Interfaceでは、Streams がサポートされています。AWS CLI を使用すると、
複数の AWS サービスをコマンドラインから制御したり、スクリプトで自動化したりできます。
• （オプション）Amazon Kinesis Connector Libraryは、Streams を他の AWS サービスに統合するの
に役立ちます。たとえば、Amazon Kinesis Connector Library を KCL とともに使用して、Amazon
DynamoDB、Amazon Redshift、および Amazon S3 に Streams から確実にデータを移動できま
す。
開発環境を設定する
KCL を使用するには、Java 開発環境が以下の要件を満たしている必要があります。
• Java 1.7（Java SE 7 JDK）以降。最新の Java ソフトウェアは、Oracle のウェブサイトの Java SE
Downloads からダウンロードできます。
• Apache Commons パッケージ（コード、HTTP クライアント、ログ記録）。
• Jackson JSON プロセッサ
AWS SDK for Java では、サードパーティフォルダーに Apache Commons と Jackson が含まれて
いることに注意してください。ただし、SDK for Java は Java 1.6 で動作しますが、Amazon Kinesis
Client Libraryには Java 1.7 が必要です。
チュートリアル: Amazon Kinesis Streams を使用
したウェブトラフィックの可視化
このチュートリアルでは、Amazon Kinesis Streams の使用開始に役立つように、その重要なコン
ポーネントについて Streams ストリーム (p. 5)、データプロデューサー (p. 6)、データコンシュー
10
Amazon Kinesis Streams 開発者ガイド
Streams のデータ可視化サンプルアプリケーション
マー (p. 7)を中心に概説します。このチュートリアルでは、リアルタイムデータ分析の一般的なユース
ケース（「Amazon Kinesis Streams とは? (p. 1)」で紹介）に基づいたサンプルアプリケーションを使
用します。
このサンプルのウェブアプリケーションは、単純な JavaScript アプリケーションを使用して、スラ
イドウィンドウにわたるトップ N 分析の結果を格納している DynamoDB テーブルをポーリングしま
す。アプリケーションはこのデータを受け取り、結果を可視化します。
Streams のデータ可視化サンプルアプリケーション
このチュートリアルのデータ可視化サンプルアプリケーションでは、&AKS; を使用してリアルタイム
でデータを取り込み分析する方法を示します。このサンプルアプリケーションは、さまざまな URL か
らのシミュレート上の閲覧者の数を Amazon Kinesis stream に投入するデータプロデューサーを作成
します。ストリームはそれらのデータレコードを受け取った順に保持します。データコンシューマー
は、ストリームからこれらのレコードを取得し、特定の URL からの閲覧者の数を計算します。最後
に、単純なウェブアプリケーションは計算結果をリアルタイムでポーリングし、計算結果を可視化し
ます。
このサンプルアプリケーションは、ストリーム処理の一般的なユースケースとして、スライディング
ウィンドウ分析を10 秒間行います。先ほど示した可視化されたデータは、ストリームのスライディ
ングウィンドウ分析の結果を反映したものであり、継続的に更新されてグラフとして表示されていま
す。さらに、データコンシューマーはデータストリームに対してトップ N 分析を行って、上位 3 つ
の閲覧者を割り出します。その結果は、2 秒ごとに更新されてグラフのすぐ下に表として表示されま
す。
すぐに開始できるように、サンプルアプリケーションは AWS CloudFormation を使用します。AWS
CloudFormation では、テンプレートを作成して、AWS リソースおよびそのアプリケーションを実行
するために必要な関連するすべての依存関係や実行時のパラメータを記述できます。サンプルアプリ
ケーションはテンプレートを使用して、すべての必要なリソース、たとえば Amazon EC2 インスタ
ンスで実行されるプロデューサーとコンシューマーのアプリケーション、集計レコード数を格納する
Amazon DynamoDB テーブルをすばやく作成します。
Note
サンプルアプリケーションの起動後、Streams の使用に関するわずかな料金が発生します。
可能ならば、サンプルアプリケーションは AWS 無料利用枠 の対象となるリソースを使用
します。このチュートリアルを終了したら、AWS リソースを削除して料金が発生しない
ようにしてください。詳細については、「ステップ 3: サンプルアプリケーションを削除す
る (p. 15)」を参照してください。
前提条件
このチュートリアルでは、Streams のデータ可視化サンプルアプリケーションをセットアップして実
行し、その結果を表示する手順を示します。サンプルアプリケーションを使用するには、最初に以下
の作業をする必要があります。
• コンピュータをセットアップし、インターネット接続を有効にします。
• AWS アカウントにサインアップします。
• さらに、ストリーム (p. 5)、データプロデューサー (p. 6)、データコンシューマー (p. 7)の概念につ
いて入門セクションを参照します。
ステップ 1: サンプルアプリケーションを起動する
AWS によって提供された AWS CloudFormation テンプレートを 使用してサンプルアプリケーション
を起動します。このサンプルアプリケーションには、ランダムにレコードを生成して Amazon Kinesis
11
Amazon Kinesis Streams 開発者ガイド
ステップ 2: サンプルアプリケー
ションのコンポーネントを表示する
stream に送信するストリームライター、リソースに対する HTTPS リクエスト数をカウントするデー
タコンシューマー、およびストリーム処理データの出力を、継続的に更新されるグラフとして表示す
るウェブアプリケーションが含まれます。
アプリケーションを起動するには
1.
このチュートリアルの AWS CloudFormation テンプレート を開きます。
2.
[Select Template] ページで、テンプレートの URL が提供されます。[Next] を選択します。
3.
[Specify Details] ページでは、デフォルトのインスタンスタイプは t2.micro です。ただし、T2
インスタンスは VPC が必要です。AWS アカウントに us-east-1 リージョンのデフォルト VPC
がない場合は、インスタンスタイプを m3.medium などの別のインスタントタイプに変更する必
要があります。[Next] を選択します。
4.
[Options] ページで、タグのキーとタグの値を任意で入力できます。このタグは、EC2 インスタン
スなどのテンプレートによって作成されたリソースに追加されます。[Next] を選択します。
5.
[Review] ページで、[I acknowledge that this template might cause AWS CloudFormation to create
IAM resources] を選択し、[Create] を選択します。
まず、ステータス CREATE_IN_PROGRESS の KinesisDataVisSample という名前のスタックが表示さ
れます。スタックが作成されるまでに数分かかる場合があります。ステータスが CREATE_COMPLETE
の場合、次のステップに進みます。ステータスが更新されない場合は、ページを更新してください。
ステップ 2: サンプルアプリケーションのコンポー
ネントを表示する
コンポーネント
• Amazon Kinesis Stream (p. 12)
• データプロデューサー (p. 13)
• データコンシューマー (p. 14)
Amazon Kinesis Stream
ストリーム (p. 5)は、大量のプロデューサーからリアルタイムでデータを取り込み、データを保存し
て、複数のコンシューマーに提供します。ストリームは、データレコードの順序付けられたシーケン
スを意味します。ストリームの作成時に、ストリーム名とシャードの数を指定する必要があります。
ストリームは 1 つまたは複数のシャードで構成されます。各シャードはデータレコードのグループで
す。
AWS CloudFormation は自動的にサンプルアプリケーションのストリームを作成します。AWS
CloudFormation テンプレートのこのセクションは、CreateStream操作で使用されるパラメータを示し
ています。
ストリームの詳細を表示するには
1.
[KinesisDataVisSample] スタックを選択します。
2.
[Outputs] タブで、URL のリンクを選択します。URL の形式は「http://ec2-xx-xx-xxxx.compute-1.amazonaws.com」のようになります。
3.
アプリケーションスタックを作成し、データ解析グラフで表示する意味のあるデータにするに
は、10 分程度かかります。リアルタイムのデータ分析グラフは、[Streams Data Visualization
Sample] というタイトルの別のページに表示されます。このグラフは、10 秒間に参照元 URL か
ら送信されたリクエストの数を表示し、1 秒ごとに更新されます。グラフのスパンは直近の 2 分
間です。
12
Amazon Kinesis Streams 開発者ガイド
ステップ 2: サンプルアプリケー
ションのコンポーネントを表示する
ストリームの詳細を表示するには
1.
https://console.aws.amazon.com/kinesis にある Amazon Kinesis コンソールを開きます。
2.
名前に ( KinesisDataVisSampleApp-KinesisStream-[randomString]) のフォームがある
ストリームを選択します。
3.
ストリームの詳細を表示するにはストリーム名を選択します。
4.
それらのグラフを見ると、データプロデューサーのアクティビティがストリームにレコードを投
入し、データコンシューマーがストリームからデータを取得していることがわかります。
データプロデューサー
データプロデューサー (p. 6)は Amazon Kinesis stream にデータレコードを送信します。ストリーム
にデータを投入するために、プロデューサーはストリームに対して PutRecord オペレーションを呼び
出します。
PutRecord の呼び出しごとに、ストリーム名とパーティションキーのほか、プロデューサーがスト
リームに追加するデータレコードが必要になります。ストリーム名により、レコードが存在すること
13
Amazon Kinesis Streams 開発者ガイド
ステップ 2: サンプルアプリケー
ションのコンポーネントを表示する
になるストリームが決まります。パーティションキーは、データレコードが追加されるストリーム内
のシャードを決定するために使用されます。
使用するパーティションキーはアプリケーションのロジックによって異なります。パーティション
キーの数は、ほとんどの場合、シャード数よりかなり大きくする必要があります。シャードに対して
十分な数のパーティションキーがあることで、ストリームはデータレコードをストリーム内のシャー
ドに均等に分配できます。
データデータプロデューサーは一般的な 6 つの URL を、2 シャード構成のストリームに投入された各
レコードのパーティションキーとして使用します。これらの URL がシミュレート上のページ閲覧者を
表します。HttpReferrerKinesisPutter コードの行 99 ～ 136 は Streams にデータを送信しています。3
つの必要なパラメータを PutRecord の呼び出し前に設定しています。pair.getResource を使用
してパーティションキーを設定しています。そのために、HttpReferrerStreamWriter コードの行 85 ～
92 で作成される 6 つの URL のいずれかをランダムに選択しています。
Streams にデータを投入するデータプロデューサーとして使用できるのは、EC2 インスタンス、ク
ライアントブラウザー、モバイルデバイスなどです。サンプルアプリケーションでは、データプロ
デューサーとそのデータコンシューマーとして同じ EC2 インスタンスを使用しています。一方、実際
のシナリオでは、アプリケーションの各コンポーネントとして別々の EC2 インスタンスを使用するこ
とになります。以下の手順に従って、サンプルアプリケーションの EC2 インスタンスのデータを表示
できます。
コンソールでインスタンスのデータを表示するには
1.
https://console.aws.amazon.com/ec2/) にある Amazon EC2 コンソールを開きます。
2.
ナビゲーションペインで、[インスタンス] を選択します。
3.
サンプルアプリケーション用に作成されたインスタンスを選択します。インスタンスが不明な場
合、KinesisDataVisSample の名前で始まるセキュリティグループがあります。
4.
[Monitoring] タブに、サンプルアプリケーションのデータプロデューサーとデータコンシューマー
のリソース使用状況が表示されます。
データコンシューマー
データコンシューマー (p. 7)は Amazon Kinesis stream 内のシャードからデータレコードを取得して
処理します。各コンシューマーはそれぞれ特定のシャードからデータを読み取ります。コンシュー
マーは GetShardIterator および GetRecords オペレーションを使用してシャードからデータを取得し
ます。
シャードイテレーターは、ストリームの位置とコンシューマーが読み取るシャードを表します。コン
シューマーは、ストリームからのレコードの読み取りを開始したり、読み取り位置を変更したりする
ときは、このシャードイテレーターを取得します。シャードイテレーターを取得するには、ストリー
ム名、シャード ID、シャードイテレータ イプを提供する必要があります。シャードイテレーター型
により、コンシューマーがストリームのどこから読み取りを開始するかを指定できます。たとえば、
データがリアルタイムで到着する場合はストリームの先頭を指定できます。ストリームはレコードを
バッチにまとめて返します。バッチのサイズは必要に応じて制限パラメータを使用して制御できま
す。
データコンシューマーは、アプリケーションの状態情報 (チェックポイントやワーカーシャードマッピ
ングなど) を維持するためのテーブルを DynamoDB に作成します。各アプリケーションには、それぞ
れ DynamoDB テーブルがあります。
データコンシューマーは最後の 2 秒間に特定の各 URL からの閲覧者のリクエストをカウントしま
す。このタイプのリアルタイムアプリケーションはスライディングウィンドウにわたるトップ N 分析
を採用しています。この例では、上位 N 個はページリクエスト数で上位 3 つの閲覧者であり、スライ
ディングウィンドウは 2 秒です。これは、Streams を使用した実際のデータ分析を示す、一般的な処
理パターンです。この計算の結果は DynamoDB テーブルに保持されます。
14
Amazon Kinesis Streams 開発者ガイド
ステップ 3: サンプルアプリケーションを削除する
Amazon DynamoDB テーブルを表示するには
1.
https://console.aws.amazon.com/dynamodb/ にある DynamoDB コンソールを開きます。
2.
ナビゲーションペインで、[Tables] を選択します。
3.
サンプルアプリケーションによって作成された 2 つのテーブルがあります。
• KinesisDataVisSampleApp-KCLDynamoDBTable-[randomString]— は状態情報を管理します。
• KinesisDataVisSampleApp-CountsDynamoDBTable-[randomString]— はスライディングウィン
ドウにわたりトップ N 分析を持続します。
4.
Select the KinesisDataVisSampleApp-KCLDynamoDBTable-[randomString] テーブル。テーブル
には 2 つのエントリがあり、特定のシャード (leaseKey)、ストリーム内の位置 (checkpoint)、
データを読み取るアプリケーション (leaseOwner) を示します。
5.
Select the KinesisDataVisSampleApp-CountsDynamoDBTable-[randomString] テーブル。
データコンシューマーがスライディングウィンドウ分析の一部として計算した総閲覧者数
（referrerCounts）を確認できます。
Amazon Kinesis クライアントライブラリ (KCL)
コンシューマーアプリケーションは、Amazon Kinesis Client Library（KCL）を使用して、ストリー
ムの並列処理を簡素化できます。KCL は、分散コンピューティングに関連する多くの複雑なタスクを
処理します。たとえば、複数のインスタンス間での負荷分散、インスタンスの障害に対する応答、処
理済みのレコードのチェックポイント作成、リシャーディングへの対応が挙げられます。KCL によっ
て、レコード処理のロジックの記述に集中できます。
データコンシューマーは、読み取るストリーム内の位置を KCL に渡します。この例では、ストリー
ムの先頭からの最新のデータを読み取るように指定しています。KCL はこの位置を使用して、コ
ンシューマーに代わって GetShardIterator を呼び出します。コンシューマーコンポーネント
は、IRecordProcessor という重要な KCL インターフェイスにより、レコードに対してどのような
処理を行うかも KCL に指定します。KCL はコールコンシューマーに代わって GetRecords を呼び出
し、IRecordProcessor により指定されたようにそれらのレコードを処理します。
• HttpReferrerCounterApplication サンプルコードの行 92 ～ 98 は KCL を設定しています。これは、
データを読み取るストリーム内の位置の設定など、KCL の初期設定になります。
• HttpReferrerCounterApplication サンプルコードの行 104 〜 108 は、IRecordProcessor という
重要な KCL コンポーネントを使用してレコードを処理するためのロジックを KCL に通知していま
す。
• CountingRecordProcessor サンプルコードの行 186 ～ 203 は、IRecordProcessor を使用する
トップ N 分析のためのカウントロジックを含んでいます。
ステップ 3: サンプルアプリケーションを削除する
サンプルアプリケーションは、アプリケーションの実行中に、シャードの使用料が発生する 2 つの
シャードを作成します。AWS アカウントが請求し続けないように、サンプルアプリケーションを終了
したら AWS CloudFormation スタックを削除してください。
アプリケーションリソースを削除するには
1.
AWS CloudFormation コンソール (https://console.aws.amazon.com/cloudformation/) を開きま
す。
2.
スタックを選択します。
3.
[ Actions] で、[Delete Stack] を選択します。
4.
確認を求めるメッセージが表示されたら、[Yes, Delete] を選択します。
15
Amazon Kinesis Streams 開発者ガイド
ステップ 4: 次のステップ
AWS CloudFormation でサンプルアプリケーションに関連付けられたリソースをクリーンアップして
いる間、ステータスが [DELETE_IN_PROGRESS] に変わります。AWS CloudFormation がリソースのク
リーンアップを終了したら、リストからスタックを削除します。
ステップ 4: 次のステップ
• GitHub で、データ可視化サンプルアプリケーションのソースコードを確認できます。
• Amazon Kinesis Streams API と AWS SDK for Java を使用した Amazon Kinesis Streams プロ
デューサーの開発 (p. 49)、Amazon Kinesis Streams API および AWS SDK for Java を使用した
Amazon Kinesis Streams コンシューマーの開発 (p. 82)、および Amazon Kinesis Stream の管
理 (p. 96) で Streams API の使用に関するより詳しい情報を見つけることができます。
• Streams からデータを取得する SDK を使用する AWS SDK for Java のサンプルアプリケーションを
確認できます。
チュートリアル: AWS CLI を使用した Amazon
Kinesis Streams の使用開始
このチュートリアルでは、AWS Command Line Interface を使用して基本的な Amazon Kinesis
Streams オペレーションを実行する方法を示します。基本的な Streams データフローの原則
と、Amazon Kinesis stream にデータを入力したり、ストリームからデータを取得したりするために
必要なステップについて説明します。
For CLI access, you need an access key ID and secret access key. Use IAM user access keys
instead of AWS root account access keys. IAM lets you securely control access to AWS services and
resources in your AWS account. For more information about creating access keys, see How Do I Get
Security Credentials? in the AWS General Reference.
IAM およびセキュリティキーの詳細なセットアップの手順については、「IAM ユーザーを作成する」
を参照してください。
このチュートリアルで説明する特定のコマンドは、特定の値が実行のたびに異なる場合を除き、その
まま使用します。また、例では 米国西部 (オレゴン) リージョンを使用していますが、Streams をサ
ポートするリージョンであればこのチュートリアルに使用できます。
トピック
• AWS CLI のインストールと設定 (p. 16)
• 基本的なストリームオペレーションの実行 (p. 18)
AWS CLI のインストールと設定
AWS CLI のインストール
このセクションでは、Windows 用と、Linux、OS X、UNIX オペレーティングシステム用の AWS CLI
のインストール方法について説明します。
Windows
1.
『AWS Command Line Interface ユーザーガイド』の「完全インストールの手順」の
「Windows」セクションから、適切な MSI インストーラをダウンロードします。
2.
ダウンロードした MSI インストーラを実行します。
3.
表示される手順に従います。
16
Amazon Kinesis Streams 開発者ガイド
AWS CLI のインストールと設定
Linux, macOS, or Unix
以下の手順では Python 2.6.3 以降が必要です。問題が発生した場合は、『AWS Command Line
Interface ユーザーガイド』の完全インストールの手順を参照してください。
1.
pip のウェブサイトからインストールスクリプトをダウンロードし実行します。
curl "https://bootstrap.pypa.io/get-pip.py" -o "get-pip.py"
sudo python get-pip.py
2.
pip を使用して AWS CLI をインストールします。
sudo pip install awscli
使用可能なオプションとサービスのリストを表示するには、次のコマンドを使用します。
aws help
Streams サービスを使用しているため、次のコマンドを使用して、Streams に関連する AWS CLI サ
ブコマンドを確認できます。
aws kinesis help
このコマンドの出力には、使用できる Streams コマンドが含まれます。
AVAILABLE COMMANDS
o add-tags-to-stream
o create-stream
o delete-stream
o describe-stream
o get-records
o get-shard-iterator
o help
o list-streams
o list-tags-for-stream
o merge-shards
o put-record
o put-records
o remove-tags-from-stream
o split-shard
17
Amazon Kinesis Streams 開発者ガイド
基本的なストリームオペレーションの実行
o wait
このコマンドリストは、『Amazon Kinesis サービス API リファレンス』に記載されている Streams
API に対応しています。たとえば、create-stream コマンドは CreateStream API アクションに対
応します。
これで AWS CLI は正常にインストールされましたが、まだ設定されていません。これについては、
次のセクションで説明します。
AWS CLI の設定
一般的な使用の場合、aws configure コマンドが、AWS CLI のインストールをセットアップするた
めの最も簡単な方法です。AWS CLI ではセッション間で設定が保存されるため、ユーザー設定に変更
がない場合、このセットアップは 1 回限りです。
aws configure
AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
Default region name [None]: us-west-2
Default output format [None]: json
AWS CLI によって、4 種類の情報の入力が求められます。AWS アクセスキー ID と AWS シークレッ
トアクセスキーは、アカウントの認証情報です。キーがない場合は、「アマゾン ウェブ サービスへの
サインアップ」を参照してください。
デフォルトのリージョンは、デフォルトで呼び出しを実行する対象のリージョンの名前です。これ
は、通常、お客様の最寄りのリージョンですが、どのリージョンでもかまいません。
Note
AWS CLI を使用するときは AWS リージョンを指定する必要があります。サービスと利用
可能なリージョンのリストについては、「リージョンとエンドポイント」を参照してくださ
い。
デフォルトの出力形式は json、text、table のいずれかです。出力形式を指定しない場合、json が使用
されます。
aws configure で作成されたファイル、追加の設定、名前付きプロファイルの詳細については、
『AWS Command Line Interface ユーザーガイド』の「AWS コマンドラインインターフェイスの設
定」を参照してください。
基本的なストリームオペレーションの実行
このセクションでは、AWS CLI を使用した、コマンドラインからの Amazon Kinesis stream の基本的
な使用方法について説明します。「Amazon Kinesis Streams の主要なコンセプト (p. 2)」と「チュー
トリアル: Amazon Kinesis Streams を使用したウェブトラフィックの可視化 (p. 10)」で説明されて
いる概念を理解している必要があります。
Note
Streams は AWS の無料利用枠の対象に該当しないため、ストリームを作成した後、Streams
の使用に関するわずかな料金が発生します。このチュートリアルを終了したら、AWS リソー
スを削除して料金が発生しないようにしてください。詳細については、「手順 4: クリーン
アップ (p. 23)」を参照してください。
トピック
18
Amazon Kinesis Streams 開発者ガイド
基本的なストリームオペレーションの実行
• ステップ 1: ストリームを作成する (p. 19)
• ステップ 2: レコードを入力する (p. 20)
• ステップ 3: レコードを取得する (p. 20)
• 手順 4: クリーンアップ (p. 23)
ステップ 1: ストリームを作成する
最初のステップは、ストリームを作成し、正常に作成されたことを確認することです。次のコマンド
を使用して、「Foo」という名前のストリームを作成します。
aws kinesis create-stream --stream-name Foo --shard-count 1
--shard-count パラメータは必須であり、チュートリアルのこの部分では、ストリームで 1 個の
シャードを使用しています。次に、次のコマンドを実行して、ストリーム作成の進行状況を確認しま
す。
aws kinesis describe-stream --stream-name Foo
次の例のような出力が得られます。
{
"StreamDescription": {
"StreamStatus": "CREATING",
"StreamName": "Foo",
"StreamARN": "arn:aws:kinesis:us-west-2:account-id:stream/Foo",
"Shards": []
}
}
この例では、ストリームのステータスは CREATING であり、使用する準備が完全には整っていない
ことを意味します。しばらくしてからもう一度調べると、次の例のような出力が表示されます。
{
"StreamDescription": {
"StreamStatus": "ACTIVE",
"StreamName": "Foo",
"StreamARN": "arn:aws:kinesis:us-west-2:account-id:stream/Foo",
"Shards": [
{
"ShardId": "shardId-000000000000",
"HashKeyRange": {
"EndingHashKey":
"170141183460469231731687303715884105727",
"StartingHashKey": "0"
},
"SequenceNumberRange": {
"StartingSequenceNumber":
"49546986683135544286507457935754639466300920667981217794"
}
}
]
}
}
19
Amazon Kinesis Streams 開発者ガイド
基本的なストリームオペレーションの実行
この出力には、このチュートリアルで気にする必要がない情報も含まれています。ここで重要な項目
は "StreamStatus": "ACTIVE" であり、ストリームを使用する準備ができたことと、リクエストし
た単一のシャードに関する情報が示されています。また、次に示すように、list-streams コマンド
を使用して新しいストリームの存在を確認することもできます。
aws kinesis list-streams
出力:
{
"StreamNames": [
"Foo"
]
}
ステップ 2: レコードを入力する
アクティブなストリームができたら、データを入力できます。このチュートリアルでは、最もシンプ
ルなコマンド put-record を使用して、"testdata" というテキストを含む単一のデータレコードをス
トリームに入力します。
aws kinesis put-record --stream-name Foo --partition-key 123 --data testdata
このコマンドが成功すると、出力は次の例のようになります。
{
"ShardId": "shardId-000000000000",
"SequenceNumber":
"49546986683135544286507457936321625675700192471156785154"
}
これで、ストリームにデータを追加できました。次にストリームからデータを取得する方法を説明し
ます。
ステップ 3: レコードを取得する
ストリームからデータを取得するには、対象となるシャードのシャードイテレーターを取得する必要
があります。シャードイテレーターは、コンシューマー（ここでは get-record コマンド）が読み取
るストリームとシャードの位置を表します。次のように get-shard-iterator コマンドを使用しま
す。
aws kinesis get-shard-iterator --shard-id shardId-000000000000 --sharditerator-type TRIM_HORIZON --stream-name Foo
aws kinesis のコマンドにはその背後に Streams API があります。示されているパラメータに関心
がある場合は、GetShardIterator API のリファレンスのトピックを参照してください。実行に成功
すると、出力は次の例のようになります（出力全体を表示するには、水平にスクロールします）。
{
"ShardIterator":
"AAAAAAAAAAHSywljv0zEgPX4NyKdZ5wryMzP9yALs8NeKbUjp1IxtZs1Sp
+KEd9I6AJ9ZG4lNR1EMi+9Md/nHvtLyxpfhEzYvkTZ4D9DQVz/
mBYWRO6OTZRKnW9gd+efGN2aHFdkH1rJl4BL9Wyrk
+ghYG22D2T1Da2EyNSH1+LAbK33gQweTJADBdyMwlo5r6PqcP2dzhg="
20
Amazon Kinesis Streams 開発者ガイド
基本的なストリームオペレーションの実行
}
ランダムに見える長い文字列がシャードイテレーターです（お客様のシャードイテレーターはこれと
は異なります）。このシャードイテレーターをコピーして、次に示す get コマンドに貼り付ける必要
があります。シャードイテレーターの有効期間は 300 秒です。これは、シャードイテレーターをコ
ピーして次のコマンドに貼り付けるのに十分な時間です。次のコマンドに貼り付ける前に、シャード
イテレーターから改行を削除する必要があることに注意してください。シャードイテレーターが有効
ではないことを示すエラーメッセージが表示された場合は、もう一度 get-shard-iterator コマン
ドを実行します。
get-records コマンドは、ストリームからデータを取得し、Streams API の GetRecords 呼
び出しとして解決されます。シャードイテレーターは、データレコードの逐次読み取りを開始す
る、シャード内の位置を指定します。イテレーターが指定するシャードの位置にレコードがない場
合、GetRecords は空のリストを返します。シャード内のレコードが含まれる位置に到達するため
に、複数の呼び出しが必要になる場合があることに注意してください。
get-records コマンドの例を次に示します（出力全体を表示するには、水平にスクロールしま
す）。
aws kinesis get-records --shard-iterator
AAAAAAAAAAHSywljv0zEgPX4NyKdZ5wryMzP9yALs8NeKbUjp1IxtZs1Sp
+KEd9I6AJ9ZG4lNR1EMi+9Md/nHvtLyxpfhEzYvkTZ4D9DQVz/
mBYWRO6OTZRKnW9gd+efGN2aHFdkH1rJl4BL9Wyrk
+ghYG22D2T1Da2EyNSH1+LAbK33gQweTJADBdyMwlo5r6PqcP2dzhg=
bash など Unix タイプのコマンドプロセッサからこのチュートリアルを実行する場合は、次のように
入れ子にしたコマンドを使用して、シャードイテレーターの取得を自動化できます（横方向にスク
ロールしてコマンド全体を表示）。
SHARD_ITERATOR=$(aws kinesis get-shard-iterator --shard-id
shardId-000000000000 --shard-iterator-type TRIM_HORIZON --stream-name Foo -query 'ShardIterator')
aws kinesis get-records --shard-iterator $SHARD_ITERATOR
Powershell をサポートするシステムからこのチュートリアルを実行する場合、次のようなコマンドを
使用してシャードのイテレータの取得を自動化できます（横方向にスクロールしてコマンド全体を表
示）。
aws kinesis get-records --shard-iterator ((aws kinesis get-shard-iterator -shard-id shardId-000000000000 --shard-iterator-type TRIM_HORIZON --streamname Foo).split('"')[4])
get-records コマンドが正常に終了すると、次の例のように、シャードイテレーターを取得すると
きに指定したシャードに対応するストリーム内のレコードがリクエストされます（出力全体を表示す
るには、水平にスクロールします）。
{
"Records":[ {
"Data":"dGVzdGRhdGE=",
"PartitionKey":"123”,
"ApproximateArrivalTimestamp": 1.441215410867E9,
"SequenceNumber":"49544985256907370027570885864065577703022652638596431874"
} ],
"MillisBehindLatest":24000,
21
Amazon Kinesis Streams 開発者ガイド
基本的なストリームオペレーションの実行
"NextShardIterator":"AAAAAAAAAAEDOW3ugseWPE4503kqN1yN1UaodY8unE0sYslMUmC6lX9hlig5+t4RtZM0/
tALfiI4QGjunVgJvQsjxjh2aLyxaAaPr
+LaoENQ7eVs4EdYXgKyThTZGPcca2fVXYJWL3yafv9dsDwsYVedI66dbMZFC8rPMWc797zxQkv4pSKvPOZvrUIudb8Uk
}
上記で get-records を "リクエスト" と説明しましたが、これは、ストリーム内にレコードが存在
する場合もゼロ件以上のレコードが返される可能性があり、返されたどのレコードも現在ストリーム
内にあるすべてのレコードを表していない可能性があることを意味します。これは完全に正常で、本
稼働用のコードではストリームに対し、適切な間隔でレコードに対するポーリングを行います（この
ポーリング速度は、個々のアプリケーションの設計要件によって異なります）。
チュートリアルのこのパートで、レコードについて最初に気付くのは、データが文字化けのように
見える点でしょう。送信した testdata のクリアテキストではありません。これは、バイナリデー
タを送信できるように、put-record では Base64 エンコーディングを使用しているためです。た
だし、AWS CLI での Streams のサポートでは、Base64 デコーディングを提供していません。これ
は、Base64 デコーディングされた raw バイナリコンテンツを stdout に出力すると、特定のプラッ
トフォームやターミナルで、意図しない動作やセキュリティ上の問題が発生する可能性があるためで
す。Base64 デコーダ（https://www.base64decode.org/ など）を使用して手動で dGVzdGRhdGE= をデ
コードすると、これが実際に testdata であることを確認できます。このチュートリアルではこれで
問題ありません。なぜなら、実際には、AWS CLI を使用してデータを利用することはまれであり、通
常は前に示したように（describe-stream および list-streams）、ストリームの状態をモニタリ
ングしたり、情報を取得したりするために使用されるからです。後のチュートリアルでは、Amazon
Kinesis クライアントライブラリ (KCL) を使用して、本稼働品質のコンシューマーアプリケーション
を構築する方法を示し、Base64 の処理も検討します。KCL の詳細については、「Amazon Kinesis
Client Library を使用した Amazon Kinesis Streams コンシューマーの開発 (p. 66)」を参照してくだ
さい。
get-records によって、常にストリーム/シャード内のすべてのレコードが返されるわけではありま
せん。このような場合は、最後の結果から NextShardIterator を使用して、次のレコードのセッ
トを取得します。したがって、大量のデータがストリームに入力されていた場合（本稼働アプリケー
ションでの通常の状況）、毎回 get-records を使用してデータのポーリングを継続できます。た
だし、300 秒のシャードイテレーターの有効期間内に次のシャードイテレーターを使用して getrecords を呼び出した場合、エラーメッセージが表示され、get-shard-iterator コマンドを使用
して最新のシャードイテレーターを取得する必要があります。
この出力には、MillisBehindLatest も含まれています。これは、GetRecords オペレーションの
ストリームの末尾からの応答をミリ秒で表した数値であり、コンシューマーの時間の現在の時刻から
の遅れを示します。値ゼロはレコード処理が追いついて、現在処理する新しいレコードは存在しない
ことを示します。このチュートリアルの場合は、作業を進めるのに時間をかけていると、この数値が
かなり大きくなる可能性があります。これは問題ではなく、データレコードはストリームに 24 時間
留まり、取得されるのを待ちます。この期間は保持期間と呼ばれ、168 時間（7 日）まで設定可能で
す。
get-records が成功したときの結果は、現在ストリームにこれ以上レコードが見つからない場合で
も常に NextShardIterator です。これは、プロデューサーがどの時点でもストリームにレコードを
入力している可能性があることを前提としたポーリングモデルです。独自のポーリングルーチンを記
述することもできますが、開発中のコンシューマーアプリケーションで、前に説明した KCL を使用し
ている場合、このポーリングによって処理が実行されます。
レコードをプルする対象のストリームまたはシャードにそれ以上レコードがなくなるまで getrecords を呼び出すと、次の例のような空のレコードの出力が表示されます（出力全体を表示するに
は、水平にスクロールします）。
{
"Records": [],
"NextShardIterator": "AAAAAAAAAAGCJ5jzQNjmdhO6B/YDIDE56jmZmrmMA/r1WjoHXC/
kPJXc1rckt3TFL55dENfe5meNgdkyCRpUPGzJpMgYHaJ53C3nCAjQ6s7ZupjXeJGoUFs5oCuFwhP
22
Amazon Kinesis Streams 開発者ガイド
基本的なストリームオペレーションの実行
+Wul/EhyNeSs5DYXLSSC5XCapmCAYGFjYER69QSdQjxMmBPE/hiybFDi5qtkT6/
PsZNz6kFoqtDk="
}
手順 4: クリーンアップ
最後に、ストリームを削除してリソースを解放し、前に説明したように、アカウントに対する意図し
ない料金が発生することを回避できます。ストリームを作成したが、使用する予定がない場合は、必
ず実際にこれを行ってください。ストリームでデータを入力および取得したかどうかにかかわらず、
ストリームごとに料金が発生するためです。クリーンアップコマンドはシンプルです。
aws kinesis delete-stream --stream-name Foo
成功しても出力はないため、describe-stream を使用して削除の進行状況を確認できます。
aws kinesis describe-stream --stream-name Foo
delete コマンドの直後にこのコマンドを実行する場合、次の例のような出力が表示されます。
{
"StreamDescription": {
"StreamStatus": "DELETING",
"StreamName": "Foo",
"StreamARN": "arn:aws:kinesis:us-west-2:account-id:stream/Foo",
"Shards": []
}
}
ストリームが完全に削除されると、describe-stream は「not found」エラーを返します。
A client error (ResourceNotFoundException) occurred when calling the
DescribeStream operation:
Stream Foo under account 112233445566 not found.
これで、これで、AWS CLI を使用した Streams の基礎に関するこのチュートリアルは終了です。
23
Amazon Kinesis Streams 開発者ガイド
第 1 部: ストリーム、プロデュー
サー、およびコンシューマー
Amazon Kinesis Streams 開発の学
習
これらのモジュールは、Streams 開発をよく理解するために必要な内容を学習することを目的として
います。どのストリーミングサービスがお客様に適切なものであるか不明な場合は、「ストリーミン
グデータとは?」の比較情報を参照してください。開始する前に、「Amazon Kinesis Streams の主要
なコンセプト (p. 2)」と「チュートリアル: Amazon Kinesis Streams を使用したウェブトラフィック
の可視化 (p. 10)」で説明されている概念、特にストリーム、シャード、プロデューサー、コンシュー
マーについて理解している必要があります。また、「チュートリアル: Amazon Kinesis Streams を
使用したウェブトラフィックの可視化 (p. 10)」と「チュートリアル: AWS CLI を使用した Amazon
Kinesis Streams の使用開始 (p. 16)」を完了していると役立ちます。
トピック
• 第 1 部: ストリーム、プロデューサー、およびコンシューマー (p. 24)
第 1 部: ストリーム、プロデューサー、およびコ
ンシューマー
Amazon Kinesis Streams 向けに Java で開発を行う方法をシリーズで説明します。これは、その第 1
部です。どのストリーミングサービスがお客様に適切なものであるか不明な場合は、「ストリーミン
グデータとは?」の比較情報を参照してください。
このモジュールのシナリオでは、株式取引をストリームに取り込み、ストリーム上で計算を実行する
シンプルなアプリケーションを記述します。第 1 部では、レコードのストリームを Streams に送信
し、ほぼリアルタイムにレコードを消費および処理するアプリケーションを実装する方法を説明しま
す。このシリーズの続きの部分では、このシナリオを拡張して、より高度な設計を行い、ほとんどの
Streams ビジネスアプリケーションに当てはまる、株式取引分析モデルのプログラミングに関する考
慮事項について説明します。
Important
Streams は AWS の無料利用枠の対象に該当しないため、ストリームを作成した後、Streams
の使用に関するわずかな料金が発生します。コンシューマーアプリケーションの起動後に
も、DynamoDB の使用に関するわずかな料金が発生します。DynamoDB は、コンシューマー
アプリケーションが処理状態を追跡する際に使用されます。このアプリケーションを終了し
たら、AWS リソースを削除して料金が発生しないようにしてください。詳細については、
「ステップ 7: 終了する (p. 37)」を参照してください。
24
Amazon Kinesis Streams 開発者ガイド
前提条件
このコードでは、実際の株式市場データにアクセスする代わりに、株式取引のストリームをシミュ
レートします。シミュレーションには、2015 年 2 月時点における時価総額上位 25 社の株式に関す
る実際の市場データを基にしたランダム株式取引ジェネレーターが使用されています。リアルタイム
の株式取引のストリームにアクセスできるとしたら、そのときに必要としている便利な統計を取得し
たいと思われるかもしれません。たとえば、スライディングウィンドウ分析を実行して、過去 5 分間
に購入された最も人気のある株式を調べたいと思われるかもしれません。または、大規模な売り注文
（膨大な株式が含まれる売り注文）が発生したときに通知を受けたいと思われるかもしれません。こ
のシリーズで示されるコードを拡張することで、これらの機能を提供することもできます。
このモジュールにある手順をデスクトップまたはノート PC で実施したら、同じマシンまたは定義さ
れた要件を満たした任意のプラットフォーム（Amazon EC2 など）で、プロデューサーおよびコン
シューマーコードの両方を実行することができます。
例では、米国西部 (オレゴン) リージョンが使用されていますが、Streams がサポートされたリージョ
ンであれば、いずれのリージョンでも動作します。
トピック
• 前提条件 (p. 25)
• ステップ 1: ストリームを作成する (p. 26)
• ステップ 2: IAM ポリシーとユーザーを作成する (p. 27)
• ステップ 3: 実装コードをダウンロードおよびビルドする (p. 30)
• ステップ 4: プロデューサーを実装する (p. 30)
• ステップ 5: コンシューマーを実装する (p. 33)
• ステップ 6: （オプション）コンシューマーを拡張する (p. 36)
• ステップ 7: 終了する (p. 37)
前提条件
Amazon Web Services アカウント
開始する前に、「Amazon Kinesis Streams の主要なコンセプト (p. 2)」と「チュートリアル: Amazon
Kinesis Streams を使用したウェブトラフィックの可視化 (p. 10)」で説明されている概念、特にス
トリーム、シャード、プロデューサー、コンシューマーについて理解している必要があります。ま
た、「チュートリアル: Amazon Kinesis Streams を使用したウェブトラフィックの可視化 (p. 10)」と
「チュートリアル: AWS CLI を使用した Amazon Kinesis Streams の使用開始 (p. 16)」を完了してい
ると役立ちます。
AWS マネジメントコンソール にアクセスするときに、AWS アカウントとウェブブラウザが必要にな
ります。
コンソールにアクセスするには、IAM ユーザー名とパスワードを使用し、IAM サインインページ か
らAWS マネジメントコンソールにサインインします。IAM では、AWS アカウントでの AWS サー
ビスとリソースへのアクセスを安全に制御できます。 アクセスキーの作成の詳細については、AWS
General Reference の「How Do I Get Security Credentials?」を参照してください。
IAM の詳細およびセキュリティキーのセットアップ手順については、「IAM ユーザーを作成する」を
参照してください。
システムソフトウェア要件
アプリケーションを実行するシステムには、Java 7 以上がインストールされている必要があります。
最新の JDK をダウンロードおよびインストールするには、Oracle 社の Java SE インストールサイ
トを参照してください。
25
Amazon Kinesis Streams 開発者ガイド
ステップ 1: ストリームを作成する
Eclipse などの Java IDE をお持ちの場合は、ソースコードを開いて、ソースコードを編集、ビルド、
および実行することができます。
最新バージョンの AWS SDK for Java が必要です。Eclipse を IDE として使用している場合は、AWS
Toolkit for Eclipse を代わりにインストールすることができます。
コンシューマーアプリケーションには、バージョン 1.2.1 以上の Kinesis クライアントライブラリ
（KCL）が必要です。このクライアントライブラリは、Amazon Kinesis Client Library (Java) の
Github から入手することができます。
ステップ 1: ストリームを作成する
このステップでは、次のステップで使用するストリームを作成します。
ストリームを作成するには
1.
AWS マネジメントコンソール にサインインし、https://console.aws.amazon.com/kinesis にある
Amazon Kinesis コンソールを開きます。
2.
ナビゲーションバーで、リージョンセレクターを展開し、リージョンを選択します。
3.
[Create Stream] を選択します。
4.
[Create Stream] ページで、ストリーム名（例: StockTradeStream）を入力します。
5.
シャードの数として 1 を入力します。このとき、[Help me decide how many shards I need]
フィールドは、オフにしたままにします。
6.
[Create] を選択します。
ストリームの作成中、[Stream List] ページのストリームの [Status] の値は、[CREATING] です。スト
リームを使用する準備ができると、[Status] は [ACTIVE] に変わります。ストリームの名前を選択しま
す。[Stream Details] ページには、ストリーム設定の概要とモニタリング情報が表示されます。
シャードに関する追加情報
この学習モジュール以外で初めて Streams を使用するときには、もっと慎重にストリーム作成プロセ
スを計画する必要がある場合があります。シャードをプロビジョニングするときには、予想される最
大需要を考慮する必要があります。このシナリオを例として使用すると、米国の株式市場の取引トラ
フィックは、昼間（東部標準時）にピークを迎えます。その時刻をサンプルとして需要の予測を行う
必要があります。その後、予想される最大需要に合わせてプロビジョニングするか、需要の変動に応
じてストリームを拡大または縮小することができます。
シャードは、スループット容量の単位です。[Create Stream] ページで、[Help me decide how many
shards I need] チェックボックスをオンにします。次のガイドラインに従って、平均レコードサイ
ズ、1 秒間に書き込まれる最大レコード数、コンシューマーアプリケーションの数を入力します。
平均レコードサイズ
計算される平均レコードサイズの予測。この値がわからない場合は、予測される最大レコードサ
イズを使用します。
1 秒間に書き込まれる最大レコード数
データを提供するエンティティの数と各エンティティで 1 秒間に生成されるおよそのレコード数
を考慮に入れます。たとえば、20 台の取引サーバーから株式取引データを取得し、各サーバーで
1 秒間に 250 個の取引が生成される場合、1 秒あたりの合計取引数（レコード数）は 5,000 にな
ります。
コンシューマーアプリケーションの数
独立してストリームを読み取り、ストリームを固有の方法で処理し、固有の出力を生成するアプ
リケーションの数。各アプリケーションは、複数のインスタンスを異なるマシン上で実行するこ
と（クラスターで実行すること）ができます。このため、ストリームが大量でも遅れることなく
処理できます。
26
Amazon Kinesis Streams 開発者ガイド
ステップ 2: IAM ポリシーとユーザーを作成する
表示された予測シャードが現在のシャード制限を超えた場合は、その数のシャードを持つストリー
ムを作成する前に、制限を増加させるようにリクエストを送信する必要がある場合があります。
シャード制限の増加をリクエストするには、「Streams Limits form」を使用します。ストリームおよ
びシャードの詳細については、「Amazon Kinesis Stream (p. 5)」および「Amazon Kinesis Stream の
管理 (p. 96)」を参照してください。
ステップ 2: IAM ポリシーとユーザーを作成する
AWS では、セキュリティのベストプラクティスとして、アクセス権限を細分化して、各リソースへの
アクセスを制御することが勧められています。AWS Identity and Access Management を使用すること
で、AWS のユーザーとユーザーアクセス権限を管理できます。IAM ポリシーには、許可されているア
クションとそれらのアクションが適用されるリソースが明示的にリストされています。
一般的に、Streams プロデューサーおよびコンシューマーには、次の最小アクセス権限が必要になり
ます。
プロデューサー:
アクション
リソース
目的
DescribeStream
Amazon Kinesis レコードを書き込む前に、プロデューサーは、ストリームが存在し、アク
stream
であることを確認する必要があります。
PutRecord、PutRecords Amazon Kinesis
stream
レコードを Streams に書き込みます。
コンシューマー:
アクション
リソース
目的
DescribeStream
Amazon Kinesis レコードを読み取る前に、コンシューマーは、ストリームが存在し、アク
stream
であることを確認し、ストリームにシャードが含まれることを確認します
GetRecords、GetShardIterator
Amazon Kinesis
stream
Streams シャードからレコードを読み込みます。
CreateTable、DescribeTable
Amazon
、GetItem、
Kinesis
PutItem
クライアントライブラリ（KCL）を使用してコンシューマーが開
、PutMetricData、Scan、UpdateItem
DynamoDB
ている場合は、アプリケーションの処理状態を追跡するときに DynamoD
テーブル
ブルにアクセスする必要があります。テーブルは、最初に開始したコンシ
マーによって作成されます。
DeleteItem
Amazon
DynamoDB
テーブル
コンシューマーが Streams シャードで分割と結合のオペレーションを実行
合。
PutMetricData
Amazon
CloudWatch ロ
グ
KCL は、アプリケーションをモニタリングするのに便利なメトリックスを
CloudWatch にアップロードします。
このアプリケーションでは、上記のすべてをアクセス権限を付与する IAM ポリシーを作成します。実
際には、プロデューサーとコンシューマーに 1 つずつ、2 つのポリシーを作成することになるかもし
れません。ここで設定したポリシーは、このシリーズの以降の学習モジュールで再利用できます。
IAM ポリシーを作成するには
1.
新しいストリームの Amazon リソースネーム（ARN）を確認します。ARN 形式は次のとおりで
す。
27
Amazon Kinesis Streams 開発者ガイド
ステップ 2: IAM ポリシーとユーザーを作成する
arn:aws:kinesis:region:account:stream/name
region
リージョンコード（例: us-west-2）。リージョンコードの詳細については、「リージョンと
アベイラビリティーゾーンに関する概念」を参照してください。
account
AWS アカウント ID（「アカウント設定」を参照してください）。
name
ステップ 1: ストリームを作成する (p. 26) からのストリームの名前
（StockTradeStream）。
2.
コンシューマーによって使用される（最初のコンシューマーインスタンスによって作成され
た）DynamoDB テーブルの ARN を確認します。ARN 形式は次のようになります。
arn:aws:dynamodb:region:account:table/name
リージョンとアカウントは前の手順と同じ場所のものですが、name はコンシューマーアプリケー
ションによって作成および使用されるテーブルの名前となります。コンシューマーによって使用
される KCL では、アプリケーション名がテーブル名として使用されます。後で使用されるアプリ
ケーション名である StockTradesProcessor を使用します。
3.
IAM コンソールで、[Policies] ノード (https://console.aws.amazon.com/iam/home#policies) を参照
し、[Create Policy] を選択します。IAM ポリシーを初めて使用する場合は、[Get Started] を選択
します。次に、[Create Policy] を選択します。
4.
[Policy Generator] の横の [Select] をクリックします。
5.
AWS サービスとして [Amazon Kinesis] を選択します。
6.
許可されるアクションとし
て、DescribeStream、GetShardIterator、GetRecords、PutRecord、および
PutRecords を選択します。
7.
ステップ 1 で作成した ARN を入力します。
8.
以下の各項目について、[Add Statement] を使用します。
AWS サービス
アクション
ARN
Amazon DynamoDB
CreateTable、DeleteItem
ステップ
、DescribeTable
2 で作成した 、GetItem、PutItem、PutMetricD
ARN
Amazon CloudWatch
PutMetricData
*
ARN を指定する必要がない場合は、アスタリスク（*）を使用します。CloudWatch に
PutMetricData アクションが呼び出される特定のリソースが存在しない場合などがこれに該当
します。
9.
[Next Step] を選択します。
10. [Policy Name] を StockTradeStreamPolicy に変更し、コードを確認したら、[Create Policy]
を選択します。
その結果コンソールに表示されるポリシードキュメントは、次のようになります。
{
"Version": "2012-10-17",
"Statement": [
{
28
Amazon Kinesis Streams 開発者ガイド
ステップ 2: IAM ポリシーとユーザーを作成する
"Sid": "Stmt123",
"Effect": "Allow",
"Action": [
"kinesis:DescribeStream",
"kinesis:PutRecord",
"kinesis:PutRecords",
"kinesis:GetShardIterator",
"kinesis:GetRecords"
],
"Resource": [
"arn:aws:kinesis:us-west-2:123:stream/StockTradeStream"
]
},
{
"Sid": "Stmt456",
"Effect": "Allow",
"Action": [
"dynamodb:*"
],
"Resource": [
"arn:aws:dynamodb:us-west-2:123:table/StockTradesProcessor"
]
},
{
"Sid": "Stmt789",
"Effect": "Allow",
"Action": [
"cloudwatch:PutMetricData"
],
"Resource": [
"*"
]
}
]
}
IAM ユーザーを作成するには
1.
https://console.aws.amazon.com/iam/ で Identity and Access Management (IAM) コンソールを開
きます。
2.
[Users] ページで、[Create New Users] を選択します。
3.
StockTradeStreamUser と入力し、[Create] を選択します。
4.
[Show User Security Credentials] ノードを展開し、自分しかアクセスできない安全な場所にある
ローカルファイルにアクセスキーとシークレットキーを保存します。このアプリケーションで
は、アクセス権限を厳しく制限した ~/.aws/credentials という名前のファイルを作成しま
す。ファイル形式は次のようになります。
aws_access_key_id=<access key>
aws_secret_access_key=<secret key>
IAM ポリシーをユーザーにアタッチするには
1.
IAM コンソールで、ポリシーページを参照し、[Policy Actions] を選択します。
2.
[StockTradeStreamPolicy] を選択し、[Attach] を選択します。
29
Amazon Kinesis Streams 開発者ガイド
ステップ 3: 実装コードをダウンロードおよびビルドする
3.
StockTradeStreamUser を選択し、[Attach Policy] を選択します。
ステップ 3: 実装コードをダウンロードおよびビル
ドする
株式取引ストリームの取り込み（プロデューサー）およびデータの処理（コンシューマー）用のスタ
ブ実装が含まれたスケルトンコードが提供されています。次の手順は、実装を完了する方法を示して
います。
実装コードをダウンロードおよびビルドするには
1.
ソースコードをコンピューターにダウンロードします。
2.
ソースコード、AWS SDK、ライブラリとしてプロジェクトに追加された Kinesis クライアントラ
イブラリを使用して、お好きな IDE でプロジェクトを作成します。
3.
IDE によっては、プロジェクトが自動的にビルドされる場合があります。自動的にビルドされな
い場合は、IDE に適切なステップを使用してプロジェクトをビルドします。
これらのステップを正常に完了できたら、次のセクションに進むことができます。ビルドのいずれか
の段階でエラーが発生した場合は、先に進む前に、原因を調査および解決する必要があります。
ステップ 4: プロデューサーを実装する
このアプリケーションでは、株式市場取引をモニタリングする実際のシナリオが使用されます。次の
原理によって、このシナリオをプロデューサーおよびサポートコード構造にマッピングすることがで
きます。
ソースコードを参照し、次の情報を確認してください。
StockTrade クラス
個々の株式取引は、StockTrade クラスのインスタンスによって表されます。このクラスには、
ティッカーシンボル、株価、株数、取引のタイプ（買いまたは売り）、取引を一意に識別する ID
などの属性が含まれています。このクラスは、既に実装されています。
ストリームレコード
ストリームとは、一連のレコードのことです。レコードとは、JSON 形式による連続する
StockTrade インスタンスの 1 つを表しています。以下に例を示します。
{"tickerSymbol": "AMZN",
"tradeType": "BUY",
"price": 395.87,
"quantity": 16,
"id": 3567129045}
StockTradeGenerator クラス
StockTradeGenerator には、呼び出されるたびにランダムに生成された新しい株式取引を返
す、getRandomTrade() と呼ばれるメソッドが含まれています。このクラスは、既に実装されて
います。
StockTradesWriter クラス
プロデューサーのメインクラスである、StockTradesWriter は、次のタスクを実行すること
で、継続的にランダム取引を取得し、それらを Streams に送信します。
1. ストリーム名とリージョン名を入力として読み取ります。
2. ~/.aws/credentials から認証情報を読み取ります。
3. それらの認証情報を使用して、AmazonKinesisClient を作成します。
30
Amazon Kinesis Streams 開発者ガイド
ステップ 4: プロデューサーを実装する
4. ストリームが存在し、アクティブであることを確認します（そうでない場合は、エラーで終了
します）。
5. 連続ループで、StockTradeGenerator.getRandomTrade() と sendStockTrade メソッド
を呼び出し、100 ミリ秒ごとに取引をストリームに送信します。
sendStockTrade メソッドは実装されていません。このメソッドは、次のセクション（「プロ
デューサーを実装するには (p. 31)」）で実装します。
プロデューサーを実装するには
•
StockTradesWriter クラスの sendStockTrade メソッドに、次のコードを追加します。
private static void sendStockTrade(StockTrade trade, AmazonKinesis
kinesisClient, String streamName) {
byte[] bytes = trade.toJsonAsBytes();
// The bytes could be null if there is an issue with the JSON
serialization by the Jackson JSON library.
if (bytes == null) {
LOG.warn("Could not get JSON bytes for stock trade");
return;
}
LOG.info("Putting trade: " + trade.toString());
PutRecordRequest putRecord = new PutRecordRequest();
putRecord.setStreamName(streamName);
// We use the ticker symbol as the partition key, explained in the
Supplemental Information section below.
putRecord.setPartitionKey(trade.getTickerSymbol());
putRecord.setData(ByteBuffer.wrap(bytes));
try {
kinesisClient.putRecord(putRecord);
} catch (AmazonClientException ex) {
LOG.warn("Error sending record to Amazon Kinesis.", ex);
}
}
次のコードの詳細を参照してください。
• PutRecord API はバイト配列を想定するため、trade を JSON 形式に変換する必要があります。
この操作は、次の 1 行のコードによって行われます。
byte[] bytes = trade.toJsonAsBytes();
• 取引を送信する前に、新しい PutRecordRequest インスタンス（この場合、putRecord と呼ばれ
る）を作成する必要があります。
PutRecordRequest putRecord = new PutRecordRequest();
各 PutRecord の呼び出しには、ストリーム名、パーティションキー、およびデータ BLOB が必要
です。次のコードによって、setXxxx() メソッドを使用して、これらのフィールドを putRecord
オブジェクトに追加します。
putRecord.setStreamName(streamName);
putRecord.setPartitionKey(trade.getTickerSymbol());
31
Amazon Kinesis Streams 開発者ガイド
ステップ 4: プロデューサーを実装する
putRecord.setData(ByteBuffer.wrap(bytes));
この例では、株式チケットをパーティションキーとして使用することで、レコードを特定のシャー
ドにマッピングしています。実際には、レコードがストリーム全体に均等に分散するように、
シャード 1 つあたりに数百個または数千個のパーティションキーを用意する必要があります。スト
リームにデータを追加する方法の詳細については、「ストリームへのデータの追加 (p. 50)」を参
照してください。
次に、putRecord をクライアントに送信（put オペレーション）することができます。
kinesisClient.putRecord(putRecord);
• エラーチェックとログ記録は、いつでも追加して損はありません。次のコードによって、エラー状
態を記録します。
if (bytes == null) {
LOG.warn("Could not get JSON bytes for stock trade");
return;
}
put オペレーションの前後に try/catch ブロックを追加します。
try {
kinesisClient.putRecord(putRecord);
} catch (AmazonClientException ex) {
LOG.warn("Error sending record to Amazon Kinesis.", ex);
}
これは、ネットワークエラーや、ストリームがスループット限界を超えて抑制されたために
Streams put オペレーションが失敗することがあるためです。データが失われることがないよう
に、単純な再試行として使用するなど、put オペレーションの再試行ポリシーを慎重に検討するこ
とをお勧めします。
• ステータスのログ記録（
LOG.info("Putting trade: " + trade.toString());
）は有益ですが、オプションです。
ここに示されているプロデューサーでは、Streams API のシングルレコード機能（PutRecord）が使
用されています。実際には、個々のプロデューサーで大量のレコードが生成される場合があります。
その場合、PutRecords のマルチレコード機能を頻繁に使用して、レコードのバッチを一度に送信す
る方が効率的です。詳細については、「ストリームへのデータの追加 (p. 50)」を参照してくださ
い。
プロデューサーを実行するには
1.
前のステップ（IAM ユーザーを作成したとき）で取得したアクセスキーとシークレットキーのペ
アがファイル ~/.aws/credentials に保存されていることを確認します。
2.
次の引数を指定して StockTradeWriter クラスを実行します。
StockTradeStream us-west-2
32
Amazon Kinesis Streams 開発者ガイド
ステップ 5: コンシューマーを実装する
us-west-2 以外のリージョンにストリームを作成した場合は、代わりにそのリージョンをここで
指定する必要があります。
次のような出力が表示されます。
Feb 16, 2015 3:53:00 PM
com.amazonaws.services.kinesis.samples.stocktrades.writer.StockTradesWriter
sendStockTrade
INFO: Putting trade: ID 8: SELL 996 shares of BUD for $124.18
Feb 16, 2015 3:53:00 PM
com.amazonaws.services.kinesis.samples.stocktrades.writer.StockTradesWriter
sendStockTrade
INFO: Putting trade: ID 9: BUY 159 shares of GE for $20.85
Feb 16, 2015 3:53:01 PM
com.amazonaws.services.kinesis.samples.stocktrades.writer.StockTradesWriter
sendStockTrade
INFO: Putting trade: ID 10: BUY 322 shares of WMT for $90.08
Streams によって株式取引ストリームが取り込まれます。
ステップ 5: コンシューマーを実装する
ここでは、「ステップ 4: プロデューサーを実装する (p. 30)」で作成した株式取引ストリームを
継続的に処理し、1 分間ごとに売買されている最も人気のある株式を出力するコンシューマーアプリ
ケーションを開発します。KCL 上に構築されたこのアプリケーションは、コンシューマーアプリケー
ションにありがちな多くの面倒な作業を行います。詳細については、「Amazon Kinesis Client Library
を使用した Amazon Kinesis Streams コンシューマーの開発 (p. 66)」を参照してください。
ソースコードを参照し、次の情報を確認してください。
StockTradesProcessor クラス
事前に用意されているコンシューマーのメインクラスで、次のタスクを実行します。
• 引数として渡されたアプリケーション、ストリーム、およびリージョン名を読み取ります。
• ~/.aws/credentials から認証情報を読み取ります。
• RecordProcessor のインスタンスとして機能し、StockTradeRecordProcessor インスタ
ンスによって実装される、RecordProcessorFactory インスタンスを作成します。
• RecordProcessorFactory インスタンスおよび標準設定（ストリーム名、認証情報、アプリ
ケーション名など）が指定された KCL ワーカーを作成します。
• このワーカーは、（このコンシューマーインスタンスに割り当てられた）各シャードに新しい
スレッドを作成し、継続的に Streams からレコードを読み取り、RecordProcessor インスタ
ンスを呼び出して受信したレコードのバッチを処理します。
StockTradeRecordProcessor クラス
RecordProcessor インスタンスを実装したら、次に
initialize、processRecords、shutdown の 3 つの必須メソッドを実装します。
KCL によって使用される initialize および shutdown は、名前が示すとおり、レコードの受
信がいつ開始し、いつ終了するかをレコードプロセッサに知らせます。これにより、レコードプ
ロセッサは、アプリケーションに固有の設定および終了タスクを行うことができます。これらの
コードは事前に用意されています。主な処理は processRecords メソッドで行われ、そこでは
各レコードの processRecord が使用されます。後者のメソッドは、ほとんどの場合、空のス
ケルトンコードとして提供されます。次のステップでは、これを実装する方法について説明しま
す。詳細は、次のステップを参照してください。
また、processRecord のサポートメソッドである reportStats および resetStats の実装に
も注目してください。これらのメソッドは、元のソースコードでは空になっています。
33
Amazon Kinesis Streams 開発者ガイド
ステップ 5: コンシューマーを実装する
processsRecords メソッドは既に実装されており、次のステップを実行します。
• 渡された各レコードについて、レコード上で processRecord を呼び出します。
• 最後のレポートから 1 分間以上経過すると、reportStats() を呼び出して最新の統計を出力
し、次の間隔に新しいレコードだけが含まれるように resetStats() を呼び出して統計を消去
します。
• 次のレポート時間を設定します。
• 最後のチェックポイントから 1 分間以上経過すると、checkpoint() を呼び出します。
• 次のチェックポイント時間を設定します。
このメソッドでは、60 秒間間隔でレポートおよびチェックポイント時間が設定されています。
チェックポイントの詳細については、「コンシューマーに関する追加情報 (p. 35)」を参照して
ください。
StockStats クラス
このクラスでは、データを保持し、最も人気のある株式の経時的な統計を示すことができます。
このコードは、事前に用意されており、次のメソッドが含まれています。
• addStockTrade(StockTrade): 指定された StockTrade を実行中の統計に取り込みます。
• toString(): 特定の形式の文字列として統計を返します。
このクラスは、各株式の合計取引数と最大取引数を継続的にカウントすることによって、最も人
気のある株式を追跡します。このクラスは、株式取引を受信するたびにこれらの数を更新しま
す。
次のステップに示されているコードを StockTradeRecordProcessor クラスのメソッドに追加しま
す。
コンシューマーを実装するには
1.
processRecord メソッドを実装するには、サイズの正しい StockTrade オブジェクトを開始
し、それにレコードデータを追加します。また、問題が発生した場合に警告がログに記録される
ようにします。
StockTrade trade = StockTrade.fromJsonAsBytes(record.getData().array());
if (trade == null) {
LOG.warn("Skipping record. Unable to parse record into StockTrade.
Partition Key: " + record.getPartitionKey());
return;
}
stockStats.addStockTrade(trade);
2.
簡単な reportStats メソッドを実装します。出力形式は好みに応じて自由に変更することがで
きます。
System.out.println("****** Shard " + kinesisShardId + " stats for last 1
minute ******\n" +
stockStats + "\n" +
"****************************************************************\n");
3.
最後に、新しい stockStats インスタンスを作成する resetStats メソッドを実装します。
stockStats = new StockStats();
34
Amazon Kinesis Streams 開発者ガイド
ステップ 5: コンシューマーを実装する
コンシューマーを実行するには
1.
2.
3.
前のモジュールで記述したプロデューサーを実行し、シミュレートした株式取引レコードをスト
リームに取り込みます。
前のステップ（IAM ユーザーを作成したとき）で取得したアクセスキーとシークレットキーのペ
アがファイル ~/.aws/credentials に保存されていることを確認します。
次の引数を指定して StockTradesProcessor クラスを実行します。
StockTradesProcessor StockTradeStream us-west-2
us-west-2 以外のリージョンにストリームを作成した場合は、代わりにそのリージョンをここで
指定する必要があります。
1 分後、次のような出力が表示されます。その後、1 分間ごとに出力が更新されます。
****** Shard shardId-000000000001 stats for last 1 minute ******
Most popular stock being bought: WMT, 27 buys.
Most popular stock being sold: PTR, 14 sells.
****************************************************************
コンシューマーに関する追加情報
「Amazon Kinesis Client Library を使用した Amazon Kinesis Streams コンシューマーの開
発 (p. 66)」などで説明されている KCL のメリットに詳しい方であれば、それをここで使用する必
要があるのはなぜだろうかと思われるかもしれません。1 つのシャードストリームとそれを処理する
1 つのコンシューマーインスタンスしか使用しない場合でも、KCL を使用してコンシューマーを実装
する方が簡単です。プロデューサーセクションとコンシューマーセクションのコードの実装手順を比
較すると、コンシューマーの実装の方が比較的に簡単であることがわかります。これは、KCL で提供
されているサービスが大きく関係しています。
このアプリケーションでは、個別のレコードを処理できるレコードプロセッサクラスの実装に焦点を
合わせてきました。新しいレコードを取得できるようになると、KCL がレコードを取得し、レコード
プロセッサを呼び出すため、レコードを Streams から取得する方法を心配しなくて済みます。また、
発生するシャードやコンシューマーインスタンスの数について心配しなくて済みます。ストリームが
大きくなっても、複数のシャードまたはコンシューマーインスタンスを処理できるようにアプリケー
ションを書き直す必要はありません。
チェックポイントとは、ストリームにおける特定のポイントのことで、それまでに消費および処理さ
れたデータレコードが記録されます。このため、アプリケーションがクラッシュしても、ストリーム
の始めからではなく、そのポイントからストリームが読み取られます。チェックポイント、チェック
ポイントのさまざまな設計パターンおよびベストプラクティスは、この章の範囲外ですが、本番環境
ではこれらの問題に直面することがあります。
「ステップ 4: プロデューサーを実装する (p. 30)」で学習したように、Streams API の put オペ
レーションは、パーティションキーを入力として受け取ります。パーティションキーは、Streams が
レコードを複数のシャードに分割する場合に使用します（複数のシャードがストリームに含まれる場
合）。同じパーティションキーは、常に同じシャードにルーティングされます。このため、同じパー
ティションキーを持つレコードはそのコンシューマーにのみ送信され、他のコンシューマーに送信
されることはないと仮定して、特定のシャードを処理するコンシューマーを設計できます。したがっ
て、コンシューマーのワーカーは、必要なデータが欠落しているかもしれないと心配することなく、
同じパーティションキーを持つすべてのレコードを集計できます。
このアプリケーションでは、コンシューマーによるレコードの処理が大変でないため、1 つのシャー
ドを使用し、KCL スレッドと同じスレッドで処理を行うことができます。実際には、まずシャード
の数を増やすことを検討する必要があるかもしれません。この点については、このシリーズの次のモ
ジュールで説明されます。レコードの処理が大変になることが予想される場合は、異なるスレッドに
35
Amazon Kinesis Streams 開発者ガイド
ステップ 6: （オプション）コンシューマーを拡張する
処理を切り替えたり、スレッドプールを使用したりする必要があるかもしれません。このように、そ
の他のスレッドがレコードを並列処理していても、KCL は新しいレコードを迅速に取得できます。一
般的に、マルチスレッド設計は簡単ではなく高度な技術が必要になるため、シャードの数を増やすこ
とが最も効果的で簡単な拡張方法です。
ステップ 6: （オプション）コンシューマーを拡張
する
ここに示すアプリケーションは、すでに目的を十分に果たしているかもしれません。このオプション
のセクションでは、少し複雑なシナリオにも対応できるようにコンシューマーコードを拡張する方法
について説明します。
1 分ごとに最大の売り注文を知りたい場合、3 箇所の StockStats クラスを変更し、新しい優先順位
を組み込むだけで行うことができます。
カスタマーを拡張するには
1.
新しいインスタンス変数を追加します。
// Ticker symbol of the stock that had the largest quantity of shares
sold
private String largestSellOrderStock;
// Quantity of shares for the largest sell order trade
private long largestSellOrderQuantity;
2.
次のコードを addStockTrade に追加します。
if (type == TradeType.SELL) {
if (largestSellOrderStock == null || trade.getQuantity() >
largestSellOrderQuantity) {
largestSellOrderStock = trade.getTickerSymbol();
largestSellOrderQuantity = trade.getQuantity();
}
}
3.
toString メソッドを変更し、追加情報を出力します。
public String toString() {
return String.format(
"Most popular stock being bought: %s, %d buys.%n" +
"Most popular stock being sold: %s, %d sells.%n" +
"Largest sell order: %d shares of %s.",
getMostPopularStock(TradeType.BUY),
getMostPopularStockCount(TradeType.BUY),
getMostPopularStock(TradeType.SELL),
getMostPopularStockCount(TradeType.SELL),
largestSellOrderQuantity, largestSellOrderStock);
}
コンシューマーを今すぐ実行すると（プロデューサーも忘れずに実行してください）、次のような出
力が表示されます。
****** Shard shardId-000000000001 stats for last 1 minute ******
Most popular stock being bought: WMT, 27 buys.
Most popular stock being sold: PTR, 14 sells.
36
Amazon Kinesis Streams 開発者ガイド
ステップ 7: 終了する
Largest sell order: 996 shares of BUD.
****************************************************************
ステップ 7: 終了する
Amazon Kinesis stream の使用には料金がかかるため、作業が終わったら、必ずストリームとそれに
対応する DynamoDB テーブルを削除してください。レコードを送信したり取得したりしていなくて
も、ストリームがアクティブなだけでわずかな料金が発生します。その理由として、アクティブなス
トリームでは、受信レコードを継続的に "リッスン" し、レコードを取得するようにリクエストするこ
とにリソースが使用されるためです。
ストリームおよびテーブルを削除するには
1.
実行しているプロデューサーおよびコンシューマーをすべてシャットダウンします。
2.
https://console.aws.amazon.com/kinesis にある Amazon Kinesis コンソールを開きます。
3.
ストリームリストで、このアプリケーション（StockTradeStream）に作成したストリームを選
択し、[Delete Stream] を選択します。
4.
https://console.aws.amazon.com/dynamodb/ にある DynamoDB コンソールを開きます。
5.
StockTradesProcessor テーブルを削除します。
概要
ほぼリアルタイムで大量のデータを処理するために、魔法のコードを記述したり、大規模なインフラ
ストラクチャを開発したりする必要はありません。Streams を使用すれば、少量のデータを処理する
ロジックを記述する（processRecord(Record) を記述する）場合と同じくらい簡単に、大量のス
トリーミングデータにも対応できるように拡張することができます。Streams が代わりに処理してく
れるため、処理を拡張する方法を心配しなくて済みます。することと言えば、ストリームレコードを
Streams に送信し、受信した新しい各レコードを処理するロジックを記述するだけです。
このアプリケーションについて考えられる拡張機能は、次のとおりです。
すべてのシャードで集計する
現在、単一のワーカーおよび単一のシャードから取得したデータレコードを集計した統計が表示
されています（単一のアプリケーションでは、シャードを複数のワーカーによって同時に処理
することはできません）。拡張するときに複数のシャードがある場合、すべてのシャードで集
計したいと思われるかもしれません。その場合、パイプラインアーキテクチャを用意することが
できます。パイプラインアーキテクチャでは、各ワーカーの出力が単一のシャードを持つ別のス
トリームに供給され、第 1 段階の出力を集計するワーカーによってそのストリームが処理され
ます。第 1 段階のデータが制限（シャードおよび 1 分間あたり 1 つのサンプル）されるため、
シャードごとに処理しやすくなります。
処理の拡張
多数のシャードが含まれるようにストリームを拡張する場合（多数のプロデューサーがデータを
送信している場合）、処理を拡張するには、より多くのワーカーを追加します。ワーカーを EC2
インスタンスで実行し、Auto Scaling グループを活用することができます。
S3/DynamoDB/Redshift/Storm までのコネクタを活用する
ストリームは継続的に処理されるため、出力を他の保存先に送信することができます。AWS に
は、Streams を他の AWS サービスおよびサードパーティ製ツールと統合するためのコネクタが
用意されています。
次のステップ
• Streams API オペレーションの使用方法については、「Amazon Kinesis Streams API と AWS SDK
for Java を使用した Amazon Kinesis Streams プロデューサーの開発 (p. 49)」、「Amazon
37
Amazon Kinesis Streams 開発者ガイド
ステップ 7: 終了する
Kinesis Streams API および AWS SDK for Java を使用した Amazon Kinesis Streams コンシュー
マーの開発 (p. 82)」、および「Amazon Kinesis Stream の管理 (p. 96)」を参照してくださ
い。
• Kinesis クライアントライブラリの詳細については、「Amazon Kinesis Client Library を使用した
Amazon Kinesis Streams コンシューマーの開発 (p. 66)」を参照してください。
• アプリケーションを最適化する方法については、「高度なトピック (p. 89)」を参照してくださ
い。
38
Amazon Kinesis Streams 開発者ガイド
ストリームへのデータの書き込み
Amazon Kinesis Streams の使用
このドキュメントでは、Amazon Kinesis Streams を使用するための情報を示します。Streams を初
めて利用する場合は、Amazon Kinesis Streams とは? (p. 1) と Amazon Kinesis Streams の使用開
始 (p. 9) に説明されている概念と用語について理解することから始めてください。
トピック
• Amazon Kinesis Streams へのデータの書き込み (p. 39)
• Amazon Kinesis Streams からのデータの読み取り (p. 66)
• Amazon Kinesis Stream の管理 (p. 96)
• Amazon Kinesis Streams のモニタリング (p. 105)
• Amazon Kinesis Streams でのストリームのタグ付け (p. 130)
• IAM により Amazon Kinesis Streams リソースへのアクセスを制御する (p. 133)
Amazon Kinesis Streams へのデータの書き込み
プロデューサーは、Amazon Kinesis Streams にデータを書き込むアプリケーションです。Streams
のプロデューサーを構築できます 。Streams を初めて利用する場合は、Amazon Kinesis Streams と
は? (p. 1) と Amazon Kinesis Streams の使用開始 (p. 9) に説明されている概念と用語について理解す
ることから始めてください。
トピック
• Amazon Kinesis プロデューサライブラリ を使用した Amazon Kinesis Streams プロデューサーの
開発 (p. 39)
• Amazon Kinesis Streams API と AWS SDK for Java を使用した Amazon Kinesis Streams プロ
デューサーの開発 (p. 49)
• Amazon Kinesis エージェントを使用して Amazon Kinesis Streams への書き込み (p. 54)
• Amazon Kinesis Streams プロデューサーのトラブルシューティング (p. 63)
• Amazon Kinesis Streams プロデューサーについての高度なトピック (p. 64)
Amazon Kinesis プロデューサライブラリ を使用し
た Amazon Kinesis Streams プロデューサーの開発
Amazon Kinesis Streams プロデューサーは、ユーザーデータレコードを Amazon Kinesis stream に
配置するアプリケーションです（データ取り込みとも呼ばれます）。Amazon Kinesis プロデューサ
39
Amazon Kinesis Streams 開発者ガイド
KPL の使用
ライブラリ（KPL）を使用すると、プロデューサーアプリケーションの開発が簡素化され、開発者は
Amazon Kinesis stream に対する優れた書き込みスループットを実現できます。
Amazon CloudWatch を使用して KPL をモニタリングできます。詳細については、「Amazon
CloudWatch による Amazon Kinesis プロデューサーライブラリのモニタリング (p. 126)」を参照し
てください。
目次
• KPL の役割 (p. 40)
• KPL を使用するメリット (p. 40)
• KPL の使用が適さない場合 (p. 41)
• インストール (p. 41)
• サポートされているプラットフォーム (p. 42)
• 主要なコンセプト (p. 42)
• プロデューサーコードとの統合 (p. 44)
• KPL を使用した Streams ストリームへの書き込み (p. 45)
• KPL の設定 (p. 46)
• コンシューマーの集約解除 (p. 47)
KPL の役割
KPL は使いやすく、Amazon Kinesis stream への書き込みに役立つ、高度な設定が可能なライブラリ
です。これは、プロデューサーアプリケーションのコードと Streams API アクション間の仲介として
機能します。KPL は次の主要なタスクを実行します。
• 自動的で設定可能な再試行メカニズムにより 1 つ以上の Amazon Kinesis stream へ書き込む
• レコードを収集し、PutRecords を使用して、リクエストごとに複数シャードへ複数レコードを書
き込む
• ユーザーレコードを集約し、ペイロードサイズを増加させ、スループットを改善する
• コンシューマーで Amazon Kinesis Client Library（KCL）とシームレスに統合して、バッチ処理され
たレコードを集約解除する
• Amazon CloudWatch メトリックスをユーザーに代わって送信し、プロデューサーのパフォーマン
スを確認可能にする
KPL は AWS SDK で使用できる Streams API とは異なることに注意してください。Streams API は
Streams の多くの要素（ストリームの作成、リシャーディング、レコードの入力と取得など）を管
理するのに役立ちます。一方、KPL はデータの取り込みに特化した抽象化層を提供します。Streams
API の詳細については、Amazon Kinesis API Reference を参照してください。
KPL を使用するメリット
Streams プロデューサーを開発するために KPL を使用するいくつかの主な利点を次のリストに示しま
す。
KPL は、同期または非同期のユースケースで使用できます。同期動作を使用する特別な理由がない
かぎり、非同期インターフェイスの優れたパフォーマンスを使用することを推奨します。これら 2 つ
のユースケースの詳細とコード例については、「KPL を使用した Streams ストリームへの書き込み
(p. 45)」を参照してください。
パフォーマンスのメリット
KPL は、高性能のプロデューサーの構築に役立ちます。Amazon EC2 インスタンスをプロキ
シとして、100 バイトのイベントを数百または数千の低電力デバイスから収集し、レコードを
Amazon Kinesis stream に書き込む状況を考えてみます。これらの EC2 インスタンスはそれぞ
40
Amazon Kinesis Streams 開発者ガイド
KPL の使用
れ、毎秒数千イベントを Amazon Kinesis stream に書き込む必要があります。必要なスループッ
トを実現するには、お客様の側で、再試行ロジックとレコード集約解除に加え、バッチ処理やマ
ルチスレッドなどの複雑なロジックをプロデューサーに実装する必要があります。KPL が、これ
らのタスクをすべて実行します。
コンシューマー側の使いやすさ
コンシューマー側の開発者が Java で KCL 使用する場合、追加作業なしで KPL が統合されま
す。KCL で、複数の KPL ユーザーレコードで構成されている集約された Streams レコードを取
得するときは、自動的に KPL が呼び出され、個々のユーザーレコードが抽出され、ユーザーに返
されます。
KCL を使用せずに API オペレーション GetRecords を直接使用するコンシューマー側の開発者
の場合、KPL Java ライブラリを使用して個々のユーザーレコードを抽出してから、それらのレ
コードをユーザーに返すことができます。
プロデューサーのモニタリング
Amazon CloudWatch と KPL を使用して、Streams プロデューサーを収集、モニタリング、分析
できます。KPL は、スループット、エラー、およびその他のメトリックスをユーザーに代わって
CloudWatch に送信し、ストリーム、シャード、またはプロデューサーレベルでモニタリングす
るように設定できます。
非同期アーキテクチャ
KPL は、レコードを Streams に送信する前にそれらのレコードをバッファ処理する場合がある
ため、実行を続行する前にレコードがサーバーに到着したことを確認するために、発信者アプリ
ケーションを強制的にブロックし待機させることはしません。レコードを KPL に配置する呼び出
しは、必ずすぐに処理が戻り、レコードの送信やサーバーからの応答の受信を待ちません。代わ
りに、レコードを Streams に送信した結果を後で受信するための Future オブジェクトが作成さ
れます。これは、AWS SDK の非同期クライアントと同じ動作です。
KPL の使用が適さない場合
KPL では、ライブラリ内で最大 RecordMaxBufferedTime まで追加の処理遅延が生じる場合があ
ります（ユーザーが設定可能）。RecordMaxBufferedTime の値が大きいほど、パッキング効率と
パフォーマンスが向上します。この追加的な遅延を許容できないアプリケーションは、AWS SDK を
直接使用することが必要になる場合があります。AWS SDK を Streams と組み合わせて使用する方
法については、「Amazon Kinesis Streams API と AWS SDK for Java を使用した Amazon Kinesis
Streams プロデューサーの開発 (p. 49)」を参照してください。RecordMaxBufferedTime などの
KPL のユーザー設定可能なプロパティの詳細については、「KPL の設定 (p. 46)」を参照してくだ
さい。
インストール
Amazon では、OS X と Windows、そして最新の Linux ディストリビューション向けに C++ KPL のビ
ルド済みバイナリを提供しています（サポートされているプラットフォームの詳細については、次の
セクションを参照してください）。 これらのバイナリは、Java の .jar ファイルの一部としてパッケー
ジ化されており、Maven を使用してパッケージをインストールする場合、自動的に呼び出され、使用
されます。KPL と KCL の最新バージョンを確認するには、次の Maven サーチリンクをご利用くださ
い。
• KPL
• KCL
Linux のバイナリは、GCC でコンパイルされ、Linux の libstdc++ に静的にリンクされています。 こ
れらのバイナリは、glibc バージョン 2.5 以降を含むすべての 64 ビット Linux ディストリビューショ
ンで動作することが推定されています。
以前のバージョンの Linux ディストリビューションのユーザーは、Github のソースとともに提供さ
れるビルド手順で KPL をビルドできます。 KPL を GitHub からダウンロードするには、「Amazon
Kinesis プロデューサライブラリ」を参照してください。
41
Amazon Kinesis Streams 開発者ガイド
KPL の使用
サポートされているプラットフォーム
KPL は、C++ で書かれており、メインユーザープロセスの子プロセスとして実行されます。プリコ
ンパイルされている 64 ビットのネイティブバイナリは、Java ベースにバンドルされており、Java
wrapper によって管理されます。
次のオペレーティングシステムでは、追加ライブラリをインストールすることなく Java のパッケー
ジを実行できます。
• カーネルバージョン 2.6.18（2006 年 9 月）の Linux ディストリビューション以降
• Apple OS X 10.9 以降
• Windows Server 2008 以降
KPL は、64 ビット版のみであることに注意してください。
ソースコード
KPL のインストールで提供されるバイナリがお客様の環境に適さない場合は、KPL のコアが C+
+ のモジュールとして書き込まれます。C++ モジュールと Java インターフェイスのソースコード
は、Amazon パブリックライセンスの下で公開され、GitHub の Amazon Kinesis プロデューサライブ
ラリ で入手できます。KPL は、最近の規格に準拠した C++ コンパイラと JRE を使用できるすべての
プラットフォームで使用できますが、Amazon では、サポートされるプラットフォームの一覧にない
プラットフォームを正式にはサポートしません。
主要なコンセプト
以下のセクションでは、KPL を理解し、そのメリットを引き出すために必要な概念と用語について説
明します。
トピック
• レコード (p. 42)
• バッチ処理 (p. 42)
• 集約 (p. 43)
• Collection (p. 43)
レコード
このガイドでは、KPL ユーザーレコードと Streams レコードを区別します。修飾語を付けずにレコー
ドという用語を使用する場合は、KPL ユーザーレコードを意味します。Streams レコードを意味する
ときは、明示的に Streams レコードと表現します。
KPL ユーザーレコードは、ユーザーにとって特定の意味のあるデータの BLOB です。たとえば、ウェ
ブサイトの UI イベントまたはウェブサーバーのログエントリを表す JSON BLOB がそれに該当しま
す。
Streams レコードは、Streams サービス API で定義された Record データ構造のインスタンスです。
これには、パーティションキー、シーケンス番号、データの BLOB が含まれています。
バッチ処理
バッチ処理は、各項目に対して単一のアクションを繰り返し実行する代わりに、複数の項目に対して
そのアクションを実行することを意味します。
ここでは、「項目」はレコードに対応し、「アクション」はレコードを Streams に送信することに対
応します。バッチ処理を使用しない場合、各レコードを別々の Streams レコードに配置し、それぞれ
42
Amazon Kinesis Streams 開発者ガイド
KPL の使用
を Streams に送信するたびに HTTP リクエストを実行します。バッチ処理では、各 HTTP リクエスト
により、1 つではなく複数のレコードを処理できます。
KPL では、2 種類のバッチ処理がサポートされます。
• 集約 – 複数のレコードを単一の Streams レコードに格納します。
• 収集 – API オペレーション PutRecords を使用して、Amazon Kinesis stream 内の 1 つ以上の
シャードに複数の Streams レコードを送信します。
2 種類の KPL バッチ処理は、共存できるように設計されており、互いに独立して有効または無効にで
きます。デフォルトでは、どちらも有効です。
集約
集約は、複数レコードを 1 つの Streams レコードに保存することを意味します。集約を使用する
と、API 呼び出しごとに送信されるレコード数を増やすことができ、効率的にプロデューサーのス
ループットを高めることができます。
Streams シャードは、1 秒あたり最大で 1,000 Streams レコードまたは 1 MB のスループットをサ
ポートします。1 秒あたりの Streams レコードの制限により、お客様のレコードは 1 KB 未満に制限
されます。レコードの集約を使用すると、複数のレコードを単一の Streams レコードに結合できま
す。そのため、お客様はシャードあたりのスループットを改善することができます。
リージョンが us-east-1 の 1 つのシャードで、1 つが 512 バイトのレコードを 1 秒あたり 1,000
レコードの一定割合で処理する場合を考えます。KPL の集約を使用すると、1,000 レコードを 10
Streams レコードに詰めることができ、RPS を 10 に減らすことができます（それぞれ 50 KB）。
Collection
収集は、各 Streams レコードをそれぞれの HTTP リクエストで送信するのではなく、複数の Streams
レコードをバッチ処理し、API オペレーション PutRecords を呼び出して単一の HTTP リクエストで
それらを送信することを意味します。
これにより、個別の HTTP リクエストを多数実行するオーバーヘッドが減るため、収集を使用しない
場合に比べスループットが向上します。実際、PutRecords 自体が、この目的のために設計されてい
ます。
収集は、Streams レコードのグループを使用している点で集約と異なります。収集された Streams レ
コードには、ユーザーの複数のレコードをさらに含めることができます。この関係は、次のように図
示できます。
record 0 --|
record 1
|
[ Aggregation ]
...
|--> Amazon Kinesis record 0 --|
...
|
|
record A --|
|
|
...
...
|
|
record K --|
|
record L
|
|
[ Collection ]
...
|--> Amazon Kinesis record C --|--> PutRecords Request
...
|
|
record S --|
|
|
...
...
|
|
43
Amazon Kinesis Streams 開発者ガイド
KPL の使用
record AA--|
|
record BB |
|
...
|--> Amazon Kinesis record M --|
...
|
record ZZ--|
プロデューサーコードとの統合
KPL は独立したプロセスで実行され、IPC を使用して親ユーザープロセスと通信します。このアーキ
テクチャは、マイクロサービスと呼ばれる場合があり、次の 2 つの主な理由からこれが選択されま
す。
1) KPL がクラッシュしても、ユーザープロセスはクラッシュしません
プロセスには Streams と無関係なタスクが含まれている場合があり、KPL がクラッシュしてもオペ
レーションを続行できます。また、親ユーザープロセスが KPL を再起動し、完全に機能する状態に復
旧することもできます（この機能は、正式なラッパーに含まれています）。
メトリックスを Streams に送信するウェブサーバーがその例です。このサーバーは、Streams 部分
が動作を停止してもページの提供を続行できます。そのため、KPL のバグが原因でサーバー全体がク
ラッシュすると、不要なサービス停止が発生します。
2) 任意のクライアントをサポートできます
正式にサポートされている言語以外の言語を使用するお客様もいます。これらのお客様も KPL を簡単
に使用できます。
推奨される使用状況
使用状況の異なるユーザーに推奨される設定を次の表に示します。この表を参考に、KPL を使用でき
るかどうか、どのように使用できるかを判断できます。集約が有効な場合、コンシューマー側で集約
解除を使用してレコードを抽出する必要があることにも注意してください。
プロデュー
サー側の言語
コンシュー
マー側の
KCL バージョ
ン
チェックポイ
ントロジック
KPL の使用可
否
注意
言語
Java 以外
*
*
*
いいえ
該当なし
Java
Java
Java SDK を直
接使用
該当なし
はい
集約を使
用する場
合、GetRecords
を呼び出した
後に、提供さ
れた集約解除
ライブラリを
使用する必要
があります。
Java
Java 以外
SDK を直接使
用
該当なし
はい
集約を無効に
する必要があ
ります。
Java
Java
1.3.x
該当なし
はい
集約を無効に
する必要があ
ります。
44
Amazon Kinesis Streams 開発者ガイド
KPL の使用
Java
Java
1.4.x
引数なしで
チェックポイ
ントを呼び出
す
はい
なし
Java
Java
1.4.x
明示的なシー
ケンス番号
を使用して
チェックポイ
ントを呼び出
す
はい
集約を無効に
するかコー
ドを変更し、
チェックポ
イント作成用
の拡張された
シーケンス番
号を使用しま
す。
Java
Java 以外
1.3.x + 複数
言語デーモン
+ 言語固有の
ラッパー
該当なし
はい
集約を無効に
する必要があ
ります。
KPL を使用した Streams ストリームへの書き込み
以下のセクションでは、最もシンプルな「最低限」のプロデューサーから完全に非同期なコードまで
順にサンプルコードを示します。
最低限のプロデューサーコード
次のコードは、最小限の機能するプロデューサーを書くために必要なものがすべて含まれていま
す。KPL ユーザーレコードはバックグラウンドで処理されます。
// KinesisProducer gets credentials automatically like
// DefaultAWSCredentialsProviderChain.
// It also gets region automatically from the EC2 metadata service.
KinesisProducer kinesis = new KinesisProducer();
// Put some records
for (int i = 0; i < 100; ++i) {
ByteBuffer data = ByteBuffer.wrap("myData".getBytes("UTF-8"));
// doesn't block
kinesis.addUserRecord("myStream", "myPartitionKey", data);
}
// Do other stuff ...
結果に対する同期的な応答
前のコード例では、KPL ユーザーレコードが成功したかどうかをチェックしませんでした。KPL
は、失敗に対処するために必要な再試行を実行しますが、結果を確認する必要がある場合には、次
の例（分かりやすくするため前の例を使用しています）のように、addUserRecord から返される
Future オブジェクトを使用して結果を確認します。
KinesisProducer kinesis = new KinesisProducer();
// Put some records and save the Futures
List<Future<UserRecordResult>> putFutures = new
LinkedList<Future<UserRecordResult>>();
for (int i = 0; i < 100; i++) {
45
Amazon Kinesis Streams 開発者ガイド
KPL の使用
ByteBuffer data = ByteBuffer.wrap("myData".getBytes("UTF-8"));
// doesn't block
putFutures.add(
kinesis.addUserRecord("myStream", "myPartitionKey", data));
}
// Wait for puts to finish and check the results
for (Future<UserRecordResult> f : putFutures) {
UserRecordResult result = f.get(); // this does block
if (result.isSuccess()) {
System.out.println("Put record into shard " +
result.getShardId());
} else {
for (Attempt attempt : result.getAttempts()) {
// Analyze and respond to the failure
}
}
}
結果に対する非同期的な応答
前の例では、Future オブジェクトに対して get() を呼び出しているため、実行がブロックされま
す。実行のブロックを避ける必要がある場合には、次の例に示すように非同期コールバックを使用で
きます。
KinesisProducer kinesis = new KinesisProducer();
FutureCallback<UserRecordResult> myCallback =
new FutureCallback<UserRecordResult>() {
@Override public void onFailure(Throwable t) {
/* Analyze and respond to the failure */
};
@Override
public void onSuccess(UserRecordResult result) {
/* Respond to the success */
};
};
for (int i = 0; i < 100; ++i) {
ByteBuffer data = ByteBuffer.wrap("myData".getBytes("UTF-8"));
ListenableFuture<UserRecordResult> f =
kinesis.addUserRecord("myStream", "myPartitionKey", data);
// If the Future is complete by the time we call addCallback,
//the callback will be invoked immediately.
Futures.addCallback(f, myCallback);
}
KPL の設定
デフォルト設定のままで、ほとんどのユースケースに問題なく使用できますが、デフォルト設定の一
部を変更することで、ニーズに合わせて KinesisProducer の動作を調整することができます。それ
には、KinesisProducerConfiguration クラスのインスタンスを KinesisProducer コンストラ
クタに渡します。たとえば、次のようにします。
KinesisProducerConfiguration config = new KinesisProducerConfiguration()
.setRecordMaxBufferedTime(3000)
.setMaxConnections(1)
.setRequestTimeout(60000)
46
Amazon Kinesis Streams 開発者ガイド
KPL の使用
.setRegion("us-west-1");
final KinesisProducer kinesisProducer = new KinesisProducer(config);
プロパティファイルから設定をロードすることもできます。
KinesisProducerConfiguration config =
KinesisProducerConfiguration.fromPropertiesFile("default_config.properties");
ユーザープロセスがアクセスできる任意のパスとファイル名に置き換えることができます。さらに、
このようにして作成した KinesisProducerConfiguration インスタンスに対して設定メソッドを
呼び出して、設定をカスタマイズできます。
プロパティファイルでは、PascalCase 内の名前を使用してパラメータを指定する必要があります。そ
の名前は、KinesisProducerConfiguration クラスの設定メソッドで使用されるものと一致しま
す。以下に例を示します。
RecordMaxBufferedTime = 100
MaxConnections = 4
RequestTimeout = 6000
Region = us-west-1
設定パラメータの使用方法と値の制限の詳細については、「GitHub のサンプル設定プロパティファイ
ル」を参照してください。
KinesisProducer を初期化した後、使用した KinesisProducerConfiguration インスタンスを
変更しても何の効果もないことに注意してください。KinesisProducer は現在、動的再設定をサ
ポートしていません。
コンシューマーの集約解除
KCL は、リリース 1.4.0 から KPL ユーザーレコードの自動集計解除をサポートしています。以前の
バージョンの KCL で書かれたコンシューマーアプリケーションのコードは、KCL を更新した後、
コードを何も修正せずにコンパイルできます。ただし、プロデューサー側で KPL の集約を使用してい
る場合、チェックポイントが多少関係してきます。集約されたレコード内のすべてのサブレコードは
同じシーケンス番号を持っているため、サブレコード間の区別が必要な場合、チェックポイントを使
用して追加のデータを保存する必要があります。この追加データは、サブシーケンス番号と呼ばれま
す。
以前のバージョンの KCL からの移行
集約とともにチェックポイントを作成する既存の呼び出しを変更する必要はありません。Streams に
保存されているすべてのレコードを正しく取得できることが保証されています。以下で説明する特定
のユースケースをサポートするために、現在 KCL には、2 つの新しいチェックポイントオペレーショ
ンが用意されています。
既存のコードが KPL サポート以前の KCL 用に書かれていて、チェックポイントオペレーションが
引数なしで呼び出される場合、そのコードの動作は、バッチ内にある最後の KPL ユーザーレコード
のシーケンス番号に対するチェックポイントの作成と同等です。シーケンス番号文字列を使用して
チェックポイントオペレーションを呼び出す場合は、暗黙的なサブシーケンス番号 0（ゼロ）を伴
う、バッチの指定されたシーケンス番号に対するチェックポイントの作成と同等です。
引数なしで新しい KCL チェックポイントオペレーション checkpoint() を呼び出すことは、暗黙的
なサブシーケンス番号 0（ゼロ）を伴う、バッチ内の最後の Record 呼び出しのシーケンス番号に対
するチェックポイントの作成と意味的に同等です。
47
Amazon Kinesis Streams 開発者ガイド
KPL の使用
新しい KCL チェックポイントオペレーション checkpoint(Record record) を呼び出すことは、
暗黙的なサブシーケンス番号 0（ゼロ）を伴う、指定された Record のシーケンス番号に対する
チェックポイントの作成と意味的に同等です。Record 呼び出しが実際には UserRecord である場
合、UserRecord のシーケンス番号とサブシーケンス番号にチェックポイントが作成されます。
新しい KCL チェックポイントオペレーション checkpoint(String sequenceNumber, long
subSequenceNumber) を呼び出すと、指定されたシーケンス番号とサブシーケンス番号に明示的に
チェックポイントが作成されます。
これらのどの場合も、チェックポイントが Amazon DynamoDB チェックポイントテーブルに保存され
た後は、アプリケーションがクラッシュして再起動した場合、KCL により、レコードの取得が正常に
再開されます。さらにレコードがシーケンス内に含まれている場合は、最後にチェックポイントが作
成されたシーケンス番号が付けられているレコード内の次のサブシーケンス番号のレコードから取得
が開始されます。前のシーケンス番号のレコードにある最後のサブシーケンス番号が、最新のチェッ
クポイントに含まれている場合、その次のシーケンス番号が付けられているレコードから取得が開始
されます。
次のセクションでは、レコードのスキップや重複を避けるために必要な、コンシューマーのシーケン
スとサブシーケンスのチェックポイントの詳細について説明します。コンシューマーのレコード処理
を停止し再起動するときに、レコードのスキップや重複が重要でない場合は、変更せずに既存のコー
ドを実行してかまいません。
KPL の集約解除のための KCL の拡張
すでに説明したように、KPL の集約解除ではサブシーケンスチェックポイントを使用できます。サブ
シーケンスチェックポイントを使いやすくするために、UserRecord クラスが KCL に追加されていま
す。
public class UserRecord extends Record {
public long getSubSequenceNumber() {
/* ... */
}
@Override
public int hashCode() {
/* contract-satisfying implementation */
}
@Override
public boolean equals(Object obj) {
/* contract-satisfying implementation */
}
}
このクラスは、現在 Record の代わりに使用されています。これは Record のサブクラスであるた
め、既存のコードは影響を受けません。UserRecord クラスは、実際のサブレコードと通常の集約さ
れていないレコードの両方を表します。集約されていないレコードは、サブレコードを 1 つだけ含む
集約されたレコードと考えることができます。
さらに、2 つの新しいオペレーションが IRecordProcessorCheckpointer に追加されています。
public void checkpoint(Record record);
public void checkpoint(String sequenceNumber, long subSequenceNumber);
サブシーケンス番号チェックポイントの使用を開始するには、次の変更を行います。次のフォーム
コードを変更します。
checkpointer.checkpoint(record.getSequenceNumber());
48
Amazon Kinesis Streams 開発者ガイド
API の使用
新しいフォームコードは次のようになります。
checkpointer.checkpoint(record);
サブシーケンスチェックポイントでは、checkpoint(Record record) フォームを使用することを
お勧めします。ただし、チェックポイントの作成で使用する文字列にすでに sequenceNumbers を保
存している場合は、次の例に示すように、subSequenceNumber も保存する必要があります。
String sequenceNumber = record.getSequenceNumber();
long subSequenceNumber = ((UserRecord) record).getSubSequenceNumber();
// ... do other processing
checkpointer.checkpoint(sequenceNumber, subSequenceNumber);
この実装では内部で UserRecord を必ず使用するため、Record から UserRecord へのキャストは必
ず成功します。シーケンス番号の計算を実行する必要がない場合、この方法はお勧めしません。
KPL ユーザーレコードの処理中に、KCL は、サブシーケンス番号を Amazon DynamoDB に各行の追
加フィールドとして書き込みます。以前のバージョンの KCL では、チェックポイントを再開するとき
に AFTER_SEQUENCE_NUMBER を使用してレコードを取得していました。KPL サポートを含む現在の
KCL では、代わりに AT_SEQUENCE_NUMBER を使用します。チェックポイントが作成されたシーケン
ス番号のレコードを取得するとき、チェックポイントが作成されたサブシーケンス番号がチェックさ
れ、サブレコードが必要に応じて削除されます（最後のサブレコードにチェックポイントが作成され
ている場合、すべてのサブレコードが削除されます）。ここでも、集約されていないレコードは、単
一のサブレコードを含む集約されたレコードと考えることができ、集約されたレコードと集約されて
いないレコードの両方で同じアルゴリズムを使用できます。
GetRecords の直接的な使用
KCL の使用を選択せずに、API オペレーション GetRecords を直接呼び出して Streams レコード
を取得することもできます。これらの取得したレコードを元の KPL ユーザーレコードに解凍するに
は、UserRecord.java にある次の静的なオペレーションの 1 つを呼び出します。
public static List<Record> deaggregate(List<Record> records)
public static List<UserRecord> deaggregate(List<UserRecord> records,
BigInteger startingHashKey, BigInteger endingHashKey)
最初のオペレーションでは、startingHashKey についてデフォルト値 0（ゼロ）を使用
し、endingHashKey についてデフォルト値 2^128 -1 を使用します。
これらの各オペレーションは、Streams レコードの指定されたリストを KPL ユーザーレコードのリ
ストに集約解除します。明示的なハッシュキーまたはパーティションキーが startingHashKey と
endingHashKey の範囲（境界を含む）の外にある KPL ユーザーレコードは、返されるレコードのリ
ストから破棄されます。
Amazon Kinesis Streams API と AWS SDK for Java
を使用した Amazon Kinesis Streams プロデュー
サーの開発
Amazon Kinesis Streams API と AWS SDK for Java を使用してプロデューサーを開発できま
す。Streams を初めて利用する場合は、Amazon Kinesis Streams とは? (p. 1) と Amazon Kinesis
Streams の使用開始 (p. 9) に説明されている概念と用語について理解することから始めてください。
49
Amazon Kinesis Streams 開発者ガイド
API の使用
次の例では、Streams API について説明し、AWS SDK for Java を使用してストリームにデータを追加
（入力）します。ただし、ほとんどのユースケースでは、Streams KPL ライブラリを使用します。詳
細については、「Amazon Kinesis プロデューサライブラリ を使用した Amazon Kinesis Streams プロ
デューサーの開発 (p. 39)」を参照してください。
この章で紹介する Java サンプルコードは、基本的な Streams API オペレーションを実行する方法を
示しており、オペレーションタイプ別に論理的に分割されています。これらのサンプルは、すべての
例外を確認しているわけではなく、すべてのセキュリティやパフォーマンスの側面を考慮しているわ
けでもない点で、本稼働環境に使用できるコードを表すものではありません。また、他のプログラミ
ング言語を使用して Streams API を呼び出すこともできます。利用可能なすべての AWS SDK の詳細
については、「アマゾン ウェブ サービスを使用した開発の開始」を参照してください。
各タスクには前提条件があります。たとえば、ストリームを作成するまではストリームにデータを
追加できず、ストリームを作成するにはクライアントを作成する必要があります。詳細については、
「Amazon Kinesis Stream の管理 (p. 96)」を参照してください。
ストリームへのデータの追加
ストリームを作成したら、レコードの形式でストリームにデータを追加できます。レコードは
データ BLOB の形式で処理するデータを格納するデータ構造です。データをレコードに格納した
後、Streams ではいずれの方法でもデータが検査、解釈、または変更されることはありません。各レ
コードにはシーケンス番号とパーティションキーも関連付けられます。
Streams API には、ストリームにデータを追加するオペレーションとして、PutRecords と
PutRecord の 2 つの異なるオペレーションがあります。PutRecords オペレーションは HTTP リク
エストごとストリームに複数のレコードを送信し、単数形の PutRecord オペレーションは一度に 1
つずつストリームにレコードを送信します（各レコードについて個別の HTTP リクエストが必要で
す）。データプロデューサーあたりのスループットが向上するため、ほとんどのアプリケーションで
は PutRecords を使用してください。これらの各オペレーションの詳細については、後のそれぞれの
サブセクションを参照してください。
トピック
• PutRecords を使用した複数のレコードの追加 (p. 50)
• PutRecord を使用した単一レコードの追加 (p. 53)
ソースアプリケーションは Streams API を使用してストリームにデータを追加するため、1 つ以上の
コンシューマーアプリケーションが同時にストリームからデータを取得して処理する可能性があるこ
とを常に念頭に置いてください。コンシューマーが Streams API を使用してデータを取得する方法の
詳細については、「ストリームからのデータの取得 (p. 82)」を参照してください。
Important
データレコードはストリームに追加されてからデフォルトでは 24 時間アクセス可能です。こ
の期間は、保持期間と呼ばれ、24 時間から 168 時間 (1～7 日) まで 1 時間単位で設定できま
す。ストリームの保持期間の詳細については、「データ保持期間の変更 (p. 105)」を参照し
てください。
PutRecords を使用した複数のレコードの追加
PutRecords オペレーションは、1 つのリクエストで Streams に複数のレコードを送信しま
す。PutRecords を使用することによって、プロデューサーは Amazon Kinesis stream にデータを
送信するときに高スループットを実現できます。各 PutRecords リクエストで、最大 500 レコー
ドをサポートできます。リクエストに含まれる各レコードは 1 MB のサイズ、リクエスト全体の上
限はパーティションキーを含めて最大 5 MB。 後で説明する単一の PutRecord オペレーションと
同様に、PutRecords はシーケンス番号とパーティションキーを使用します。ただし、PutRecord
の SequenceNumberForOrdering パラメータは、PutRecords の呼び出しには含まれませ
50
Amazon Kinesis Streams 開発者ガイド
API の使用
ん。PutRecords オペレーションでは、リクエストの自然な順序ですべてのレコードを処理するよう
試みます。
各データレコードには一意のシーケンス番号があります。シーケンス番号は、client.putRecords
を呼び出してストリームにデータレコードを追加した後に、Streams によって割り当てられま
す。同じパーティションキーのシーケンス番号は一般的に、時間の経過とともに大きくなりま
す。PutRecords リクエスト間の期間が長くなるほど、シーケンス番号は大きくなります。
Note
シーケンス番号は、同じストリーム内の一連のデータのインデックスとして使用すること
はできません。一連のデータを論理的に区別するには、パーティションキーを使用するか、
データセットごとに個別のストリームを作成します。
PutRecords リクエストには、異なるパーティションキーのレコードを含めることができます。リ
クエストのスコープはストリームです。各リクエストには、リクエストの制限まで、パーティショ
ンキーとレコードのあらゆる組み合わせを含めることができます。複数の異なるパーティションキー
を使用して、複数の異なるシャードを含むストリームに対して実行されたリクエストは、少数のパー
ティションキーを使用して少数のシャードに対して実行されたリクエストよりも一般的に高速です。
レイテンシーを低減し、スループットを最大化するには、パーティションキーの数をシャードの数よ
りも大きくする必要があります。
PutRecords の例
次のコードでは、シーケンシャルなパーティションキーを持つ 100 件のデータレコードを作成
し、DataStream という名前のストリームに格納しています。
AmazonKinesisClient amazonKinesisClient = new
AmazonKinesisClient(credentialsProvider);
PutRecordsRequest putRecordsRequest = new PutRecordsRequest();
putRecordsRequest.setStreamName("DataStream");
List <PutRecordsRequestEntry> putRecordsRequestEntryList = new
ArrayList<>();
for (int i = 0; i < 100; i++) {
PutRecordsRequestEntry putRecordsRequestEntry = new
PutRecordsRequestEntry();
putRecordsRequestEntry.setData(ByteBuffer.wrap(String.valueOf(i).getBytes()));
putRecordsRequestEntry.setPartitionKey(String.format("partitionKey-%d",
i));
putRecordsRequestEntryList.add(putRecordsRequestEntry);
}
putRecordsRequest.setRecords(putRecordsRequestEntryList);
PutRecordsResult putRecordsResult =
amazonKinesisClient.putRecords(putRecordsRequest);
System.out.println("Put Result" + putRecordsResult);
PutRecords のレスポンスには、レスポンスの Records の配列が含まれます。レスポンス配列の各
レコードは、リクエスト配列内のレコードと自然な順序（リクエストやレスポンスの上から下へ）で
直接相互に関連付けられます。レスポンスの Records 配列には、常にリクエスト配列と同じ数のレ
コードが含まれます。
PutRecords 使用時のエラーの処理
デフォルトでは、リクエスト内の個々のレコードでエラーが発生しても、PutRecords リクエスト内
のそれ以降のレコードの処理は停止されません。つまり、レスポンスの Records 配列には、正常に
51
Amazon Kinesis Streams 開発者ガイド
API の使用
処理されたレコードと、正常に処理されなかったレコードの両方が含まれていることを意味します。
正常に処理されなかったレコードを検出し、それ以降の呼び出しに含める必要があります。
正常に処理されたレコードには SequenceNumber 値と ShardID 値が、正常に処理されなかったレ
コードには ErrorCode 値と ErrorMessage 値が含まれます。ErrorCode パラメータはエラーのタ
イプを反映しており、ProvisionedThroughputExceededException または InternalFailure
のいずれかになります。ErrorMessage は、ProvisionedThroughputExceededException 例外
について、スロットリングされたレコードのアカウント ID、ストリーム名、シャード ID などの詳細
情報を提供します。次の例では、PutRecords リクエストに 3 つのレコードがあります。2 番目のレ
コードは失敗し、レスポンスに反映されます。
Example PutRecords リクエストの構文
{
"Records": [
{
"Data": "XzxkYXRhPl8w",
"PartitionKey": "partitionKey1"
},
{
"Data": "AbceddeRFfg12asd",
"PartitionKey": "partitionKey1"
},
{
"Data": "KFpcd98*7nd1",
"PartitionKey": "partitionKey3"
},
"StreamName": "myStream"
}
Example PutRecords レスポンスの構文
{
"FailedRecordCount”: 1,
"Records": [
{
"SequenceNumber": "21269319989900637946712965403778482371",
"ShardId": "shardId-000000000001"
},
{
“ErrorCode":”ProvisionedThroughputExceededException”,
“ErrorMessage": "Rate exceeded for shard shardId-000000000001 in stream
exampleStreamName under account 111111111111."
},
{
"SequenceNumber": "21269319989999637946712965403778482985",
"ShardId": "shardId-000000000002"
}
]
}
正常に処理されなかったレコードは、以降の PutRecords リクエストに含めることができます。最
初に、putRecordsResult の FailedRecordCount パラメータを調べて、リクエスト内にエラー
となったレコードがあるかどうかを確認します。このようなレコードがある場合は、ErrorCode が
null 以外である各 putRecordsEntry を、以降のリクエストに追加してください。このタイプのハ
ンドラーの例については、次のコードを参照してください。
52
Amazon Kinesis Streams 開発者ガイド
API の使用
Example PutRecords エラーハンドラー
PutRecordsRequest putRecordsRequest = new PutRecordsRequest();
putRecordsRequest.setStreamName(myStreamName);
List<PutRecordsRequestEntry> putRecordsRequestEntryList = new ArrayList<>();
for (int j = 0; j < 100; j++) {
PutRecordsRequestEntry putRecordsRequestEntry = new
PutRecordsRequestEntry();
putRecordsRequestEntry.setData(ByteBuffer.wrap(String.valueOf(j).getBytes()));
putRecordsRequestEntry.setPartitionKey(String.format("partitionKey-%d",
j));
putRecordsRequestEntryList.add(putRecordsRequestEntry);
}
putRecordsRequest.setRecords(putRecordsRequestEntryList);
PutRecordsResult putRecordsResult =
amazonKinesisClient.putRecords(putRecordsRequest);
while (putRecordsResult.getFailedRecordCount() > 0) {
final List<PutRecordsRequestEntry> failedRecordsList = new ArrayList<>();
final List<PutRecordsResultEntry> putRecordsResultEntryList =
putRecordsResult.getRecords();
for (int i = 0; i < putRecordsResultEntryList.size(); i++) {
final PutRecordsRequestEntry putRecordRequestEntry =
putRecordsRequestEntryList.get(i);
final PutRecordsResultEntry putRecordsResultEntry =
putRecordsResultEntryList.get(i);
if (putRecordsResultEntry.getErrorCode() != null) {
failedRecordsList.add(putRecordRequestEntry);
}
}
putRecordsRequestEntryList = failedRecordsList;
putRecordsRequest.setRecords(putRecordsRequestEntryList);
putRecordsResult = amazonKinesisClient.putRecords(putRecordsRequest);
}
PutRecord を使用した単一レコードの追加
PutRecord の各呼び出しは、1 つのレコードに対して動作します。アプリケーションで常にリクエ
ストごとに 1 つのレコードを送信する必要がある場合や、PutRecords を使用できないその他の理
由がある場合を除いて、「PutRecords を使用した複数のレコードの追加 (p. 50)」で説明している
PutRecords オペレーションを使用します。
各データレコードには一意のシーケンス番号があります。シーケンス番号は、client.putRecord
を呼び出してストリームにデータレコードが追加された後に、Streams によって割り当てられま
す。同じパーティションキーのシーケンス番号は一般的に、時間の経過とともに大きくなりま
す。PutRecord リクエスト間の期間が長くなるほど、シーケンス番号は大きくなります。
入力が立て続けに行われた場合、返されるシーケンス番号は大きくなるとは限りません。入力オペ
レーションが基本的に Streams に対して同時に実行されるためです。同じパーティションキーに対し
て厳密にシーケンス番号が大きくなるようにするには、「PutRecord の例 (p. 54)」のサンプルコー
ドに示しているように、SequenceNumberForOrdering パラメータを使用します。
SequenceNumberForOrdering を使用するかどうかにかかわらず、Streams が GetRecords の呼び
出しを通じて受け取るレコードは厳密にシーケンス番号順になります。
53
Amazon Kinesis Streams 開発者ガイド
エージェントの使用
Note
シーケンス番号は、同じストリーム内の一連のデータのインデックスとして使用すること
はできません。一連のデータを論理的に区別するには、パーティションキーを使用するか、
データセットごとに個別のストリームを作成します。
パーティションキーはストリーム内のデータをグループ化するために使用されます。データレコー
ドはそのパーティションキーに基づいてストリーム内でシャードに割り当てられます。具体的に
は、Streams ではパーティションキー（および関連するデータ）を特定のシャードにマッピングする
ハッシュ関数への入力として、パーティションキーを使用します。
このハッシュメカニズムの結果として、パーティションキーが同じすべてのデータレコードは、ス
トリーム内で同じシャードにマッピングされます。ただし、パーティションキーの数がシャードの
数を超えている場合、一部のシャードにパーティションキーが異なるレコードが格納されることが
あります。設計の観点から、すべてのシャードが適切に使用されるようにするには、シャードの数
（CreateStreamRequest の setShardCount メソッドで指定）を一意のパーティションキーの数よ
りも大幅に少なくする必要があります。また、1 つのパーティションキーへのデータの流量をシャー
ドの容量より大幅に小さくする必要があります。
PutRecord の例
以下のコードでは、2 つのパーティションキーに配分される 10 件のデータレコードを作成
し、myStreamName という名前のストリームに格納しています。
for (int j = 0; j < 10; j++)
{
PutRecordRequest putRecordRequest = new PutRecordRequest();
putRecordRequest.setStreamName( myStreamName );
putRecordRequest.setData(ByteBuffer.wrap( String.format( "testData-%d",
j ).getBytes() ));
putRecordRequest.setPartitionKey( String.format( "partitionKey-%d", j/5 ));
putRecordRequest.setSequenceNumberForOrdering( sequenceNumberOfPreviousRecord );
PutRecordResult putRecordResult = client.putRecord( putRecordRequest );
sequenceNumberOfPreviousRecord = putRecordResult.getSequenceNumber();
}
上記のコード例では、setSequenceNumberForOrdering を使用して、各パーティションキー内で
順番が厳密に増えるようにしています。このパラメーターを効果的に使用するには、現在のレコード
（レコード n）の SequenceNumberForOrdering を前のレコード（レコード n-1）のシーケンス番
号に設定します。ストリームに追加されたレコードのシーケンス番号を取得するには、putRecord の
結果に対して getSequenceNumber を呼び出します。
SequenceNumberForOrdering パラメーターを使用すると、同じクライアントが PutRecord を呼
び出したときに、パーティションキーが同じであっても、シーケンス番号は厳密に大きくなるよう
になります。SequenceNumberForOrdering を使用しても、複数の同時実行のアプリケーションか
ら追加されたレコード間、または複数のパーティションキー間では、順序が正しくなるとは限りませ
ん。
Amazon Kinesis エージェントを使用して Amazon
Kinesis Streams への書き込み
Amazon Kinesis エージェントはスタンドアロンの Java ソフトウェアアプリケーションで、データを
収集して Streams に送信する簡単な方法を提供します。このエージェントは一連のファイルを継続
54
Amazon Kinesis Streams 開発者ガイド
エージェントの使用
的に監視し、新しいデータをストリームに送信します。エージェントはファイルのローテーション、
チェックポイント、失敗時の再試行を処理します。タイムリーで信頼性の高い簡単な方法で、すべて
のデータを提供します。また、ストリーミング処理のモニタリングとトラブルシューティングに役立
つ Amazon CloudWatch メトリックスも出力します。
デフォルトでは、レコードは改行文字 ('\n') に基づいて各ファイルから解析されます。しかし、
複数行レコードを解析するよう、エージェントを設定することもできます (「エージェントの設
定 (p. 57)」を参照)。
このエージェントは、ウェブサーバー、ログサーバーおよびデータベースサーバーなど、Linux ベー
スのサーバー環境にインストールできます。エージェントをインストールした後で、モニタリング用
のファイルとデータストリームを指定して設定します。エージェントが設定されると、ファイルから
永続的にデータを収集して、ストリームに安全にデータを送信します。
トピック
• 前提条件 (p. 55)
• エージェントのダウンロードとインストール (p. 55)
• エージェントの設定と開始 (p. 56)
• エージェントの設定 (p. 57)
• 複数のファイルディレクトリを監視し、複数のストリームに書き込み (p. 59)
• エージェントを使用してデータを事前処理する (p. 59)
• エージェント CLI コマンド (p. 62)
前提条件
• オペレーティングシステムは Amazon Linux AMI バージョン 2015.09 以降、または Red Hat
Enterprise Linux バージョン 7 以降でなければなりません。
• Amazon EC2 を使用してエージェントを実行している場合は、EC2 インスタンスを起動します。
• 次のいずれかの方法を使用して、AWS 認証情報を管理します。
• EC2 インスタンスを起動する際に IAM ロールを指定します。
• エージェントを設定する際に AWS 認証情報を指定します (awsAccessKeyId (p.
awsSecretAccessKey (p.
) を参照してください)。
) および
• /etc/sysconfig/aws-kinesis-agent を編集して、リージョンと AWS アクセスキーを指定
します。
• 指定した IAM ロールまたは AWS 認証情報は、エージェントがストリームにデータを送信するた
めに、Streams PutRecords 操作を実行する権限が必要です。エージェントの CloudWatch モニタ
リングを有効にしている場合は、CloudWatch &link-cw-api-putmetricdata; 操作を実行する権限も必
要になります。詳細については、「IAM により Amazon Kinesis Streams リソースへのアクセスを
制御する (p. 133)」、「Amazon CloudWatch で Streams エージェントの状態をモニタリングす
る (p. 114)」および「CloudWatch のアクセスコントロール」を参照してください。
エージェントのダウンロードとインストール
最初に、インスタンスに接続します。詳細については、『Linux インスタンス用 Amazon EC2 ユー
ザーガイド』の「インスタンスへの接続」を参照してください。接続できない場合は、『Linux イン
スタンス用 Amazon EC2 ユーザーガイド』の「インスタンスへの接続に関するトラブルシューティン
グ」を参照してください。
Amazon Linux AMI を使用してエージェントを設定するには
次のコマンドを使用して、エージェントをダウンロードしてインストールします。
55
Amazon Kinesis Streams 開発者ガイド
エージェントの使用
sudo yum install –y aws-kinesis-agent
Red Hat Enterprise Linux を使用してエージェントを設定する
次のコマンドを使用して、エージェントをダウンロードしてインストールします。
sudo yum install –y https://s3.amazonaws.com/streaming-data-agent/awskinesis-agent-latest.amzn1.noarch.rpm
GitHubを使用してエージェントを設定する
1.
「awlabs/amazon-kinesis-agent」からエージェントをダウンロードしてください。
2.
ダウンロードしたディレクトリまで移動し、次のコマンドを実行してエージェントをインストー
ルします。
sudo ./setup --install
エージェントの設定と開始
エージェントを設定して開始するには
1.
（デフォルトのファイルアクセス権限を使用している場合、スーパーユーザーとして）設定ファ
イル (/etc/aws-kinesis/agent.json) を開き、編集します。
この設定ファイルで、エージェントがデータを集めるファイル ("filePattern") とエージェン
トがデータを送信するストリーム ("kinesisStream") を指定します。ファイル名はパターン
で、エージェントはファイルローテーションを確認する点に注意してください。1 秒あたりに一
度だけ、ファイルを交替または新しいファイルを作成できます。エージェントはファイル作成タ
イムスタンプを使用して、どのファイルを追跡してストリームに送信するかを判断します。新規
ファイルの作成やファイルの交換を 1 秒あたりに一度以上頻繁に交換すると、エージェントはそ
れらを適切に区別できません。
{
"flows": [
{
"filePattern": "/tmp/app.log*",
"kinesisStream": "yourkinesisstream"
}
]
}
2.
エージェントを手動で開始する:
sudo service aws-kinesis-agent start
3.
(オプション) システムスタートアップ時にエージェントを開始するように設定します。
sudo chkconfig aws-kinesis-agent on
エージェントは、システムのサービスとしてバックグラウンドで実行されます。継続的に指定ファイ
ルをモニタリングし、指定されたストリームにデータを送信します。エージェント活動は /var/log/
aws-kinesis-agent/aws-kinesis-agent.log に記録されます。
56
Amazon Kinesis Streams 開発者ガイド
エージェントの使用
エージェントの設定
エージェントは、2つの必須設定、filePattern と kinesisStream、さらに追加機能として任意の
設定をサポートしています。必須およびオプションの設定を /etc/aws-kinesis/agent.json で指
定できます。
設定ファイルを変更した場合は、次のコマンドを使用してエージェントを停止および起動する必要が
あります。
sudo service aws-kinesis-agent stop
sudo service aws-kinesis-agent start
または、次のコマンドを使用できます。
sudo service aws-kinesis-agent restart
全般設定は次のとおりです。
構成設定
説明
awsAccessKeyId
デフォルトの認証情報を上書きする AWS アクセスキー IDです。この設定
は、他のすべての認証情報プロバイダーに優先されます。
awsSecretAccessKey デフォルトの認証情報を上書きする AWS シークレットキーです。この設
定は、他のすべての認証情報プロバイダーに優先されます。
cloudwatch.emitMetrics
エージェントがメトリックスを CloudWatch に発行できるようにします
(true に設定された場合)。
デフォルト: true
cloudwatch.endpoint CloudWatch のリーションのエンドポイントです。
デフォルト: monitoring.us-east-1.amazonaws.com
kinesis.endpoint
Streams のリーションのエンドポイントです。
デフォルト: kinesis.us-east-1.amazonaws.com
フロー設定は次のとおりです。
構成設定
説明
dataProcessingOptions
ストリームに送信される前に解析された各レコードに適用されるの処理オ
プションの一覧。処理オプションは指定した順序で実行されます。詳細に
ついては、「エージェントを使用してデータを事前処理する (p. 59)」
を参照してください。
kinesisStream
[必須] ストリームの名前。
filePattern
[必須] エージェントによってモニタリングされる必要があるファイルの
globこのパターンに一致するすべてのファイルは、エージェントによって
自動的に選択され、モニタリングされます。このパターンに一致するすべ
てのファイルは、読み取り権限を aws-kinesis-agent-user に付与す
る必要があります。ファイルを含むディレクトリには、読み取りと実行権
限を aws-kinesis-agent-user に付与する必要があります。
57
Amazon Kinesis Streams 開発者ガイド
エージェントの使用
構成設定
説明
initialPosition
ファイルの解析が開始される最初の位置。有効な値は、START_OF_FILE
および END_OF_FILE です。
デフォルト: END_OF_FILE
maxBufferAgeMillis エージェントがストリームに送信する前にデータをバッファーする最大時
間 (ミリ秒)。
値の範囲: 1,000 ～ 900,000（1 秒～ 15 分）
デフォルト: 60,000（1 分）
maxBufferSizeBytes エージェントがストリームに送信する前にデータをバッファーする最大サ
イズ (バイト)。
値の範囲: 1 ～ 4,194,304（4 MB）
デフォルト: 4,194,304（4 MB）
maxBufferSizeRecordsエージェントがストリームに送信する前にデータをバッファーするレコー
ドの最大数。
値の範囲: 1 ～ 500
デフォルト: 500
minTimeBetweenFilePollsMillis
エージェントが新しいデータのモニタリング対象ファイルをポーリング
し、解析する時間間隔 (ミリ秒単位)。
値の範囲: 1 以上
デフォルト: 100
multiLineStartPattern
レコードの開始を識別するパターン。レコードは、パターンに一致する 1
行と、それに続くパターンに一致しない行で構成されます。有効な値は正
規表現です。デフォルトでは、ログファイルのそれぞれの改行は 1 つのレ
コードとして解析されます。
partitionKeyOption パーティションのキーを生成する方法。有効な値は RANDOM (ランダムに
生成される整数) と DETERMINISTIC (データから計算されるハッシュ値)
です。
デフォルト: RANDOM
skipHeaderLines
モニタリング対象ファイルの始めにエージェントが解析をスキップするの
行数。
値の範囲: 0 以上
デフォルト: 0 (ゼロ)
truncatedRecordTerminator
レコードのサイズが Streams レコードの許容サイズを超えたときに解析
されたレコードを切り捨てるために、エージェントが使用する文字列。
(1,000 KB)
デフォルト: '\n'（改行）
58
Amazon Kinesis Streams 開発者ガイド
エージェントの使用
複数のファイルディレクトリを監視し、複数のストリームに書
き込み
複数のフロー設定を指定することによって、エージェントが複数のファイルディレクトリを監視し、
複数のストリームにデータを送信するように設定できます。以下の構成例では、エージェントは 2 つ
のファイルディレクトリ監視し、それぞれ Amazon Kinesis ストリームおよび Firehose 配信ストリー
ムにデータを送信します。Amazon Kinesis ストリームと Firehose 配信ストリームが 同じリージョン
にある必要がないように Streams と Firehose に異なるエンドポイントを指定できます。
{
"cloudwatch.emitMetrics": true,
"kinesis.endpoint": "https://your/kinesis/endpoint",
"firehose.endpoint": "https://your/firehose/endpoint",
"flows": [
{
"filePattern": "/tmp/app1.log*",
"kinesisStream": "yourkinesisstream"
},
{
"filePattern": "/tmp/app2.log*",
"deliveryStream": "yourfirehosedeliverystream"
}
]
}
Firehose でエージェントを使用に関する詳細については、「Amazon Kinesis エージェントによる
Amazon Kinesis Firehose への書き込み」を参照してください。
エージェントを使用してデータを事前処理する
エージェントはストリームにレコードを送信する前に、モニタリング対象ファイルから解析したレ
コードを事前処理できます。ファイルフローに dataProcessingOptions 設定を追加することで、
この機能を有効にできます。1 つ以上の処理オプションを追加でき、また指定されている順序で実行
されます。
エージェントは、リストされた次の処理オプションに対応しています。エージェントはオープンソー
スであるため、処理オプションを開発および拡張できます。Amazon Kinesis エージェント からエー
ジェントをダウンロードできます。
処理オプション
SINGLELINE
改行文字、先頭のスペース、末尾のスペースを削除することで、複数行レコードを単一行レコー
ドに変換します。
{
"optionName": "SINGLELINE"
}
CSVTOJSON
区切り形式から JSON 形式にレコードを変換します。
{
"optionName": "CSVTOJSON",
"customFieldNames": [ "field1", "field2", ... ],
59
Amazon Kinesis Streams 開発者ガイド
エージェントの使用
"delimiter": "yourdelimiter"
}
customFieldNames
[必須] 各 JSON キー値のペアでキーとして使用されるフィールド名。たとえば、["f1",
"f2"] を指定した場合は、レコード「v1、v2」は {"f1":"v1","f2":"v2"} に変換されま
す。
delimiter
レコードで区切り記号として使用する文字列。デフォルトはカンマ (,) です。
LOGTOJSON
ログ形式から JSON 形式にレコードを変換します。サポートされているログ形式は、Apache
Common Log、 Apache Combined Log、Apache Error Log、 および RFC3164 Syslog です。
{
"optionName": "LOGTOJSON",
"logFormat": "logformat",
"matchPattern": "yourregexpattern",
"customFieldNames": [ "field1", "field2", … ]
}
logFormat
[必須] ログエントリ形式。以下の値を指定できます。
• COMMONAPACHELOG — Apache Common Log 形式各ログエントリは、デフォルトで次の
パターン「%{host} %{ident} %{authuser} [%{datetime}] \"%{request}\"
%{response} %{bytes}」になります。
• COMBINEDAPACHELOG — The Apache Combined Log 形式。各ログエントリは、デ
フォルトで次のパターン「%{host} %{ident} %{authuser} [%{datetime}]
\"%{request}\" %{response} %{bytes} %{referrer} %{agent}」になります。
• APACHEERRORLOG — Apache Error Log 形式。各ログエントリは、デフォルトで次のパ
ターン「[%{timestamp}] [%{module}:%{severity}] [pid %{processid}:tid
%{threadid}] [client: %{client}] %{message}」になります。
• SYSLOG — RFC3164 Syslog 形式。各ログエントリは、デフォルトで次のパターン
「%{timestamp} %{hostname} %{program}[%{processid}]: %{message}」にな
ります。
matchPattern
ログエントリから値を取得するために使用する正規表現パターン。この設定は、ログエント
リが定義されたログ形式の一つとして存在していない場合に使用されます。この設定を使用
する場合は、customFieldNames を指定する必要があります。
customFieldNames
JSON キー値のペアでキーとして使用されるカスタムフィールド名。matchPattern から抽
出した値のフィールド名を定義するために、または事前定義されたログ形式のデフォルトの
フィールド名を上書きするために、この設定を使用できます。
Example : LOGTOJSON 設定
JSON形式に変換された Apache Common Log エントリの LOGTOJSON 設定の一つの例を次に示しま
す。
{
"optionName": "LOGTOJSON",
"logFormat": "COMMONAPACHELOG"
}
変換前:
60
Amazon Kinesis Streams 開発者ガイド
エージェントの使用
64.242. 88.10 - - [07/Mar/2004:16:10:02 -0800] "GET /mailman/listinfo/
hsdivision HTTP/1.1" 200 6291
変換後:
{"host":"64.242.88.10","ident":null,"authuser":null,"datetime":"07/
Mar/2004:16:10:02 -0800","request":"GET /mailman/listinfo/hsdivision
HTTP/1.1","response":"200","bytes":"6291"}
Example : カスタムフィールドがある LOGTOJSON 設定
こちらは LOGTOJSON 設定の別の例です。
{
"optionName": "LOGTOJSON",
"logFormat": "COMMONAPACHELOG",
"customFieldNames": ["f1", "f2", "f3", "f4", "f5", "f6", "f7"]
}
この設定では、前の例からの同じ Apache Common Log エントリは、次のように JSON 形式に変換さ
れます。
{"f1":"64.242.88.10","f2":null,"f3":null,"f4":"07/
Mar/2004:16:10:02 -0800","f5":"GET /mailman/listinfo/hsdivision
HTTP/1.1","f6":"200","f7":"6291"}
Example : Apache Common Log エントリの変換
次のフロー設定は Apache Common Log エントリを JSON 形式の単一行レコードに変換します。
{
"flows": [
{
"filePattern": "/tmp/app.log*",
"kinesisStream": "my-stream",
"dataProcessingOptions": [
{
"optionName": "LOGTOJSON",
"logFormat": "COMMONAPACHELOG"
}
]
}
]
}
Example : 複数行レコードの変換
次のフロー設定は、最初の行が「[SEQUENCE=」で開始している複数行レコードを解析します。各レ
コードはまず単一行レコードに変換されます。次に、値はタブの区切り記号に基づいたレコードから
取得されます。取得された値は指定された customFieldNames 値にマッピングされ、JSON 形式の
単一行レコードを形成します。
{
"flows": [
61
Amazon Kinesis Streams 開発者ガイド
エージェントの使用
{
"filePattern": "/tmp/app.log*",
"kinesisStream": "my-stream",
"multiLineStartPattern": "\\[SEQUENCE=",
"dataProcessingOptions": [
{
"optionName": "SINGLELINE"
},
{
"optionName": "CSVTOJSON",
"customFieldNames": [ "field1", "field2", "field3" ],
"delimiter": "\\t"
}
]
}
]
}
Example : 一致パターンで LOGTOJSON 設定
こちらは、最後のフィールド (バイト) が省略された JSON 形式に変換された Apache Common Log
エントリの LOGTOJSON 設定の一例です。
{
"optionName": "LOGTOJSON",
"logFormat": "COMMONAPACHELOG",
"matchPattern": "^([\\d.]+) (\\S+) (\\S+) \\[([\\w:/]+\\s[+\\-]\\d{4})\\]
\"(.+?)\" (\\d{3})",
"customFieldNames": ["host", "ident", "authuser", "datetime", "request",
"response"]
}
変換前:
123.45.67.89 - - [27/Oct/2000:09:27:09 -0400] "GET /java/javaResources.html
HTTP/1.0" 200
変換後:
{"host":"123.45.67.89","ident":null,"authuser":null,"datetime":"27/
Oct/2000:09:27:09 -0400","request":"GET /java/javaResources.html
HTTP/1.0","response":"200"}
エージェント CLI コマンド
システムスタートアップ時のエージェントの自動的開始:
sudo chkconfig aws-kinesis-agent on
エージェントのステータスの確認:
sudo service aws-kinesis-agent status
エージェントの停止:
62
Amazon Kinesis Streams 開発者ガイド
トラブルシューティング
sudo service aws-kinesis-agent stop
この場所からエージェントのログファイルを読む:
/var/log/aws-kinesis-agent/aws-kinesis-agent.log
エージェントのアンインストール:
sudo yum remove aws-kinesis-agent
Amazon Kinesis Streams プロデューサーのトラブ
ルシューティング
以下のセクションでは、Amazon Kinesis Streams プロデューサーの操作中に発生する可能性がある一
般的な問題に対する解決策を示します。
• プロデューサーアプリケーションの書き込みの速度が予想よりも遅い (p. 63)
プロデューサーアプリケーションの書き込みの速度が予想より
も遅い
書き込みのスループットが予想よりも遅くなる最も一般的な理由は次のとおりです。
• サービスの制限を超過している (p. 63)
• プロデューサーの最適化 (p. 64)
サービスの制限を超過している
サービスの制限を超過しているかどうかを確認するには、プロデューサーがサービスからのスルー
プット例外をスローしており、どの API オペレーションがスロットリングされているかを確認しま
す。呼び出しによって制限が異なることに注意して、Amazon Kinesis Streams の制限 (p. 7) を確認し
てください。たとえば、書き込みと読み取りのシャードレベルの制限は最もよく知られていますが、
以下のようなストリームレベルの制限もあります。
• CreateStream
• DeleteStream
• ListStreams
• GetShardIterator
• MergeShards
• DescribeStream
CreateStream、DeleteStream、ListStreams、 GetShardIterator、MergeShards のオペ
レーションは、1 秒あたり 5 個の呼び出しに制限されます。DescribeStream オペレーションは、1
秒あたり 10 個の呼び出しに制限されます。
このような呼び出しが原因でない場合は、すべてのシャードで put オペレーションを均等にディスト
リビューションすることが可能なパーティションキーを選択しており、残りのサービスが制限に達
しない場合にサービスの制限に達してしまうような特定のパーティションキーがないことを確認しま
す。これには、ピークスループットを測定して、ストリームのシャードの数を考慮する必要がありま
す。ストリーム管理の詳細については、「Amazon Kinesis Stream の管理 (p. 96)」を参照してくだ
さい。
63
Amazon Kinesis Streams 開発者ガイド
高度なトピック
Tip
マルチレコードオペレーション PutRecords を使用するスループットスロットリングの
計算では各セルでレコードの累計を四捨五入しますが、シングルレコードオペレーショ
ン PutRecord では、最も近いキロバイト数に四捨五入するようにしてください。たとえ
ば、PutRecords は 1.1 KB になる 600 レコードのリクエストをスロットリングしません。
プロデューサーの最適化
プロデューサーの最適化を始める前に、完了しておかなければならない重要なタスクがいくつかあ
ります。最初に、レコードのサイズと 1 秒あたりのレコード数で必要となるスループットピークを
特定します。次に、制限要素としてのストリーム容量を除外します（サービスの制限を超過してい
る (p. 63)）。ストリーム容量を除外している場合は、以下のプロデューサーの 2 つの一般的なタ
イプのトラブルシューティングのヒントと最適化のガイドラインを使用します。
ラージプロデューサー
ラージプロデューサーは、通常オンプレミスサーバーまたは Amazon EC2 インスタンスから実行さ
れます。ラージプロデューサーからより高いスループットを必要とするお客様は、通常レコードあた
りのレイテンシーに注意を払います。レイテンシーを処理する戦略には、以下の項目が含まれます。
マイクロバッチ/バッファレコードが可能なお客様は、Amazon Kinesis プロデューサライブラリ（高
度な集約ロジック）またはマルチレコードオペレーション PutRecords を使用するか、またはシング
ルレコードオペレーション PutRecord を使用する前にレコードをより大きいファイルに集約します。
バッチ/バッファを使用できない場合は、複数のスレッドを使用して Streams サービスに同時に書き込
みます。AWS SDK for Java とその他の SDK には、ごく少数のコードでこれを実行できる非同期クラ
イアントが含まれます。
スモールプロデューサー
スモールプロデューサーは、通常モバイルアプリケーション、IoT デバイス、またはウェブクライア
ントです。モバイルアプリケーションの場合は、PutRecords オペレーションまたは AWS モバイル
SDK で Amazon Kinesis レコーダーを使用することをお勧めします。詳細については、「AWS Mobile
SDK for Android 入門ガイド」および「AWS Mobile SDK for iOS Getting Started Guide」を参照してく
ださい。モバイルアプリケーションは、本来断続的な接続を処理する必要があり、PutRecords のよ
うなバッチ put タイプを必要とします。何らかの理由でバッチを使用できない場合は、上記のラージ
プロデューサーの情報を参照してください。プロデューサーがブラウザの場合、生成されるデータの
量は通常非常に小さなものとなります。ただし、アプリケーションの重要なパスに put オペレーショ
ンを配置することはお勧めしません。
Amazon Kinesis Streams プロデューサーについて
の高度なトピック
このセクションでは、Amazon Kinesis Streams プロデューサーを最適化する方法について説明しま
す。
目次
• KPL の再試行とレート制限 (p. 64)
• KPL 集約を使用するときの考慮事項 (p. 65)
KPL の再試行とレート制限
KPL addUserRecord() オペレーションを使用して KPL ユーザーレコードを追加する場合、レコー
ドにタイムスタンプが与えられ、RecordMaxBufferedTime 設定パラメータで期限が設定されたバッ
ファにそのレコードが追加されます。このタイムスタンプと期限の組み合わせにより、バッファの優
先順位が設定されます。レコードは、次の条件に基づいてバッファからフラッシュされます。
64
Amazon Kinesis Streams 開発者ガイド
高度なトピック
• バッファの優先度
• 集約設定
• 収集設定
バッファの動作に影響を与える集約および収集の設定パラメータは次のとおりです。
• AggregationMaxCount
• AggregationMaxSize
• CollectionMaxCount
• CollectionMaxSize
さらに、フラッシュされたレコードは Streams API オペレーション PutRecords への呼び出
しを使用して、Amazon Kinesis Streams レコードとして Amazon Kinesis stream に送信されま
す。PutRecords オペレーションはストリームにリクエストを送信しますが、すべての失敗または部
分的な失敗を示す場合があります。失敗したレコードは、自動的に KPL バッファに戻されます。新し
い期限は、次の 2 つの値のうち小さい方に基づいて設定されます。
• 現在の RecordMaxBufferedTime 設定の半分
• レコードの有効期限値
この戦略では、再試行する KPL ユーザーレコードをそれ以降の Streams API 呼び出しに含めることが
でき、Streams レコードの有効期限値を適用しながら、スループットを改善し、複雑さを減らすこと
ができます。バックオフアルゴリズムがないため、これは比較的積極的な再試行戦略です。過剰な再
試行による大量送信は、次のセクションで説明するレート制限により防止できます。
レート制限
KPL にはレート制限機能があり、1 つのプロデューサーからの送信されるシャード単位のスループッ
トを制限できます。レート制限は、Streams のレコードとバイトに別々のバケットを使用するトーク
ンバケットアルゴリズムを使用して実装されています。Amazon Kinesis stream への書き込みが成功
するたびに、特定のしきい値に達するまで、各バケットに 1 つまたは複数のトークンが追加されま
す。このしきい値は設定できますが、デフォルトでは実際のシャード制限より 50% 大きく設定され、
単一のプロデューサーによるシャードの飽和が許されています。
この制限を小さくすることにより、過剰な再試行による大量送信を抑制できます。ただし、ベストプ
ラクティスは、各プロデューサーについて、最大スループットまで積極的に再試行することと、スト
リームの容量を拡大し、適切なパーティションキー戦略を実装することにより、結果的に過剰と判断
されたスロットリングを適切に処理することです。
KPL 集約を使用するときの考慮事項
結果として得られた Amazon Kinesis Streams レコードのシーケンス番号方式は同じままですが、集
約された Streams レコードに含まれる KPL ユーザーレコードのインデックスは 0（ゼロ）から始ま
ります。ただし、シーケンス番号に依存しない方法で KPL ユーザーレコードを一意に識別するかぎ
り、集約（KPL ユーザーレコードの Streams レコードへの集約）とその後の集約解除（Streams レ
コードの KPL ユーザーレコードへの集約解除）で自動的に考慮されるため、このようにインデックス
が 0（ゼロ）から始まることをコード上は無視してかまいません。これは、コンシューマーが KCL と
AWS SDK のどちらを使用している場合でも適用されます。AWS SDK で提供される API を使用して
コンシューマーが書かれている場合、この集約機能を使用するには、KPL の Java 部分をビルドに組
み込む必要があります。
KPL ユーザーレコードの一意な識別子としてシーケンス番号を使用する場合、Record および
UserRecord に提供されている、契約に順守した public int hashCode() および public
boolean equals(Object obj) オペレーションを使用して、KPL ユーザーレコードの比較を有効
65
Amazon Kinesis Streams 開発者ガイド
ストリームからのデータの読み取り
にすることをお勧めします。さらに、KPL ユーザーレコードのサブシーケンス番号を調べる必要があ
る場合は、そのユーザーレコードを UserRecord インスタンスにキャストして、そのサブシーケンス
番号を取得することができます。
詳細については、「コンシューマーの集約解除 (p. 47)」を参照してください。
Amazon Kinesis Streams からのデータの読み取
り
コンシューマーは、Amazon Kinesis Streams からデータを読み取り、処理するアプリケーショ
ンです。コンシューマーを対象とした Streams を構築できます。Streams を初めて利用する場合
は、Amazon Kinesis Streams とは? (p. 1) と Amazon Kinesis Streams の使用開始 (p. 9) に説明されて
いる概念と用語について理解することから始めてください。
トピック
• Amazon Kinesis Client Library を使用した Amazon Kinesis Streams コンシューマーの開
発 (p. 66)
• Amazon Kinesis Streams API および AWS SDK for Java を使用した Amazon Kinesis Streams コ
ンシューマーの開発 (p. 82)
• Amazon Kinesis Streams コンシューマーのトラブルシューティング (p. 86)
• Amazon Kinesis Streams コンシューマーについての高度なトピック (p. 89)
Amazon Kinesis Client Library を使用した Amazon
Kinesis Streams コンシューマーの開発
Amazon Kinesis Client Library（KCL）を使用して、Amazon Kinesis Streams のコンシューマーアプ
リケーションを開発できます。Streams API を使用して Amazon Kinesis streamからデータを取得す
ることはできますが、KCLで提供するコンシューマーアプリケーションの設計パターンとコードを使
用することをお勧めします。
Amazon CloudWatch を使用して KCL をモニタリングできます。詳細については、「Amazon
CloudWatch による Amazon Kinesis クライアントライブラリのモニタリング (p. 118)」を参照して
ください。
目次
• Amazon Kinesis Client Library (p. 66)
• KCL のロール (p. 67)
• Java での Amazon Kinesis Client Library コンシューマーの開発 (p. 67)
• Node.js での Amazon Kinesis Client Library コンシューマーの開発 (p. 73)
• .NET での Amazon Kinesis Client Library コンシューマーの開発 (p. 76)
• Python での Amazon Kinesis Client Library コンシューマーの開発 (p. 79)
• Ruby での Amazon Kinesis Client Library コンシューマーの開発 (p. 81)
Amazon Kinesis Client Library
Amazon Kinesis Client Library（KCL）を使用して、Amazon Kinesis streamからデータを取得して処
理できます。このタイプのアプリケーションは、コンシューマーとも呼ばれます。KCL は、分散コ
66
Amazon Kinesis Streams 開発者ガイド
KCL の使用
ンピューティングに関連する多くの複雑なタスクを処理します。たとえば、複数のインスタンス間
での負荷分散、インスタンスの障害に対する応答、処理済みのレコードのチェックポイント作成、リ
シャーディングへの対応が挙げられます。KCL によって、レコード処理のロジックの記述に集中する
ことができます。
KCL は AWS SDK で使用できる Streams API とは異なることに注意してください。Streams API は
Streams の多くの要素（ストリームの作成、リシャーディング、レコードの入力と取得など）を管理
するのに役立ちます。一方、KCLはコンシューマーロールでデータの処理に特化した抽象化層を提供
します。Streams API の詳細については、Amazon Kinesis API Reference を参照してください。
KCL は Java ライブラリです。Java 以外の言語のサポートは、MultiLangDaemon という多言語イ
ンターフェイスを使用して提供されます。このデーモンは Java ベースで、Java 以外の KCL 言語
を使用するときに実行されます。 たとえば、KCL for Python をインストールして、コンシューマー
アプリケーションをすべて Python で書く場合でも、MultiLangDaemon を使用するために、Java
をシステムにインストールする必要があります。さらに、MultiLangDaemon には、接続先の AWS
リージョンなどの、ユースケースに合わせてカスタマイズする必要のあるデフォルト設定例がありま
す。MultiLangDaemon の詳細については、GitHub で「KCL MultiLangDaemon project」のページにア
クセスしてください。
KCLアプリケーションは、実行時に設定情報を使用してワーカーをインスタンス化し、次にレコー
ドプロセッサを使用して Amazon Kinesis streamから取得したデータを処理します。KCLアプリケー
ションは任意の数のインスタンスで実行できます。同じアプリケーションの複数のインスタンスが、
障害発生時に連係し、動的な負荷分散を行います。スループットの制限を条件として、複数の KCLア
プリケーションで同じストリームを処理することもできます。
KCL のロール
KCL は、レコード処理のロジックと Streams の仲介として機能します。
KCLアプリケーションは起動時に KCLを呼び出してワーカーをインスタンス化します。この呼び出し
は、アプリケーションの設定情報（ストリーム名や AWS の認証情報など）を KCL に提供します。
KCL は、次のタスクを実行します。
• ストリームに接続する
• シャードを列挙する
• シャードと他のワーカー（存在する場合）の関連付けを調整する
• レコードプロセッサで管理する各シャードのレコードプロセッサをインスタンス化する
• ストリームからデータレコードを取得する
• 対応するレコードプロセッサにレコードを送信する
• 処理されたレコードのチェックポイントを作成する
• ワーカーのインスタンス数が変化したときに、シャードとワーカーの関連付けを調整する
• シャードが分割またはマージされたときに、シャードとワーカーの関連付けを調整する
Java での Amazon Kinesis Client Library コンシューマーの開
発
Amazon Kinesis Client Library（KCL）を使用して Amazon Kinesis stream からデータを処理するアプ
リケーションを構築できます。Amazon Kinesis Client Library は、複数の言語で使用できます。このト
ピックでは、Java について説明します。javadoc レファレンスを表示するには、「AWS javadoc topic
for Class AmazonKinesisClient」を参照してください。
GitHub から Java KCL をダウンロードするには、「Amazon Kinesis Client Library (Java)」を参照し
てください。 Maven で Java KCL を検索するには、「KCLsearch results」参照してください。 Java
67
Amazon Kinesis Streams 開発者ガイド
KCL の使用
KCL コンシューマーアプリケーションのサンプルコードをダウンロードするには、GitHub の「KCL
for Java sample project」を参照してください。
このサンプルアプリケーションは Apache Commons Logging を使用しま
す。AmazonKinesisApplicationSample.java ファイルで定義されている静的メソッド
configure を使用して、ログ記録の設定を変更できます。Apache Commons Logging を Log4j
や AWS Java アプリケーションとともに使用する方法の詳細については、『AWS SDK for Java
Developer Guide』の「Log4j を使用したログ記録」を参照してください。
Java で KCLコンシューマーアプリケーションを実装する場合は、次のタスクを完了する必要がありま
す。
タスク
• IRecordProcessor メソッドを実装する (p. 68)
• IRecordProcessor インターフェイスのクラスファクトリを実装する (p. 70)
• ワーカーの作成 (p. 71)
• 設定プロパティを変更する (p. 71)
• レコードプロセッサインターフェイスのバージョン 2 への移行 (p. 72)
IRecordProcessor メソッドを実装する
KCL は現在、IRecordProcessor インターフェイスの 2 つのバージョンをサポートしています。最
初のインターフェースは KCL のファーストバージョンで、バージョン 2 は KCL 1.5.0 バージョンか
ら利用可能です。どちらのインターフェイスも完全にサポートされています。どちらにするかの選択
は、お使いのシナリオの要件によって異なります。 違いについての詳細は、ローカルの Java ビルド
の Java ドキュメント、あるいはソースコードを参照してください。 以下のセクションでは、使い始
めの最小限の実装を概説します。
IRecordProcessor バージョン
• オリジナルインターフェイス（バージョン 1） (p. 68)
• 更新されたインターフェイス（バージョン 2） (p. 70)
オリジナルインターフェイス（バージョン 1）
オリジナルな IRecordProcessor interface (package
com.amazonaws.services.kinesis.clientlibrary.interfaces) は、コンシューマーが実装
しているべき次のレコードプロセッサメソッドを公開します。 このサンプルでは、開始点として使用
できる実装を提供しています（AmazonKinesisApplicationSampleRecordProcessor.java を参
照してください）。
public void initialize(String shardId)
public void processRecords(List<Record> records, IRecordProcessorCheckpointer
checkpointer)
public void shutdown(IRecordProcessorCheckpointer checkpointer,
ShutdownReason reason)
initialize
public void initialize(String shardId)
KCL は、レコードプロセッサがインスタンス化されたときに、パラメータとして特定のシャード ID
を渡して、initialize メソッドを呼び出します。このレコードプロセッサはこのシャードのみを
処理し、通常、その逆も真です（このシャードはこのレコード プロセッサによってのみ処理されま
68
Amazon Kinesis Streams 開発者ガイド
KCL の使用
す）。 ただし、コンシューマーでは、データレコードが複数回処理される可能性に対応する必要があ
ります。Streams では「少なくとも 1 回」のセマンティクスを使用しています。これは、シャードか
ら取得されたすべてのデータレコードが、コンシューマーのワーカーによって少なくとも 1 回処理さ
れることを意味します。特定のシャードが複数のワーカーによって処理される可能性がある場合の詳
細については、「リシャーディング、拡張、並列処理 (p. 91)」を参照してください。
processRecords
public void processRecords(List<Record> records, IRecordProcessorCheckpointer
checkpointer)
KCL は、initialize(shardId) メソッドで指定されたシャードからのデータレコードのリストを渡
して、processRecords メソッドを呼び出します。 レコードプロセッサは、コンシューマーのセマ
ンティクスに従って、これらのレコードのデータを処理します。たとえば、ワーカーは、データ変換
を実行した後、Amazon S3 バケットに結果を格納できます。
データ自体に加えて、レコードにもシーケンス番号とパーティションキーが含まれます。ワーカー
はデータを処理するときに、これらの値を使用できます。たとえば、ワーカーは、パーティションの
キーの値に基づいて、データを格納する S3 バケットを選択できます。Record クラスは、レコードの
データ、シーケンス番号、およびパーティションキーへのアクセスを提供する次のメソッドを公開し
ます。
record.getData()
record.getSequenceNumber()
record.getPartitionKey()
サンプルでは、プライベートメソッド processRecordsWithRetries に、ワーカーでレコードの
データ、シーケンス番号、およびパーティションキーにアクセスする方法を示すコードが含まれてい
ます。
Streams では、シャードで既に処理されたレコードを追跡するためにレコードプロセッサが必要で
す。KCL は、チェックポインタ（IRecordProcessorCheckpointer）を processRecords に渡
すことで、この追跡を処理します。レコードプロセッサは、このインターフェイスの checkpoint メ
ソッドを呼び出して、シャード内のレコードの処理の進行状況を KCL に通知します。ワーカーでエ
ラーが発生した場合、KCL はこの情報を使用して、処理されたことが分かっている最後のレコードか
らシャードの処理を再開します。
分割または結合オペレーションの場合、KCL は、元のシャードのプロセッサが checkpoint を呼び出
して元のシャードの処理がすべて完了したことを通知するまで、新しいシャードの処理を開始しませ
ん。
パラメータを渡さない場合、KCL は、checkpoint が呼び出されるときは、レコードプロセッサに渡
された最後のレコードまで、すべてのレコードが処理されたと見なします。したがって、レコードプ
ロセッサは、渡されたリストにあるすべてのレコードの処理が完了した場合にのみ、checkpoint を
呼び出す必要があります。レコードプロセッサは、processRecords の各呼び出しで checkpoint
を呼び出す必要はありません。たとえば、プロセッサは、checkpoint を 3 回呼び出すたび
に、processRecords を呼び出すことができます。オプションでレコードの正確なシーケンス番号を
パラメータとして checkpoint に指定できます。この場合、KCL は、すべてのレコードがそのレコー
ドまで処理されたと見なします。
このサンプルでは、プライベートメソッド checkpoint で、適切な例外処理と再試行のロジックを使
用する IRecordProcessorCheckpointer.checkpoint を呼び出す方法を示しています。
KCL は、processRecords を使用して、データレコードの処理から発生するすべての例外を処理し
ます。例外が processRecords からスローされた場合、KCL は例外発生よりも前に渡されたデータ
レコードをスキップします。つまり、これらのレコードは、例外をスローしたレコードプロセッサ
や、コンシューマー内の他のレコードプロセッサには再送信されません。
69
Amazon Kinesis Streams 開発者ガイド
KCL の使用
shutdown
public void shutdown(IRecordProcessorCheckpointer checkpointer,
ShutdownReason reason)
KCL は、処理が終了した場合（シャットダウンの理由は TERMINATE）またはワーカーが応答してい
ない場合（シャットダウンの理由は ZOMBIE）、shutdown メソッドを呼び出します。
シャードが分割または結合されたか、ストリームが削除されたため、レコードプロセッサがシャード
からこれ以上レコードを受信しない場合は、処理が終了します。
KCL はまた、IRecordProcessorCheckpointer インターフェイスを shutdown に渡します。
シャットダウンの理由が TERMINATE である場合、レコードプロセッサはすべてのデータレコードの
処理を終了し、このインターフェイスの checkpoint メソッドを呼び出します。
更新されたインターフェイス（バージョン 2）
更新された IRecordProcessor interface (package
com.amazonaws.services.kinesis.clientlibrary.interfaces.v2) は、コンシューマーが
実装しているべき次のレコードプロセッサメソッドを公開します。
void initialize(InitializationInput initializationInput)
void processRecords(ProcessRecordsInput processRecordsInput)
void shutdown(ShutdownInput shutdownInput)
コンテナオブジェクトのメソッドの呼び出しで、インターフェイスのオリジナルバージョンのす
べての引数にアクセスできます。 たとえば、processRecords() でレコードのリストを取得に
は、processRecordsInput.getRecords() が使用できます。
このインターフェイスのバージョン 2（KCL 1.5.0 以降）0では、オリジナルインターフェースで提供
される入力に加えて次の新しい入力が使用できます。
シーケンス番号の開始
initialize() オペレーションへ渡される InitializationInput オブジェクトでは、開始
シーケンス番号はレコードプロセッサのインスタンスに配信されるレコードです。 このシーケン
ス番号は、同じシャードで処理されたレコードプロセッサインスタンスの最後のチェックポイン
トです。 これは、アプリケーションでこの情報が必要になる場合のために提供されます。
保留チェックポイントシーケンス番号
initialize() オペレーションへ渡される InitializationInput オブジェクトの保留チェッ
クポイントシーケンス番号（ある場合）とは、前のレコードプロセッサが停止する以前に実行で
きなかったものを示します。
IRecordProcessor
インターフェイスのクラスファクトリを実装する
レコードプロセッサのメソッドを実装するクラスのファクトリも実装する必要があります。コン
シューマーは、ワーカーをインスタンス化するときに、このファクトリへの参照を渡します。
サンプルでは、オリジナルのレコードプロセッサインターフェースを使用し
た、AmazonKinesisApplicationSampleRecordProcessorFactory.java ファイルのファク
トリクラスを実装します。 クラスファクトリでバージョン 2 レコードプロセッサを作成する場合に
は、com.amazonaws.services.kinesis.clientlibrary.interfaces.v2 とい名のパッケージ
を使用してください。
public class SampleRecordProcessorFactory implements
IRecordProcessorFactory {
70
Amazon Kinesis Streams 開発者ガイド
KCL の使用
/**
* Constructor.
*/
public SampleRecordProcessorFactory() {
super();
}
/**
* {@inheritDoc}
*/
@Override
public IRecordProcessor createProcessor() {
return new SampleRecordProcessor();
}
}
ワーカーの作成
「IRecordProcessor メソッドを実装する (p. 68)」で説明されるように、KCL レコードプロセッサ
には選択できる 2 バージョンがあり、ワーカーを作成する方法に影響します。 オリジナルレコードプ
ロセッサインターフェイスは、次のコードストラクチャを使用してワーカーを作成します。
final KinesisClientLibConfiguration config = new
KinesisClientLibConfiguration(...)
final IRecordProcessorFactory recordProcessorFactory = new
RecordProcessorFactory();
final Worker worker = new Worker(recordProcessorFactory, config);
レコード プロセッサインターフェイスのバージョン 2 では、Worker.Builder を使用してワーカを
作成でき、どのコンストラクタを使うかや引数の順序を考慮する必要はありません。 更新されたレ
コードプロセッサインターフェイスは、次のコードストラクチャを使用してワーカーを作成します。
final KinesisClientLibConfiguration config = new
KinesisClientLibConfiguration(...)
final IRecordProcessorFactory recordProcessorFactory = new
RecordProcessorFactory();
final Worker worker = new Worker.Builder()
.recordProcessorFactory(recordProcessorFactory)
.config(config)
.build();
設定プロパティを変更する
このサンプルでは、設定プロパティのデフォルト値を提供します。ワーカーのこの設定データは
KinesisClientLibConfiguration オブジェクトにまとめられています。ワーカーをインスタンス
化する呼び出しで、このオブジェクトと IRecordProcessor のクラスファクトリへの参照が渡され
ます。Java の properties ファイルを使用してこれらのプロパティを独自の値にオーバーライドできま
す（AmazonKinesisApplicationSample.java を参照してください）。
アプリケーション名
KCL には、ユーザーのアプリケーション間、および同じリージョン内の DynamoDB テーブル間で一
意のアプリケーション名が必要です。次のようにアプリケーション名の設定値を使用します。
• このアプリケーション名と関連付けられたすべてのワーカーは、連係して同じストリームを処理し
ていると見なされます。これらのワーカーは複数のインスタンスに分散している場合もあります。
同じアプリケーションコードの追加のインスタンスを実行するときに、アプリケーション名が異な
71
Amazon Kinesis Streams 開発者ガイド
KCL の使用
る場合、KCL は 2 番目のインスタンスを、同じストリームで動作するまったく別のアプリケーショ
ンと見なします。
• KCL はアプリケーション名を使用して DynamoDB テーブルを作成し、このテーブルを使用してア
プリケーションの状態情報（チェックポイントやワーカーとシャードのマッピングなど）を保存
します。各アプリケーションには、それぞれ DynamoDB テーブルがあります。詳細については、
「Amazon Kinesis Streams Applicationの状態の追跡 (p. 89)」を参照してください。
認証情報の設定
デフォルトの認証情報プロバイダチェーンのいずれかの認証情報プロバイダで AWS の認証情報を使
用できるようにする必要があります。たとえば、EC2 インスタンスでコンシューマーを実行してい
る場合は、IAM ロールでインスタンスを起動することをお勧めします。この IAM ロールに関連付け
られたアクセス許可を反映する AWS の認証情報は、インスタンスメタデータを通じて、インスタン
ス上のアプリケーションで使用できるようになります。これは、EC2 インスタンスで実行されるコン
シューマーの認証情報を管理するための最も安全な方法です。
サンプルアプリケーションは、最初にインスタンスメタデータから IAM の認証情報を取得しようとし
ます。
credentialsProvider = new InstanceProfileCredentialsProvider();
サンプルアプリケーションは、インスタンスメタデータから認証情報を取得できない場合、properties
ファイルから認証情報を取得しようとします。
credentialsProvider = new ClasspathPropertiesFileCredentialsProvider();
インスタンスメタデータの詳細については、『Linux インスタンス用 Amazon EC2 ユーザーガイド』
の「インスタンスメタデータ」を参照してください。
複数のインスタンスへのワーカー ID の使用
サンプルの初期化コードは、次のコードスニペットに示すように、ローカルコンピュータ名にグロー
バル一意識別子を追加して、ワーカーの ID（workerId）を作成します。このアプローチによって、1
台のコンピュータでコンシューマーアプリケーションの複数のインスタンスを実行するシナリオに対
応できます。
String workerId = InetAddress.getLocalHost().getCanonicalHostName() + ":" +
UUID.randomUUID();
レコードプロセッサインターフェイスのバージョン 2 への移行
オリジナルインターフェースで使われるコードを移行するためには、上記のステップに加えて、次の
手順が必要となります。
1.
レコードプロセッサのクラスを変更して、バージョン 2 レコードプロセッサインターフェイスに
インポートします。
import
com.amazonaws.services.kinesis.clientlibrary.interfaces.v2.IRecordProcessor;
2.
入力するレファレンスを変更して、コンテナオブジェクトでメソッドの呼び出
しを使います。 たとえば、shutdown() オペレーションで、checkpointer を
shutdownInput.getCheckpointer() に変更します。
3.
レコードプロセッサのファクトリークラスを変更して、バージョン 2 レコードプロセッサファク
トリーインターフェイスにインポートします。
72
Amazon Kinesis Streams 開発者ガイド
KCL の使用
import
com.amazonaws.services.kinesis.clientlibrary.interfaces.v2.IRecordProcessorFactory;
4.
ワーカーのコンストラクチャを変更して、Worker.Builder を使います。 以下に例を示しま
す。
final Worker worker = new Worker.Builder()
.recordProcessorFactory(recordProcessorFactory)
.config(config)
.build();
Node.js での Amazon Kinesis Client Library コンシューマーの
開発
Amazon Kinesis Client Library（KCL）を使用して Amazon Kinesis stream からデータを処理するアプ
リケーションを構築できます。Amazon Kinesis Client Library は、複数の言語で使用できます。このト
ピックでは、Node.js について説明します。
KCL は Java ライブラリです。Java 以外の言語のサポートは、MultiLangDaemon という多言語イン
ターフェイスを使用して提供されます。このデーモンは Java ベースで、Java 以外の KCL 言語を使用
するときに実行されます。 そのため、KCL for Node.js をインストールして、コンシューマーアプリ
ケーションをすべて Node.js で書く場合でも、MultiLangDaemon を使用するために、Java をシステ
ムにインストールする必要があります。さらに、MultiLangDaemon には、接続先の AWS リージョン
などの、ユースケースに合わせてカスタマイズする必要のあるデフォルト設定例があります。GitHub
の MultiLangDaemon の詳細については「KCL MultiLangDaemon project」のページを参照してくださ
い。
GitHub から Node.js KCL をダウンロードするには、「Amazon Kinesis Client Library (Node.js)」を参
照してください。
サンプルコードのダウンロード
Node.js の KCL で使用可能な 2 つのサンプルコードがあります。
• 基本サンプル
Node.js で KCLコンシューマーアプリケーションを構築する方法の基本を説明する次のセクション
で使用されます。
• click-stream-sample
基本サンプルコードを理解したあとの、やや上級で実際のシナリオを使用したサンプル。このサン
プルはここでは説明しませんが、詳細を説明した README ファイルがあります。
Node.js で KCLコンシューマーアプリケーションを実装する場合は、次のタスクを完了する必要があ
ります。
タスク
• レコードプロセッサを実装する (p. 73)
• 設定プロパティを変更する (p. 75)
レコードプロセッサを実装する
KCL for Node.js を使用した最もシンプルなコンシューマーは、recordProcessor 関数を実装する必
要があります。この関数には、initialize、processRecords、および shutdown 関数が含まれま
73
Amazon Kinesis Streams 開発者ガイド
KCL の使用
す。このサンプルでは、開始点として使用できる実装を提供しています（sample_kcl_app.js を参
照してください）。
function recordProcessor() {
// return an object that implements initialize, processRecords and shutdown
functions.}
initialize
initialize: function(initializeInput, completeCallback)
レコードプロセッサが開始するときに、KCL が initialize 関数を呼び出します。このレコードプ
ロセッサは initializeInput.shardId として渡されるシャード ID のみを処理し、通常、その逆も
真です（このシャードはこのレコードプロセッサによってのみ処理されます）。ただし、コンシュー
マーでは、データレコードが複数回処理される可能性に対応する必要があります。これは、Streams
では「少なくとも 1 回」のセマンティクスを使用しているためです。これは、シャードから取得され
たすべてのデータレコードが、コンシューマーのワーカーによって少なくとも 1 回処理されることを
意味します。特定のシャードが複数のワーカーによって処理される可能性がある場合の詳細について
は、「リシャーディング、拡張、並列処理 (p. 91)」を参照してください。
processRecords
processRecords : function (processRecordsInput, completeCallback)
KCL は、initialize 関数に指定したシャードからのデータレコードのリストが含まれる入力を使用
して、この関数を呼び出します。実装するレコードプロセッサは、コンシューマーのセマンティクス
に従って、これらのレコードのデータを処理します。たとえば、ワーカーは、データ変換を実行した
後、 S3 バケットに結果を格納できます。
データ自体に加えて、レコードにもシーケンス番号とパーティションキーが含まれ、ワーカーはデー
タを処理するときに、これらを使用できます。たとえば、ワーカーは、パーティションのキーの値に
基づいて、データを格納する S3 バケットを選択できます。record ディクショナリは、レコードの
データ、シーケンス番号、およびパーティションキーにアクセスする次のキーと値のペアを公開しま
す。
record.data
record.sequenceNumber
record.partitionKey
データは Base64 でエンコードされていることに注意してください。
基本サンプルでは、関数 processRecords に、ワーカーでレコードのデータ、シーケンス番号、お
よびパーティションキーにアクセスする方法を示すコードが含まれています。
Streams では、シャードで既に処理されたレコードを追跡するためにレコードプロセッサが必要で
す。KCL は、processRecordsInput.checkpointer として渡した checkpointer オブジェクト
を使用して、この追跡を処理します。レコードプロセッサは、checkpointer.checkpoint 関数を
呼び出して、シャード内のレコードの処理の進行状況を KCL に通知します。ワーカーでエラーが発生
した場合、シャードの処理を再開するときに、処理されたことが分かっている最後のレコードから再
開するように、KCL はこの情報を使用します。
分割または結合オペレーションの場合、KCL は、元のシャードのプロセッサが checkpoint を呼び出
して元のシャードの処理がすべて完了したことを通知するまで、新しいシャードの処理を開始しませ
ん。
74
Amazon Kinesis Streams 開発者ガイド
KCL の使用
checkpoint 関数にシーケンス番号を渡さない場合、KCL は、checkpoint が呼び出されるときは、
レコードプロセッサに渡された最後のレコードまで、すべてのレコードが処理されたと見なします。
したがって、レコードプロセッサは、渡されたリストにあるすべてのレコードの処理が完了した場合
にのみ、checkpoint を呼び出す必要があります。レコードプロセッサは、processRecords の各
呼び出しで checkpoint を呼び出す必要はありません。たとえば、プロセッサは、3 回呼び出すた
びに、または、レコードプロセッサの外部イベント（実装したカスタムの認証または検証サービスな
ど）により、checkpoint を呼び出すことができます。
オプションでレコードの正確なシーケンス番号をパラメータとして checkpoint に指定できます。こ
の場合、KCL は、すべてのレコードがそのレコードまで処理されたと見なします。
基本サンプルアプリケーションでは、checkpointer.checkpoint 関数の最もシンプルな呼び出し
を示します。関数のこの時点でコンシューマーに必要な他のチェックポイントロジックを追加できま
す。
shutdown
shutdown: function(shutdownInput, completeCallback)
KCL は、処理が終了した場合（shutdownInput.reason は TERMINATE）またはワーカーが応答し
ていない場合（shutdownInput.reason は ZOMBIE）、shutdown 関数を呼び出します。
シャードが分割または結合されたか、ストリームが削除されたため、レコードプロセッサがシャード
からこれ以上レコードを受信しない場合は、処理が終了します。
また、KCL は、shutdownInput.checkpointer オブジェクトを shutdown に渡します。シャット
ダウンの理由が TERMINATE である場合、レコードプロセッサがすべてのデータレコードの処理を終
了したことを確認し、このインターフェイスの checkpoint 関数を呼び出します。
設定プロパティを変更する
このサンプルでは、設定プロパティのデフォルト値を提供します。これらのプロパティを独自の値に
オーバーライドできます（基本サンプルの sample.properties を参照してください）。
アプリケーション名
KCL には、ユーザーのアプリケーション間、および同じリージョン内の DynamoDB テーブル間で一
意のアプリケーションが必要です。次のようにアプリケーション名の設定値を使用します。
• このアプリケーション名と関連付けられたすべてのワーカーは、連係して同じストリームを処理し
ていると見なされます。これらのワーカーは複数のインスタンスに分散している場合もあります。
同じアプリケーションコードの追加のインスタンスを実行するときに、アプリケーション名が異な
る場合、KCL は 2 番目のインスタンスを、同じストリームで動作するまったく別のアプリケーショ
ンと見なします。
• KCL はアプリケーション名を使用して DynamoDB テーブルを作成し、このテーブルを使用してア
プリケーションの状態情報（チェックポイントやワーカーとシャードのマッピングなど）を保存
します。各アプリケーションには、それぞれ DynamoDB テーブルがあります。詳細については、
「Amazon Kinesis Streams Applicationの状態の追跡 (p. 89)」を参照してください。
認証情報の設定
デフォルトの認証情報プロバイダチェーンのいずれかの認証情報プロバイダで AWS の認証情報を使
用できるようにする必要があります。AWSCredentialsProvider プロパティを使用して認証情報
プロバイダを設定できます。sample.properties ファイルで、デフォルトの認証情報プロバイダ
チェーンのいずれかの認証情報プロバイダでユーザーの認証情報を使用できるようにする必要があり
ます。EC2 インスタンスでコンシューマーを実行している場合は、IAM ロールでインスタンスを設定
することをお勧めします。この IAM ロールに関連付けられたアクセス許可を反映する AWS の認証情
75
Amazon Kinesis Streams 開発者ガイド
KCL の使用
報は、インスタンスメタデータを通じて、インスタンス上のアプリケーションで使用できるようにな
ります。これは、EC2 インスタンスで実行されるコンシューマーアプリケーションの認証情報を管理
するための最も安全な方法です。
次の例では、KCL を設定し、sample_kcl_app.js で指定されているレコードプロセッサを使用して
「kclnodejssample」という Amazon Kinesis stream を処理します。
# The Node.js executable
script
executableName = node sample_kcl_app.js
# The name of an Amazon Kinesis stream to process
streamName = kclnodejssample
# Unique KCL application name
applicationName = kclnodejssample
# Use default AWS credentials provider chain
AWSCredentialsProvider = DefaultAWSCredentialsProviderChain
# Read from the beginning of the stream
initialPositionInStream = TRIM_HORIZON
.NET での Amazon Kinesis Client Library コンシューマーの開
発
Amazon Kinesis Client Library（KCL）を使用して Amazon Kinesis stream からデータを処理するアプ
リケーションを構築できます。Amazon Kinesis Client Library は、複数の言語で使用できます。このト
ピックでは、.NET について説明します。
KCL は Java ライブラリです。Java 以外の言語のサポートは、MultiLangDaemon という多言語イ
ンターフェイスを使用して提供されます。このデーモンは Java ベースで、Java 以外の KCL 言語
を使用するときに実行されます。 そのため、KCL for .NET をインストールして、コンシューマーア
プリケーションをすべて .NET で書く場合でも、MultiLangDaemon を使用するために、Java をシ
ステムにインストールする必要があります。さらに、MultiLangDaemon には、接続先の AWS リー
ジョンなどの、ユースケースに合わせてカスタマイズする必要のあるデフォルト設定例がありま
す。MultiLangDaemon の詳細については、GitHub で「KCL MultiLangDaemon project」のページにア
クセスしてください。
GitHub から .NET KCL をダウンロードするには、「Amazon Kinesis Client Library (.NET)」にアクセ
スしてください。 .NET KCL コンシューマーアプリケーションのサンプルコードをダウンロードする
には、GitHub で「GitHub の KCL for .NET sample consumer project」のページにアクセスしてくださ
い。
.NET で KCLコンシューマーアプリケーションを実装する場合は、次のタスクを完了する必要があり
ます。
タスク
• IRecordProcessor クラスのメソッドを実装する (p. 76)
• 設定プロパティを変更する (p. 78)
IRecordProcessor クラスのメソッドを実装する
コンシューマーでは、IRecordProcessor の次のメソッドを実装する必要があります。出発
点として使用できる実装がサンプルコンシューマーに提供されています（SampleConsumer/
AmazonKinesisSampleConsumer.cs の SampleRecordProcessor クラスを参照してくださ
い）。
public void Initialize(InitializationInput input)
76
Amazon Kinesis Streams 開発者ガイド
KCL の使用
public void ProcessRecords(ProcessRecordsInput input)
public void Shutdown(ShutdownInput input)
Initialize
public void Initialize(InitializationInput input)
KCL は、レコードプロセッサがインスタンス化されたときに、input パラメータの特定のシャード
ID（input.ShardId）を渡して、このメソッドを呼び出します。このレコードプロセッサはこの
シャードのみを処理し、通常、その逆も真です（このシャードはこのレコード プロセッサによっての
み処理されます）。ただし、コンシューマーでは、データレコードが複数回処理される可能性に対応
する必要があります。これは、Streams では「少なくとも 1 回」のセマンティクスを使用しているた
めです。これは、シャードから取得されたすべてのデータレコードが、コンシューマーのワーカーに
よって少なくとも 1 回処理されることを意味します。特定のシャードが複数のワーカーによって処理
される可能性がある場合の詳細については、「リシャーディング、拡張、並列処理 (p. 91)」を参照
してください。
ProcessRecords
public void ProcessRecords(ProcessRecordsInput input)
KCL は、Initialize メソッドで指定されたシャードの input パラメータにあるデータレコードの
リスト（input.Records）を渡して、このメソッドを呼び出します。実装するレコードプロセッサ
は、コンシューマーのセマンティクスに従って、これらのレコードのデータを処理します。たとえ
ば、ワーカーは、データ変換を実行した後、 S3 バケットに結果を格納できます。
データ自体に加えて、レコードにもシーケンス番号とパーティションキーが含まれます。ワーカーは
データを処理するときに、これらの値を使用できます。たとえば、ワーカーは、パーティションの
キーの値に基づいて、データを格納する S3 バケットを選択できます。Record クラスは以下を公開
し、レコードのデータ、シーケンス番号、およびパーティションキーのアクセスを可能にします。
byte[] Record.Data
string Record.SequenceNumber
string Record.PartitionKey
サンプルでは、メソッド ProcessRecordsWithRetries に、ワーカーでレコードのデータ、シーケ
ンス番号、およびパーティションキーにアクセスする方法を示すコードが含まれています。
Streams では、シャードで既に処理されたレコードを追跡するためにレコードプロ
セッサが必要です。KCL は、Checkpointer オブジェクトを ProcessRecords に渡
すこと（input.Checkpointer）で、この追跡を処理します。レコードプロセッサ
は、Checkpointer.Checkpoint メソッドを呼び出して、シャード内のレコード処理の進行状況を
KCL に通知します。ワーカーでエラーが発生した場合、KCL はこの情報を使用して、処理されたこと
が分かっている最後のレコードからシャードの処理を再開します。
分割または結合オペレーションの場合、KCL は、元のシャードのプロセッサが
Checkpointer.Checkpoint を呼び出して元のシャードの処理がすべて完了したことを通知するま
で、新しいシャードの処理を開始しません。
パラメータを渡さない場合、KCL は、Checkpointer.Checkpoint が呼び出されるときは、レ
コードプロセッサに渡された最後のレコードまで、すべてのレコードが処理されたと見なしま
す。したがって、レコードプロセッサは、渡されたリストにあるすべてのレコードの処理が完了
した場合にのみ、Checkpointer.Checkpoint を呼び出す必要があります。レコードプロセッ
サは、ProcessRecords の各呼び出しで Checkpointer.Checkpoint を呼び出す必要はありま
せん。たとえば、プロセッサは、3 回または 4 回呼び出すたびに、Checkpointer.Checkpoint
77
Amazon Kinesis Streams 開発者ガイド
KCL の使用
を呼び出すことができます。オプションでレコードの正確なシーケンス番号をパラメータとして
Checkpointer.Checkpoint に指定できます。この場合、KCL は、レコード処理がそのレコードま
で完了したと見なします。
サンプルでは、プライベートメソッド Checkpoint(Checkpointer checkpointer) で、適切な例
外処理と再試行のロジックを使用する Checkpointer.Checkpoint メソッドを呼び出す方法を示し
ています。
KCL for .NET では、例外を処理する方法が他の KCL 言語ライブラリとは異なり、データレコードの
処理から発生した例外を扱いません。ユーザーコードからの例外がキャッチされないと、プログラム
がクラッシュします。
シャットダウン
public void Shutdown(ShutdownInput input)
KCL は、処理が終了した場合（シャットダウンの理由は TERMINATE）またはワーカーが応答してい
ない場合（シャットダウンの input.Reason の値は ZOMBIE）、Shutdown メソッドを呼び出しま
す。
シャードが分割または結合されたか、ストリームが削除されたため、レコードプロセッサがシャード
からこれ以上レコードを受信しない場合は、処理が終了します。
また、KCL は、Checkpointer オブジェクトを shutdown に渡します。シャットダウンの理由が
TERMINATE である場合、レコードプロセッサはすべてのデータレコードの処理を終了し、このイン
ターフェイスの checkpoint メソッドを呼び出します。
設定プロパティを変更する
このサンプルコンシューマーでは、設定プロパティのデフォルト値を提供します。これらのプロパ
ティを独自の値にオーバーライドできます（SampleConsumer/kcl.properties を参照してくださ
い）。
アプリケーション名
KCL には、ユーザーのアプリケーション間、および同じリージョン内の DynamoDB テーブル間で一
意のアプリケーションが必要です。次のようにアプリケーション名の設定値を使用します。
• このアプリケーション名と関連付けられたすべてのワーカーは、連係して同じストリームを処理し
ていると見なされます。これらのワーカーは複数のインスタンスに分散している場合もあります。
同じアプリケーションコードの追加のインスタンスを実行するときに、アプリケーション名が異な
る場合、KCL は 2 番目のインスタンスを、同じストリームで動作するまったく別のアプリケーショ
ンと見なします。
• KCL はアプリケーション名を使用して DynamoDB テーブルを作成し、このテーブルを使用してア
プリケーションの状態情報（チェックポイントやワーカーとシャードのマッピングなど）を保存
します。各アプリケーションには、それぞれ DynamoDB テーブルがあります。詳細については、
「Amazon Kinesis Streams Applicationの状態の追跡 (p. 89)」を参照してください。
認証情報の設定
デフォルトの認証情報プロバイダチェーンのいずれかの認証情報プロバイダで AWS の認証情報を使
用できるようにする必要があります。AWSCredentialsProvider プロパティを使用して認証情報プ
ロバイダを設定できます。sample.properties で、デフォルトの認証情報プロバイダチェーンのいずれ
かの認証情報プロバイダでユーザーの認証情報を使用できるようにする必要があります。EC2 インス
タンスでコンシューマーアプリケーションを実行している場合は、IAM ロールでインスタンスを設定
することをお勧めします。この IAM ロールに関連付けられたアクセス許可を反映する AWS の認証情
78
Amazon Kinesis Streams 開発者ガイド
KCL の使用
報は、インスタンスメタデータを通じて、インスタンス上のアプリケーションで使用できるようにな
ります。これは、EC2 インスタンスで実行されるコンシューマーの認証情報を管理するための最も安
全な方法です。
サンプルのプロパティファイルでは、KCL を設定し、AmazonKinesisSampleConsumer.cs で指定
されているレコードプロセッサを使用して「words」という Amazon Kinesis stream を処理します。
Python での Amazon Kinesis Client Library コンシューマーの
開発
Amazon Kinesis Client Library（KCL）を使用して Amazon Kinesis stream からデータを処理するアプ
リケーションを構築できます。Amazon Kinesis Client Library は、複数の言語で使用できます。このト
ピックでは、Python について説明します。
KCL は Java ライブラリです。Java 以外の言語のサポートは、MultiLangDaemon という多言語イ
ンターフェイスを使用して提供されます。このデーモンは Java ベースで、Java 以外の KCL 言語
を使用するときに実行されます。 そのため、KCL for Python をインストールして、コンシューマー
アプリケーションをすべて Python で書く場合でも、MultiLangDaemon を使用するために、Java
をシステムにインストールする必要があります。さらに、MultiLangDaemon には、接続先の AWS
リージョンなどの、ユースケースに合わせてカスタマイズする必要のあるデフォルト設定例があり
ます。MultiLangDaemon の詳細については https://github.com/awslabs/amazon-kinesis-client/tree/
master/src/main/java/com/amazonaws/services/kinesis/multilangGitHub の KCL MultiLangDaemon プ
ロジェクトのページを参照してください。
GitHub から Python KCL をダウンロードするには、「Amazon Kinesis Client Library (Python)」にア
クセスしてください。 Python KCL コンシューマーアプリケーションのサンプルコードをダウンロー
ドするには、GitHub で「KCL for Python sample project」にアクセスしてください。
Python で KCLコンシューマーアプリケーションを実装する場合は、次のタスクを完了する必要があり
ます。
タスク
• RecordProcessor クラスのメソッドを実装する (p. 79)
• 設定プロパティを変更する (p. 81)
RecordProcessor クラスのメソッドを実装する
RecordProcess クラスでは、RecordProcessorBase を拡張して次のメソッドを実装
する必要があります。このサンプルでは、開始点として使用できる実装を提供しています
（sample_kclpy_app.py を参照してください。）
def initialize(self, shard_id)
def process_records(self, records, checkpointer)
def shutdown(self, checkpointer, reason)
initialize
def initialize(self, shard_id)
KCL は、レコードプロセッサがインスタンス化されたときに、パラメータとして特定のシャード ID
を渡して、initialize メソッドを呼び出します。このレコードプロセッサはこのシャードのみを
処理し、通常、その逆も真です（このシャードはこのレコード プロセッサによってのみ処理されま
す）。ただし、コンシューマーでは、データレコードが複数回処理される可能性に対応する必要があ
ります。これは、Streams では「少なくとも 1 回」のセマンティクスを使用しているためです。これ
79
Amazon Kinesis Streams 開発者ガイド
KCL の使用
は、シャードから取得されたすべてのデータレコードが、コンシューマーのワーカーによって少なく
とも 1 回処理されることを意味します。特定のシャードが複数のワーカーによって処理される可能性
がある場合の詳細については、「リシャーディング、拡張、並列処理 (p. 91)」を参照してくださ
い。
process_records
def process_records(self, records, checkpointer)
KCL は、initialize メソッドで指定されたシャードからのデータレコードのリストを渡して、この
メソッドを呼び出します。実装するレコードプロセッサは、コンシューマーのセマンティクスに従っ
て、これらのレコードのデータを処理します。たとえば、ワーカーは、データ変換を実行した後、 S3
バケットに結果を格納できます。
データ自体に加えて、レコードにもシーケンス番号とパーティションキーが含まれます。ワーカー
はデータを処理するときに、これらの値を使用できます。たとえば、ワーカーは、パーティションの
キーの値に基づいて、データを格納する S3 バケットを選択できます。record ディクショナリは、レ
コードのデータ、シーケンス番号、およびパーティションキーにアクセスする次のキーと値のペアを
公開します。
record.get('data')
record.get('sequenceNumber')
record.get('partitionKey')
データは Base64 でエンコードされていることに注意してください。
サンプルでは、メソッド process_records に、ワーカーでレコードのデータ、シーケンス番号、お
よびパーティションキーにアクセスする方法を示すコードが含まれています。
Streams では、シャードで既に処理されたレコードを追跡するためにレコードプロセッサが必要で
す。KCL は、Checkpointer オブジェクトを process_records に渡すことで、この追跡を処理し
ます。レコードプロセッサは、このオブジェクトの checkpoint メソッドを呼び出して、シャード内
のレコードの処理の進行状況を KCL に通知します。ワーカーでエラーが発生した場合、KCL はこの
情報を使用して、処理されたことが分かっている最後のレコードからシャードの処理を再開します。
分割または結合オペレーションの場合、KCL は、元のシャードのプロセッサが checkpoint を呼び出
して元のシャードの処理がすべて完了したことを通知するまで、新しいシャードの処理を開始しませ
ん。
パラメータを渡さない場合、KCL は、checkpoint が呼び出されるときは、レコードプロセッサに渡
された最後のレコードまで、すべてのレコードが処理されたと見なします。したがって、レコードプ
ロセッサは、渡されたリストにあるすべてのレコードの処理が完了した場合にのみ、checkpoint を
呼び出す必要があります。レコードプロセッサは、process_records の各呼び出しで checkpoint
を呼び出す必要はありません。たとえば、プロセッサは、3 回呼び出すたびに、checkpoint を
呼び出すことができます。オプションでレコードの正確なシーケンス番号をパラメータとして
checkpoint に指定できます。この場合、KCL は、すべてのレコードがそのレコードまで処理された
と見なします。
サンプルでは、プライベートメソッド checkpoint で、適切な例外処理と再試行のロジックを使用す
る Checkpointer.checkpoint メソッドを呼び出す方法を示しています。
KCL は、process_records を使用して、データレコードの処理から発生するすべての例外を
処理します。例外が process_records からスローされた場合、KCLは例外発生よりも前に
process_records に渡されたデータレコードをスキップします。つまり、これらのレコードは、例
外をスローしたレコードプロセッサや、コンシューマー内の他のレコードプロセッサには再送信され
ません。
80
Amazon Kinesis Streams 開発者ガイド
KCL の使用
shutdown
def shutdown(self, checkpointer, reason)
KCL は、処理が終了した場合（シャットダウンの理由は TERMINATE）またはワーカーが応答してい
ない場合（シャットダウンの reason は ZOMBIE）、shutdown メソッドを呼び出します。
シャードが分割または結合されたか、ストリームが削除されたため、レコードプロセッサがシャード
からこれ以上レコードを受信しない場合は、処理が終了します。
また、KCL は、Checkpointer オブジェクトを shutdown に渡します。シャットダウンの reason
が TERMINATE である場合、レコードプロセッサはすべてのデータレコードの処理を終了し、このイ
ンターフェイスの checkpoint メソッドを呼び出します。
設定プロパティを変更する
このサンプルでは、設定プロパティのデフォルト値を提供します。これらのプロパティを独自の値に
オーバーライドできます（sample.properties を参照してください）。
アプリケーション名
KCL には、ユーザーのアプリケーション間、および同じリージョン内の DynamoDB テーブル間で一
意のアプリケーションが必要です。次のようにアプリケーション名の設定値を使用します。
• このアプリケーション名と関連付けられたすべてのワーカーは、連係して同じストリームを処理し
ていると見なされます。これらのワーカーは複数のインスタンスに分散している場合もあります。
同じアプリケーションコードの追加のインスタンスを実行するときに、アプリケーション名が異な
る場合、KCL は 2 番目のインスタンスを、同じストリームで動作するまったく別のアプリケーショ
ンと見なします。
• KCL はアプリケーション名を使用して DynamoDB テーブルを作成し、このテーブルを使用してア
プリケーションの状態情報（チェックポイントやワーカーとシャードのマッピングなど）を保存
します。各アプリケーションには、それぞれ DynamoDB テーブルがあります。詳細については、
「Amazon Kinesis Streams Applicationの状態の追跡 (p. 89)」を参照してください。
認証情報の設定
デフォルトの認証情報プロバイダチェーンのいずれかの認証情報プロバイダで AWS の認証情報を使
用できるようにする必要があります。AWSCredentialsProvider プロパティを使用して認証情報プ
ロバイダを設定できます。sample.properties で、デフォルトの認証情報プロバイダチェーンのいずれ
かの認証情報プロバイダでユーザーの認証情報を使用できるようにする必要があります。EC2 インス
タンスでコンシューマーアプリケーションを実行している場合は、IAM ロールでインスタンスを設定
することをお勧めします。この IAM ロールに関連付けられたアクセス許可を反映する AWS の認証情
報は、インスタンスメタデータを通じて、インスタンス上のアプリケーションで使用できるようにな
ります。これは、EC2 インスタンスで実行されるコンシューマーアプリケーションの認証情報を管理
するための最も安全な方法です。
サンプルのプロパティファイルでは、KCL を設定し、sample_kclpy_app.py で指定されているレ
コードプロセッサを使用して「words」という Amazon Kinesis stream を処理します。
Ruby での Amazon Kinesis Client Library コンシューマーの開
発
Amazon Kinesis Client Library（KCL）を使用して Amazon Kinesis stream からデータを処理するアプ
リケーションを構築できます。Amazon Kinesis Client Library は、複数の言語で使用できます。このト
ピックでは、Ruby について説明します。
81
Amazon Kinesis Streams 開発者ガイド
API の使用
KCL は Java ライブラリです。Java 以外の言語のサポートは、MultiLangDaemon という多言語イ
ンターフェイスを使用して提供されます。このデーモンは Java ベースで、Java 以外の KCL 言語
を使用するときに実行されます。 そのため、KCL for .Ruby をインストールして、コンシューマー
アプリケーションをすべて Ruby で書く場合でも、MultiLangDaemon を使用するために、Java を
システムにインストールする必要があります。 さらに、MultiLangDaemon には、接続先の AWS
リージョンなどの、ユースケースに合わせてカスタマイズする必要のあるデフォルト設定例がありま
す。MultiLangDaemon の詳細については、GitHub で「KCL MultiLangDaemon project」のページにア
クセスしてください。
GitHub から Ruby KCL をダウンロードするには、「Amazon Kinesis Client Library (Ruby)」にアクセ
スしてください。 Ruby KCL コンシューマーアプリケーションのサンプルコードをダウンロードする
には、GitHub で「KCLfor Ruby sample project」にアクセスしてください。
KCL の Ruby サポートライブラリの詳細については、「KCL Ruby Gems Documentation」を参照して
ください。
Amazon Kinesis Streams API および AWS SDK
for Java を使用した Amazon Kinesis Streams コン
シューマーの開発
Amazon Kinesis Streams API と AWS SDK for Java を使用してコンシューマーを開発できま
す。Streams を初めて利用する場合は、Amazon Kinesis Streams とは? (p. 1) と Amazon Kinesis
Streams の使用開始 (p. 9) に説明されている概念と用語について理解することから始めてください。
以下の例では、Streams API について説明し、AWS SDK for Java を使用してストリームからデータを
取得します。ただし、ほとんどのユースケースでは、Streams KCL ライブラリを使用します。詳細に
ついては、「Amazon Kinesis Client Library を使用した Amazon Kinesis Streams コンシューマーの開
発 (p. 66)」を参照してください。
この章で紹介する Java サンプルコードは、基本的な Streams API オペレーションを実行する方法を
示しており、オペレーションタイプ別に論理的に分割されています。これらのサンプルは、すべての
例外を確認しているわけではなく、すべてのセキュリティやパフォーマンスの側面を考慮しているわ
けでもない点で、本稼働環境に使用できるコードを表すものではありません。また、他のプログラミ
ング言語を使用して Streams API を呼び出すこともできます。利用可能なすべての AWS SDK の詳細
については、「アマゾン ウェブ サービスを使用した開発の開始」を参照してください。
各タスクには前提条件があります。たとえば、ストリームを作成するまではストリームにデータを
追加できず、ストリームを作成するにはクライアントを作成する必要があります。詳細については、
「Amazon Kinesis Stream の管理 (p. 96)」を参照してください。
ストリームからのデータの取得
Streams API には、ストリームからデータを取得する getShardIterator メソッドと getRecords
メソッドが用意されています。これはプルモデルで、コードはストリームのシャードからデータを直
接取得します。
Amazon Kinesis Client Library（KCL）で提供されているレコードプロセッサのサポートを使用して、
コンシューマーアプリケーションのストリームデータを取得することをお勧めします。これは、デー
タを処理するコードを組み込むプッシュ モデルです。KCL は、ストリームからデータレコードを取
り出し、アプリケーションコードに配信します。さらに、KCL には、フェイルオーバー、リカバリ、
負荷分散の機能が用意されています。詳細については、「Amazon Kinesis Client Library を使用した
Amazon Kinesis Streams コンシューマーの開発 (p. 66)」を参照してください。
ただし、状況によっては AWS SDK for Java とともに Streams API を使用した方がよい場合がありま
す。たとえば、ストリームのモニタリングやデバッグのためのカスタムツールを実装する場合です。
82
Amazon Kinesis Streams 開発者ガイド
API の使用
Important
データレコードはストリームに追加されてからデフォルトでは 24 時間アクセス可能です。こ
の期間は、保持期間と呼ばれ、24 時間から 168 時間 (1～7 日) まで 1 時間単位で設定できま
す。ストリームの保持期間の詳細については、「データ保持期間の変更 (p. 105)」を参照し
てください。
シャードイテレーターを使用する
ストリームからシャード単位でレコードを取得します。シャードごとに、そのシャードから取得する
レコードのバッチごとに、シャードイテレーターを取得する必要があります。シャードイテレーター
を getRecordsRequest オブジェクトで使用して、レコードの取得元になるシャードを指定します。
シャードイテレーターに関連付ける型により、シャード内でレコードの取得元になる位置が決まりま
す（詳細については以下を参照）。シャードイテレーターを使用する前に、「ストリームからシャー
ドを取得する (p. 99)」で説明したように、シャードを取得する必要が あります。
最初のシャードイテレーターは、getShardIterator メソッドを使用して取得します。レ
コードのその他のバッチのシャードイテレーターは、getRecords メソッドによって返された
getRecordsResult オブジェクトの getNextShardIterator メソッドを使用して取得します。
シャードイテレーターは 5 分間有効です。有効な間、シャードイテレーターを使用すると、新しいも
のを取得します。使用された後でも、各シャードイテレーターは 5 分間有効であることに注目してく
ださい。
最初のシャードイテレーターを取得するには、GetShardIteratorRequest をインスタンス化
し、getShardIterator メソッドに渡します。リクエストを設定するには、ストリームとシャード
ID を指定する必要があります。AWS アカウントのストリームを取得する方法については、「スト
リームのリスト (p. 98)」を参照してください。ストリーム内のシャードを取得する方法について
は、「ストリームからシャードを取得する (p. 99)」を参照してください。
String shardIterator;
GetShardIteratorRequest getShardIteratorRequest = new
GetShardIteratorRequest();
getShardIteratorRequest.setStreamName(myStreamName);
getShardIteratorRequest.setShardId(shard.getShardId());
getShardIteratorRequest.setShardIteratorType("TRIM_HORIZON");
GetShardIteratorResult getShardIteratorResult =
client.getShardIterator(getShardIteratorRequest);
shardIterator = getShardIteratorResult.getShardIterator();
このサンプルコードでは、最初のシャードイテレーターを取得するときにイテレーター型として
TRIM_HORIZON を指定しています。このイテレーター型を指定することで、レコードはまず、シャー
ドに直近に追加されたレコード（tip）からではなく、シャードに最初に追加されたレコードから返さ
れます。可能なイテレーターの種類は次になります。
• AT_SEQUENCE_NUMBER
• AFTER_SEQUENCE_NUMBER
• AT_TIMESTAMP
• TRIM_HORIZON
• LATEST
詳細については、「ShardIteratorType」を参照してください。
イテレーター型によっては、型に加えてシーケンス番号を指定する必要があります。以下に例を示し
ます。
83
Amazon Kinesis Streams 開発者ガイド
API の使用
getShardIteratorRequest.setShardIteratorType("AT_SEQUENCE_NUMBER");
getShardIteratorRequest.setStartingSequenceNumber(specialSequenceNumber);
getRecords を使用してレコードを取得した後、レコードの getSequenceNumber メソッドを呼び
出すことで、レコードのシーケンス番号を取得できます。
record.getSequenceNumber()
さらに、データストリームにレコードを追加するコードでは、putRecord の結果に対して
getSequenceNumber を呼び出すことで、追加したレコードのシーケンス番号を取得できます。
lastSequenceNumber = putRecordResult.getSequenceNumber();
シーケンス番号を使用すると、レコードの順番が厳密に増えるようにできます。詳細については、
「PutRecord の例 (p. 54)」のサンプルコードを参照してください。
GetRecords を使用する
シャードイテレーターを取得した後、GetRecordsRequest オブジェクトをインスタンス化しま
す。setShardIterator メソッドを使用してリクエストのイテレーターを指定します。
必要に応じて、setLimit メソッドを使用して、取得するレコードの数を設定することもできま
す。getRecords によって返されるレコードの数は常にこの制限以下になります。この制限を指定し
ない場合、getRecords は取得したレコードの 10 MB を返します。次のサンプルコードでは、この制
限を 25 個のレコードに設定しています。
レコードが返されない場合、シャードイテレーターによって参照されたシーケンス番号では、この
シャードからどのデータレコードも現在使用できないことになります。この状況になった場合、ス
トリームのデータソースに対して、アプリケーションを適切な時間（少なくとも 1 秒間）待機状態
にする必要があります。次に、getRecords の前の呼び出しで返されたシャードイテレーターを
使用して、シャードからのデータの取得を再試行します。レコードがストリームに追加されてから
getRecords で使用できるまでに約 3 秒の遅延があることに注意してください。
getRecords メソッドに getRecordsRequest を渡し、 getRecordsResult オブジェクトとして返
された値をキャプチャします。データレコードを取得するには、getRecordsResult オブジェクト
の getRecords メソッドを呼び出します。
GetRecordsRequest getRecordsRequest = new GetRecordsRequest();
getRecordsRequest.setShardIterator(shardIterator);
getRecordsRequest.setLimit(25);
GetRecordsResult getRecordsResult = client.getRecords(getRecordsRequest);
List<Record> records = getRecordsResult.getRecords();
getRecords の別の呼び出しに備えて、getRecordsResult から次のシャードイテレーターを取得
します。
shardIterator = getRecordsResult.getNextShardIterator();
最良の結果を得るには、getRecords の呼び出し間の 1 秒（1,000 ミリ秒）以上はスリープ状態にし
て、getRecords の頻度制限を超えないようにしてください。
try {
84
Amazon Kinesis Streams 開発者ガイド
API の使用
Thread.sleep(1000);
}
catch (InterruptedException e) {}
一般的に、テストシナリオで 1 つのレコードを取得するときでも、getRecords はループ内で呼び
出す必要があります。getRecords の 1 回の呼び出しでは、後続のシーケンス番号でシャード内に
レコードがある場合でも、空のレコードのリストが返されることがあります。この状況になった場合
は、空のレコードのリストと共に返された NextShardIterator によってシャード内の後続のシーケ
ンス番号が参照されて、続く getRecords の呼び出しによって最終的にレコードが返されます。次の
サンプルでは、ループの使用を示しています。
例: getRecords
以下のコード例には、このセクションで示した getRecords のヒント（ループ内での呼び出しなど）
を反映しています。
// Continuously read data records from a shard
List<Record> records;
while (true) {
// Create a new getRecordsRequest with an existing shardIterator
// Set the maximum records to return to 25
GetRecordsRequest getRecordsRequest = new GetRecordsRequest();
getRecordsRequest.setShardIterator(shardIterator);
getRecordsRequest.setLimit(25);
GetRecordsResult result = client.getRecords(getRecordsRequest);
// Put the result into record list. The result can be empty.
records = result.getRecords();
try {
Thread.sleep(1000);
}
catch (InterruptedException exception) {
throw new RuntimeException(exception);
}
shardIterator = result.getNextShardIterator();
}
Amazon Kinesis Client Libraryを使用している場合は、データが返されるまで KCL によって複数回呼
び出しが行われることに注意してください。この動作は仕様であり、KCL やデータの問題を示すもの
ではありません。
リシャーディングに適応する
getRecordsResult.getNextShardIterator によって が返された場合、このシャードは分割また
は結合されて、現在 状態であり、使用可能なすべてのデータレコードはこのシャードから読み取り済
みということです。nullCLOSED
このシナリオでは、ストリーム内のシャードを再び列挙して、分割または結合によって作成された新
しいシャードを取得する必要があります。
分割の場合、2 つの新しいシャードの parentShardId はいずれも、前に処理されたシャードの ID に
一致します。これらのシャードの adjacentParentShardId の値はいずれも null です。
85
Amazon Kinesis Streams 開発者ガイド
トラブルシューティング
結合の場合、結合によって作成された 1 つの新しいシャードの parentShardId は、親のシャード
のいずれかの ID に一致し、adjacentParentShardId は、その他の親シャードの ID に一致しま
す。アプリケーションはこれらのいずれかのシャードからすべてのデータを読み取り済みです。これ
は、getRecordsResult.getNextShardIterator が null を返したシャードです。データの順序
がアプリケーションにとって重要である場合、結合によって作成された子シャードから新しいデータ
を読み取る前に、その他の親シャードからもすべてのデータを読み取るようにする必要があります。
複数のプロセッサを使用してストリームからデータを取得する場合、シャードごとに 1 つのプロセッ
サがあり、シャードの分割または結合を行うとすると、プロセッサの数を増やしたり減らしたりし
て、シャードの数の変化に適応する必要があります。
シャードの状態（CLOSED など）の説明を含むリシャーディングの詳細については、「ストリームを
リシャーディングする (p. 100)」を参照してください。
Amazon Kinesis Streams コンシューマーのトラブ
ルシューティング
以下のセクションでは、Amazon Kinesis Streams コンシューマーの操作中に発生する可能性がある一
般的な問題に対する解決策を示します。
• Kinesis クライアントライブラリの使用時に一部の Streams レコードがスキップされる (p. 86)
• 同じシャードに属するレコードが、異なるレコードプロセッサによって同時に処理され
る (p. 86)
• コンシューマーアプリケーションの読み取りの速度が予想よりも遅い (p. 87)
• ストリームにデータがある場合でも、GetRecords が空の Records 配列を返す (p. 87)
• シャードイテレータが予期せずに終了する (p. 88)
• コンシューマーレコードの処理が遅れる (p. 88)
Kinesis クライアントライブラリの使用時に一部の Streams レ
コードがスキップされる
レコードがスキップされる最も一般的な原因は、processRecords からスローされる処理されない
例外です。Amazon Kinesis Client Library (KCL) は、processRecords コードを使用して、データレ
コードの処理から発生するすべての例外を処理します。processRecords からスローされるすべて
の例外は、KCL によって吸収されます。反復的なエラーに対する無限再試行を回避するために、KCL
では例外の発生時に処理中であったレコードのバッチを再送信しません。KCL は、レコードプロセッ
サを再開することなく、データレコードの次のバッチについて processRecords を呼び出します。
これにより、事実上、コンシューマーアプリケーションではレコードがスキップされたことになりま
す。レコードのスキップを防止するには、processRecords 内ですべての例外を適切に処理します。
同じシャードに属するレコードが、異なるレコードプロセッサ
によって同時に処理される
実行されている Amazon Kinesis Client Library (KCL) アプリケーションでは、シャードの所有者はひ
とりだけです。ただし、複数のレコードプロセッサが一時的に同じシャードを処理する場合がありま
す。ネットワーク接続を紛失したワーカーインスタンスの場合、KCL はフェイルオーバー時間の期限
が切れた後に、到達できないワーカーはレコードを処理していないと仮定し、他のワーカーインスタ
ンスが引き継ぐように指示します。このとき短時間ですが、新しいレコードプロセッサと到達不可能
なワーカーのレコードプロセッサが同じシャードのデータを処理する場合があります。
アプリケーションに適したフェイルオーバー時間を設定する必要があります。低レイテンシーアプリ
ケーションの場合、10秒のデフォルトは、待機する最大時間を表している場合があります。ただし、
より頻繁に接続が失われる地域で通話を行うなどの接続問題が予想される場合、この数値は低すぎる
場合があります。
86
Amazon Kinesis Streams 開発者ガイド
トラブルシューティング
ネットワーク接続は通常、以前の到達不可能なワーカーに復元されるため、アプリケーションではこ
のシナリオを予期して処理する必要があります。レコードプロセッサのシャードが別のレコードプロ
セッサに引き継がれた場合、レコードプロセッサは正常なシャットダウンを実行するために次の 2 つ
のケースを処理する必要があります。
1. processRecords の現在の呼び出しが完了した後、KCL はシャットダウンの理由「ZOMBIE」を
使用してレコードプロセッサでシャットダウンメソッドを呼び出します。レコードプロセッサは、
すべてのリソースを必要に応じて適切にクリーンアップした後、終了する必要があります。
2. 「ゾンビ」ワーカーからチェックポイントを作成しようとすると、KCL は ShutdownException
をスローします。この例外を受け取った後、コードは現在のメソッドを正常に終了する必要があり
ます。
詳細については、「重複レコードの処理 (p. 92)」を参照してください。
コンシューマーアプリケーションの読み取りの速度が予想より
も遅い
読み取りのスループットが予想よりも遅くなる最も一般的な理由は次のとおりです。
1. 複数おコンシューマーアプリケーションの読み取りの合計が、シャードごとの制限を超えていま
す。詳細については、「Amazon Kinesis Streams の制限 (p. 7)」を参照してください。この場
合、Amazon Kinesis stream のシャードの数を増やします。
2. 呼び出しあたりの GetRecords の最大数を指定する リミットに低い値が設定されています。KCL を
使用している場合は、ワーカーに設定した maxRecords プロパティの値が低い可能性があります。
一般的に、このプロパティにはシステムのデフォルトを使用することをお勧めします。
3. processRecords 呼び出し内のロジックに予想よりも時間がかかる場合があります。これには、
ロジックが CPU を大量に消費する、I/O をブロックする、同期のボトルネックになっているなど、
多くの理由が考えられます。これに該当するかどうかをテストするには、空のレコードプロセッサ
をテスト実行し、読み取りスループットを比較します。受信データに遅れずに対応する方法につい
ては、「リシャーディング、拡張、並列処理 (p. 91)」を参照してください。
コンシューマーアプリケーションが 1 つのみである場合、通常、PUT レートの少なくとも 2 倍
高速に読み取りを実行できます。これは、書き込みについては最大 1 秒あたり 1,000 レコード、
データの最大書き込み合計レートは 1 秒あたり 1 MB (パーティションキーを含む) まで書き込む
ことができるためです。開いている各シャードは 読み取りは最大 1 秒あたり 5 件のトランザク
ション、データ読み取りの最大合計レートは 1 秒あたり 2 MB をサポートできます。各読み取り
(GetRecords) は、レコードのバッチを取得します。GetRecords によって返されるデータのサイズ
は、シャードの使用状況によって異なります。GetRecords が返すことができるデータの最大サイズ
は、10 MB です。呼び出しがその制限を返す場合、次の 5 秒以内に行われるそれ以降の呼び出しは
ProvisionedThroughputExceededException をスローします。
ストリームにデータがある場合でも、GetRecords が空の
Records 配列を返す
レコードの消費、つまり取得は、プルモデルです。開発者は、バックオフがない連続ループで
GetRecords を呼び出す必要があります。GetRecords のすべての呼び出しは、ShardIterator 値も
返します。この値は、ループの次のイテレーションで使用する必要があります。
GetRecords オペレーションはブロックしません。その代わりに、関連データレコードまたは空の
Records 要素とともに、直ちに制御を戻します。空の Records 要素は、2 つの条件の下で返されま
す。
1. 現在シャードにはそれ以上のデータがない。
2. シャードの ShardIterator で指定されたパートの近くにデータがない。
87
Amazon Kinesis Streams 開発者ガイド
トラブルシューティング
後者の条件は微妙ですが、レコードを取得するときに無限のシーク時間 (レイテンシー) を回避するた
めに必要な設計上のトレードオフです。そのため、ストリームを使用するアプリケーションはループ
し、GetRecords を呼び出して、当然のこととして空のレコードを処理します。
本稼働シナリオで、連続ループが終了するのは、NextShardIterator の値が NULL である場
合のみにする必要があります。NextShardIterator が NULL である場合、現在のシャードが閉
じられ、ShardIterator 値は最後のレコードを過ぎたことを示します。コンシューマーアプリ
ケーションが SplitShard または MergeShards を呼び出さない場合、シャードは開いたままにな
り、GetRecords の呼び出しは NextShardIterator である NULL 値を返しません。
Amazon Kinesis Client Library (KCL) を使用する場合、お客様に対しては前述の消費パターンは抽象化
されます。これには、動的に変更する一連のシャードの自動処理が含まれます。KCL により、開発者
は入力レコードを処理するロジックのみを提供します。ライブラリが自動的に GetRecords の継続的
な呼び出しを行うため、これが可能になります。
シャードイテレータが予期せずに終了する
新しいシャードのイテレーターは、GetRecords リクエスト (NextShardIterator として) によっ
て返されます。これは次の GetRecords リクエスト (ShardIterator として) で使用します。通常の
場合、このシャードイテレーターは使用する前に有効期限が切れることはありません。ただし、5 分
以上 を呼び出さなかったため、またはコンシューマーアプリケーションの再起動を実行したため、
シャードイテレーターの有効期限が切れる場合があります。
シャードイテレーターの有効期限がすぐに切れた場合、それを使用するには、これは Amazon Kinesis
によって使用されている DynamoDB テーブルに リースデータを格納するのに十分な容量がないこと
を示している可能性あります。この状況は、多数のシャードがある場合により発生する可能性が高
くなります。この問題を解決するには、シャードテーブルに割り当てられた書き込み容量を増やしま
す。詳細については、「Amazon Kinesis Streams Applicationの状態の追跡 (p. 89)」を参照してく
ださい。
コンシューマーレコードの処理が遅れる
ほとんどのユースケースで、コンシューマーアプリケーションはストリームから最新のデータの読み
取ります。特定の状況下では、コンシューマーの読み取りが遅れるという好ましくない事態が発生し
ます。コンシューマーの読み取りの遅れ具合を確認したら、遅れの最も一般的な理由を参照してくだ
さい。
GetRecords.IteratorAgeMilliseconds メトリックスを起動して、ストリーム内のすべての
シャードとコンシューマーの読み取り位置を追跡します。イテレータの経過日数が保持期間（デ
フォルトで 24 時間、最大で 7 日まで設定可能）の 50% を経過すると失効する場合、レコード
の有効期限切れによるデータ損失のリスクがあります。とりあえずの解決策は、保持期間を長
くすることです。これにより、問題のトラブルシューティングを行う間に重要なデータが失わ
れるのを防ぎます。詳細については、「Amazon CloudWatch による Amazon Kinesis Streams
サービスのモニタリング (p. 106)」を参照してください。次に、Amazon Kinesis Client Library
(KCL)、MillisBehindLatest が出力するカスタム CloudWatch メトリックスを使用して、コン
シューマーアプリケーションの読み取りが各シャードからどのくらい遅れているかを確認します。詳
細については、「Amazon CloudWatch による Amazon Kinesis クライアントライブラリのモニタリン
グ (p. 118)」を参照してください。
コンシューマーが遅れる最も一般的な理由:
• GetRecords.IteratorAgeMilliseconds の突然の上昇または MillisBehindLatest は、通常
ダウンストリームアプリケーションに対する API オペレーションの障害などの一時的な問題を示し
ます。どちらかのメトリックスが恒常的にこのような動きを示す場合、この急激な上昇を調査する
必要があります。
• これらのメトリックスが徐々に上昇する場合は、レコードの処理速度が不十分なためストリー
ムにコンシューマーが追いついていないことを示します。この状況に共通の原因は、物理リ
ソースの不足またはストリームスループットの上昇にレコード処理ロジックが追随できない
88
Amazon Kinesis Streams 開発者ガイド
高度なトピック
ことです。processTask、RecordProcessor.processRecords.Time、Success など
の、RecordsProcessed オペレーションに関連する KCL が出力する他のカスタム CloudWatch メ
トリックスを確認することで、この状況を調査できます。
• スループットの増加に伴う processRecords.Time メトリックスの上昇が確認された場合、レ
コード処理ロジックを分析して、スループットの増加に対応したスケーリングができない理由を
調べる必要があります。
• スループットの上昇とは関連性がない processRecords.Time 値の上昇が認められた場合は、
重要なパスでブロック呼び出しを行っていないか確認します。これは、レコード処理の低下を
招きます。代替策として、シャードの数を増やして並列処理を増やす方法があります。最後に、
ピーク需要時の基礎処理ノードで物理的リソース（メモリ、CPU 使用率など）の量が十分である
ことを確認します。
Amazon Kinesis Streams コンシューマーについて
の高度なトピック
このセクションでは、Amazon Kinesis Streams コンシューマーを最適化する方法について説明しま
す。
目次
• Amazon Kinesis Streams Applicationの状態の追跡 (p. 89)
• 低レイテンシー処理 (p. 90)
• Amazon Kinesis プロデューサライブラリ での AWS Lambda の使用 (p. 91)
• リシャーディング、拡張、並列処理 (p. 91)
• 重複レコードの処理 (p. 92)
• Amazon Kinesis Streams の障害からの復旧 (p. 94)
• 起動、シャットダウン、スロットリングの処理 (p. 95)
Amazon Kinesis Streams Applicationの状態の追跡
KCL は、各 Amazon Kinesis Streams applicationに対して、一意の Amazon DynamoDB テーブルを使
用してアプリケーションの状態を追跡します。KCL では、Amazon Kinesis Streams application名を使
用してテーブルの名前を作成するため、各アプリケーション名は一意である必要があります。
アプリケーションの実行中に、Amazon DynamoDB コンソールを使用してテーブルを表示できます。
アプリケーションの起動時に Amazon Kinesis Streams applicationの Amazon DynamoDB テーブルが
存在しない場合は、ワーカーの 1 つがテーブルを作成し、describeStream メソッドを呼び出して
テーブルの値を設定します。詳細については、「アプリケーション状態データ (p. 90)」を参照して
ください。
Important
アカウントには、Streams 自体に関連付けられているコストに加えて、DynamoDB テーブル
に関連付けられているコストが課金されます。
スループット
Amazon Kinesis Streams applicationでプロビジョニングされたスループットの例外が発生した場合
は、DynamoDB テーブルにプロビジョニングされたスループットを増やす必要があります。KCL が
テーブルを作成するときにプロビジョニングされるスループットは、1 秒あたりの読み込み 10 回、1
秒あたりの書き込み 10 回ですが、これがユーザーのアプリケーションで十分でない場合がありま
す。たとえば、Amazon Kinesis Streams applicationが頻繁にチェックポイントを作成する場合や、多
89
Amazon Kinesis Streams 開発者ガイド
高度なトピック
くのシャードで構成されるストリームを処理する場合は、より多くのスループットが必要になる可能
性があります。
DynamoDB でプロビジョニングされたスループットの詳細については、『Amazon DynamoDB 開発
者ガイド』の「Amazon DynamoDB でプロビジョニングされたスループット」と「テーブルの操作」
を参照してください。
アプリケーション状態データ
DynamoDB テーブルの各行は、アプリケーションによって処理中のシャードを表します。テーブルの
ハッシュキーはシャード ID です。
シャード ID に加えて、各行には次のデータが含まれます。
• チェックポイント: シャードの最新チェックポイントのシーケンス番号。この値はストリームのすべ
てのシャードで一意です。
• checkpointSubSequenceNumber: Kinesis プロデューサーライブラリの集約機能を使用するとき、
これは Amazon Kinesis レコード内の個別のユーザーレコードを追跡するチェックポイントに対す
る拡張となります。
• leaseCounter: ワーカーが他のワーカーの撮影を受けたことを検出できるように、リースのバージョ
ニングに使用されます。
• leaseKey: リースの固有識別子。各リースはストリームのシャードに固有のもので、一度に 1 つの
ワーカーで保持されます。
• leaseOwner: このリースを保持しているワーカー。
• ownerSwitchesSinceCheckpoint: 最後にチェックポイントが書き込まれてから、このリースワー
カーが何回変更されたかを示します。
• parentShardId: 子シャードの処理を開始する前に、親シャードが完全に処理されるようにするため
に使用します。これにより、レコードがストリームに入力されたのと同じ順序で処理されるように
なります。
低レイテンシー処理
伝達遅延は、レコードがストリームに書き込まれた瞬間からコンシューマーアプリケーションによっ
て読み取られるまでの、エンドツーエンドのレイテンシーとして定義されます。この遅延はいくつか
の要因によって異なりますが、最も大きく影響するのはコンシューマーアプリケーションのポーリン
グ間隔です。
ほとんどのアプリケーションについては、アプリケーションごとに各シャードを 1 秒に 1 回ポーリ
ングすることをお勧めします。この設定では、Amazon Kinesis Streams の制限（1 秒あたり 5 回の
GetRecords 呼び出し）を超えることなく、複数のコンシューマーアプリケーションで同時に 1 つの
ストリームを処理することができます。さらに、処理するデータバッチが大きくなると、アプリケー
ション内でネットワークおよび他の下流レイテンシーを効率的に短縮できる可能性が高くなります。
KCL のデフォルト値は、毎秒のポーリングのベストプラクティスに従うよう設定されています。この
デフォルト設定により、平均的な伝達遅延は通常、1 秒未満になります。
Streams レコードは、書き込まれた後、すぐに読み取り可能になります。このことを利用し、スト
リームが使用可能になったらすぐにストリームのデータ利用が必要になるユースケースもあります。
次の例に示されているように、KCL のデフォルト設定を上書きしてポーリングの頻度を高くすると、
伝達遅延を大幅に短縮できます。
Java KCL の設定コードを次に示します。
kinesisClientLibConfiguration = new
KinesisClientLibConfiguration(applicationName,
90
Amazon Kinesis Streams 開発者ガイド
高度なトピック
streamName,
credentialsProvider,
workerId).withInitialPositionInStream(initialPositionInStream).withIdleTimeBetweenReadsInMi
Python および Ruby KCL のプロパティファイル設定を次に示します。
idleTimeBetweenReadsInMillis = 250
Note
Streams には、シャードごとに GetRecords を呼び出す回数として 1 秒あたり 5 回という
上限があるため、idleTimeBetweenReadsInMillis プロパティを 200 ms 未満に設定する
と、アプリケーションで ProvisionedThroughputExceededException 例外が発生する可
能性があります。この例外の発生回数が多くなりすぎると、エクスポネンシャルバックオフ
につながり、予期しない大幅なレイテンシーが処理中に生じることが考えられます。このプ
ロパティを 200 ms または少し上に設定した場合も、複数の処理アプリケーションが実行され
ていれば、同様の調整が発生します。
Amazon Kinesis プロデューサライブラリ での AWS Lambda
の使用
Amazon Kinesis プロデューサライブラリ (KPL) は、ユーザーがフォーマットした小さなレコード
を最大 1 MB のレコードに集約して、Amazon Kinesis Streams スループットの使用を容易にしま
す。Java 用の KCL はこれらのレコードの集約解除をサポートしますが、ストリームのコンシュー
マーとして AWS Lambda を使用する場合は、特別なモジュールを使用してレコードを集約解除する
必要があります。「Amazon Kinesis プロデューサライブラリAWS Lambda の集約解除モジュール」
の GitHub から、必要なプロジェクトコードと指示を取得できます。このプロジェクトのコンポーネ
ントでは、Java、Node.js、および Python で、KPL のシリアル化されたデータを AWS Lambda 内で
処理することもできます。これらのコンポーネントは、複数言語 KCL アプリケーションの一部として
使用することもできます。
リシャーディング、拡張、並列処理
リシャーディングによって、ストリームのデータフロー率の変化に合わせて、ストリーム内のシャー
ドの数を増減することができます。リシャーディングは、通常、シャードのデータ処理メトリックス
を監視する管理アプリケーションによって実行されます。KCL 自体はリシャーディングオペレーショ
ンを開始しませんが、リシャーディングに起因するシャードの数の変化に適応するように設計されて
います。
「Amazon Kinesis Streams Applicationの状態の追跡 (p. 89)」に示されているように、KCL は
Amazon DynamoDB テーブルを使用してストリーム内のシャードを追跡します。リシャーディングの
結果として新しいシャードが作成されるときに、KCL は新しいシャードを検出し、テーブル内の新し
い行に値を入力します。ワーカーは、自動的に新しいシャードを検出し、シャードからのデータを処
理するためにプロセッサを作成します。また、KCL は、ストリーム内のシャードを、利用可能なすべ
てのワーカーとレコードプロセッサに分散させます。
KCL は、リシャーディング前にシャードに存在していたすべてのデータが最初に処理されるようにし
ます。このデータが処理された後、新しいシャードからのデータがレコードプロセッサに送信されま
す。このようにして、KCL は、データレコードが特定のパーティションキーのストリームに追加され
た順序を保持します。
例: リシャーディング、拡張、並列処理
次の例は、KCL を使用してスケーリングとリシャーディングを処理する方法を示しています。
91
Amazon Kinesis Streams 開発者ガイド
高度なトピック
• アプリケーションが 1 つの EC2 インスタンスで実行中であり、4 つのシャードを含む 1 つの
Amazon Kinesis stream を処理しているとします。この 1 つのインスタンスに 1 つの KCL ワーカー
と、4 つのレコードプロセッサ（各シャードに 1 つのレコードプロセッサ）があります。この 4 つ
のレコードプロセッサは、同一プロセス内で並列実行されます。
• 次に、別のインスタンスを使用するようにアプリケーションを拡張し、2 つのインスタンスで、4
つのシャードを含む 1 つのストリームを処理するとします。KCL ワーカーが 2 番目のインスタンス
で起動すると、最初のインスタンスとの間で負荷分散が行われ、各インスタンスで 2 つのシャード
が処理されるようになります。
• 次に、4 つのシャードを 5 つのシャードに分割するとします。KCL は再度インスタンスでの処理を
調整します。一方のインスタンスが 3 つのシャードを処理し、もう一方のインスタンスが 2 つの
シャードを処理するように調整されます。シャードをマージしたときにも、同様の調整が行われま
す。
通常、KCL を使用する場合、インスタンスの数がシャードの数を超過しないように注意します（障害
に対するスタンバイを目的とする場合を除く）。各シャードは厳密に 1 つの KCL ワーカーによって処
理され、対応するレコードプロセッサが厳密に 1 つ存在するため、1 つのシャードを処理するために
複数のインスタンスが必要になることはありません。ただし、1 つのワーカーで任意の数のシャード
を処理できるため、シャードの数がインスタンスの数を超過していても問題はありません。
アプリケーションでの処理を拡張するには、次のようなアプローチの組み合わせをテストする必要が
あります。
• インスタンスのサイズを拡張する（すべてのレコードプロセッサがプロセス内で並列実行されるた
め）
• 開くことができるシャードの最大数までインスタンスの数を増やす（シャードを個別に処理できる
ため）
• シャードの数を増やす（並列処理のレベルが向上する）
Auto Scaling を使用すると、適切なメトリックスに基づいて自動的にインスタンスを拡張できます。
詳細については、「Auto Scaling ユーザーガイド」を参照してください。
リシャーディングによってストリーム内のシャードの数が増加すると、対応するレコードプロセッ
サの数も増加し、これらをホストする EC2 インスタンスの負荷が増大します。このインスタンス
が Auto Scaling グループの一部であり、負荷の増加が十分である場合、増加した負荷を処理するた
めに Auto Scaling グループにインスタンスが追加されます。新しいインスタンスで追加のワーカー
やレコードプロセッサがすぐにアクティブになるように、インスタンスの起動時に Amazon Kinesis
Streams applicationを起動するように設定してください。
リシャーディングの詳細については、「ストリームをリシャーディングする (p. 100)」を参照してく
ださい。
重複レコードの処理
レコードが複数回 Amazon Kinesis Streams applicationに配信される理由は、主にプロデューサーの再
試行とコンシューマーの再試行の 2 つになります。アプリケーションは、各レコードの複数回処理を
予測して適切に処理する必要があります。
プロデューサーの再試行
PutRecord を呼び出した後で Amazon Kinesis Streams から受信確認を受け取る前までに、ネット
ワーク関連のタイムアウトを発生させるプロデューサーを検討してください。プロデューサーは、
レコードが Streams に配信されたかどうかを確認することができません。各レコードがアプリケー
ションにとって重要である場合、同じデータを使用して呼び出しを再試行するようにプロデューサー
を記述します。同じデータでの PutRecord の呼び出しが両方とも Streams に正常にコミットされ
ると、Streams レコードは 2 つになります。2 つのレコードには同一データが存在しますが、これら
92
Amazon Kinesis Streams 開発者ガイド
高度なトピック
には一意のシーケンス番号が付けられています。厳密な保証を必要とするアプリケーションは、後で
処理するときに重複を削除するようにレコード内にプライマリキーを埋め込む必要があります。プロ
デューサーの再試行に起因する重複の数が、コンシューマーの再試行に起因する重複の数より通常は
少ないことに注意してください。
Note
AWS SDK の PutRecord を使用すると、デフォルトの設定により、失敗した PutRecord の
呼び出しを 3 回まで再試行します。
コンシューマーの再試行
コンシューマー（データ処理アプリケーション）の再試行は、レコードプロセッサが再開するときに
発生します。同じシャードのレコードプロセッサは次の場合に再開します。
1. ワーカーが予期せず終了する
2. ワーカーのインスタンスが追加または削除される
3. シャードが結合または分割される
4. アプリケーションがデプロイされる
これらのすべての場合において、負荷分散処理に対するシャードとワーカーとレコードプロセッサの
マッピングは継続的に更新されます。他のインスタンスに移行されたシャードプロセッサは、最後の
チェックポイントからレコードの処理を再開します。これにより、次の例に示すように、重複レコー
ド処理が発生します。負荷分散の詳細については、「リシャーディング、拡張、並列処理 (p. 91)」
を参照してください。
例: コンシューマーの再試行によるレコードの再配信
この例では、ストリームから継続的にレコードを読み取り、ローカルファイルにレコードを集約し、
このファイルを Amazon S3 にアップロードするアプリケーションがあるとします。分かりやすいよ
うに、1 つのシャードとこのシャードを処理する 1 つのワーカーがあるとします。最後のチェックポ
イントがレコード番号 10000 であると仮定して、次の例の一連のイベントを考えてみます。
1. ワーカーで、シャードから次のレコードのバッチを読み込みます（10001 から 20000）。
2. 次にワーカーで、そのレコードのバッチを関連付けられたレコードプロセッサに渡します。
3. レコードプロセッサはデータを集約し、Amazon S3 ファイルを作成してこのファイルを Amazon
S3 に正常にアップロードします。
4. 新しいチェックポイントが発生する前にワーカーが予期せず終了します。
5. アプリケーション、ワーカー、およびレコードプロセッサが再開します。
6. ワーカーは、正常な最後のチェックポイント（この場合は 10001）から読み込みを開始しました。
したがって、10001 から 20000 のレコードは複数回使用されます。
コンシューマーの再試行に対する弾力性
レコードが複数回処理される可能性がある場合でも、アプリケーションは、レコードが 1 回だけ処理
されたかのように副作用を示すことがあります（べき等処理）。この問題に対するソリューションは
複雑さと正確性によって異なります。最終データの送信先が重複を適切に処理できる場合は、べき等
処理の実行に最終送信先を使用することをお勧めします。たとえば、Elasticsearch で、バージョニン
グと一意の ID の組み合わせを使用して重複処理を回避することができます。
前のセクションのサンプルアプリケーションでは、ストリームから継続的にレコードを読み取り、
ローカルファイルにレコードを集約し、このファイルを Amazon S3 にアップロードします。図に示
すように、10001 から 20000 のレコードが複数回使用されることにより、複数の Amazon S3 ファイ
93
Amazon Kinesis Streams 開発者ガイド
高度なトピック
ルのデータは同じになります。この例の重複を減らす方法の 1 つは、ステップ 3 で次のスキーマを使
用することです。
1. レコードプロセッサは、各 Amazon S3 ファイルに固定のレコード番号（5000 など）を使用しま
す。
2. ファイル名には、このスキーマ（Amazon S3、プレフィックス、シャード ID、および FirstSequence-Num）を使用します。この場合、sample-shard000001-10001 のようになります。
3. Amazon S3 ファイルをアップロードした後で、Last-Sequence-Num を指定してチェックポイン
トを作成します。この場合、レコード番号 15000 にチェックポイントが作成されます。
このスキーマを使用すると、レコードが複数回処理されても、Amazon S3 ファイルには同じ名前と
同じデータが保持されます。再試行によってのみ、同じファイルに同じデータが複数回書き込まれま
す。
リシャーディングオペレーションの場合、シャードに残っているレコードの数は必要な一定数より少
ないことがあります。この場合、shutdown() メソッドは Amazon S3 にファイルをフラッシュし、
最後のシーケンス番号でチェックポイントを作成する必要があります。前述のスキーマも、リシャー
ディングオペレーションと互換性があります。
Amazon Kinesis Streams の障害からの復旧
Amazon Kinesis Streams applicationを使用してストリームからのデータを処理するときに、次のレベ
ルで障害が発生する可能性があります。
• レコードプロセッサで障害が発生する
• ワーカーで障害が発生するか、そのワーカーをインスタンス化したこのアプリケーションのインス
タンスで障害が発生する
• アプリケーションの 1 つ以上のインスタンスをホストしている EC2 インスタンスで障害が発生する
レコードプロセッサの障害
ワーカーは、Java の ExecutorService タスクを使用してレコードプロセッサメソッドを呼び出しま
す。タスクが失敗した場合でも、ワーカーはレコードプロセッサが処理中であったシャードの制御を
保持しています。ワーカーは、このシャードを処理するために新しいレコードプロセッサタスクを開
始します。詳細については、「読み込みのスロットリング (p. 96)」を参照してください。
ワーカーまたはアプリケーションの障害
ワーカー、または Amazon Kinesis Streams applicationインスタンスに障害が発生した場合、状況を検
出して処理する必要があります。たとえば、Worker.run メソッドが例外をスローする場合、この例
外をキャッチして処理する必要があります。
アプリケーション自体に障害が発生した場合は、これを検出し、再起動する必要があります。アプリ
ケーションは、起動するときに新しいワーカーをインスタンス化します。このワーカーが新しいレ
コードプロセッサをインスタンス化すると、処理するシャードが自動的に割り当てられます。これら
は、障害が発生する前に、これらのレコード プロセッサが処理していたものと同じシャードにするこ
とも、これらのプロセッサで新しいシャードにすることもできます。
ワーカーやアプリケーションで障害が発生したが、この障害を検出しない場合、このアプリケーショ
ンの他のインスタンスが他の EC2 インスタンスで実行されているときには、これらのインスタンス上
のワーカーが障害を処理します。これらのインスタンスは、障害が発生したワーカーで処理されなく
なったシャードを処理するために、追加のレコードプロセッサを作成します。これにより、他の EC2
インスタンスの負荷は増加します。
ここで説明するシナリオでは、ワーカーやアプリケーションに障害が発生した場合でも、ホストして
いる EC2 インスタンスは実行されているため、Auto Scaling グループによって再起動されないことを
前提としています。
94
Amazon Kinesis Streams 開発者ガイド
高度なトピック
Amazon EC2 インスタンスの障害
アプリケーションの EC2 インスタンスを Auto Scaling グループで実行することをお勧めします。こ
のようにすることで、いずれかの EC2 インスタンスに障害が発生した場合でも、Auto Scaling グルー
プによって、自動的にそのインスタンスを置き換える新しいインスタンスが起動されます。起動時に
Amazon Kinesis Streams applicationを起動するようにこのインスタンスを設定する必要があります。
起動、シャットダウン、スロットリングの処理
ここでは、Amazon Kinesis Streams applicationの設計に取り入れる必要がある、追加の考慮事項を示
します。
目次
• データプロデューサとデータコンシューマーの起動 (p. 95)
• Amazon Kinesis Streams Applicationのシャットダウン (p. 95)
• 読み込みのスロットリング (p. 96)
データプロデューサとデータコンシューマーの起動
デフォルトでは、KCL はストリームの末尾（最後に追加されたレコード）からレコードの読み込みを
開始します。この設定では、受信側のレコードプロセッサが実行される前に、データプロデューサー
アプリケーションがストリームにレコードを追加した場合、レコードプロセッサが起動した後、これ
らのレコードはレコードプロセッサによって読み込まれません。
レコードプロセッサの動作を変更して、常にストリームの先頭からデータを読み込むには、Amazon
Kinesis Streams applicationの properties ファイルで次の値を設定します。
initialPositionInStream = TRIM_HORIZON
Amazon Kinesis Streams は、レコードを 24 ～ 168 時間保持します。この期間は保持期間と呼ば
れます。TRIM_HORIZON に起動ポジションを設定すると、保持期間で定義されているとおりに、ス
トリームの古いデータを使用してレコードプロセッサが起動します。TRIM_HORIZON 設定でも、レ
コードプロセッサが保持期間経過後に起動した場合は、ストリームのデータの一部が使用できなく
なります。そのため、ストリームから読み込むコンシューマーアプリケーションが常に存在してお
り、CloudWatch メトリックス GetRecords.IteratorAgeMilliseconds を使用して、アプリケー
ションが受信データに追随していることをモニタリングする必要があります。
シナリオによっては、レコードプロセッサでストリームの最初の数レコードが不足していても問題は
ない場合があります。たとえば、ストリームがエンドツーエンドで正常に機能していることをテスト
するために、ストリームに最初の数レコードを送信できます。この初期確認を行った後、ワーカーを
起動し、ストリームへの本稼働データの送信を開始します。
TRIM_HORIZON の設定の詳細については、「シャードイテレーターを使用する (p. 83)」を参照し
てください。
Amazon Kinesis Streams Applicationのシャットダウン
Amazon Kinesis Streams applicationが目的のタスクを完了したら、アプリケーションが実行されてい
る EC2 インスタンスを終了することによって、アプリケーションをシャットダウンする必要がありま
す。インスタンスを終了するには、AWS マネジメントコンソールまたは AWS CLI を使用します。
Amazon Kinesis Streams applicationをシャットダウンした後、KCL でアプリケーションの状態を追跡
するために使用した Amazon DynamoDB テーブルを削除する必要があります。
95
Amazon Kinesis Streams 開発者ガイド
ストリームの管理
読み込みのスロットリング
ストリームのスループットは、シャードレベルでプロビジョニングされます。各シャードの読み込み
スループットは 読み取りは最大 1 秒あたり 5 件のトランザクション、データ読み取りの最大合計レー
トは 1 秒あたり 2 MB です。アプリケーション（または同じストリームで動作するアプリケーション
のグループ）がシャードからデータをより高速に取得しようとすると、Streams は対応する GET オペ
レーションを調整します。
Amazon Kinesis Streams applicationでは、レコードプロセッサが制限よりも高速にデータを処理す
る場合（フェイルオーバーの場合など）に、スロットリングが発生します。Amazon Kinesis Client
Library (p. 66)によってアプリケーションと Streams との対話が管理されるため、スロットリング
例外は、アプリケーションコードではなく KCL コードで発生します。ただし、KCL によってこれら
の例外がログに記録されるため、ログで例外を確認できます。
アプリケーションのスロットリングが一貫して行われる場合は、ストリームのシャードの数を増やす
ことを検討してください。
Amazon Kinesis Stream の管理
次の例では、Amazon Kinesis Streams API について説明し、AWS SDK for Java を使用して Amazon
Kinesis stream を作成、削除、および操作する方法を示します。
この章で紹介する Java サンプルコードは、基本的な Streams API オペレーションを実行する方法を
示しており、オペレーションタイプ別に論理的に分割されています。これらのサンプルは、すべての
例外を確認しているわけではなく、すべてのセキュリティやパフォーマンスの側面を考慮しているわ
けでもない点で、本稼働環境に使用できるコードを表すものではありません。また、他のプログラミ
ング言語を使用して Streams API を呼び出すこともできます。利用可能なすべての AWS SDK の詳細
については、「アマゾン ウェブ サービスを使用した開発の開始」を参照してください。
トピック
• ストリームの作成 (p. 96)
• ストリームのリスト (p. 98)
• ストリームからシャードを取得する (p. 99)
• ストリームを削除する (p. 99)
• ストリームをリシャーディングする (p. 100)
• データ保持期間の変更 (p. 105)
ストリームの作成
次の手順に従って Amazon Kinesis stream を作成します 。
Streams クライアントを作成する
Amazon Kinesis stream を使用する前に、クライアントオブジェクトをインスタンス化する必要があ
ります。次の Java コードでは、Streams クライアントを作成し、クライアントのエンドポイント情
報を設定します。setEndpoint のこのオーバーロードには、サービス名とリージョンも含まれてい
ます。serviceName を kinesis に設定します。
client = new AmazonKinesisClient();
client.setEndpoint(endpoint, serviceName, regionId);
96
Amazon Kinesis Streams 開発者ガイド
ストリームの作成
詳細については、『AWS General Reference』の「Streams のリージョンとエンドポイント」を参照
してください。
ストリームを作成する
Streams クライアントを作成したら、使用するストリームを作成できます。この作業は、Streams コ
ンソールを使用して行うか、プログラムによって実行することができます。プログラムでストリーム
を作成するには、CreateStreamRequest オブジェクトをインスタンス化し、ストリームの名前とス
トリームが使用するシャードの数を指定します。
CreateStreamRequest createStreamRequest = new CreateStreamRequest();
createStreamRequest.setStreamName( myStreamName );
createStreamRequest.setShardCount( myStreamSize );
ストリーム名はストリームを識別するために使用されます。この名前のスコープは、アプリケーショ
ンが使用する AWS アカウントに限定されます。また、リージョンにも限定されます。つまり、2 つ
の異なる AWS アカウント内の 2 つのストリームを同じ名前にすることができ、同じ AWS アカウン
トで 2 つの異なるリージョン内の 2 つのストリームを同じ名前にすることができますが、同じアカウ
ントで、同じリージョン内の 2 つのストリームを同じ名前にすることはできません。
ストリームのスループットはシャードの数によって決まります。プロビジョンドスループットを高く
するほど、必要になるシャードの数は増えます。シャードが増えると、ストリームに対して請求さ
れる AWS のコストも増えます。アプリケーションに適切なシャードの数の計算の詳細については、
「Amazon Kinesis Stream の初期サイズを決定する (p. 5)」を参照してください。
createStreamRequest オブジェクトを設定した後、クライアントの createStream メソッドを呼
び出すことで、ストリームを作成します。createStream の呼び出し後、ストリームに対してさらに
オペレーションを実行するには、ストリームが ACTIVE 状態になるまで待機します。ストリームの状
態を確認するには、describeStream メソッドを呼び出します。ただし、ストリームが存在しない場
合、describeStream は例外をスローします。そのために、describeStream の呼び出しは try/
catch ブロックで囲みます。
client.createStream( createStreamRequest );
DescribeStreamRequest describeStreamRequest = new DescribeStreamRequest();
describeStreamRequest.setStreamName( myStreamName );
long startTime = System.currentTimeMillis();
long endTime = startTime + ( 10 * 60 * 1000 );
while ( System.currentTimeMillis() < endTime ) {
try {
Thread.sleep(20 * 1000);
}
catch ( Exception e ) {}
try {
DescribeStreamResult describeStreamResponse =
client.describeStream( describeStreamRequest );
String streamStatus =
describeStreamResponse.getStreamDescription().getStreamStatus();
if ( streamStatus.equals( "ACTIVE" ) ) {
break;
}
//
// sleep for one second
//
try {
Thread.sleep( 1000 );
97
Amazon Kinesis Streams 開発者ガイド
ストリームのリスト
}
catch ( Exception e ) {}
}
catch ( ResourceNotFoundException e ) {}
}
if ( System.currentTimeMillis() >= endTime ) {
throw new RuntimeException( "Stream " + myStreamName + " never went
active" );
}
ストリームのリスト
前のセクションで説明したように、ストリームのスコープは、Streams クライアントのインスタンス
化に使用される AWS の認証情報に関連付けられた AWS アカウントに限定されます。また、このク
ライアントに指定されたリージョンにも限定されます。AWS アカウントを使用して多数のストリー
ムを 1 度にアクティブにできます。ストリームは、Streams コンソールでリストするか、プログラム
によってリストすることができます。このセクションのコードでは、AWS アカウントのすべてのスト
リームをリスト表示する方法を示します。
ListStreamsRequest listStreamsRequest = new ListStreamsRequest();
listStreamsRequest.setLimit(20);
ListStreamsResult listStreamsResult = client.listStreams(listStreamsRequest);
List<String> streamNames = listStreamsResult.getStreamNames();
このコード例では、最初に ListStreamsRequest の新しいインスタンスを作成し、その setLimit
メソッドを呼び出して、最大 20 個のストリームが listStreams の呼び出しごとに返される
ように指定しています。setLimit の値を指定しない場合は、アカウントにあるストリームの
数と同じかそれよりも少ないストリームの数が Streams によって返されます。次に、コードは
クライアントの listStreams メソッドに listStreamsRequest を渡します。listStreams
の戻り値は ListStreamsResult オブジェクトに格納されます。コードはこのオブジェクトの
getStreamNames メソッドを呼び出して、返されたストリームの名前を streamNames リストに
格納します。アカウントとリージョンにこの制限で指定したよりも多くのストリームがある場合で
も、Streams によって返されるストリームの数が指定した制限に満たないことがあります。確実にす
べてのストリームを取得するには、次のコード例で説明している getHasMoreStreams メソッドを使
用します。
while (listStreamsResult.getHasMoreStreams())
{
if (streamNames.size() > 0) {
listStreamsRequest.setExclusiveStartStreamName(streamNames.get(streamNames.size()
- 1));
}
listStreamsResult = client.listStreams(listStreamsRequest);
streamNames.addAll(listStreamsResult.getStreamNames());
}
このコードは、listStreamsRequest の getHasMoreStreams メソッドを呼び出し
て、listStreams の最初の呼び出しで返されたストリームの数よりも多いストリームがあ
るかどうかを確認します。ある場合、コードは setExclusiveStartStreamName メソッド
を呼び出して、listStreams の前の呼び出しで返された最後のストリームの名前を指定しま
す。setExclusiveStartStreamName メソッドは listStreams の次の呼び出しをそのストリーム
の後から開始します。その呼び出しによって返されたストリーム名のグループが streamNames リス
トに追加されます。すべてのストリームの名前がリストに収集されるまで、この処理を続行します。
listStreams で返されるストリームは以下のいずれかの状態になります。
98
Amazon Kinesis Streams 開発者ガイド
ストリームからシャードを取得する
• CREATING
• ACTIVE
• UPDATING
• DELETING
前の「ストリームの作成 (p. 96)」で示した describeStream メソッドを使用して、ストリームの
状態を確認できます。
ストリームからシャードを取得する
describeStream メソッドによって返された応答オブジェクトを使用すると、ストリームを構成する
シャードについて情報を取得できます。シャードを取得するには、このオブジェクトの getShards
メソッドを呼び出します。このメソッドは、1 回の呼び出しでストリームからすべてのシャードを返
すとは限りません。以下のコードでは、getStreamDescription の getHasMoreShards メソッド
を使用して、返されなかったシャードがあるかどうかを確認しています。ある場合、つまり、このメ
ソッドが true を返した場合は、ループ内で getShards の呼び出しを繰り返して、返されたシャー
ドの新しいバッチをシャードのリストに追加していきます。getHasMoreShards が false を返した
場合は、ループが終了します。つまり、すべてのシャードが返されたことになります。getShards は
状態のシャードを返さないことに注意してください。EXPIREDシャードの状態（EXPIRED 状態など）
の詳細については、「リシャーディング後のデータのルーティング、データの永続化、シャードの状
態 (p. 104)」を参照してください。
DescribeStreamRequest describeStreamRequest = new DescribeStreamRequest();
describeStreamRequest.setStreamName( myStreamName );
List<Shard> shards = new ArrayList<>();
String exclusiveStartShardId = null;
do {
describeStreamRequest.setExclusiveStartShardId( exclusiveStartShardId );
DescribeStreamResult describeStreamResult =
client.describeStream( describeStreamRequest );
shards.addAll( describeStreamResult.getStreamDescription().getShards() );
if (describeStreamResult.getStreamDescription().getHasMoreShards() &&
shards.size() > 0) {
exclusiveStartShardId = shards.get(shards.size() - 1).getShardId();
} else {
exclusiveStartShardId = null;
}
} while ( exclusiveStartShardId != null );
ストリームを削除する
ストリームは、Streams コンソールで削除するか、プログラムによって削除することができます。ス
トリームをプログラムで削除するには、次のコードに示されているように DeleteStreamRequest
を使用します。
DeleteStreamRequest deleteStreamRequest = new DeleteStreamRequest();
deleteStreamRequest.setStreamName(myStreamName);
client.deleteStream(deleteStreamRequest);
ストリームを削除する前に、そのストリームとやり取りしているアプリケーションをすべてシャッ
トダウンする必要があります。削除したストリームとアプリケーションがやり取りしようとする
と、ResourceNotFound 例外を受け取ります。また、削除した前のストリームと同じ名前の新しい
ストリームを作成した場合、前のストリームとやり取りしていたアプリケーションがまだ実行されて
99
Amazon Kinesis Streams 開発者ガイド
ストリームをリシャーディングする
いると、それらのアプリケーションが前のストリームであるかのように新しいストリームとやり取り
しようとして、予期しない動作につながることがあります。
ストリームをリシャーディングする
Streams ではリシャーディングがサポートされています。リシャーディングにより、ストリーム内の
シャードの数を調整して、ストリームのデータフロー率の変化に適応できます。リシャーディングは
高度なオペレーションと見なされます。Streams を初めて使用する場合は、Streams の他のあらゆる
機能を使い慣れてから、このトピックをお読みください。
リシャーディングには、シャードの分割と結合という 2 種類のオペレーションがあります。シャー
ドの分割では、1 つのシャードを 2 つシャードに分けます。シャードの結合では、2 つシャードを 1
つのシャードに組み合わせます。リシャーディングは、1 回のオペレーションで複数のシャードに
分割できなければ、1 回のオペレーションで複数のシャードを結合できないという意味で、常に「ペ
アワイズ」です。リシャーディングオペレーションの実行対象となるシャードまたはシャードペア
は、親シャードと呼ばれます。リシャーディングオペレーションの実行結果となるシャードまたは
シャードペアは、子シャードと呼ばれます。
分割によりストリーム内のシャードの数が増え、したがってストリームのデータ容量は増えます。
シャード単位で請求されるため、分割によりストリームのコストが増えます。同様に、統合によりス
トリーム内のシャードの数は減り、したがってストリームのデータ容量（コスト）は減ります。
リシャーディングは、通常、プロデューサー（入力）アプリケーションやコンシューマー（取得）
アプリケーションとは別の管理アプリケーションによって実行されます。管理アプリケーション
は、CloudWatch が提供するメトリックに基づいて、またはプロデューサーとコンシューマーから収
集されたメトリックに基づいて、ストリームの全体的なパフォーマンスを監視します。管理アプリ
ケーションには、コンシューマーまたはプロデューサーよりも広範な IAM アクセス権限も必要にな
ります。コンシューマーとプロデューサーは通常、リシャーディングに使用される API にアクセス
する必要がないためです。Streams の IAM アクセス許可の詳細については、「IAM により Amazon
Kinesis Streams リソースへのアクセスを制御する (p. 133)」を参照してください。
トピック
• リシャーディングのための戦略 (p. 100)
• シャードの分割 (p. 101)
• 2 つのシャードを結合する (p. 102)
• リシャーディング後 (p. 103)
リシャーディングのための戦略
リシャーディングの目的は、ストリームをデータの流量の変化に適応させることです。シャードを分
割すると、ストリームの容量（およびコスト）が増えます。シャードを結合すると、ストリームのコ
スト（および容量）が減ります。
リシャーディングへの 1 つのアプローチとして考えられるのは、単にストリーム内のすべてのシャー
ドを分割することです。これにより、ストリームの容量は倍増します。ただし、実際に必要になるよ
りも多くの容量が追加されるため、不要なコストが生じる可能性があります。
メトリックを使用して、シャードが「ホット」であるか「コールド」であるか、つまり、想定より過
多なデータを受け取っているか、過少なデータを受け取っているかを判断できます。ホットシャー
ドは分割して、それらのハッシュキーに対応した容量を増やすことができます。同様に、コールド
シャードは結合して、未使用の容量をより有効に活用できます。
Streams が発行する CloudWatch メトリックスから、ストリームについてパフォーマンスデータを取
得できます。ただし、ストリームについて独自のメトリックを収集することもできます。1 つのアプ
ローチとして考えられるのは、データレコードのパーティションキーによって生成されたハッシュ
100
Amazon Kinesis Streams 開発者ガイド
ストリームをリシャーディングする
キー値をログに記録することです。ストリームにレコードを追加するときにパーティションキーを指
定していることを思い出してください。
putRecordRequest.setPartitionKey( String.format( "myPartitionKey" ) );
Streams では、MD5 を使用してパーティションキーからハッシュキーを計算します。レコードのパー
ティションキーを指定しているため、MD5 を使用してそのレコードのハッシュキー値を計算し、ログ
に記録できます。
また、データレコードが割り当てられているシャードの ID をログに記録することもできます。
シャード ID は、putRecords メソッドによって返される putRecordResults オブジェクトおよび
putRecord メソッドによって返される putRecordResult オブジェクトの getShardId メソッドを
使用することによって利用できます。
String shardId = putRecordResult.getShardId();
シャード ID とハッシュキー値を使用すると、最も多いまたは少ないトラフィックを受け取っている
シャードとハッシュキーを特定できます。その後、リシャーディングによりこれらのハッシュキーに
対応した容量を増やすか減らすことができます。
シャードの分割
シャードを分割するには、親シャードのハッシュキー値を子シャードに再配分する方法を指定する
必要があります。データレコードをストリームに追加すると、レコードはハッシュキー値に基づい
てシャードに割り当てられます。ハッシュキー値は、ストリームにデータレコードを追加するとき
にデータレコードに指定するパーティションキーの MD5 ハッシュです。パーティションキーが同じ
データレコードはハッシュキー値も同じです。
指定したシャードに使用可能なハッシュキー値は、順序付けられた連続する正の整数で構成されま
す。ハッシュキーの一連の値は以下の式により得られます。
shard.getHashKeyRange().getStartingHashKey();
shard.getHashKeyRange().getEndingHashKey();
シャードを分割するときは、この一連の値を指定します。そのハッシュキー値とそれより上位のす
べてのハッシュキー値は、いずれかの子シャードの配分されます。それより下位のすべてのハッシュ
キー値は、その他の子のシャードに配分されます。
以下のコードでは、子シャード間でハッシュキーを均等に再配分し、親シャードを半分に分割する基
本的なシャード分割オペレーションを示します。これは、親シャードを分割する方法の 1 つに過ぎま
せん。たとえば、親シャードの下位 1/3 のキーを 1 つの子シャードに配分し、上位 2/3 のキーをその
他の子シャードに配分して、シャードを分割することもできます。ただし、多くアプリケーションに
効果的なのは、シャードを半分に分割することです。
以下のコードでは、myStreamName にストリームの名前が格納され、オブジェクト変数 shard に分
割するシャードが格納されるとします。新しい splitShardRequest オブジェクトをインスタンス化
し、ストリーム名とシャード ID を設定することから始めます。
SplitShardRequest splitShardRequest = new SplitShardRequest();
splitShardRequest.setStreamName(myStreamName);
splitShardRequest.setShardToSplit(shard.getShardId());
シャード内の最小値と最大値の中間にあるハッシュキー値を決定します。これは、子シャード
の開始ハッシュキー値になり、親シャードのハッシュキーの上位半分が含まれます。この値を
101
Amazon Kinesis Streams 開発者ガイド
ストリームをリシャーディングする
setNewStartingHashKey メソッドで指定します。指定する必要があるのはこの値のみです。この値
より下位のハッシュキーは、分割によって作成されたその他の子シャードに、Streams によって自動
的に配分されます。最後に、Streams クライアントの splitShard メソッドを呼び出します。
BigInteger startingHashKey = new
BigInteger(shard.getHashKeyRange().getStartingHashKey());
BigInteger endingHashKey
= new
BigInteger(shard.getHashKeyRange().getEndingHashKey());
String newStartingHashKey = startingHashKey.add(endingHashKey).divide(new
BigInteger("2")).toString();
splitShardRequest.setNewStartingHashKey(newStartingHashKey);
client.splitShard(splitShardRequest);
この方法の後の最初の手順は、「ストリームが再度アクティブになるまで待機する (p. 103)」に示さ
れています。
2 つのシャードを結合する
シャードの結合オペレーションは、指定した 2 つのシャードを取得し、1 つシャードに組み合わせま
す。結合後、1 つの子シャードは 2 つの親シャードのすべてのハッシュキー値のデータを受け取りま
す。
シャードの隣接
2 つシャードを結合するには、シャードが隣接している必要があります。2 つシャードのハッシュ
キー範囲が途切れておらず連続している場合、2 つのシャードは隣接していると考えられます。たと
えば 2 つシャードがあり、一方のハッシュキー範囲が 276 ～ 381、もう一方のハッシュキー範囲が
382 ～ 454 である場合、これら 2 つシャードを、ハッシュキー範囲が 276 ～ 454 の 1 つのシャード
に結合できます。
別の例を考えてみます。2 つシャードがあり、一方のハッシュキー範囲が 276 ～ 381、もう一方の
ハッシュキー範囲が 455 ～ 560 である場合、これらの 2 つのシャードは結合できません。2 つのハッ
シュキー範囲の間 382 ～ 454 に 1 つ以上のシャードがあるためです。
ストリーム内で OPEN 状態にある一連のシャードはすべて、グループとして、常に MD5 ハッシュキー
値の全範囲にまたがります。シャードの状態（CLOSED など）の詳細については、「リシャーディン
グ後のデータのルーティング、データの永続化、シャードの状態 (p. 104)」を参照してください。
結合候補になるシャードを特定するには、CLOSED 状態にあるすべてのシャードを除外する必要があ
ります。OPEN 状態のシャード（CLOSED 状態でないシャード）の終了シーケンス番号は null です。
以下のコードを使用してシャードの終了シーケンス番号をテストできます。
if( null == shard.getSequenceNumberRange().getEndingSequenceNumber() )
{
// Shard is OPEN, so it is a possible candidate to be merged.
}
CLOSED 状態のシャードを除外した後、各シャードでサポートされている最大ハッシュキー値で、残
りのシャードを並べ替えます。以下のコード使用してこの値を取得できます。
shard.getHashKeyRange().getEndingHashKey();
このフィルタリングして並び替えたリストで 2 つシャードが隣接している場合、それらのシャードは
結合できます。
102
Amazon Kinesis Streams 開発者ガイド
ストリームをリシャーディングする
結合オペレーションのコード
以下のコードでは、2 つシャードを結合しています。myStreamName には、ストリームの名前が格納
され、オブジェクト変数 shard1 と shard2 には、結合する 2 つの隣接するシャードが格納されると
します。
結合オペレーションの場合、新しい mergeShardsRequest オブジェクトをインスタンス化すること
から始めます。setStreamName メソッドでストリーム名を指定します。次に、setShardToMerge
と setAdjacentShardToMerge のメソッドを使用して、結合する 2 つのシャードを指定します。最
後に、Streams クライアントの mergeShards メソッドを呼び出して、このオペレーションを実行し
ます。
MergeShardsRequest mergeShardsRequest = new MergeShardsRequest();
mergeShardsRequest.setStreamName(myStreamName);
mergeShardsRequest.setShardToMerge(shard1.getShardId());
mergeShardsRequest.setAdjacentShardToMerge(shard2.getShardId());
client.mergeShards(mergeShardsRequest);
この方法の後の最初の手順は、「ストリームが再度アクティブになるまで待機する (p. 103)」に示さ
れています。
リシャーディング後
リシャーディングの手順が終了した後、通常のレコード処理を再開する前に、その他の手順および考
慮が必要になります。以下のセクションでは、これらについて説明します。
トピック
• ストリームが再度アクティブになるまで待機する (p. 103)
• リシャーディング後のデータのルーティング、データの永続化、シャードの状態 (p. 104)
ストリームが再度アクティブになるまで待機する
リシャーディングオペレーションとして splitShard または mergeShards のいずれかを呼び出した
後、ストリームが再びアクティブになるまで待機する必要があります。使用するコードは、ストリー
ムの作成 (p. 96)後にストリームがアクティブになるまで待機する場合のものと同じです。以下にそ
のコードを再び示します。
DescribeStreamRequest describeStreamRequest = new DescribeStreamRequest();
describeStreamRequest.setStreamName( myStreamName );
long startTime = System.currentTimeMillis();
long endTime = startTime + ( 10 * 60 * 1000 );
while ( System.currentTimeMillis() < endTime )
{
try {
Thread.sleep(20 * 1000);
}
catch ( Exception e ) {}
try {
DescribeStreamResult describeStreamResponse =
client.describeStream( describeStreamRequest );
String streamStatus =
describeStreamResponse.getStreamDescription().getStreamStatus();
if ( streamStatus.equals( "ACTIVE" ) ) {
break;
103
Amazon Kinesis Streams 開発者ガイド
ストリームをリシャーディングする
}
//
// sleep for one second
//
try {
Thread.sleep( 1000 );
}
catch ( Exception e ) {}
}
catch ( ResourceNotFoundException e ) {}
}
if ( System.currentTimeMillis() >= endTime )
{
throw new RuntimeException( "Stream " + myStreamName + " never went
active" );
}
リシャーディング後のデータのルーティング、データの永続化、シャードの状
態
Streams はリアルタイムのデータストリーミングサービスです。つまりアプリケーションでは、デー
タがストリーム内のシャードに連続的に流れていることが前提になります。リシャーディングする
と、親シャードに流れていたデータレコードは、データレコードのパーティションキーがマッピン
グされるハッシュキー値に基づいて、子シャードに流れるように再ルーティングされます。ただし、
リシャーディング前に親シャードにあったデータレコードはすべて、それらのシャードに残ります。
すなわち、リシャーディング後に親シャードが失われることはありません。それらのシャードはリ
シャーディング前に格納されていたデータと共に保持されます。親シャード内のデータレコードに
は、Streams API の getShardIterator と getRecords (p. 82) のオペレーションを使用する
か、Amazon Kinesis Client Libraryを使用してアクセスできます。
Note
データレコードは、現在の保持期間にストリームを追加した時間からアクセスできます。こ
れは、その期間内のストリームのシャードの変更に関係なく当てはまります。ストリームの
保持期間の詳細については、「データ保持期間の変更 (p. 105)」を参照してください。
リシャーディングの過程で、親シャードは OPEN 状態から CLOSED 状態に、さらに EXPIRED 状態へと
移行します。
• OPEN: リシャーディングオペレーションの前、親シャードは OPEN 状態にあります。つまり、デー
タレコードはシャードへの追加とシャードからの取得のいずれも可能です。
• CLOSED: リシャーディングオペレーションの後、親シャードは CLOSED 状態に移行します。つま
り、データレコードはシャードに追加されなくなります。このシャードに追加されることになって
いたデータレコードは、子シャードに追加されるようになります。ただし、データレコードは引き
続き、制限された時間内にシャードから取得できます。
• 期限切れ: ストリーム保持期間の有効期限が切れたら、親シャードのすべてのデータレコードの期
限も切れてアクセスできなくなります。この時点で、シャード自体は EXPIRED 状態に移行しま
す。getStreamDescription().getShards を呼び出してストリーム内のシャードを列挙して
も、返されるシャードのリストには 状態のシャードは含まれません。EXPIREDストリームの保持期
間の詳細については、「データ保持期間の変更 (p. 105)」を参照してください。
リシャーディング後、ストリームが再び ACTIVE 状態になるとすぐに、子シャードからのデー
タの読み取りを開始できます。ただし、リシャーディング後に残った親シャードには依然とし
て、リシャーディング前にストリームに追加されてまだ読み取られていないデータが格納されて
いる可能性があります。親シャードからすべてのデータを読み取る前に、子シャードからデータ
を読み取った場合は、特定のハッシュキーが原因で、読み取ったデータがデータレコードのシー
104
Amazon Kinesis Streams 開発者ガイド
データ保持期間の変更
ケンス番号に基づいた順序に並ばない可能性があります。したがって、データの順序が重要な場
合は、リシャーディング後に親シャードからのデータを読み取りを、そのデータを使い切るまで
続行する必要があります。その後でのみ、子シャードからのデータの読み取りを開始してくださ
い。getRecordsResult.getNextShardIterator が を返した場合は、親シャード内のすべての
データを読み取ったということです。nullAmazon Kinesis Client Libraryを使用してデータを読み取
る場合は、リシャーディング後でも正しい順序でデータを受け取ることができます。
データ保持期間の変更
Streams は、ストリームのデータレコードの保持期間の変更をサポートしています。Amazon Kinesis
stream はデータレコードの順序付けられたシーケンスで、リアルタイムで書き込みと読み取りができ
ることが前提となっています。したがって、データレコードはシャードに一時的に保存されます。レ
コードが追加されてからアクセスできなくなるまでの期間は、保持期間と呼ばれます。デフォルトで
Amazon Kinesis stream は 24 時間レコードを保持し、最大値は 168 時間です。
IncreaseStreamRetentionPeriod オペレーションを使用して保持期間を最大 168 時間まで増やした
り、DecreaseStreamRetentionPeriod オペレーションを使用して最短の 24 時間に短縮したりできま
す。両方のオペレーションに対するリクエスト構文には、時間にストリーム名と保存期間が含まれま
す。最後に、DescribeStream オペレーションを呼び出すことで、ストリームの現在の保持期間を確認
できます。
オペレーションはどちらも操作が簡単です。保持期間を変更する例を、以下の AWS CLI （リンク）
に示します。
aws kinesis increase-stream-retention-period --stream-name
retentionPeriodDemo --retention-period-hours 72
Streams は、数分間延長した保持期間内で古い保持期間のアクセス停止を解除することができます。
たとえば、保持期間を 24 時間から 48 時間に変更すると、23 時間 55 分前にストリームに追加された
レコードは、さらに 24 時間が経過するまで使用可能になります。
Streams は、保持期間が短縮されると、新しい保持期間よりも古いレコードをほぼ即座にアクセス不
能にします。したがって、DecreaseStreamRetentionPeriod オペレーションを呼び出すときは、細心
の注意が必要です。
問題が発生した場合は、期限が切れる前にデータを読めるように、保持期間を設定しておく必要があ
ります。レコード処理ロジックの問題または長期間にわたるダウンストリームの依存関係など、あら
ゆる可能性を慎重に検討してください。保持期間は、安全策としてデータ回復のための余裕期間を見
込んでください。保持期間 API オペレーションでは、この期間を事前に設定したり、オペレーション
イベントにリアクティブに対応したりできます。
追加料金は 24 時間を超えて保持されたストリームに適用されます。詳細については、「Amazon
Kinesis Streams 料金表」を参照してください。
Amazon Kinesis Streams のモニタリング
次の機能を使用して Amazon Kinesis Streams をモニタリングできます。
• CloudWatch メトリックス (p. 106) – Streams は、Amazon CloudWatch に各ストリームの詳細モ
ニタリングのカスタムメトリックスを送信します。
• Amazon Kinesis エージェント (p. 114) ‐ Amazon Kinesis エージェントは、エージェントが期待ど
おりに動作している場合に、カスタム CloudWatch メトリックスを発行します。
• API ログ作成 (p. 114) – Streams は AWS CloudTrail を使用して API 呼び出しをログに記録し、そ
のデータを Amazon S3 バケットに保存します。
105
Amazon Kinesis Streams 開発者ガイド
CloudWatch によるサービスのモニタリング
• Amazon Kinesis クライアントライブラリ (p. 118) — Streams クライアントライブラリ (KCL)
は、シャード、ワーカー、および KCL アプリケーションあたりのメトリックスを提供します。
• Amazon Kinesis プロデューサーライブラリ (p. 126) — Streams プロデューサーライブラリ (KPL)
は、シャード、ワーカー、および KPL アプリケーションあたりのメトリックスを提供します。
Amazon CloudWatch による Amazon Kinesis
Streams サービスのモニタリング
Amazon Kinesis Streams と Amazon CloudWatch は統合されているため、Amazon Kinesis stream
の CloudWatch メトリックスを収集、表示、分析できます。たとえば、シャードの使用状況の追跡
に、PutRecords.Bytes メトリックスと GetRecords.Bytes メトリックスをモニタリングし、スト
リーム内のシャードの数と比較できます。
ストリーム用に設定するメトリックスは、自動的に収集され、1 分おきに CloudWatch にプッシュさ
れます。2 週間分のメトリックスがアーカイブされ、その期間が経過したデータは破棄されます。
次の表は、Amazon Kinesis の基本的なストリームレベルと拡張シャードレベルのモニタリングについ
て説明しています。
型
説明
基本 (ストリームレベル)
ストリームレベルデータは自動的に 1 分間無料
で取得できます。
拡張 (シャードレベル)
1分間のシャードレベルデータを取得できます。
追加料金がかかります。このレベルのデータを
取得するには、EnableEnhancedMonitoring 操作
を使用してストリームを明示的に有効にする必
要があります。
料金表の詳細については、Amazon CloudWatch
product page を参照してください。
トピック
• Amazon Kinesis Streams のディメンションおよびメトリックス (p. 106)
• Streams の Amazon CloudWatch メトリックスへのアクセス (p. 113)
Amazon Kinesis Streams のディメンションおよびメトリック
ス
Streams は、ストリームレベルとオプションのシャードレベルの 2 つのレベルでメトリックスを
CloudWatch に送信します。ストリームレベルのメトリックスは、通常の条件での最も一般的なモニ
タリングのユースケース用です。シャードレベルのメトリックスは、通常トラブルシューティングに
関連する特定のモニタリングタスクで、EnableEnhancedMonitoring 操作を使用して有効になります。
CloudWatch メトリックスから収集された統計の説明については、『Amazon CloudWatch 開発者ガイ
ド』の「CloudWatch の統計」を参照してください。
トピック
• Basic Stream-level Metrics (p. 107)
• Enhanced Shard-level Metrics (p. 110)
• Amazon Kinesis Streams メトリックスのディメンション (p. 112)
106
Amazon Kinesis Streams 開発者ガイド
CloudWatch によるサービスのモニタリング
• 推奨 Amazon Kinesis Streams メトリックス (p. 112)
Basic Stream-level Metrics
The AWS/Kinesis namespace includes the following stream-level metrics.
Streams sends these stream-level metrics to CloudWatch every minute. These metrics are always
available.
Metric
Description
GetRecords.Bytes
The number of bytes retrieved from the Amazon Kinesis stream, measured
over the specified time period. Minimum, Maximum, and Average statistics
represent the bytes in a single GetRecords operation for the stream in the
specified time period.
Shard-level metric name: OutgoingBytes
Dimensions: StreamName
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Bytes
GetRecords.IteratorAge
This metric is deprecated. Use
GetRecords.IteratorAgeMilliseconds.
GetRecords.IteratorAgeMilliseconds
The age of the last record in all GetRecords calls made against an
Amazon Kinesis stream, measured over the specified time period. Age is
the difference between the current time and when the last record of the
GetRecords call was written to the stream. The Minimum and Maximum
statistics can be used to track the progress of Amazon Kinesis consumer
applications. A value of zero indicates that the records being read are
completely caught up with the stream.
Shard-level metric name: IteratorAgeMilliseconds
Dimensions: StreamName
Statistics: Minimum, Maximum, Average, Samples
Units: Milliseconds
GetRecords.Latency The time taken per GetRecords operation, measured over the specified
time period.
Dimensions: StreamName
Statistics: Minimum, Maximum, Average
Units: Milliseconds
GetRecords.Records The number of records retrieved from the shard, measured over the
specified time period. Minimum, Maximum, and Average statistics
represent the records in a single GetRecords operation for the stream in
the specified time period.
Shard-level metric name: OutgoingRecords
Dimensions: StreamName
107
Amazon Kinesis Streams 開発者ガイド
CloudWatch によるサービスのモニタリング
Metric
Description
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Count
GetRecords.Success The number of successful GetRecords operations per stream, measured
over the specified time period.
Dimensions: StreamName
Statistics: Average, Sum, Samples
Units: Count
IncomingBytes
The number of bytes successfully put to the Amazon Kinesis stream over
the specified time period. This metric includes bytes from PutRecord
and PutRecords operations. Minimum, Maximum, and Average statistics
represent the bytes in a single put operation for the stream in the specified
time period.
Shard-level metric name: IncomingBytes
Dimensions: StreamName
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Bytes
IncomingRecords
The number of records successfully put to the Amazon Kinesis stream
over the specified time period. This metric includes record counts from
PutRecord and PutRecords operations. Minimum, Maximum, and
Average statistics represent the records in a single put operation for the
stream in the specified time period.
Shard-level metric name: IncomingRecords
Dimensions: StreamName
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Count
PutRecord.Bytes
The number of bytes put to the Amazon Kinesis stream using the
PutRecord operation over the specified time period.
Dimensions: StreamName
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Bytes
PutRecord.Latency
The time taken per PutRecord operation, measured over the specified
time period.
Dimensions: StreamName
Statistics: Minimum, Maximum, Average
Units: Milliseconds
108
Amazon Kinesis Streams 開発者ガイド
CloudWatch によるサービスのモニタリング
Metric
Description
PutRecord.Success
The number of successful PutRecord operations per Amazon Kinesis
stream, measured over the specified time period. Average reflects the
percentage of successful writes to a stream.
Dimensions: StreamName
Statistics: Average, Sum, Samples
Units: Count
PutRecords.Bytes
The number of bytes put to the Amazon Kinesis stream using the
PutRecords operation over the specified time period.
Dimensions: StreamName
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Bytes
PutRecords.Latency The time taken per PutRecords operation, measured over the specified
time period.
Dimensions: StreamName
Statistics: Minimum, Maximum, Average
Units: Milliseconds
PutRecords.Records The number of successful records in a PutRecords operation per Amazon
Kinesis stream, measured over the specified time period.
Dimensions: StreamName
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Count
PutRecords.Success The number of PutRecords operations where at least one record
succeeded, per Amazon Kinesis stream, measured over the specified time
period.
Dimensions: StreamName
Statistics: Average, Sum, Samples
Units: Count
109
Amazon Kinesis Streams 開発者ガイド
CloudWatch によるサービスのモニタリング
Metric
Description
ReadProvisionedThroughputExceeded
The number of GetRecords calls throttled for the stream over the
specified time period. The most commonly used statistic for this metric is
Average.
When the Minimum statistic has a value of 1, all records were throttled for
the stream during the specified time period.
When the Maximum statistic has a value of 0 (zero), no records were
throttled for the stream during the specified time period.
Shard-level metric name: ReadProvisionedThroughputExceeded
Dimensions: StreamName
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Count
WriteProvisionedThroughputExceeded
The number of records rejected due to throttling for the stream over the
specified time period. This metric includes throttling from PutRecord and
PutRecords operations. The most commonly used statistic for this metric
is Average.
When the Minimum statistic has a non-zero value, records were being
throttled for the stream during the specified time period.
When the Maximum statistic has a value of 0 (zero), no records were being
throttled for the stream during the specified time period.
Shard-level metric name: WriteProvisionedThroughputExceeded
Dimensions: StreamName
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Count
Enhanced Shard-level Metrics
The AWS/Kinesis namespace includes the following shard-level metrics.
Amazon Kinesis sends the following shard-level metrics to CloudWatch every minute. These metrics
are not enabled by default. There is a nominal charge for enhanced metrics emitted from Amazon
Kinesis. For more information, see Amazon CloudWatch Pricing.
Metric
Description
IncomingBytes
The number of bytes successfully put to the shard over the specified time
period. This metric includes bytes from PutRecord and PutRecords
operations. Minimum, Maximum, and Average statistics represent the
bytes in a single put operation for the shard in the specified time period.
Stream-level metric name: IncomingBytes
Dimensions: StreamName, ShardId
Statistics: Minimum, Maximum, Average, Sum, Samples
110
Amazon Kinesis Streams 開発者ガイド
CloudWatch によるサービスのモニタリング
Metric
Description
Units: Bytes
IncomingRecords
The number of records successfully put to the shard over the specified
time period. This metric includes record counts from PutRecord and
PutRecords operations. Minimum, Maximum, and Average statistics
represent the records in a single put operation for the shard in the specified
time period.
Stream-level metric name: IncomingRecords
Dimensions: StreamName, ShardId
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Count
IteratorAgeMilliseconds
The age of the last record in all GetRecords calls made against a shard,
measured over the specified time period. Age is the difference between the
current time and when the last record of the GetRecords call was written
to the stream. The Minimum and Maximum statistics can be used to track
the progress of Amazon Kinesis consumer applications. A value of 0 (zero)
indicates that the records being read are completely caught up with the
stream.
Stream-level metric name: GetRecords.IteratorAgeMilliseconds
Dimensions: StreamName, ShardId
Statistics: Minimum, Maximum, Average, Samples
Units: Milliseconds
OutgoingBytes
The number of bytes retrieved from the shard, measured over the specified
time period. Minimum, Maximum, and Average statistics represent the
bytes in a single GetRecords operation for the shard in the specified time
period.
Stream-level metric name: GetRecords.Bytes
Dimensions: StreamName, ShardId
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Bytes
OutgoingRecords
The number of records retrieved from the shard, measured over the
specified time period. Minimum, Maximum, and Average statistics
represent the records in a single GetRecords operation for the shard in
the specified time period.
Stream-level metric name: GetRecords.Records
Dimensions: StreamName, ShardId
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Count
111
Amazon Kinesis Streams 開発者ガイド
CloudWatch によるサービスのモニタリング
Metric
Description
ReadProvisionedThroughputExceeded
The number of GetRecords calls throttled for the shard over the specified
time period. This exception count covers all dimensions of the following
limits: 5 reads per shard per second or 2 MB per second per shard. The
most commonly used statistic for this metric is Average.
When the Minimum statistic has a value of 1, all records were throttled for
the shard during the specified time period.
When the Maximum statistic has a value of 0 (zero), no records were
throttled for the shard during the specified time period.
Stream-level metric name: ReadProvisionedThroughputExceeded
Dimensions: StreamName, ShardId
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Count
WriteProvisionedThroughputExceeded
The number of records rejected due to throttling for the shard over the
specified time period. This metric includes throttling from PutRecord and
PutRecords operations and covers all dimensions of the following limits:
1,000 records per second per shard or 1 MB per second per shard. The
most commonly used statistic for this metric is Average.
When the Minimum statistic has a non-zero value, records were being
throttled for the shard during the specified time period.
When the Maximum statistic has a value of 0 (zero), no records were being
throttled for the shard during the specified time period.
Stream-level metric name: WriteProvisionedThroughputExceeded
Dimensions: StreamName, ShardId
Statistics: Minimum, Maximum, Average, Sum, Samples
Units: Count
Amazon Kinesis Streams メトリックスのディメンション
You can use the following dimensions to filter the metrics for Amazon Kinesis Streams.
Dimension
Description
StreamName
The name of the Amazon Kinesis stream.
ShardId
The shard ID within the Amazon Kinesis stream.
推奨 Amazon Kinesis Streams メトリックス
Amazon Kinesis Streams のお客様の多くにとって有益なメトリックスがいくつか存在します。次のリ
ストは推奨メトリックスとご利用方法を提供しています。
112
Amazon Kinesis Streams 開発者ガイド
CloudWatch によるサービスのモニタリング
メトリックス
使用に関する注意事項
GetRecords.IteratorAgeMilliseconds
ストリームのすべてのシャードとコンシューマーの読み込み場所を追跡し
ます。イテレータの経過日数が保持期間（デフォルトで 24 時間、最大で
7 日まで設定可能）の 50% を経過すると失効する場合、レコードの有効
期限切れによるデータ損失のリスクがあります。この損失がリスクになる
前に警告するように、最大統計の CloudWatch アラームを使用することを
お勧めします。このメトリックスを使用するシナリオ例は、「コンシュー
マーレコードの処理が遅れる (p. 88)」を参照してください。
ReadProvisionedThroughputExceeded
コンシューマー側のレコード処理に後れが生じているときに、ボトルネッ
クがどこにあるかを確認するのは難しい場合があります。このメトリック
スを使用して、読み取りスループット制限を超えたために、読み取りが調
整されているかを判断してください。このメトリックスで最も一般的に使
用される統計は Average です。
WriteProvisionedThroughputExceeded
これは、ReadProvisionedThroughputExceeded メトリックスと同じ
目的ですが、ストリームのプロデューサ (PUT) 側用です。このメトリック
スで最も一般的に使用される統計は Average です。
PutRecord.Success、PutRecords.Success
レコードがストリームの役に立っていないことを示す平均統計の
CloudWatch アラームを使用することをお勧めします。プロデューサー
が使用しているものに応じて、一つまたは両方の種類の PUT 種類を選
択します。Kinesis プロデューサーライブラリ (KPL) を使用している場
合、PutRecords.Success を使用します。
GetRecords.Success レコードがストリームから失敗していることを示す、平均統計の
CloudWatch アラームを使用することをお勧めします。
Streams の Amazon CloudWatch メトリックスへのアクセス
CloudWatch コンソール、コマンドライン、または CloudWatch API を使用して、Streams のメトリッ
クスをモニタリングできます。次の手順は、これらのさまざまなメソッドを使用してメトリックスに
アクセスする方法を示しています。
CloudWatch コンソールを使用してメトリックスにアクセスするには
1.
2.
https://console.aws.amazon.com/cloudwatch/にある CloudWatch コンソールを開きます。
ナビゲーションバーから、リージョンを選択します。
3.
4.
ナビゲーションペインで メトリックスを選択します。
[CloudWatch Metrics by Category] ペインで [Kinesis Metrics] を選択します。
5.
該当する行をクリックし、指定した [MetricName] と [StreamName] の統計を表示します。
6.
注: ほとんどのコンソール統計の名前は、[Read Throughput] と [Write Throughput] を除いて、
上記の対応する CloudWatch メトリックス名に一致します。次の統計は 5 分間隔で計算されま
す。[Write Throughput] は IncomingBytes CloudWatch メトリックスをモニタリングし、[Read
Throughput] は GetRecords.Bytes をモニタリングします。
（オプション）グラフペインで、統計と期間を選択し、これらの設定を使用して CloudWatch ア
ラームを作成します。
AWS CLI を使用してメトリックスにアクセスするには
list-metrics コマンドと get-metric-statistics コマンドを使用します。
CloudWatch CLI を使用してメトリックスにアクセスするには
mon-list-metrics コマンドと mon-get-stats コマンドを使用します。
113
Amazon Kinesis Streams 開発者ガイド
CloudWatch によるエージェントのモニタリング
CloudWatch API を使用してメトリックスにアクセスするには
ListMetrics と GetMetricStatistics 操作を使用してください。
Amazon CloudWatch で Streams エージェントの状
態をモニタリングする
エージェントは、[AWSKinesisAgent] の名前空間でカスタム CloudWatch メトリックスを発行して、
エージェントがデータを指定されたとおりに Streams にデータを送信しており、状態が正常でデータ
プロデューサーで適切な量の CPU リソースとメモリリソースを消費している場合の評価を容易にし
ます。送信されたレコード数やバイト数などのメトリックスは、エージェントがストリームにデータ
を送信する速度を知るのに便利です。これらのメトリックスが、ある程度の割合低下するかゼロにな
ることで期待されるしきい値を下回っている場合は、設定の問題、ネットワークエラー、エージェン
トの状態の問題を示している場合があります。オンホスト CPU やメモリなどの消費量とエージェン
トエラーカウンターなどのメトリックスは、プロデューサーのリソース使用率を示し、潜在的な構成
またはホストのエラーに対する洞察を提供します。最後に、エージェントの問題を調査するのに役立
つサービス例外を記録します。これらのメトリックスは、エージェント設定 cloudwatch.endpoint
で指定されたリージョンで報告されます。エージェント設定の詳細については、「エージェントの設
定 (p. 57)」を参照してください。
CloudWatch によるモニタリング
Streams エージェントは以下のメトリックスを CloudWatch に送信します。
メトリックス
説明
BytesSent
指定された期間に Streams に送信されたバイト数。
単位: バイト
RecordSendAttempts 指定した期間内の PutRecords 呼び出しのレコード数（初回または再試
行の）。
単位: Count
RecordSendErrors
指定した期間内の、PutRecords への呼び出しの失敗ステータス（再試行
など）のレコード数。
単位: Count
ServiceErrors
指定した期間内の、サービスエラー（スロットリングエラーを除く）と
なった PutRecords への呼び出し数。
単位: Count
AWS CloudTrail を使用した Amazon Kinesis
Streams API 呼び出しのログ記録
Amazon Kinesis Streams は AWS CloudTrail と統合されます。CloudTrail は Streams による直接的
または間接的な API 呼び出しをキャプチャし、指定した Amazon S3 バケットにログファイルを渡し
ます。API 呼び出しは、Streams コンソールを使用して間接的に行うか、Streams API を使用して直
接的に行うことができます。CloudTrail によって収集された情報を使用して、Streams に対してどの
ようなリクエストが行われたか（リクエストの実行元 IP アドレス、実行者、実行日時など）を判断
できます。CloudTrail の詳細（設定して有効にする方法など）については、『AWS CloudTrail User
Guide』を参照してください。
114
Amazon Kinesis Streams 開発者ガイド
CloudTrail を使用した API 呼び出しのログ記録
Streams および CloudTrail
CloudTrail のログ記録を有効にすると、Streams のアクションに対する呼び出しがログファイルに記
録されます。Streams のレコードは、CloudTrail のログ記録で有効な他の AWS サービスのレコード
とともにログファイルに書き込まれます。CloudTrail は、指定された期間とファイルサイズに基づい
て、新しいファイルをいつ作成して書き込むかを決定します。
以下のアクションがサポートされています。
• CreateStream
• DeleteStream
• DescribeStream
• ListStreams
• MergeShards
• SplitShard
各ログエントリには、リクエストの生成元に関する情報が含まれます。たとえば、ストリームを作成
するリクエスト（CreateStream）が行われた場合は、そのリクエストを行ったユーザーのユーザー ID
またはサービスがログに記録されます。ユーザー ID 情報は、リクエストが、ルートまたは IAM ユー
ザーの認証情報を使用して送信されたか、ロールまたはフェデレーションユーザーの一時的なセキュ
リティ認証情報を使用して送信されたか、あるいは別の AWS サービスによって送信されたかを確認
するのに役立ちます。詳細については、『AWS CloudTrail User Guide』の「userIdentity 要素」を参
照してください。
必要な場合はログファイルを自身のバケットに保存できますが、ログファイルを自動的にアーカイブ
または削除するように Amazon S3 ライフサイクルルールを定義することもできます。デフォルトで
は Amazon S3 のサーバー側の暗号化（SSE）を使用して、ログファイルが暗号化されます。
また、複数の AWS リージョンと複数の AWS アカウントからの Streams ログファイルを 1 つの
Amazon S3 バケットに集約することもできます。詳細については、『AWS CloudTrail User Guide』
の「CloudTrail ログファイルの単一の Amazon S3 バケットへの集約」を参照してください。
ログファイルの配信時にすぐにアクションを実行する必要がある場合、新しいログファイルの配信
時に CloudTrail により SNS 通知が発行されるようにできます。詳細については、『AWS CloudTrail
User Guide』の「Amazon SNS 通知の設定」を参照してください。
Streams ログファイルエントリ
CloudTrail ログファイルには、複数の JSON 形式イベントで構成される 1 つ以上のログエントリが
記録されます。ログエントリは任意の送信元からの単一のリクエストを表し、リクエストされたアク
ション、パラメーター、アクションの日時などに関する情報を含みます。ログエントリは、特定の順
序になるように生成されるわけではありません。つまり、API 呼び出しの順序付けられたスタックト
レースではありません。
次の例は、CloudTrail のログエントリを示しています。
{
"Records": [
{
"eventVersion": "1.01",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn:aws:iam::012345678910:user/Alice",
"accountId": "012345678910",
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
115
Amazon Kinesis Streams 開発者ガイド
CloudTrail を使用した API 呼び出しのログ記録
},
"eventTime": "2014-04-19T00:16:31Z",
"eventSource": "kinesis.amazonaws.com",
"eventName": "CreateStream",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "aws-sdk-java/unknown-version Linux/x.xx",
"requestParameters": {
"shardCount": 1,
"streamName": "GoodStream"
},
"responseElements": null,
"requestID": "db6c59f8-c757-11e3-bc3b-57923b443c1c",
"eventID": "b7acfcd0-6ca9-4ee1-a3d7-c4e8d420d99b"
},
{
"eventVersion": "1.01",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn:aws:iam::012345678910:user/Alice",
"accountId": "012345678910",
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
},
"eventTime": "2014-04-19T00:17:06Z",
"eventSource": "kinesis.amazonaws.com",
"eventName": "DescribeStream",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "aws-sdk-java/unknown-version Linux/x.xx",
"requestParameters": {
"streamName": "GoodStream"
},
"responseElements": null,
"requestID": "f0944d86-c757-11e3-b4ae-25654b1d3136",
"eventID": "0b2f1396-88af-4561-b16f-398f8eaea596"
},
{
"eventVersion": "1.01",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn:aws:iam::012345678910:user/Alice",
"accountId": "012345678910",
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
},
"eventTime": "2014-04-19T00:15:02Z",
"eventSource": "kinesis.amazonaws.com",
"eventName": "ListStreams",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "aws-sdk-java/unknown-version Linux/x.xx",
"requestParameters": {
"limit": 10
},
"responseElements": null,
"requestID": "a68541ca-c757-11e3-901b-cbcfe5b3677a",
116
Amazon Kinesis Streams 開発者ガイド
CloudTrail を使用した API 呼び出しのログ記録
"eventID": "22a5fb8f-4e61-4bee-a8ad-3b72046b4c4d"
},
{
"eventVersion": "1.01",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn:aws:iam::012345678910:user/Alice",
"accountId": "012345678910",
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
},
"eventTime": "2014-04-19T00:17:07Z",
"eventSource": "kinesis.amazonaws.com",
"eventName": "DeleteStream",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "aws-sdk-java/unknown-version Linux/x.xx",
"requestParameters": {
"streamName": "GoodStream"
},
"responseElements": null,
"requestID": "f10cd97c-c757-11e3-901b-cbcfe5b3677a",
"eventID": "607e7217-311a-4a08-a904-ec02944596dd"
},
{
"eventVersion": "1.01",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn:aws:iam::012345678910:user/Alice",
"accountId": "012345678910",
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
},
"eventTime": "2014-04-19T00:15:03Z",
"eventSource": "kinesis.amazonaws.com",
"eventName": "SplitShard",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "aws-sdk-java/unknown-version Linux/x.xx",
"requestParameters": {
"shardToSplit": "shardId-000000000000",
"streamName": "GoodStream",
"newStartingHashKey": "11111111"
},
"responseElements": null,
"requestID": "a6e6e9cd-c757-11e3-901b-cbcfe5b3677a",
"eventID": "dcd2126f-c8d2-4186-b32a-192dd48d7e33"
},
{
"eventVersion": "1.01",
"userIdentity": {
"type": "IAMUser",
"principalId": "EX_PRINCIPAL_ID",
"arn": "arn:aws:iam::012345678910:user/Alice",
"accountId": "012345678910",
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
117
Amazon Kinesis Streams 開発者ガイド
CloudWatch による KCL のモニタリング
},
"eventTime": "2014-04-19T00:16:56Z",
"eventSource": "kinesis.amazonaws.com",
"eventName": "MergeShards",
"awsRegion": "us-east-1",
"sourceIPAddress": "127.0.0.1",
"userAgent": "aws-sdk-java/unknown-version Linux/x.xx",
"requestParameters": {
"streamName": "GoodStream",
"adjacentShardToMerge": "shardId-000000000002",
"shardToMerge": "shardId-000000000001"
},
"responseElements": null,
"requestID": "e9f9c8eb-c757-11e3-bf1d-6948db3cd570",
"eventID": "77cf0d06-ce90-42da-9576-71986fec411f"
}
]
}
Amazon CloudWatch による Amazon Kinesis クラ
イアントライブラリのモニタリング
Amazon Kinesis Client Library (KCL) for Amazon Kinesis Streams は、ユーザーに代わって、名前空間
として KCL アプリケーションの名前を使用して、カスタム Amazon CloudWatch メトリックスを発
行します。CloudWatch コンソール に移動し、[Custom Metrics] を選択すると、これらのメトリック
スを表示できます。カスタムメトリックスの詳細については、『Amazon CloudWatch ユーザーガイ
ド』の「カスタムメトリックスをパブリッシュする」を参照してください。
KCL によって CloudWatch にアップロードされたメトリックスには、小額の課金が発生します。具体
的には、Amazon CloudWatch カスタムメトリックスと Amazon CloudWatch API リクエストの料金が
適用されます。詳細については、「Amazon CloudWatch 料金表」を参照してください。
トピック
• メトリックスと名前空間 (p. 118)
• メトリックスレベルとディメンション (p. 118)
• メトリックスの設定 (p. 119)
• メトリックスの一覧 (p. 119)
メトリックスと名前空間
メトリックスのアップロードに使用される名前空間は、KCL の起動時に指定されたアプリケーション
名になります。
メトリックスレベルとディメンション
CloudWatch にアップロードされるメトリックスを制御する 2 つのオプションがあります。
メトリックスレベル
すべてのメトリックスに、個別のレベルが割り当てられます。メトリックスのレポートレベルを
設定すると、レポートレベル以下の個別のレベルのメトリックスは CloudWatch に送信されませ
ん。このレベルとして、NONE、SUMMARY、DETAILED があります。デフォルト設定は DETAILED
であり、すべてのメトリックスが CloudWatch に送信されます。レポートレベル NONE は、メト
リックスがまったく送信されないことを意味します。各メトリックスに割り当てられるメトリッ
クスの詳細については、「メトリックスの一覧 (p. 119)」を参照してください。
118
Amazon Kinesis Streams 開発者ガイド
CloudWatch による KCL のモニタリング
有効なディメンション
各 KCL メトリックスには、CloudWatch にも送信される関連ディメンションがありま
す。Operation ディメンションは常にアップロードされ、無効にすることはできません。デフォ
ルトでは、WorkerIdentifier ディメンションは無効となり、Operation および ShardID
ディメンションのみがアップロードされます。
CloudWatch メトリックスディメンションの詳細については、『Amazon CloudWatch ユーザー
ガイド』の「CloudWatch の概念」トピックの「ディメンション」セクションを参照してくださ
い。
WorkerIdentifier ディメンションが有効で、特定の KCL ワーカーが再起動するたびに、ワー
カー ID プロパティに異なる値が使用される場合、新しい WorkerIdentifier ディメンション値
を持つ新しいメトリックスのセットが CloudWatch に送信されます。特定の KCL ワーカーの再起
動で、WorkerIdentifier ディメンションの値が同じである必要がある場合、各ワーカーに初期
化中に、明示的に同じワーカー ID 値を指定する必要があります。アクティブな各 KCL ワーカー
のワーカー ID 値は、すべての KCL ワーカー間で一意である必要があります。
メトリックスの設定
メトリックスレベルと有効なディメンションは、KinesisClientLibConfiguration インスタンスを使用
して設定でき、このインスタンスは KCL アプリケーションを起動するときにワーカーに渡されま
す。MultiLangDaemon の場合、metricsLevel および metricsEnabledDimensions プロパティ
は、MultiLangDaemon KCL アプリケーションを起動するために使用される .properties ファイルで指
定できます。
メトリックスレベルには、NONE、SUMMARY、または DETAILED の 3 つの値のうち 1 つを割り当
てることができます。有効なディメンションの値は、CloudWatch メトリックスで許可されている
ディメンションのリストを含むカンマ区切りの文字列である必要があります。KCL アプリケーション
によって使用されるディメンションは、Operation、ShardID、および WorkerIdentifier です。
メトリックスの一覧
次の表には、範囲および操作によってグループ分けされた KCL メトリックスが表示されています。
トピック
• KCL アプリケーションあたりのメトリックス (p. 119)
• ワーカーあたりのメトリックス (p. 122)
• シャードあたりのメトリックス (p. 124)
KCL アプリケーションあたりのメトリックス
これらのメトリックスは、Amazon CloudWatch 名前空間で定義されているように、アプリケーショ
ンの範囲内にあるすべての KCL ワーカーで集約されます。
トピック
•
•
•
•
InitializeTask (p. 119)
ShutdownTask (p. 120)
ShardSyncTask (p. 121)
BlockOnParentTask (p. 122)
InitializeTask
InitializeTask オペレーションは、KCL アプリケーションのレコードプロセッサを初期化しま
す。このオペレーションのロジックには、Streams からのシャードイテレーターの取得とレコードプ
ロセッサの初期化が含まれています。
119
Amazon Kinesis Streams 開発者ガイド
CloudWatch による KCL のモニタリング
メトリックス:
メトリックス名
説明
KinesisDataFetcher.getIterator.Success
KCL アプリケーションあたりの GetShardIterator オペレーションの成
功回数。
メトリックスレベル: Detailed
単位: Count
KinesisDataFetcher.getIterator.Time
指定された KCL アプリケーションの GetShardIterator オペレーショ
ンにかかった時間。
メトリックスレベル: Detailed
単位: ミリ秒
RecordProcessor.initialize.Time
レコードプロセッサの初期化メソッドにかかった時間。
メトリックスレベル: Summary
単位: ミリ秒
成功
レコードプロセッサの初期化の成功回数。
メトリックスレベル: Summary
単位: Count
時間
KCL ワーカーでレコードプロセッサの初期化にかかった時間。
メトリックスレベル: Summary
単位: ミリ秒
ShutdownTask
ShutdownTask オペレーションは、シャード処理のシャットダウンシーケンスを開始します。これ
は、シャードが分割または結合された場合やシャードリースがワーカーから失われた場合に発生する
場合があります。どちらの場合も、レコードプロセッサ shutdown() 関数が呼び出されます。また、
シャードが分割または結合された場合、新しいシャードが 1 つまたは 2 つ作成されるため、新しい
シャードが検出されます。
メトリックス:
メトリックス名
説明
CreateLease.Success
親シャードのシャットダウンの後に、新しい子シャードが KCL アプリ
ケーションの DynamoDB テーブルに正常に追加された回数。
メトリックスレベル: Detailed
単位: Count
CreateLease.Time
KCL アプリケーションの DynamoDB テーブルに新しい子シャード情報を
追加するのにかかった時間。
メトリックスレベル: Detailed
単位: ミリ秒
120
Amazon Kinesis Streams 開発者ガイド
CloudWatch による KCL のモニタリング
UpdateLease.Success
レコードプロセッサのシャットダウン中に成功した最終チェックポイント
の数。
メトリックスレベル: Detailed
単位: Count
UpdateLease.Time
レコードプロセッサのシャットダウン中にチェックポイントオペレーショ
ンにかかった時間。
メトリックスレベル: Detailed
単位: ミリ秒
RecordProcessor.shutdown.Time
レコードプロセッサのシャットダウンメソッドにかかった時間。
メトリックスレベル: Summary
単位: ミリ秒
成功
シャットダウンタスクの成功回数。
メトリックスレベル: Summary
単位: Count
時間
KCL ワーカーでシャットダウンタスクにかかった時間。
メトリックスレベル: Summary
単位: ミリ秒
ShardSyncTask
ShardSyncTask オペレーションは、Amazon Kinesis stream のシャード情報に対する変更を検出す
るため、新しいシャードは KCL アプリケーションで処理することができます。
メトリックス:
メトリックス名
説明
CreateLease.Success
KCL アプリケーションの DynamoDB テーブルへの新しいシャード情報の
追加が成功した回数。
メトリックスレベル: Detailed
単位: Count
CreateLease.Time
KCL アプリケーションの DynamoDB テーブルに新しいシャード情報を追
加するのにかかった時間。
メトリックスレベル: Detailed
単位: ミリ秒
成功
シャード同期オペレーションの成功回数。
メトリックスレベル: Summary
単位: Count
121
Amazon Kinesis Streams 開発者ガイド
CloudWatch による KCL のモニタリング
時間
シャード同期オペレーションにかかった時間。
メトリックスレベル: Summary
単位: ミリ秒
BlockOnParentTask
シャードが分割または他のシャードと結合された場合、新しい子シャードが作成されま
す。BlockOnParentTask オペレーションは、KCL による親シャードの処理が完了するまで、新しい
シャードのレコード処理を開始しないことを保証します。
メトリックス:
メトリックス名
説明
成功
親シャードの完了チェックの成功回数。
メトリックスレベル: Summary
単位: Count
時間
親シャードが完了するまでにかかった時間。
メトリックスレベル: Summary
単位: ミリ秒
ワーカーあたりのメトリックス
これらのメトリックスは、Amazon EC2 インスタンスのように Amazon Kinesis stream のデータを消
費するすべてのレコードプロセッサについて集約されます。
トピック
• RenewAllLeases (p. 122)
• TakeLeases (p. 123)
RenewAllLeases
RenewAllLeases オペレーションは、特定のワーカーインスタンスによって所有されるシャードリー
スを定期的に更新します。
メトリックス:
メトリックス名
説明
RenewLease.Success
ワーカーによるリース更新の成功回数。
メトリックスレベル: Detailed
単位: Count
RenewLease.Time
リース更新オペレーションにかかった時間。
メトリックスレベル: Detailed
単位: ミリ秒
122
Amazon Kinesis Streams 開発者ガイド
CloudWatch による KCL のモニタリング
CurrentLeases
すべてのリースの更新後にワーカーによって所有されているシャードリー
スの数。
メトリックスレベル: Summary
単位: Count
LostLeases
ワーカーによって所有されているすべてのリースの更新を試みたときに失
われたシャードリースの数。
メトリックスレベル: Summary
単位: Count
成功
ワーカーのリース更新オペレーションが成功した回数。
メトリックスレベル: Summary
単位: Count
時間
ワーカーのすべてのリースを更新するのにかかった時間。
メトリックスレベル: Summary
単位: ミリ秒
TakeLeases
TakeLeases オペレーションは、すべての KCL ワーカー間でレコード処理の負荷を分散させます。現
在の KCL ワーカーのシャードリースが、必要数を下回る場合、過負荷になっている他のワーカーから
シャードリースを取得します。
メトリックス:
メトリックス名
説明
ListLeases.Success
すべてのシャードリースが KCL アプリケーションの DynamoDB テーブル
から正常に取得された回数。
メトリックスレベル: Detailed
単位: Count
ListLeases.Time
KCL アプリケーションの DynamoDB テーブルからすべてのシャードリー
スを取得するのにかかった時間。
メトリックスレベル: Detailed
単位: ミリ秒
TakeLease.Success
ワーカーが他の KCL ワーカーからシャードリースを正常に取得した回
数。
メトリックスレベル: Detailed
単位: Count
TakeLease.Time
ワーカーが取得したリースを使用してリーステーブルを更新するのにか
かった時間。
メトリックスレベル: Detailed
123
Amazon Kinesis Streams 開発者ガイド
CloudWatch による KCL のモニタリング
単位: ミリ秒
NumWorkers
特定のワーカーにより識別されるワーカーの総数。
メトリックスレベル: Summary
単位: Count
NeededLeases
現在のワーカーがシャード処理の負荷を分散するのに必要なシャードリー
スの数。
メトリックスレベル: Detailed
単位: Count
LeasesToTake
ワーカーが取得を試みるリースの数。
メトリックスレベル: Detailed
単位: Count
TakenLeases
ワーカーが取得に成功したリースの数。
メトリックスレベル: Summary
単位: Count
TotalLeases
KCL アプリケーションが処理しているシャードの総数。
メトリックスレベル: Detailed
単位: Count
ExpiredLeases
特定のワーカーによって識別されるどのワーカーでも処理されていない
シャードの総数。
メトリックスレベル: Summary
単位: Count
成功
TakeLeases オペレーションが正常に完了した回数。
メトリックスレベル: Summary
単位: Count
時間
ワーカーの TakeLeases オペレーションにかかった時間。
メトリックスレベル: Summary
単位: ミリ秒
シャードあたりのメトリックス
これらのメトリックスは、単一のレコードプロセッサについて集約されます。
ProcessTask
ProcessTask オペレーションは、現在のイテレーター位置を使用して GetRecords を呼び出すこと
によりストリームからレコードを取得し、レコードプロセッサの processRecords 関数を起動しま
す。
124
Amazon Kinesis Streams 開発者ガイド
CloudWatch による KCL のモニタリング
メトリックス:
メトリックス名
説明
KinesisDataFetcher.getRecords.Success
Amazon Kinesis stream シャードあたりの GetRecords オペレーションの
成功回数。
メトリックスレベル: Detailed
単位: Count
KinesisDataFetcher.getRecords.Time
Amazon Kinesis stream シャードの GetRecords オペレーションにかかっ
た時間。
メトリックスレベル: Detailed
単位: ミリ秒
UpdateLease.Success
指定されたシャードのレコードプロセッサによってチェックポイントが正
常に作成された回数。
メトリックスレベル: Detailed
単位: Count
UpdateLease.Time
指定されたシャードの各チェックポイントオペレーションにかかった時
間。
メトリックスレベル: Detailed
単位: ミリ秒
DataBytesProcessed
ProcessTask の各呼び出しで処理されたレコードのバイト単位の合計サ
イズ。
メトリックスレベル: Summary
単位: バイト
RecordsProcessed
ProcessTask の各呼び出しで処理されたレコード数。
メトリックスレベル: Summary
単位: Count
ExpiredIterator
GetRecords を呼び出したときに受信した ExpiredIteratorException の
数。
メトリックスレベル: Summary
単位: Count
MillisBehindLatest
現在のイテレーターがシャード内の最新のレコード (先端) から遅れてい
る時間。この値は、応答の最新レコードと現在時間における時間差と同じ
かそれ以下です。これは、最新の応答レコードのタイムスタンプを比較す
るよりも、シャードが先端からどれくらい離れているかを示すより正確な
反映です。この値は、各レコードの全タイムスタンプの平均ではなく、レ
コードの最新バッチに適用されることに留意してください。
メトリックスレベル: Summary
単位: ミリ秒
125
Amazon Kinesis Streams 開発者ガイド
CloudWatch による KPL のモニタリング
RecordProcessor.processRecords.Time
レコードプロセッサの processRecords メソッドにかかった時間。
メトリックスレベル: Summary
単位: ミリ秒
成功
プロセスタスクオペレーションの成功回数。
メトリックスレベル: Summary
単位: Count
時間
プロセスタスクオペレーションにかかった時間。
メトリックスレベル: Summary
単位: ミリ秒
Amazon CloudWatch による Amazon Kinesis プロ
デューサーライブラリのモニタリング
Amazon Kinesis プロデューサライブラリ (KPL) for Amazon Kinesis Streams は、ユーザーに代わっ
てカスタム Amazon CloudWatch メトリックスを発行します。CloudWatch コンソール に移動し、
[Custom Metrics] を選択すると、これらのメトリックスを表示できます。カスタムメトリックスの詳
細については、『Amazon CloudWatch ユーザーガイド』の「カスタムメトリックスをパブリッシュ
する」を参照してください。
KPL によって CloudWatch にアップロードされたメトリックスには、小額の課金が発生します。具体
的には、Amazon CloudWatch カスタムメトリックスと Amazon CloudWatch API リクエストの料金が
適用されます。詳細については、「Amazon CloudWatch 料金表」を参照してください。ローカルメ
トリックスの収集では、CloudWatch の課金が発生しません。
トピック
• メトリックス、ディメンション、および名前空間 (p. 126)
• メトリックスレベルと詳細度 (p. 126)
• ローカルアクセスと Amazon CloudWatch へのアップロード (p. 127)
• メトリックスの一覧 (p. 128)
メトリックス、ディメンション、および名前空間
KPL の起動時にアプリケーション名を指定できます。これは、メトリックスをアップロードする際、
名前空間の一部として使用されます。これはオプションであり、アプリケーション名を設定しない場
合は、KPL によりデフォルト値が設定されます。
また、メトリックスに任意の追加ディメンションを追加するように KPL を設定できます。これは、よ
り詳細なデータが CloudWatch メトリックスに必要な場合に便利です。たとえば、ディメンションと
してホスト名を追加でき、これによりフリート全体の均一でない負荷分散を特定できます。すべての
KPL 設定は変更不可能なため、KPL インスタンスを初期化した後、これらの追加ディメンションは変
更できません。
メトリックスレベルと詳細度
CloudWatch にアップロードされるメトリックスの数を制御する 2 つのオプションがあります。
126
Amazon Kinesis Streams 開発者ガイド
CloudWatch による KPL のモニタリング
メトリックスレベル
これは、メトリックスの重要性を示すおおよその目安です。すべてのメトリックスにレベルが割
り当てられます。レベルを設定すると、それより下のレベルのメトリックスは、CloudWatch に
送信されません。このレベルとして、NONE、SUMMARY、DETAILED があります。デフォルト設定
は DETAILED であり、すべてのメトリックスが対象です。NONE はメトリックスが一切ないこと
を意味し、実際にはどのメトリックスもそのレベルに割り当てられません。
詳細度
これは、追加の詳細度レベルで同じメトリックスが出力されるかどうかを制御します。このレベ
ルとして、GLOBAL、STREAM、SHARD があります。デフォルト設定は SHARD で、最も詳細なメ
トリックスが含まれます。
SHARD が選択されると、ストリーム名とシャード ID をディメンションとしてメトリックスが出
力されます。また、同じメトリックスは、ストリーム名のディメンションのみを使用して出力さ
れるため、そのメトリックスにはストリーム名がありません。つまり、ある特定のメトリックス
について、それぞれに 2 つのシャードがある 2 つのストリームから、7 つの CloudWatch メト
リックスが生成されます。各シャードに 1 つ、各ストリームに 1 つ、全体に 1 つのメトリックス
が生成され、これらはどれも同じ統計情報を記述していますが、詳細度のレベルは異なります。
次の図は、これを説明するものです。
異なる詳細度から階層が形成され、システム内のすべてのメトリックスから、メトリックス名を
ルートとするツリーが構成されます。
MetricName (GLOBAL):
Metric X
Metric Y
|
|
---------------------------|
|
|
|
StreamName (STREAM):
Stream A
Stream B
Stream A
Stream B
|
|
---------------|
|
|
|
ShardID (SHARD):
Shard 0 Shard 1 Shard 0 Shard 1
すべてのメトリックスをシャードレベルで使用できるわけではありません。一部のメトリックス
はストリームレベルまたは本質的にグローバルです。これらは、シャードレベルのメトリックス
を有効にしても、シャードレベルで生成されません（上の図の Metric Y）。
追加のディメンションを指定すると、tuple:<DimensionName, DimensionValue,
Granularity> に値を指定する必要があります。詳細度は、カスタムディメンションが階層のど
こに挿入されたかを判断するのに使用されます。GLOBAL は、追加のディメンションがメトリッ
クス名の後に挿入されたことを意味し、STREAM はストリーム名の後に、SHARD は ID シャードの
後に挿入されたことをそれぞれ意味します。複数の追加ディメンションが詳細度レベルごとに指
定された場合、それらは指定された順序で挿入されます。
ローカルアクセスと Amazon CloudWatch へのアップロード
現在の KPL インスタンスのメトリックスはローカルでリアルタイムに使用できるため、いつでも KPL
でクエリを実行してそれらを取得できます。KPL では、CloudWatch の場合と同様に、すべてのメト
リックスの合計、平均、最小値、最大値、および個数をローカルで計算します。
プログラムの開始から現在の時点までの累積として、または過去 N 秒間（N は 1 から 60 までの整
数）のローリングウィンドウを使用して統計情報を取得できます。
すべてのメトリックスは、CloudWatch へのアップロードに使用することができます。これは、複数
のホスト、モニタリング、およびアラームの間でデータを集約するのに特に役立ちます。この機能
は、ローカルでは使用できません。
127
Amazon Kinesis Streams 開発者ガイド
CloudWatch による KPL のモニタリング
前に説明したように、メトリックスレベルと詳細度の設定を使用してどのメトリックスをアップロー
ドするかを選択できます。ローカルでメトリックスをアップロードしたり使用したりすることはでき
ません。
データポイントを個別にアップロードするのは、高トラフィックの場合、毎秒数百万のアップロード
が発生するためお勧めしません。そのため、KPL は、メトリックスをローカルで 1 分間のバケットに
集約し、有効なメトリックスごとに 1 分あたり 1 回ずつ統計情報オブジェクトを CloudWatch にアッ
プロードします。
メトリックスの一覧
メトリックス
説明
User Records
Received
入力オペレーションで KPL コアにより受信された論理ユーザーレコード
の数。シャードレベルでは使用できません。
メトリックスレベル: Detailed
単位: 個
User Records
Pending
現在保留状態にあるユーザーレコード数の定期的なサンプリング。レコー
ドが現在バッファ処理されていて送信待ちの場合、または、送信済みで
バックエンドサービスで処理中の場合、そのレコードは保留状態です。
シャードレベルでは使用できません。
KPL が提供する専用のメソッドを使用して、グローバルレベルでこのメト
リックスを取得することで、お客様は PUT レートを管理できます。
メトリックスレベル: Detailed
単位: 個
User Records Put
入力に成功した論理ユーザーレコードの数。
このメトリックスの場合、KPL では、失敗したレコードがカウントされま
せん。このため、平均が成功率に、個数が総試行回数に、個数と合計の差
が失敗件数にそれぞれ対応します。
メトリックスレベル: Summary
単位: 個
User Records Data
Put
入力に成功した論理ユーザーレコードのバイト数。
メトリックスレベル: Detailed
単位: バイト
Kinesis Records
Put
入力に成功した Streams レコードの数（各 Streams レコードは、複数の
ユーザーレコードを含むことができます）。
KPL は、失敗したレコードに対してゼロを出力します。このため、平均が
成功率に、個数が総試行回数に、個数と合計の差が失敗件数にそれぞれ対
応します。
メトリックスレベル: Summary
単位: 個
Kinesis Records
Data Put
Streams レコードのバイト数。
128
Amazon Kinesis Streams 開発者ガイド
CloudWatch による KPL のモニタリング
メトリックスレベル: Detailed
単位: バイト
Errors by Code
各種類のエラーコードの数。これにより、StreamName や ShardID など
の通常のディメンションに加え、ディメンション ErrorCode が追加され
ます。シャードに対して、すべてのエラーを追跡することはできません。
追跡できないエラーは、ストリームレベルまたはグローバルレベルでのみ
出力されます。このメトリックスは、スロットリング、シャードマッピン
グの変更、内部エラー、サービス使用不可、タイムアウトなどに関する情
報をとらえます。
Streams API のエラーは、Streams レコードごとに 1 回カウントされま
す。Streams レコード内の複数のユーザーレコードで複数回のカウントが
生じることはありません。
メトリックスレベル: Summary
単位: 個
All Errors
これは、同じエラーによって Errors by Code としてトリガーされますが、
エラーの種類は区別されません。異なる種類のすべてのエラーから件数の
合計を手計算する必要がなくなるため、これはエラー率の総合的なモニタ
リングに役立ちます。
メトリックスレベル: Summary
単位: 個
Retries per
Record
ユーザーレコードあたりの再試行の実行回数。1 回の試行でレコードが成
功した場合は、ゼロが出力されます。
ユーザーレコードが終了すると（成功した場合またはそれ以上再試行され
ない場合）、直ちにデータが出力されます。レコードの有効期限値が大き
いと、このメトリックスの出力が大幅に遅延する場合があります。
メトリックスレベル: Detailed
単位: 個
Buffering Time
ユーザーレコードが KPL に到着してからバックエンドに送信されるまで
の時間。この情報は、レコード単位でユーザーに返されますが、集約され
た統計情報としても使用できます。
メトリックスレベル: Summary
単位: ミリ秒
Request Time
PutRecordsRequests の実行にかかる時間。
メトリックスレベル: Detailed
単位: ミリ秒
User Records per
Kinesis Record
単一の Streams レコードに集約された論理ユーザーレコードの数。
メトリックスレベル: Detailed
単位: 個
129
Amazon Kinesis Streams 開発者ガイド
ストリームのタグ付け
Amazon Kinesis
Records per
PutRecordsRequest
単一の PutRecordsRequest に集約された Streams レコードの数。
シャードレベルでは使用できません。
メトリックスレベル: Detailed
単位: 個
User Records per
PutRecordsRequest
PutRecordsRequest に含まれているユーザーレコードの総数。これは、
前の 2 つのメトリックスの積にほぼ一致します。シャードレベルでは使用
できません。
メトリックスレベル: Detailed
単位: 個
Amazon Kinesis Streams でのストリームのタグ
付け
Amazon Kinesis Streams で作成したストリームに、独自のメタデータをタグ形式で割り当てることが
できます。タグは、ストリームに対して定義するキーと値のペアです。タグの使用は、AWS リソース
の管理やデータ（請求データなど）の整理を行うシンプルかつ強力な方法です。
目次
• タグの基本 (p. 130)
• タグ付けを使用したコストの追跡 (p. 131)
• タグの制限 (p. 131)
• Streams コンソールを使用したストリームのタグ付け (p. 131)
• AWS CLI を使用したストリームのタグ付け (p. 132)
• Streams API を使用したストリームのタグ付け (p. 132)
タグの基本
Streams コンソール、AWS CLI、または Streams API を使用して、次のタスクを実行します。
• ストリームにタグを追加する
• ストリームのタグを一覧表示する
• ストリームからタグを削除する
タグを使用すると、ストリームを分類できます。たとえば、目的、所有者、環境などに基づいてスト
リームを分類できます。タグごとにキーと値を定義するため、特定のニーズを満たすためのカテゴリ
のカスタムセットを作成できます。たとえば、所有者と、関連するアプリケーションに基づいてスト
リームを追跡するのに役立つタグのセットを定義できます。次にいくつかのタグの例を示します。
• プロジェクト: プロジェクト名
• 所有者: 名前
• 目的: 負荷テスト
• アプリケーション: アプリケーション名
• 環境: 本稼働
130
Amazon Kinesis Streams 開発者ガイド
タグ付けを使用したコストの追跡
タグ付けを使用したコストの追跡
タグを使用して、AWS コストを分類して追跡できます。AWS リソース（ストリームなど）にタグを
適用すると、AWS のコスト配分レポートに、タグ別に集計された使用状況とコストが表示されます。
自社のカテゴリ（例えばコストセンター、アプリケーション名、所有者）を表すタグを適用すると、
複数のサービスにわたってコストを分類することができます。詳細については、『AWS Billing and
Cost Management ユーザーガイド』の「コスト配分タグを使用したカスタム請求レポート」を参照し
てください。
タグの制限
タグには次の制限があります。
基本制限
• リソース（ストリーム）あたりのタグの最大数は 10 です。
• タグのキーと値は大文字と小文字が区別されます。
• 削除されたストリームのタグを変更または編集することはできません。
タグキーの制限
• 各タグキーは一意である必要があります。既に使用されているキーを含むタグを追加すると、新し
いタグで、既存のキーと値のペアが上書きされます。
• aws: は AWS が使用するように予約されているため、このプレフィックスを含むタグキーで開始す
ることはできません。AWS ではユーザーの代わりにこのプレフィックスで始まるタグを作成します
が、ユーザーはこれらのタグを編集または削除することはできません。
• タグキーの長さは 1～128 文字（Unicode）にする必要があります。
• タグキーは、次の文字で構成する必要があります。Unicode 文字、数字、空白、特殊文字（_ . /
= + - @）。
タグ値の制限
• タグ値の長さは 0～255 文字（Unicode）にする必要があります。
• タグ値は空白にすることができます。空白にしない場合は、次の文字で構成する必要がありま
す。Unicode 文字、数字、空白、特殊文字（_ . / = + - @）。
Streams コンソールを使用したストリームのタグ付
け
Streams コンソールを使用してタグの追加、一覧表示、および削除を行うことができます。
ストリームのタグを表示するには
1.
Streams コンソールを開きます。ナビゲーションバーで、リージョンセレクターを展開し、リー
ジョンを選択します。
2.
[Stream List] ページで、ストリームを選択します。
3.
[Stream Details] ページで、[Tags] タブをクリックします。
131
Amazon Kinesis Streams 開発者ガイド
AWS CLI を使用したストリームのタグ付け
ストリームにタグを追加するには
1.
Streams コンソールを開きます。ナビゲーションバーで、リージョンセレクターを展開し、リー
ジョンを選択します。
2.
[Stream List] ページで、ストリームを選択します。
3.
[Stream Details] ページで、[Tags] タブをクリックします。
4.
[Key] フィールドにタグキーを指定し、オプションとして [Value] フィールドにタグ値を指定した
後で、[Add Tag] をクリックします。
[Add Tag] ボタンが有効でない場合は、指定したタグキーまたはタグ値のいずれかがタグの制限を
満たしていません。詳細については、「タグの制限 (p. 131)」を参照してください。
5.
[Tags] タブのリストに新しいタグを表示するには、更新アイコンをクリックします。
ストリームからタグを削除するには
1.
Streams コンソールを開きます。ナビゲーションバーで、リージョンセレクターを展開し、リー
ジョンを選択します。
2.
[Stream List] ページで、ストリームを選択します。
3.
[Stream Details] ページで、[Tags] タブをクリックし、タグの [Remove] アイコンをクリックしま
す。
4.
[Delete Tag] ダイアログボックスで、[Yes, Delete] をクリックします。
AWS CLI を使用したストリームのタグ付け
AWS CLI を使用してタグの追加、一覧表示、および削除を行うことができます。例については、次の
ドキュメントを参照してください。
add-tags-to-stream
指定したストリームのタグを追加または更新します。
list-tags-for-stream
指定したストリームのタグを一覧表示します。
remove-tags-from-stream
指定したストリームからタグを削除します。
Streams API を使用したストリームのタグ付け
Streams API を使用してタグの追加、一覧表示、および削除を行うことができます。例については、
次のドキュメントを参照してください。
AddTagsToStream
指定したストリームのタグを追加または更新します。
ListTagsForStream
指定したストリームのタグを一覧表示します。
RemoveTagsFromStream
指定したストリームからタグを削除します。
132
Amazon Kinesis Streams 開発者ガイド
アクセスの制御
IAM により Amazon Kinesis Streams リソースへ
のアクセスを制御する
AWS Identity and Access Management （IAM）を使って以下を行えます。
• お客様の AWS アカウントでユーザーとグループを作成する
• お客様の AWS アカウントでユーザーごとに固有のセキュリティ認証情報を割り当てる
• AWS のリソースを使用してタスクを実行するために各ユーザーのアクセス許可を制御する
• 別の AWS アカウントのユーザーがお客様の AWS のリソースを共有できるようにする
• AWS アカウントにロールを作成し、それを行えるユーザーまたはサービスを定義する
• お客様の企業用の既存のアイデンティティを使用し、AWS のリソースを使用してタスクを実行する
ようにアクセス許可を与える
Streams と組み合わせて IAM を使用することにより、組織のユーザーが特定の Streams API アクショ
ンを使用してタスクを実行できるかどうか、また、特定の AWS リソースを使用できるかどうかを制
御できます。
Amazon Kinesis Client Library（KCL）ライブラリを使用してアプリケーションを開発する場合、ポリ
シーに Amazon DynamoDB と Amazon CloudWatch へのアクセス許可を含める必要があります。これ
は、KCL がアプリケーションの状態情報を追跡するために DynamoDB を使用し、ユーザーに代わっ
て KCL メトリックスを CloudWatch に送信するために CloudWatch を使用するからです。KCL の詳
細については、「Amazon Kinesis Client Library を使用した Amazon Kinesis Streams コンシューマー
の開発 (p. 66)」を参照してください。
IAM の詳細については、以下を参照してください。
• Identity and Access Management (IAM)
• はじめに
• IAM ユーザーガイド
IAM および Amazon DynamoDB の詳細については、『Amazon DynamoDB 開発者ガイド』の「Using
IAM to Control Access to Amazon DynamoDB Resources」を参照してください。
IAM と Amazon CloudWatch の詳細については、『Amazon CloudWatch ユーザーガイド』の「AWS
アカウントへのユーザーアクセスのコントロール」を参照してください。
目次
• ポリシー構文 (p. 133)
• Streams のアクション (p. 134)
• Streams 用の Amazon リソースネーム（ARN） (p. 134)
• Streams のポリシー例 (p. 135)
ポリシー構文
IAM ポリシーは 1 つ以上のステートメントで構成される JSON ドキュメントです。各ステートメント
は次のように構成されます。
{
133
Amazon Kinesis Streams 開発者ガイド
Streams のアクション
"Statement":[{
"Effect":"effect",
"Action":"action",
"Resource":"arn",
"Condition":{
"condition":{
"key":"value"
}
}
}
]
}
ステートメントはさまざまなエレメントで構成されます。
• [Effect]: effect は、Allow または Deny にすることができます。デフォルトでは、IAM ユーザーはリ
ソースおよび API アクションを使用するアクセス許可がないため、リクエストはすべて拒否されま
す。明示的な許可はデフォルトに優先します。明示的な拒否はすべての許可に優先します。
• [Action]: action は、アクセス許可を付与または拒否する対象とする、特定の API アクションです。
• [Resource]: アクションによって影響を及ぼされるリソースです。ステートメント内でリソースを指
定するには、Amazon リソースネーム（ARN）を使用する必要があります。
• [Condition]: condition はオプションです。ポリシーの発効条件を指定するために使用します。
IAM のポリシーを作成および管理するときは、AWS Policy Generator と IAM Policy Simulator を使用
することもできます。
Streams のアクション
IAM ポリシーステートメントで、IAM をサポートするすべてのサービスから任意の API アクションを
指定できます。Streams の場合、API アクション kinesis: の名前に次のプレフィックスを使用しま
す。例: kinesis:CreateStream、kinesis:ListStreams、および kinesis:DescribeStream。
単一のステートメントに複数のアクションを指定するには、次のようにコンマで区切ります。
"Action": ["kinesis:action1", "kinesis:action2"]
ワイルドカードを使用して複数のアクションを指定することもできます。たとえば、「Get」という単
語で始まる名前のすべてのアクションは、以下のように指定できます。
"Action": "kinesis:Get*"
すべての Streams オペレーションを指定するには、次のように * ワイルドカードを使用します。
"Action": "kinesis:*"
Streams API アクションの完全なリストについては、『Amazon Kinesis API Reference』を参照して
ください。
Streams 用の Amazon リソースネーム（ARN）
各 IAM ポリシーステートメントは、ARN を使用して指定したリソースに適用されます。
134
Amazon Kinesis Streams 開発者ガイド
Streams のポリシー例
Amazon Kinesis stream には、次の ARN リソースフォーマットを使用します。
"Resource": arn:aws:kinesis:region:account-id:stream/stream-name
以下に例を示します。
"Resource": arn:aws:kinesis:*:111122223333:stream/my-stream
Streams のポリシー例
次のポリシーの例は、Amazon Kinesis stream へのユーザーアクセスの制御方法について説明してい
ます。
Example 1: ユーザーがストリームからデータを取得できるようにする
このポリシーでは、ユーザーまたはグループが、指定したストリームに対して
GetShardIterator、GetRecords、DescribeStream、ListStreams のオペレーションを実行で
きます。このポリシーは、特定のストリームからデータを取得できる必要があるユーザーに適用でき
ます。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kinesis: Get*"
],
"Resource": [
"arn:aws:kinesis:us-east-1:111122223333:stream/stream1"
]
},
{
"Effect": "Allow",
"Action": [
"kinesis:DescribeStream"
],
"Resource": [
"arn:aws:kinesis:us-east-1:111122223333:stream/stream1"
]
},
{
"Effect": "Allow",
"Action": [
"kinesis:ListStreams"
],
"Resource": [
"*"
]
}
]
}
135
Amazon Kinesis Streams 開発者ガイド
Streams のポリシー例
Example 2: ユーザーがアカウントの任意のストリームにデータを追加できるようにする
このポリシーでは、ユーザーまたはグループが、アカウントのストリームに対して PutRecord オペ
レーションを使用できます。このポリシーは、アカウントのすべてのストリームにデータレコードを
追加できる必要のあるユーザーに適用できます。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kinesis:PutRecord"
],
"Resource": [
"arn:aws:kinesis:us-east-1:111122223333:stream/*"
]
}
]
}
Example 3: 特定のストリームに対して任意の Streams アクションを実行できるようにする
このポリシーでは、ユーザーまたはグループが、指定したストリームに対して任意の Streams オペ
レーションを実行できます。このポリシーは、特定のストリームに対して管理上の制御が必要なユー
ザーに適用できます。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "kinesis:*",
"Resource": [
"arn:aws:kinesis:us-east-1:111122223333:stream/stream1"
]
}
]
}
136
Amazon Kinesis Streams 開発者ガイド
Streams のポリシー例
Example 4: 任意のストリームに対して任意の Streams アクションを実行できるようにする
このポリシーでは、ユーザーまたはグループが、アカウントの任意のストリームに対して任意の
Streams オペレーションを実行できます。このポリシーは、すべてのストリームへのフルアクセスを
許可するため、管理者にのみ適用する必要があります。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "kinesis:*",
"Resource": [
"arn:aws:kinesis:*:111122223333:stream/*"
]
}
]
}
137
Amazon Kinesis Streams 開発者ガイド
ドキュメント履歴
以下の表は Amazon Kinesis Streams のドキュメントの重要な変更点をまとめたものです。
変更
説明
変更日
拡張 CloudWatch メ
トリックスの新しい
コンテンツ。
更新済み Amazon Kinesis Streams のモニタリン
グ (p. 105).
2016 年 4 月 19 日
拡張 Amazon
Kinesis エージェン
トの新しいコンテン
ツ。
更新済み Amazon Kinesis エージェントを使用して
Amazon Kinesis Streams への書き込み (p. 54).
2016 年 4 月 11 日
Amazon Kinesis
エージェントを使用
するための新しいコ
ンテンツ。
「Amazon Kinesis エージェントを使用して Amazon
Kinesis Streams への書き込み (p. 54)」が追加されま
した。
2015 年 10 月 2 日
リリース 0.10.0 へ
の KPL コンテンツ
の更新
「Amazon Kinesis プロデューサライブラリ を使用
した Amazon Kinesis Streams プロデューサーの開
発 (p. 39)」が追加されました。
2015 年 7 月 15 日
設定可能なメトリッ
クスの KCL メト
リックスのトピック
の更新。
「Amazon CloudWatch による Amazon Kinesis クライ
アントライブラリのモニタリング (p. 118)」が追加さ
れました。
2015 年 7 月 9 日
コンテンツの再編
成。
コンテンツトピックを大幅に再編成し、より簡潔なツ
リー表示とより論理的なグループ化を行いました。
2015 年 7 月 01 日
新しい KPL 開発者
ガイドのトピック。
「Amazon Kinesis プロデューサライブラリ を使用
した Amazon Kinesis Streams プロデューサーの開
発 (p. 39)」が追加されました。
2015 年 6 月 02 日
新しい KCL メト
リックスのトピッ
ク。
「Amazon CloudWatch による Amazon Kinesis クライ
アントライブラリのモニタリング (p. 118)」が追加さ
れました。
2015 年 5 月 19 日
KCL .NET のサポー
ト
「.NET での Amazon Kinesis Client Library コンシュー
マーの開発 (p. 76)」が追加されました。
2015 年 5 月 1 日
138
Amazon Kinesis Streams 開発者ガイド
変更
説明
変更日
KCL Node.js のサ
ポート
「Node.js での Amazon Kinesis Client Library コン
シューマーの開発 (p. 73)」が追加されました。
2015 年 3 月 26 日
KCL Ruby のサポー
ト
KCL Ruby ライブラリへのリンクを追加しました。
2015 年 1 月 12 日
新しい API
PutRecords
「the section called “PutRecords を使用した複数のレ
コードの追加” (p. 50)」に、新しい PutRecords API に
関する情報を追加しました。
2014 年 12 月 15 日
タグ指定のサポート
「Amazon Kinesis Streams でのストリームのタグ付
け (p. 130)」が追加されました。
2014年９月11日
CloudWatch メト
リックスの新規追加
GetRecords.IteratorAgeMilliseconds メトリッ
クを Amazon Kinesis Streams のディメンションおよ
びメトリックス (p. 106) に追加しました。
2014年９月3日
モニタリングに関す
る章の新規追加
Amazon Kinesis Streams のモニタリング (p. 105) と
Amazon CloudWatch による Amazon Kinesis Streams
サービスのモニタリング (p. 106) が追加されました。
2014 年 7 月 30 日
サンプルアプリケー
ションの新規追加
「チュートリアル: Amazon Kinesis Streams を使用し
たウェブトラフィックの可視化 (p. 10)」が追加されま
した。
2014 年 6 月 27 日
デフォルトのシャー
ド制限
Amazon Kinesis Streams の制限 (p. 7) の更新点: デ
フォルトのシャード制限が 5 から 10 に増えました。
2014 年 2 月 25 日
デフォルトのシャー
ド制限
Amazon Kinesis Streams の制限 (p. 7) の更新点: デ
フォルトのシャード制限が 2 から 5 に増えました。
2014 年 1 月 28 日
2014 年 1 月 3 日
API バージョンに合
わせた更新
Streams API の 2013-12-02 バージョンに合わせた更
新。
2013年12月12日
初回リリース
Amazon Kinesis Developer Guide の初回リリース。
2013 年 11 月 14 日
139
Amazon Kinesis Streams 開発者ガイド
AWS の用語集
最新の AWS の用語については、『AWS General Reference』の「AWS の用語集」を参照してくださ
い。
140

悪質な偽サイトにご注意ください

Amazonギフト券とは？ Amazon.co.jpとは？

仮想デスクトップサービスAmazon WorkSpacesの自社導入開始～既存

【HZ 乗っ取り手口詳細と，我が国の行く末を案じてベンチ ャー育成の提言

クリスマスイベントを開催！ - グッドラックスリー採用情報

マルチクラウド運用サービス - 株式会社VINX（ヴィンクス）

「Amazonスポンサープロダクト広告」をPDFでダウンロードする

Ankama Japan 「DOFUS」×「eggfile」アート