Amazon Kinesis Streams 开发人员指南

Amazon Kinesis Streams 开发人员指南
Amazon Kinesis Streams
开发人员指南
Amazon Kinesis Streams 开发人员指南
Amazon Kinesis Streams: 开发人员指南
Copyright © 2016 Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Abstract
使用 Amazon Kinesis Streams 对大数据流的实时处理进行弹性扩展。
Amazon Kinesis Streams 开发人员指南
Table of Contents
什么是 Amazon Kinesis Streams? ................................................................................................... 1
Streams 可以用来做什么? ..................................................................................................... 1
使用 Streams 的好处 .............................................................................................................. 2
相关服务 .............................................................................................................................. 2
主要概念 .............................................................................................................................. 2
高级别架构 ................................................................................................................... 2
术语 ............................................................................................................................ 3
Streams 技术 ........................................................................................................................ 4
确定 Amazon Kinesis Stream 的初始大小 .......................................................................... 5
创建流 ....................................................................................................................... 19
创建器 ................................................................................................................................. 6
使用器 ................................................................................................................................. 6
限制 .................................................................................................................................... 7
入门 ............................................................................................................................................ 8
设置 .................................................................................................................................... 8
注册 AWS .................................................................................................................... 8
下载库和工具 ................................................................................................................ 9
配置您的开发环境 .......................................................................................................... 9
教程:可视化 Web 流量 .......................................................................................................... 9
Streams 数据可视化示例应用程序 .................................................................................. 10
先决条件 .................................................................................................................... 10
步骤 1:启动示例应用程序 ............................................................................................ 10
步骤 2:查看示例应用程序的组件 ................................................................................... 11
步骤 3:删除示例应用程序资源 ...................................................................................... 16
步骤 4:后续步骤 ........................................................................................................ 16
教程:开始使用 CLI ............................................................................................................. 17
安装和配置 AWS CLI .................................................................................................... 17
执行基本流操作 ........................................................................................................... 19
学习 Amazon Kinesis Streams 开发 ................................................................................................ 24
第一部分:流、创建器和使用器 ............................................................................................. 24
先决条件 .................................................................................................................... 25
第 1 步:创建流 ........................................................................................................... 26
第 2 步:创建 IAM 策略和用户 ....................................................................................... 26
第 3 步:下载和构建实施代码 ........................................................................................ 29
第 4 步:实施创建器 .................................................................................................... 30
第 5 步:实施使用器 .................................................................................................... 32
第 6 步:(可选)扩展使用器 ........................................................................................ 35
第 7 步:收尾 .............................................................................................................. 36
使用 Amazon Kinesis Streams ....................................................................................................... 38
将数据写入到流 ................................................................................................................... 38
使用 KPL .................................................................................................................... 39
使用 API .................................................................................................................... 48
使用代理写入 .............................................................................................................. 52
问题排查 .................................................................................................................... 58
高级主题 .................................................................................................................... 59
读取流中的数据 ................................................................................................................... 61
使用 KCL ................................................................................................................... 61
使用 API .................................................................................................................... 75
问题排查 .................................................................................................................... 79
高级主题 .................................................................................................................... 81
管理流 ............................................................................................................................... 87
创建流 ....................................................................................................................... 88
列出流 ....................................................................................................................... 89
从流中检索分片 ........................................................................................................... 90
删除流 ....................................................................................................................... 90
iii
Amazon Kinesis Streams 开发人员指南
对流进行重新分片 ........................................................................................................ 91
更改数据保留期 ........................................................................................................... 95
监控 .................................................................................................................................. 96
利用 CloudWatch 监控服务 ............................................................................................ 96
利用 CloudWatch 监控代理 ............................................................................................ 99
使用 CloudTrail 记录 API 调用 ........................................................................................ 99
利用 CloudWatch 监控 KCL ......................................................................................... 103
利用 CloudWatch 监控 KPL ......................................................................................... 111
为您的流添加标签 .............................................................................................................. 114
有关标签的基本知识 ................................................................................................... 114
使用标签跟踪成本 ...................................................................................................... 115
标签限制 .................................................................................................................. 115
使用 Streams 控制台为流添加标签 ................................................................................ 115
使用 AWS CLI 为流添加标签 ........................................................................................ 116
使用 Streams API 为流添加标签 ................................................................................... 116
Controlling Access ............................................................................................................. 116
策略语法 .................................................................................................................. 117
针对 Streams 的操作 .................................................................................................. 118
适用于 Streams 的 Amazon 资源名称 (ARN) ................................................................... 118
Streams 策略示例 ...................................................................................................... 118
文档历史记录 ............................................................................................................................ 121
AWS 词汇表 .............................................................................................................................. 123
iv
Amazon Kinesis Streams 开发人员指南
Streams 可以用来做什么?
什么是 Amazon Kinesis Streams?
Abstract
使用 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。
有关 AWS 大数据解决方案的更多信息,请参阅大数据。有关 AWS 流数据解决方案的更多信息,请参阅
什么是流数据?
Streams 可以用来做什么?
您可以将 Streams 用于快速而持续的数据引入和聚合。使用的数据类型包括 IT 基础设施日志数据、应用
程序日志、社交媒体、市场数据源和 Web 点击流数据。由于数据引入和处理的响应时间是实时的,因此
处理通常是轻量级的。
以下是使用 Streams 的典型场景:
加速的日志和数据源引入和处理
您可以让创建器直接将数据推入流。例如,推送系统和应用程序日志,它们可在几秒内用于处理。这
可以防止因前端或应用程序服务器失败而造成日志数据丢失。Streams 提供加速的数据源引入,因为
您在提交数据以备引入之前,未在服务器上批处理数据。
实时指标和报告
您可以使用收集到 Streams 中的数据进行实时的简单数据分析和报告。例如,您的数据处理应用程
序可以处理系统和应用程序日志的指标和报告,因为数据将流入而不是等待接收批量数据。
实时数据分析
这可将并行处理的强大功能与实时数据的价值相结合。例如,实时处理网站点击流,然后使用多个并
行运行的不同的 Streams 应用程序来分析站点可用性参与度。
1
Amazon Kinesis Streams 开发人员指南
使用 Streams 的好处
复杂流处理
您可以创建 Amazon Kinesis Streams application 和数据流的有向无环图 (DAG)。这通常会涉及将数
据从多个 Amazon Kinesis Streams application 放入其他流,以供其他 Amazon Kinesis Streams
application 进行下游处理。
使用 Streams 的好处
虽然可使用 Streams 解决各种流数据问题,但其常见用途是实时聚合数据,然后将聚合数据上传到数据
仓库或 map-reduce 集群。
将数据放入 Amazon Kinesis stream,这可确保持久性和弹性。将记录放入流的时间与可检索记录的时间
之间的延迟(put-to-get 延迟)通常少于 1 秒 - 换言之,在添加数据后,Amazon Kinesis Streams application
几乎立即可以开始使用流中的数据。Streams 的托管服务方面可减轻您创建和运行数据引入管道的操作负
担。您可以创建流式处理 map-reduce 类型应用程序,并且 Streams 的弹性允许您扩大或缩小流,这样
您绝不会在数据记录过期前丢失它们。
多个 Amazon Kinesis Streams application 可使用流中的数据,以便多个操作(如存档和处理)可以同时
单独进行。例如,两个应用程序可读取同一流中的数据。第一个应用程序计算正在运行的聚合并更新
DynamoDB 表,第二个应用程序压缩数据并将数据存档至数据存储(如 Amazon S3)。然后,控制面板
将读取带正在运行的聚合的 DynamoDB 表以获取实时报告(分钟级)。
Amazon Kinesis Client Library 支持容错使用流中的数据,并提供针对 Amazon Kinesis Streams application
的扩展支持。
相关服务
有关如何使用 Amazon EMR 集群直接读取和处理 Amazon Kinesis stream 的示例,请参阅 Amazon Elastic
MapReduce 开发人员指南 中的分析 Streams 数据。
Amazon Kinesis Streams 主要概念
Abstract
列出 Amazon Kinesis Streams 的主要概念、术语和架构。
在您开始使用 Amazon Kinesis Streams 时,就将从了解其架构和术语中获益。
Streams 高级别架构
下图演示 Streams 的高级别架构。创建器会持续将数据推送到 Streams,并且使用器可实时处理数据。
使用器可使用 AWS 服务(例如 Amazon DynamoDB、Amazon Redshift 或 Amazon S3)来存储其结果。
2
Amazon Kinesis Streams 开发人员指南
术语
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 小时。您可以
使用 IncreaseRetentionPeriod 操作将保留期增加到最高 168 小时(7 天),使用
DecreaseRetentionPeriod 操作可将保留期减少到最短 24 小时。对于保留期设置为 24 小时以上的
流,将收取额外费用。有关更多信息,请参阅Amazon Kinesis Streams 定价。
创建器
创建器将记录放入 Amazon Kinesis Streams 中。例如,发送日志数据到流的 Web 服务器是创建器。
使用器
使用器从 Amazon Kinesis Streams 获取记录并进行处理。这些使用器称为 Amazon Kinesis Streams
Application (p. 3)。
Amazon Kinesis Streams Application
Amazon Kinesis Streams application 是通常在 EC2 实例队列上运行的流的使用器。
您可以使用 Amazon Kinesis Client Library 或 Streams API 开发 Amazon Kinesis Streams application。
3
Amazon Kinesis Streams 开发人员指南
Streams 技术
Amazon Kinesis Streams application 的输出可能是另一个流的输入,这使您能够实时创建处理数据的复
杂拓扑。应用程序也可将数据发送到各种其他 AWS 服务。一个流可以有多个应用程序,每个应用程序可
同时单独使用流中的数据。
分片
分片是流中数据记录的唯一标识组。一个流由一个或多个分片组成,每个分片提供一个固定的容量单位。
每个分片均可支持 最多 5 transactions per second 可用于读取,最多可达的最大总数据读取速率为 2 MB
per second 和 最多 1,000 records per second 可用于写入,最多可达的最大总数据写入速率为 1 MB per
second (including partition keys)。流的数据容量是您为流指定的分片数的函数。流的总容量是其分片容
量的总和。
如果数据速率增加,您只需添加更多分片即可增大流的大小。同样,如果数据速率降低,则可删除分片。
分区键
分区键 用于按分片对流中的数据进行分组。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 表存储控制数据。它会为每个正在处理数据的
应用程序创建一个表。
Application Name
Amazon Kinesis Streams application 的名称标识应用程序。每个应用程序必须有一个唯一名称,其范围
限定于该应用程序使用的 AWS 账户和区域。此名称用作 Amazon DynamoDB 中的控制表名称和 Amazon
CloudWatch 指标的命名空间。
Amazon Kinesis Stream
Abstract
了解 Amazon Kinesis stream。
Amazon Kinesis Streams 实时吸收大量数据、持久存储数据并使这些数据可供使用。Streams 服务存储
的数据单位是数据记录。流 表示数据记录的有序序列。流中的数据记录将分发到分片中。
4
Amazon Kinesis Streams 开发人员指南
确定 Amazon Kinesis Stream 的初始大小
分片 是流中的数据记录组。在创建流时,您将指定流的分片数。每个分片均可支持 最多 5 transactions
per second 可用于读取,最多可达的最大总数据读取速率为 2 MB per second 和 最多 1,000 records per
second 可用于写入,最多可达的最大总数据写入速率为 1 MB per second (including partition keys)。流
的总容量是其分片容量的总和。您可以根据需要增加或减少流中的分片数。但请注意,您需要按分片付
费。
创建器 (p. 6)将数据记录放入分片,使用器 (p. 6)从分片中获取数据。
确定 Amazon Kinesis Stream 的初始大小
在创建流之前,您需要确定流的初始大小。在创建流后并且有 Amazon Kinesis Streams application 使用
流中的数据的情况下,您可以动态调整流的大小或添加和删除分片。
要确定流的初始大小,您需要以下输入值:
• 写入流的数据记录的平均大小(以 KB 为单位,四舍五入为 1 KB),数据大小
(average_data_size_in_KB)。
• 每秒写入流和从流读取的数据记录数 (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_band
width_in_KB/2000)
创建流
您可以使用 Streams 控制台、Streams API 或 AWS CLI 创建流。
使用控制台创建流
1.
2.
通过以下网址打开 Streams 控制台:https://console.amazonaws.cn/kinesis/。
在导航栏中,展开区域选择器并选择一个区域。
3.
4.
单击 Create Stream (创建流)。
在 Create Stream 页面上,输入流名称和所需分片数,然后单击 Create。
在 Stream List 页面上,在创建流的过程中,其 Status 为 CREATING。当流可以使用时,Status 会更
改为 ACTIVE。
5.
单击流的名称。Stream Details (流详细信息) 页面显示了流配置摘要以及监控信息。
使用 Streams API 创建流
有关使用 Streams API 创建流的信息,请参阅 创建流 (p. 88)。
使用 AWS CLI 创建流
有关使用 AWS CLI 创建流的信息,请参阅 create-stream 命令。
5
Amazon Kinesis Streams 开发人员指南
创建器
Amazon Kinesis Streams 的创建器
Abstract
了解 Amazon Kinesis Streams 的创建器。
创建器 会将数据记录放入 Amazon Kinesis stream。例如,将日志数据发送至 Amazon Kinesis stream 的
Web 服务器即是创建器。使用器 (p. 6)处理流中的数据记录。
Important
数据记录默认可在其添加到流的 24 小时内访问。此时间范围称为保留期,并且可以在从 24 到
168 小时(1 到 7 天)的范围内按小时为增量进行配置。有关流的保留期的更多信息,请参阅the
section called “更改数据保留期” (p. 95)。
要将数据放入流,您必须指定流的名称、分区键和要添加到流的数据 Blob。分区键用来确定数据记录将
添加到流中的哪个分片。
分片中的所有数据将发送至正在处理分片的同一个工作程序。使用哪个分区键取决于您的应用程序逻辑。
通常,分区键的数量应比分片的数量多得多。这是因为分区键用来确定如何将数据记录映射到特定分片。
如果您有足够的分区键,数据可以在流中的分片间均匀分布。
有关更多信息,请参阅 向流添加数据 (p. 48)(包括 Java 示例代码)、Streams API 中的 PutRecords 和
PutRecord 操作,或 put-record 命令。
Amazon Kinesis Streams 的使用器
Abstract
了解 Amazon Kinesis Streams 的使用器。
使用器 (p. 6)从 Amazon Kinesis stream 获取数据记录。称为 Amazon Kinesis Streams application 的使
用器处理来自流的数据记录。
Important
数据记录默认可在其添加到流的 24 小时内访问。此时间范围称为保留期,并且可以在从 24 到
168 小时(1 到 7 天)的范围内按小时为增量进行配置。有关流的保留期的更多信息,请参阅the
section called “更改数据保留期” (p. 95)。
每个使用器使用分片迭代器从特定分片进行读取。分片迭代器 表示使用器将从中读取的流中的位置。开
始从流中读取时,使用器获取分片迭代器,这可用于更改使用器从流中读取数据的位置。当使用器执行读
取操作时,它将收到一批基于由分片迭代器指定的位置的数据记录。
每个使用器必须有一个唯一名称,其范围限定于应用程序使用的 AWS 账户和区域。此名称用作 Amazon
DynamoDB 中的控制表名称和 Amazon CloudWatch 指标的命名空间。在您的应用程序启动时,它将创
建一个 Amazon DynamoDB 表来存储应用程序状态,连接到指定的流,然后开始使用流中的数据。您可
以使用 CloudWatch 控制台查看 Streams 指标。
您可以通过将使用器添加到 AMI 来将其部署到 EC2 实例。您可以通过在 Auto Scaling 组下的多个 EC2
实例上运行使用器来扩展它。使用 Auto Scaling 组可帮助在 EC2 实例发生故障时自动启动新的实例,还
可以在应用程序上的负载随着时间的推移发生更改时弹性扩展实例数。Auto Scaling 组可确保特定数目的
EC2 实例始终运行。要在 Auto Scaling 组中触发扩展事件,您可以指定指标(例如 CPU 和内存使用率)
来扩大或缩小处理流中数据的 EC2 实例的数目。有关更多信息,请参阅 Auto Scaling 入门指南。
6
Amazon Kinesis Streams 开发人员指南
限制
您可以使用 Amazon Kinesis Client Library (KCL) 按 EC2 实例队列上运行的工作程序队列来简化流的并
行处理。KCL 简化用于从流的分片中读取的代码的编写并确保为流中的每个分片分配一个工作程序。KCL
还通过提供检查点功能来提供容错帮助。开始使用 KCL 的最佳方式是查看 使用 Amazon Kinesis Client
Library 开发 Amazon Kinesis Streams 使用器 (p. 61) 中的示例。
Amazon Kinesis Streams 限制
Abstract
列出 Amazon Kinesis Streams 的大小和限制。
Streams 有以下限制。
• 仅以下区域的默认分片限制为 50 分片:
• US East (N. Virginia)
• 美国西部(俄勒冈)
• 欧洲(爱尔兰)
所有其他区域的默认分片限制为 25。
一个流或账户中的分片数没有上限。要请求增大分片限制,请使用 Streams 限制表单。
• 数据记录默认可在其添加到流的 24 小时内访问。此时间范围称为保留期,并且可以在从 24 到 168 小
时(1 到 7 天)的范围内按小时为增量进行配置。有关流的保留期的更多信息,请参阅the section called
“更改数据保留期” (p. 95)。
• 数据 Blob 的最大大小(Base64 编码前的数据有效载荷)是 最多 1 MB。
• CreateStream、DeleteStream 和 ListStreams 可提供 每秒最多 5 次交易。
• MergeShards 和 SplitShard 可提供 每秒最多 5 次交易。
• DescribeStream 可提供 每秒最多 10 次交易。
• GetShardIterator 可提供 每个打开的分片每秒最多 5 次交易。
• GetRecords 可检索数据的 10 MB。
• 每个分片可支持 最多 5 transactions per second 可用于读取,最多可达的最大总数据读取速率为 2 MB
per second。
• 每个分片可支持 最多 1,000 records per second 可用于写入,最多可达的最大总数据写入速率为 1 MB
per second (including partition keys)。此写入限制适用于 PutRecord 和 PutRecords 等操作。
• GetShardIterator 返回的分片迭代器在处于未使用状态 5 分钟后将超时。
读取限制基于打开的分片数。有关分片状态的更多信息,请参阅 分片之后的数据路由、数据保留和分片
状态 (p. 95)。
其中很多限制与 API 操作直接相关。有关更多信息,请参见 Amazon Kinesis API Reference。
7
Amazon Kinesis Streams 开发人员指南
设置
开始使用 Amazon Kinesis Streams
Abstract
针对 Amazon Kinesis Streams 新用户的主题。
本节提供了多个主题,以帮助您开始使用 Amazon Kinesis Streams。如果您不熟悉 Streams,在使用本
文档之前,请花点时间熟悉一下 什么是 Amazon Kinesis Streams? (p. 1) 节中介绍的概念和术语。
主题
• 设置 Amazon Kinesis Streams (p. 8)
• 教程:使用 Amazon Kinesis Streams 可视化 Web 流量 (p. 9)
• 教程:Amazon Kinesis Streams 的 AWS CLI 使用入门 (p. 17)
设置 Amazon Kinesis Streams
Abstract
完成以下步骤以便为首次使用 Amazon Kinesis Streams 做好准备。
首次使用 Amazon Kinesis Streams 之前,请完成以下任务。
任务
• 注册 AWS (p. 8)
• 下载库和工具 (p. 9)
• 配置您的开发环境 (p. 9)
注册 AWS
当您注册 Amazon Web Services (AWS) 时,您的 AWS 账户会自动注册 AWS 中的所有服务,包括
Streams。您只需为使用的服务付费。
如果您已有一个 AWS 账户,请跳到下一个任务。如果您还没有 AWS 账户,请使用以下步骤创建。
8
Amazon Kinesis Streams 开发人员指南
下载库和工具
如需注册 AWS 账户
1.
打开 http://www.amazonaws.cn/,然后选择 Create an AWS Account。
2.
按照屏幕上的说明进行操作。
作为注册流程的一部分,您会收到一个电话,需要您使用电话键盘输入一个 PIN 码。
下载库和工具
以下库和工具可帮助您使用 Streams:
• Amazon Kinesis API Reference 是 Streams 支持的一组基本操作。有关使用 Java 代码执行基本操作
的更多信息,请参阅 the section called “使用 API” (p. 48)、the section called “使用 API” (p. 75) 和 the
section called “管理流” (p. 87)。
• 适用于 Java、JavaScript、.NET、Node.js、PHP、Python 和 Ruby 的 AWS 开发工具包包括 Streams
支持和示例。
如果您的 AWS SDK for Java版本不包括 Streams 的示例,您还可以从 GitHub 下载它们。
• Amazon Kinesis Client Library (KCL) 提供了一个易于使用的编程模型来处理数据。KCL 可帮助您快速
开始使用 Streams,有关更多信息,请参阅使用 Amazon Kinesis Client Library 开发 Amazon Kinesis
Streams 使用器 (p. 61)。KCL 可用于 Java、Python 和 Ruby:
• Amazon Kinesis Client Library (Java)
• Amazon Kinesis Client Library (Python)
• Amazon Kinesis Client Library (Ruby)
• AWS Command Line Interface支持 Streams。利用 AWS CLI,您可以从命令行管理多个 AWS 服务并
通过脚本自动执行这些服务。
• (可选)Amazon Kinesis Connector Library可帮助您将 Streams 与其他 AWS 服务集成。例如,您可
以将 Amazon Kinesis Connector Library与 KCL 结合使用,以便将数据可靠地从 Streams 移动到 Amazon
DynamoDB、Amazon Redshift 和 Amazon S3。
配置您的开发环境
要使用 KCL,请确保您的 Java 开发环境符合以下要求:
• Java 1.7 (Java SE 7 JDK) 或更高版本。您可以从 Oracle 网站上的 Java SE 下载页面下载最新的 Java
软件。
• Apache Commons 程序包(代码、HTTP 客户端和日志记录)
• Jackson JSON 处理器
请注意,AWS SDK for Java将 Apache Commons 和 Jackson 包含在第三方文件夹中。但是,适用于
Java 的开发工具包适用于 Java 1.6,而 Amazon Kinesis Client Library则需要 Java 1.7。
教程:使用 Amazon Kinesis Streams 可视化 Web
流量
Abstract
设置和运行 Amazon Kinesis Streams 数据可视化示例应用程序。
9
Amazon Kinesis Streams 开发人员指南
Streams 数据可视化示例应用程序
本教程通过介绍关键 Streams 结构(具体而言就是流 (p. 4)、数据创建器 (p. 6)和数据使用器 (p. 6))
来帮助您开始使用 Amazon Kinesis Streams。本教程使用了基于实时数据分析的常用案例的示例应用程
序,如什么是 Amazon Kinesis Streams? (p. 1) 中所述。
Streams 数据可视化示例应用程序
在本教程中,您将构建一个数据可视化示例应用程序,该示例应用程序演示如何将 Streams 用于实时数
据注入和分析。该示例应用程序将创建一个数据创建器,该数据创建器会将来自各个 URL 的模拟访问者
计数放入一个 Amazon Kinesis stream。该流将以接收这些数据记录的顺序长期存储它们。数据使用器将
从该流中获取这些记录,然后计算多少访问者来自某个特定 URL。最后,一个简单的 Web 应用程序将实
时轮询结果以提供计算的可视化,如下图所示。
此示例应用程序将演示在 10 秒的期限内执行滑动窗口分析的常用流处理案例。上述可视化中显示的数据
以持续更新的图表的形式反映流的滑动窗口分析结果。此外,数据使用器将对数据流执行 Top-K 分析,
以计算在计数上排名前三的引用站点,它们将立即显示在图表下方的表格中,并且每两秒更新一次。
为了让您快速入门,该示例应用程序使用了 AWS CloudFormation。利用 AWS CloudFormation,您可以
创建示例模板来介绍 AWS 资源以及运行应用程序所需的任何关联依赖项或运行时参数。该示例应用程序
使用示例模板来快速创建所有必要的资源,包括在 Amazon Elastic Compute Cloud (Amazon EC2) 上运
行的创建器和使用器应用程序以及 Amazon DynamoDB 中用来存储聚合记录计数的表。
先决条件
本指南将帮助您设置、运行和查看 Streams 数据可视化示例应用程序的结果。要开始使用示例应用程序,
您首先需要执行以下操作:
• 使用运行正常的 Internet 连接设置计算机。
• 注册 AWS 账户。
• 此外,通读简介部分以大致了解流 (p. 4)、数据创建器 (p. 6)和数据使用器 (p. 6)。
步骤 1:启动示例应用程序
本过程将使用 AWS CloudFormation 模板创建示例应用程序。该应用程序有一个流写入器(随机生成记
录并将其发送到 Amazon Kinesis stream)、一个数据使用器(计算针对某个资源的 HTTPS 请求的计数)
和一个 Web 应用程序(以持续更新的图表的形式显示流处理数据的输出)。
Note
在应用程序启动后,它将产生针对 Streams 使用的名义费用。在可能的情况下,示例应用程序将
使用有资格享受免费套餐的资源。当您完成本教程时,请删除 AWS 资源以停止产生费用。有关
更多信息,请参阅 步骤 3:删除示例应用程序资源 (p. 16)。
启动应用程序
1.
2.
启动链接的 AWS CloudFormation 模板,该模板包含为您填写的所有必填字段。
在前三个表上单击 Next,无需修改预填写的值。这应该会将您转到 IAM 资源确认,类似于下图:
10
Amazon Kinesis Streams 开发人员指南
步骤 2:查看示例应用程序的组件
3.
检查已代表您设置的所有参数并单击复选框以确认可能的 IAM 资源创建。单击 Create (创建)。
接下来,您应该会看到一个状态为“CREATE_IN_PROGRESS”的堆栈。创建该堆栈可能需要几分钟,但
当状态被标记为“CREATE_COMPLETE”时,请继续下一步。如果状态未更新,请单击刷新按钮。
步骤 2:查看示例应用程序的组件
Amazon Kinesis Stream
流 (p. 4)能够实时注入来自大量创建器的数据、长期存储这些数据,并将这些数据提供给多个使用器。
流表示数据记录的有序序列。可以使用 CreateStream 操作或通过 AWS 管理控制台以编程方式创建流。
CreateStream 操作需要两个参数:流名称和分片计数。一个流包含一个或多个分片;每个分片是一组
数据记录。
AWS CloudFormation 会根据提供的模板自动创建“数据可视化示例应用程序”流。AWS CloudFormation
模板的此部分显示了 CreateStream 操作中使用的参数。您可以按照下面的指示来查看示例应用程序的
流。
Note
从 AWS CloudFormation 模板创建应用程序堆栈并将有意义的数据显示在 Stream Details 页面上
大约需要 10 分钟。
查看堆栈详细信息
1.
创建堆栈后,打开(或者在必要时刷新)AWS CloudFormation 控制台。选择 KinesisDataVisSample
堆栈。控制台会将堆栈详细信息显示在控制台窗口的下部。
11
Amazon Kinesis Streams 开发人员指南
步骤 2:查看示例应用程序的组件
2.
3.
选择 Outputs 选项卡,然后单击 URL 字段中的链接。URL 的形式应类似于
“http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com”。
实时数据分析图将显示在名为 Streams Data Visualization Sample 的单独页面上。它显示了引用 URL
在 10 秒的时间范围内发送的请求数,该图表每 1 秒更新一次。图表的时间范围是最近 2 分钟。
查看流详细信息
1.
2.
3.
登录 AWS 管理控制台 并通过以下网址打开 Amazon Kinesis 控制台:https://console.amazonaws.cn/
kinesis。
在 Stream List 页面上,您应该会看到一个包含两个分片且状态为 ACTIVE 的流。该流的名称以
“KinesisDataVisSampleApp-KinesisStream-[RandomString]”开头。单击该流的链接可打开 Stream
Details 页面。
查看下图中的流统计数据:
• 写入容量和读取容量(以每秒的字节数为单位)
• 放入延迟和获取延迟(以毫秒为单位)
• 放入请求和获取请求(直接计数)
此示例中的流包含两个分片,这两个分片可接收来自创建器的数据并使数据对使用器可用。每个分片有 2
MB/秒的写入容量和 4 MB/秒的读取容量。Put and Get Requests 图将实际放入和获取活动显示为蓝色。
这些图表显示了将记录放入流中的示例应用程序的数据创建器以及从流中获取和处理数据的数据使用器。
12
Amazon Kinesis Streams 开发人员指南
步骤 2:查看示例应用程序的组件
数据创建器
数据创建器 (p. 6)向 Amazon Kinesis stream 提交数据记录。为了将数据放入流中,创建器会对流调用
PutRecord 操作。
每个 PutRecord 调用都需要流名称、分区键和创建器正在添加到流的数据记录。流名称用于确定记录所
在的流。分区键用于确定数据记录要添加到的流中的分片。
使用哪个分区键取决于您的应用程序逻辑。在大多数情况下,分区键的数量应比分片的数量多得多。分区
键的数量多于分片的数量可让流将数据记录均匀地分布在流中的各个分片中。
数据可视化示例应用程序的数据创建器 使用六个常用 URL 作为放入到包含两个分片的流中的每个记录的
分区键。这些 URL 代表模拟的页面访问。HttpReferrerKinesisPutter 代码的 99-136 行会将数据发送到
Streams。三个必需参数是在调用 PutRecord 之前设置的。分区键是使用 pair.getResource() 设置
的,该命令将随机选择在 HttpReferrerStreamWriter 代码的 85-92 行中创建的六个 URL 之一。
数据创建器可以是将数据放入 Streams 的任何东西,如 EC2 实例、客户端浏览器或移动设备。示例应用
程序对其数据创建器和数据使用器使用一个 EC2 实例;然而,在大多数现实世界情景中,示例应用程序
的每个组件都有单独的 EC2 实例。您可以按照以下指示从示例应用程序查看 EC2 实例数据。
13
Amazon Kinesis Streams 开发人员指南
步骤 2:查看示例应用程序的组件
在控制台中查看实例数据
1.
登录 AWS 管理控制台 并通过以下网址打开 Amazon EC2 控制台 https://console.amazonaws.cn/
ec2/。
2.
在导航菜单中,单击 Instances。此时将列出您的所有实例(处于活动或终止状态),包括最近创建
的实例。
单击 Streams 示例应用程序的实例;很多选项卡将出现在列表下方。该实例包含一个以
“KinesisDataVisSampleApp”开头的安全组。选择 Description 选项卡。
单击 Monitoring 选项卡,该选项卡将显示示例应用程序的数据创建器和使用器的资源使用情况。
3.
4.
数据使用器
数据使用器 (p. 6)从 Amazon Kinesis stream 的分片中检索和处理数据记录。每个使用器都从一个特定
分片中读取数据。使用器使用 GetShardIterator 和 GetRecords 操作从分片中检索数据。
GetShardIterator 返回分片一个迭代器,该迭代器表示使用器将从中读取数据的流和分片的位置。当
使用器开始从流中读取记录或更改要从流中读取记录的位置时,它就会调用此操作。每个
GetShardIterator 调用都需要流名称、分片 ID 和分片迭代器类型。利用分片迭代器类型,使用器可
以指定要从流中的哪个位置开始读取记录(例如从数据实时到达的流的开头)。
GetRecords 将根据所需的分片迭代器在流中指定的位置返回记录。流批量返回记录,您可以使用可选的
限制参数控制其大小。
使用器应用程序可使用 Amazon Kinesis 客户端库 (KCL) 来简化流的并行处理。KCL 负责许多与分布式计
算相关的复杂任务,例如对多个实例进行负载均衡、对实例故障做出响应、对已处理的数据执行检查点操
作和对重新分片做出反应。KCL 可让您将精力放在编写记录处理逻辑上。
数据可视化示例应用程序的数据使用器将使用 KCL 在 DynamoDB 中创建一个表,用来保留应用程序的
状态信息(如检查点和工作程序-分片映射)。每个应用程序都有自己的 DynamoDB 表。您可以在下面找
到查看 KCL 创建的名为 KinesisDataVisSampleApp-KCLDynamoDBTable 的 DynamoDB 表的指示。
示例应用程序的数据使用器对最近两秒来自每个特定 URL 的访问者请求进行计数。此类型的实时应用程
序对滑动窗口采用 Top-N 分析。在这种情况下,Top-N 是访问者请求的前三页,而滑动窗口为两秒。这
是常见的处理模式,体现了现实情况下使用 Streams 进行的数据分析。此计算的结果保存在 DynamoDB
表中。您可以在下面找到查看 KCL 创建的名为 KinesisDataVisSampleApp-CountsDynamoDBTable 的
DynamoDB 表的指示。
查看 Amazon DynamoDB 表
1.
2.
登录 AWS 管理控制台 并通过以下网址打开 DynamoDB 控制台:https://console.amazonaws.cn/
dynamodb/。
DynamoDB 控制台列出了您的 AWS 账户中的所有表。该列表包含示例应用程序创建的两个表。每
个表名称以以下名称开头,后面附带一个随机生成的唯一标识符:
• KinesisDataVisSampleApp-KCLDynamoDBTable - KCL 创建的用于管理状态信息的表。
• KinesisDataVisSampleApp-CountsDynamoDBTable - 示例应用程序创建的表,用来保存对滑动窗
口的 Top-N 分析的结果。
3.
4.
单击 List Tables 然后单击 KinesisDataVisSampleApp-KCLDynamoDBTable 可查看表结构。您可以
在表中看到两个条目,指示特定分片 (leaseKey)、流中的位置 (checkpoint) 和读取数据的应用程序
(leaseOwner)。
单击 List Tables 然后单击 KinesisDataVisSampleApp-CountsDynamoDBTable 可查看表结构。您可
以查看聚合的访问者计数 (referrerCounts),该计数是数据使用器作为滑动窗口分析的一部分计算的。
14
Amazon Kinesis Streams 开发人员指南
步骤 2:查看示例应用程序的组件
示例应用程序的数据使用器组件向 KCL 提供了它要在其中读取数据的流的位置,在本例中为指定来自流
的开头的最新可能数据。库使用此数据来代表使用器调用 GetShardIterator。使用器组件还向客户端
库提供了要对使用名为 IRecordProcessor 的重要 KCL 接口处理的记录执行的操作。KCL 代表使用器
调用 GetRecords,然后按照 IRecordProcessor 的指示处理这些数据。
• HttpReferrerCounterApplication 示例代码的 92-98 行配置 KCL。这将使用库的初始配置来设置库,例
如设置要在其中读取数据的流的位置。
• HttpReferrerCounterApplication 示例代码的 104-108 行告知 KCL 在使用重要的客户端库组件
IRecordProcessor 处理记录时要使用的逻辑。
• CountingRecordProcessor 示例代码的 186-203 行包含使用 IRecordProcessor 的 Top-N 分析的计
数逻辑。
带实时控制面板的 Web 应用程序
Streams 的一个关键优势是能够支持多个应用程序同时从同一个流读取数据。不同的应用程序可在处理一
个流中的记录的同时执行各自的活动。例如,一个应用程序可以将数据存档到 Amazon S3,而另一个应
用程序可以在同一时间聚合指标并将其发送到 Amazon Redshift。
Streams 与其他分析产品(包括其他 AWS 服务和开源工具)集成在一起。Kinesis 连接器库(请勿与之
前讨论的 Kinesis 客户端库混淆)支持 Amazon S3、DynamoDB 和 Amazon Redshift,并且开发人员能
将该库与流结合使用。在处理流中的数据时,Kinesis 连接器库甚至提供了更多工具。
数据可视化示例应用程序的 Web 应用程序 使用一个简单的 JavaScript 应用程序来轮询 DynamoDB 表,
该表用于存储对滑动窗口的 Top-N 分析的结果。该应用程序将采用此数据并创建结果的可视化效果。
查看实时数据分析图
1.
2.
3.
登录 AWS 管理控制台 并通过以下网址打开 AWS CloudFormation 控制台:https://
console.amazonaws.cn/cloudformation/。
选择 AmazonKinesisDataVisSample 并导航至 Outputs 选项卡。单击 URL 中的链接,该链接应类似
于:http://ec2-xx-xx-xx-xx.compute-1.amazonaws.com。
实时数据分析图将显示在名为 Amazon Kinesis Data Visualization Sample 的单独页面上。
15
Amazon Kinesis Streams 开发人员指南
步骤 3:删除示例应用程序资源
步骤 3:删除示例应用程序资源
AWS 已尽力将示例应用程序资源纳入免费套餐(Streams 服务除外)。该应用程序将创建两个分片,它
运行时将针对分片的使用产生费用。要确保您的 AWS 账户不会被继续计费,请确保删除您的 AWS
CloudFormation 堆栈。
删除应用程序资源
1.
2.
登录 AWS 管理控制台 并通过以下网址打开 AWS CloudFormation 控制台:https://
console.amazonaws.cn/cloudformation/。
选择您创建的堆栈并单击 Delete Stack。在 AWS CloudFormation 清除与示例应用程序关联的资源
时,状态会更改为 DELETE_IN_PROGRESS。当 AWS CloudFormation 完成删除所有资源时,该堆
栈将从列表中删除。
步骤 4:后续步骤
• 您可以在 GitHub 上浏览数据可视化示例应用程序 的源代码。
• 您可以在《开发人员指南》的 the section called “使用 API” (p. 48)、the section called “使用 API” (p. 75)
和 the section called “管理流” (p. 87) 这三节中找到有关使用 Streams API 操作的更多高级材料。
• 最新的适用于 Java 的 AWS 开发工具包包含另一个示例应用程序,该示例应用程序将指导您使用开发
工具包将数据放入 Streams 和从其中获取数据。
16
Amazon Kinesis Streams 开发人员指南
教程:开始使用 CLI
教程:Amazon Kinesis Streams 的 AWS CLI 使用
入门
Abstract
了解如何使用 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. 17)
• 执行基本流操作 (p. 19)
安装和配置 AWS CLI
Abstract
安装和配置 AWS CLI。
安装 AWS CLI
本节介绍如何安装适用于 Windows 以及适用于 Linux、OS X 和 Unix 操作系统的 AWS CLI。
Windows
1.
从 AWS Command Line Interface 用户指南 中的完整安装说明的“Windows”部分下载相应的 MSI 安
装程序。
2.
运行下载的 MSI 安装程序。
3.
按显示的说明执行操作。
Linux, OS X, 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。
17
Amazon Kinesis Streams 开发人员指南
安装和配置 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
o wait
此命令列表与 Amazon Kinesis 服务 API 参考中记录的 Streams API 对应。例如,create-stream 命令
与 CreateStream API 操作对应。
AWS CLI 现已成功安装,但未配置。这将在下一节展示。
配置 AWS CLI
对于一般用途,aws configure 命令是设置 AWS CLI 安装的最快方法。如果您的首选项不更改,这将
是一次性设置,因为 AWS CLI 会在不同会话之间记住您的设置。
18
Amazon Kinesis Streams 开发人员指南
执行基本流操作
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 将提示四种信息。AWS 访问密钥 ID 和 AWS 秘密密钥是您的账户凭证。如果您没有密钥,请
参阅注册 Amazon Web Services。
默认区域是您希望默认对其进行调用的区域的名称。通常是离您最近的区域,但可以是任意区域。
Note
使用 AWS CLI 时必须指定 AWS 区域。有关服务和可用区域的列表,请参阅区域和终端节点。
默认输出格式可以是 json、文本或表。如果不指定输出格式,将使用 json。
有关 aws configure 创建的文档、附加设置和命名配置文件的更多信息,请参阅 AWS Command Line
Interface 用户指南中的配置 AWS 命令行界面。
执行基本流操作
Abstract
了解如何使用 AWS CLI 执行基本流操作。
本节介绍如何通过 AWS CLI 从命令行对 Amazon Kinesis stream 执行基本操作。确保您熟悉 Amazon
Kinesis Streams 主要概念 (p. 2)和教程:使用 Amazon Kinesis Streams 可视化 Web 流量 (p. 9)中讨
论的概念。
Note
在创建流后,将象征性地向您的账户收取 Streams 使用费,因为 Streams 没有获得 AWS 免费套
餐的资格。当您完成本教程时,请删除 AWS 资源以停止产生费用。有关更多信息,请参阅 步骤
4:清除 (p. 23)。
主题
• 第 1 步:创建流 (p. 19)
• 步骤 2:放置记录 (p. 20)
• 步骤 3:获取记录 (p. 21)
• 步骤 4:清除 (p. 23)
第 1 步:创建流
您的第一步是创建一个流并验证它是否已创建成功。使用以下命令创建一个名为“Foo”的流:
aws kinesis create-stream --stream-name Foo --shard-count 1
参数 --shard-count 是必需的,并且在本教程的这一部分中,您将在您的流中使用一个分片。接下来,
发出以下命令以检查流的创建进度:
aws kinesis describe-stream --stream-name Foo
19
Amazon Kinesis Streams 开发人员指南
执行基本流操作
您应获得类似于以下示例的输出:
{
"StreamDescription": {
"StreamStatus": "CREATING",
"StreamName": "Foo",
"StreamARN": "arn:aws:kinesis:us-west-2:<account i.d.>:stream/Foo",
"Shards": []
}
}
在此示例中,流的状态为 CREATING,这表示它还未完全做好使用准备。在几分钟后再次检查,您应看
到类似于以下示例的输出:
{
"StreamDescription": {
"StreamStatus": "ACTIVE",
"StreamName": "Foo",
"StreamARN": "arn:aws:kinesis:us-west-2:<account i.d.>:stream/Foo",
"Shards": [
{
"ShardId": "shardId-000000000000",
"HashKeyRange": {
"EndingHashKey": "170141183460469231731687303715884105727",
"StartingHashKey": "0"
},
"SequenceNumberRange": {
"StartingSequenceNumber":
"49546986683135544286507457935754639466300920667981217794"
}
}
]
}
}
此输出包含您在本教程中无需关注的信息。目前,您需要重点关注的是 "StreamStatus": "ACTIVE"(告
知您流已做好使用准备)和有关您请求的单个分片的信息。您还可以通过使用 list-streams 命令验证
您的新流是否存在,如下所示:
aws kinesis list-streams
输出:
{
"StreamNames": [
"Foo"
]
}
步骤 2:放置记录
既然您已经拥有活动的流,您便已做好放置一些数据的准备。在本教程中,您将使用最简单的命令
put-record,该命令会将一个包含文本“testdata”的数据记录放入流中:
20
Amazon Kinesis Streams 开发人员指南
执行基本流操作
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 --shard-iteratortype TRIM_HORIZON --stream-name Foo
请记住,aws kinesis 命令后面有一个 Streams API,因此如果您对显示的任何参数感兴趣,都可以在
GetShardIterator API 参考主题中阅读有关它们的信息。执行成功将产生与以下示例类似的输出(水
平滚动可查看完整输出):
{
"ShardIterator": "AAAAAAAAAAHSywljv0zEgPX4NyKdZ5wryMzP9yALs8NeK
bUjp1IxtZs1Sp+KEd9I6AJ9ZG4lNR1EMi+9Md/nHvtLyxpfhEzYvkTZ4D9DQVz/mBY
WRO6OTZRKnW9gd+efGN2aHFdkH1rJl4BL9Wyrk+ghYG22D2T1Da2EyNSH1+LAbK33gQweTJADBdyM
wlo5r6PqcP2dzhg="
}
看起来像随机字符的长字符串就是分片迭代器(您的字符串将与此不同)。您需要将分片迭代器复制/粘
贴到接下来显示的 get 命令中。分片迭代器的有效生命周期为 300 秒,应该足以让您将分片迭代器复制/
粘贴到下一个命令中。请注意,在将分片迭代器粘贴到写一个命令之前,您需要从中删除所有换行符。如
果您收到分片迭代器不再有效的错误消息,只需再次执行 get-shard-iterator 命令。
get-records 命令从流中获取数据,并解析为对 Streams API 中的 GetRecords 的调用。分片迭代器
指定了分片中的一个位置,您希望从该位置开始按顺序读取数据记录。如果迭代器指向的分片中的部分没
有可用的记录,GetRecords 将返回空白列表。请注意,可能需要进行多次调用才能到达分片中包含记录
的部分。
在以下 get-records 命令示例中(水平滚动可查看完整命令):
aws kinesis get-records --shard-iterator AAAAAAAAAAHSywljv0zEgPX4NyK
dZ5wryMzP9yALs8NeKbUjp1IxtZs1Sp+KEd9I6AJ9ZG4lNR1EMi+9Md/nHvtLyxpf
hEzYvkTZ4D9DQVz/mBYWRO6OTZRKnW9gd+efGN2aHFdkH1rJl4BL9Wyrk+ghYG22D2T1Da2EyN
SH1+LAbK33gQweTJADBdyMwlo5r6PqcP2dzhg=
如果您是从 Unix 类型的命令处理器(如 bash)运行本教程,则可以使用嵌套命令自动执行分片迭代器的
获取,如下所示(水平滚动可查看完整命令):
SHARD_ITERATOR=$(aws kinesis get-shard-iterator --shard-id shardId-000000000000
--shard-iterator-type TRIM_HORIZON --stream-name Foo --query 'ShardIterator')
21
Amazon Kinesis Streams 开发人员指南
执行基本流操作
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 --stream-name
Foo).split('"')[4])
get-records 命令的成功结果将从您在获取分片迭代器时指定的分片的流中请求记录,如以下示例所示
(水平滚动可查看完整输出):
{
"Records":[ {
"Data":"dGVzdGRhdGE=",
"PartitionKey":"123”,
"ApproximateArrivalTimestamp": 1.441215410867E9,
"SequenceNumber":"49544985256907370027570885864065577703022652638596431874"
} ],
"MillisBehindLatest":24000,
"NextShardIterator":"AAAAAAAAAAEDOW3ug
seWPE4503kqN1yN1UaodY8unE0sYslMUmC6lX9hlig5+t4RtZM0/tALfiI4QGjunVgJvQsjxjh2aLyx
aAaPr+LaoENQ7eVs4EdYXgKyThTZGPcca2fVXYJWL3yafv9dsDwsYVedI66dbMZFC8rPM
Wc797zxQkv4pSKvPOZvrUIudb8UkH3VMzx58Is="
}
请注意,get-records 在上面被描述为请求,这意味着即使您的流中有记录,您可能也会收到零个或零
个以上的记录,并且任何返回的记录都无法表示当前您的流中的所有记录。这是完全正常的,并且生产代
码只会以适当的时间间隔轮询流中的记录(此轮询速度因您的特定应用程序设计要求而异)。
在本教程的这一部分,您可能首先注意到的与您的记录的有关的事情是:数据似乎是垃圾代码;它不是我
们发送的明文 testdata。这归因于 put-record 使用 Base64 编码支持您发送二进制数据的方式。但
是,AWS CLI 中的 Streams 支持未提供 Base64 解码,因为对输出到 stdout 的原始二进制内容的 Base64
解码在某些平台和终端上可能会导致非预期的行为和潜在的安全问题。如果您使用 Base64 解码程序(例
如,https://www.base64decode.org/)对 dGVzdGRhdGE= 进行手动解码,您将看到它实际上是 testdata。
这对本教程来说已足够,在实践中,AWS CLI 很少用于使用数据,更多时候是用于监控流的状态和获取
信息,如前面所示(describe-stream 和 list-streams)。将来的教程将向您展示如何使用 Amazon
Kinesis 客户端库 (KCL) 构建生产质量的使用器应用程序,KCL 将会为您处理 Base64。有关 KCL 的更多
信息,请参阅使用 Amazon Kinesis Client Library 开发 Amazon Kinesis Streams 使用器 (p. 61)。
get-records 并非总是会返回在流/分片中指定的所有记录。当出现这种情况时,请使用最后一个结果中
的 NextShardIterator 获取下一组记录。因此,如果更多数据正在被放入流中(正常情况下在生产应
用程序中),您每次都可以使用 get-records 持续轮询数据。但是,如果您在 300 秒的分片迭代器生
命周期内未使用下一个分片迭代器调用 get-records,则会收到一条错误消息,并且需要使用
get-shard-iterator 命令来获取新的分片迭代器。
此输出中还提供了 MillisBehindLatest,它是从流的末端响应 GetRecords 操作的毫秒数,指示使
用者落后当前时间多远。零值指示正进行记录处理,此时没有新的记录要处理。在本教程中,如果您一边
阅读教程一边操作,则可能会看到这个数值非常大。这不是问题,数据记录将会在流中保留 24 小时以等
待您进行检索。此时间范围称为保留期,可以配置为最多 168 小时(7 天)。
请注意,一个成功的 get-records 结果总是有一个 NextShardIterator,即使目前流中没有更多记
录。这是一个假定创建器在任何给定时间内正在将更多记录放入流中的轮询模型。虽然您可编写自己的轮
询例程,但如果您使用之前提到的 KCL 开发使用者应用程序,则系统将会为您执行此轮询。
22
Amazon Kinesis Streams 开发人员指南
执行基本流操作
如果您调用 get-records,直到您正在提取的流和分片中没有更多记录,您将看到带有空白记录的输
出,类似于以下示例(水平滚动可查看完整输出):
{
"Records": [],
"NextShardIterator": "AAAAAAAAAAGCJ5jzQNjmdhO6B/YDIDE56jmZm
rmMA/r1WjoHXC/kPJXc1rckt3TFL55dENfe5meNgdkyCRpUPGzJpMgYHaJ53C3nCA
jQ6s7ZupjXeJGoUFs5oCuFwhP+Wul/EhyNeSs5DYXLSSC5XCapmCAYGFjYER69QSdQjxMmBPE/hiybF
Di5qtkT6/PsZNz6kFoqtDk="
}
步骤 4:清除
最后,如前所述,您希望删除您的流以释放资源和避免您的账户产生意外费用。在实践中,每当您创建了
不会使用的流时,请执行此操作,因为费用是按流量计算的,无论您是否在使用流放入和获取数据。清除
命令很简单:
aws kinesis delete-stream --stream-name Foo
成功之后不会生成输出,因此您可能希望使用 describe-stream 来检查删除进度:
aws kinesis describe-stream --stream-name Foo
如果您在执行删除命令后立即执行此命令,您可能会看到类似于以下示例的输出:
{
"StreamDescription": {
"StreamStatus": "DELETING",
"StreamName": "Foo",
"StreamARN": "arn:aws:kinesis:us-west-2:<account i.d.>:stream/Foo",
"Shards": []
}
}
在流完全删除后,describe-stream 将生成“未找到”错误:
A client error (ResourceNotFoundException) occurred when calling the Describe
Stream operation:
Stream Foo under account 980530241719 not found.
恭喜您!您已完成有关使用 AWS CLI 的 Streams 基础知识的本教程。
23
Amazon Kinesis Streams 开发人员指南
第一部分:流、创建器和使用器
学习 Amazon Kinesis Streams 开发
Abstract
Amazon Kinesis Streams 开发实践学习模块。
本部分中的模块旨在让您讲解精通 Streams 开发需要了解的内容。如果您不确定哪一款流服务适合于您,
请在什么是流数据?中查看比较信息。在开始之前,请确保您熟悉 Amazon Kinesis Streams 主要概
念 (p. 2) 和 教程:使用 Amazon Kinesis Streams 可视化 Web 流量 (p. 9) 中讨论的概念,特别是流、
分片、创建器和使用器。参阅 教程:使用 Amazon Kinesis Streams 可视化 Web 流量 (p. 9) 和 教程:
Amazon Kinesis Streams 的 AWS CLI 使用入门 (p. 17) 也很有帮助。
主题
• 第一部分:流、创建器和使用器 (p. 24)
第一部分:流、创建器和使用器
Abstract
了解如何将 Amazon Kinesis Streams 用于实时股票分析模拟。
本文档是说明如何在 Java 中针对 Amazon Kinesis Streams 进行开发的多部分系列教程的第一部分。如
果您不确定哪一款流服务适合于您,请在什么是流数据?中查看比较信息。
本模块的场景是将股票交易注入流中并编写用来对流执行计算的简单应用程序。在第一部分中,您将了解
如何将记录流发送到 Streams 并实施几乎能实时使用和处理记录的应用程序。在本系列的后续部分中,
场景将扩展以包含有关适用于大多数 Streams 业务应用程序的股票交易分析模型的更多中级和高级设计
和编程注意事项。
Important
在创建流后,将象征性地向您的账户收取 Streams 使用费,因为 Streams 没有获得 AWS 免费套
餐的资格。在使用器应用程序启动后,也会象征性地向您收取 DynamoDB 使用费。DynamoDB
由使用器应用程序用来跟踪处理状态。在使用完此应用程序后,请删除 AWS 资源以停止产生费
用。有关更多信息,请参阅 第 7 步:收尾 (p. 36)。
代码不访问实际股票市场数据,而是模拟股票交易流。它通过使用随机股票交易生成器(将截至 2015 年
2 月市值排名前 25 位的股票的实际市场数据作为起始点)来执行此操作。如果您有权访问实时的股票交
24
Amazon Kinesis Streams 开发人员指南
先决条件
易流,则可能有兴趣从该流派生有用且及时的统计数据。例如,您可能希望执行滑动窗口分析,从而确定
前 5 分钟内购买的最热门股票。或者,您可能希望在销售订单过大(即具有过多股份)时收到通知。可扩
展本系列中显示的代码以提供此类功能。
您可以在台式机或笔记本电脑上演练此模块中的步骤,然后在同一台计算机或支持已定义要求的任何平台
(如 Amazon EC2)上同时运行创建器和使用器代码。
显示的示例使用的是 美国西部(俄勒冈) 区域,但它可使用任何支持 Streams 的区域。
主题
• 先决条件 (p. 25)
• 第 1 步:创建流 (p. 26)
• 第 2 步:创建 IAM 策略和用户 (p. 26)
• 第 3 步:下载和构建实施代码 (p. 29)
• 第 4 步:实施创建器 (p. 30)
• 第 5 步:实施使用器 (p. 32)
• 第 6 步:(可选)扩展使用器 (p. 35)
• 第 7 步:收尾 (p. 36)
先决条件
Abstract
起始步骤。
Amazon Web Services 账户
在开始之前,请确保您熟悉 Amazon Kinesis Streams 主要概念 (p. 2) 和 教程:使用 Amazon Kinesis
Streams 可视化 Web 流量 (p. 9) 中讨论的概念,特别是流、分片、创建器和使用器。参阅 教程:使用
Amazon Kinesis Streams 可视化 Web 流量 (p. 9) 和 教程:Amazon Kinesis Streams 的 AWS CLI 使用
入门 (p. 17) 也很有帮助。
您需要 AWS 账户和 Web 浏览器才能访问 AWS 管理控制台。
对于控制台访问,请使用您的 IAM 用户名和密码登录AWS 管理控制台(使用 IAM 登录页面)。通过
IAM,您可以安全控制对您的 AWS 账户中的 AWS 服务与资源的访问。更多有关创建访问密钥的信息,
请参阅如何获取安全证书?(在 AWS General Reference 中)。
有关 IAM 和安全密钥设置说明的更多信息,请参阅创建 IAM 用户。
系统软件要求
用于运行应用程序的系统必须已安装 Java 7 或更高版本。要下载和安装最新 JDK,请转到 Oracle 的 Java
SE 安装站点。
如果您具有 Java IDE(如 Eclipse),则可打开源代码,然后编辑、构建并运行它。
您需要最新的 AWS SDK for Java 版本。如果您将 Eclipse 用作 IDE,则可改为安装 AWS Toolkit for
Eclipse。
使用器应用程序需要 Kinesis 客户端库 (KCL) 1.2.1 版或更高版本,您可以从 Amazon Kinesis Client Library
(Java)上的 Github 获得该版本。
25
Amazon Kinesis Streams 开发人员指南
第 1 步:创建流
第 1 步:创建流
Abstract
流创建。
在此步骤中,您可创建将在后续步骤中使用的流。
创建流
1.
2.
登录 AWS 管理控制台 并通过以下网址打开 Amazon Kinesis 控制台:https://console.amazonaws.cn/
kinesis。
在导航栏中,展开区域选择器并选择一个区域。
3.
4.
选择 Create Stream。
在 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”的复选框。根据以下准则输入平均记录大小、每秒写入的最大记录数以及使用的应用程序数:
Average Record Size
您的记录的计算平均大小的估计值。如果您不知道此值,请使用估计的最大记录大小作为此值。
Maximum Records Written/Second
考虑提供数据的实体的数量以及每个实体每秒生成的记录的大约数量。例如,如果要从 20 台交易服
务器获取股票交易数据,并且每台服务器每秒生成 250 次交易,则每秒的交易(记录)总数为 5000。
Number of Consuming Applications
应用程序的数量,这些应用程序单独从流进行读取以采用不同的方式处理流并生成不同的输出。每个
应用程序可具有在不同的计算机上运行(即在集群中运行)的多个实例,以便能跟进大容量流。
如果显示的估计分片数超过当前分片数限制,您可能需要先提交增大限制的请求,然后才能具有该数量的
分片的流。要请求增大分片限制,请使用 Streams 限制表单。有关流和分片的更多信息,请参阅 the
section called “Streams 技术” (p. 4) 和 the section called “管理流” (p. 87)。
第 2 步:创建 IAM 策略和用户
Abstract
创建 IAM 策略和用户。
AWS 的安全最佳实践描述了如何使用精细权限来控制对各种资源的访问。利用 AWS Identity and Access
Management,您可以管理 AWS 中的用户和用户权限。IAM 策略明确列出了允许的操作以及这些操作适
用于的资源。
26
Amazon Kinesis Streams 开发人员指南
第 2 步:创建 IAM 策略和用户
下面是 Streams 创建器和使用器通常需要的最低权限。
创建器:
操作
资源
目的
DescribeStream
Amazon Kinesis 在尝试写入记录前,创建器应检查流是否存在且处于活动状态。
stream
PutRecord、PutRecords Amazon Kinesis
stream
将记录写入 Streams。
使用器:
操作
资源
目的
DescribeStream
Amazon Kinesis 在尝试读取记录前,使用器需检查流是否存在并处于活动状态,以及分片是
stream
在流中。
GetRecords、GetShardIterator
Amazon Kinesis 从 Streams 分片读取记录。
stream
CreateTable、DeAmazon DynamoDB 表
scribeTable、
GetItem、PutItem、
PutMetricData、Scan、
UpdateItem
如果使用器是使用 Kinesis 客户端库 (KCL) 开发的,它需要 DynamoDB 表
能跟踪应用程序的处理状态。第一个使用器已开始创建表。
DeleteItem
Amazon DynamoDB 表
适用于使用器在 Streams 分片上执行拆分/合并操作时。
PutMetricData
Amazon CloudWatch 日志
KCL 还会将指标上传到 CloudWatch,这对于监控应用程序很有用。
对于此应用程序,您应创建授予上述所有权限的单个 IAM 策略。实际上,您可能需要考虑创建两个策略,
一个策略适用于创建器,另一个策略适用于使用器。您在此设置的策略可在本系列的后续学习模块中重复
使用。
创建 IAM 策略
1.
确定新流的 Amazon 资源名称 (ARN)。ARN 格式为:
arn:aws:kinesis:region:account:stream/name
region
区域代码;例如,us-west-2。有关区域代码的更多信息,请参阅区域和可用区概念。
account
AWS 账户 ID,如账户设置中所示。
name
the section called “第 1 步:创建流” (p. 26) 中的流名称,即 StockTradeStream。
2.
确定要由使用器使用(并由第一个使用器实例创建)的 DynamoDB 表的 ARN。它应采用以下格式:
arn:aws:dynamodb:region:account:table/name
27
Amazon Kinesis Streams 开发人员指南
第 2 步:创建 IAM 策略和用户
3.
区域和账户来自上一步骤中的相同位置,但这一次,name 为使用器应用程序创建和使用的表的名称。
使用器所使用的 KCL 将应用程序名称用作表名称。使用 StockTradesProcessor,它是稍后使用
的应用程序名称。
在 IAM 控制台中,转到策略节点 (https://console.amazonaws.cn/iam/home#policies),然后选择
Create Policy。如果这是您首次使用 IAM 策略,请选择 Get Started,然后选择 Create Policy。
4.
5.
6.
选择 Policy Generator 旁边的 Select。
选择 Amazon Kinesis 作为 AWS 服务。
选择 DescribeStream、GetShardIterator、GetRecords、PutRecord 和 PutRecords 作为
允许的操作。
7.
8.
输入您在步骤 1 中创建的 ARN。
对以下各项使用 Add Statement:
AWS 服务
操作
ARN
Amazon DynamoDB
CreateTable、DeleteItem、DescribeTable、GetItem、
PutItem、PutMetricData、Scan、UpdateItem
您在步骤 2 中创建的 ARN
Amazon CloudWatch
PutMetricData
*
在不需要指定 ARN 时可使用星号 (*)。在此示例中,这是因为 CloudWatch 中没有可对其调用
PutMetricData 操作的特定资源。
9. 选择 Next Step。
10. 将 Policy Name 重命名为 StockTradeStreamPolicy,审阅代码,然后选择 Create Policy。
控制台中显示的所生成的 Policy Document 应类似于以下内容:
{
"Version": "2012-10-17",
"Statement": [
{
"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:*"
],
28
Amazon Kinesis Streams 开发人员指南
第 3 步:下载和构建实施代码
"Resource": [
"arn:aws:dynamodb:us-west-2:123:table/StockTradesProcessor"
]
},
{
"Sid": "Stmt789",
"Effect": "Allow",
"Action": [
"cloudwatch:PutMetricData"
],
"Resource": [
"*"
]
}
]
}
创建 IAM 用户
1.
2.
3.
通过以下网址打开 IAM 控制台:https://console.amazonaws.cn/iam/。
在“Users”页面上,选择 Create New Users。
输入 StockTradeStreamUser,然后选择 Create。
4.
展开 Show User Security Credentials 节点,并将访问密钥和私有密钥保存到位于仅您可访问的安全
位置的本地文件中。对于此应用程序,请创建名为 ~/.aws/credentials(具有严格权限)的文
件。该文件应采用以下格式:
aws_access_key_id=<access key>
aws_secret_access_key=<secret key>
将 IAM 策略附加到用户
1.
2.
在 IAM 控制台中,转到 Policies 页面并选择 Policy Actions。
选择 StockTradeStreamPolicy 和 Attach。
3.
选择 StockTradeStreamUser 和 Attach Policy。
第 3 步:下载和构建实施代码
Abstract
下载提供的代码并构建它。
已为您提供框架代码,其中包含针对股票交易流注入(创建器)以及正在处理的数据(使用器)的存根实
施。以下过程演示如何完成实施。
下载和构建实施代码
1.
2.
3.
将源代码下载到计算机上。
使用源代码在您喜爱的 IDE 中创建一个项目,AWS 开发工具包和 Kinesis 客户端库将作为库添加到
该项目。
根据您的 IDE,项目可能会自动构建。如果未自动构建项目,请使用适合您的 IDE 的步骤构建项目。
29
Amazon Kinesis Streams 开发人员指南
第 4 步:实施创建器
如果已成功完成这些步骤,则可进入下一节。如果您的构建在任何阶段出错,您需要先调查并纠正错误,
然后才能继续。
第 4 步:实施创建器
Abstract
实施用于注入数据的创建器代码。
此应用程序使用股票市场交易监控的实际场景。以下准则简要说明了此场景如何映射到创建器和支持的代
码结构。
请参阅源代码并查看以下信息。
StockTrade 类
单次股票交易由一个 StockTrade 类实例表示,该类包含一些属性,如股票代号、价格、股份数、
交易类型(买入或卖出)以及用于唯一标识交易的 ID。将为您实现此类。
流记录
流是一个记录序列。记录是 JSON 格式的 StockTrade 实例序列化。例如:
{"tickerSymbol": "AMZN",
"tradeType": "BUY",
"price": 395.87,
"quantity": 16,
"id": 3567129045}
StockTradeGenerator 类
StockTradeGenerator 包含一个名为 getRandomTrade() 的方法,当调用此方法时,它将返回
一个随机生成的新股票交易。将为您实现此类。
StockTradesWriter 类
创建器的主类 StockTradesWriter 将持续检索随机交易,然后通过执行以下任务将该交易发送到
Streams:
1. 将流名称和区域名称作为输入读取
2. 从 ~/.aws/credentials 读取凭证
3. 使用这些凭证创建 AmazonKinesisClient。
4. 检查流是否存在且处于活动状态(如果不是这样,它将退出并显示错误)。
5. 在连续循环中,调用 StockTradeGenerator.getRandomTrade() 和 sendStockTrade 方法
以便每 100 毫秒将交易发送到流一次。
sendStockTrade 方法尚未实施。您将在下一节 实施创建器 (p. 30) 中实施此方法。
实施创建器
•
将以下代码添加到 StockTradesWriter 类的 sendStockTrade 方法:
private static void sendStockTrade(StockTrade trade, AmazonKinesis kinesis
Client, String streamName) {
byte[] bytes = trade.toJsonAsBytes();
// The bytes could be null if there is an issue with the JSON serializ
ation by the Jackson JSON library.
if (bytes == null) {
LOG.warn("Could not get JSON bytes for stock trade");
return;
}
30
Amazon Kinesis Streams 开发人员指南
第 4 步:实施创建器
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 Sup
plemental 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 格式。此行代码将执行该操
作:
byte[] bytes = trade.toJsonAsBytes();
• 您需要先创建新的 PutRecordRequest 实例(此示例中称为 putRecord),然后才能发送交易:
PutRecordRequest putRecord = new PutRecordRequest();
每个 PutRecord 调用均需要流名称、分区键和数据 Blob。以下代码使用 putRecord 对象的 setXxxx()
方法来填充该对象中的这些字段:
putRecord.setStreamName(streamName);
putRecord.setPartitionKey(trade.getTickerSymbol());
putRecord.setData(ByteBuffer.wrap(bytes));
该示例使用股票行情自动收录器作为将记录映射到特定分片的分区键。实际上,每个分片应具有数百或
数千个分区键,以便记录均匀地分布在流中。有关如何将数据添加到流的更多信息,请参阅 向流添加
数据 (p. 48)。
现在 putRecord 已准备好发送到客户端(put 操作):
kinesisClient.putRecord(putRecord);
• 错误检查和日志记录始终是有用的附加功能。此代码将记录错误条件:
if (bytes == null) {
LOG.warn("Could not get JSON bytes for stock trade");
return;
}
围绕 put 操作添加 try/catch 块:
31
Amazon Kinesis Streams 开发人员指南
第 5 步:实施使用器
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. 48)。
运行创建器
1.
验证之前(在创建 IAM 用户时)检索到的访问密钥和私有密钥对是否保存到文件
~/.aws/credentials 中。
2.
使用以下参数运行 StockTradeWriter 类:
StockTradeStream us-west-2
请注意,如果您在 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 步:实施使用器
Abstract
实施用于在 Streams 中处理数据的使用器代码的演练。
您正在开发的使用器应用程序将持续处理您在 第 4 步:实施创建器 (p. 30) 中创建的股票交易流,并输出
每分钟买入和卖出最多的股票。该应用程序基于 KCL 构建,后者需要完成对使用器应用程序常见的大量
32
Amazon Kinesis Streams 开发人员指南
第 5 步:实施使用器
繁重工作。有关更多信息,请参阅 使用 Amazon Kinesis Client Library 开发 Amazon Kinesis Streams 使
用器 (p. 61)。
请参阅源代码并查看以下信息。
StockTradesProcessor 类
为您提供的使用器的主类,它将执行以下任务:
• 读取作为参数传入的应用程序名称、流名称和区域名称。
• 从 ~/.aws/credentials 读取凭证。
• 创建一个 RecordProcessorFactory 实例,该实例提供由 StockTradeRecordProcessor 实
例实施的 RecordProcessor 的实例。
• 利用 RecordProcessorFactory 实例和标准配置(包括流名称、凭证和应用程序名称)创建
KCL 工作程序。
• 工作程序为分配给此使用器实例的每个分片创建一个新线程,该线程将持续循环以从 Streams 读
取记录,然后调用 RecordProcessor 实例以处理收到的每批记录。
StockTradeRecordProcessor 类
RecordProcessor 实例的实施,该实例反过来将实施三个必需方法:initialize、
processRecords 和 shutdown。
正如其名称所示,shutdown 和 initialize 由 KCL 使用,旨在让记录处理器了解何时应准备好开
始接收记录以及何时应停止接收记录,因此该方法可以执行任何特定于应用程序的设置和终止任务。
将为您提供这些方法的代码。processRecords 方法中进行的主要处理,该处理反过来对每条记录
使用 processRecord。后一个方法主要作为空框架代码提供给您,以便您在下一步骤中实施,届时
将进一步对其进行说明。
另外要注意的是 processRecord 的支持方法 reportStats 和 resetStats 的实施,二者在初始
源代码中为空。
已为您实施 processsRecords 方法,并执行了以下步骤:
• 对于每条传入的记录,对其调用 processRecord。
• 如果自上一次报告以来已过去至少 1 分钟,请调用 reportStats()(它将打印出最新统计数据),
然后调用 resetStats()(它将清除统计数据以便下一个间隔仅包含新记录)。
• 设置下一次报告时间。
• 如果自上一次检查点操作以来已过去至少 1 分钟,请调用 checkpoint()。
• 设置下一次检查点操作时间。
此方法使用 60 秒间隔作为报告和检查点操作比率。有关检查点操作的更多信息,请参阅 有关使用器
的附加信息 (p. 34)。
StockStats 类
此类提供一段时间内针对最热门股票的数据保留和统计数据跟踪。此代码已提供给您并包含以下方
法:
• addStockTrade(StockTrade):将给定的 StockTrade 注入正在使用的统计数据。
• toString():以格式化字符串形式返回统计数据。
此类跟踪最热门股票的方式是,保留每只股票的总交易数的连续计数并保留最大计数。它确保每当股
票交易达成时更新这些计数。
将代码添加到 StockTradeRecordProcessor 类的方法,如以下步骤中所示。
实施使用器
1.
通过实例化大小正确的 StockTrade 对象并将记录数据添加到该对象来实施 processRecord 方法,
并在出现问题时记录警告。
33
Amazon Kinesis Streams 开发人员指南
第 5 步:实施使用器
StockTrade trade = StockTrade.fromJsonAsBytes(record.getData().array());
if (trade == null) {
LOG.warn("Skipping record. Unable to parse record into StockTrade. Par
tition Key: " + record.getPartitionKey());
return;
}
stockStats.addStockTrade(trade);
2.
实施简单的 reportStats 方法。可随时将输出格式修改为您的首选格式。
System.out.println("****** Shard " + kinesisShardId + " stats for last 1
minute ******\n" +
stockStats + "\n" +
"****************************************************************\n");
3.
最后,实施 resetStats 方法,这将创建新的 stockStats 实例。
stockStats = new StockStats();
运行使用器
1.
2.
运行您在上一模块中编写的创建器以将模拟股票交易记录注入流。
验证之前(在创建 IAM 用户时)检索到的访问密钥和私有密钥对是否保存在文件
~/.aws/credentials 中。
3.
使用以下参数运行 StockTradesProcessor 类:
StockTradesProcessor StockTradeStream us-west-2
请注意,如果您在 us-west-2 之外的区域创建流,则必须改为在此处指定该区域。
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.
****************************************************************
有关使用器的附加信息
Abstract
有关使用器的补充信息。
如果您熟悉 KCL 的好处(在 使用 Amazon Kinesis Client Library 开发 Amazon Kinesis Streams 使用
器 (p. 61) 中和其他位置已讨论),您可能想知道为何您应在此处使用它。虽然您只使用单个分片流和单
个使用器实例来处理它,但使用 KCL 实施使用器仍会更轻松。将创建器部分中的代码实施步骤与使用器
部分中的进行对比,您会发现实施使用器相对来说容易一些。这很大程度上是因为 KCL 提供的服务。
34
Amazon Kinesis Streams 开发人员指南
第 6 步:(可选)扩展使用器
在此应用程序中,您专注于实施可处理单条记录的记录处理器类。您无需担心如何从 Streams 提取记录;
当有可用的新记录时,KCL 就会提取这些记录并调用记录处理器。此外,您无需担心有多少个分片和使
用器实例;如果已扩展流,则您无需重写应用程序以处理多个分片或多个使用器实例。
术语检查点操作是指记录到流中目前已使用和处理的数据记录所在的点,这样一来,当应用程序发生崩溃
时,系统将从该点读取流,而不是从头开始读取流。检查点操作主题、各种设计模式以及相关最佳实践不
在本章讨论范围内,但您在生产环境中可能会遇到。
正如您在the section called “第 4 步:实施创建器” (p. 30)一节中了解到的,Streams API 中的 put 操作将
分区键作为输入。分区键被 Streams 用作将记录拆分到多个分片中的机制(当流中有多个分片时)。相
同的分区键将始终路由到同一个分片。这使得能够基于以下假设来设计用于处理特定分片的使用器:具有
相同分区键的记录只会发送给该使用器,具有相同分区键的任何记录都不会在任何其他使用器处结束。因
此,使用器的工作程序可聚合具有相同分区键的所有记录而不用担心丢失所需的数据。
在此应用程序中,使用器对记录的处理并不集中,因此您可以使用一个分片并在与 KCL 线程相同的线程
中执行处理。但在实际应用中,请先考虑增大分片数,本学习系列中的下一个模块将对此进行演示。在某
些情况下,您可能需要将处理切换到其他线程或需要使用线程池(如果您的记录处理应是集中的)。这样
一来,KCL 可以更快地提取新记录,而其他线程可并行处理记录。请注意,多线程设计并不是无关紧要
的,应使用先进技术来实现,因此增加分片计数通常是最有效、最轻松的扩展方法。
第 6 步:(可选)扩展使用器
Abstract
向 Streams 使用器代码添加功能以获得其他优先级。
此处显示的应用程序可能已足以达到您的目的。本可选部分将演示您可能希望如何针对更为复杂的场景扩
展使用器代码。
若要了解每分钟的最大销售订单数,您需要对 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() > largestSel
lOrderQuantity) {
largestSellOrderStock = trade.getTickerSymbol();
largestSellOrderQuantity = trade.getQuantity();
}
}
3.
修改 toString 方法以打印其他信息:
public String toString() {
return String.format(
35
Amazon Kinesis Streams 开发人员指南
第 7 步:收尾
"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), getMostPopularStock
Count(TradeType.BUY),
getMostPopularStock(TradeType.SELL), getMostPopularStock
Count(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.
Largest sell order: 996 shares of BUD.
****************************************************************
第 7 步:收尾
Abstract
通过删除 Amazon Kinesis stream 和 DynamoDB 表来清除资源。
由于您需要付费使用 Amazon Kinesis stream,请确保在使用完流后删除流和相应的 DynamoDB 表。即
使您不发送和获取记录,活动流也会产生象征性的费用。这是因为活动流将持续“侦听”传入记录和获取记
录的请求,这将耗用资源。
删除流和表
1.
2.
3.
关闭您可能仍在运行的任何创建器和使用器。
通过以下网址打开 Amazon Kinesis 控制台:https://console.amazonaws.cn/kinesis。
在流列表中,选择为此应用程序创建的流 (StockTradeStream) 并选择 Delete Stream。
4.
通过以下网址打开 DynamoDB 控制台:https://console.amazonaws.cn/dynamodb/。
5.
删除 StockTradesProcessor 表。
摘要
几乎实时处理大量数据不需要编写任何功能强大的代码或开发大型基础设施。这就像编写逻辑来处理少量
数据(如编写 processRecord(Record))一样简单,但会使用 Streams 进行缩放以使该逻辑能处理大
量流数据。您无需担心处理的缩放方式,因为 Streams 将为您完成这一工作。您只需将流记录发送到
Streams 并编写用于处理收到的每条新记录的逻辑。
以下是针对此应用程序的一些可能的改进。
跨所有分片进行聚合
当前,您通过聚合单个分片(一个分片不能同时由单个应用程序中的多个工作程序处理)中的单个工
作程序所收到的数据记录来获得统计数据。当然,当您进行缩放并且有多个分片时,您可能希望跨所
有分片进行聚合。此操作可通过部署管道架构完成。在该架构中,每个工作程序的输出被传递到具有
单个分片的另一个流,该流由聚合第一个阶段的输出的工作程序处理。由于来自第一个阶段的数据是
有限的(每分片每分钟一个示例),因此一个分片即可轻松处理它。
36
Amazon Kinesis Streams 开发人员指南
第 7 步:收尾
缩放处理
当流进行扩展以包含多个分片(因为多个创建器正在发送数据)时,扩展处理的方式是添加更多工作
程序。您可以在 EC2 实例中运行工作程序并利用 Auto Scaling 组。
使用连接 S3/DynamoDB/Redshift/Storm 的连接器
由于流将得到持续处理,因此可将其输出发送到其他目标。AWS 提供了连接器以将 Streams 与其他
AWS 服务和第三方工具集成。
后续步骤
• 有关使用 Streams API 操作的更多信息,请参阅 the section called “使用 API” (p. 48)、the section
called “使用 API” (p. 75) 和 the section called “管理流” (p. 87)。
• 有关 Kinesis 客户端库的更多信息,请参阅 the section called “使用 KCL” (p. 61)。
• 有关如何优化应用程序的更多信息,请参阅 the section called “高级主题” (p. 81)。
37
Amazon Kinesis Streams 开发人员指南
将数据写入到流
使用 Amazon Kinesis Streams
Abstract
针对使用 Amazon Kinesis Streams 的客户的主题。
本节提供有关使用 Amazon Kinesis Streams 的信息。如果您不熟悉 Streams,在使用本文档之前,请花
点时间熟悉一下 什么是 Amazon Kinesis Streams? (p. 1) 和 开始使用 Amazon Kinesis Streams (p. 8)
这两节中介绍的概念和术语。
主题
• 将数据写入到 Amazon Kinesis Streams (p. 38)
• 读取 Amazon Kinesis Streams 中的数据 (p. 61)
• 管理 Amazon Kinesis Stream (p. 87)
• 监控 Amazon Kinesis Streams (p. 96)
• 为您在 Amazon Kinesis Streams 中的流加标签 (p. 114)
• 使用 IAM 控制对 Amazon Kinesis Streams 资源的访问 (p. 116)
将数据写入到 Amazon Kinesis Streams
Abstract
有关使用 AWS 开发工具包和 KPL 构建 Amazon Kinesis Streams 创建器的指南。
创建器 是将数据写入 Amazon Kinesis Streams 的应用程序。本节提供有关构建 Streams 的生产者的信
息。如果您不熟悉 Streams,在使用本文档之前,请花点时间熟悉一下 什么是 Amazon Kinesis
Streams? (p. 1) 和 开始使用 Amazon Kinesis Streams (p. 8) 这两节中介绍的概念和术语。
主题
• 使用 Amazon Kinesis 创建器库 开发 Amazon Kinesis Streams 创建器 (p. 39)
• 通过将 Amazon Kinesis Streams API 与适用于 Java 的 AWS 开发工具包结合使用来开发 Amazon
Kinesis Streams 生产者 (p. 48)
• 使用 Amazon Kinesis 代理写入 Amazon Kinesis Streams (p. 52)
• Amazon Kinesis Streams 创建器故障排除 (p. 58)
• 有关 Amazon Kinesis Streams 生产者的高级主题 (p. 59)
38
Amazon Kinesis Streams 开发人员指南
使用 KPL
使用 Amazon Kinesis 创建器库 开发 Amazon Kinesis
Streams 创建器
Abstract
KPL 提供了 Amazon Kinesis Streams 创建器应用程序的设计模式和代码。
Amazon Kinesis Streams 创建器是指将用户数据记录放入 Amazon Kinesis stream 中(也称为数据注入)
的任何应用程序。Amazon Kinesis 创建器库 (KPL) 简化了创建器应用程序的开发,从而允许开发人员实
现到 Amazon Kinesis stream 的高写入吞吐量。
您可利用 Amazon CloudWatch 监控 KPL。有关更多信息,请参阅 the section called “利用 CloudWatch
监控 KPL” (p. 111)。
内容
•
•
•
•
•
•
•
•
•
•
KPL 的角色 (p. 39)
使用 KPL 的优势 (p. 39)
何时不使用 KPL (p. 40)
安装 (p. 40)
支持的平台 (p. 40)
主要概念 (p. 41)
与创建器代码集成 (p. 42)
使用 KPL 写入到您的 Streams 流 (p. 43)
配置 KPL (p. 45)
使用器取消聚合 (p. 46)
KPL 的角色
KPL 是一个易于使用的、高度可配置的库,可帮助您对 Amazon Kinesis stream 进行写入。它在您的创
建器应用程序代码和 Streams API 操作之间充当中介。KPL 执行以下主要任务:
• 利用可配置的自动重试机制对一个或多个 Amazon Kinesis stream 进行写入
• 收集记录并使用 PutRecords 根据请求将多条记录写入多个分片
• 聚合用户记录以增加负载大小并提高吞吐量
• 与 Amazon Kinesis Client Library (KCL) 无缝集成以在使用器上取消聚合批记录
• 代表您提交 Amazon CloudWatch 指标以提供创建器性能的可见性
请注意,KPL 与 AWS 软件开发工具包 中可用的 Streams API 不同。Streams API 可帮助您管理 Streams
的许多方面(包括创建流、重新分片以及放置并获取记录),而 KPL 提供专用于注入数据的提取层。有
关 Streams API 的信息,请参阅 Amazon Kinesis API Reference。
使用 KPL 的优势
以下列表说明了使用 KPL 开发 Streams 创建器的一些主要优势。
KPL 可在同步或异步使用案例中使用。除非存在使用同步操作的具体原因,否则建议您使用异步接口的
较高性能。有关这两种使用案例和示例代码的更多信息,请参阅 使用 KPL 写入到您的 Streams 流 (p. 43)。
性能优势
KPL 可帮助构建高性能创建器。考虑以下情况:您的 Amazon EC2 实例充当代理来从数以百计或数
以千计的低功率设备中收集 100 个字节的事件并将记录写入 Amazon Kinesis stream 中。这些 EC2
39
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 中的调用始终立即返回,并且
不等待发送记录或接收来自服务器的响应。相反,将创建一个 Future 对象,该对象稍后将接收向
Streams 发送记录的结果。这与 AWS 开发工具包中的异步客户端的行为相同。
何时不使用 KPL
KPL 会促使库(用户可配置的)中产生高达 RecordMaxBufferedTime 的额外处理延迟。
RecordMaxBufferedTime 值越大,产生的包装效率和性能就越高。无法容忍此额外延迟的应用程序可
能需要直接使用 AWS 开发工具包。有关将 AWS 开发工具包与 Streams 结合使用的更多信息,请参阅
the section called “使用 API” (p. 48)。有关 RecordMaxBufferedTime 和 KPL 的其他用户可配置的属性
的更多信息,请参阅 the section called “配置 KPL” (p. 45) 部分。
安装
Abstract
KPL 的安装信息。
Amazon 提供了针对 OS X、Windows 和最新 Linux 发行版(有关支持的平台的详细信息,请参阅下一部
分)的 C++ KPL 的预先构建的二进制文件。如果您使用 Maven 安装程序包,这些二进制文件将作为 Java
.jar 文件的一部分打包,并将自动被调用和使用。要查找最新版的 KPL 和 KCL,请使用以下 Maven 搜索
链接:
• KPL
• KCL
Linux 二进制文件已采用 GCC 进行编译并已静态链接到 Linux 上的 libstdc++。这些二进制文件应适用于
包含 glibc 2.5 版或更高版本的任何 64 位 Linux 发行版。
早期 Linux 发行版的用户可使用 Github 上与源一起提供的构建说明构建 KPL。要从 Github 中下载 KPL,
请参阅 Amazon Kinesis 创建器库
支持的平台
Abstract
KPL 当前支持以下平台和源代码信息。
KPL 采用 C++ 进行编写并且作为主用户进程的子进程运行。预编译的 64 位本机二进制文件与 Java 版本
捆绑在一起并由 Java 包装程序管理。
40
Amazon Kinesis Streams 开发人员指南
使用 KPL
无需在以下操作系统上安装任何其他库即可运行 Java 程序包:
• 内核为 2.6.18(2006 年 9 月)及更高版本的 Linux 发行版
• Apple OS X 10.9 及更高版本
• Windows Server 2008 及更高版本
请注意,KPL 仅为 64 位。
源代码
如果 KPL 安装中提供的二进制文件无法满足您的环境,则 KPL 的内核将编写为 C++ 模块。C++ 模块和
Java 接口的源代码将在 Amazon 公用许可下发布并可通过 Amazon Kinesis 创建器库 上的 GitHub 获得。
虽然 KPL 可在适用于最新的符合标准的 C++ 编译器和 JRE 的任何平台上使用,但 Amazon 仍未正式支
持不在受支持的平台列表中的任何平台。
主要概念
Abstract
KPL 引入了一些新的概念和术语。
以下部分包含了解 KPL 并从中获益所需的概念和术语。
主题
• 记录 (p. 41)
• 批处理 (p. 41)
• 聚合 (p. 42)
• 集合 (p. 42)
记录
在本指南中,我们区分了 KPL 用户记录 和 Streams 记录。当我们使用没有限定词的术语记录 时,我们
指的是 KPL 用户记录。当我们提及 Streams 记录时,我们会明确地表述 Streams 记录。
KPL 用户记录是对用户有特别含义的数据 Blob。示例包括表示网站上的 UI 事件的 JSON Blob 或 Web 服
务器中的日志条目。
Streams 记录是由 Streams 服务 API 定义的 Record 数据结构的实例。它包含一个分区键、序列号和数
据 Blob。
批处理
批处理 指对多个项执行单个操作而不是对每个单独的项重复执行操作。
在此背景下,“项”是一条记录,操作是将项发送到 Streams。在非批处理情况下,您会将每条记录放置在
一个单独的 Streams 记录中,并发出一个 HTTP 请求以将其发送到 Streams。利用批处理,每个 HTTP
请求可携带多条记录而不仅仅是一条记录。
KPL 支持两种批处理:
• 聚合 – 在单条 Streams 记录中存储多条记录。
• 集合 – 使用 API 操作 PutRecords 将多条 Streams 记录发送到 Amazon Kinesis stream 中的一个或多
个分片。
这两种类型的 KPL 批处理旨在共存并可彼此独立启用或禁用。默认情况下,两种批处理将同时启用。
41
Amazon Kinesis Streams 开发人员指南
使用 KPL
聚合
聚合 指在一条 Streams 记录中存储多条记录。聚合允许客户增加每个 API 调用发送的记录的数目,这将
有效增加创建器吞吐量。
Streams 分片支持每秒最多 1,000 条 Streams 记录或 1 MB 吞吐量。每秒 Streams 记录数限制将绑定具
有 1 KB 以下的记录的客户。记录聚合允许客户将多条记录合并为一条 Streams 记录。这使客户能够提高
其每分片吞吐量。
考虑以下情况:区域 us-east-1 中的一个分片当前正在以每秒 1,000 条记录的恒速运行,其中每条记录的
大小为 512 个字节。利用 KPL 聚合,您可将一千条记录打包到 10 条 Streams 记录中,从而将 RPS 降
低到 10(每条记录 50 KB)。
集合
集合 指批处理多条 Streams 记录并通过调用 API 操作 PutRecords 在单个 HTTP 请求发送这些记录,
而不是在其自己的 HTTP 请求中发送每条 Streams 记录。
与不使用集合相比,这将增加吞吐量,因为它减少了发出多个单独 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 --|
|
|
...
...
|
|
record AA--|
|
record BB |
|
...
|--> Amazon Kinesis record M --|
...
|
record ZZ--|
与创建器代码集成
Abstract
了解如何将 KPL 作为微服务运行。
KPL 在单独进程中运行,并使用 IPC 与您的父用户进程通信。此架构有时称为微服务,出于两个主要原
因选择该架构:
1) 您的用户进程将不会发生崩溃,即使 KPL 发生崩溃也是如此
42
Amazon Kinesis Streams 开发人员指南
使用 KPL
您的进程可具有与 Streams 不相关的任务,并且可以继续运行,即使 KPL 发生崩溃也是如此。对于您的
父用户进程来说,也可重新启动 KPL 并恢复到完全运行状态(此功能位于正式包装程序中)。
例如,将指标发送到 Streams 的 Web 服务器;该服务器可继续使用页面,即使 Streams 部分已停止运
行也是如此。由于 KPL 中存在 bug,导致整个服务器发生崩溃,从而造成不必要的中断。
2) 可支持任意客户端
始终存在使用官方支持的语言之外的语言的客户。这些客户也应能轻松使用 KPL。
推荐的使用矩阵
以下使用矩阵枚举了不同用户的推荐设置,并向您提供了有关是否以及如何使用 KPL 的建议。请记住,
如果启用聚合,则还必须使用取消聚合来提取使用器端的记录。
创建器端语言
使用器端
KCL 版本
检查点逻辑
是否可使用
KPL?
警告
除 Java 之外的 *
任何语言
*
*
否
不适用
Java
Java
直接使用 Java 不适用
软件开发工具包
是
如果使用聚合,
您必须在
GetRecords 调
用后使用提供的
取消聚合库。
Java
除 Java 之外的
任何语言
直接使用软件开 不适用
发工具包
是
必须禁用聚合。
Java
Java
1.3.x
不适用
是
必须禁用聚合
Java
Java
1.4.x
调用不带任何
参数的检查点
是
无
Java
Java
1.4.x
调用带明确序
列号的检查点
是
禁用聚合或更改
代码以使用扩展
的序列号进行检
查点操作
Java
除 Java 之外的
任何语言
1.3.x + 多语言 不适用
守护进程 + 特定
于语言的包装程
序
是
必须禁用聚合
语言
使用 KPL 写入到您的 Streams 流
Abstract
可使用 KPL 实施许多针对创建器的常见案例。
以下部分说明了正在运行的示例代码,从可能最简单的“barebones”创建器到完全异步的代码。
Barebones 创建器代码
以下代码是写入最小工作创建器所需的全部代码。在后台处理 KPL 用户记录。
43
Amazon Kinesis 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<UserRe
cordResult>>();
for (int i = 0; i < 100; i++) {
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
44
Amazon Kinesis Streams 开发人员指南
使用 KPL
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
Abstract
自定义 KPL 的配置参数。
虽然默认设置应适用于大多数使用案例,但您可能想更改部分默认设置以定制 KinesisProducer 的行
为来满足您的需求。为此,可将 KinesisProducerConfiguration 类的实例传递给 KinesisProducer
构造函数,例如:
KinesisProducerConfiguration config = new KinesisProducerConfiguration()
.setRecordMaxBufferedTime(3000)
.setMaxConnections(1)
.setRequestTimeout(60000)
.setRegion("us-west-1");
final KinesisProducer kinesisProducer = new KinesisProducer(config);
您也可从属性文件中加载配置:
KinesisProducerConfiguration config = KinesisProducerConfiguration.fromProper
tiesFile("default_config.properties");
您可替换用户进程可访问的任何路径和文件名。此外,您可在通过此方式创建的
KinesisProducerConfiguration 实例上调用 set 方法来自定义 config。
属性文件应使用以帕斯卡拼写法书写的名称来指定参数。这些名称将与 KinesisProducerConfiguration
类中的设置方法中使用的名称匹配。例如:
RecordMaxBufferedTime = 100
MaxConnections = 4
RequestTimeout = 6000
Region = us-west-1
有关配置参数使用规则和值限制的更多信息,请参阅 在 GitHub 上示例配置属性的文件。
请注意,初始化 KinesisProducer 后,更改已使用的 KinesisProducerConfiguration 实例不会
产生进一步的影响。KinesisProducer 当前不支持动态重新配置。
45
Amazon Kinesis Streams 开发人员指南
使用 KPL
使用器取消聚合
Abstract
在使用 KPL 时应考虑使用器端注意事项和过程。
从版本 1.4.0 开始,KCL 支持自动取消聚合 KPL 用户记录。在更新 KCL 后,将编译利用早期版本的 KCL
编写的使用器应用程序代码而不做任何修改。不过,如果正在创建器端使用 KPL 聚合,则有一个与检查
点操作相关的细微之处:已聚合记录中的所有子记录都具有相同的序列号,因此如果您需要区分子记录,
则必须利用检查点存储额外数据。此额外数据称作子序列号。
从早期版本的 KCL 进行迁移
您无需更改现有调用来同时执行检查点操作与聚合。仍确保您能够成功检索 Streams 中存储的所有记录。
KCL 现在提供两个新的检查点操作来支持特定的使用案例,如下所述。
如果您的现有代码先于 KPL 支持为 KCL 写入,并且调用了不带参数的检查点操作,则它等同于对批处理
中的上一条 KPL 用户记录的序列号进行检查点操作。如果调用带序列号字符串的检查点操作,则它等同
于对批处理的指定序列号以及隐式子序列号 0(零)进行检查点操作。
调用没有任何参数的新的 KCL 检查点操作 checkpoint() 在语义上等同于对批处理中的上个 Record
调用的序列号以及隐式子序列号 0(零)进行检查点操作。
调用新的 KCL 检查点操作 checkpoint(Record record) 在语义上等同于对指定 Record 的序列号以
及隐式子序列号 0(零)进行检查点操作。如果 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 */
}
}
46
Amazon Kinesis Streams 开发人员指南
使用 KPL
现在使用的是此类而不是 Record。这不会破坏现有代码,因为它是 Record 的子类。UserRecord 类同
时表示实际子记录和标准非聚合记录。非聚合记录可被视为刚好具有一条子记录的聚合记录。
此外,将两个新的操作添加到 IRecordProcessorCheckpointer:
public void checkpoint(Record record);
public void checkpoint(String sequenceNumber, long subSequenceNumber);
要开始使用子序列号检查点操作,您可执行以下转换。更改以下形式代码:
checkpointer.checkpoint(record.getSequenceNumber());
新的形式代码:
checkpointer.checkpoint(record);
建议您使用 checkpoint(Record record) 形式来进行子序列检查点操作。不过,如果您已以字符串
形式存储 sequenceNumbers 以用于检查点操作,则您现在也应存储 subSequenceNumber,如以下示
例所示:
String sequenceNumber = record.getSequenceNumber();
long subSequenceNumber = ((UserRecord) record).getSubSequenceNumber();
do other processing
checkpointer.checkpoint(sequenceNumber, subSequenceNumber);
// ...
从 Record 到 UserRecord 的转换始终成功实施,因为实施始终在后台使用 UserRecord。除非需要对
序列号进行算术运算,否则建议不要采用此方法。
在处理 KPL 用户记录时,KCL 会将子序列号写入 Amazon DynamoDB 作为每行的额外字段。在恢复检
查点操作时,早期版本的 KCL 使用 AFTER_SEQUENCE_NUMBER 提取记录。而具有 KPL 支持的当前 KCL
使用的是 AT_SEQUENCE_NUMBER。在检索带已进行检查点操作的序列号的记录时,会检查已进行检查点
操作的子序列号,而且会根据需要删除子记录(如果上一条子记录为已进行检查点操作的记录,则可能删
除所有子记录)。同样,非聚合记录可被视为具有单条子记录的聚合记录,因此相同的算法同时适用于聚
合和非聚合记录。
直接使用 GetRecords
您也可以选择不使用 KCL 而是直接调用 API 操作 GetRecords 来检索 Streams 记录。要将已检索到的
记录提取到原始 KPL 用户记录中,可在 UserRecord.java 中调用下列静态操作之一:
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 用户记录。
47
Amazon Kinesis Streams 开发人员指南
使用 API
通过将 Amazon Kinesis Streams API 与适用于 Java
的 AWS 开发工具包结合使用来开发 Amazon Kinesis
Streams 生产者
Abstract
使用 Amazon Kinesis Streams API 开发 Amazon Kinesis Streams 生产者的示例和指导。
本节提供有关将 Amazon Kinesis Streams API 与适用于 Java 的 AWS 开发工具包结合使用来开发生产者
的信息。如果您不熟悉 Streams,在使用本文档之前,请花点时间熟悉一下 什么是 Amazon Kinesis
Streams? (p. 1) 和 开始使用 Amazon Kinesis Streams (p. 8) 这两节中介绍的概念和术语。
这些示例讨论 Streams API 并使用适用于 Java 的 AWS 开发工具包向流中添加(放置)数据。但是,在
大多数使用案例中,您应会更喜欢使用 Streams KPL 库。有关更多信息,请参阅 the section called “使用
KPL” (p. 39)。
本章中的 Java 示例代码演示如何执行基本的 Streams API 操作,并按照操作类型从逻辑上进行划分。这
些示例并非可直接用于生产的代码,因为它们不会检查所有可能的异常,或者不会考虑到所有可能的安全
或性能问题。此外,您可使用其他不同的编程语言调用 Streams API。有关所有可用 AWS 开发工具包的
更多信息,请参阅开始使用 Amazon Web Services 开发。
本节中的每个任务都有先决条件;例如,您在创建流之前不能向流中添加数据,这需要您创建一个客户
端。有关更多信息,请参阅 the section called “管理流” (p. 87)。
向流添加数据
Abstract
了解如何使用适用于 Java 的 AWS 开发工具包向 Amazon Kinesis stream 添加数据。
在创建流之后,您可以记录的形式向其中添加数据。记录是一种数据结构,其中包含要处理的数据(采用
数据 Blob 形式)。在将数据存储到记录中之后,Streams 不会以任何形式检查、解释或更改数据。每个
记录还有一个关联的序列号和分区键。
Streams API 中有两种不同的向流添加数据的操作:PutRecords 和 PutRecord。PutRecords 操作将
按 HTTP 请求向您的流发送多个记录,并且单个 PutRecord 操作一次可向您的流发送多个记录(每个记
录需要单独的 HTTP 请求)。对于大多数应用程序,您应会更喜欢使用 PutRecords,因为这将使每个
数据创建器实现更高的吞吐量。有关每种操作的更多信息,请参阅以下各小节。
主题
• 使用 PutRecords 添加多个记录 (p. 49)
• 使用 PutRecord 添加单一记录 (p. 51)
请始终记住,在您的源应用程序使用 Streams API 向流添加数据时,很可能存在一个或多个同时处理离
开流的数据的消费者应用程序。有关消费者应用程序使用 Streams API 获取数据的信息,请参阅 从流中
获取数据 (p. 75)。
Important
数据记录默认可在其添加到流的 24 小时内访问。此时间范围称为保留期,并且可以在从 24 到
168 小时(1 到 7 天)的范围内按小时为增量进行配置。有关流的保留期的更多信息,请参阅the
section called “更改数据保留期” (p. 95)。
48
Amazon Kinesis Streams 开发人员指南
使用 API
使用 PutRecords 添加多个记录
PutRecords 操作可在一次请求中向 Streams 发送多个记录。通过使用 PutRecords,创建器可在向其
Amazon Kinesis stream 发送数据时实现更高的吞吐量。每 PutRecords 请求可以支持多达 500 条记录。
请求中的每一个记录可以大到 1 MB,整个请求的上限为 5 MB,包括分区键。 与下面描述的 PutRecord
操作一样,PutRecords 将使用序列号和分区键。但是,PutRecord 参数 SequenceNumberForOrdering
未包含在 PutRecords 调用中。PutRecords 操作将尝试按请求的自然顺序处理所有记录。
每个数据记录都有一个唯一的序列号。此序列号在您调用 client.putRecords 向流添加数据记录之后
由 Streams 分配。同一分区键的序列号通常会随时间变化增加;PutRecords 请求之间的时间段越长,
序列号变得越大。
Note
序列号不能用作相同流中的数据集的索引。为了在逻辑上分隔数据集,请使用分区键或为每个数
据集创建单独的流。
PutRecords 请求可包含具有不同分区键的记录。请求的应用范围是一个流;每个请求可包含分区键和记
录的任何组合,直到达到请求限制。使用许多不同的分区键对具有许多不同分片的流进行的请求一般快于
使用少量分区键对少量分片进行的请求。分区键的数量应远大于分片的数量以减少延迟并最大程度提高吞
吐量。
PutRecords 示例
以下代码创建 100 个使用连续分区键的数据记录并将其放入名为 DataStream 的流中。
AmazonKinesisClient amazonKinesisClient = new AmazonKinesisClient(credentialsPro
vider);
PutRecordsRequest putRecordsRequest = new PutRecordsRequest();
putRecordsRequest.setStreamName("DataStream");
List <PutRecordsRequestEntry> putRecordsRequestEntryList = new ArrayList<>();
for (int i = 0; i < 100; i++) {
PutRecordsRequestEntry putRecordsRequestEntry = new PutRecord
sRequestEntry();
putRecordsRequestEntry.setData(ByteBuffer.wrap(String.valueOf(i).get
Bytes()));
putRecordsRequestEntry.setPartitionKey(String.format("partitionKey-%d",
i));
putRecordsRequestEntryList.add(putRecordsRequestEntry);
}
putRecordsRequest.setRecords(putRecordsRequestEntryList);
PutRecordsResult putRecordsResult = amazonKinesisClient.putRecords(putRecord
sRequest);
System.out.println("Put Result" + putRecordsResult);
PutRecords 响应包含响应 Records 的数组。响应数组中的每个记录按自然顺序(从请求和响应的顶部
到底部)直接与请求数组中的一个记录关联。响应 Records 数组包含的记录数量始终与请求数组相同。
处理使用 PutRecords 时的操作失败
默认情况下,请求内的单个记录的失败不会中止对 PutRecords 请求中后续记录的处理。这意味着,响
应 Records 数组包含处理成功和不成功的记录。您必须删除处理不成功的记录并在后续调用中包括它
们。
49
Amazon Kinesis Streams 开发人员指南
使用 API
成功的记录包括 SequenceNumber 和 ShardID 值,而不成功的记录包含 ErrorCode 和 ErrorMessage
值。ErrorCode 参数反映了错误类型,可能为下列值之一:
ProvisionedThroughputExceededException 或 InternalFailure。ErrorMessage 提供有关
ProvisionedThroughputExceededException 异常的更多详细信息,包括账户 ID、流名称和已阻止
的记录的分片 ID。以下示例在 PutRecords 请求中有三个记录。第二个记录失败并反映在响应中。
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 添加到后续请求中。有关此类处理程序的示例,请参阅以下代码。
50
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).get
Bytes()));
putRecordsRequestEntry.setPartitionKey(String.format("partitionKey-%d",
j));
putRecordsRequestEntryList.add(putRecordsRequestEntry);
}
putRecordsRequest.setRecords(putRecordsRequestEntryList);
PutRecordsResult putRecordsResult = amazonKinesisClient.putRecords(putRecord
sRequest);
while (putRecordsResult.getFailedRecordCount() > 0) {
final List<PutRecordsRequestEntry> failedRecordsList = new ArrayList<>();
final List<PutRecordsResultEntry> putRecordsResultEntryList = putRecordsRes
ult.getRecords();
for (int i = 0; i < putRecordsResultEntryList.size(); i++) {
final PutRecordsRequestEntry putRecordRequestEntry = putRecord
sRequestEntryList.get(i);
final PutRecordsResultEntry putRecordsResultEntry = putRecordsResul
tEntryList.get(i);
if (putRecordsResultEntry.getErrorCode() != null) {
failedRecordsList.add(putRecordRequestEntry);
}
}
putRecordsRequestEntryList = failedRecordsList;
putRecordsRequest.setRecords(putRecordsRequestEntryList);
putRecordsResult = amazonKinesisClient.putRecords(putRecordsRequest);
}
使用 PutRecord 添加单一记录
对 PutRecord 的每次调用对一个记录起作用。应首选 使用 PutRecords 添加多个记录 (p. 49) 中描述的
PutRecords 操作,除非您的应用程序明确需要每一请求始终发送一条记录,或因某种其他原因无法使用
PutRecords。
每个数据记录都有一个唯一的序列号。此序列号在您调用 client.putRecord 向流添加数据记录之后由
Streams 分配。同一分区键的序列号通常会随时间变化增加;PutRecord 请求之间的时间段越长,序列
号变得越大。
在快速连续进行放置时,不保证返回的序列号会递增,因为放置操作的发生对于 Streams 实际上是同步
进行的。要确保相同分区键的序列号严格递增,请使用 SequenceNumberForOrdering 参数,如
PutRecord 示例 (p. 52) 代码示例中所示。
无论您是否使用 SequenceNumberForOrdering,Streams 通过 GetRecords 调用接收的记录都将按
序列号严格进行排序。
Note
序列号不能用作相同流中的数据集的索引。为了在逻辑上分隔数据集,请使用分区键或为每个数
据集创建单独的流。
51
Amazon Kinesis Streams 开发人员指南
使用代理写入
分区键用于对流中的数据进行分组。数据记录将基于其分区键分配给流中的分片。具体来说,Streams 使
用分区键作为将分区键(和关联数据)映射到特定分片的哈希函数的输入。
作为此哈希机制的结果,具有相同分区键的所有数据记录将映射到流中的同一分片。但是,如果分区键的
数量超出分片的数量,则一些分片必定会包含具有不同分区键的记录。从设计的角度看,要确保您的所有
分片得到充分利用,分片的数量(由 CreateStreamRequest 的 setShardCount 方法指定)应远少于
唯一分区键的数量,并且流至单一分区键的数据量应远少于分片容量。
PutRecord 示例
以下代码创建跨两个分区键分配的 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。
同一客户端调用 PutRecord 时,SequenceNumberForOrdering 参数可确保相同分区键的序列号严格
递增。SequenceNumberForOrdering 不会在从多个并发应用程序添加的记录中或在多个分区键中提供
顺序保证。
使用 Amazon Kinesis 代理写入 Amazon Kinesis
Streams
Abstract
有关使用 Amazon Kinesis Streams 代理的指南。
本节提供有关使用代理写入 Amazon Kinesis Streams 的信息。如果您不熟悉 Streams,请花点时间熟悉
一下 什么是 Amazon Kinesis Streams? (p. 1) 部分中介绍的概念和术语。
代理是独立的 Java 软件应用程序,可提供更轻松的方式来将数据收集和提取到 Streams 中。代理持续监
控一组日志文件,并将新数据记录发送到您的 Amazon Kinesis stream。默认情况下,通过新行来确定每
个文件中的记录,不过也可以配置为处理多行记录(请参阅the section called “代理配置设置” (p. 54))。
代理处理文件轮换、检查点操作并在失败时重试。它以可靠及时的简单方法提供您的所有数据。它还发出
CloudWatch 指标,以帮助您更好地监控流式处理过程并排除故障。
您可以在基于 Linux 的服务器环境(如 Web 服务器、前端、日志服务器和数据库服务器)上安装此代理。
在安装后(请参阅the section called “安装代理” (p. 53)),通过指定要监控的日志文件和 Amazon Kinesis
stream 名称来配置代理。在配置之后,代理将长期从日志文件收集数据并以可靠的方式将数据提交到
Amazon Kinesis stream。
Amazon Kinesis 代理是开源软件。如果以下安装说明的系统要求不适用于您,您可以在 Github 上获取源
代码。要从 Github 下载源代码,请参阅 Amazon Kinesis 代理。
52
Amazon Kinesis Streams 开发人员指南
使用代理写入
内容
• 安装代理 (p. 53)
• 代理配置设置 (p. 54)
• 在同一个数据创建器上处理多个文件 (p. 57)
• 同时写入到 Amazon Kinesis Firehose 和 Amazon Kinesis Streams (p. 57)
• 有用的代理 CLI 命令 (p. 58)
安装代理
本部分提供安装代理所需的步骤。
先决条件
您必须具有活动的 Amazon Kinesis stream 并且知道 Amazon Kinesis stream 名称。
您的操作系统需要是 Amazon Linux AMI 版本 2015.09 或更高版本,或者 Red Hat Enterprise Linux 版本
7 或更高版本。
AWS 证书
如果您正在使用 Amazon EC2 运行代理,则必须具有 EC2 实例,最好配置了 IAM 角色。有关将 IAM 角
色分配到 EC2 实例的更多信息,请参阅 适用于 Amazon EC2 的 IAM 角色。
如果您未使用 EC2 实例,或者 EC2 实例没有 IAM 角色,则可在安装代理之后使用以下方法之一管理
AWS 凭证:
• 配置代理时,请参阅the section called “代理配置设置” (p. 54)并指定 AWS 凭证。
• 编辑 /etc/sysconfig/aws-kinesis-agent 以指定您的区域和 AWS 访问密钥对。
您指定的权限需要允许 Streams PutRecords 操作访问权限以便将数据放入您的 Amazon Kinesis stream。
如果您为代理启用 CloudWatch 监控,则 CloudWatch PutMetricData 操作也需要访问权限。有关更多
信息,请参阅the section called “Controlling Access” (p. 116)和 CloudWatch 访问控制。
设置代理
您必须使用以下过程之一安装和配置代理。
下载并安装代理
请选择以下任一选项:
选项 1:Amazon Linux AMI
1.
连接到您的 Amazon Linux 实例。想要了解更多信息,请参阅 Amazon EC2 用户指南(适用于 Linux
实例) 中的连接到您的实例。如果在连接时出现问题,请参阅 Amazon EC2 用户指南(适用于 Linux
实例) 中的排除连接实例的故障。
2.
下载并安装代理:
sudo yum install –y aws-kinesis-agent
选项 2:Red Hat Enterprise Linux
•
下载并安装代理:
53
Amazon Kinesis Streams 开发人员指南
使用代理写入
sudo yum install –y https://s3.amazonaws.com/streaming-data-agent/aws-kinesisagent-1.0-1.amzn1.noarch.rpm
选项 3:GitHub
1.
下载代理。要从 Github 下载代理,请转到 awlabs/amazon-kinesis-agent。
2.
导航到下载目录并发出以下命令来安装代理:
sudo ./setup --install
配置并启动代理
配置代理
•
打开并编辑配置文件(如果使用默认文件访问权限,则以超级用户的身
份):/etc/aws-kinesis/agent.json。代理读取文件并将其发送到流。在此配置文件中指定文
件的位置 ("filePattern") 以及流的名称和终端节点 ("kinesisStream")。请注意,文件名是模
式,并且代理能够观察文件轮换。受监控的文件限制为按最短 1 秒的时间间隔轮换或创建。
{
"cloudwatch.emitMetrics": true,
"kinesis.endpoint": "",
"flows": [
{
"filePattern": "/tmp/app.log*",
"kinesisStream": "yourkinesisstream"
}
]
}
启动代理
1.
手动启动代理:
sudo service aws-kinesis-agent start
2.
可以选择配置代理在系统启动时启动:
sudo chkconfig aws-kinesis-agent on
现在,代理作为系统服务在后台运行。它持续监控在配置文件中指定的位置,并将数据发布到 Streams
中,在 /var/log/aws-kinesis-agent/aws-kinesis-agent.log 中记录代理活动。
代理配置设置
您可以配置代理以使用可选设置,此时默认情况下代理从文件 /etc/aws-kinesis/agent.json 加载。
54
Amazon Kinesis Streams 开发人员指南
使用代理写入
对配置文件的任何更改都需要停止并重新启动代理,如以下命令所示:
sudo service aws-kinesis-agent stop
sudo service aws-kinesis-agent start
或者
sudo service aws-kinesis-agent restart
最常用的可选设置如下(有关详细信息,请参阅the section called “代理配置设置参考” (p. 55))。
证书
如果在配置中设置了 awsAccessKeyId 和 awsSecretAccessKey,则这些值要优先于其他凭证提
供程序。
Streams 和 CloudWatch 终端节点
默认情况下,这些终端节点设置为区域 us-east-1,或者您用于从 CLI 启动实例的终端节点。
多个流程
配置流程用于监控多个日志文件并将数据发送到多个流。
多行开始位置模式
默认情况下,日志文件中的每一个新行都被解析为一条记录。要发送多行记录,请配置
multiLineStartPattern。
multiLineStartPattern 指定用于标识记录开始位置的模式。记录由与模式匹配的行以及与模式
不匹配的任何以下行组成。有效值为正则表达式。
下面显示了带有可选设置的示例配置文件。ACCESSKEY 和 SECRETKEY 表示您的实际键值。
{
"checkpointFile": "/tmp/aws-kinesis-agent-checkpoints",
"cloudwatch.emitMetrics": true,
"cloudwatch.endpoint": "https://monitoring.us-east-1.amazonaws.com",
"kinesis.endpoint": "https://kinesis.us-east-1.amazonaws.com",
"awsAccessKeyId": "ACCESSKEY",
"awsSecretAccessKey": "SECRETKEY",
"flows": [
{
"filePattern": "/tmp/aws-kinesis-agent-test1.log*",
"kinesisStream": "aws-kinesis-agent-test1"
},
{
"filePattern": "/tmp/aws-kinesis-agent-test2.log*",
"kinesisStream": "aws-kinesis-agent-test2"
}
]
}
代理配置设置参考
一般配置设置如下所示。所有一般设置字段都是可选的。
设置
说明
awsAccessKeyId
覆盖默认凭证中的 AWS 访问密钥 ID。此设置优先于所有其他凭证提供程序。
55
Amazon Kinesis Streams 开发人员指南
使用代理写入
设置
说明
awsSecretAccessKey 覆盖默认凭证中的 AWS 密钥。此设置优先于所有其他凭证提供程序。
cloudwatch.emitMet- 一个标记,在启用 (true) 时允许代理向 CloudWatch 发出指标;在禁用 (false)
时则禁止发出指标。
rics
默认值:True
cloudwatch.endpoint
您的 CloudWatch 服务的区域终端节点。默认为 monitoring.us-east1.amazonaws.com。
kinesis.endpoint
您的 Streams 服务的区域终端节点。默认为 kinesis.us-east1.amazonaws.com。
流程配置设置如下所示。所有字段均可选,不过 filePattern 和 kinesisStream 除外。
设置
说明
filePattern
需要由此代理监视的文件的 Glob。任何与此模式匹配的文件都是监控的候选
项。代理继续监视与此 Glob 匹配的文件,只要新文件出现就选取并使用。受
监控的文件限制为按最短 1 秒的时间间隔轮换或创建。与此模式匹配的文件
必须具有 aws-kinesis-agent-user 的读取权限。包含文件的目录必须具
有 aws-kinesis-agent-user 的读取和执行权限。
initialPosition
开始解析文件的初始位置。有效值为 START_OF_FILE 和 END_OF_FILE。
默认值:END_OF_FILE
kinesisStream
从受监控文件集发送数据的 Amazon Kinesis stream 的名称。
maxBufferAgeMillis 缓冲区保持不发送到目标的最长时间,以毫秒为单位。
值范围:1,000 到 900,000(1 秒到 15 分钟)
默认值:60,000(1 分钟)
maxBufferSizeBytes 每个 API 调用中发送到目标的批量记录的最大大小(字节)。
值范围:1 到 5,242,880 (5 MB)
默认值:5,242,880 (5 MB)
maxBufferSizeRecords
每个 API 调用中批量发送到目标的记录的最大数量。
值范围:1 到 500
默认值:500
minTimeBetweenFile- Streams 轮询所跟踪文件并开始解析新数据的时间间隔,以毫秒为单位。
PollsMillis
值范围:1 或更大值
默认值:100
multiLineStartPat- 用于标识记录开始的模式。记录由与模式匹配的行以及与模式不匹配的任何
以下行组成。有效值为正则表达式。默认情况下,日志文件中的每一个新行
tern
都被解析为一条记录。
56
Amazon Kinesis Streams 开发人员指南
使用代理写入
设置
说明
partitionKeyOption 分区键生成方法。
有效值:
RANDOM - 随机生成的整数。
DETERMINISTIC - 从数据 Blob 计算得到的哈希值。
默认值: RANDOM
skipHeaderLines
对于所跟踪的每个文件,跳过解析的开始行数。
默认值:0(零)
truncatedRecordTer- 记录超过了最大大小而需要截断时 Streams 放在记录结尾的字符串。
minator
默认值:"\n"(换行符)
在同一个数据创建器上处理多个文件
安装在数据创建器上的单个代理可以监控位于不同源文件位置的不同应用程序数据,并可以将它们提供给
相同或不同的 Amazon Kinesis stream。支持大部分常用文件滚动策略。代理支持 CSV 格式的单行记录
以及 JSON 格式的多行记录。使用代理可以预先批处理请求以提高吞吐量。批处理使用前面的表中的以
下任意可配置触发器刷新到服务:
• maxBufferSizeRecords - 最大记录数(通过 PutRecords 操作限制)
• maxBufferSizeBytes - 最大批处理大小(通过 PutRecords 操作限制)
• maxBufferAgeMillis - 最长批处理期限(毫秒,可配置)
对于要节省数据创建器计算机资源并发送非常小的离散文件的使用案例,建议使用预先聚合,特别是在单
个文件的大小小于几百个字节时。例如,股票代码行情。
同时写入到 Amazon Kinesis Firehose 和 Amazon Kinesis Streams
您可以通过添加多个文件流程到配置文件中,配置代理来发送数据到 Amazon Kinesis Firehose 和 Amazon
Kinesis Streams,如以下示例所示。请注意,您可以根据需要添加多个流程。Amazon Kinesis Streams
和 Amazon Kinesis Firehose 的默认终端节点为 us-east-1。如果您的流位于不同区域,则需要更新
kinesis.endpoint 和 firehose.endpoint。您的 Amazon Kinesis Streams 和 Amazon Kinesis
Firehose 传送流不必位于相同区域中。
{
"cloudwatch.emitMetrics": true,
"kinesis.endpoint": "https://your/kinesis/endpoint",
"firehose.endpoint": "https://your/firehose/endpoint",
"flows": [
{
"filePattern": "/tmp/app.log*",
"kinesisStream": "yourkinesisstream"
},
{
"filePattern": "/tmp/app.log*",
"deliveryStream": "yourfirehosedeliverystream"
}
57
Amazon Kinesis Streams 开发人员指南
问题排查
]
}
有用的代理 CLI 命令
有一些命令行函数可供您在使用代理时执行。
系统启动时自动启动代理:
sudo chkconfig aws-kinesis-agent on
检查代理的状态:
sudo service aws-kinesis-agent status
停止代理:
sudo service aws-kinesis-agent stop
从此位置读取代理的日志文件:
/var/log/aws-kinesis-agent/aws-kinesis-agent.log
卸载代理:
sudo yum remove aws-kinesis-agent
Amazon Kinesis Streams 创建器故障排除
Abstract
获取解决在使用 Amazon Kinesis Streams 创建器时所发现的问题的方案。
下列章节提供使用 Amazon Kinesis Streams 创建器时可能发现的一些常见问题的解决方案。
• 创建器应用程序的写入速率比预期的慢 (p. 58)
创建器应用程序的写入速率比预期的慢
写入吞吐量低于预期的最常见原因如下所示。
• 超过服务限制 (p. 58)
• 创建器优化 (p. 59)
超过服务限制
要查明是否超过了服务限制,请检查您的创建器是否从服务引发了吞吐量异常,并验证哪些 API 操作受
限制。请记住,根据调用会有不同的限制,具体请参阅the section called “限制” (p. 7)。例如,除了最广
为人知的对读写操作的分片级别限制之外,还存在以下流级别的限制:
• CreateStream
58
Amazon Kinesis Streams 开发人员指南
高级主题
• DeleteStream
• ListStreams
• GetShardIterator
• MergeShards
• DescribeStream
操作 CreateStream、DeleteStream、ListStreams、GetShardIterator 和 MergeShards 限制
为每秒 5 个调用。DescribeStream 操作限制为每秒 10 个调用。
如果这些调用不存在问题,请确保您选择了允许在所有分片之间均匀分配 put 操作的分区键,并且没有某
个特殊分区键无意中达到了服务限制而其他分区键则未达到限制。这要求您衡量高峰吞吐量并考虑流中的
分片数量。有关管理流的详细信息,请参阅the section called “管理流” (p. 87)。
Tip
请记住,在使用单记录操作 PutRecord 时,吞吐量限制计算会向上舍入到最接近的 KB 值,而
多记录操作 PutRecords 对各个调用中记录的累加和进行舍入。例如,带有 600 个 1.1 KB 大小
记录的 PutRecords 请求不会受到限制。
创建器优化
在您开始优化创建器之前,有一些关键任务需要完成。首先,根据记录大小和每秒记录数,确定您需要的
高峰吞吐量。接下来,排除流容量作为限制因素 (超过服务限制 (p. 58)) 的可能性。如果您已排除了流容
量,对于两种常见类型的创建器,请使用以下故障排除提示和优化指南。
大型创建器
大型创建器通常从本地服务器或 Amazon EC2 实例运行。需要由大型创建器提供较高吞吐量的客户通常
会关注每记录延迟。处理延迟的策略如下:如果客户可以微量批处理/缓冲记录,则使用 Amazon Kinesis
创建器库(具有高级聚合逻辑)、多记录操作 PutRecords 或者先将记录聚合到较大的文件中,然后再
使用单记录操作 PutRecord。如果无法批处理/缓冲,则使用多个线程来同时写入到 Streams 服务。AWS
SDK for Java 和其他开发工具包中包括异步客户端,可以用非常少的代码完成此任务。
小型创建器
小型创建器通常是移动应用程序、IoT 设备或 Web 客户端。如果是移动应用程序,我们建议使用
PutRecords 操作或 AWS 移动软件开发工具包中的 Amazon Kinesis 记录器。有关更多信息,请参阅 适
用于 Android 的 AWS SDK 入门指南 和 AWS Mobile SDK for iOS Getting Started Guide。移动应用程序
自身必须处理断续连接,并且需要某种类型的批量 put,例如 PutRecords。如果由于某些原因而无法批
处理,请参阅上面的大型创建器信息。如果您的创建器是浏览器,则生成的数据量通常非常小。不过,您
将 put 操作放在了应用程序的关键路径上,我们建议不要这样做。
有关 Amazon Kinesis Streams 生产者的高级主题
Abstract
了解如何优化您的 Amazon Kinesis Streams 生产者。
本节讨论如何优化您的 Amazon Kinesis Streams 生产者。
内容
• KPL 重试和速率限制 (p. 60)
• 使用 KPL 聚合时的注意事项 (p. 60)
59
Amazon Kinesis Streams 开发人员指南
高级主题
KPL 重试和速率限制
Abstract
在 Amazon Kinesis Streams 中自定义重试和速率限制行为。
当您使用 KPL addUserRecord() 操作添加 KPL 用户记录时,将利用由 RecordMaxBufferedTime 配
置参数设置的截止日期为记录提供一个时间戳并将记录添加到缓冲区。此时间戳/截止日期组合将设置缓
冲区优先级。记录基于以下标准从缓冲区进行刷新:
• 缓冲区优先级
• 聚合配置
• 集合配置
影响缓冲区行为的聚合和集合配置参数如下所示:
• AggregationMaxCount
• AggregationMaxSize
• CollectionMaxCount
• CollectionMaxSize
然后,刷新后的记录将通过调用 Streams API 操作 PutRecords 来作为 Amazon Kinesis Streams 发送
到您的 Amazon Kinesis stream。PutRecords 操作将请求发送到有时完全失败或部分失败的流。失败的
记录将自动添加回 KPL 缓冲区。基于这两个值中的较小值设置新的截止日期:
• 将当前 RecordMaxBufferedTime 配置分为两半
• 记录的生存时间值
此策略允许将重试的 KPL 用户记录包含在后续 Streams API 调用中,从而在强制实施 Streams 记录的生
存时间值时提高吞吐量并降低复杂性。不存在退避算法,这使得该策略成为相对积极的重试策略。由于重
试次数过多而造成的垃圾邮件会受到速率限制的阻止,该内容将在下一部分中进行讨论。
速率限制
KPL 包括速率限制功能,该功能可限制从单个创建器发送的每个分片的吞吐量。使用令牌桶算法以及同
时适用于 Streams 记录和字节的单独存储桶来实施速率限制。每当对 Amazon Kinesis stream 进行成功
写入时都会将一个令牌(或多个令牌)添加到每个存储桶,直至达到特定阈值。此阈值是可配置的,但默
认情况下设定的值将比实际分片限制高出 50%,这将允许单个创建器中的分片饱和。
您可减小此限制来减少因重试次数过多而造成的垃圾邮件。然而,最佳实践是每个创建器主动重试最大吞
吐量,通过扩展流的容量并实施相应的分区键策略来处理已确定为过多的任何结果限制。
使用 KPL 聚合时的注意事项
Abstract
Amazon Kinesis Streams 中 KPL 聚合的最佳实践。
当结果 Amazon Kinesis Streams 记录的序列号架构保持相同时,聚合会形成包含在以 0(零)为开始的
聚合 Streams 记录的 KPL 用户记录的索引;然而,只要您不依赖序列号来唯一标识您的 KPL 用户记录,
您的代码可忽略它,因为聚合(属于您的 Streams 记录中的 KPL 用户记录)和后续取消聚合(属于您的
KPL 用户记录中的 Streams 记录)将自动为您考虑这一方面。无论使用器是使用 KCL 还是 AWS 软件开
发工具包,这一点都适用。要使用此聚合功能,您需要将 KPL 的 Java 部分拉入您的版本中(如果您的使
用器是利用 AWS 软件开发工具包中提供的 API 编写的)。
60
Amazon Kinesis Streams 开发人员指南
读取流中的数据
如果您打算使用序列号作为 KPL 用户记录的唯一标识符,建议您使用 Record 和 UserRecord 中提供的
遵守合约的 public int hashCode() 和 public boolean equals(Object obj) 操作来比较您的
KPL 用户记录。此外,如果您希望检查 KPL 用户记录的子序列号,则可将其转换为 UserRecord 实例并
检索其子序列号。
有关更多信息,请参阅 the section called “使用器取消聚合” (p. 46)。
读取 Amazon Kinesis Streams 中的数据
Abstract
有关使用 AWS 开发工具包和 KCL 构建 Amazon Kinesis Streams 使用器的指南。
使用器 是读取和处理 Amazon Kinesis Streams 中的数据的应用程序。本节提供有关构建 Streams 使用
者的信息。如果您不熟悉 Streams,在使用本文档之前,请花点时间熟悉一下 什么是 Amazon Kinesis
Streams? (p. 1) 和 开始使用 Amazon Kinesis Streams (p. 8) 这两节中介绍的概念和术语。
主题
• 使用 Amazon Kinesis Client Library 开发 Amazon Kinesis Streams 使用器 (p. 61)
• 通过将 Amazon Kinesis Streams API 与适用于 Java 的 AWS 开发工具包结合使用来开发 Amazon
Kinesis Streams 使用者 (p. 75)
• Amazon Kinesis Streams 使用者问题排查 (p. 79)
• 有关 Amazon Kinesis Streams 使用者的高级主题 (p. 81)
使用 Amazon Kinesis Client Library 开发 Amazon
Kinesis Streams 使用器
Abstract
KCL 为 Amazon Kinesis Streams 使用者应用程序提供设计模式和代码。
您可使用 Amazon Kinesis Client Library (KCL) 开发适用于 Amazon Kinesis Streams 的使用器应用程序。
尽管您可使用 Streams API 从 Amazon Kinesis stream 中获取数据,但我们建议为 KCL 提供的使用者应
用程序使用设计模式和代码。
您可利用 Amazon CloudWatch 监控 KCL。有关更多信息,请参阅 the section called “利用 CloudWatch
监控 KCL” (p. 103)。
内容
• Amazon Kinesis Client Library (p. 62)
• KCL 的角色 (p. 62)
• 在 Java 中开发 Amazon Kinesis Client Library 使用者 (p. 62)
• 在 Node.js 中开发 Amazon Kinesis Client Library 使用者 (p. 67)
• 在 .NET 中开发 Amazon Kinesis Client Library 使用者 (p. 70)
• 在 Python 中开发 Amazon Kinesis Client Library 使用者 (p. 72)
• 在 Ruby 中开发 Amazon Kinesis Client Library 使用者 (p. 74)
61
Amazon Kinesis Streams 开发人员指南
使用 KCL
Amazon Kinesis Client Library
Amazon Kinesis Client Library (KCL) 帮助您使用和处理来自 Amazon Kinesis stream 的数据。此类应用
程序也称为使用者。KCL 负责执行与分配式计算关联的许多复杂任务,如跨多个实例进行负载均衡、响
应实例故障、对已处理记录进行检查点操作以及对重新分片作出反应。KCL 使您能够专注于编写记录处
理逻辑。
请注意,KCL 与 AWS 软件开发工具包中提供的 Streams API 不同。Streams API 可帮助您管理 Streams
的许多方面(包括创建流、重新分片以及放置和获取记录),而 KCL 提供了专门用于以使用者角色处理
数据的抽象层。有关 Streams API 的信息,请参阅 Amazon Kinesis API Reference。
KCL 是一个 Java 库,支持 Java 以外的其他语言,提供使用多语言界面,称为MultiLangDaemon。此后
台程序是基于 Java 和在后台运行,当您使用 KCL 语言而非 Java。例如,如果您安装了适用于 Python
的 KCL 并完全在 Python 中编写使用者应用程序,则由于 MultiLangDaemon,您仍需要在您的系统中安
装 Java。此外,MultiLangDaemon 有一些默认设置,您可能需要根据自己的使用案例进行自定义,例如
所连接到的 AWS 区域。有关 MultiLangDaemon 的更多信息,请转至 GitHub 上的 KCL MultiLangDaemon
项目页。
在运行时,KCL 应用程序利用配置信息实例化工作程序,然后使用记录处理器处理从 Amazon Kinesis
stream 接收的数据。您可以在任意数量的实例上运行 KCL 应用程序。同一应用程序的多个实例将动态协
调故障和负载均衡。您还可以使用多个 KCL 应用程序处理相同的流,具体取决于吞吐量限制。
KCL 的角色
KCL 充当您的记录处理逻辑和 Streams 之间的中介。
当您启动 KCL 应用程序时,它会调用 KCL 来实例化工作程序。这一调用将为应用程序提供带配置信息的
KCL,如流名称和 AWS 凭证。
KCL 将执行以下任务:
•
•
•
•
•
•
•
•
连接到流
枚举分片
协调与其他工作程序的分片关联(如果有)
为其管理的每个分片实例化记录处理器
从流中提取数据记录
将记录推送到对应的记录处理器
对已处理记录进行检查点操作
在工作程序实例计数更改时均衡分片与工作程序的关联
• 在分片被拆分或合并时均衡分片与工作程序的关联
在 Java 中开发 Amazon Kinesis Client Library 使用者
Abstract
了解使用 KCL 在 Java 中开发使用者应用程序的基础知识。
您可使用 Amazon Kinesis Client Library (KCL) 来构建处理您的 Amazon Kinesis stream 中的数据的应用
程序。Amazon Kinesis Client Library有多种语言版本。本主题将讨论 Java。
要从 GitHub 下载 Java KCL,请转至 Amazon Kinesis Client Library (Java)。要查找 Maven 上的 Java
KCL,请转至 KCL 搜索结果页。要从 GitHub 下载 Java KCL 使用者应用程序的示例代码,请转至 GitHub
上的适用于 Java 的 KCL 示例项目页。
62
Amazon Kinesis Streams 开发人员指南
使用 KCL
该示例应用程序使用 Apache Commons Logging。您可以使用文件
AmazonKinesisApplicationSample.java 中定义的静态 configure 方法更改日志记录配置。有关
如何将 Apache Commons Logging 用于 Log4j 和 AWS Java 应用程序的更多信息,请参阅 AWS SDK for
Java Developer Guide 中的使用 Log4j 进行日志记录。
在 Java 中实现 KCL 使用者应用程序时,您必须完成下列任务:
任务
• 实现 IRecordProcessor 方法 (p. 63)
• 为 IRecordProcessor 接口实现类工厂 (p. 65)
• 创建工作线程 (p. 65)
• 修改配置属性 (p. 66)
• 迁移到版本 2 的记录处理器接口 (p. 67)
实现 IRecordProcessor 方法
KCL 当前支持两个版本的 IRecordProcessor 接口 - KCL 的第一个版本附带的原始接口,以及从 KCL
1.5.0 版开始的版本 2 接口。这两个接口都完全受支持;您的选择取决于您的特定方案要求。请参阅您在
本地构建的 Javadocs 或源代码以查看所有区别。以下各节概述了开始使用的最低实施要求。
IRecordProcessor 版本
• 原始接口(版本 1) (p. 63)
• 更新后的接口(版本 2) (p. 64)
原始接口(版本 1)
原始 IRecordProcessor 接口 (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 在实例化记录处理器时调用 initialize 方法,并将特定分片 ID 作为参数传递。此记录处理器仅
处理此分片,并且通常情况下反过来说也成立(此分片仅由此记录处理器处理)。但是,您的使用者应该
考虑数据记录可能会经过多次处理的情况。Streams 具有“至少一次”语义,即分片中的每个数据记录至少
会被您的使用者中的工作程序处理一次。有关特定分片可能由多个工作程序进行处理的情况的更多信息,
请参阅the section called “重新分片、扩展和并行处理” (p. 83)。
processRecords
public void processRecords(List<Record> records, IRecordProcessorCheckpointer
checkpointer)
63
Amazon Kinesis Streams 开发人员指南
使用 KCL
KCL 调用 processRecords 方法,并传递来自由 initialize(shardId) 方法指定的分片的数据记录
的列表。记录处理器根据使用者的语义处理这些记录中的数据。例如,工作程序可能对数据执行转换,然
后将结果存储在 Amazon S3 存储桶中。
除了数据本身之外,记录还包含一个序号和一个分区键。工作程序可在处理数据时使用这些值。例如,工
作线程可选择 S3 存储桶,并在其中根据分区键的值存储数据。Record 类公开了以下方法,这些方法提
供对记录的数据、序列号和分区键的访问。
record.getData()
record.getSequenceNumber()
record.getPartitionKey()
在该示例中,私有方法 processRecordsWithRetries 具有显示工作程序如何访问记录的数据、序号
和分区键的代码。
Streams 需要记录处理器来跟踪已在分片中处理的记录。KCL 通过将检查指针
(IRecordProcessorCheckpointer) 传递到 processRecords 来为您执行此跟踪。记录处理器将对此
接口调用 checkpoint 方法,以向 KCL 告知记录处理器处理分片中的记录的进度。如果工作程序失败,
KCL 将使用此信息在上一个已知的已处理记录处重新启动分片的处理。
对于拆分或合并操作,在原始分片的处理器调用 checkpoint 以指示原始分片上的所有处理操作都已完
成之前,KCL 不会开始处理新分片。
如果您未传递参数,KCL 将假定对 checkpoint 的调用表示所有记录都已处理,一直处理到传递到记录
处理器的最后一个记录。因此,记录处理器只应在已处理传递到它的列表中的所有记录后才调用
checkpoint。记录处理器不需要在每次调用 processRecords 时调用 checkpoint。例如,处理器可
以在每第三次调用 processRecords 时调用 checkpoint。您可以选择性地将某个记录的确切序号指定
为 checkpoint 的参数。在本例中,KCL 将假定所有记录都已处理,一直到达该记录。
在该示例中,私有方法 checkpoint 展示了如何使用适当的异常处理和重试逻辑调用
IRecordProcessorCheckpointer.checkpoint。
KCL 依靠 processRecords 来处理由处理数据记录引起的任何异常。如果 processRecords 引发了异
常,则 KCL 会跳过在异常发生前传递的数据记录;也就是说,这些记录不会重新发送到引发了异常的记
录处理器或使用者中的任何其他记录处理器。
shutdown
public void shutdown(IRecordProcessorCheckpointer checkpointer, ShutdownReason
reason)
KCL 在处理结束(关闭原因为 TERMINATE)或工作程序不再响应(关闭原因为 ZOMBIE)时调用 shutdown
方法。
处理操作在记录处理器不再从分片中接收任何记录时结束,因为分片已被拆分或合并,或者流已删除。
KCL 还会将 IRecordProcessorCheckpointer 接口传递到 shutdown。如果关闭原因为 TERMINATE,
则记录处理器应完成处理任何数据记录,然后对此接口调用 checkpoint 方法。
更新后的接口(版本 2)
更新后的 IRecordProcessor 接口 (package
com.amazonaws.services.kinesis.clientlibrary.interfaces.v2) 公开了下列记录处理器方
法,您的使用者必须实施这些方法:
64
Amazon Kinesis Streams 开发人员指南
使用 KCL
void initialize(InitializationInput initializationInput)
void processRecords(ProcessRecordsInput processRecordsInput)
void shutdown(ShutdownInput shutdownInput)
原始版本的接口中的所有参数可通过容器对象上的 get 方法进行访问。例如,要检索 processRecords()
中的记录的列表,可使用 processRecordsInput.getRecords()。
自此接口的版本 2(KCL 1.5.0 及更高版本)起,除了原始接口提供的输入之外,以下新输入也可用:
起始序列号
在传递给 initialize() 运算的 InitializationInput 对象中,将提供给记录处理器实例的记
录的起始序列号。这是由之前处理同一分片的记录处理器实例进行最近一次检查点操作的序列号。此
序列号在您的应用程序需要此信息时提供。
待进行检查点操作的序列号
在传递给 initialize() 运算的 InitializationInput 对象中,在上一个记录处理器实例停止
前可能无法提交的待进行检查点操作的序列号(如果有)。当您的应用程序使用的是 KCL 1.5.0 中引
入的两阶段检查点协议并且需要实现幂等处理时,这非常有用。
为 IRecordProcessor 接口实现类工厂
您还需要为实现记录处理器方法的类实现一个工厂。当使用者实例化工作程序时,它将传递对此工厂的引
用。
以下示例使用原始记录处理器接口在文件
AmazonKinesisApplicationSampleRecordProcessorFactory.java 中实现工厂类。如果您希望
此工厂类创建版本 2 记录处理器,请使用程序包名称
com.amazonaws.services.kinesis.clientlibrary.interfaces.v2。
public class SampleRecordProcessorFactory implements IRecordProcessorFactory
{
/**
* Constructor.
*/
public SampleRecordProcessorFactory() {
super();
}
/**
* {@inheritDoc}
*/
@Override
public IRecordProcessor createProcessor() {
return new SampleRecordProcessor();
}
}
创建工作线程
如 the section called “实现 IRecordProcessor 方法” (p. 63) 一节中讨论的,有两个版本的 KCL 记录处理
器接口可供选择,这将影响您创建工作线程的方式。原始记录处理器接口使用以下代码结构创建工作线
程:
final KinesisClientLibConfiguration config = new KinesisClientLibConfigura
tion(...)
65
Amazon Kinesis Streams 开发人员指南
使用 KCL
final IRecordProcessorFactory recordProcessorFactory = new RecordProcessorFact
ory();
final Worker worker = new Worker(recordProcessorFactory, config);
当使用版本 2 的记录处理器接口时,您可使用 Worker.Builder 创建工作线程而无需担心要使用的构造
函数以及参数的顺序。更新后的记录处理器接口使用以下代码结构创建工作线程:
final KinesisClientLibConfiguration config = new KinesisClientLibConfigura
tion(...)
final IRecordProcessorFactory recordProcessorFactory = new RecordProcessorFact
ory();
final Worker worker = new Worker.Builder()
.recordProcessorFactory(recordProcessorFactory)
.config(config)
.build();
修改配置属性
该示例提供了配置属性的默认值。工作程序的此配置数据随后将整合到
KinesisClientLibConfiguration 对象中。此对象和对 IRecordProcessor 的类工厂的引用将传
入用于实例化工作程序的调用。您可借助 Java 属性文件(请参阅
AmazonKinesisApplicationSample.java)用您自己的值覆盖任何这些属性。
Application Name
KCL 需要一个应用程序名称,该名称在您的应用程序中以及同一区域的 DynamoDB 表中是唯一的。KCL
通过以下方法使用应用程序名称配置值:
• 假定所有与此应用程序名称关联的工作程序在同一数据流上合作。这些工作程序可被分配到多个实例
上。如果运行同一应用程序代码的其他实例,但使用不同的应用程序名称,则 KCL 会将第二个实例视
为在同一数据流运行的完全独立的应用程序。
• KCL 利用应用程序名称创建 DynamoDB 表并使用该表保留应用程序的状态信息(如检查点和工作程序
-分片映射)。每个应用程序都有自己的 DynamoDB 表。有关更多信息,请参阅 the section called “跟
踪状态” (p. 81)。
设置凭证
您必须向默认凭证提供程序链中的凭证提供程序之一提供您的 AWS 凭证。例如,如果您正在 EC2 实例
上运行您的使用者,我们建议您使用 IAM 角色启动实例。反映与此 IAM 角色关联的权限的 AWS 凭证通
过实例的元数据提供给实例上的应用程序。使用这种方式管理在 EC2 实例上运行的使用者的凭证最安全。
示例应用程序首先尝试从实例元数据中检索 IAM 凭证:
credentialsProvider = new InstanceProfileCredentialsProvider();
如果示例应用程序无法从实例元数据中获取凭证,它会尝试从属性文件中检索凭证:
credentialsProvider = new ClasspathPropertiesFileCredentialsProvider();
有关实例元数据的更多信息,请参阅 Amazon EC2 用户指南(适用于 Linux 实例) 中的实例元数据。
66
Amazon Kinesis Streams 开发人员指南
使用 KCL
将工作程序 ID 用于多个实例
示例初始化代码通过使用本地计算机的名称并附加一个全局唯一的标识符为工作程序创建 ID (workerId),
如以下代码段所示。此方法支持使用者应用程序的多个实例在单台计算机上运行的方案。
String workerId = InetAddress.getLocalHost().getCanonicalHostName() + ":" +
UUID.randomUUID();
迁移到版本 2 的记录处理器接口
如果要迁移使用原始接口的代码,则除了上述步骤之外,还需要执行以下步骤:
1.
更改您的记录处理器类以导入版本 2 记录处理器接口:
import com.amazonaws.services.kinesis.clientlibrary.interfaces.v2.IRecord
Processor;
2.
更改对输入的引用以使用容器对象上的 get 方法。例如,在 shutdown() 运算中,将“checkpointer”
更改为“shutdownInput.getCheckpointer()”。
3.
更改您的记录处理器工厂类以导入版本 2 记录处理器工厂接口:
import com.amazonaws.services.kinesis.clientlibrary.interfaces.v2.IRecord
ProcessorFactory;
4.
更改工作线程的结构以使用 Worker.Builder。例如:
final Worker worker = new Worker.Builder()
.recordProcessorFactory(recordProcessorFactory)
.config(config)
.build();
在 Node.js 中开发 Amazon Kinesis Client Library 使用者
Abstract
了解使用 KCL 在 Node.js 中开发使用者应用程序的基础知识。
您可使用 Amazon Kinesis Client Library (KCL) 来构建处理您的 Amazon Kinesis stream 中的数据的应用
程序。Amazon Kinesis Client Library有多种语言版本。本主题将讨论 Node.js。
KCL 是一个 Java 库,支持 Java 以外的其他语言,提供使用多语言界面,称为MultiLangDaemon。此后
台程序是基于 Java 和在后台运行,当您使用 KCL 语言而非 Java。因此,如果您安装了适用于 Node.js
的 KCL 并完全在 Node.js 中编写使用者应用程序,则由于 MultiLangDaemon,您仍需要在您的系统中安
装 Java。此外,MultiLangDaemon 有一些默认设置,您可能需要根据自己的使用案例进行自定义,例如
所连接到的 AWS 区域。有关 GitHub 上的 MultiLangDaemon 的更多信息,请转至 KCL MultiLangDaemon
项目页。
要从 GitHub 下载 Node.js KCL,请转至 Amazon Kinesis Client Library (Node.js)。
示例代码下载
Node.js 中有两个代码示例可用于 KCL:
67
Amazon Kinesis Streams 开发人员指南
使用 KCL
• basic-sample
在下列节中用于阐释使用 Node.js 构建 KCL 使用者应用程序的基础知识。
• click-stream-sample
稍微复杂一些,使用了现实世界的情景,适合在您熟悉基本示例代码之后采用。此示例在这里不做讨
论,但它有一个包含更多信息的自述文件。
在 Node.js 中实现 KCL 使用者应用程序时,您必须完成下列任务:
任务
• 实现记录处理器 (p. 68)
• 修改配置属性 (p. 69)
实现记录处理器
使用适用于 Node.js 的 KCL 的可能最简单的使用者必须实现 recordProcessor 函数,该函数反过来包
含函数 initialize、processRecords 和 shutdown。该示例提供了可用作起点的实现(请参阅
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 具有“至少一次”语义,即分
片中的每个数据记录至少会被您的使用者中的工作程序处理一次。有关特定分片可能由多个工作程序进行
处理的情况的更多信息,请参阅the section called “重新分片、扩展和并行处理” (p. 83)。
processRecords
processRecords : function (processRecordsInput, completeCallback)
KCL 使用包含一个数据记录的列表(这些记录来自在 initialize 函数中指定的分片)的输入来调用此
函数。您实现的记录处理器根据您的使用者的语义处理这些记录中的数据。例如,工作线程可能对数据执
行转换,然后将结果存储在 S3 存储桶中。
除了数据本身之外,记录还包含工作程序在处理数据时可使用的序号和分区键。例如,工作线程可选择
S3 存储桶,并在其中根据分区键的值存储数据。record 词典公开了以下键-值对来访问记录的数据、序
号和分区键:
record.data
record.sequenceNumber
record.partitionKey
请注意,数据是 Base64 编码的。
68
Amazon Kinesis Streams 开发人员指南
使用 KCL
在该基本示例中,函数 processRecords 具有显示工作程序如何访问记录的数据、序号和分区键的代
码。
Streams 需要记录处理器来跟踪已在分片中处理的记录。KCL 利用作为
processRecordsInput.checkpointer 传递的 checkpointer 执行此跟踪。您的记录处理器将调用
checkpointer.checkpoint 函数以向 KCL 告知记录处理器处理分片中的记录的进度。如果工作程序
失败,KCL 将在您重新启动分片的处理时使用此信息,以便在上一个已知的已处理记录处继续处理。
对于拆分或合并操作,在原始分片的处理器调用 checkpoint 以指示原始分片上的所有处理操作都已完
成之前,KCL 不会开始处理新分片。
如果您未将序号传递到 checkpoint 函数,KCL 将假定对 checkpoint 的调用表示所有记录都已处理,
一直处理到传递到记录处理器的最后一个记录。因此,记录处理器只应在已处理传递到它的列表中的所有
记录后才调用 checkpoint。记录处理器不需要在每次调用 processRecords 时调用 checkpoint。例
如,处理器可以在每第三次调用时调用 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)。
Application Name
KCL 需要一个应用程序名称,该名称在您的应用程序中以及同一区域的 DynamoDB 表中是唯一的。KCL
通过以下方法使用应用程序名称配置值:
• 假定所有与此应用程序名称关联的工作程序在同一数据流上合作。这些工作程序可被分配到多个实例
上。如果运行同一应用程序代码的其他实例,但使用不同的应用程序名称,则 KCL 会将第二个实例视
为在同一数据流运行的完全独立的应用程序。
• KCL 利用应用程序名称创建 DynamoDB 表并使用该表保留应用程序的状态信息(如检查点和工作程序
-分片映射)。每个应用程序都有自己的 DynamoDB 表。有关更多信息,请参阅 the section called “跟
踪状态” (p. 81)。
设置凭证
您必须向默认凭证提供程序链中的凭证提供程序之一提供您的 AWS 凭证。您可使用
AWSCredentialsProvider 属性设置凭证提供程序。sample.properties 文件需要向默认凭证提供
程序链中的凭证提供程序之一提供您的凭证。如果您正在 EC2 实例上运行您的使用者,我们建议您使用
69
Amazon Kinesis Streams 开发人员指南
使用 KCL
IAM 角色配置实例。反映与此 IAM 角色关联的权限的 AWS 凭证通过实例的元数据提供给实例上的应用
程序。使用这种方式管理在 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 使用者
Abstract
了解使用 KCL 在 .NET 中开发使用者应用程序的基础知识。
您可使用 Amazon Kinesis Client Library (KCL) 来构建处理您的 Amazon Kinesis stream 中的数据的应用
程序。Amazon Kinesis Client Library有多种语言版本。本主题将讨论 .NET。
KCL 是一个 Java 库,支持 Java 以外的其他语言,提供使用多语言界面,称为MultiLangDaemon。此后
台程序是基于 Java 和在后台运行,当您使用 KCL 语言而非 Java。因此,如果您安装了适用于 .NET 的
KCL 并完全在 .NET 中编写使用者应用程序,则由于 MultiLangDaemon,您仍需要在您的系统中安装
Java。此外,MultiLangDaemon 有一些默认设置,您可能需要根据自己的使用案例进行自定义,例如所
连接到的 AWS 区域。有关 MultiLangDaemon 的更多信息,请转至 GitHub 上的 KCL MultiLangDaemon
项目页。
要从 GitHub 下载 .NET KCL,请转至 Amazon Kinesis Client Library (.NET)。要下载适用于 .NET KCL
使用者应用程序的示例代码,请转至 GitHub 上的 适用于 .NET 的 KCL 示例使用者项目页。
在 .NET 中实现 KCL 使用者应用程序时,您必须完成下列任务:
任务
• 实现 IRecordProcessor 类方法 (p. 70)
• 修改配置属性 (p. 72)
实现 IRecordProcessor 类方法
使用者必须实现适用于 IRecordProcessor 的以下方法。示例使用者提供了可用作起点的实现(请参阅
SampleConsumer/AmazonKinesisSampleConsumer.cs 中的 SampleRecordProcessor 类)。
public void Initialize(InitializationInput input)
public void ProcessRecords(ProcessRecordsInput input)
public void Shutdown(ShutdownInput input)
70
Amazon Kinesis Streams 开发人员指南
使用 KCL
Initialize
public void Initialize(InitializationInput input)
KCL 在实例化记录处理程序时调用此方法,并将特定分片 ID 传入 input 参数 (input.ShardId)。此记
录处理器只处理此分片,并且通常情况下反过来说也成立(此分片只能由此记录处理器处理)。但是,您
的使用者应该考虑数据记录可能会经过多次处理的情况。这是因为 Streams 具有“至少一次”语义,即分片
中的每个数据记录在您的使用者中由工作程序至少处理一次。有关特定分片可能由多个工作程序进行处理
的情况的更多信息,请参阅the section called “重新分片、扩展和并行处理” (p. 83)。
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 将使用此信息在上一个已知的已处理记录处重新启动分片的处理。
对于拆分或合并操作,在原始分片的处理器调用 Checkpointer.Checkpoint 以指示原始分片上的所有
处理操作都已完成之前,KCL 不会开始处理新分片。
如果您未传递参数,KCL 将假定对 Checkpointer.Checkpoint 的调用表示所有记录都已处理,一直
处理到传递到记录处理器的最后一个记录。因此,记录处理器只应在已处理传递到它的列表中的所有记录
后才调用 Checkpointer.Checkpoint。记录处理器不需要在每次调用 ProcessRecords 时调用
Checkpointer.Checkpoint。例如,处理器在每第三次或第四次调用时调用
Checkpointer.Checkpoint。您可以选择性地将某个记录的确切序号指定为
Checkpointer.Checkpoint 的参数。在本例中,KCL 将假定所有记录都已处理,一直处理到该记录。
在该示例中,私有方法 Checkpoint(Checkpointer checkpointer) 展示了如何使用适当的异常处
理和重试逻辑调用 Checkpointer.Checkpoint 方法。
适用于 .NET 的 KCL 处理异常的方式不同于其他 KCL 语言库,前者不处理因处理数据记录而引起的任何
异常。用户代码中任何未捕获的异常都将使程序崩溃。
关闭
public void Shutdown(ShutdownInput input)
71
Amazon Kinesis Streams 开发人员指南
使用 KCL
KCL 在处理结束(关闭原因为 TERMINATE)或工作程序不再响应(关闭 input.Reason 值为 ZOMBIE)
时调用 Shutdown 方法。
处理操作在记录处理器不再从分片中接收任何记录时结束,因为分片已被拆分或合并,或者流已删除。
KCL 还会将 Checkpointer 对象传递到 shutdown。如果关闭原因为 TERMINATE,则记录处理器应完
成处理任何数据记录,然后对此接口调用 checkpoint 方法。
修改配置属性
示例使用者提供了配置属性的默认值。您可使用自己的值覆盖任何这些属性(请参阅
SampleConsumer/kcl.properties)。
Application Name
KCL 需要一个应用程序名称,该名称在您的应用程序中以及同一区域的 DynamoDB 表中是唯一的。KCL
通过以下方法使用应用程序名称配置值:
• 假定所有与此应用程序名称关联的工作程序在同一数据流上合作。这些工作程序可被分配到多个实例
上。如果运行同一应用程序代码的其他实例,但使用不同的应用程序名称,则 KCL 会将第二个实例视
为在同一数据流运行的完全独立的应用程序。
• KCL 利用应用程序名称创建 DynamoDB 表并使用该表保留应用程序的状态信息(如检查点和工作程序
-分片映射)。每个应用程序都有自己的 DynamoDB 表。有关更多信息,请参阅 the section called “跟
踪状态” (p. 81)。
设置凭证
您必须向默认凭证提供程序链中的凭证提供程序之一提供您的 AWS 凭证。您可使用
AWSCredentialsProvider 属性设置凭证提供程序。sample.properties 需要向默认凭证提供程序链中
的凭证提供程序之一提供您的凭证。如果您正在 EC2 实例上运行您的使用者应用程序,我们建议您使用
IAM 角色配置实例。反映与此 IAM 角色关联的权限的 AWS 凭证通过实例的元数据提供给实例上的应用
程序。使用这种方式管理在 EC2 实例上运行的使用者的凭证最安全。
该示例的属性文件将配置 KCL 以使用 AmazonKinesisSampleConsumer.cs 中提供的记录处理器处理
名为“words”的 Amazon Kinesis stream。
在 Python 中开发 Amazon Kinesis Client Library 使用者
Abstract
了解使用 KCL 在 Python 中开发使用者应用程序的基础知识。
您可使用 Amazon Kinesis Client Library (KCL) 来构建处理您的 Amazon Kinesis stream 中的数据的应用
程序。Amazon Kinesis Client Library有多种语言版本。本主题将讨论 Python。
KCL 是一个 Java 库,支持 Java 以外的其他语言,提供使用多语言界面,称为MultiLangDaemon。此后
台程序是基于 Java 和在后台运行,当您使用 KCL 语言而非 Java。因此,如果您安装了适用于 Python
的 KCL 并完全在 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 上的适用于 Python 的 KCL 示例项目页。
在 Python 中实现 KCL 使用者应用程序时,您必须完成下列任务:
72
Amazon Kinesis Streams 开发人员指南
使用 KCL
任务
• 实现 RecordProcessor 类方法 (p. 73)
• 修改配置属性 (p. 74)
实现 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 在实例化记录处理器时调用 initialize 方法,并将特定分片 ID 作为参数传递。此记录处理器只
处理此分片,并且通常情况下反过来说也成立(此分片只能由此记录处理器处理)。但是,您的使用者应
该考虑数据记录可能会经过多次处理的情况。这是因为 Streams 具有“至少一次”语义,即分片中的每个数
据记录在您的使用者中由工作程序至少处理一次。有关特定分片可能由多个工作程序进行处理的情况的更
多信息,请参阅the section called “重新分片、扩展和并行处理” (p. 83)。
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 将使用此信息在上一个已知的已处理记
录处重新启动分片的处理。
对于拆分或合并操作,在原始分片的处理器调用 checkpoint 以指示原始分片上的所有处理操作都已完
成之前,KCL 不会开始处理新分片。
如果您未传递参数,KCL 将假定对 checkpoint 的调用表示所有记录都已处理,一直处理到传递到记录
处理器的最后一个记录。因此,记录处理器只应在已处理传递到它的列表中的所有记录后才调用
checkpoint。记录处理器不需要在每次调用 process_records 时调用 checkpoint。例如,处理器
73
Amazon Kinesis Streams 开发人员指南
使用 KCL
可在每第三次调用时调用 checkpoint。您可以选择性地将某个记录的确切序号指定为 checkpoint 的
参数。在本例中,KCL 将假定所有记录都已处理,一直到达该记录。
在该示例中,私有方法 checkpoint 展示了如何使用适当的异常处理和重试逻辑调用
Checkpointer.checkpoint 方法。
KCL 依靠 process_records 来处理由处理数据记录引起的任何异常。如果从 process_records 中引
发了异常,则 KCL 会跳过在异常发生前传递到 process_records 的数据记录;也就是说,这些记录不
会重新发送到引发了异常的记录处理器或使用者中的任何其他记录处理器。
shutdown
def shutdown(self, checkpointer, reason)
KCL 在处理结束(关闭原因为 TERMINATE)或工作程序不再响应(关闭 reason 为 ZOMBIE)时调用
shutdown 方法。
处理操作在记录处理器不再从分片中接收任何记录时结束,因为分片已被拆分或合并,或者流已删除。
KCL 还会将 Checkpointer 对象传递到 shutdown。如果关闭 reason 是 TERMINATE,则记录处理器
应完成处理任何数据记录,然后对此接口调用 checkpoint 方法。
修改配置属性
该示例提供了配置属性的默认值。您可使用自己的值覆盖任何这些属性(请参阅 sample.properties)。
Application Name
KCL 需要一个应用程序名称,该名称在您的应用程序中以及同一区域的 DynamoDB 表中是唯一的。KCL
通过以下方法使用应用程序名称配置值:
• 假定所有与此应用程序名称关联的工作程序在同一数据流上合作。这些工作程序可被分配到多个实例
上。如果运行同一应用程序代码的其他实例,但使用不同的应用程序名称,则 KCL 会将第二个实例视
为在同一数据流运行的完全独立的应用程序。
• KCL 利用应用程序名称创建 DynamoDB 表并使用该表保留应用程序的状态信息(如检查点和工作程序
-分片映射)。每个应用程序都有自己的 DynamoDB 表。有关更多信息,请参阅 the section called “跟
踪状态” (p. 81)。
设置凭证
您必须向默认凭证提供程序链中的凭证提供程序之一提供您的 AWS 凭证。您可使用
AWSCredentialsProvider 属性设置凭证提供程序。sample.properties 需要向默认凭证提供程序链中
的凭证提供程序之一提供您的凭证。如果您正在 EC2 实例上运行您的使用者应用程序,我们建议您使用
IAM 角色配置实例。反映与此 IAM 角色关联的权限的 AWS 凭证通过实例的元数据提供给实例上的应用
程序。使用这种方式管理在 EC2 实例上运行的使用者应用程序的凭证最安全。
该示例的属性文件将配置 KCL 以使用 sample_kclpy_app.py 中提供的记录处理器处理名为“words”的
Amazon Kinesis stream。
在 Ruby 中开发 Amazon Kinesis Client Library 使用者
Abstract
了解使用 KCL 在 Ruby 中开发使用者应用程序的基础知识。
您可使用 Amazon Kinesis Client Library (KCL) 来构建处理您的 Amazon Kinesis stream 中的数据的应用
程序。Amazon Kinesis Client Library有多种语言版本。本主题将讨论 Ruby。
74
Amazon Kinesis Streams 开发人员指南
使用 API
KCL 是一个 Java 库,支持 Java 以外的其他语言,提供使用多语言界面,称为MultiLangDaemon。此后
台程序是基于 Java 和在后台运行,当您使用 KCL 语言而非 Java。 因此,如果您安装了适用于 Ruby 的
KCL 并完全在 Ruby 中编写使用者应用程序,则由于 MultiLangDaemon,您仍需要在您的系统中安装
Java。此外,MultiLangDaemon 有一些默认设置,您可能需要根据自己的使用案例进行自定义,例如所
连接到的 AWS 区域。有关 MultiLangDaemon 的更多信息,请转至 GitHub 上的 KCL MultiLangDaemon
项目页。
要从 GitHub 下载 Ruby KCL,请转至 Amazon Kinesis Client Library (Ruby)。要下载适用于 Ruby KCL
使用者应用程序的示例代码,请转至 GitHub 上的适用于 Ruby 的 KCL 示例项目页。
有关 KCL Ruby 支持库的更多信息,请参阅 KCL Ruby Gems Documentation。
通过将 Amazon Kinesis Streams API 与适用于 Java
的 AWS 开发工具包结合使用来开发 Amazon Kinesis
Streams 使用者
Abstract
有关使用 Amazon Kinesis Streams API 开发 Amazon Kinesis Streams 使用者的示例和指导。
本节提供有关将 Amazon Kinesis Streams API 与适用于 Java 的 AWS 开发工具包结合使用来开发使用者
的信息。如果您不熟悉 Streams,在使用本文档之前,请花点时间熟悉一下 什么是 Amazon Kinesis
Streams? (p. 1) 和 开始使用 Amazon Kinesis Streams (p. 8) 这两节中介绍的概念和术语。
这些示例讨论 Streams API 并使用适用于 Java 的 AWS 开发工具包从流中获取数据。但是,在大多数使
用案例中,您应会更喜欢使用 Streams KCL 库。有关更多信息,请参阅 the section called “使用
KCL” (p. 61)。
本章中的 Java 示例代码演示如何执行基本的 Streams API 操作,并按照操作类型从逻辑上进行划分。这
些示例并非可直接用于生产的代码,因为它们不会检查所有可能的异常,或者不会考虑到所有可能的安全
或性能问题。此外,您可使用其他不同的编程语言调用 Streams API。有关所有可用 AWS 开发工具包的
更多信息,请参阅开始使用 Amazon Web Services 开发。
本节中的每个任务都有先决条件;例如,您在创建流之前不能向流中添加数据,这需要您创建一个客户
端。有关更多信息,请参阅 the section called “管理流” (p. 87)。
从流中获取数据
Abstract
了解如何使用适用于 Java 的 AWS 开发工具包从 Amazon Kinesis stream 流获取数据。
Streams API 提供了用于从流检索数据的 getShardIterator 和 getRecords 方法。这些方法代表“拉
取”模式,在此模式下,您的代码将直接从流的指定分片中获取数据。
一般来说,您应更喜欢使用 Amazon Kinesis Client Library (KCL) 提供的记录处理器支持来检索消费者应
用程序中的流数据。这表示“推送”模式,在此模式下,您只需实现处理数据的代码即可。KCL 将会执行从
流检索数据记录并将数据记录交付给您的应用程序代码的工作。此外,KCL 还提供故障转移、恢复和负
载均衡功能。有关更多信息,请参阅 使用 Amazon Kinesis Client Library 开发 Amazon Kinesis Streams
使用器 (p. 61)。
但是,在某些情况下,您可能倾向于将 Streams API 与适用于 Java 的 AWS 开发工具包结合使用。例
如,在实施自定义工具以监控或调试流时。
75
Amazon Kinesis Streams 开发人员指南
使用 API
Important
数据记录默认可在其添加到流的 24 小时内访问。此时间范围称为保留期,并且可以在从 24 到
168 小时(1 到 7 天)的范围内按小时为增量进行配置。有关流的保留期的更多信息,请参阅the
section called “更改数据保留期” (p. 95)。
主题
• 使用分片迭代器 (p. 76)
• 使用 GetRecords (p. 77)
• 适应重新分片 (p. 78)
使用分片迭代器
可从流中按分片检索记录。对于每个分片以及您从分片中检索的每批记录,您需要获取分片迭代器。可在
getRecordsRequest 对象中使用分片迭代器来指定要从中检索记录的分片。与分片迭代器关联的类型
决定了应在分片中检索记录的起点(有关更多详细信息,请参阅以下内容)。在可以使用分片迭代器之
前,您需要先检索分片(从流中检索分片 (p. 90) 中已讨论)。
使用 getShardIterator 方法获取初始分片迭代器。使用 getRecordsResult 对象(由 getRecords
方法返回)的 getNextShardIterator 方法为其他记录批次获取分片迭代器。
Important
getShardIterator 返回的分片迭代器若不使用,则会在 5 分钟后超时。
要获取初始分片迭代器,请实例化 GetShardIteratorRequest 并将其传递给 getShardIterator 方
法。要配置请求,您需要指定流和分片 ID。有关如何获取您的 AWS 账户中的流的信息,请参阅 列出
流 (p. 89)。有关如何获取流中分片的信息,请参阅 从流中检索分片 (p. 90)。
String shardIterator;
GetShardIteratorRequest getShardIteratorRequest = new GetShardIteratorRequest();
getShardIteratorRequest.setStreamName(myStreamName);
getShardIteratorRequest.setShardId(shard.getShardId());
getShardIteratorRequest.setShardIteratorType("TRIM_HORIZON");
GetShardIteratorResult getShardIteratorResult = client.getShardIterator(get
ShardIteratorRequest);
shardIterator = getShardIteratorResult.getShardIterator();
以上示例代码将 TRIM_HORIZON 指定为获取初始分片迭代器时的迭代器类型。此迭代器类型意味着记录
应从添加到分片的第一个记录而不是从最近添加的记录(也称为顶端)开始返回。可能的迭代器类型如
下:
• AT_SEQUENCE_NUMBER
• AFTER_SEQUENCE_NUMBER
• TRIM_HORIZON
• LATEST
有关更多信息,请参阅 ShardIteratorType。
部分迭代器类型除了需要指定类型之外,还需要指定序列号。例如:
76
Amazon Kinesis Streams 开发人员指南
使用 API
getShardIteratorRequest.setShardIteratorType("AT_SEQUENCE_NUMBER");
getShardIteratorRequest.setStartingSequenceNumber(specialSequenceNumber);
在您使用 getRecords 获取记录之后,您可通过调用记录的 getSequenceNumber 方法获取记录的序列
号。
record.getSequenceNumber()
此外,将记录添加到数据流的代码可通过对 putRecord 的结果调用 getSequenceNumber 获取已添加
记录的序列号。
lastSequenceNumber = putRecordResult.getSequenceNumber();
您可使用序列号确保记录的顺序严格递增。有关更多信息,请参阅 PutRecord 示例 (p. 52) 一节中的代码
示例。
使用 GetRecords
在获取分片迭代器之后,实例化 GetRecordsRequest 对象。使用 setShardIterator 方法为请求指
定迭代器。
(可选)您还可使用 setLimit 方法设置要检索的记录的数量。getRecords 返回的记录数量始终等于
或小于此限制。如果您未指定此限制,getRecords 将返回已检索记录的 10 MB。以下示例代码将此限
制设置为 25 个记录。
如果未返回任何记录,则意味着此分片中当前没有分片迭代器引用的序列号对应的可用数据记录。出现此
情况时,您的应用程序应等待流的数据源所需的时间,但至少为 1 秒。然后尝试使用对 getRecords 的
上一调用返回的分片迭代器再次从分片获取数据。请注意,记录添加到流的时间与它在 getRecords 中
可用的时间之间约有 3 秒的延迟。
将 getRecordsRequest 传递给 getRecords 方法并捕获返回的值作为 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 秒(1000 毫秒)以免超出 getRecords
频率限制。
try {
Thread.sleep(1000);
}
catch (InterruptedException e) {}
77
Amazon Kinesis Streams 开发人员指南
使用 API
通常,您应循环调用 getRecords,甚至当您在测试方案中检索单一记录时也是如此。对 getRecords
的单一调用可能返回空的记录列表,即使分片包含更多具有之后的序列号的记录也是如此。出现此情况
时,将返回 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 返回 null,则指示以下内容:出现了涉及分片的
分片拆分或合并,此分片现在处于 CLOSED 状态,并且您已读取此分片中的所有可用数据记录。
在此方案中,您应重新枚举流中的分片以选取通过拆分或合并创建的新分片。
在拆分中,两个新分片的 parentShardId 都与您之前处理的分片的分片 ID 相同。这两个分片的
adjacentParentShardId 值为 null。
在合并中,合并创建的一个新分片的 parentShardId 等于父分片之一的分片 ID,并且
adjacentParentShardId 等于另一父分片的分片 ID。您的应用程序已读取这些分片之一中的所有数
据;这是 getRecordsResult.getNextShardIterator 返回 null 的分片。如果数据顺序对于您的
应用程序很重要,则应确保它在读取合并创建的子分片中的任何新数据之前,读取另一父分片中的所有数
据。
如果您使用多个处理器从流检索数据,假定一个分片一个处理器,并且出现分片拆分或合并时,您应增加
或减少处理器数量以适应分片数量的变化。
有关重新分片的更多信息,包括有关分片状态(如 CLOSED)的讨论,请参阅 对流进行重新分片 (p. 91)。
78
Amazon Kinesis Streams 开发人员指南
问题排查
Amazon Kinesis Streams 使用者问题排查
Abstract
获取解决在使用 Amazon Kinesis Streams 使用者时所发现的问题的方案。
下列章节提供使用 Amazon Kinesis Streams 使用者时可能发现的一些常见问题的解决方案。
• 在使用 Kinesis 客户端库时跳过了某些 Streams 记录 (p. 79)
• 属于同一分片的记录通过不同的记录处理器同时处理 (p. 79)
• 使用器应用程序的读取速率比预期的慢 (p. 79)
• 即使流中有数据,GetRecords 仍然返回空记录阵列 (p. 80)
• 分片迭代器意外过期 (p. 80)
• 使用器记录处理滞后 (p. 80)
在使用 Kinesis 客户端库时跳过了某些 Streams 记录
跳过记录的最常见原因是未处理从 processRecords 引发的异常。Kinesis 客户端库 (KCL) 依靠您的
processRecords 代码处理由处理数据记录引起的任何异常。从 processRecords 引发的任何异常都
会被 KCL 吸收。为避免永无止境地对反复出现的故障进行重试,KCL 不会重新发送在发生异常时处理的
那批记录。KCL 随后会在不重新启动记录处理器的情况下对下一批数据记录调用 processRecords。这
有效地导致使用器应用程序观察到跳过的记录。要防止跳过记录,请适当处理 processRecords 中的所
有异常。
属于同一分片的记录通过不同的记录处理器同时处理
对于任何当前正在运行的 Kinesis 客户端库 (KCL) 应用程序,只有一个记录处理器是特定分片的真正所有
者。但是,多个记录处理器可以临时处理同一分片。如果工作程序实例失去网络连接几分钟,KCL 将假
定无法访问的工作程序不再处理记录。故障转移时间(默认值为 10 秒)结束后,其他工作程序实例将从
无法访问的工作程序接手分片的处理。在短时间内,新的记录处理器和来自无法访问的工作程序的记录处
理器会处理来自同一个分片的数据。
您的应用程序应预料到并处理这种情况,尤其是因为网络连接通常会恢复到之前无法访问的工作程序。如
果一个记录处理器让另一个记录处理器接手其分片,它必须处理以下两种情况才能顺利执行关闭:
1. 对 processRecords 的当前调用完成后,KCL 会用关闭原因“ZOMBIE”在记录处理器上调用关闭方
法。您的记录处理器应视情况清除所有资源然后退出。
2. 当您尝试从“zombie”工作程序执行检查点操作时,KCL 会引发 ShutdownException。收到此异常后,
您的代码应完全退出当前方法。
有关更多信息,请参阅 the section called “处理重复记录” (p. 84)。
使用器应用程序的读取速率比预期的慢
读取吞吐量低于预期的最常见原因如下:
1. 多个使用器应用程序的总读取量超过每个分片的限制。有关更多信息,请参阅 the section called “限
制” (p. 7)。在这种情况下,请增加 Amazon Kinesis stream 中的分片数。
2. 指定每个调用的最大 GetRecords 数的 limit 可能已被配置为一个较低值。如果您正在使用 KCL,您
可能已经使用一个较低的 maxRecords 属性值配置了工作程序。一般来说,我们推荐对此属性使用系
统默认值。
3. 出于很多可能的原因,您的 processRecords 调用内的逻辑花费的时间可能超过预期;该逻辑可能是
CPU 使用率高、I/O 阻止或同步出现瓶颈。要测试是否如此,请对空的记录处理器进行测试运行并比
79
Amazon Kinesis Streams 开发人员指南
问题排查
较读取吞吐量。有关如何跟踪传入数据的信息,请参阅the section called “重新分片、扩展和并行处
理” (p. 83)。
如果您只有一个使用器应用程序,那么读取速率比放入速率至少高两倍始终是可能的。这是因为您可以写
入最多 1,000 records per second 可用于写入,最多可达的最大总数据写入速率为 1 MB per second
(including partition keys)。每个打开的分片可支持最多 5 transactions per second 可用于读取,最多可达
的最大总数据读取速率为 2 MB per second。请注意,每次读取(GetRecords 调用)都将获取一批记
录。GetRecords 返回的数据的大小因分片的使用率而异。GetRecords 可返回的数据的最大大小为 10
MB。如果某个调用返回了该限制,在接下来 5 分钟内进行的后续调用将引发
ProvisionedThroughputExceededException。
即使流中有数据,GetRecords 仍然返回空记录阵列
使用或获取记录是一种拉取模型。开发人员应该在不会回退的连续循环中调用 GetRecords。每个
GetRecords 调用还将返回一个 ShardIterator 值,该值必须在循环的下一个迭代中使用。
GetRecords 操作不会阻止。相反,它将立即返回一些相关数据记录或一个空的 Records 元素。在两种
情况下,将返回空的 Records 元素:
1. 目前分片中没有更多数据。
2. ShardIterator 指向的分片部分附近没有数据。
后一种情况很微妙,但却是避免在检索数据时搜寻时间无止境(延迟)的一种必要的设计折衷。因此,流
使用应用程序应循环并调用 GetRecords,并且理所当然地处理空记录。
在生产场景中,仅当 NextShardIterator 值为 NULL 时,才应退出连续循环。当 NextShardIterator
为 NULL 时,这意味着当前分片已关闭,ShardIterator 值的指向应越过最后一条记录。如果使用应用
程序从不调用 SplitShard 或 MergeShards,分片将保持打开状态,并且对 GetRecords 的调用从不
返回为 NULL 的 NextShardIterator 值。
如果您使用 Kinesis 客户端库 (KCL),以上使用模式已为您提取。这包括自动处理一组动态变化的分片。
在 KCL 中,开发人员只需提供处理传入记录的逻辑。这是可能的,因为该库会为您连续调用 GetRecords。
分片迭代器意外过期
每个 GetRecords 请求返回新的分片迭代器(作为 NextShardIterator),然后您可以将其用于下一
个 GetRecords 请求(作为 ShardIterator)。在正常情况下,此分片迭代器不会在您使用前过期。
不过,您可能会发现,由于您超过 5 分钟没有调用 GetRecords,或者您执行了使用器应用程序的重新
启动操作,该分片迭代器会过期。
使用器记录处理滞后
对于大多数使用案例,使用器应用程序从流中读取最新数据。在特定情况下,使用器读取可能会滞后,而
您可能并不希望出现这种情况。在确定您的使用器读取滞后多久后,请查看使用器滞后的最常见原因。
从 GetRecords.IteratorAgeMilliseconds 指标开始,该指标跟踪流中所有分片和使用器的读取位
置。请注意,如果某个迭代器的寿命超过了保留期的 50%(默认值为 24 小时,可配置为最高 7 天),则
存在由于记录过期造成数据丢失的风险。一种快速的权宜之计是增加保留期。这会在您进一步对问题进行
故障排除时防止重要数据丢失。有关更多信息,请参阅 利用 Amazon CloudWatch 监控 Amazon Kinesis
Streams 服务 (p. 96)。接下来,使用 Kinesis 客户端库 (KCL) 发出的自定义 CloudWatch 指标,确定使
用器应用程序从每个分片读取的滞后时间长度 MillisBehindLatest。有关更多信息,请参阅 利用
Amazon CloudWatch 监控 Amazon Kinesis 客户端库 (p. 103)。
下面是使用器滞后的最常见原因:
80
Amazon Kinesis Streams 开发人员指南
高级主题
• GetRecords.IteratorAgeMilliseconds 或 MillisBehindLatest 突然发生大幅提升,通常表
明临时性问题,例如下游应用程序的 API 操作失败。如果任何一个指标持续指示此行为,您应该调查
这些突然增长的原因。
• 这些指标的逐步增大表明,由于处理记录的速度不够快,使用器无法与流保持同步。此行为最常见的根
本原因是没有足够的物理资源,或者记录处理逻辑没有随着流吞吐量的增大而进行扩展。您可以查看
KCL 发出的与 processTask 操作关联的其他自定义 CloudWatch 指标,包括
RecordProcessor.processRecords.Time、Success 和 RecordsProcessed,来验证此行为。
• 如果您发现与吞吐量上升相关的 processRecords.Time 指标发生增长,则应该分析记录处理逻
辑,以确定为什么逻辑没有随吞吐量的增长而扩展。
• 如果您发现与吞吐量上升无关的 processRecords.Time 值发生增长,请检查您是否在关键路径中
执行了任何阻塞性调用,这通常会导致记录处理速度下降。替代方法是通过增加分片数来提高并行
度。最后,请确认需求高峰期间在底层处理节点上,您有足够数量的物理资源(内存、CPU 使用率
等)。
有关 Amazon Kinesis Streams 使用者的高级主题
Abstract
了解如何优化您的 Amazon Kinesis Streams 使用者。
本节讨论如何优化您的 Amazon Kinesis Streams 使用者。
内容
• 跟踪 Amazon Kinesis Streams Application状态 (p. 81)
• 低延迟处理 (p. 82)
• 将 AWS Lambda 与Amazon Kinesis 创建器库配合使用 (p. 83)
• 重新分片、扩展和并行处理 (p. 83)
• 处理重复记录 (p. 84)
• 从 Amazon Kinesis Streams 中的故障恢复 (p. 85)
• 处理启动、关闭和限制 (p. 86)
跟踪 Amazon Kinesis Streams Application状态
Abstract
了解如何使用 Amazon Kinesis Client Library跟踪您的 Amazon Kinesis Streams application的状态。
对于每个 Amazon Kinesis Streams application,KCL 使用唯一的 Amazon DynamoDB 表跟踪应用程序
的状态。由于 KCL 使用 Amazon Kinesis Streams application的名称来创建该表的名称,因此每个应用程
序名称都必须是唯一的。
您可在应用程序运行的同时使用 Amazon DynamoDB 控制台查看该表。
如果您的 Amazon Kinesis Streams application的 Amazon DynamoDB 表在应用程序启动时不存在,则其
中一个工作程序会创建该表并调用 describeStream 方法来填充该表。有关更多信息,请参阅 the section
called “应用程序状态数据” (p. 82)。
Important
您的账户将被收取与 DynamoDB 表关联的费用(除开与 Streams 本身关联的费用)。
81
Amazon Kinesis Streams 开发人员指南
高级主题
吞吐量
如果您的 Amazon Kinesis Streams application收到了预置的吞吐量异常,您应为 DynamoDB 表增加预
置的吞吐量。KCL 将创建预置吞吐量为 10 次读取/秒和 10 次写入/秒的表,但这对于您的应用程序可能不
够。例如,如果您的 Amazon Kinesis Streams application执行频繁的检查点操作或对由很多分片组成的
流执行操作,您可能需要更多吞吐量。
有关 DynamoDB 中的预置吞吐量的信息,请参阅 Amazon DynamoDB 开发人员指南 中的 Amazon
DynamoDB 中的预置吞吐量和处理表。
应用程序状态数据
DynamoDB 表中的每行表示您的应用程序正在处理的分片。该表的哈希键为分片 ID。
除了分片 ID 以外,每行还包含以下数据:
• checkpoint:分片的最新检查点序号。此值在流中的所有分片中都是唯一的。
• checkpointSubSequenceNumber:使用 Kinesis 创建器库的聚合功能时,这是对跟踪 Amazon Kinesis
记录中单个用户记录的 checkpoint 的扩展。
• leaseCounter:用于租赁版本控制,工作程序可以检测其租赁已由其他工作程序获取。
• leaseKey:租赁的唯一标识符。每个租赁特定于流中的一个分片,一次由一个工作程序持有。
• leaseOwner:持有此租赁的工作程序。
• ownerSwitchesSinceCheckpoint:自上次写入检查点以来,此租赁更改了工作程序的次数。
• parentShardId:用于确保在开始子分片上的处理之前已经完全处理了父分片。这可以确保记录按照放
入流中的相同顺序处理。
低延迟处理
Abstract
了解如何有效地轮询您的流。
传播延迟 的定义是从将记录写入到流到使用者应用程序读取该记录的端对端延迟。此延迟会因各种因素
而变化,但主要受使用者应用程序的轮询间隔影响。
对于大多数应用程序,我们建议针对每个应用程序每秒轮询每个分片一次。这使您能够具有并行处理流的
多个使用者应用程序,而不会达到每秒 5 次 GetRecords 调用的 Amazon Kinesis Streams 限制。此外,
若要处理大批量的数据,降低您的应用程序中的网络和其他下游延迟时往往更高效。
KCL 默认值被设置为遵循每 1 秒轮询一次的最佳实践。此默认值导致了通常少于 1 秒的平均传播延迟。
Streams 记录在写入后便立即可被读取。有一些需要利用此延迟并且在流中的数据可用时立即需要使用它
的使用案例。您可通过覆盖 KCL 默认设置来更频繁地进行轮询,从而显著降低传播延迟,如以下示例所
示。
Java KCL 配置代码:
kinesisClientLibConfiguration = new
KinesisClientLibConfiguration(applicationName,
streamName,
credentialsProvider,
workerId).withInitialPositionInStream(initialPositionInStream).withId
leTimeBetweenReadsInMillis(250);
Python 和 Ruby KCL 的属性文件设置:
82
Amazon Kinesis Streams 开发人员指南
高级主题
idleTimeBetweenReadsInMillis = 250
Note
由于 Streams 具有每秒 5 次 GetRecords 调用的限制,因此将
idleTimeBetweenReadsInMillis 属性设置为少于 200ms 可能导致您的应用程序观察到
ProvisionedThroughputExceededException 异常。如果这类异常过多,则可能导致指数
退避,并因此导致处理过程中出现重大的意外延迟。如果您将此属性设置为 200 ms 或更大并且
具有多个正在处理的应用程序,则会遇到类似的限制。
将 AWS Lambda 与Amazon Kinesis 创建器库配合使用
Abstract
使用 AWS Lambda 时取消聚合 KPL 记录。
Amazon Kinesis 创建器库 (KPL) 将较小的用户格式化记录聚合为最大 1MB 的记录,以更好地利用 Amazon
Kinesis Streams 吞吐量。虽然 Java 的 KCL 支持取消聚合这些记录,但在使用 AWS Lambda 作为流的
使用器时,您需要使用特殊模块来取消聚合记录。您可以从 GitHub 获取必要的项目代码和说明,具体参
见 Amazon Kinesis 创建器库AWS Lambda 的取消聚合模块。此项目中的组件为您提供了在 Java、Node.js
和 Python 中处理 AWS Lambda 内的 KPL 序列化数据的能力。这些组件可用作多语言 KCL 应用程序的
一部分。
重新分片、扩展和并行处理
Abstract
了解如何在您的流中增加或减少分片的数量。
利用重新分片,您可以增加或减少流中的分片的数量,以便适应流过流的数据的速率的变化。重新分片通
常是由监控分片数据处理指标的管理应用程序执行的。尽管 KCL 本身不启动重新分片操作,但它能够适
应由于重新分片而生成的分片的数量的变化。
如跟踪 Amazon Kinesis Streams Application状态 (p. 81)中所述,KCL 使用 Amazon DynamoDB 表跟踪
流中的分片。当由于重新分片而创建新的分片时,KCL 会发现新的分片并在该表中填充新行。工作程序
将自动发现新的分片并创建处理器以处理来自分片的数据。KCL 还将跨所有可用工作程序和记录处理器
分配流中的分片。
KCL 将确保在重新分片之前已存在于分片中的任何数据优先处理。在处理该数据后,新分片中的数据将
发送到记录处理器。这样,KCL 便保留了为特定分区键将数据记录添加到流的顺序。
示例:重新分片、扩展和并行处理
以下示例将演示 KCL 如何帮助您处理扩展和重新分片:
• 例如,如果您的应用程序正在 1 个 EC2 实例上运行,并且正在处理 1 个包含 4 个分片的 Amazon
Kinesis stream。这 1 个实例包含 1 个 KCL 工作程序和 4 个记录处理器(每个分片有 1 个记录处理
器)。这 4 个记录处理器在同一进程内并行运行。
• 接下来,如果您扩展应用程序以使用其他实例,您将有 2 个处理 1 个包含 4 个分片的流的实例。当 KCL
工作程序在第二个实例上启动时,它会与第一个实例进行负载均衡,以便让每个实例现在处理两个分
片。
• 如果您随后决定将 4 个分片拆分为 5 个分片。KCL 会再次跨实例协调处理:一个实例处理 3 个分片,
另一个实例处理 2 个分片。类似协调在合并分片时出发生。
83
Amazon Kinesis Streams 开发人员指南
高级主题
通常,在使用 KCL 时,您应确保实例的数量不超过分片的数量(故障待机除外)。每个分片正好由一个
KCL 工作程序处理并且正好有一个对应的记录处理器,因此您永远不需要多个实例来处理一个分片。但
是,一个工作程序可处理任意数量的分片,因此分片的数量超过实例的数量没有关系。
要扩展您的应用程序中的处理,您应测试以下方法的组合:
• 增加实例大小(因为所有记录处理器都在进程内并行运行)
• 增加实例的数量,最多为开放分片的最大数量(因为分片可以单独处理)
• 增加分片的数量(这会提高并行机制的级别)
请注意,您可使用 Auto Scaling 基于适当的指标自动扩展您的实例。
当重新分片增加了流中的分片数时,记录处理器的数量的相应增加会增加托管处理器的 EC2 实例上的负
载。如果实例为 Auto Scaling 组的一部分,并且负载增加得足够多,则 Auto Scaling 组会添加更多实例
来处理增加的负载。您应在启动时配置用来启动 Amazon Kinesis Streams application的实例,以便让其
他工作程序和记录处理器在新实例上立即激活。
有关重新分片的更多信息,请参阅对流进行重新分片 (p. 91)。
处理重复记录
Abstract
学习以了解您的 Amazon Kinesis stream 中的重复记录处理。
有两个主要原因可能导致多次向您的 Amazon Kinesis Streams application提供记录:创建者重试和使用
者重试。您的应用程序必须预计并适当地应对多次处理单个记录的问题。
创建者重试
假设有一位创建者,它在已经对 PutRecord 进行调用但还无法从 Amazon Kinesis Streams 接收确认时
遇到了与网络相关的超时。创建者无法确定记录是否已传输到 Streams。假定每个记录对应用程序都很重
要,创建者应该已被写入以重试对相同数据的调用。如果对相同数据的两次 PutRecord 调用已成功提交
到 Streams,则会有两个 Streams 记录。尽管这两个记录具有相同的数据,但它们各具有唯一的序号。
需要严格保证的应用程序应在记录中嵌入一个主键,以便在随后的处理过程中删除重复项。请注意,由创
建者重试产生的重复项的数量通常低于由使用者重试产生的重复项的数量。
Note
如果您使用 AWS 软件开发工具包 PutRecord,则默认配置会重试已失败的 PutRecord 调用最
多三次。
使用者重试
使用者(数据处理应用程序)重试在记录处理器重新启动时发生。相同分片的记录处理器在以下情况下重
新启动:
1. 工作程序意外终止
2. 已添加或删除工作程序实例
3. 已拆分或合并分片
4. 已部署应用程序
在所有这些情况下,分片到工作程序再到记录处理器的映射将持续更新到负载均衡处理。已迁移到其他实
例的分片处理器将从上一个检查点开始重新启动处理记录。这导致了重复的记录处理,如以下示例所示。
有关负载均衡的更多信息,请参阅重新分片、扩展和并行处理 (p. 83)。
84
Amazon Kinesis Streams 开发人员指南
高级主题
示例:导致重新传送记录的使用者重试
在此示例中,您有一个持续从流中读取记录、将记录聚合到本地文件并将文件上传到 Amazon S3 的应用
程序。为简便起见,假定只有 1 个分片和 1 个处理该分片的工作程序。考虑以下示例顺序的事件,假定
上一个检查点位于记录编号 10000 处:
1. 工作程序从该分片中读取下一批记录,即从 10001 到 20000 的记录。
2. 工作程序随后将这批记录传递到关联的记录处理器。
3. 记录处理器聚合数据、创建 Amazon S3 文件并将文件成功上传到 Amazon S3。
4. 工作程序在新的检查点出现之前意外终止。
5. 应用程序、工作程序和记录处理器重新启动。
6. 工作程序现在开始从上次成功的检查点(在本案例中为 10001)开始读取。
因此,记录 10001-20000 使用了多次。
实现对使用者重试的弹性
尽管记录可被处理多次,但您的应用程序可能会带来副作用,就像记录只能处理一次一样(幂等处理)。
有关此问题的解决方案因复杂性和准确性而异。如果最终数据的目标可以很好地处理重复,我们建议依靠
最终目标来实现幂等处理。例如,利用 Elasticsearch,您可以使用版本控制和唯一 ID 的组合来防止重复
的处理。
在上一节的示例应用程序中,它持续从流中读取记录、将记录聚合到本地文件并将文件上传到 Amazon
S3。如图所示,记录 10001 - 20000 使用了多次,从而生成了具有相同数据的多个 Amazon S3 文件。减
少此示例中的重复的一种方法是确保步骤 3 使用了以下方案:
1. 记录处理器对每个 Amazon S3 文件使用了固定数量的记录,如 5000。
2. 文件名使用以下架构:Amazon S3 前缀、分片 ID 和 First-Sequence-Num。在本例中,它可以是类
似于 sample-shard000001-10001 的形式。
3. 在上传 Amazon S3 文件后,通过指定 Last-Sequence-Num 进行检查点操作。在本例中,您将在记
录编号 15000 处进行检查点操作。
利用此方案,即使记录被处理了多次,生成的 Amazon S3 文件也会具有相同的名称和数据。重试只会导
致将相同的数据多次写入到相同的文件。
对于重新分片操作,分片中剩余的记录的数量可能少于您需要的固定数量。在本例中,您的 shutdown()
方法必须将文件刷新到 Amazon S3 并对上一个序号进行检查点操作。以上方案也与重新分片操作兼容。
从 Amazon Kinesis Streams 中的故障恢复
Abstract
了解如何在 Amazon Kinesis Streams 中从故障中恢复。
故障可能在您使用 Amazon Kinesis Streams application处理流中的数据时在以下级别发生:
• 记录处理器可能失败
• 工作程序可能失败,或者已实例化工作程序的应用程序的实例可能失败
• 托管该应用程序的一个或多个实例的 EC2 实例可能失败
85
Amazon Kinesis Streams 开发人员指南
高级主题
记录处理器失败
工作程序使用 Java ExecutorService 任务调用记录处理器方法。如果任务失败,工作程序将保留对记录
处理器之前在处理的分片的控制。工作程序启动一项新的记录处理器任务来处理该分片。有关更多信息,
请参阅 读取限制 (p. 87)。
工作程序或应用程序失败
如果工作程序(或 Amazon Kinesis Streams application的实例)失败,您应检测并处理该情况。例如,
如果 Worker.run 方法引发了一项异常,则您应捕获并处理它。
如果应用程序本身失败,您应检测此应用程序并重新启动它。该应用程序启动时,它会实例化一个新工作
程序,这会反过来实例化自动获得要处理的分片的新记录处理器。这些分配可能是记录处理器在失败前正
在处理的相同分片或这些处理器新接触的分片。
如果工作程序或应用程序失败,但您未检测该失败,而且应用程序有其他实例正在其他 EC2 实例上运行,
则这些实例上的工作程序会处理该失败:它们将创建额外的记录处理器来处理不再由已失败的工作程序处
理的分片。这些其他 EC2 实例上的负载也会相应地增加。
此处描述的情形假定,尽管工作程序或应用程序已失败,但托管 EC2 实例仍在运行并因此不由 Auto
Scaling 组重新启动。
Amazon EC2 实例失败
我们建议您在 Auto Scaling 组中为您的应用程序运行 EC2 实例。这样,如果其中一个 EC2 实例失败,
Auto Scaling 组会自动启动一个新的实例来代替它。您应配置实例在启动时启动您的 Amazon Kinesis
Streams application。
处理启动、关闭和限制
Abstract
了解您的 Amazon Kinesis Streams application的设计提示。
以下是要融入到您的 Amazon Kinesis Streams application的设计中的一些其他注意事项。
内容
• 启动数据创建器和数据使用器 (p. 86)
• 关闭 Amazon Kinesis Streams Application (p. 87)
• 读取限制 (p. 87)
启动数据创建器和数据使用器
默认情况下,KCL 从流的提示 处开始读取记录,这是最近添加的记录。在此配置中,如果数据生成应用
程序在任何接收记录的处理器运行前向流添加记录,那么记录处理器不会在启动后读取这些记录。
要更改记录处理器的行为以便它始终从流的开头处读取数据,请在属性文件中为您的 Amazon Kinesis
Streams application设置以下值:
initialPositionInStream = TRIM_HORIZON
Amazon Kinesis Streams 会将记录保留 24 到 168 小时。此时间范围称为保留期。将开始位置设置为
TRIM_HORIZON 时,将根据保留期的定义,对流中最早的数据启动记录处理器。即使使用 TRIM_HORIZON
设置,如果记录处理器在超过了保留期很长一段时间之后启动,流中的一些数据将不再可用。因此,您应
86
Amazon Kinesis Streams 开发人员指南
管理流
始终让使用器应用程序读取流,并使用 CloudWatch 指标 GetRecords.IteratorAgeMilliseconds
进行监视,以确保应用程序与传入数据保持同步。
在某些情况下,对于记录处理器来说,错过流中的前几个记录没有关系。例如,您可能在流中运行一些初
始记录来测试流是否正在按预期方式在端到端之间工作。在此初步验证之后,您随后会启动您的工作程序
并开始将生产数据放入流中。
有关 TRIM_HORIZON 设置的更多信息,请参阅使用分片迭代器 (p. 76)。
关闭 Amazon Kinesis Streams Application
当您的 Amazon Kinesis Streams application已完成其预定任务时,您应通过终止运行该应用程序的 EC2
实例来关闭它。您可使用 AWS 管理控制台或 AWS CLI 来终止实例。
关闭您的 Amazon Kinesis Streams application后,您应删除 KCL 用于跟踪应用程序的状态的 Amazon
DynamoDB 表。
读取限制
流的吞吐量在分片级别进行配置。每个分片具有一个 最多 5 transactions per second 可用于读取,最多
可达的最大总数据读取速率为 2 MB per second 的读取吞吐量。如果某个应用程序(或对相同的流执行操
作的一组应用程序)尝试以较快的速率从分片中获取数据,Streams 将限制对应的 Get 操作。
在 Amazon Kinesis Streams application中,如果记录处理器处理数据的速率高于限额(如在故障转移的
情况下),则会出现限制。由于 Amazon Kinesis Client Library (p. 62)管理应用程序与 Streams 之间的交
互,因此限制异常会在 KCL 代码中出现,而不会在应用程序代码中出现。然而,由于 KCL 会记录这些异
常,因此您可在日志中查看它们。
如果您发现您的应用程序一直受到限制,则应考虑增加流的分片的数量。
管理 Amazon Kinesis Stream
Abstract
了解如何将 Amazon Kinesis Streams 与 AWS SDK for Java 结合使用。
这些示例讨论 Amazon Kinesis Streams API 并使用 适用于 Java 的 AWS 开发工具包来创建、删除和使
用 Amazon Kinesis stream。
本章中的 Java 示例演示如何执行基本的 Streams API 操作以及如何按操作类型从逻辑上划分这些操作。
这些示例并非可直接用于生产的代码,因为它们不会检查所有可能的异常,或者不会考虑到所有可能的安
全或性能问题。此外,您可使用其他不同的编程语言调用 Streams API。有关所有可用 AWS 开发工具包
的更多信息,请参阅开始使用 Amazon Web Services 开发。
主题
• 创建流 (p. 88)
• 列出流 (p. 89)
• 从流中检索分片 (p. 90)
• 删除流 (p. 90)
• 对流进行重新分片 (p. 91)
• 更改数据保留期 (p. 95)
87
Amazon Kinesis Streams 开发人员指南
创建流
创建流
Abstract
了解如何使用 AWS SDK for Java 创建 Amazon Kinesis stream。
本节描述创建您的 Amazon Kinesis stream 所需的步骤。
创建 Streams 客户端
您必须先实例化一个客户端对象,然后才能处理 Amazon Kinesis stream。以下 Java 代码创建 Streams
客户端并为该客户端设置终端节点信息。此 setEndpoint 重载还包括服务名称和区域。将 serviceName
设置为 kinesis。
client = new AmazonKinesisClient();
client.setEndpoint(endpoint, serviceName, regionId);
有关更多信息,请参阅 AWS General Reference 中的 Streams 区域和终端节点。
创建流
现在您已创建 Streams 客户端,接下来可创建要处理的流。可通过 Streams 控制台或以编程方式来创建
流。要以编程方式创建流,请实例化 CreateStreamRequest 对象并指定流名称以及流要使用的分片数
量。
CreateStreamRequest createStreamRequest = new CreateStreamRequest();
createStreamRequest.setStreamName( myStreamName );
createStreamRequest.setShardCount( myStreamSize );
流名称用于标识流。此名称的使用范围限定在应用程序使用的 AWS 账户内。它还受区域限制。也就是
说,两个不同 AWS 账户中的两个流可具有相同的名称,不同区域的相同 AWS 账户中的两个流可具有相
同的名称,但相同区域的相同账户中的两个流不能具有相同的名称。
流的吞吐量是分片数量的函数;配置更大的吞吐量需要更多分片。更多的分片还会增加 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 ) {}
88
Amazon Kinesis Streams 开发人员指南
列出流
try {
DescribeStreamResult describeStreamResponse = client.describeStream( de
scribeStreamRequest );
String streamStatus = describeStreamResponse.getStreamDescription().get
StreamStatus();
if ( streamStatus.equals( "ACTIVE" ) ) {
break;
}
//
// 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"
);
}
列出流
Abstract
了解如何使用适用于 Java 的 AWS 开发工具包列出 Amazon Kinesis stream。
如上一节中所述,流的应用范围限定在与用于实例化 Streams 客户端的 AWS 凭证关联的 AWS 账户以及
为该客户端指定的区域。AWS 账户可以同时具有多个活动流。您可在 Streams 控制台中列出流,也可以
编程方式列出流。此节中的代码演示如何列出您的 AWS 账户的所有流。
ListStreamsRequest listStreamsRequest = new ListStreamsRequest();
listStreamsRequest.setLimit(20);
ListStreamsResult listStreamsResult = client.listStreams(listStreamsRequest);
List<String> streamNames = listStreamsResult.getStreamNames();
此代码示例首先创建 ListStreamsRequest 的一个新实例,然后调用其 setLimit 方法来指定对
listStreams 的每次调用应返回最多 20 个流。如果您未为 setLimit 指定值,则 Streams 将返回的流
数量小于或等于账户中的流数量。此代码之后将 listStreamsRequest 传递到客户端的 listStreams
方法。返回值 listStreams 存储在 ListStreamsResult 对象中。此代码对此对象调用
getStreamNames 方法,并将返回的流名称存储在 streamNames 列表中。请注意,Streams 返回的流
数量可能少于指定限制值所指定的数量,即使账户和区域中的流数量多于此数量也是如此。要确保检索所
有流,请使用下一代码示例中描述的 getHasMoreStreams 方法。
while (listStreamsResult.getHasMoreStreams())
{
if (streamNames.size() > 0) {
listStreamsRequest.setExclusiveStartStreamName(streamNames.get(stream
Names.size() - 1));
}
listStreamsResult = client.listStreams(listStreamsRequest);
streamNames.addAll(listStreamsResult.getStreamNames());
}
89
Amazon Kinesis Streams 开发人员指南
从流中检索分片
此代码对 listStreamsRequest 调用 getHasMoreStreams 方法,以检查是否有超出在对 listStreams
的初始调用中返回的流数量的可用流。如果有,则此代码将使用在对 listStreams 的上一调用中返回的
最后一个流的名称调用 setExclusiveStartStreamName 方法。setExclusiveStartStreamName
方法将导致对 listStreams 的下一调用在该流之后开始。该调用返回的一组流名称之后将添加到
streamNames 列表。此过程将继续,直到所有流名称已收集到列表中。
listStreams 返回的流可能处于下列状态之一:
• CREATING
• ACTIVE
• UPDATING
• DELETING
您可使用 describeStream 方法查看流的状态(如上一节 创建流 (p. 88) 中所示)。
从流中检索分片
Abstract
了解如何使用适用于 Java 的 AWS 开发工具包从 Amazon Kinesis stream 中检索分片。
describeStream 方法返回的响应对象使您能够检索有关组成流的分片的信息。要检索分片,请对此对
象调用 getShards 方法。此方法可能不会通过一次调用返回流中的所有分片。在以下代码中,我们查看
getStreamDescription 上的 getHasMoreShards 方法以了解是否有未返回的其他分片。如果有,也
就是说,如果此方法返回 true,则我们将继续循环调用 getShards,以将返回的新的分片批次添加到
我们的分片列表中。循环将在 getHasMoreShards 返回 false 时退出;即,所有分片均已返回。请注
意,getShards 不会返回处于 EXPIRED 状态的分片。有关分片状态(包括 EXPIRED 状态)的更多信
息,请参阅 分片之后的数据路由、数据保留和分片状态 (p. 95)。
DescribeStreamRequest describeStreamRequest = new DescribeStreamRequest();
describeStreamRequest.setStreamName( myStreamName );
List<Shard> shards = new ArrayList<>();
String exclusiveStartShardId = null;
do {
describeStreamRequest.setExclusiveStartShardId( exclusiveStartShardId );
DescribeStreamResult describeStreamResult = client.describeStream( describe
StreamRequest );
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 );
删除流
Abstract
了解如何使用适用于 Java 的 AWS 开发工具包删除 Amazon Kinesis stream。
您可使用 Streams 控制台或以编程方式删除流。要以编程方式删除流,请使用 DeleteStreamRequest,
如以下代码所示。
90
Amazon Kinesis Streams 开发人员指南
对流进行重新分片
DeleteStreamRequest deleteStreamRequest = new DeleteStreamRequest();
deleteStreamRequest.setStreamName(myStreamName);
client.deleteStream(deleteStreamRequest);
删除流之前,您应先关闭对其进行操作的任何应用程序。如果应用程序尝试对已删除的流进行操作,则将
收到 ResourceNotFound 异常。此外,如果您随后创建名称与之前的流相同的新流,并且对之前的流进
行操作的应用程序仍在运行,则这些应用程序可能会尝试与新流交互(即使新流是之前的流),这将导致
无法预测的行为。
对流进行重新分片
Abstract
了解如何使用适用于 Java 的 AWS 开发工具包对 Amazon Kinesis stream 进行重新分片。
Streams 支持重新分片,这使您能够调整流中的分片数量以便适应流中的数据流量的变化。重新分片被视
为高级操作。如果您不熟悉 Streams,请在熟悉 Streams 的所有其他方面之后再回来阅读此主题。
这里有两种类型的重新分片操作:分片拆分和分片合并。在分片拆分中,可将一个分片拆分为两个分片。
在分片合并中,可将两个分片组合成一个分片。重新分片始终是“成对”进行的,也就是说,您无法在一次
操作中拆分为两个以上的分片,并且您无法在一次操作中合并两个以上的分片。重新分片操作涉及的分片
或分片对称为父分片。从重新分片操作中生成的分片或分片对称为子分片。
拆分将增加流中分片的数量,从而增加流的数据容量。由于按分片收费,因此拆分将增加流的费用。同
样,合并将减少流中分片的数量,从而减少流的数据容量和费用。
重新分片一般由不同于创建器(放置)应用程序和消费者(获取)应用程序的管理应用程序执行。此类管
理应用程序基于 CloudWatch 提供的指标或从创建器和消费者应用程序收集的指标监视流的整体性能。相
比消费者和创建器应用程序,管理应用程序需要更多的 IAM 权限集,因为消费者应用程序和创建器应用
程序一般应不需要访问用于重新分片的 API。有关用于 Streams 的 IAM 权限的更多信息,请参阅the
section called “Controlling Access” (p. 116)。
主题
• 重新分片策略 (p. 91)
• 拆分分片 (p. 92)
• 合并两个分片 (p. 93)
• 重新分片后 (p. 94)
重新分片策略
Abstract
了解使用适用于 Java 的 AWS 开发工具包对 Amazon Kinesis stream 进行重新分片的策略。
重新分片的目的在于使您的流能够适应数据流量的变化。拆分分片将增加流的容量(和费用)。合并分片
将减少流的费用(和容量)。
一种重新分片方式可以是简单地拆分流中的每个分片 - 这将使流的容量增加一倍。但是,这提供的容量可
能比您实际需要的要多,从而产生不必要的费用。
您还可使用指标确定您的“冷”或“热”分片(即,将接收的数据多于预期或少于预期的分片)。之后您可选
择性地拆分热分片以增加面向这些分片的哈希键的容量。同样,您可合并冷分片以更好地利用其未使用的
容量。
91
Amazon Kinesis Streams 开发人员指南
对流进行重新分片
您可从 Streams 发布的 CloudWatch 指标中获取流的部分性能数据。但是,您也可收集您自己的一些关
于流的指标。一种方式是记录由您的数据记录的分区键生成的哈希键值。记住,您在向流添加记录时指定
了分区键。
putRecordRequest.setPartitionKey( String.format( "myPartitionKey" ) );
Streams 使用 MD5 计算分区键中的哈希键。由于您为记录指定了分区键,因此可使用 MD5 计算该记录
的哈希键值并将此值记录下来。
您还可记录您的数据记录分配到的分片的 ID。分片 ID 是通过使用 putRecordResults 对象(由
putRecords 方法返回)和对 putRecordResult 对象(由 putRecord 方法返回)的 getShardId 方
法提供的。
String shardId = putRecordResult.getShardId();
利用分片 ID 和哈希键值,您可确定将接收最多流量或最少流量的分片和哈希键。您之后可使用重新分片
操作来增加或减少容量(视这些键的情况而定)。
拆分分片
Abstract
了解如何使用适用于 Java 的 AWS 开发工具包拆分 Amazon Kinesis stream 的分片。
要拆分分片,您需要指定父分片中的哈希键值应如何重新分配到子分片。当您向流添加数据记录时,将基
于哈希键值将数据记录分配给分片。哈希键值是您在向流添加数据记录的同时为数据记录指定的分区键的
MD5 哈希;具有相同分区键的数据记录也具有相同的哈希键值。
指定分区的可能的哈希键值构成一组有序的连续非负整数。此可能的哈希键值范围通过以下命令指定:
shard.getHashKeyRange().getStartingHashKey();
shard.getHashKeyRange().getEndingHashKey();
在拆分分片时,您指定此范围内的一个值。此哈希键值和所有较高的哈希键值将分配到其中一个子分片。
所有较小的哈希键值将分配到另一子分片。
以下代码演示在所有子分片之间均匀地重新分配哈希键的分片拆分操作,基本上是将父分片一分为二。这
只是一种可能的父分片划分方式。例如,您可拆分分片,以便父分片中下层三分之一的键分配给一个子分
片,上层三分之二的键分配给另一子分片。但是,在许多应用程序中,将分片一分为二是一种很有效的方
法。
此代码假定 myStreamName 包含您的流名称,对象变量 shard 包含要拆分的分片。首先实例化一个新的
splitShardRequest 对象并设置流名称和分片 ID。
SplitShardRequest splitShardRequest = new SplitShardRequest();
splitShardRequest.setStreamName(myStreamName);
splitShardRequest.setShardToSplit(shard.getShardId());
确定位于分片中最低值和最高值的中间的哈希键值。这是将包含父分片中上半层哈希键的子分片的起始哈
希键值。在 setNewStartingHashKey 方法中指定此值。您只需指定此值:Streams 将会自动将低于此
值的哈希键分配给拆分操作所创建的另一子分片。最后一步是对 Streams 客户端调用 splitShard 方
法。
92
Amazon Kinesis Streams 开发人员指南
对流进行重新分片
BigInteger startingHashKey = new BigInteger(shard.getHashKeyRange().getStarting
HashKey());
BigInteger endingHashKey
= new BigInteger(shard.getHashKeyRange().getEnding
HashKey());
String newStartingHashKey = startingHashKey.add(endingHashKey).divide(new Bi
gInteger("2")).toString();
splitShardRequest.setNewStartingHashKey(newStartingHashKey);
client.splitShard(splitShardRequest);
等待流再次变为活动状态 (p. 94) 中演示了此过程之后的第一步。
合并两个分片
Abstract
了解如何使用适用于 Java 的 AWS 开发工具包合并 Amazon Kinesis stream 的分片。
分片合并操作使用两个指定分片并将它们合并为一个分片。在合并后,单个子分片将收到两个父分片所包
含的所有哈希键值的数据。
分片相邻
若要合并两个分片,分片必须相邻。如果两个分片的哈希键范围联合构成一个无间断的连续集,则认为两
个分片相邻。例如,如果您有两个分片,一个分片的哈希键范围为 276...381,另一个分片的哈希键范围
为 382...454,则您可将这两个分片合并为一个分片,其哈希键范围为 276...454。
另举一例,如果您有两个分片,一个分片的哈希键范围为 276..381,另一个分片的哈希键范围为 455...560,
则您无法合并这两个分片,因为这两个分片之间有一个或多个哈希键在 382..454 范围的分片。
流中所有 OPEN 分片的集(作为一个组)始终跨越 MD5 哈希键值的整个范围。有关分片状态(如 CLOSED)
的更多信息,请参阅 分片之后的数据路由、数据保留和分片状态 (p. 95)。
要标识作为合并候选的分片,您应筛选出处于 CLOSED 状态的所有分片。处于 OPEN 状态(不是 CLOSED
状态)的分片将具有结束序列号 null。您可使用以下命令测试此结束序列号:
if( null == shard.getSequenceNumberRange().getEndingSequenceNumber() )
{
// Shard is OPEN, so it is a possible candidate to be merged.
}
在筛选出已关闭分片后,按每个分片支持的最高哈希键值对剩余分片进行排序。您可使用以下命令检索此
值:
shard.getHashKeyRange().getEndingHashKey();
如果两个分片在这个经过筛选和排序的列表中相邻,则可合并它们。
合并操作的代码
以下代码可合并两个分片。此代码假定 myStreamName 包含您的流名称并且对象变量 shard1 和 shard2
包含要合并的两个相邻分片。
为进行合并操作,首先实例化一个新的 mergeShardsRequest 对象。使用 setStreamName 方法指定
流名称。然后使用 setShardToMerge 和 setAdjacentShardToMerge 方法指定要合并的两个分片。
最后,对 Streams 客户端调用 mergeShards 方法以执行此操作。
93
Amazon Kinesis Streams 开发人员指南
对流进行重新分片
MergeShardsRequest mergeShardsRequest = new MergeShardsRequest();
mergeShardsRequest.setStreamName(myStreamName);
mergeShardsRequest.setShardToMerge(shard1.getShardId());
mergeShardsRequest.setAdjacentShardToMerge(shard2.getShardId());
client.mergeShards(mergeShardsRequest);
等待流再次变为活动状态 (p. 94) 中演示了此过程之后的第一步。
重新分片后
Abstract
了解在使用适用于 Java 的 AWS 开发工具包对 Amazon Kinesis stream 执行重新分片后应执行的操作。
在任何类型的重新分片过程之后,并在继续常规的记录处理之前,需要执行其他一些过程并考虑一些注意
事项。以下各节介绍了这些过程。
主题
• 等待流再次变为活动状态 (p. 94)
• 分片之后的数据路由、数据保留和分片状态 (p. 95)
等待流再次变为活动状态
在调用重新分片操作 splitShard 或 mergeShards 之后,您需要等待流再次变为活动状态。要使用的
代码与您在创建流 (p. 88)之后等待流变为活动状态时使用的代码相同。下面重复列出了代码。
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( de
scribeStreamRequest );
String streamStatus = describeStreamResponse.getStreamDescription().get
StreamStatus();
if ( streamStatus.equals( "ACTIVE" ) ) {
break;
}
//
// sleep for one second
//
try {
Thread.sleep( 1000 );
}
catch ( Exception e ) {}
}
catch ( ResourceNotFoundException e ) {}
94
Amazon Kinesis Streams 开发人员指南
更改数据保留期
}
if ( System.currentTimeMillis() >= endTime )
{
throw new RuntimeException( "Stream " + myStreamName + " never went active"
);
}
分片之后的数据路由、数据保留和分片状态
Streams 是一种实时数据流服务,也就是说,您的应用程序应假定数据不断地在流中的分片内流动。当您
重新分片时,流至父分片的数据记录将基于数据记录分区键映射到的哈希键值重新路由至子分片。但是,
重新分片前位于父分片中的任何数据记录将仍位于这些父分片中。换句话说,父分片在重新分片发生时不
会消失;它们将与重新分片之前它们包含的数据一起保留。父分片中的数据记录可通过在 Streams API
中使用 getShardIterator 和 getRecords (p. 75) 操作或通过 Amazon Kinesis Client Library 进行访
问。
Note
数据记录在当前保留期内添加到流中后即可访问。不论在该期间内对流中的分片进行了任何更
改,都是如此。有关流的保留期的更多信息,请参阅the section called “更改数据保留期” (p. 95)。
在重新分片过程中,父分片将从 OPEN 状态过渡到 CLOSED 状态再过渡到 EXPIRED 状态。
• OPEN:在重新分片操作之前,父分片处于 OPEN 状态,这意味着数据记录可添加到分片中并且可从分
片进行检索。
• CLOSED:在重新分片操作之后,父分片将过渡到 CLOSED 状态。这意味着无法再向此分片添加数据
记录。原本应该已添加到此分片的数据记录现在将改为添加到子分片。但是,数据记录在有限时间内仍
可从此分片进行检索。
• EXPIRED:在流的保留期过期之后,父分片中的所有数据记录将会过期,不再可供访问。此时,父分
片自身将过渡到 EXPIRED 状态。用于枚举流中的分片的 getStreamDescription().getShards 调
用不包括返回的分片列表中的 EXPIRED 分片。有关流的保留期的更多信息,请参阅the section called
“更改数据保留期” (p. 95)。
在进行重新分片并且流再次处于 ACTIVE 状态之后,您可立即开始读取子分片中的数据。但是,在重新分
片后保留的父分片可能仍包含您尚未读取并且已在重新分片前添加到流中的数据。如果您在读取完父分片
中的所有数据之前读取子分片中的数据,则可不按数据记录的序列号指定的顺序读取特定哈希键的数据。
因此,假定数据顺序很重要,您在重新分片后应始终继续读取父分片中的数据直到读取完,并且只有在这
之后才开始读取子分片中的数据。如果 getRecordsResult.getNextShardIterator 返回 null,则
这指示您已读取完父分片中的所有数据。如果您使用 Amazon Kinesis Client Library 读取数据,则此库可
确保您按顺序接收数据,即使发生重新分片也是如此。
更改数据保留期
Abstract
了解如何更改 Amazon Kinesis stream 的记录保留期。
Streams 支持更改您的流的数据记录保留期。Amazon Kinesis stream 是数据记录的有序序列,可用于执
行实时写入和读取。因此,数据记录临时存储在您的流的分片中。从添加记录开始,到记录不再可供访问
为止的时间段称为保留期。Amazon Kinesis stream 默认情况下存储记录 24 小时,最高可存储 168 小
时。
您可以使用 IncreaseRetentionPeriod 操作将保留期增加到最高 168 小时,使用
DecreaseRetentionPeriod 操作可将保留期减少到最短 24 小时。两个操作的请求语法均包括流名称
和保留期(以小时为单位)。最后,您可以通过调用 DescribeStream 操作来检查流的当前保留期。
95
Amazon Kinesis Streams 开发人员指南
监控
这两个操作都很容易运行。通过 AWS CLI 更改保留期的示例(链接)如下所示。
aws kinesis increase-stream-retention-period --stream-name retentionPeriodDemo
--retention-period-hours 72
在增加保留期后的数分钟内,Streams 会使处于旧保留期内的记录可继续访问。例如,将保留期从 24 小
时更改为 48 小时意味着,在 23 小时 55 分钟之前添加到流中的记录在经过 24 小时之后仍可供访问。
在缩短保留期后,Streams 几乎会立即使比新保留期更早的记录不可供访问。因此,在调用
DecreaseRetentionPeriod 操作时务必小心谨慎。
数据保留期的设置应该确保在出现问题时,您的使用器可以在数据过期之前读取数据。您应该仔细考虑所
有可能的情况,例如记录处理逻辑出现问题,或者下游依赖关系长时间断开。保留期应该视为安全网,以
便使您的数据使用器有更多时间来恢复。使用保留期 API 操作,您可以主动设置此项,或者积极响应操
作事件。
对于保留期设置为 24 小时以上的流,将收取额外费用。有关更多信息,请参阅Amazon Kinesis Streams
定价。
监控 Amazon Kinesis Streams
Abstract
了解如何在 Amazon Kinesis Streams 中监控您的流。
您可利用以下功能监控 Amazon Kinesis Streams:
• CloudWatch 指标 (p. 96) - Streams 发送与针对每个流的详细监控相关的 Amazon CloudWatch 自定义
指标。
• Amazon Kinesis 代理 (p. 99) - Amazon Kinesis 代理发布自定义 CloudWatch 指标以帮助评估代理是否
按预期运行。
• API 日志记录 (p. 99) - Streams 使用 AWS CloudTrail 记录 API 调用并将数据存储在 Amazon S3 存储
桶中。
• Amazon Kinesis 客户端库 (p. 103) - Streams 客户端库 (KCL) 提供针对分片、工作程序和 KCL 应用程
序的指标。
• Amazon Kinesis 生产者库 (p. 111) - Streams 生产者库 (KPL) 提供针对分片、工作程序和 KPL 应用程序
的指标。
利用 Amazon CloudWatch 监控 Amazon Kinesis
Streams 服务
Abstract
查看 Amazon Kinesis Streams 服务发送到 CloudWatch 的指标。
通过将 Amazon Kinesis Streams 和 Amazon CloudWatch 集成,您可以收集、查看和分析您的 Amazon
Kinesis stream 的 CloudWatch 指标。例如,要跟踪分片使用情况,您可监控 PutRecords.Bytes 和
GetRecords.Bytes 指标并将它们与流中分片数进行比较。
您为流配置的指标将每分钟自动收集一次并推送给 CloudWatch。指标会存档两周。两周后,数据会被丢
弃。
CloudWatch 中报告的 Streams 指标是不收费的。
96
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控服务
Amazon Kinesis 指标
Amazon Kinesis 会向 CloudWatch 发送以下指标。
指标
说明
PutRecord.Bytes
在指定时段内使用 PutRecord 放置到 Amazon Kinesis 流的字节数。
单位:字节
有效统计数据:Minimum、Maximum、Average、Sum
PutRecord.Latency
在指定时段内测量的每个 PutRecord 操作所用的时间。
单位:毫秒
有效统计数据:Minimum、Maximum、Average
PutRecord.Success
在指定时段内每个 Amazon Kinesis 流中的成功PutRecord操作数。平均值
反映了对流的成功写入的百分比。
单位:计数
有效统计数据:Average、Sum、Data Samples
PutRecords.Bytes
在指定时段内使用 PutRecords 放置到 Amazon Kinesis 流的字节数。
单位:字节
有效统计数据:Minimum、Maximum、Average、Sum
PutRecords.Latency 在指定时段内测量的每个 PutRecords 操作所用的时间。
单位:毫秒
有效统计数据:Minimum、Maximum、Average
PutRecords.Records 在指定时段内测量的每个 Amazon Kinesis 流的 PutRecords 操作中的成功
记录数。
单位:计数
有效统计数据:Minimum、Maximum、Average、Sum
PutRecords.Success 在指定时间段内测得的每个 Amazon Kinesis 流中至少有一个记录成功的 PutRecords 操作的数量。
单位:计数
有效统计数据:Average、Sum、Data Samples
IncomingBytes
在指定时段内成功放置到 Amazon Kinesis 流的字节数。该指标包含来自 PutRecord 和 PutRecords 的字节数。
单位:字节
有效统计数据:Minimum、Maximum、Average、Sum
97
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控服务
指标
说明
IncomingRecords
在指定时段内成功放置到 Amazon Kinesis 流的记录数。该指标包含来自 PutRecord 和 PutRecords 的记录数。
单位:计数
有效统计数据:Minimum、Maximum、Average、Sum
GetRecords.Bytes
在指定时段内从 Amazon Kinesis 流检索的字节数。
单位:字节
有效统计数据:Minimum、Maximum、Average、Sum
GetRecords.Iterat- 此指标已弃用。使用 GetRecords.IteratorAgeMilliseconds.
orAge
GetRecords.Iterat- 对某个 Amazon Kinesis 流进行的所有 GetRecords 调用中最后一条记录的
orAgeMilliseconds 存在时间,是在指定的时间段测量的。存在时间是当前时间与最后一条
GetRecords 调用记录写入流的时间之差。Minimum 和 Maximum 统计数据
可用于跟踪 Amazon Kinesis 使用者应用程序的进度。值为“零”表示正在读取
的记录已完全与流匹配。
单位:毫秒
有效统计数据:Minimum、Maximum、Average
GetRecords.Latency 在指定时段内测量的每个 GetRecords 操作所用的时间。
单位:毫秒
有效统计数据:Minimum、Maximum、Average
GetRecords.Success 在指定时段内测量的每个流中的成功 GetRecords 操作数。
单位:计数
有效统计数据:Average、Sum、Data Samples
访问 Streams 的 Amazon CloudWatch 指标
您可使用 CloudWatch 控制台、命令行或 CloudWatch API 监控 Streams 的指标。以下过程介绍如何使
用这些不同的方式访问指标。
使用 CloudWatch 控制台访问指标
1.
2.
通过以下网址打开 CloudWatch 控制台:https://console.amazonaws.cn/cloudwatch/。
从导航栏中选择区域。
3.
4.
5.
在导航窗格中,选择 Metrics。
在 CloudWatch Metrics by Category 窗格中,选择 Kinesis Metrics。
单击相关行可查看指定的 MetricName 和 StreamName 的统计数据。
注意:大部分控制台统计数据名称与上面列出的对应 CloudWatch 指标名称匹配,不过 Read
Throughput 和 Write Throughput 例外。这些统计数据按照 5 分钟的时间间隔计算:Write Throughput
监控 IncomingBytes CloudWatch 指标,Read Throughput 监控 GetRecords.Bytes。
6.
(可选)在图形窗格中,选择一个统计数据和时间段,然后使用这些设置创建 CloudWatch 警报。
98
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控代理
使用 AWS CLI 访问指标
使用 list-metrics 和 get-metric-statistics 命令。
使用 CloudWatch CLI 访问指标
使用 mon-list-metrics 和 mon-get-stats 命令。
使用 CloudWatch API 访问指标
使用 ListMetrics 和 GetMetricStatistics 操作。
使用 Amazon CloudWatch 监控 Streams 代理运行状
况
代理发布自定义 CloudWatch 指标以及命名空间 AWSKinesisAgent 来帮助评估代理是否按指定方式将数
据提交到 Streams、运行正常并且在数据创建器上使用适当数量的 CPU 和内存资源。记录数和发送的字
节数等指标对于了解代理将数据提交到流的速率非常有用。当这些指标低于预期阈值一定的百分比或者降
低为零时,可能表明存在配置问题、网络错误或代理运行状况问题。诸如主机上的 CPU 和内存消耗以及
代理错误计数器等指标可用于指示数据创建器资源使用情况,并提供对潜在的配置或主机错误的深入分
析。最后,代理还会记录服务异常,以帮助调查代理问题。这些指标在代理配置设置
cloudwatch.endpoint 指定的区域中报告。有关代理配置的更多信息,请参阅the section called “代理
配置设置” (p. 54)。
使用 CloudWatch 进行监控
Streams 代理会向 CloudWatch 发送以下指标。
指标
说明
BytesSent
在指定时间段内发送到 Streams 的字节数。
单位:字节
RecordSendAttempts 在指定的时间范围内对 PutRecords 的一次调用中尝试的记录数(第一次,
或者作为重试)。
单位:计数
RecordSendErrors
在指定时间范围内对 PutRecords 的一次调用中返回故障状态的记录数,包
括重试。
单位:计数
ServiceErrors
在指定时间范围内产生服务错误(限制错误之外的其他错误)的 PutRecords
调用次数。
单位:计数
使用 AWS CloudTrail 记录 Amazon Kinesis Streams
API 调用
Abstract
记录 Amazon Kinesis Streams 的 API 调用。
99
Amazon Kinesis Streams 开发人员指南
使用 CloudTrail 记录 API 调用
Amazon Kinesis Streams 与 AWS CloudTrail, 集成在一起,这将捕获由 Streams 或代表它发出的 API 调
用,并将日志文件传送到您指定的 Amazon S3 存储桶。这些 API 调用可通过使用 Streams 控制台间接
发出,也可以通过使用 Streams API 直接发出。通过使用 CloudTrail 收集的信息,您可以确定向 Streams
发出了什么请求、发出请求的源 IP 地址、何人发出的请求以及发出请求的时间等。要了解有关 CloudTrail
的更多信息,包括如何对其进行配置和启用,请参阅 AWS CloudTrail User Guide。
Streams 和 CloudTrail
在启用 CloudTrail 日志记录后,将在日志文件中跟踪对 Streams 操作发出的调用。Streams 的记录将与
为 CloudTrail 日志记录启用的任何其他 AWS 服务中的记录一起写入日志文件中。CloudTrail 基于指定的
时间段和文件大小来确定何时创建新文件并向其写入内容。
支持以下操作:
• CreateStream
• DeleteStream
• DescribeStream
• ListStreams
• MergeShards
• SplitShard
每个日志条目都包含有关生成请求的人员的信息。例如,如果已发出创建流的请求 (CreateStream),则
发出该请求的人员或服务的用户身份会被记录下来。用户身份信息有助于确定发出的请求是否具有根或
IAM 用户证书,是否具有角色或联合用户临时安全证书,或者是否由其他 AWS 服务发出。有关更多信
息,请参阅 AWS CloudTrail User Guide 中的 userIdentity 元素。
日志文件可以在存储桶中存储任意长时间,不过您也可以定义 Amazon S3 生命周期规则以自动存档或删
除日志文件。默认情况下,将使用 Amazon S3 服务器端加密 (SSE) 对日志文件进行加密。
您还可以将多个 AWS 区域和多个 AWS 账户中的 Streams 日志文件聚合到单个 Amazon S3 存储桶中。
有关信息,请参阅 AWS CloudTrail User Guide 中的将 CloudTrail 日志文件聚合到单个 Amazon S3 存储
桶中。
如果您需要针对日志文件传输快速采取措施,可让 CloudTrail 在传输新的日志文件时发布 SNS 通知。有
关信息,请参阅 AWS CloudTrail User Guide 中的配置 Amazon SNS 通知。
Streams 的日志文件条目
CloudTrail 日志文件可包含一个或多个日志条目,每个条目由多个 JSON 格式的事件组成。一个日志条目
表示来自任何源的一个请求,包括有关所请求的操作、所有参数以及操作的日期和时间等信息。日志条目
不一定具有任何特定顺序。也就是说,这不是 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"
100
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,
101
Amazon Kinesis Streams 开发人员指南
使用 CloudTrail 记录 API 调用
"requestID": "a68541ca-c757-11e3-901b-cbcfe5b3677a",
"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",
102
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控 KCL
"accessKeyId": "EXAMPLE_KEY_ID",
"userName": "Alice"
},
"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 客户
端库
Abstract
了解 Amazon Kinesis 客户端库中提供的指标。
Amazon Kinesis Streams 的 Amazon Kinesis Client Library (KCL) 通过将您的 KCL 应用程序名称用作命
名空间来代表您发布自定义 Amazon CloudWatch 指标。您可以通过导航至 CloudWatch 控制台 并选择
Custom Metrics 来查看这些指标。有关自定义指标的更多信息,请参阅 Amazon CloudWatch 开发者指
南 中的发布自定义指标。
对于由 KCL 上传到 CloudWatch 的指标,需要收取名义上的费用;具体而言,将收取 Amazon CloudWatch
自定义指标 和 Amazon CloudWatch API 请求 费用。有关更多信息,请参阅 Amazon CloudWatch 定价。
主题
• 指标和命名空间 (p. 103)
• 指标级别和维度 (p. 103)
• 指标配置 (p. 104)
• 指标的列表 (p. 104)
指标和命名空间
用于上传指标的命名空间将是您在启动 KCL 时指定的应用程序名称。
指标级别和维度
可通过两个选项控制上传到 CloudWatch 的指标:
指标级别
每个指标分配有一个独立的级别。在您设置指标报告级别后,独立级别低于报告级别的指标将不会发
送到 CloudWatch。级别如下:NONE、SUMMARY 和 DETAILED。默认设置为 DETAILED;即,所有
103
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控 KCL
指标都将发送到 CloudWatch。NONE 报告级别意味着不会发送任何指标。有关将哪些级别分配到哪
些指标的信息,请参阅 the section called “指标的列表” (p. 104)。
启用的维度
每个 KCL 指标都有一个也将发送到 CloudWatch 的关联维度。将始终上传并且不会禁用 Operation
维度。默认情况下,将禁用 WorkerIdentifier,并且仅上传 Operation 和 ShardId 维度。
有关 CloudWatch 指标维度的更多信息,请参阅 Amazon CloudWatch 开发者指南 中的“CloudWatch
概念”主题中的 维度节。
请注意,启用 WorkerIdentifier 维度后,如果每次特定的 KCL 工作程序重新启动时使用的是不
同的工作程序 ID 属性值,则会将新的指标组和新的 WorkerIdentifier 维度值组发送到
CloudWatch。如果您需要 WorkerIdentifier 维度值在特定的 KCL 工作程序重新启动时保持不
变,则必须在每个工作程序初始化时显式指定相同的工作程序 ID 值。请注意,每个有效 KCL 工作程
序的工作程序 ID 值在所有 KCL 工作程序中必须是唯一的。
指标配置
指标级别和启用的维度可使用 KinesisClientLibConfiguration 实例进行配置,该实例将在启动 KCL 应用程
序时将传递给工作程序。在 MultiLangDaemon 案例中,metricsLevel 和 metricsEnabledDimensions
属性可在用于启动 MultiLangDaemon KCL 应用程序的 .properties 文件中指定。
可向指标级别分配下列三个值之一:NONE、SUMMARY 或 DETAILED。启用的维度值在 CloudWatch
指标允许的维度的列表中必须是以逗号分隔的字符串。KCL 应用程序使用的维度为 Operation、ShardId
和 WorkerIdentifier。
指标的列表
本节包含列出 KCL 指标(按作用域和操作分组)的表。
主题
• 针对 KCL 应用程序的指标 (p. 104)
• Per-Worker 指标 (p. 107)
• Per-Shard 指标 (p. 109)
针对 KCL 应用程序的指标
这些指标跨应用程序作用域内的所有 KCL 工作程序聚合一起,就像 Amazon CloudWatch 命名空间所定
义的那样。
主题
• InitializeTask (p. 104)
• ShutdownTask (p. 105)
• ShardSyncTask (p. 106)
• BlockOnParentTask (p. 107)
InitializeTask
InitializeTask 操作负责初始化 KCL 应用程序的记录处理器。此操作的逻辑包括从 Streams 中获取
分片迭代器并初始化记录处理程序。
指标:
指标名称
描述
104
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控 KCL
KinesisDataFetcher.getIterator.Success
每个 KCL 应用程序的成功 GetShardIterator 操作的数量。
指标级别:详细
单位:计数
KinesisDataFetcher.getIterator.Time
给定 KCL 应用程序的每个 GetShardIterator 操作所花费的时间。
指标级别:详细
单位:毫秒
RecordProcessor.initial- 记录处理器的初始化方法所花费的时间。
ize.Time
指标级别:汇总
单位:毫秒
成功
成功的记录处理程序初始化的数目。
指标级别:汇总
单位:计数
时间
KCL 工作程序初始化记录处理器所花费的时间。
指标级别:汇总
单位:毫秒
ShutdownTask
ShutdownTask 操作初始化分片处理的关闭顺序。这可能是因为分片被拆分或合并,或者当分片租赁从
工作程序中丢失时。在这两种情况下,将调用记录处理程序 shutdown() 函数。在分片被拆分或合并的
情况下也会发现新的分片,这将创建一个或两个新的分片。
指标:
指标名称
描述
CreateLease.Success
新的子分片在父分片关闭后成功添加到 KCL 应用程序 DynamoDB 表的次数。
指标级别:详细
单位:计数
CreateLease.Time
在 KCL 应用程序 DynamoDB 表中添加新的子分片信息所花费的时间。
指标级别:详细
单位:毫秒
UpdateLease.Success
记录处理程序关闭期间成功的最终检查点的数目。
指标级别:详细
单位:计数
105
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控 KCL
UpdateLease.Time
记录处理程序关闭期间检查点操作所花费的时间。
指标级别:详细
单位:毫秒
RecordProcessor.shutdown.Time
记录处理器的关闭方法所花费的时间。
指标级别:汇总
单位:毫秒
成功
成功的关闭任务的数目。
指标级别:汇总
单位:计数
时间
KCL 工作程序关闭任务所花费的时间。
指标级别:汇总
单位:毫秒
ShardSyncTask
ShardSyncTask 操作会发现对 Amazon Kinesis stream 的分片信息所做的更改,因此 KCL 应用程序可
处理新的分片。
指标:
指标名称
描述
CreateLease.Success
将新的分片信息添加到 KCL 应用程序 DynamoDB 表的成功尝试次数。
指标级别:详细
单位:计数
CreateLease.Time
在 KCL 应用程序 DynamoDB 表中添加新的分片信息所花费的时间。
指标级别:详细
单位:毫秒
成功
成功的分片同步操作的数目。
指标级别:汇总
单位:计数
时间
分片同步操作所花费的时间。
指标级别:汇总
单位:毫秒
106
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控 KCL
BlockOnParentTask
如果一个分片被拆分或与其他分片合并,则会创建新的子分片。BlockOnParentTask 操作确保新分片
的记录处理在 KCL 完全处理父分片之前不会开始。
指标:
指标名称
描述
成功
父分片完成的成功检查的数目。
指标级别:汇总
单位:计数
时间
父分片完成所花费的时间。
指标级别:汇总
单位:毫秒
Per-Worker 指标
这些指标跨使用 Amazon Kinesis stream(例如 Amazon EC2 实例)中的数据的所有记录处理程序进行
聚合。
主题
• RenewAllLeases (p. 107)
• TakeLeases (p. 108)
RenewAllLeases
RenewAllLeases 操作定期续订由特定工作程序实例拥有的分片租约。
指标:
指标名称
描述
RenewLease.Success
工作程序成功续订租约的数目。
指标级别:详细
单位:计数
RenewLease.Time
租约续订操作所花费的时间。
指标级别:详细
单位:毫秒
CurrentLeases
续订所有租约后由工作程序拥有的分片租约数。
指标级别:汇总
单位:计数
107
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控 KCL
LostLeases
在尝试续订由工作程序拥有的所有租约后丢失的分片租约数。
指标级别:汇总
单位:计数
成功
工作程序的成功的租约续订操作次数。
指标级别:汇总
单位:计数
时间
续订工作程序的所有租约所花费的时间。
指标级别:汇总
单位:毫秒
TakeLeases
TakeLeases 操作使所有 KCL 工作程序之间的记录处理达到平衡。如果当前 KCL 工作程序拥有的分片租
约少于所需的分片租约,则将从已过载的另一个工作程序中提取分片租约。
指标:
指标名称
描述
ListLeases.Success
成功从 KCL 应用程序 DynamoDB 表中检索所有分片租约的次数。
指标级别:详细
单位:计数
ListLeases.Time
从 KCL 应用程序 DynamoDB 表中检索所有分片租约所花费的时间。
指标级别:详细
单位:毫秒
TakeLease.Success
此工作程序成功从其他 KCL 工作程序中提取分片租约的次数。
指标级别:详细
单位:计数
TakeLease.Time
利用该工作程序提取的租约更新租约表所花费的时间。
指标级别:详细
单位:毫秒
NumWorkers
工作程序总数,由特定工作程序标识。
指标级别:汇总
单位:计数
108
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控 KCL
NeededLeases
当前工作程序为平衡分片处理负载所需的分片租约数。
指标级别:详细
单位:计数
LeasesToTake
工作程序将尝试提取的租约的数目。
指标级别:详细
单位:计数
TakenLeases
工作程序已成功提取的租约的数目。
指标级别:汇总
单位:计数
TotalLeases
KCL 应用程序正在处理的分片的总数。
指标级别:详细
单位:计数
ExpiredLeases
未由任何工作程序处理的分片的总数,由特定工作程序标识。
指标级别:汇总
单位:计数
成功
TakeLeases 操作已成功完成的次数。
指标级别:汇总
单位:计数
时间
工作程序的 TakeLeases 操作所花费的时间。
指标级别:汇总
单位:毫秒
Per-Shard 指标
这些指标跨单个记录处理程序聚合一起。
ProcessTask
ProcessTask 操作利用当前迭代器位置调用 GetRecords 以从流中检索记录并调用记录处理器
processRecords 函数。
指标:
指标名称
描述
KinesisDataFetcher.getRecords.Success
每个 Amazon Kinesis stream 分片的成功 GetRecords 操作的数量。
指标级别:详细
单位:计数
109
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控 KCL
KinesisDataFetcher.getRecords.Time
Amazon Kinesis stream 分片的每个 GetRecords 操作所花费的时间。
指标级别:详细
单位:毫秒
UpdateLease.Success
给定分片的记录处理程序完成的成功检查点的数目。
指标级别:详细
单位:计数
UpdateLease.Time
给定分片的每个检查点操作所花费的时间。
指标级别:详细
单位:毫秒
DataBytesProcessed
每个 ProcessTask 调用所处理的记录的总大小(以字节为单位)。
指标级别:汇总
单位:字节
RecordsProcessed
每个 ProcessTask 调用所处理的记录的数量。
指标级别:汇总
单位:计数
ExpiredIterator
调用 GetRecords 时收到的 ExpiredIteratorException 的数量。
指标级别:汇总
单位:计数
MillisBehindLatest
当前迭代器晚于分片中最新记录的时间。
指标级别:汇总
单位:毫秒
RecordProcessor.processRecords.Time
记录处理器的 processRecords 方法所花费的时间。
指标级别:汇总
单位:毫秒
成功
成功处理任务操作的数目。
指标级别:汇总
单位:计数
时间
处理任务操作所花费的时间。
指标级别:汇总
单位:毫秒
110
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控 KPL
利用 Amazon CloudWatch 监控 Amazon Kinesis 创建
器库
Abstract
了解 Amazon Kinesis 创建器库中提供的指标。
Amazon Kinesis Streams 的 Amazon Kinesis 创建器库 (KPL) 代表您发布自定义 Amazon CloudWatch
指标。您可以通过导航至 CloudWatch 控制台 并选择 Custom Metrics 来查看这些指标。有关自定义指标
的更多信息,请参阅 Amazon CloudWatch 开发者指南 中的发布自定义指标。
将象征性地对由 KPL 上传到 CloudWatch 的指标收取费用;具体而言,将收取 Amazon CloudWatch 自
定义指标和 Amazon CloudWatch API 请求费用。有关更多信息,请参阅 Amazon CloudWatch 定价。本
地指标收集不会产生 CloudWatch 费用。
主题
• 指标、维度和命名空间 (p. 111)
• 指标级别和粒度 (p. 111)
• 本地访问和 Amazon CloudWatch 上传 (p. 112)
• 指标的列表 (p. 112)
指标、维度和命名空间
您可在启动 KPL 时指定应用程序名称,该名称随后在上传指标时将用作命名空间的一部分。这是可选的;
如果未设置应用程序名称,则 KPL 会提供一个默认值。
您也可以配置 KPL 来将任意其他维度添加到指标。这在您希望获得 CloudWatch 指标中的更详细数据时
很有用。例如,您可将主机名作为维度添加,随后该维度将允许您标识队列中不均匀的负载分配。所有
KPL 配置设置是不可变的,因此在初始化 KPL 实例后无法更改其他维度。
指标级别和粒度
可通过两个选项控制已上传到 CloudWatch 的指标的数目:
指标级别
这是对指标重要性的粗略估计。为每个指标分配了一个级别。在设置一个级别时,级别低于该级别的
指标将不会发送到 CloudWatch。级别为 NONE、SUMMARY 和 DETAILED。默认设置为 DETAILED;
即所有指标。NONE 表示没有任何指标,因此实际上未为该级别分配任何指标。
粒度
这可控制是否在其他粒度级别发出相同指标。级别为 GLOBAL、STREAM 和 SHARD。默认设置为
SHARD,其中包含粒度最高的指标。
选择 SHARD 后,发出将流名称和分片 ID 作为维度的指标。此外,还发出仅具有流名称维度的相同指
标和不带流名称的指标。这意味着,对于特定指标,具有两个分片的两个流均会生成 7 个 CloudWatch
指标:一个针对每个分片的指标、一个针对每个流的指标以及一个针对整体的指标;所有指标都描述
相同但处于不同级别粒度的统计数据。有关说明,请见下图。
层次结构中的不同粒度级别与系统中的所有指标构成了一个基于指标名称的树:
MetricName (GLOBAL):
Metric X
|
----------------|
|
111
Metric Y
|
-----------|
|
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控 KPL
StreamName (STREAM):
ShardId (SHARD):
Stream A
|
-------|
|
Shard 0 Shard 1
Stream B
Stream A
|
--------|
|
Shard 0 Shard 1
Stream B
并不会在分片级别提供所有指标;一些指标本来就属于流级别或全局级别。将不会在分片级别生成这
些指标,即使已启用分片级别指标(上图中的 Metric Y)。
在指定其他维度时,您需要提供 tuple:<DimensionName, DimensionValue, Granularity>
的值。粒度用于确定自定义维度在层次结构中的插入位置:GLOBAL 表示其他维度将插入到指标名称
的后面;STREAM 表示其他维度将插入到流名称的后面;SHARD 表示其他维度将插入到分片 ID 的后
面。如果为每个粒度级别提供多个其他维度,则这些维度将按给定顺序插入。
本地访问和 Amazon CloudWatch 上传
将实时本地提供当前 KPL 实例的指标;您可随时查询 KPL 以获得这些指标。KPL 本地计算每个指标的
和、平均值、最小值、最大值和计数,就像在 CloudWatch 中一样。
您可获取从程序启动到当前时间点或在过去 N 秒内(其中 N 为介于 1 和 60 之间的整数)使用滚动窗口
累积的统计数据。
所有指标均可上传到 CloudWatch。这在跨多台主机聚合数据、监控和警报时特别有用。此功能在本地不
可用。
如前所述,您可选择使用指标级别和粒度设置来上传的指标。未上传的指标在本地可用。
不支持单独上传数据点,因为如果流量过高,则每秒会生成数以百万计的上传。为此,KPL 会将指标本
地聚合到 1 分钟存储桶中,并每分钟按启用的指标将统计数据对上传到 CloudWatch 一次。
指标的列表
指标
说明
User Record Received
由放置操作的 KPL 内核接收的逻辑用户记录的计数。在分片级别不可用。
指标级别:详细
单位:计数
User Records
Pending
当前挂起的用户记录的数目的定期取样。如果记录当前已缓冲并等待发送,
或已发送和正在发送到后端服务,则记录处于挂起状态。在分片级别不可用。
KPL 提供了专用方法来在全局级别检索此指标以便客户管理其放置速率。
指标级别:详细
单位:计数
User Records Put
已成功放置的逻辑用户记录的计数。
KPL 不计算此指标的失败记录数。这允许用于提供成功率的平均值、用于提
供总尝试数的计数以及用于提供失败计数的计数与总和之间的差值。
指标级别:汇总
单位:计数
112
Amazon Kinesis Streams 开发人员指南
利用 CloudWatch 监控 KPL
User Records Data
Put
逻辑用户记录成功放置的字节数。
指标级别:详细
单位:字节
Kinesis Records
Put
已成功放置的 Streams 记录的计数(每条 Streams 记录均可包含多个用户记
录)。
KPL 输出零作为失败记录数。这允许用于提供成功率的平均值、用于提供总
尝试数的计数以及用于提供失败计数的计数与总和之间的差值。
指标级别:汇总
单位:计数
Kinesis Records
Data Put
Streams 记录中的字节数。
指标级别:详细
单位:字节
Errors by Code
每种错误代码的计数。这引入了 StreamName 和 ShardId 等正常维度以及
ErrorCode 的其他维度。并非每个错误都可跟踪到分片。无法跟踪的错误仅
在流或全局级别发出。此指标捕获有关限制、分片映射更改、内部故障、服
务不可用、超时等的信息。
一次计算每条 Streams 记录的 Streams API 错误数。Streams 记录中的多个
用户记录不生成多个计数。
指标级别:汇总
单位:计数
All Errors
这是由与 Errors by Code 相同的错误引发的,但并不区分类型。这在常规监
控错误率而不需要手动汇总所有不同类型错误的计数时非常有用。
指标级别:汇总
单位:计数
Retries per Record 每个用户记录执行的重试次数。为一次性尝试成功的记录发出零。
在用户记录完成时(成功时或不再能够重试时)发出数据。如果记录生存时
间是一个较大的值,则此指标可能显著延迟。
指标级别:详细
单位:计数
Buffering Time
用户记录到达 KPL 和离开前往后端之间的时间。此信息将基于记录传回给用
户,还可用作聚合的统计数据。
指标级别:汇总
单位:毫秒
Request Time
执行 PutRecordsRequests 所花费的时间。
指标级别:详细
单位:毫秒
113
Amazon Kinesis Streams 开发人员指南
为您的流添加标签
User Records per
Kinesis Record
已聚合到单个 Streams 记录中的逻辑用户记录的数目。
指标级别:详细
单位:计数
Amazon Kinesis Re- 已聚合到单个 PutRecordsRequest 中的 Streams 记录的数目。在分片级别
cords per PutRe不可用。
cordsRequest
指标级别:详细
单位:计数
User Records per
PutRecordsRequest
包含在 PutRecordsRequest 中的用户记录的总数。这大致相当于之前两个
指标的产品。在分片级别不可用。
指标级别:详细
单位:计数
为您在 Amazon Kinesis Streams 中的流加标签
Abstract
将您自己的元数据标签分配给您在 Amazon Kinesis Streams 中的流,以便能管理这些标签。
您可以使用标签的形式,将自己的元数据分配到您在 Amazon Kinesis Streams 中创建的流。标签是您为
流定义的键值对。使用标签是管理 AWS 资源和组织数据(包括账单数据)的一种简单却强有力的方式。
内容
• 有关标签的基本知识 (p. 114)
• 使用标签跟踪成本 (p. 115)
• 标签限制 (p. 115)
• 使用 Streams 控制台为流添加标签 (p. 115)
• 使用 AWS CLI 为流添加标签 (p. 116)
• 使用 Streams API 为流添加标签 (p. 116)
有关标签的基本知识
使用 Streams 控制台、AWS CLI 或 Streams API 可完成以下任务:
• 向流添加标签
• 列出流的标签
• 从流中删除标签
您可以使用标签对流进行分类。例如,您可以按用途、所有者或环境对流进行分类。由于您定义每个标签
的键和值,因此您可以创建一组自定义类别来满足您的特定需求。例如,您可以定义一组标签来帮助您按
拥有者和关联应用程序跟踪流。以下几个标签示例:
• 项目:项目名称
• 所有者:名称
• 用途:负载测试
114
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.
3.
在 Stream List 页面上,选择一个流。
在 Stream Details 页面上,单击 Tags 选项卡。
向流添加标签
1.
2.
打开 Streams 控制台。在导航栏中,展开区域选择器并选择一个区域。
在 Stream List 页面上,选择一个流。
3.
4.
在 Stream Details 页面上,单击 Tags 选项卡。
在 Key 字段中指定标签键,(可选)在 Value 字段中指定标签值,然后单击 Add Tag。
115
Amazon Kinesis Streams 开发人员指南
使用 AWS CLI 为流添加标签
5.
如果 Add Tag 按钮未启用,即表示您指定的标签键或标签值不满足标签限制。有关更多信息,请参
阅 标签限制 (p. 115)。
要在 Tags 选项卡上的列表中查看您的新标签,请单击刷新图标。
从流中删除标签
1.
2.
打开 Streams 控制台。在导航栏中,展开区域选择器并选择一个区域。
在“Stream List”页面上,选择一个流。
3.
4.
在“Stream Details”页面上,单击 Tags 选项卡,然后单击标签的 Remove 图标。
在 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
从指定的流中删除标签。
使用 IAM 控制对 Amazon Kinesis Streams 资源的
访问
Abstract
使用 AWS Identity and Access Management (IAM) 控制对 Amazon Kinesis Streams 资源的访问。
使用 AWS Identity and Access Management (IAM) 可以执行以下操作:
• 在您的 AWS 账户下创建用户和组
• 为您的 AWS 账户下的每个用户分配唯一的安全证书
• 控制每个用户使用 AWS 资源执行任务的权限
• 允许另一 AWS 账户的用户共享 AWS 资源
• 创建 AWS 账户角色并定义可以担任这些角色的用户或服务
• 借助企业的现有身份验证,授予使用 AWS 资源执行任务的权限
116
Amazon Kinesis Streams 开发人员指南
策略语法
通过将 IAM 与 Streams 配合使用,您可以控制组织中的用户能否用特定的 Streams API 操作执行某项任
务,以及他们能否使用特定的 AWS 资源。
如果您使用 Amazon Kinesis Client Library (KCL) 开发应用程序,您的策略必须包含对 Amazon DynamoDB
和 Amazon CloudWatch 的权限;KCL 使用 DynamoDB 跟踪应用程序的状态信息,并使用 CloudWatch
代表您将 KCL 指标发送到 CloudWatch。有关 KCL 的更多信息,请参阅使用 Amazon Kinesis Client
Library 开发 Amazon Kinesis Streams 使用器 (p. 61)。
有关 IAM 的更多信息,请参阅下文:
• Identity and Access Management (IAM)
• 入门
• IAM 用户指南
有关 IAM 和 Amazon DynamoDB 的更多信息,请参阅 Amazon DynamoDB 开发人员指南 中的使用 IAM
控制对 Amazon DynamoDB 资源的访问。
有关 IAM 和 Amazon CloudWatch 的更多信息,请参阅 Amazon CloudWatch 开发者指南 中的 控制用户
对您的 AWS 账户的访问。
内容
• 策略语法 (p. 117)
• 针对 Streams 的操作 (p. 118)
• 适用于 Streams 的 Amazon 资源名称 (ARN) (p. 118)
• Streams 策略示例 (p. 118)
策略语法
IAM 策略是包含一个或多个语句的 JSON 文档。每个语句的结构如下:
{
"Statement":[{
"Effect":"effect",
"Action":"action",
"Resource":"arn",
"Condition":{
"condition":{
"key":"value"
}
}
}
]
}
组成语句的各个元素如下:
• Effect:此 effect 可以是 Allow 或 Deny。默认情况下 IAM 用户没有使用资源和 API 操作的权限,因
此,所有请求均会被拒绝。显式允许将覆盖默认规则。显式拒绝将覆盖任何允许。
• Action:action 是对其授予或拒绝权限的特定 API 操作。
• Resource:操作影响的资源。要在语句中指定资源,您需要使用其Amazon 资源名称 (ARN)。
• Condition:条件是可选的。它们可以用于控制策略生效的时间。
在创建和管理 IAM 策略时,您可能希望使用 AWS 策略生成器和 IAM 策略模拟器。
117
Amazon Kinesis Streams 开发人员指南
针对 Streams 的操作
针对 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 指定的资源。
请对 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的访问。
118
Amazon Kinesis Streams 开发人员指南
Streams 策略示例
Example 1:允许用户从流中获取数据
此策略允许用户或组对指定流执行 DescribeStream、ListStreams、GetShardIterator 和
GetRecords 操作。此策略可应用于应该能够从特定流获取数据的用户。
{
"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": [
"*"
]
}
]
}
Example 2:允许用户将数据添加到账户中的流
此策略允许用户或组对账户的任一流使用 PutRecord 操作。此策略可应用于应该能够向账户中的所有流
添加数据记录的用户。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kinesis:PutRecord"
],
"Resource": [
"arn:aws:kinesis:us-east-1:111122223333:stream/*"
]
}
]
}
119
Amazon Kinesis Streams 开发人员指南
Streams 策略示例
Example 3:允许对特定流的任何 Streams 操作
此策略允许用户或组对指定流使用任何 Streams 操作。此策略可应用于应该对特定流有管理控制权限的
用户。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "kinesis:*",
"Resource": [
"arn:aws:kinesis:us-east-1:111122223333:stream/stream1"
]
}
]
}
Example 4:允许对任何流的任何 Streams 操作
此策略允许用户或组对账户中的任何流使用任何 Streams 操作。由于此策略会授予对您的所有流的完全
访问权限,您应该将其限制为仅对管理员可用。
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": "kinesis:*",
"Resource": [
"arn:aws:kinesis:*:111122223333:stream/*"
]
}
]
}
120
Amazon Kinesis Streams 开发人员指南
文档历史记录
Abstract
查找 Amazon Kinesis Streams 文档的修订日期、相关版本和重要更改。
下表介绍了对 Amazon Kinesis Streams 文档的一些重要更改。
更改
描述
修改日期
新增了关于使用
Streams 代理的内
容。
增加了 使用 Amazon Kinesis 代理写入 Amazon Kinesis
Streams (p. 52).
2015 年 10 月 2 日
更新 0.10.0 版的 KPL 增加了 使用 Amazon Kinesis 创建器库 开发 Amazon
内容。
Kinesis Streams 创建器 (p. 39).
2015 年 7 月 15 日
更新可配置指标的
KCL 指标主题。
增加了 利用 Amazon CloudWatch 监控 Amazon Kinesis 2015 年 7 月 9 日
客户端库 (p. 103).
重新组织的内容。
为提供更简洁的树视图和更有逻辑的分组,内容主题经过 2015 年 7 月 01 日
了大幅地重新组织。
“新 KPL 开发人员的
指南”主题。
增加了 使用 Amazon Kinesis 创建器库 开发 Amazon
Kinesis Streams 创建器 (p. 39).
2015 年 6 月 02 日
“新 KCL 指标”主题。 增加了 利用 Amazon CloudWatch 监控 Amazon Kinesis 2015 年 5 月 19 日
客户端库 (p. 103).
对 KCL .NET 的支持 增加了 在 .NET 中开发 Amazon Kinesis Client Library 使 2015 年 5 月 1 日
用者 (p. 70).
对 KCL Node.js 的支 增加了 在 Node.js 中开发 Amazon Kinesis Client Library 2015 年 3 月 26 日
持
使用者 (p. 67).
对 KCL Ruby 的支持 添加了指向 KCL Ruby 库的链接。
2015 年 1 月 12 日
新 API PutRecords
向the section called “使用 PutRecords 添加多个记
录” (p. 49)添加了有关新 PutRecords API 的信息。
2014 年 12 月 15 日
对标签的支持
增加了 为您在 Amazon Kinesis Streams 中的流加标
签 (p. 114).
2014 年 9 月 11 日
121
Amazon Kinesis Streams 开发人员指南
更改
描述
修改日期
新 CloudWatch 指标
向 Amazon Kinesis 指标 (p. 97)添加了指标 GetRecords.IteratorAgeMilliseconds。
2014 年 9 月 3 日
新的监控章节
添加了监控 Amazon Kinesis Streams (p. 96)和利用
Amazon CloudWatch 监控 Amazon Kinesis Streams 服
务 (p. 96)。
2014 年 7 月 30 日
新的示例应用程序
增加了 教程:使用 Amazon Kinesis Streams 可视化 Web 2014 年 6 月 27 日
流量 (p. 9).
默认分片限制
更新了 Amazon Kinesis Streams 限制 (p. 7):默认分片
限制从 5 个提高到 10 个。
2014 年 2 月 25 日
默认分片限制
更新了 Amazon Kinesis Streams 限制 (p. 7):默认分片
限制从 2 个提高到 5 个。
2014 年 1 月 28 日
API 版本更新
对 Streams API 版本 2013-12-02 的更新。
2013 年 12 月 12 日
首次发布
Amazon Kinesis Developer Guide首次发布。
2013 年 11 月 14 日
122
Amazon Kinesis Streams 开发人员指南
AWS 词汇表
Abstract
列出最新 AWS 术语和用法。
有关最新的 AWS 术语,请参阅 AWS General Reference中的 AWS 术语表。
123
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement