简介

tair 是淘宝自己开发的一个分布式 key/value 存储引擎. tair 分为持久化和非持久化两种使用方式. 非持久化的 tair
可以看成是一个分布式缓存. 持久化的 tair 将数据存放于磁盘中. 为了解决磁盘损坏导致数据丢失, tair 可以配置数据的备份数目,
tair 自动将一份数据的不同备份放到不同的主机上, 当有主机发生异常, 无法正常提供服务的时候, 其于的备份会继续提供服务.

tair 的总体结构

tair 作为一个分布式系统, 是由一个中心控制节点和一系列的服务节点组成. 我们称中心控制节点为config server.
服务节点是data server. config server 负责管理所有的data server, 维护data server的状态信息.
data server 对外提供各种数据服务, 并以心跳的形式将自身状况汇报给config server. config server是控制点,
而且是单点, 目前采用一主一备的形式来保证其可靠性. 所有的 data server 地位都是等价的.

tair 的负载均衡算法是什么

tair 的分布采用的是一致性哈希算法, 对于所有的key, 分到Q个桶中, 桶是负载均衡和数据迁移的基本单位. config server
根据一定的策略把每个桶指派到不同的data server上. 因为数据按照key做hash算法, 所以可以认为每个桶中的数据基本是平衡的.
保证了桶分布的均衡性, 就保证了数据分布的均衡性.

增加或者减少data server的时候会发生什么

当有某台data server故障不可用的时候, config server会发现这个情况, config
server负责重新计算一张新的桶在data server上的分布表, 将原来由故障机器服务的桶的访问重新指派到其它的data server中.
这个时候, 可能会发生数据的迁移. 比如原来由data server A负责的桶, 在新表中需要由 B负责. 而B上并没有该桶的数据,
那么就将数据迁移到B上来. 同时config server会发现哪些桶的备份数目减少了, 然后根据负载情况在负载较低的data
server上增加这些桶的备份. 当系统增加data server的时候, config server根据负载, 协调data
server将他们控制的部分桶迁移到新的data server上. 迁移完成后调整路由. 当然, 系统中可能出现减少了某些data
server 同时增加另外的一些data server. 处理原理同上. 每次路由的变更, config
server都会将新的配置信息推给data server. 在客户端访问data server的时候, 会发送客户端缓存的路由表的版本号.
如果data server发现客户端的版本号过旧, 则会通知客户端去config server取一次新的路由表. 如果客户端访问某台data
server 发生了不可达的情况(该 data server可能宕机了), 客户端会主动去config server取新的路由表.

发生迁移的时候data server如何对外提供服务

当迁移发生的时候, 我们举个例子, 假设data server A 要把 桶 3,4,5 迁移给data server B. 因为迁移完成前,
客户端的路由表没有变化, 客户端对 3, 4, 5 的访问请求都会路由到A. 现在假设 3还没迁移, 4 正在迁移中, 5已经迁移完成.
那么如果是对3的访问, 则没什么特别, 跟以前一样. 如果是对5的访问, 则A会把该请求转发给B,并且将B的返回结果返回给客户,
如果是对4的访问, 在A处理, 同时如果是对4的修改操作, 会记录修改log.当桶4迁移完成的时候, 还要把log发送到B,
在B上应用这些log. 最终A B上对于桶4来说, 数据完全一致才是真正的迁移完成. 当然, 如果是因为某data
server宕机而引发的迁移, 客户端会收到一张中间临时状态的分配表. 这张表中, 把宕机的data
server所负责的桶临时指派给有其备份data server来处理. 这个时候, 服务是可用的, 但是负载可能不均衡. 当迁移完成之后,
才能重新达到一个新的负载均衡的状态.

桶在data server上分布时候的策略

程序提供了两种生成分配表的策略, 一种叫做负载均衡优先, 一种叫做位置安全优先: 我们先看负载优先策略. 当采用负载优先策略的时候,
config server会尽量的把桶均匀的分布到各个data server上. 所谓尽量是指在不违背下面的原则的条件下尽量负载均衡. 1
每个桶必须有COPY_COUNT份数据 2 一个桶的各份数据不能在同一台主机上; 位置安全优先原则是说, 在不违背上面两个原则的条件下,
还要满足位置安全条件, 然后再考虑负载均衡. 位置信息的获取是通过 _pos_mask(参见安装部署文档中关于配置项的解释) 计算得到.
一般我们通过控制 _pos_mask 来使得不同的机房具有不同的位置信息. 那么在位置安全优先的时候, 必须被满足的条件要增加一条,
一个桶的各份数据不能都位于相同的一个位置(不在同一个机房). 这里有一个问题, 假如只有两个机房, 机房1中有100台data server,
机房2中只有1台data server. 这个时候, 机房2中data server的压力必然会非常大. 于是这里产生了一个控制参数
_build_diff_ratio(参见安装部署文档). 当机房差异比率大于这个配置值时, config server也不再build新表.
机房差异比率是如何计出来的呢? 首先找到机器最多的机房, 不妨设使RA, data server数量是SA. 那么其余的data
server的数量记做SB. 则机房差异比率=|SA – SB|/SA. 因为一般我们线上系统配置的COPY_COUNT是3. 在这个情况下,
不妨设只有两个机房RA和RB, 那么两个机房什么样的data server数量是均衡的范围呢? 当差异比率小于
0.5的时候是可以做到各台data server负载都完全均衡的.这里有一点要注意, 假设RA机房有机器6台,RB有机器3台. 那么差异比率 =
6 – 3 / 6 = 0.5. 这个时候如果进行扩容, 在机房A增加一台data server, 扩容后的差异比率 = 7 – 3 / 7 =
0.57. 也就是说, 只在机器数多的机房增加data server会扩大差异比率.
如果我们的_build_diff_ratio配置值是0.5. 那么进行这种扩容后, config server会拒绝再继续build新表.

tair 的一致性和可靠性问题

分布式系统中的可靠性和一致性是无法同时保证的, 因为我们必须允许网络错误的发生. tair 采用复制技术来提高可靠性,
并且为了提高效率做了一些优化, 事实上在没有错误发生的时候, tair 提供的是一种强一致性. 但是在有data server发生故障的时候,
客户有可能在一定时间窗口内读不到最新的数据. 甚至发生最新数据丢失的情况.

tair提供的客户端

tair 的server端是C++写的, 因为server和客户端之间使用socket通信,
理论上只要可以实现socket操作的语言都可以直接实现成tair客户端. 目前实际提供的客户端有java 和 C++.
客户端只需要知道config server的位置信息就可以享受tair集群提供的服务了.

主要的性能数据

待补充

Tair用户指南

本文档介绍了Tair客户端的工作原理，以及Java和c++客户端的使用方法和接口介绍。

工作原理

Tair是一个分布式的key/value存储系统，数据往往存储在多个数据节点上。客户端需要决定数据存储的具体节点，然后才能完成具体的操作。

Tair的客户端通过和configserver交互获取这部分信息。configserver会维护一张表，这张表包含hash值与存储其对应数据的节点的对照关系。客户端在启动时，需要先和configserver通信，获取这张对照表。

在获取到对照表后，客户端便可以开始提供服务。客户端会根据请求的key的hash值，查找对照表中负责该数据的数据节点，然后通过和数据节点通信完成用户的请求。

支持的客户端

Tair当前支持Java http://baike.corp.taobao.com/index.php/GetClient和c++语言的客户端。

java客户端使用指南

java版本兼容性

Tair的java客户端需要JDK 1.5或与其兼容的环境。我们使用Sun公司的JDK 1.5在 Linux和Windows上测试过。

依赖

Tair客户端使用mina（  http://mina.apache.org/ ）通信框架与Tair server通信，所以使用Tair java客户端需要确保运行环境中包含mina的jar包以及其依赖的库，mina请使用1.1.x的版本。

配置java客户端

支持的配置项

初始化Java客户端

// 创建config server列表
List<String> confServers = new ArrayList<String>();
confServers.add("CONFIG_SERVER_ADDREEE:PORT");
confServers.add("CONFIG_SERVER_ADDREEE_2:PORT"); // 可选

// 创建客户端实例
DefaultTairManager tairManager = new DefaultTairManager();
tairManager.setConfigServerList(confServers);

// 设置组名
tairManager.setGroupName("GROUP_NAME");
// 初始化客户端
tairManager.init();

如果你的系统使用spring，那么可以使用类似下面的bean配置：

<bean id="tairManager" class="com.taobao.tair.impl.DefaultTairManager" init-method="init">
        <property name="configServerList">
                <list>
                        <value>CONFIG_SERVER_ADDREEE:PORT</value>
                        <value>CONFIG_SERVER_ADDREEE_2:PORT</value> <!-- 可选 -->
                </list>
        </property>
        <property name="groupName">
                <value>GROUP_NAME</value>
        </property>
</bean>

接口介绍

预备知识

由于Tair中的value除了用户的数据外，好包括version等元信息。所以返回的用户数据将和元数据一起封装在DataEntry对象中。

Tair客户端的所有接口都不抛出异常，操作的结果状态使用ResultCode表示。如果接口会返回数据，则返回的数据和ResultCode一起封装在Result中。

Result和ResultCode都包含有isSuccess方法，如果该方法返回true，则表示请求成功（当get的数据不存在时，该方法也返回 true）。

基本接口

• get接口

get接口用于获取单个数据，要获取的数据由namespace和key指定。

当数据存在时，返回成功，数据存放在DataEntry对象中；

当数据不存在时，返回成功，ResultCode为ResultCode.DATANOTEXSITS，value为null。

示例：

Result<DataEntry> result = tairManager.get(namespace, key);
if (result.isSuccess()) {
    DataEntry entry = result.getValue();
    if(entry != null) {
        // 数据存在
    } else {
        // 数据不存在
    }
} else {
    // 异常处理
}

• mget接口

mget接口用于批量获取同一个namespace中的多个key对应的数据集合。mget在客户端将key列表根据key所在的服务器分组，然后将分组后的key列表发送到对应的服务器上，发送到多个服务器这个步骤是异步的，所以需要的时间不是线性的。

当得到返回结果时

• 如果返回的个数为0，ResultCode为ResultCode.DATANOTEXSITS
• 如果返回的个数小于请求的个数，ResultCode为ResultCode.PARTSUCC
• 全部返回，则返回成功

当有数据返回时，Result对象中的value是一个List<DataEntry>，这个List包含了所有取到的数据，每个 DataEntry都会包括请求的key，返回的value和version信息。

• put接口

put接口有3个签名，分别为：

ResultCode put(int namespace, Serializable key, Serializable value); // version为0，即不关心版本；expireTime为0，即不失效
ResultCode put(int namespace, Serializable key, Serializable value, int version); // expireTime为0，即不失效
ResultCode put(int namespace, Serializable key, Serializable value, int version, int expireTime);

示例：

ResultCode rc = tairManager.put(namespace, key, value);
if (rc.isSuccess()) {
    // put成功
} else if (ResultCode.VERERROR.equals(rc) {
    // 版本错误的处理代码
} else {
    // 其他失败的处理代码
}

// version应该从get返回的DataEntry对象中获取
// 出给使用0强制更新，否则不推荐随意指定版本
rc = tairManager.put(namespace, key, value, version);

// 使用全参数版本的put
rc = tairManager.put(namespace, key, value, version, expireTime);

• delete接口

delete接口用于删除有namespac和key指定的value。如果请求删除的key不存在，tair也将返回成功。

示例：

// 使用删除接口
ResultCode rc = tairManager.delete(namespace, key);
if (rc.isSuccess()) {
    // 删除成功
} else {
    // 删除失败
}

• mdelete接口

mdelete接口用于批量删除数据，该接口只能删除同一个namespace中的多条数据。其工作原理和mget接口类似。

示例：

// 使用批量删除接口
ResultCode rc = tairManager.mdelete(namespace, keys);
if (rc.isSuccess()) {
    // 删除成功
} else {
    // 部分成功处理代码
}

• incr接口

incr和decr接口配合使用可以提供计数器的功能。使用get和put接口也能实现计数器的功能，但由于两个操作不是原子的，很多情况下这不能满足需求。所以我们提供了incr和decr接口，通过这两个接口提供原子的计数器操作。

incr接口的方法签名为： Result<Integer> incr(int namespace, Serializable key, int value, int defaultValue, int expireTime);

接口参数的含义为：

示例：

Result<Integer> result = tairManager.incr(namespace, key, 1, 0);
if (result.isSuccess()) {
    int rv = result.getValue(); // 这里是1
} else {
    // 错误处理
}

// 将返回4
result = tairManager.incr(namespace, key, 3, 0);

// 将返回2
result = tairManager.decr(namespace, key, 2, 0);

• item接口

item接口是对原有key/value接口的扩充，item接口将value视为一个数组，配合服务器端的支持，可以完成以下操作：

• 向item末尾添加新的items
• 获取指定范围的items
• 删除指定范围的items
• 获取并删除指定范围的items
• 获取item的个数

Item接口内部使用json格式，只支持基本类型，包括：

• String
• Long
• Integer
• Double

同一个Value中的类型需要保持一致，否则将返回序列化错误。

每个item可以指定maxcount，当item的条数操作指定的maxcount是，服务器将自动删除最早插入的item。

List<Integer> intList = new ArrayList<Integer>();
intList.add(1);
intList.add(2);

// 添加新的itmes
ResultCode rc = tairManager.addItems(1, key, intList, 50, 0, 0);

// 获取item的总条数
Result<Integer> ic = tairManager.getItemCount(1, key);
int totalCount = ic.getValue();

// 获取所有items
Result<DataEntry> rets = tairManager.getItems(1, key, 0, totalCount);

// 获取第一个item，并将其从系统中删除
rets = tairManager.getAndRemove(1, key, 0, 1);

C++客户端使用指南

数据操作接口

put
get
remove

incr
decr

初始化(连接到tair)

startup

清理

close

超时时间设置

setTimeout
超时时间意味着客户端对单个请求的最大等待时间，即当客户端发出一个请求后在该时间内还未收到服务端的回应即返回超时。
各个接口的参数详见头文件。

使用流程

CTAIRClinetAPI *tairClient = new CTAIRClientAPI();
assert(tairClient != 0);
if ( !tairClient->startup(configserver_master,configserver_slave,group_name)){
    //没连上，处理错误
}

tairClinet->put(...);
tairClient->get(...);
......

delete tairClient;

or


CTAIRClientAPI tairClient;
tairClient.startup();

//put
//get
//etc.

tairClient.close(); //可选，析构时会自动清理

对几个常见的Tair错误码做一个简要的解释

0, "success"

1, -3998 "data not exist" 数据不存在

-3988, "data expired" 数据过期，由于tair的数据删采用的是lazy
delete，也就是删除的数据不会马上做物理删除，而是逻辑上无法读到，所以有时候过期数据也可能返回data not
exist，新版本统一成了返回data not exist。

-1, "connection error or timeout" -3989, "timeout" 超时。

-3997, "version error" 版本错误，tair操作中的版本相当于一种乐观锁的机制，参见

-3994, "serialize error"
被问到次数最多的错误。。。Tair存储的key和value都必须是可序列化的对象，如果是String
，integer等基本类型就会按照java的序列化方式进行序列化，如果是自定义的对象，需要继承Serializable，出现这种错误一般是一个应
用put了一个自定义的对象，另外一个应用找不到这个类的定义，或者put后对对象进行了修改导致。

-3984, "migrate busy" tair的迁移的过程要保证仍然对外提供服务，因此迁移过程会分成很多轮，当迁移过程中的数据增量小到一定的阈值后，会有很小的一段时间停止写服务，这是就会返回migrate busy，稍稍过几秒钟重试应该就可以成功。

-3986, "write not on master"
操作没有发生在主桶上，这一般是拿到了错误的或者过时的对照表，当集群状态发生变化时，client拿着老的对照表读写数据可能会出现这个错误，然后
client就会去config
server获取新的对照表，因此如果有节点的变化（扩容或者节点当机下线）短暂出现这个错误是可以理解，如果一直报这个错误可能是服务端配置不正确。

-5, "key length error" -6, "value length error" key不能超过1K value不能超过1M

-20008, "not support"
不支持的操作，一般是Tair客户端的版本和服务器版本不匹配，不同的存储引擎支持的操作也有所不同.

TAIR命令说明

• ./tairclient
• 说明：输出如下帮助信息
  

        ./tairclient -c configserver:port -g groupname
            -c, --configserver     	default port: 5198
            -g, --groupname        	group name
            -l, --cmd_line         	exec cmd
            -q, --cmd_file         	script file
            -h, --help             	print this message
            -v, --verbose         	print debug info
            -V, --version        	print version
  

• ./tairclient –c configserver:port –g groupname
• 说明：连接到指定的configserver，同时连接到指定的dataserver。 如：“./tairclient –c 
  192.168.0.15 –g group_1” 或者 “./tairclient –c 192.168.0.15:6155 –g 
  group_1”
• configserver：configserver所在机器的ip号
• port: configerserver.conf中配置的IP端口号，即configserver那台机器开启的端口号。
• groupname: group.conf文件中配置的group name

• ./tairclient -V
• 说明：查看版本信息

• ./tairclient –c configserver:port –g groupname –v
• 说明：按照上述命令连接后，在进行put以及get操作的时候，每次都会打印一些调试的信息。

• ./tairclient –h
• 说明：打印帮助信息（和./tairclient命令的效果一样）

• ./tairclient –c configserver:port –g groupname –l cmd_line
• 说明：在-l之后直接添加命令，实现put、get等。如“./tairclient –c 192.168.0.15 –g 
  group_1 “put key data””。“./tairclient –c 192.168.0.15 –g group_1 “get 
  key ””。

• ./tairclient –c configserver:port –g groupname –q cmd_file
• 说明：将命令写进文件，然后在连接的时候通过指定命令所在的文件来执行所需的命令。如“./tairclient –c 192.168.0.15 –g group_1 –q cmdfile.txt”。

• 在TAIR>提示符下：
• help
• 作用：输出帮助信息
• 说明：输出如下帮助信息
  

  ------------------------------------------------
  SYNOPSIS   : put key data [area] [expired]
  DESCRIPTION: area   - namespace , default: 0
  expired- in seconds, default: 0,never expired
  ------------------------------------------------
  SYNOPSIS   : incr key [count] [initValue] [area]
  DESCRIPTION: initValue , default: 0
  ------------------------------------------------
  SYNOPSIS   : get key [area]
  ------------------------------------------------
  SYNOPSIS   : remove key [area]
  ------------------------------------------------
  SYNOPSIS   : stat
  DESCRIPTION: get stat info
  ------------------------------------------------
  SYNOPSIS   : delall area
  DESCRIPTION: delete all data of [area]
  ------------------------------------------------
  SYNOPSIS   : dump dumpinfo.txt
  DESCRIPTION: dumpinfo.txt is a config file of dump,syntax:
  area start_time end_time,eg:10 2008-12-09 12:08:07 2008-12-10 12:10:00
  

• 在TAIR>提示符下 put
• 作用：将(key,data)存至DataServer上。
• 说明：输出如下帮助信息
  

  SYNOPSIS   : put key data [area] [expired]
  DESCRIPTION: area   - namespace , default: 0
  expired- in seconds, default: 0,never expired
  

• area: 可以通过该选项指定不同的命名空间，以int型指定，范围在0~1024之间（包括1024），默认情况下为0。
• expired: 数据在DataServer中存放的期限，单位秒，在有效期内对相应key进行get可以得到对应的数据，过了有效期后，对相应的key进行get将失败，提示数据过期，默认情况为0，表示一直有效。

• 在TAIR>提示符下 get
• 作用：根据key值获取对应的数据
• 说明：输出如下帮助信息。
  

  SYNOPSIS : get key [area]
  key: 希望获取的数据对应的key值
  area：指定命名空间，获取数据时将到相应的命名空间下取数据，默认为0。
  

• 在TAIR>提示符下incr
• 作用：增加计数
• 说明：输出如下帮助信息
  

  SYNOPSIS   : incr key [count] [initValue] [area]
  DESCRIPTION: initValue , default: 0
  

• count: 本次增加的数量
• initValue:当计数器不存在时的初始化值
• area: 指定命名空间，默认为0。

• 在TAIR>提示符下 stat
• 作用：输出一些统计信息。
• 说明：输出一些状态信息，包括DataServer上的不同命名空间的一些统计信息，如get、put的次数，占据空间的大小等。

• 在TAIR>提示符下 remove
• 作用：移除指定的(key,data)
• 说明：输出如下帮助信息
  

  SYNOPSIS   : remove key [area]
  key: 	指定想要移除的key。
  area:	指定某个命名空间，默认值为0。
  

• 在TAIR>提示符下 delall area
• 作用：移除指定的命名空间的全部内容。
• 说明：area: 指定的命名空间的值。

• ./tair_cfg_svr
• 说明：输出如下信息
  

  -f, --config_file  config file
  -h, --help         this help
  -V, --version      version
  -f  config_file：指定configserver的配置文件
  -h:	   		 输出上述帮助信息
  -V：			 输出版本信息
  

• ./tair_server
• 说明：输出如下信息
  

  -f, --config_file  config file name
  -h, --help         display this help and exit
  -V, --version      version and build time
  -f config_file：指定DataServer的配置信息
  -h:			输出上述帮助信息
  -V：			输出版本信息
  

• ./parameter_printer
• 说明：输出一些参数的设置，如key的最大长度，area的最大值等。

• ./stat_info_test
• 说明：测试系统的状态是否正常。

• ./cst_monitor
• 说明：找到configserver里的桶分配表，将其二进制文件转换成txt文件并输出。如“./cst_monitor ../configserverdir/data/group_1_server_table”。

• ./cst_transfer
• 说明：用法和./cst_monitor相反，将txt格式的信息转换成二进制的信息。

• ./sif_monitor
• 说明：打印出configerserver的信息。如“./sif_monitor ../configserverdir/data/server_info.0”。