JindoDistCp使用说明 - 开源大数据平台E-MapReduce

本文为您介绍如何使用JindoDistCp。

什么是JindoDistCp

JindoDistCp是阿里云数据湖存储团队开发的大规模集群内部和集群之间分布式文件拷贝的工具。其使用MapReduce实现文件分发、错误处理和恢复，把文件和目录的列表作为MapReduce任务的输入，每个任务会完成源列表中部分文件的拷贝。目前全量支持HDFS、OSS-HDFS、OSS和S3之间的数据拷贝场景，提供多种个性化拷贝参数和多种拷贝策略。重点优化HDFS到OSS-HDFS的数据拷贝，通过定制化CopyCommitter，实现No-Rename拷贝，并保证数据拷贝落地的一致性。功能全量对齐S3 DistCp和HDFS DistCp，性能较HDFS DistCp有较大提升，致力于提供高效、稳定、安全的数据拷贝工具。

环境要求

JDK 1.8.0及以上。
Hadoop 2.3+版本，请下载最新版的jindo-distcp-tool-x.x.x.jar，该JAR包含在jindosdk-${version}.tar.gz内，解压缩后可在tools/目录下找到，单击进入JindoData下载。
说明
EMR-5.6.0及以上版本、EMR-3.40.0及以上版本的集群已部署JindoDistCp，可在/opt/apps/JINDOSDK/jindosdk-current/tools目录下找到jindo-distcp-tool-x.x.x.jar。

参数说明

JindoDistCp提供JAR包形式使用，您可以使用hadoop jar命令配合一系列参数来完成迁移操作。

参数	参数类型	说明	默认值	版本	OSS	OSS-HDFS
--src	必选	设置源目录，支持的前缀有： hdfs:// oss:// s3:// cos:// obs://	无	4.3.0+	支持	支持
--dest	必选	设置目标目录，支持的前缀有： hdfs:// oss:// s3:// cos:// obs://	无	4.3.0+	支持	支持
--bandWidth	可选	设置单个节点的带宽限制，单位：MB。	-1	4.3.0+	支持	支持
--codec	可选	设置压缩类型，支持的编解码器包括 gzip、gz、lzo、lzop和snapp。	keep（不更改压缩类型）	4.3.0+	支持	支持
--policy	可选	设置目标存储策略，支持Standard、IA、Archive、ColdArchive。	Standard	4.3.0+	支持	不支持
--filters	可选	设置包含过滤规则的文件。	无	4.3.0+	支持	支持
--srcPrefixesFile	可选	设置包含符合规则的文件。	无	4.3.0+	支持	支持
--parallelism	可选	设置DistCp任务的并发度，对应MR任务中的 mapreduce.job.maps。	10	4.3.0+	支持	支持
--jobBatch	可选	设置每个distcp job处理的文件数量。	10000	4.5.1+	支持	支持
--taskBatch	可选	设置每个distcp task处理的文件数量。	1	4.3.0+	支持	支持
--tmp	可选	设置临时目录。	/tmp	4.3.0+	支持	支持
--hadoopConf <key=value>	可选	设置Configuration。	无	4.3.0+	支持	支持
--disableChecksum	可选	设置是否关闭Checksum检查。	false	4.3.0+	支持	支持
--deleteOnSuccess	可选	设置是否删除源文件，用于移动数据。	false	4.3.0+	支持	支持
--enableTransaction	可选	设置是否开启事务，以保证Job级别的原子性。	false	4.3.0+	支持	支持
--ignore	可选	设置是否忽略拷贝任务中抛出的异常，避免中断任务。	false	4.3.0+	支持	支持
--enableCMS	可选	是否开启监控告警。	false	4.5.1+	支持	支持
--diff	可选	设置DistCp模式为DIF，查看src和dest的文件差异。	DistCpMode.COPY	4.3.0+	支持	支持
--update	可选	设置DistCp模式为UPDATE，指定增量同步功能，跳过完全相同的文件和目录，直接将src中新增或发生改变的文件和目录同步到dest上。	DistCpMode.COPY	4.3.0+	支持	支持
--preserveMeta	可选	设置是否开启保存元数据信息。	false	4.4.0+	不支持	支持

--src和--dest（必选）

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--src：表示指定源文件的路径。
--dest：表示目标文件的路径。

示例命令如下：

hadoop jar jindo-distcp-tool-${version}.jar --src /data/hourly_table  --dest oss://example-oss-bucket/hourly_table

您可以通过指定dest路径来确定拷贝后的文件目录。如果您需要将/data/hourly_table下的文件拷贝到example-oss-bucket这个bucket下的hourly_table目录下，则可以使用上述语句来完成。此处和Hadoop的DistCp行为有所不同，JindoDistCp会默认将src目录下的所有文件拷贝到您指定dest路径下，并不包括当前的根目录名称。您可以在dest中指定拷贝路径的根目录，如果不存在会自动创建。

如果您需要拷贝单个文件，dest需指定为目录。

hadoop jar jindo-distcp-tool-${version}.jar --src /test.txt --dest oss://example-oss-bucket/tmp

使用--bandWidth

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--bandWidth：表示本次distcp任务所用的单机带宽（单位：MB），避免单机占用过大带宽。

示例命令如下：

jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --bandWidth 6

使用--codec

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

原始文件通常以未压缩的文本格式进入OSS或OSS-HDFS。无论是存储成本还是对该数据进行分析，此格式都不太理想。JindoDistCp可以使用--codec选项帮助您在线高效地存储数据和压缩文件。

--codec用来指定文件压缩编解码器，支持gzip、gz、lzo、lzop和snappy编码器以及关键字none和keep（默认值）。关键字含义如下：

none：保存为未压缩的文件。如果文件已压缩，则JindoDistCp会将其解压缩。
keep（默认值）：不更改文件压缩形态，按原样复制。

示例命令如下：

jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --codec gz

命令执行后，检查目标文件夹中的文件。可以看到这些文件现在已经使用gz编解码器压缩了。

[root@emr-header-1 opt]# hdfs dfs -ls oss://example-oss-bucket/hourly_table/2017-02-01/03
Found 6 items
-rw-rw-rw-   1        938 2020-04-17 20:58 oss://example-oss-bucket/hourly_table/2017-02-01/03/000151.sst.gz
-rw-rw-rw-   1       1956 2020-04-17 20:58 oss://example-oss-bucket/hourly_table/2017-02-01/03/1.log.gz
-rw-rw-rw-   1       1956 2020-04-17 20:58 oss://example-oss-bucket/hourly_table/2017-02-01/03/2.log.gz
-rw-rw-rw-   1       1956 2020-04-17 20:58 oss://example-oss-bucket/hourly_table/2017-02-01/03/OPTIONS-000109.gz
-rw-rw-rw-   1        506 2020-04-17 20:58 oss://example-oss-bucket/hourly_table/2017-02-01/03/emp01.txt.gz
-rw-rw-rw-   1        506 2020-04-17 20:58 oss://example-oss-bucket/hourly_table/2017-02-01/03/emp06.txt.gz

说明

如果您想在开源Hadoop集群环境中使用编解码器lzo，则需要安装gplcompression的native库和hadoop-lzo包。如果您缺少相关环境，建议使用其他压缩方式进行压缩。

使用--filters

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--filters：指定有过滤规则的文件。

示例命令如下：

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --filters filter.txt

假设filter.txt的内容如下为.*test.*，则不会将路径中带有test字符的文件拷贝到OSS。

使用--srcPrefixesFile

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--srcPrefixesFile：指定有符合规则的文件。

示例命令如下：

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --srcPrefixesFile prefixes.txt

假设prefixes.txt的内容为.*test.*，则只有路径中带有test字符的文件才会拷贝到OSS。

使用--parallelism

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--parallelism：指定MapReduce任务里的mapreduce.job.maps参数，该参数在E-MapReduce环境中默认为10，您可以根据集群的资源情况自定义parallelism的大小来控制distcp任务的并发度。

示例命令如下：

 jindo-distcp-tool-${version}.jar --src /opt/tmp --dest oss://example-oss-bucket/tmp --parallelism 20

使用--taskBatch

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--taskBatch：指定每个distcp task处理的文件数量，默认为1。

示例命令如下：

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --taskBatch 1

使用--tmp

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--tmp：指定一个临时目录在hdfs上传存放临时数据，默认值为/tmp，即hdfs:///tmp/。

示例命令如下：

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table  --tmp /tmp

配置访问OSS/OSS-HDFS的AccessKey

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--hadoopConf：在E-MapReduce外或免密服务出现问题的情况下，您可以通过指定AccessKey来获得访问OSS/OSS-HDFS服务的权限。您可以在命令中使用--hadoopConf选项来指定AccessKey。

示例命令如下：

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --hadoopConf fs.oss.accessKeyId=yourkey --hadoopConf fs.oss.accessKeySecret=yoursecret

您也可以将OSS/OSS-HDFS服务的AccessKey ID和AccessKey Secret预先配置在Hadoop的core-site.xml文件里，避免每次使用时临时填写AccessKey。您可以在EMR控制台Hadoop-Common服务的core-site.xml页面添加如下配置。

<configuration>
    <property>
        <name>fs.oss.accessKeyId</name>
        <value>xxx</value>
    </property>

    <property>
        <name>fs.oss.accessKeySecret</name>
        <value>xxx</value>
    </property>
</configuration>

使用--disableChecksum

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--disableChecksum：关闭检查文件checksum。

示例命令如下：

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --disableChecksum

使用--deleteOnSuccess

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--deleteOnSuccess：指定移动数据而不是复制数据。此选项类似于mv操作，首先复制文件，然后从源位置删除文件。

示例命令如下：

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --deleteOnSuccess

使用--enableTransaction

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--enableTransaction：JindoDistCp默认使用Task级别完整性，如果您需要保证Job级别的完整性以及保证Job之间的事务支持，您可以使用该参数指定。

示例命令如下：

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --enableTransaction

使用--ignore

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--ignore：指定有符合规则的文件。忽略数据迁移期间发生的异常，相关报错不会中断任务，并最终以JindoCounter的形式透出（如果开启CMS，也会以指定方式进行通知）。

示例命令如下：

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --ignore

使用--diff

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--diff：查看src和dest的文件差异。如果src的文件未能同步到dest上，则会在当前目录下生成一个包含文件内容差异的文件。如果您的JindoDistCp任务包含压缩或者解压缩，则--diff不能显示正确的文件差异，因为压缩或者解压缩会改变文件的大小。

示例命令如下：

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --diff

如果文件有差异，则会在当前目录下生成一个包含文件内容差异的文件，并会提示如下信息：

JindoCounter
DIFF_FILES=1

如果您的--dest为HDFS路径，现支持/path、hdfs://hostname:ip/path、hdfs://headerIp:ip/path的写法，暂不支持hdfs:///path、hdfs:/path和其他自定义写法。

如果您想查看文件元数据的差异，您可以使用--diff --preserveMeta命令：

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --diff --preserveMeta

使用--update

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	支持

--update：指定增量同步功能，跳过完全相同的文件和目录，直接将src中新增或发生改变的文件和目录同步到dest上。

如果JindoDistCp任务因为各种原因中间失败了，而此时您想进行断点续传，只复制剩下未复制成功的文件，或者源端文件新增了部分文件，此时需要您在上一次JindoDistCp任务完成后指定该参数。

示例命令如下：

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --update

使用冷归档/归档/低频写入OSS

版本	OSS	OSS-HDFS
4.3.0及以上版本	支持	不支持

--policy：指定以冷归档、归档和低频的模式写入OSS，进行数据存储。如果不指定，则默认以standard标准模式写入，不进行冷归档、归档和低频操作。

使用冷归档写入OSS（coldArchive）
目前只在部分地域可用，具体请参见OSS存储类型介绍。使用示例命令如下：
```
 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-bucket/hourly_table --policy coldArchive --parallelism 20
```

使用归档写入OSS（archive）

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-bucket/hourly_table --policy archive --parallelism 20

使用低频写入OSS（ia）

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-bucket/hourly_table --policy ia --parallelism 20

使用--preserveMeta

版本	OSS	OSS-HDFS
4.4.0及以上版本	不支持	支持

--preserveMeta：指定迁移数据的同时迁移包括Owner、Group、Permission、Atime、Mtime、Replication、BlockSize、XAttrs和ACL在内的元数据信息。

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --preserveMeta

使用--jobBatch

版本	OSS	OSS-HDFS
4.5.1及以上版本	支持	支持

--jobBatch：在您的distcp任务写入OSS时，您可以通过--jobBatch来指定每个distcp job处理的文件数量，默认为10000。

 jindo-distcp-tool-${version}.jar --src /data/hourly_table --dest oss://example-oss-bucket/hourly_table --jobBatch 50000

使用--enableCMS

版本	OSS	OSS-HDFS
4.5.1及以上版本	支持	支持

--enableCMS：开启云监控告警功能。

JindoDistCp Counters

JindoDistCp Counters信息汇总了JindoDistCp执行的结果。信息内容如下表所示。

参数	说明
COPY_FAILED	拷贝失败的文件数。
CHECKSUM_DIFF	Checksum校验失败的文件数，并计入COPY_FAILED。
FILES_EXPECTED	预期的拷贝的文件数。
BYTES_EXPECTED	预期的拷贝的字节数。
FILES_COPIED	拷贝成功的文件数。
BYTES_COPIED	拷贝成功的字节数。
FILES_SKIPPED	增量更新时跳过的文件数。
BYTES_SKIPPED	增量更新时跳过的字节数。
DIFF_FILES	源路径与目标路径下不相同的文件数。
SAME_FILES	源路径与目标路径下完全相同的文件数。
DST_MISS	目标路径不存在的文件数，并计入DIFF_FILES。
LENGTH_DIFF	源文件和目标文件大小不一致的数量，并计入DIFF_FILES。
CHECKSUM_DIFF	Checksum校验失败的文件数，并计入DIFF_FILES。
DIFF_FAILED	文件比较操作异常的文件数。