KeyDB是Redis的替代品，宣称是世界上最快的NoSQL数据库，比Redis快5倍。KeyDB完全遵循Redis的协议，可以无缝的从Redis切换。

KeyDB支持多主复制、跨Region的水平扩容，支持垂直扩容。

KeyDB支持多个保持同步的主节点，这些主节点都可以接受读、写请求。主节点可以括Region分布。不需要哨兵节点进行监控。

KeyDB通过MVCC实现无锁（不需等待）的并发操作、后台保存。

得益于KeyDB的MVCC支持：

1. 事务、查询是非阻塞（不会有锁）的，同时具有原子性保证
2. 未来将支持事务回滚

KeyDB是完全的多线程的，不像Redis那样仅仅在I/O上支持并发，这意味着它可以充分利用多核心。

这个特性让KeyDB的吞吐量比Redis 5大5倍，Redis 6大3倍。再启用TLS的情况下，吞吐量可以比Redis大7倍。

多线程特性让KeyDB能最大化利用单机能力，这意味着通过配置能实现水平扩容。

单个KeyDB能够充分利用10（不使用TLS）-16（使用TLS）核心。

支持将一个set中的所有键一起过期，过期时的删除操作是接近实时完成的，不会有延迟。

可以很好的在ARM体系结构下运行。

sudo curl -s --compressed -o /etc/apt/trusted.gpg.d/keydb.gpg https://download.keydb.dev/keydb-ppa/keydb.gpg
sudo curl -s --compressed -o /etc/apt/sources.list.d/keydb.list https://download.keydb.dev/keydb-ppa/keydb.list
sudo apt update
sudo apt install keydb

wget https://download.keydb.dev/packages/deb/ubuntu16.04_xenial/amd64/keydb-latest/keydb-tools_6.0.16-1~xenial1_amd64.deb
sudo dpkg -i keydb-tools_6.0.16-1~xenial1_amd64.deb 

要启用Active Replica模式，遵循如下步骤：

1. 两个服务器A/B都需要配置

   active-replica yes

2. 在B上执行命令

   replicaof [A address] [A port]

   ，丢弃自己的数据，加载A的数据
3. 在A上执行命令

   replicaof [B address] [B port]

   ，丢弃自己的数据，加载B的数据
4. 现在两个服务器会传播自己的写操作到对方

或者完全通过配置文件：

# 节点A的配置
port 6379
# 当前节点的密码
requirepass mypassword123
# 连接到Master的密码
masterauth mypassword123
# 增加下面的
active-replica yes
# 从Redis 5.0开始，slaveof改成replicaof
replicaof 10.0.0.3 6379


# 节点B的配置
port 6379
requirepass mypassword123
masterauth mypassword123
# 增加下面的
active-replica yes
replicaof 10.0.0.2 6379

在每个节点上增加多个replicaof配置项：

# 一共有3个节点 A/B/C 10.0.0.2/3/4

# 节点A
multi-master yes
active-replica yes
replicaof 10.0.0.3 6379
replicaof 10.0.0.4 6379

# 节点B
multi-master yes
active-replica yes
replicaof 10.0.0.2 6379
replicaof 10.0.0.4 6379

# 节点C
multi-master yes
active-replica yes
replicaof 10.0.0.2 6379
replicaof 10.0.0.3 6379

创建配置文件，参考：

port 6379
cluster-enabled yes
cluster-config-file nodes.conf
cluster-node-timeout 5000
appendonly yes

dir ./
loglevel notice
logfile keydb.log

save 900 1
save 300 10
save 60 10000

启动实例，参考：

keydb-server keydb.conf

所有实例启动后，使用如下命令创建集群：

keydb-cli --cluster create 10.0.0.1:6379   10.0.0.2:6379 ... --cluster-replicas 1

后续可以使用如下命令添加新的节点：

# 作为新的Master加入
#                            新节点           通过谁连接到既有集群
keydb-cli --cluster add-node 10.0.0.11:6379  10.0.0.1:6379

# 自动作为副本少的Master的Slave
keydb-cli --cluster add-node 10.0.0.11:6379 10.0.0.1:6379 --cluster-slave

# 强制指定Master
keydb-cli --cluster add-node 10.0.0.11:6379 10.0.0.1:6379 --cluster-slave --cluster-master-id 3c3a0c74aae0b56170ccb03a76b60cfe7dc1912e 

通过如下命令可以进行再分片： 

keydb-cli reshard 10.0.0.11:6379 --cluster-from <node-id> --cluster-to <node-id> \
  --cluster-slots <number of slots> --cluster-yes

大部分配置项和Redis是相通的，参考Redis学习笔记。这里仅仅列出Redis新版本增加 / KeyDB特有的配置项。

通过复制（Replication），一个KeyDB节点可以保证自己的数据集和和Master(s)实例一致：

1. 当Slave和Master之间的连接良好时，Master通过发送写、键过期、键驱除等操作的数据流给Slave来保证Slave的数据和自己一致
2. 当网络断开后，Slave会尝试重新连接到Master，并进行增量同步
3. 如果增量同步无法实现（落后太远），Slave会请求进行全量同步。Master会创建它的数据集的快照，发送给Slave，然后继续发送增量的数据流

关于KeyDB的复制机制，你需要知道以下事实：

1. KeyDB默认使用异步的同步方式，这种方式的优势时延迟低、性能高。Slave会在接收了一定量的复制数据之后，向Master发送Ack。类似于Redis，使用WAIT命令可以确保特定的数据被多个Slave所Ack。WAIT命令并不能保证CAP中的CP —— 已经Ack的写操作，仍然可能在故障转移时丢失，尽管几率很小
2. 每个Master可以对应多个Slaves
3. Slave可以有自己的Slaves，参与复制的KeyDB节点可以形成树状拓扑
4. 在Master侧，复制是非阻塞的。不管是增量/全量同步，都不影响Master继续处理查询
5. 在Slave侧，复制很大程度上也是非阻塞的：
   1. 通过配置，KeyDB可以在接收初始同步时使用旧数据集提供服务。你也可以配置，当复制流宕掉的情况下，让Slave返回错误给客户端
   2. 在初始同步完毕后，有个阻塞的时间窗口，在此窗口中Slave替换旧的数据集
   3. 从4.0开始，可以配置KeyDB让删除数据集的操作在其它线程执行。但是，加载新数据集的操作仍然在主线程执行，会阻塞Slave
6. 通过复制，可以：
   1. 提升可扩容性：将缓慢的O(N)操作offload给Slave
   2. 提升数据安全性、高可用性
7. 使用复制，可以免于Master需要将数据集写入到磁盘的开销。这需要在Slave上配置高频的存盘，或者启用AOF。需要注意，这种用法下Master重启时是空数据集，如果不进行适当处理，它会导致Slave的数据集立刻变空

KeyDB支持Active Replicas（Active Active）模式，这大大简化了故障转移的处理 —— 不需要确定副本何时应该晋升。

默认情况下，KeyDB以类似Redis的方式运行，仅仅允许从Master到Replicas的单向数据复制，副本仅仅支持只读处理。启用Active Replica模式后，即使Replica到Master的连接中断，它也能够处理请求。

KeyDB在复制时，支持多主模式。 使用配置：

multi-master yes

当KeyDB连接到多个Master进行复制时，其行为和传统复制不同：

1. 多次调用replicaof命令，会为本节点添加额外的Master，而非替换掉Master
2. 同步到Masters之前，不会丢弃自己的数据
3. 将合并来自多个Masters的读写到自己的内部数据库中
4. 最后一个操作生效，也就是说，有两个Masters同时修改一个键，那么后修改的那个是实际值

到目前为止，多主特性仍然是试验性的，在偶然情况下该特性可能触发流量封包。

如果仅仅有两个实例，建议使用主主模式。

KeyDB能够处理脑裂（两个节点之间网络断开）的场景。脑裂发生时，每个节点各自接受写入操作，每个写操作被加上时间戳，当连接恢复后，主节点们合并数据，以后写入的数据为准。

这种last-win原则在KeyDB里很常见，其它的例子如下文会提到的configEpoch冲突处理。

从2.6版本开始KeyDB支持Slave的只读模式，并且默认开启。对应的选项是

slave-read-only

CONFIG SET

从2.8版本开始KeyDB支持设置：仅仅当至少有N个Slave连接到Master，此Master才允许写操作。这可以增强数据安全性，再次强调一下，任何时候都不能保证数据绝不丢失。

该特性的工作方式是：

1. KeyDB Slaves每秒PING一次Master，Ack自己处理的复制流的量
2. KeyDB Master记住每个Slave的最后一次PING的时间
3. 如果PING正常的Slave数量小于配置的值，Master停止写入

相关配置项：

1. min-slaves-to-write

   ：正常PING的Slave的最小数量

2. min-slaves-max-lag

   ：如果PING延迟大于此参数指定的秒数，认为Slave不正常

KeyDB集群的设计目标，依据重要性排列如下：

1. 高性能，支持最多1000节点规模。不使用代理、异步复制，不需要对键值进行merge操作
2. 可接受的数据安全性：集群尽可能保证连接到大部分Master节点的客户端的写操作。最小化Ack后的写操作丢失的可能性，连接到少数Master节点的客户端的写操作丢失的可能性更大
3. 可用性：当出现网络分区后，如果大部分Master节点可以连接，并且对于无法连接的Master节点们至少各有一个Slave节点可以连接，则可用性得到保证。此外，如果使用副本迁移（replicas migration），没有Slave的节点可以从Slave过多的节点夺取Slave

KeyDB集群使用异步复制，Last Failover  Wins原则意味着最后晋升的主的数据集会覆盖其它副本的数据集。由于异步复制的天然特征，这意味着总是存在丢失数据的窗口。

如果出现网络分区，连接到大部分Master所在分区的客户端，丢失数据的时间窗口比连接到少数Master所在分区的客户端要小。发生故障转移的必要条件是集群中大多数Master到某个Master的通信不可达时间超过NODE_TIMEOUT，如果网络分区在超时前恢复，不会丢失数据（被新的Master覆盖）。当连接断开超过NODE_TIMEOUT之后，如果网络分区中Master数量少于一半，则所有Master停止接受写入。

下面是连接到大多数Master的客户端丢失已经Ack数据的场景：

1. 写操作已经到达Master，应答客户端时，异步的复制尚未传播到Slave
2. Master宕机
3. 过了较长时间后，Slave晋升，它的数据集成为权威

另外一个场景：

1. Master由于网络分区不可达
2. 发生故障转移，Slave晋升
3. 旧Master网络恢复
4. 某个客户端使用过期的路由表，将数据写到Master

第二种场景的发生概率很小，需要多种巧合同时发生。

对于连接到少数Master的客户端，数据丢失的时间窗口可能较大，直到NODE_TIMEOUT之前的写入都可能丢失。

出现网络分区后，少数Master所在的分区失去可用性。 

在多数Master所在的分区，如果对于不可达的Master，至少有一个Slave也在该分区，则可用性在NODE_TIMEOUT+若干秒（Slave晋升为Master，通常需要1-2秒）后恢复。

副本迁移（replicas migration）可以提升可用性，在大多数Master分区中，如果某个Master有多余的Replica，可以迁移给（在当前分区）没有Slave的（不在当前分区的）Master。

KeyDB集群不会代理请求，只会向客户端发起重定向，让它访问匹配的键空间分片的节点。

最终客户端会得到up-to-date的集群、键空间分片-节点映射关系的信息，并且直接访问正确的节点，避免重定向。

由于通常的操作仅仅发生在单个节点上，因此可以认为N主节点的KeyDB集群的性能和单个KeyDB实例是相似的。

KeyDB集群节点提供总线进行通信，总线使用客户端端口+10000（默认16379），协议是KeyDB Cluster protocol。

在KeyDB Cluster protocol中，节点负责存储数据、集群状态（包括键到节点的映射）、发现其它节点、检测无效节点、晋升Slave节点为Master。

节点之间使用一种gossip协议来传播关于集群的信息，从而发现新节点、发送PING包来检测节点是否正常工作、同步关于集群特定状态的信号。

KeyDB Cluster Bus还用于在集群范围内传播Pub/Sub消息，协调用户发起的手工故障转移。

为了实现总线的功能，所有节点通过二进制协议KeyDB Cluster Bus连接在一起，支持1000节点需要维持百万级的TCP连接。

为了避免在节点之间交换过多的信息，KeyDB使用gossip协议 + 一种配置更新机制。这保证了消息量不会随着集群规模而指数级增长。

KeyDB集群不会代理（转发）客户端请求，它可能给出响应并触发重定向。理论上客户端可以发送请求给任何节点，并在必要时获得重定向，因此它不需要持有集群的状态信息。但是，客户端可以缓存键-节点映射，来改善性能。

节点总是接受总线端口上的连接，并且应答PONG给PING请求，即使源节点不受信任。但是对于其它消息，如果源节点不是集群成员，将全部丢弃。

节点在以下情况下，接受某个源节点作为集群成员：

1. 新节点发送

   MEET

   消息，此消息类似于PING，但是会强迫消息接受者，接纳源节点作为集群成员。仅当系统管理员执行：
   

   CLUSTER MEET ip port

   节点才会发送MEET消息

2. 通过gossip协议传递的，关于节点被加入集群的事实。如果A、B已经是集群成员，现在C新加入并且MEET了A，那么A会gossip给B，这样A、B都认可C作为成员了

总线不支持在NAT环境下，或者任何TCP被映射的环境下工作。对于Docker来说，你可能需要设置

--net=host

整个键空间被划分为16384个Hash Slots，Slot是分片的最小单位，意味着理论上集群最多有16384个主节点（实际上建议的上限是1000左右）。

集群中每个Master处理这些Slots的子集。如果没有进行中的集群再配置（reconfiguration）—— 没有正在移动的Hash Slots ——则我们称集群为stable的。稳定集群中每个Slot被单个Master节点所处理

键到Slot的映射算法是：

HASH_Slot = CRC16(key) mod 16384

使用Hash tag可以确保多个键被分配到同一个Slot，以便KeyDB集群支持multi-key操作。

如果键中包含

{...}

集群中的每个节点具有唯一的、自动生成的ID，该名称是160bit的随机数。节点会将此名称存放在配置文件中，并且一直使用相同的名称，除非：

1. 配置文件被删除
2. 执行硬重置命令

   CLUSTER RESET

节点ID用于在集群范围内唯一的标识节点，节点可以改变自己的IP地址，但是它的ID不需要改变。集群可以感知节点的IP地质变更，并使用gossip协议，通过集群总线进行重配置。

在任何节点执行

CLUSTER NODES

1. 节点IP地址:端口
2. 一系列标记位
3. 如果节点被标记为Slave，则它的Master是谁

keydb-cli cluster nodes

d1861060fe 127.0.0.1:6379 myself - 0 1318428930 1 connected 0-1364
# 节点ID   地质:端口       标记      最后PING/PONG时间   配置epoch  连接状态   Slots
3886e65cc9 127.0.0.1:6380 master - 1318428930 1318428931 2        connected 1365-2729
d289c575dc 127.0.0.1:6381 master - 1318428931 1318428931 3        connected 2730-4095

KeyDB集群允许在运行时添加、删除节点。这都潜在的意味着Hash Slot的重新平衡。和调整Hash Slot有关的命令有：

# 添加Slot，通常加入新节点时使用
CLUSTER ADDSlotS Slot1 [Slot2] ... [SlotN]
# 很少使用
CLUSTER DELSlotS Slot1 [Slot2] ... [SlotN]

# 将Slot分配给特定节点
CLUSTER SETSlot Slot NODE node

Hash Slot重新分配之后，将通过gossip协议进行配置传播（ configuration propagation ）。

SETSlot子命令还可以拆分为两条。假设我们希望将Slot 8从A迁移到B：

1. 向B发送：

   CLUSTER SETSlot Slot MIGRATING A

   。这样，B会接受所有关于Slot 8的查询，但是如果本地没有Key，则发送

   ASK

   重定向，让客户度询问A
2. 向A发送：

   CLUSTER SETSlot Slot IMPORTING B

   。这样，A会接受所有关于Slot 8的查询，但是请求必须以

   ASKING

   命令作为前导，否则MOVE重定向给Slot的负责人B

重新分片牵涉到键的迁移，这个迁移是逐步进行的 —— 不是原子的移动Slot。

这意味着，在迁移过程中，多键操作的Key，可能一部分位于节点A，一部分以及迁移到节点B。由于KeyDB集群限制多键操作仅仅牵涉单个节点（所有键位于一个Hash Slot），因此这种情况下会应答客户端以

TRYAGAIN

KeyDB客户端可以自由的向任何节点发送查询请求，节点会进行以下处理：

1. 分析查询请求是否是acceptable的 —— 要么查询仅仅牵涉一个键，要么牵涉到在同一Hash Slot中的multikey
2. 查找其内部的Slot-node映射，找到负责目标Hash Slot的节点：
   1. 如果是当前节点负责，直接处理请求
   2. 如果是其它节点负责，应答客户端以MOVED错误：
      

      GET x
      #      键所属Slot   负责处理此Slot的节点
      -MOVED 3999        127.0.0.1:6381

重定向中已经给出正确节点的信息，客户端应该（但不必须）缓存并且向正确节点发请求。

一旦重定向发生，可能潜在的Slot-node映射发生很大变化，客户端可以通过

CLUSTER NODES

CLUSTER SlotS

MOVED用于提示客户端，很明确Hash Slot永久的被另外一个服务器所处理了。

ASK重定向则是提示客户端，Hash Slot可能处于迁移过程中，我虽然负责此Slot，但是没有找到你需要的Key，你去问问原来的所有者吧。

默认情况下，Slave节点仅仅会重定向请求给处理Hash Slot的Master节点。

客户端可以使用

READONLY

当一个连接处于只读默认下时，仅当查询牵涉不被Slave的Master负责的Key（可以由于重新分片导致）时才会发送重定向。

使用命令

READWRITE

KeyDB节点持续的交换PING/PONG封包，这两种消息的差别仅仅是消息类型。PING/PONG消息也叫心跳。

通常情况下，PING会触发接受者回复PONG。但是PONG也可以用来携带重要的配置信息，并且不需要应答。这种用法可以尽快广播新的配置。

通常情况下，发送心跳时，节点会随机选择几个节点作为目标，而不是发给所有节点。这避免了随着集群规模的增大而出现消息风暴。不过，作为一个前提，节点确保在NODE_TIMEOUT / 2的时间内，至少发送一个心跳给从未沟通过（不管谁主动发送PING都可以）的节点。

即使NODE_TIMEOUT到达了，节点也会重新发起一次TCP连接，防止因为连接的问题导致误判。注意NODE_TIMEOUT必须要大于RTT。

需要注意根据集群规模来配置NODE_TIMEOUT，如果集群规模很大，而NODE_TIMEOUT又偏小，会导致大量的心跳包。

PING/PONG包和其他消息具有相同的头，该头的内容：

1. Node ID，发送节点的标识符
2. 发送节点的currentEpoch、configEpoch，这两个字段和KeyDB集群使用的分布式算法有关。Slave的configEpoch是它的Master的最后一个已知的configEpoch
3. 节点标记，提示节点是Slave还是Master，以及其他的单比特节点属性
4. 发送节点所负责的Hash Slot的位图信息，如果发送节点是Slave则发送它的Master的信息
5. 发送节点的客户端TCP端口
6. 从发送节点的角度来看，集群的状态（down/ok）
7. 对于Slave，其Master的Node ID

PING/PONG包还包括一个gossip段，其中包含发送者所认为的，集群（一部分随机的，否则消息太大，具体数量取决于集群规模）其它节点的状态。每个节点的信息包括：Node ID、IP:PORT、节点标记。这个gossip段可以用来进行故障发现、发现新节点。

故障发现（Failure Detection）用于发现这样的异常：Master/Slave不再被集群中的大部分节点可见，进而引起的Slave晋升为Master的过程。

如果无法通过晋升来解决故障，则集群进入错误状态，不再接受客户端查询请求。

通过前面的心跳机制我们了解到，每个节点都维护自己所认为的，其它节点的状态。状态表现为一系列标记，其中和故障发现有关的是：

1. PFAIL

   ，P表示Possible，即某个节点可能出故障了，但是尚未确认。如果目标节点在NODE_TIMEOUT时间范围内，从当前节点不可达，则标注为PFAIL。Master/Slave都有权标记某个节点为PFAIL

2. FAIL

   ，节点故障在固定的时间范围内被大多数Master所认可，该状态从PFAIL升级而来

前面我们了解到心跳的gossip段包含当前节点所认为的，随机的其它几个节点的状态。经过若干次心跳后，每个节点的的认知会传播到所有其它节点。当满足以下条件后，PFAIL变为FAIL：

1. 某个节点A，将节点B标记为PFAIL
2. 节点A通过心跳接收到的gossip分析集群中大部分节点关于B状态的声明
3. 如果大部分节点在

   NODE_TIMEOUT * FAIL_REPORT_VALIDITY_MULT

   的时间区间内，标记节点B为PFAIL或FAIL。那么A标记B为FAIL，并发送

   FAIL

   消息给所有可达节点
4. FAIL消息会导致所有接收节点都将节点B标记为FAIL，不管它是不是认为B处于PFAIL状态

当前实现将FAIL_REPORT_VALIDITY_MULT设置为2。这意味着，在两倍NODE_TIMEOUT时间内，大多数Master将某个节点标记为故障，则集群认为该节点宕掉了。

需要了解PFAIL到FAIL的转换，依赖于一种弱（一致）的协议：

1. 节点在一段时间范围内，收集其它节点的（关于节点状态）视图。由于时间窗口的存在，我们无法确认（也不需要）在某个时间点是否大多数Master达成一致
2. FAIL消息会被传播，但是无法保证所有节点都能收到并修改故障节点状态，这是因为故障常常伴随网络分区

节点状态可以从PFAIL变成FAIL，但是FAIL状态仅仅在以下情况下才能清除掉：

1. 节点变得可达，并且成为Slave。由于Slave不能参与故障转移，因此FAIL状态清除
2. 节点变得可达，成为Master，但是不负责任何Slot。这种情况下FAIL状态可以被清除，因为该节点并没有正常参与到集群中
3. 节点变得可达，成为Master，过了很长时间（NODE_TIMEOUT的N倍）仍然没有可觉察的Slave晋升。这种情况下，最好是让该节点重新加入集群

KeyDB使用类似于Raft算法中的Term的概念，叫Epoch。当多个节点提供了冲突的信息时，Epoch可用于确定谁的状态是up-to-date的：

1. currentEpoch，可以认为是集群状态的版本号，最终所有节点应该具有相同的currentEpoch
2. configEpoch，每个Master节点具有独特的configEpoch，主要包含它负责的Hash Slots列表

每个新创建的节点，它的 currentEpoch（64bit无符号整数）都是0。每当从其它节点接收到一个消息，如果消息中的epoch大于本地的currentEpoch，则更新currentEpoch为接收到的epoch。

过了一段时间后，集群中所有节点都会使用最大的configEpoch作为自己的currentEpoch。

currentEpoch在集群节点需要协商，以决定执行某操作的时候用到，currentEpoch大的节点具有话语权。目前只支持Slave晋升这一种操作。

所有Master在PING/PONG的时候，都会通告自己的configEpoch（连同自己负责的Hash Slots）。

当一个新节点加入集群后，Master将configEpoch设置为0。Slave尝试晋升自己的时候，会增加configEpoch的值，并尝试获得大多数Master的授权。一旦Slave获得授权，则它成为使用此新configEpoch的Master。

Slave在PING/PONG中也会通告configEpoch，通告的是它（通过最后一次消息得到）的Master的configEpoch。如果它通告的configEpoch小于Master的真实configEpoch，这意味着它需要更新，选举时Master不会投票给持有过期configEpoch的Slave。

节点的configEpoch变更，会被所有接收到相关心跳的节点fsync到nodes.config中。如果引起currentEpoch的变更，也会fsync到nodes.config。

configEpoch值的递增有一个简单算法负责，此算法确保它是新的、递增的、唯一的。configEpoch的变化由于故障转移、再分片导致。

如果由于Slave晋升导致configEpoch增加，集群会确保它是唯一的。

以下两种操作，仅仅简单的更新本地的configEpoch，可能导致configEpoch冲突：

1. 使用带

   TAKEOVER

   选项的

   CLUSTER FAILOVER

   命令，可以强制晋升一个Slave节点，不需要大多数Master可用
2. 手工迁移Slot来进行再分片，也仅仅在本地节点生成新的epoch

手工再分片时，如果Slot从A迁移到B，分片程序会强制B增加自己的epoch为可发现集群范围内的最大值 + 1，除非节点的epoch已经是最大。由于再分片常常牵涉到大量Slot的迁移，为了每个Slot，进行协商并获得更高的configEpoch是很低效的，因此增加epoch仅在本地进行，并且仅仅在迁移第一个Slot时进行。

尽管可能性较低，还是会出现多个节点声明相同configEpoch的情况 —— 如果手工再分片和自动故障转移发生外加运气差的话。KeyDB使用下面的冲突解决算法：

1. 如果Master A发现Master B正在通告和自己相同的configEpoch
2. 并且根据字典序比较，A的Node ID比B大
3. 那么A将currentEpoch+1，并且将其作为自己的configEpoch

也就是说，如果集群中有若干节点具有相同configEpoch，那么其中ID最大的取胜，出现Hash Slot冲突时以它为准。

Hash Slots - 节点映射关系的传播，不管对于新集群，还是由于故障转移/手工重分片导致的Slot负责节点变更，都是关键的。

Hash Slots配置信息可以通过两种方式传播：

1. 心跳消息：节点发送PING/PONG时总是携带它（或者它的Master）所负责的Slot的信息
2. UPDATE消息：由于心跳中还携带了自己的epoch，如果接受者发现此epoch过期，则会发送UPDATE消息，强制过期节点更新配置

当一个新的节点加入到集群后，它的Hash Slot映射（16383 个key）简单的置空（表示未分配）。当接收到心跳/UPDATE消息后，根据以下规则来更新映射：

1. 如果Slot为空，并且某个已知的节点claim该Slot，分配Slot给节点
2. 如果Slot不为空，并且它映射给Master A，如果现在接收到Master B的消息，声明Slot归它管。这种情况下，如果B的configEpoch大于A，则重新绑定Slot给B

由于规则2的存在，最终集群中所有的节点都认可configEpoch最大的节点通告的映射关系，这就是所谓last failover wins机制。

故障转移：

1. 依赖于上面两节提到的故障发现、配置传播机制
2. 由出问题的Master的Slave主导，其它Master节点参与投票完成
3. 触发时机为：
   1. Master进入FAIL状态，并且经过了选举时延
   2. Master至少负责1个Slot
   3. Slave和Master的复制连接断开时间小于，这是为了保证Slave的数据不过于陈旧

故障转移过程如下：

1. Slave增加自己的configEpoch，并同步currentEpoch
2. 请求Masters来投票，具体做法是广播

   FAILOVER_AUTH_REQUEST

   消息给所有Master节点
3. 等待Master的应答，最长

   NODE_TIMEOUT * 2

   ，最短2秒
4. 如果应答的Master的epoch小于发起晋升时Slave的currentEpoch，则应答被丢弃。这个可以防止接收到关于上一次选举的投票
5. 如果Slave在限定时间内获得大多数Master的投票，则晋升成功。否则，等待

   NODE_TIMEOUT * 4

   再次进行选举

Master参与投票时遵循以下规则：

1. 对于一个给定的epoch，每个Master仅会投票一次：如果Master投票给Slave，它应答FAILOVER_AUTH_ACK，同时将lastVoteEpoch字段持久化到配置文件。Master在NODE_TIMEOUT * 2的时间内，不再能投票给故障Master的其它Slave，这可以防止同时选出多个新Master。
2. 只有Master任何被故障转移的Master处于FAIL状态，才会进行投票
3. 如果FAILOVER_AUTH_REQUEST中的currentEpoch小于Master的currentEpoch，请求被忽略 —— 这意味着投票应答的epoch总是和请求的相同

Master进入FAIL状态后，Slave还需要等待一个选举延迟：

DELAY = 500 毫秒 + 0 -500 毫秒随机延迟 + SLAVE_RANK * 1000 毫秒

才会发起选举投票。固定延迟让FAIL消息有机会传播到整个集群，随机延迟可以防止两个SLAVE_RANK相同的Slave同时尝试晋升。

SLAVE_RANK的大小取决于复制的进度。当Master故障时，Slave会相互通信，交换自己的复制进度，并进行排名。进度最快的Slave的SLAVE_RANK为0，依次递增。

一旦Slave赢得选举，它将获得大于所有其它Master的configEpoch，并且通过心跳通告自己的configEpoch、负责的Slots。

为了让集群尽快完成重新配置，Slave将发送一个PONG包给整个集群。当前不可达的节点可能通过下面两种方式之一获得更新：

1. 接收到其它节点的PING/PONG包
2. 其自己发送的心跳，由于信息过期，被其它节点应答以UPDATE

重新配置的内容包括：

1. 对于故障的Master的原有其它Slave，需要更新复制源
2. 对于所有节点，需要更新Hash Slot - 节点映射关系 

如果一个Master节点因为网络分区，脱离集群，并且时间足够长，发生了故障转移。那么网络恢复后，旧的Master如何处理？

在KeyDB中，旧Master将配置为偷取了它的Slot的那个节点的Slave。

重置节点，可以让它以另外一个角色加入集群，或者加入其它集群。

执行

CLUSTER RESET

1. 如果节点是Slave，则角色切换为Master，丢弃数据集；如果节点是Master并且持有Key，则中止重置
2. 释放所有Hash Slot，重置手工故障转移状态
3. 移除节点表中所有其它节点，这样节点对原先集群一无所知
4. 对于硬重置：currentEpoch、configEpoch、lastVoteEpoch均置零
5. 对于硬重置：Node ID修改为新的随机值

通过重新分片，将Master的Slot全部迁移走，就可以关闭它了。

由于其它节点仍然记着移除节点的Node ID和地址，还会尝试连接它，因此，你应当调用

CLUSTER FORGET <node-id>

1. 从所有节点的nodes table中移除指定节点
2. 60s内禁止被移除节点（根据ID）再次加入集群。防止因为gossip导致重新加入

集群的客户端可以在任何节点上订阅，在任何节点上发布。KeyDB会保证消息被正确的转发 —— 目前的实现仅仅是简单的广播。

The post KeyDB学习笔记 appeared first on 绿色记忆.

MariaDB提供了兼容MySQL的数据库解决方案，它本身是MySQL的一个Fork。

MySQL中复制（Replication）是异步的、单向的。其中一个服务器作为Master，其它的作为Slave。所谓主主模式，是两个服务器分别配置为对方的Slave。MariaDB提供主主复制、主从复制。

MySQL 的默认二进制日志格式是基于行的，而在 MariaDB 中，默认的二进制日志格式是混合式的。

MariaDB支持二进制日志压缩（log_bin_compress）。

MySQL提供shared-nothing的集群支持，通过自动分区的方式将数据分发到不同节点。在内部MySQL使用同步的、两阶段的提交，确保数据被写入到多个分片。

MariaDB使用Galera Cluster实现多主，从10.1开始MariaDB内置Galera，只需要配置参数即可启用集群模式。

MariaDB支持更多的存储引擎：XtraDB（10.2-的默认引擎，InnoDB增强版）、InnoDB（10.2+默认引擎）、MariaDB ColumnStore、Aria、Archive、Blackhole、Cassandra Storage Engine、Connect、CSV、FederatedX、Memory、Merge、Mroonga、MyISAM、MyRocks、QQGraph、Sequence Storage Engine、SphinxSE、Spider、TokuDB

MariaDB 上可用，MySQL 不支持该功能。这个功能允许创建不再 SELECT * 语句中出现的列，而在进行插入时，如果它们的名字没有出现在 INSERT 语句中，就不需要为这些列提供值。

从 5.7 版本开始，MySQL 支持由 RFC 7159 定义的原生 JSON 数据类型，可以高效地访问 JSON 文档中的数据。

MariaDB 没有提供这一增强功能，认为 JSON 数据类型不是 SQL 标准的一部分。但为了支持从 MySQL 复制数据，MariaDB 为 JSON 定义了一个别名，实际上就是一个 LONGTEXT 列。

MariaDB 支持连接线程池，这对于短查询和 CPU 密集型的工作负载（OLTP）来说非常有用。在 MySQL 的社区版本中，线程数是固定的，因而限制了这种灵活性。MySQL 计划在企业版中增加线程池功能。

MariaDB Galera Cluster提供MariaDB多主集群，仅仅对XtraDB/InnoDB存储引擎提供支持。

从MariaDB 10.1开始，MySQL-wsrep补丁被合并到MariDB，这意味着使用标准的MariaDB+Galera wsrep提供者库即可构建Galera集群。该补丁由Codership开发，提供wsrep API支持。

Galera的主要特性包括：

1. 几乎同步的（virtually synchronous ）的复制
2. Active-Active多主拓扑支持，不需要failover
3. 针对集群的任何节点进行读写操作
4. 自动的集群成员控制，失败的节点能够自动的移出集群
5. 自动节点加入
6. 真正的（从底层）并行复制
7. 不需要读写分离
8. Slave支持多线程以提升性能

基于Galera的集群的主要优势包括：

1. 没有Slave的延迟
2. 不会丢失事务
3. 读操作的可扩容性
4. 更小的客户端延迟

Galera的使用场景包括：

1. 从Master读写：Galera支持这种传统场景，但是和MariaDB传统主从复制相比，任何一个节点都可以随时成为Master，而其它节点仅仅是客户端将其作为Slave看待而以。由于Slave可以并行的应用writeset，集群的吞吐量会快的多，此外复制的延迟也被消除
2. 广域网集群：可以支持这种网络下的几乎同步复制，可能会存在延迟，取决于RTT。这些延迟仅仅影响commit操作
3. 灾难恢复：广域网集群的子用例。这种情况下，位于某个数据中心的节点仅被动接受复制，不处理任何客户端事务。由于Galera的几乎同步的复制，它不会丢失数据，并可以在主节点宕机后立即升级为新的主节点
4. 延迟消除：让客户端访问靠近自己的节点，可以消除读操作的延迟。延迟仅仅在写操作时才发生

MariaDB、Galera库、wsrep API版本对应关系如下：

使用包名galera-4安装Galera 4 wsrep provider。版本26.4.6对应MariaDB的版本是10.5.7 / 10.4.16

使用包名galera安装Galera 3 wsrep provider。版本25.3.31对应MariaDB的版本是10.3.26 / 10.2.35 / 10.1.48

Galera复制功能实现为一个共享库，可以连接到任何实现了wsrep API的事务处理系统。它是由一系列组件组成的协议栈，提供准备、复制、应用事务writeset的功能。

在Galera 4很多组件被重新设计。

即写入集复制API（writeset replication API），它定义了Galera Replication和MariaDB之间的接口，以及各自的职责。 

在RDBMS引擎中的wsrep集成点。

为Galera库实现wsrep API。

尽管galera provider负责在提交时，在所有节点认证writeset，但是writeset不需要被立即apply到节点。实际上writeset被放置在节点的接收队列上，由节点的某个galera slave thread最终apply到数据库中。

Galera slave thread的数量可以通过系统变量

wsrep_slave_threads

Galera slave thread们负责自行判断哪些writeset可以被安全的并行apply，但是，如果节点经常出现数据一致性问题，可以将线程数量设置为1。

负责准备writeset，执行认证测试。

管理复制协议，提供整体上的排序能力（ordering capabilities）

为Group Communication系统（GCS）提供插件化架构。很多GCS实现可以被适配。内置实现是vsbes、gemini 

所谓状态转移是指从现有节点复制数据，以使得新节点/宕机后恢复的节点到达同步状态的操作。

在一次State Snapshot Transfers / SST中，集群通过从一个节点拷贝完整的数据集，来创建新节点。

当新节点加入集群后，它会触发一次SST。

在一次Incremental State Transfers /IST中，集群从正常节点，拷贝某个节点缺失的writeset。

如果节点离开集群时间比较短，则IST通常比SST更块。

在Galera集群中，服务器在提交（Commit）期间进行事务复制。其做法是，将事务关联的写入集（writeset）广播到所有节点。 

同步复制能够保证：如果一个节点上的数据发生变更，那么这些变更会同时发生在其它节点上。

异步复制不提供上述保证，这意味着，在第一个节点上发生变更后，复制完成之前该节点宕机，可能会导致数据丢失。

同步复制的优势：

1. 使用同步复制的集群，总是能保证HA和数据一致性。节点崩溃不会导致数据丢失
2. 同步复制允许事务在所有节点上并行的执行。而不是进行Replay
3. 因果律保证：如果先在A节点发生事务，然后在B节点执行查询，那么该查询一定能看到A节点那个事务的结果

典型的同步复制利用两阶段提交或者分布式锁来实现，非常缓慢。再加上实现的复杂度，导致MySQL、PostgreSQL等传统RDBMS都仅仅支持异步复制，或者所谓半同步复制（主库在执行完客户端提交的事务后不是立刻返回给客户端，而是等待至少一个从库接收到并写到Relay log中才返回给客户端）。

Galera使用基于认证的复制（Certification-based replication），实现几乎完全同步（virtually synchronous）的数据复制。

Galera的基本思想是乐观执行（ optimistic execution）：假设不存在冲突，正常执行事务，直到达到提交点（commit point），在提交之前，通过认证来检查冲突

Galera的核心机制包括：

1. 分组通信（group communication）：定义了数据库节点之间的通信pattern，保证复制数据的一致性
2. 写入集（writeset）：将若干数据库写操作合并为一个消息，避免了每次数据库操作都引发节点之间的协作。writeset中包含了事务的所有必要信息
3. 数据库状态机（database state machine）：只读事务仅在节点本地执行。非只读事务首先在单个节点本地执行，然后广播writeset到其它节点，认证并apply到数据库
4. 全局事务排序（global transaction reordering）：在复制期间，Galera为每个事务分配一个全局的序号即seqno，每个节点将以相同的顺序接收（和应用）事务。当事务到达提交点时，节点会检查上一次成功的事务的seqno。这两次事务seqno的差值，提示了尚未apply的事务数量。节点会对这些没处理的事务进行主键冲突检查，发现冲突则触发认证失败

Galera执行数据复制的流程如下：

1. 当客户端发出一个 commit 指令，在事务在服务器端被正式（数据已经写入，只差）提交之前，所有对数据库的更改都会被writeset收集起来，并且将 writeset 纪录广播给其他节点

2. writeset 将在每个节点（包括发起writeset的原始节点）上、基于主键进行决定性认证测试（deterministic certification test,），测试结果决定节点能否 apply writeset

3. 如果认证测试失败：节点丢弃writeset，集群回滚原始事务

4. 如果认证测试成功：事务被正式提交，其余节点则apply writeset

只有所有节点都认证成功，达成共识，那么发起事务的原始节点就可以正式提交并给客户端响应。在这个时间点，用户的写入集已经同步到了所有节点，不会因为原始节点故障而导致数据丢失

关于从普通MariaDB转到Galera的TIPS，参考：https://mariadb.com/kb/en/tips-on-converting-to-galera/

对任何其它引擎的表的写入，包括系统表（mysql.*，使用MyISAM引擎）都不会复制到其它节点。例外情况是DDL语句，这些语句虽然修改mysql.*表，但是却会被复制。

对MyISAM复制目前提供试验性支持，设置系统变量：wsrep_replicate_myisam。

FLUSH PRIVILEGES 不会被复制。

LOCK TABLES、FLUSH TABLES (table list) WITH READ LOCK等语句不被支持，可以通过适当的事务控制来达到相同效果。

全局性的锁操作，例如FLUSH TABLES WITH READ LOCK则可以被支持。

所有表必须具有主键（支持复合主键）。针对无主键表的DELETE操作是不支持的。没有主键的表，可能在不同节点上的顺序不同。

普通查询日志、缓慢查询日志，不支持写入到表中。如果启用这些日志，你必须设置log_out=FILE

尽管Galera没有明确限制，但是writeset被存储在内存中，这隐含了对事务尺寸的限制。

为了避免非常大的事务严重影响节点性能。系统变量的默认值设置为：

1. wsrep_max_ws_rows  事务最大影响行数，128K
2. wsrep_max_ws_size 事务最大尺寸（写入集大小）2GB

此外根据社区的反馈，大尺寸事务可能有额外的不可忽略的开销。你写入100K的行，可能需要额外200-300MB甚至数G内存。

你的DML语句操作一个锁，而另外一个DDL已经发起。正常情况下MySQL会等待元数据锁，但是Galera则会立即执行DML。甚至仅有单个节点的情况下，也会发生这种情况。

不要假设自增长的列是一个个顺序增长的。Galera为了保证没有冲突，为每个节点的自增长键都设置了空虚。

当出现网络分区，并且当前节点不再大多数节点所在分区。命令会导致ER_UNKNOWN_COM_ERROR：WSREP has not yet prepared node for application use / Unknown command。这个报错是为了放置数据不一致。网络分区状态可以通过检查

wsrep_ready

少部分节点所在的分区，节点可能会丢弃所有客户端连接，这个行为可能比较意外 —— 因为客户端可能是空闲的，甚至不知道发生什么连接就忽然断了。

这种被分区的节点重新连接到集群后，可能有大量数据需要同步。在同步完成之前，它仍然会报告unknown command。

在运行时修改binlog格式，不但会导致复制失败，还会导致其它节点崩溃。

根据Galera的设计，集群的整体性能取决于最慢的节点。

此外，即使只有一个节点。性能也可能比非集群模式的MariaDB低很多，特别是对于大事务。

在MariaDB Galera Cluster 5.5.40, MariaDB Galera Cluster 10.0.14以及MariaDB 10.1.2之前，需要设置query_cache_size=0以禁用查询缓存。

启用异步复制模式的情况下，不支持在Slave节点上进行并行复制（slave-parallel-threads 大于1）。

节点的表结构可能不一致，特别是在执行rolling schema upgrade期间。

读写分离不是必须的，但是仍然建议做读写分离，未来底层架构可能变化。

所有状态变量具有一致的前缀：

SHOW STATUS LIKE 'wsrep%';

为了安装MariaDB Galera Cluster，需要以下包：

1. 支持Galera的MariDB
2. Galera wsrep提供者库

为了支持基于SST的备份，可能需要额外的包。

添加源配置：

# MariaDB 10.5 CentOS repository list - created 2021-01-15 07:44 UTC
# http://downloads.mariadb.org/mariadb/repositories/
[mariadb]
name = MariaDB
baseurl = http://yum.mariadb.org/10.5/centos8-amd64
module_hotfixes=1
gpgkey=https://yum.mariadb.org/RPM-GPG-KEY-MariaDB
gpgcheck=1

执行安装：

dnf install MariaDB-server
systemctl start mariadb

dnf install galera4 

集群的第一个节点需要以下面的命令行选项来自举（bootstrap）：

mysqld --wsrep-new-cluster

这个选项告诉MariaDB，不需要连接到既有集群。对于一个现有的节点，以该选项重启，会导致创建新的识别集群身份的UUID，并且它不会再连接到老集群。

对于使用Systemd的系统，应该使用下面的命令创建新集群：

galera_new_cluster

要添加新节点，需要通过wsrep_cluster_address选项指定集群地址，如果第一个节点的地址是192.168.0.1，则可以用下面的配置加入新节点：

[mariadb]
; 支持IP地址或DNS名称
wsrep_cluster_address=gcomm://192.168.0.1

使用上述配置，新节点将会连接到一个既有集群节点，并随后发现所有的节点。最好在此配置中，指定所有集群成员的地址，免得因为单点的故障 导致无法加入集群。

当所有成员加入到集群，状态不一致的集群可能通过IST/SST来达到一致性。

当集群所有节点关闭后，需要依次重启节点。

如果第一个节点以常规方式启动， 则它会尝试连接到wsrep_cluster_address中的其它节点，这必然失败。因此，集群完全关闭之后，需要对第一个节点进行bootstrap操作。

第一个节点，必须是数据最新的节点。如果节点检测到它可能不是数据最新（如果它不是最后一个关闭的，或者它是崩掉的）的节点，它会拒绝bootstrap。

查看所有节点的grastate.dat文件，其中seqno字段的值最大的，就是数据最新的节点。如果节点是崩掉的且seqno=-1，则可以使用下面的命令恢复seqno：

mysqld --wsrep_recover

确定数据最新节点后，可以修改它的数据目录下的grastate.dat文件，设置：

safe_to_bootstrap=1

使用Systemd的情况下，节点的seqno可以通过命令：

galera_recovery

#                                 集群group id                         seqno
[Note] WSREP: Recovered position: 7bff636d-50c7-11eb-81c8-6f8dd75e7fb4:1202

启用Galera时，MariaDB的Systemd服务会在启动数据库之前自动运行galera_recovery。

和Galera相关的状态变量，都放在wsrep_前缀下：

SHOW GLOBAL STATUS LIKE 'wsrep_%';

参考在K8S中运行一节。

当新加入一个节点到Galera集群时，此节点需要从集群节点获取数据，这个复制过程被称作状态转移（State Transfer），Galera支持两种状态传输方式：

1. State Snapshot Transfers (SST) 传输一个节点的完整状态（即所有数据），全量复制
2. Incremental State Transfers (IST) 只传输缺失的数据，增量复制

使用 IST 的方式时，集群会判断加入集群的节点所缺失的数据，而不必传输完整的数据集。使用 IST 必须满足特定的条件：

1. 加入节点的 state UUID 必须和此集群的相同
2. 加入节点所缺失的数据都在 donor 节点的 writeset cache 中存在

如果上述条件满足，供给节点会发送加入节点上缺失的事务，按照顺序replay它们，直到加入节点赶上集群进度。

IST不会阻塞供给节点

使用 IST 最重要的参数是 donor 节点的 gcache.size 大小，这个参数表示分配多少空间用于缓存 writeset。缓存的空间越多，能够使用 IST 的几率就越大

所谓状态快照转移（SST），就是指集群通过将某个up-to-date节点的数据集，完整的拷贝到另外一个节点的过程/操作。

从概念上来看，存在两种状态转移方式。

即mysqldump SST，该SST方法，实际上是调用mysqldump，从源节点获取数据库的逻辑dump文件。

要使用mysqldump SST，新加入的节点必须完全初始化，并且准备好接受连接。

该SST方法会阻塞源节点，在状态转移期间，无法对源节点进行修改。该SST方法是最慢的一种，在高负载集群中可能导致问题。

这类SST方法将数据文件从源节点拷贝到新加入的节点。节点需要在状态转移之后再完成初始化。mariabackup SST等属于这一类别。

这类方法比mysqldump SST快很多，但是具有一些限制条件：

1. 只能在服务器启动时使用
2. 新节点必须和源节点配置很相似，例如 innodb_file_per_table取值必须相同

这类方法中的某些，例如mariabackup SST，是非阻塞的，也就是说，在状态转移期间源节点可以继续处理请求。

通过设置全局系统变量，可以修改使用的SST方法：

SET GLOBAL wsrep_sst_method='mariabackup';

SST方法也可以在配置文件中修改：

[mariadb]
wsrep_sst_method = mariabackup

注意：源节点和新节点必须使用相同的SST方法。 建议所有节点使用一致的SST方法。

除了rsync SST之外，都需要配置基于用户名:密码的身份验证：

SET GLOBAL wsrep_sst_auth = 'mariabackup:password';

或者修改配置文件：

[mariadb]
wsrep_sst_auth = mariabackup:password

某些身份认证插件，例如unix_socket或gssapi，不需要密码，这种情况下只需要指定用户名： 

[mariadb]
wsrep_sst_auth = mariabackup:

为了防止脑裂的出现，推荐最小集群规模为3。

另外一个需要3节点的原因是，当SST阻塞了源节点时，仍然可以有一个节点能响应查询。

如果状态转移失败，新节点一般是不可用的。

如果使用mysqldump SST，可能还需要手工恢复某些MariaDB管理表。

本节介绍如何使用这种SST方法。

修改配置文件：

[mariadb]
wsrep_sst_method = mariabackup 

或者通过命令行设置：

SET GLOBAL wsrep_sst_method='mariabackup';

该SST方法需要在所有供给（donor）节点上进行本地身份验证。

首先需要创建专用的数据库账号： 

CREATE USER 'mariabackup'@'localhost' IDENTIFIED BY 'mypassword';
GRANT RELOAD, PROCESS, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'mariabackup'@'localhost';

然后修改配置文件或执行命令行设置：

[mariadb]
wsrep_sst_auth = mariabackup:mypassword

SET GLOBAL wsrep_sst_auth = 'mariabackup:mypassword';

可以使用unix_socket身份认证插件，这样就不需要指定密码： 

CREATE USER 'mysql'@'localhost' IDENTIFIED VIA unix_socket;
GRANT RELOAD, PROCESS, LOCK TABLES, REPLICATION CLIENT ON *.* TO 'mysql'@'localhost';

当mariadbbackup在供给（donor）节点创建备份时，它需要在备份最后创建一个全局的锁：

1. 在10.3-，锁通过 

   FLUSH TABLES WITH READ LOCK

   实现
2. 在10.4+，锁通过 

   BACKUP STAGE BLOCK_COMMIT

   实现

如果集群中某个节点正作为“主”节点来使用 —— 也就是说应用程序连接到它来写入数据，那么该节点不应该用作SST源，因为全局锁会干扰应用程序的写操作。

可以通过下面的系统变量，来设置偏好使用哪些节点作为源：

[mariadb]
; 如果集群由 node1, node2, node3, node4, node5构成。node1作为主使用
; 那么node2可以这样配置：
wsrep_sst_donor=node3,node4,node5,
; 结尾的逗号表示，如果偏好的节点不可用，允许选择任何节点作为源

mariabackup SST具有独立的日志，不和数据库日志在一起：

[sst]
sst-log-archive=1
sst-log-archive-dir=/var/log/mysql/sst/
; 记录到syslog中
sst-syslog=1

Galera Load Balancer（GLB）是一个简单的、特地为Galera设计负载均衡器。该LB支持多种负载均衡策略。

节点可以被设置不同的权重，优先使用高权重的节点，根据选择的策略，低权重节点可能被忽略（除非高权重节点挂掉）。

一个轻量级的守护进程glbd负责接收客户端连接，并执行LB算法，重定向客户端请求到适当的节点。

1. 可以在运行时配置后端节点列表
2. 支持drain节点，也就是不分配新的连接给它，但是不会kill服务器 —— 让它优雅关闭
3. 使用epool提升性能
4. 支持多线程，可以利用多核心CPU
5. 支持可选的watchdog来监控后端并调整路由表

GLB支持以下负载均衡策略：

1. least connected： 最少连接，新连接并分发给连接最少的节点，需要考虑节点权重
2. round-robin：依次循环调度给每个节点
3. single：所有连接调度给最高权重的节点，除非此节点挂了，或者引入一个新的、更高权重的节点
4. random：随机调度
5. source tracking：来自同一源地址的连接，总是被调度给同一节点

推荐的部署模式是3节点以上，奇数节点。

如果部署第3个节点（例如只有两个数据中心）的成本过高，可以考虑引入仲裁节点（Galera Arbitrator）以防止脑裂。仲裁节点：

1. 参与投票，来决定Primary Component。当两节点集群出现网络分区时，能够看到仲裁节点的那个构成Primary Component
2. 不参与复制。尽管仲裁节点不参与复制，但是它会接收所有数据（但是不存储），这意味着你不能将其放置在网络连接差的地方，否则可能导致很差的集群性能

仲裁节点还有另外一个用途——用于备份，它可以请求数据库状态的一致性快照。

由独立的守护进程garbd来运行仲裁节点：

garbd --group=example_cluster \
     --address="gcomm://192.168.1.1,192.168.1.2,192.168.1.3" \
     --option="socket.ssl_key=/etc/ssl/galera/server-key.pem;socket.ssl_cert=/etc/ssl/galera/server-cert.pem;socket.ssl_ca=/etc/ssl/galera/ca-cert.pem;socket.ssl_cipher=AES128-SHA256""

配置信息也可以放在独立文件中：

group = example_cluster
address = gcomm://192.168.1.1,192.168.1.2,192.168.1.3

garbd --cfg /path/to/arbitrator.config

由于Galera集群的复制特性，执行备份时我们只需要在一个节点上进行。而在恢复时，也仅仅需要在一个节点上执行，剩下节点的同步，可以依靠状态转移自动完成。

任何时候，都可以针对某个Galera节点，使用常规的MariaDB备份工具进行备份。

上文中的内置SST方法，对应了各种备份工具，混合使用多种备份方法，能够提高额外的数据安全性。这里挑选几个工具说明用法：

--single-transaction

wsrep_desync=OFF

# 备份所有数据库
mysqldump -u root -p pswd –all-databases > data.sql
# 仅仅备份gmem数据库的表结构
mysqldump -u root -p pswd –no-data gmem > schema.sql


# 恢复数据库，可能需要先清空
mysql> drop database gmem;

mysql -u root -p pswd <  schema.sql

#                   数据目录                  备份存放目录
xtrabackup --backup --datadir=/var/lib/mysql/ --target-dir=/data/backups/mysql/

xtrabackup: Transaction log of lsn (<SLN>) to (<LSN>) was copied.

# 假设使用innodb_file_per_table选项
/data/backups/mysql/ibdata1
/data/backups/mysql/test
/data/backups/mysql/test/tbl1.ibd
/data/backups/mysql/xtrabackup_checkpoints
/data/backups/mysql/xtrabackup_logfile

xtrabackup --prepare --target-dir=/data/backups/mysql/

# 结束时会打印
101107 16:40:15  InnoDB: Shutdown completed; log sequence number <LSN>

rsync -avrP /data/backup/ /var/lib/mysql/
chown -R mysql:mysql /var/lib/mysql

# 备份      数据库帐号密码                      备份根目录            不创建基于时间戳的子目录
innobackupex --user=DBUSER --password=DBUSERPASS /path/to/BACKUP-DIR/ --no-timestamp
#            指定MySQL配置文件
innobackupex --defaults-file=/tmp/other-my.cnf --user=DBUSER --password=DBUSERPASS /path/to/BACKUP-DIR/

# 准备                   允许使用多少内存
innobackupex --apply-log --use-memory=100M  /path/to/BACKUP-DIR

# 恢复
innobackupex --copy-back /path/to/BACKUP-DIR

由于所有Galera节点具有相同的数据，因此你可以使用常规的MariaDB备份工具进行备份，但是这种方式存在缺点 —— 缺少全局事务ID信息（GTID）。使用这种备份来恢复，不能让节点进入良好定义的状态。此外，某些备份工具会阻塞节点，这也需要注意。

因此，理想的备份方式是发起一次SST：

1. 节点会在一个良好定义的点发起备份
2. 节点会将GTID关联到备份
3. 备份期间，节点从集群desync，避免影响性能 —— 备份过程可能阻塞节点
4. 集群知道节点正在进行备份，因此不会将其选为donor

我们需要利用仲裁节点来发起备份：

# garbd可以以函数方式执行，调用一个命令
#                                   如果在集群节点上发起，则4567已被占用，另外选择一个端口
garbd --address gcomm://192.168.1.2?gmcast.listen_addr=tcp://0.0.0.0:4444 \
#   机器名称               供给节点名称           在供给节点上执行的脚本的后缀
  --group example_cluster --donor galera-3 --sst backup_mysqldump

你也可以通过配置文件指定各种选项：

; 填写集群的wsrep_cluster_name
group='example_cluster'
; 填写集群的wsrep_cluster_address
address="gcomm://172.31.30.39:4567,172.31.18.53:4567,172.31.26.106:4567"
; 填写集群的wsrep_provider_options。listen_addr添加garbd进程的监听端口
options="gmcast.listen_addr=tcp://0.0.0.0:4444"
; 指定哪个节点执行备份
donor="galera-3"
; 日志文件路径
log='/var/log/garbd.log'
; 备份节点上的备份脚本的后缀，对于下面的后缀，脚本名是wsrep_sst_backup_mysqldump
sst='backup_mysqldump'

下面是一个脚本的示例，它使用了bash + mysqldump，但是任何脚本语言、备份工具都是可以的： 

#!/bin/bash

# SET VARIABLES
db_user='admin_backup'
db_passwd='Rover123!'

backup_dir='/backup'
backup_sub_dir='temp'

today=`date +"%Y%m%d"`
# Dump文件路径
backup_today="galera-mysqldump-$today.sql"
# GTID文件路径
gtid_file="gtid-$today.dat"


# 加载此脚本，它提供GTID变量
. /usr/bin/wsrep_sst_common


# 备份配置文件
cp /etc/my.cnf $backup_dir/$backup_sub_dir/
cp /etc/garb.cnf $backup_dir/$backup_sub_dir/
# 备份GTID
echo "GTID: ${WSREP_SST_OPT_GTID}" > $backup_dir/$backup_sub_dir/$gtid_file


# 进行数据库Dump
mysqldump --user="$db_user" --password="$db_passwd" \
          --flush-logs --all-databases \
          > $backup_dir/$backup_sub_dir/$backup_today

# 打包
cd $backup_sub_dir
tar -czf $backup_dir/$backup_today.tgz * --transform "s,^,$backup_today/," 

将备份恢复到一个新集群，或者既有集群，可以使用相同的步骤：

1. 选择一个节点，作为恢复节点
2. 停止其它节点
3. 关闭恢复节点的Galera Replication，进入Standalone模式：
   

   SET GLOBAL wsrep_provider = 'none';
   
   SHOW STATUS LIKE 'wsrep_connected';
   
   +-----------------+-------+
    
   | Variable_name   | Value |
    
   +-----------------+-------+
    
   | wsrep_connected | OFF   |
    
   +-----------------+-------+

4. 调用备份工具，执行恢复
5. 在恢复节点上重新开启Galera Replication
6. 启动被停止的节点重新加入集群，并通过SST重新获得同步

用于存放writeset的特殊缓存，叫作writeset cache或GCache。GCache支持三种存储：

1. Permanent In-Memory Store：直接使用操作系统的内存，适合有很多空余内存的系统，默认情况是禁用的
2. Permanent Ring-Buffer File：在缓存初始化时就预先分配的一块磁盘空间，默认情况下，它的大小是 128Mb
3. On-Demand Page Store：根据需要在运行时动态分配内存映射页文件，默认情况下是 128Mb，但如果需要更大的 write-set，它可以动态的增长。当 page file 不再使用时，Galera Cluster 会删除这些文件，可以对 page file 的总大小进行限制

Galera Cluster 的缓存分配算法会按上面的顺序来分配缓存空间，gcache.dir 参数可以指定缓存保存在磁盘的位置。

Galera允许一个节点根据需要来暂停/恢复复制，这叫作Flow Control。FC可以节点在apply事务方面，过于落后其它节点。

我们知道，所有节点收到writeset并进行认证之后，原始的接收请求的节点就可以在本地完成提交并应答客户端了。此时，其它节点不一定也apply/commit了事务（取决于配置）。尚未apply/commit的事务（writeset）会存放在接收队列中。

如果某个节点速度缓慢，那么它的接收队列会不断积压，到达一定程度之后，就会触发FC：

1. 暂停复制
2. 处理接收队列的积压
3. 当队列到达可管理的大小之后，再恢复复制

在Galera中，需要去分单节点内的、集群范围的事务隔离级别。单节点内的事务隔离级别不必多提，参考MariaDB提供的配置项即可。

集群范围的事务隔离，受到复制协议的影响，不同节点上发起的事务，可能不会完全等同的隔离。

集群中能互相保持心跳通信的节点的集合叫作Component，两个Component之间存在网络分区，无法相互通信。理想情况下，集群只有一个Component。

大部分节点组成的Component叫作Primary Component —— PC必须满足大多数原则，在三节点集群中，至少两个节点才能组成PC。

只有位于PC中的节点，才能继续修改数据库状态。

Galera Cluster 会周期性的检查每个节点的连接是否正常， evs.inactive_check_peroid 参数可以设置检查的周期。如果一个节点的失效时间超过了 evs.suspect_timeout 的值，那么节点将被标记为 suspect。如果 Primary Component 中的所有节点都将某个节点标记为 suspect ，那么此节点被移出集群。

如果一个节点的失效时间超过了 evs.inactive_timeout 的值，此节点将直接被移出集群而不需要协商。故障的节点将不可读不可写。

在计算是否构成Primary Component / Quorum时，节点是可以被加权的。节点的权重通过pc.weight配置。例如下面的配置：

node1: pc.weight = 2
node2: pc.weight = 1
node3: pc.weight = 0

即使同时杀掉node2和node3，node1仍然构成PC 

提供者选项在系统变量 wsrep_provider_options 中配置，选项之间用;隔开。

Orange开发了一个Galera Operator，简化K8S中的Galera的部署和运维。支持的特性包括：

1. 创建、销毁集群
2. 集群规模括缩容
3. 垂直括缩：修改容器CPU/内存、持久卷大小
4. 节点崩溃后自动故障转移
5. 备份Galera集群到外部S3存储
6. 从外部备份恢复Galera集群

来自 severalnines / galera-docker-mariadb。此方案在K8S中运行Maria DB 10.1，支持Galera，需要同时运行一个Etcd集群。

逻辑比较乱，主要是通过查询Etcd来获得集群节点列表、各节点的seqno信息：

#!/bin/bash
set -e

# if command starts with an option, prepend mysqld
if [ "${1:0:1}" = '-' ]; then
  CMDARG="$@"
fi

[ -z "$TTL" ] && TTL=10

if [ -z "$CLUSTER_NAME" ]; then
  echo >&2 'Error:  You need to specify CLUSTER_NAME'
  exit 1
fi

DATADIR="$("mysqld" --verbose --help 2>/dev/null | awk '$1 == "datadir" { print $2; exit }')"
echo >&2 "Content of $DATADIR:"
ls -al $DATADIR

if [ ! -s "$DATADIR/grastate.dat" ]; then
  # 没有grastate.dat文件，意味着集群尚未初始化
  INITIALIZED=1
  if [ -z "$MYSQL_ROOT_PASSWORD" -a -z "$MYSQL_ALLOW_EMPTY_PASSWORD" -a -z "$MYSQL_RANDOM_ROOT_PASSWORD" ]; then
    echo >&2 'error: database is uninitialized and password option is not specified '
    echo >&2 '  You need to specify one of MYSQL_ROOT_PASSWORD, MYSQL_ALLOW_EMPTY_PASSWORD and MYSQL_RANDOM_ROOT_PASSWORD'
    exit 1
  fi
  mkdir -p "$DATADIR"
  chown -R mysql:mysql "$DATADIR"

  # 初始化MariaDB
  echo 'Running mysql_install_db'
  mysql_install_db --user=mysql --datadir="$DATADIR" --rpm
  echo 'Finished mysql_install_db'

  # 在后台启动MariaDB
  mysqld --user=mysql --datadir="$DATADIR" --skip-networking &
  pid="$!"

  mysql=(mysql --protocol=socket -uroot)

  # 等待MariaDB初始化完毕
  for i in {30..0}; do
    if echo 'SELECT 1' | "${mysql[@]}" &>/dev/null; then
      break
    fi
    echo 'MySQL init process in progress...'
    sleep 1
  done
  if [ "$i" = 0 ]; then
    echo >&2 'MySQL init process failed.'
    exit 1
  fi

  # sed is for https://bugs.mysql.com/bug.php?id=20545
  mysql_tzinfo_to_sql /usr/share/zoneinfo | sed 's/Local time zone must be set--see zic manual page/FCTY/' | "${mysql[@]}" mysql
  if [ ! -z "$MYSQL_RANDOM_ROOT_PASSWORD" ]; then
    MYSQL_ROOT_PASSWORD="$(pwmake 128)"
    echo "GENERATED ROOT PASSWORD: $MYSQL_ROOT_PASSWORD"
  fi

  # 在本地（禁止复制）创建root xtrabackup等用户
  "${mysql[@]}" <<-EOSQL
	  -- What's done in this file shouldn't be replicated
	  --  or products like mysql-fabric won't work
	  SET @@SESSION.SQL_LOG_BIN=0;
	  DELETE FROM mysql.user ;
	  CREATE USER 'root'@'%' IDENTIFIED BY '${MYSQL_ROOT_PASSWORD}' ;
	  GRANT ALL ON *.* TO 'root'@'%' WITH GRANT OPTION ;
	  CREATE USER 'xtrabackup'@'localhost' IDENTIFIED BY '$XTRABACKUP_PASSWORD';
	  GRANT RELOAD,LOCK TABLES,REPLICATION CLIENT ON *.* TO 'xtrabackup'@'localhost';
	  GRANT REPLICATION CLIENT ON *.* TO monitor@'%' IDENTIFIED BY 'monitor';
	  DROP DATABASE IF EXISTS test ;
	  FLUSH PRIVILEGES ;
EOSQL
  if [ ! -z "$MYSQL_ROOT_PASSWORD" ]; then
    mysql+=(-p"${MYSQL_ROOT_PASSWORD}")
  fi

  # 创建额外的数据库、用户
  if [ "$MYSQL_DATABASE" ]; then
    echo "CREATE DATABASE IF NOT EXISTS \`$MYSQL_DATABASE\` ;" | "${mysql[@]}"
    mysql+=("$MYSQL_DATABASE")
  fi

  if [ "$MYSQL_USER" -a "$MYSQL_PASSWORD" ]; then
    echo "CREATE USER '"$MYSQL_USER"'@'%' IDENTIFIED BY '"$MYSQL_PASSWORD"' ;" | "${mysql[@]}"

    if [ "$MYSQL_DATABASE" ]; then
      echo "GRANT ALL ON \`"$MYSQL_DATABASE"\`.* TO '"$MYSQL_USER"'@'%' ;" | "${mysql[@]}"
    fi

    echo 'FLUSH PRIVILEGES ;' | "${mysql[@]}"
  fi

  if [ ! -z "$MYSQL_ONETIME_PASSWORD" ]; then
    "${mysql[@]}" <<-EOSQL
		ALTER USER 'root'@'%' PASSWORD EXPIRE;
EOSQL
  fi
  if ! kill -s TERM "$pid" || ! wait "$pid"; then
    echo >&2 'MySQL init process failed.'
    exit 1
  fi

  echo
  echo 'MySQL init process done. Ready for start up.'
  echo
fi
chown -R mysql:mysql "$DATADIR"

function join {
  local IFS="$1"
  shift
  echo "$*"
}


# 将当前MariaDB实例加入到Galera集群，通过访问Etcd获取必要信息
if [ -z "$DISCOVERY_SERVICE" ]; then
  cluster_join=$CLUSTER_JOIN
else
  echo
  echo '>> Registering in the discovery service'

  etcd_hosts=$(echo $DISCOVERY_SERVICE | tr ',' ' ')
  flag=1

  echo
  # 寻找健康Etcd节点
  for i in $etcd_hosts; do
    echo ">> Connecting to https://${i}/health"
    curl -s -k --cacert /etc/etcd/ca.crt --cert /etc/etcd/client.crt --key /etc/etcd/client.key https://${i}/health || continue
    if curl -s -k --cacert /etc/etcd/ca.crt --cert /etc/etcd/client.crt --key /etc/etcd/client.key https://$i/health | jq -e 'contains({ "health": "true"})'; then
      healthy_etcd=$i
      flag=0
      break
    else
      echo >&2 ">> Node $i is unhealty. Proceed to the next node."
    fi
  done

  # 如果没有Etcd节点则放弃
  if [ $flag -ne 0 ]; then
    echo ">> Couldn't reach healthy etcd nodes."
    exit 1
  fi

  echo
  echo ">> Selected healthy etcd: $healthy_etcd"

  if [ ! -z "$healthy_etcd" ]; then
    URL="https://$healthy_etcd/v2/keys/galera/$CLUSTER_NAME"

    set +e
    echo >&2 ">> Waiting for $TTL seconds to read non-expired keys.."
    # 防止刚刚死去的Galera节点的注册信息仍然存在
    sleep $TTL

    # 获取活动Galera节点列表
    echo >&2 ">> Retrieving list of keys for $CLUSTER_NAME"
    addr=$(curl -s -k --cacert /etc/etcd/ca.crt --cert /etc/etcd/client.crt --key /etc/etcd/client.key $URL | jq -r '.node.nodes[]?.key' | awk -F'/' '{print $(NF)}')
    cluster_join=$(join , $addr)

    ipaddr=$(hostname -i | awk {'print $1'})
    [ -z $ipaddr ] && ipaddr=$(hostname -I | awk {'print $1'})

    echo
    if [ -z $cluster_join ]; then
      # 没有活动Galera节点。集群尚未初始化，或者集群完全宕机后重启（需要bootstrap）
      echo >&2 ">> KV store is empty. This is a the first node to come up."
      echo
      echo >&2 ">> Registering $ipaddr in https://$healthy_etcd"
      # 写入当前节点信息到Etcd
      curl -s -k --cacert /etc/etcd/ca.crt --cert /etc/etcd/client.crt --key /etc/etcd/client.key $URL/$ipaddr/ipaddress -X PUT -d "value=$ipaddr"
    else
      # 存在活动的Galera节点，看看有没有Synced的
      curl -s -k --cacert /etc/etcd/ca.crt --cert /etc/etcd/client.crt --key /etc/etcd/client.key ${URL}?recursive=true\&sorted=true >/tmp/out
      running_nodes=$(cat /tmp/out | jq -r '.node.nodes[].nodes[]? | select(.key | contains ("wsrep_local_state_comment")) | select(.value == "Synced") | .key' | awk -F'/' '{print $(NF-1)}' | tr "\n" ' ' | sed -e 's/[[:space:]]*$//')
      echo
      echo ">> Running nodes: [${running_nodes}]"

      if [ -z "$running_nodes" ]; then
        # 没有Synced节点，必须恢复本节点的seqno，如果本节点最大，则可以自举
        TMP=/var/lib/mysql/$(hostname).err
        echo >&2 ">> There is no node in synced state."
        echo >&2 ">> It's unsafe to bootstrap unless the sequence number is the latest."
        echo >&2 ">> Determining the Galera last committed seqno using --wsrep-recover.."
        echo

        # 恢复seqno
        mysqld_safe --wsrep-cluster-address=gcomm:// --wsrep-recover
        cat $TMP
        seqno=$(cat $TMP | tr ' ' "\n" | grep -e '[a-z0-9]*-[a-z0-9]*:[0-9]' | head -1 | cut -d ":" -f 2)
        # 此容器是新启动的，才会设置INITIALIZED。对于新节点，seqno设置为0
        if [ $INITIALIZED -eq 1 ]; then
          echo >&2 ">> This is a new container, thus setting seqno to 0."
          seqno=0
        fi

        echo
        if [ ! -z $seqno ]; then
          # 将当前节点的seqno写入到Etcd
          echo >&2 ">> Reporting seqno:$seqno to ${healthy_etcd}."
          WAIT=$(($TTL * 2))
          curl -s -k --cacert /etc/etcd/ca.crt --cert /etc/etcd/client.crt --key /etc/etcd/client.key $URL/$ipaddr/seqno -X PUT -d "value=$seqno&ttl=$WAIT"
        else
          seqno=$(cat $TMP | tr ' ' "\n" | grep -e '[a-z0-9]*-[a-z0-9]*:[0-9]' | head -1)
          echo >&2 ">> Unable to determine Galera sequence number."
          exit 1
        fi
        rm $TMP

        echo
        echo >&2 ">> Sleeping for $TTL seconds to wait for other nodes to report."
        sleep $TTL

        echo
        echo >&2 ">> Retrieving list of seqno for $CLUSTER_NAME"
        bootstrap_flag=1

        # Retrieve seqno from etcd
        curl -s -k --cacert /etc/etcd/ca.crt --cert /etc/etcd/client.crt --key /etc/etcd/client.key ${URL}?recursive=true\&sorted=true >/tmp/out
        cluster_seqno=$(cat /tmp/out | jq -r '.node.nodes[].nodes[]? | select(.key | contains ("seqno")) | .value' | tr "\n" ' ' | sed -e 's/[[:space:]]*$//')

        for i in $cluster_seqno; do
          if [ $i -gt $seqno ]; then
            # 如果存在其它节点的seqno更大，本节点不处理bootstrap
            bootstrap_flag=0
            echo >&2 ">> Found another node holding a greater seqno ($i/$seqno)"
          fi
        done

        echo
        if [ $bootstrap_flag -eq 1 ]; then
          # 本节点seqno最大，处理bootstrap
          # Find the earliest node to report if there is no higher seqno
          # node_to_bootstrap=$(cat /tmp/out | jq -c '.node.nodes[].nodes[]?' | grep seqno | tr ',:\"' ' ' | sort -k 11 | head -1 | awk -F'/' '{print $(NF-1)}')
          ## The earliest node to report if there is no higher seqno is computed wrongly: issue #6
          node_to_bootstrap=$(cat /tmp/out | jq -c '.node.nodes[].nodes[]?' | grep seqno | tr ',:"' ' ' | sort -k5,5r -k11 | head -1 | awk -F'/' '{print $(NF-1)}')
          if [ "$node_to_bootstrap" == "$ipaddr" ]; then
            echo >&2 ">> This node is safe to bootstrap."
            cluster_join=
          else
            echo >&2 ">> Based on timestamp, $node_to_bootstrap is the chosen node to bootstrap."
            echo >&2 ">> Wait again for $TTL seconds to look for a bootstrapped node."
            sleep $TTL
            curl -s -k --cacert /etc/etcd/ca.crt --cert /etc/etcd/client.crt --key /etc/etcd/client.key ${URL}?recursive=true\&sorted=true >/tmp/out

            # Look for a synced node again
            running_nodes2=$(cat /tmp/out | jq -r '.node.nodes[].nodes[]? | select(.key | contains ("wsrep_local_state_comment")) | select(.value == "Synced") | .key' | awk -F'/' '{print $(NF-1)}' | tr "\n" ' ' | sed -e 's/[[:space:]]*$//')

            echo
            echo >&2 ">> Running nodes: [${running_nodes2}]"

            if [ ! -z "$running_nodes2" ]; then
              cluster_join=$(join , $running_nodes2)
            else
              echo
              echo >&2 ">> Unable to find a bootstrapped node to join."
              echo >&2 ">> Exiting."
              exit 1
            fi
          fi
        else
          # seqno不是最大的，不处理bootstrap
          echo >&2 ">> Refusing to start for now because there is a node holding higher seqno."
          echo >&2 ">> Wait again for $TTL seconds to look for a bootstrapped node."
          sleep $TTL

          # Look for a synced node again
          curl -s -k --cacert /etc/etcd/ca.crt --cert /etc/etcd/client.crt --key /etc/etcd/client.key ${URL}?recursive=true\&sorted=true >/tmp/out
          running_nodes3=$(cat /tmp/out | jq -r '.node.nodes[].nodes[]? | select(.key | contains ("wsrep_local_state_comment")) | select(.value == "Synced") | .key' | awk -F'/' '{print $(NF-1)}' | tr "\n" ' ' | sed -e 's/[[:space:]]*$//')

          echo
          echo >&2 ">> Running nodes: [${running_nodes3}]"

          if [ ! -z "$running_nodes2" ]; then
            cluster_join=$(join , $running_nodes3)
          else
            echo
            echo >&2 ">> Unable to find a bootstrapped node to join."
            echo >&2 ">> Exiting."
            exit 1
          fi
        fi
      else
        # if there is a Synced node, join the address
        cluster_join=$(join , $running_nodes)
      fi
    fi
    set -e

    echo
    echo >&2 ">> Cluster address is gcomm://$cluster_join"
  else
    echo
    echo >&2 '>> No healthy etcd host detected. Refused to start.'
    exit 1
  fi
fi

echo
echo >&2 ">> Starting reporting script in the background"
nohup /report_status.sh root $MYSQL_ROOT_PASSWORD $CLUSTER_NAME $TTL $DISCOVERY_SERVICE &

# set IP address based on the primary interface
sed -i "s|WSREP_NODE_ADDRESS|$ipaddr|g" /etc/my.cnf

echo
echo >&2 ">> Starting mysqld process"
if [ -z $cluster_join ]; then
  export _WSREP_NEW_CLUSTER='--wsrep-new-cluster'
  # set safe_to_bootstrap = 1
  GRASTATE=$DATADIR/grastate.dat
  [ -f $GRASTATE ] && sed -i "s|safe_to_bootstrap.*|safe_to_bootstrap: 1|g" $GRASTATE
else
  export _WSREP_NEW_CLUSTER=''
fi

exec mysqld --wsrep_cluster_name=$CLUSTER_NAME --wsrep-cluster-address="gcomm://$cluster_join" --wsrep_sst_auth="xtrabackup:$XTRABACKUP_PASSWORD" $_WSREP_NEW_CLUSTER $CMDARG

该脚本会每TTL报告一次当前Galera容器的状态。

如果Galera集群名字为my_wsrep_cluster，则此方案会在Etcd中存储以下数据：

// url -s "http://192.168.55.111:2379/v2/keys/galera/my_wsrep_cluster?recursive=true"
{
    "action": "get",
    "node": {
        "createdIndex": 10049,
        "dir": true,
        "key": "/galera/my_wsrep_cluster",
        "modifiedIndex": 10049,
        "nodes": [
            {
                "createdIndex": 10067,
                "dir": true,
                // 每个节点在 /galera/$CLUSTER_NAME/下有个键
                "key": "/galera/my_wsrep_cluster/10.255.0.6",
                "modifiedIndex": 10067,
                "nodes": [
                    {
                        "createdIndex": 10075,
                        "expiration": "2016-11-29T10:55:35.37622336Z",
                        // 存储节点seqno
                        "key": "/galera/my_wsrep_cluster/10.255.0.6/wsrep_last_committed",
                        "modifiedIndex": 10075,
                        "ttl": 10,
                        "value": "0"
                    },
                    {
                        "createdIndex": 10073,
                        "expiration": "2016-11-29T10:55:34.788170259Z",
                        // 存储节点状态
                        "key": "/galera/my_wsrep_cluster/10.255.0.6/wsrep_local_state_comment",
                        "modifiedIndex": 10073,
                        "ttl": 10,
                        "value": "Synced"
                    }
                ]
            }...
        ]
    }
}

The post Galera学习笔记 appeared first on 绿色记忆.

Prometheus是一个开源监控系统，它既适用于面向服务器等硬件指标的监控，也适用于高动态的面向服务架构的监控。对于现在流行的微服务，Prometheus的多维度数据收集和数据筛选查询语言也是非常的强大。

Prometheus的主要特性包括：

1. 多维度数据模型
2. 灵活的查询语言
3. 不依赖分布式存储，单个服务器节点是自治的
4. 通过服务（sd，准确的说是监控目标）发现或者静态配置，来发现目标服务对象
5. 支持多种多样的图表和界面展示，可以和Grafana集成
6. 数据采集方式：
   1. Pull：通过HTTP协议定期去采集指标，只要被监控系统提供HTTP接口即可接入
   2. Push：被监控系统主动推送指标到网关，Prometheus定期从网关Pull

Prometheus包括以下组件：

1. Prometheus Server：负责抓取和存储时间序列数据
2. Push Gateway：推送网关，第三方可以推送数据到此网关，Prometheus Server再从此网关拉取数据
3. 多种导出工具，支持导出Graphite、StatsD等所需的格式
4. 命令行查询工具
5. Alert Manager：告警管理器
6. PromQL查询语言

Prometheus中所有数据都存放为时间序列——具有时间戳的数据流，这些数据属于同一指标、以及由一系列标签定义的维度集。每个时间序列由指标名+标签集唯一的识别，标签由键、值组成。时间序列通常使用如下记号表示：

<metric name>{<label name>=<label value>, ...}
# 示例：
api_http_requests_total{method="POST", handler="/messages"}

指标名是需要监控系统特性的一般性名称，例如http_requests_total可以表示HTTP请求计数。

标签为一个具体的指标“实例”提供维度信息。使用PromQL你可以基于标签进行过滤、分组。增加、修改、删除某个标签，则新的时间序列会被创建。标签名只能ASCII字符，但是标签值可以是任何Unicode字符。

样本（Sample）构成了实际的时间序列的数据点。样本由float64类型的数值+毫秒精度的时间戳组成。

Prometheus的客户端库区分了4种指标类型，目前服务器端不理解这些类型的不同，但是未来可能改变。

# prometheus_tsdb_compaction_chunk_range_count{instance="localhost:9090"}
# 样本总数
tsdb_compaction_chunk_range_count{}                   64388371

# prometheus_tsdb_compaction_chunk_range_sum{instance="localhost:9090"}
# 所有样本的值的总和
tsdb_compaction_chunk_range_sum{}                     456743796630059

# sort(prometheus_tsdb_compaction_chunk_range_bucket{instance="localhost:9090"})
# 值小于25600的样本数量
tsdb_compaction_chunk_range_bucket{le="25600"         1301
tsdb_compaction_chunk_range_bucket{le="400"}          1301
tsdb_compaction_chunk_range_bucket{le="100"}          1301
tsdb_compaction_chunk_range_bucket{le="1600"}         1301
tsdb_compaction_chunk_range_bucket{le="6400"}         1301
tsdb_compaction_chunk_range_bucket{le="102400"}       20000
tsdb_compaction_chunk_range_bucket{le="409600"}       108533
tsdb_compaction_chunk_range_bucket{le="1.6384e+06"}   254369
tsdb_compaction_chunk_range_bucket{le="6.5536e+06"}   655322
tsdb_compaction_chunk_range_bucket{le="2.62144e+07"}  64272199
# 所有样本数量
tsdb_compaction_chunk_range_bucket{le="+Inf"}         64272199

// 估算99分位数
histogram_quantile(0.99, 
  // 以le分组求和
  sum(
    // 以interval为区间获得平均值
    irate(
      istio_request_duration_seconds_bucket{
        reporter="destination",
        destination_workload=~"$workload",
        destination_workload_namespace=~"$namespace"
      }[$interval]
    )
  ) by (le)
)

# 样本总数
tsdb_wal_fsync_duration_seconds_count{job="prometheus"}                  369717
# 样本值总和
tsdb_wal_fsync_duration_seconds_sum{job="prometheus"}                   24423.798953890488
# 中位数耗时0.05秒，也就是说，有一半的磁盘同步操作在0.05秒内完成
tsdb_wal_fsync_duration_seconds{job="prometheus",quantile="0.5"}	0.053841949
# 九分位数耗时0.12秒，也就是说，90%的磁盘同步操作都在0.12秒内完成
tsdb_wal_fsync_duration_seconds{job="prometheus",quantile="0.9"}	0.116763012
tsdb_wal_fsync_duration_seconds{job="prometheus",quantile="0.99"}	0.263791273

一个你可以从中抓取监控数据的endpoint称为实例（Instance），实例通常对应一个进程，例如NodeExporter、RedisExporter……

一系列相同目的的实例，称为Job。多实例的原因可能是为了可靠性、扩容。

当Prometheus服务器抓取数据时，它会自动为时间序列添加标签：

1. job，抓取目标所属的Job的名称
2. instance，目标从什么host:port抓取得到

如果上述两个标签已经存在于抓取的数据上，则配置项honor_labels影响服务器的行为。

除了添加标签之外，还会为以下时间序列添加样本：

1. up{job="<job-name>", instance="<instance-id>"}:1/0。如果实例可达则取值1，否则0
2. scrape_duration_seconds{job="<job-name>", instance="<instance-id>"}:抓取目标消耗的时间
3. scrape_samples_post_metric_relabeling{job="<job-name>", instance="<instance-id>"}:指标重打标签后，剩余的样本数量
4. scrape_samples_scraped{job="<job-name>", instance="<instance-id>"}: 目标暴露的样本数量

Graphite专注于作为一个被动的时间序列数据库，同时提供查询语言、图形化特性。Prometheus则是一个全功能的监控和趋势分析系统，内置主动拉取、存储、图形化、报警功能。

Graphite存储数字采样，但是其元数据模型不如Prometheus丰富。Graphite的指标名称使用点号分隔的单词，暗含维度信息。Prometheus则将维度信息作为明确的标签存储。Prometheus更容易支持过滤、分组操作。

Graphite在本地磁盘上，以Whisper格式存储时间序列数据。每个时间序列存储一个文件，一段时间后，新采样会覆盖旧采样，此外采样频率是固定的。Prometheus也是每个时间序列对应一个文件，但是采样频率是动态的，新数据简单的Append到文件尾部。

InfluxDB的持续查询类似于Prometheus的Recording规则。Kapacitor类似于Recording规则、Alerting规则和Alertmanager的通知功能的组合。Alertmanager具有额外的分组、去重、静默功能。

InfluxDB的Tag和Prometheus的Label一样，都是键值对形式的维度信息。InfluxDB还提供第二级的“标签”——字段（Field）

helm install gmem/prometheus --name prometheus --namespace=kube-system

此Chart的定义位于：https://github.com/gmemcc/charts/tree/master/prometheus

安装完毕，到https://prometheus.k8s.gmem.cc/targets可以查看各监控目标的状态。

wget https://github.com/prometheus/prometheus/releases/download/v2.2.1/prometheus-2.2.1.linux-amd64.tar.gz
tar xzf prometheus-2.2.1.linux-amd64.tar.gz
rm prometheus-2.2.1.linux-amd64.tar.gz
mv prometheus-2.2.1.linux-amd64 prometheus
cd prometheus
./prometheus --config.file="prometheus.yml"       # 指定配置文件
             --web.listen-address="0.0.0.0:9090"  # UI/API/Telemetry监听地址
             --storage.tsdb.path="data/"          # 时间序列数据库存储路径
             --storage.tsdb.retention=15d         # 时间序列数据存储时长
             # 等待处理的的告警管理器通知队列长度
             --alertmanager.notification-queue-capacity=10000
             --alertmanager.timeout=10s           # 发送告警给告警管理器的超时

Prometheus通过命令行、配置文件进行配置。命令行参数可以配置一些不变的系统参数，例如存储位置、存留在内存和磁盘中的数据量。配置文件则用于指定Job、Instance、Rule的配置。

配置文件的格式是YAML，使用--config.file指定配置文件的位置。本节列出重要的配置项。

global:
  # 默认抓取周期，可用单位ms、smhdwy
  [ scrape_interval: <duration> | default = 1m ]
  # 默认抓取超时
  [ scrape_timeout: <duration> | default = 10s ]
  # 估算规则的默认周期
  [ evaluation_interval: <duration> | default = 1m ]
  # 和外部系统（例如AlertManager）通信时为时间序列或者警情（Alert）强制添加的标签列表
  external_labels:
    [ <labelname>: <labelvalue> ... ]

# 规则文件列表
rule_files:
  [ - <filepath_glob> ... ]

# 抓取配置列表
scrape_configs:
  [ - <scrape_config> ... ]

# 和Alertmanager相关的配置
alerting:
  alert_relabel_configs:
    [ - <relabel_config> ... ]
  alertmanagers:
    [ - <alertmanager_config> ... ]

# 和远程读写特性相关的配置
remote_write:
  [ - <remote_write> ... ]
remote_read:
  [ - <remote_read> ... ]

配置一系列的目标，以及如何抓取它们的参数。一般情况下，每个scrape_config对应单个Job。

目标可以在scrape_config中静态的配置，也可以使用某种服务发现机制动态发现。

# 任务名称，自动作为抓取到的指标的一个标签
job_name: <job_name>

# 抓取周期
[ scrape_interval: <duration> | default = <global_config.scrape_interval> ]
# 每次抓取的超时
[ scrape_timeout: <duration> | default = <global_config.scrape_timeout> ]
# 从目标抓取指标的URL路径
[ metrics_path: <path> | default = /metrics ]
# 当添加标签发现指标已经有同名标签时，是否保留原有标签不覆盖
[ honor_labels: <boolean> | default = false ]
# 抓取协议
[ scheme: <scheme> | default = http ]
# 可选的请求参数
params:
  [ <string>: [<string>, ...] ]

# 身份验证信息
basic_auth:
  [ username: <string> ]
  [ password: <secret> ]
  [ password_file: <string> ]
# Authorization请求头取值
[ bearer_token: <secret> ]
# 从文件读取Authorization请求头
[ bearer_token_file: /path/to/bearer/token/file ]

# TLS配置
tls_config:
  [ <tls_config> ]

# 代理配置
[ proxy_url: <string> ]

# DNS服务发现配置
dns_sd_configs:
  [ - <dns_sd_config> ... ]
# 文件服务发现配置
file_sd_configs:
  [ - <file_sd_config> ... ]
# K8S服务发现配置
kubernetes_sd_configs:
  [ - <kubernetes_sd_config> ... ]

# 此Job的静态配置的目标列表
static_configs:
  [ - <static_config> ... ]

# 目标重打标签配置
relabel_configs:
  [ - <relabel_config> ... ]
# 指标重打标签配置
metric_relabel_configs:
  [ - <relabel_config> ... ]

# 每次抓取允许的最大样本数量，如果在指标重打标签后，样本数量仍然超过限制，则整个抓取认为失败
# 0表示不限制
[ sample_limit: <int> | default = 0 ]

使用该配置，可以从K8S API Server暴露的REST API中发现抓取目标，并且和K8S集群保持同步。你可以配置以下role，以发现目标：

通常，你会给相关K8S资源添加以下注解：

annotations:                                                                                                                                                                           
  prometheus.io/path: /metrics                                                                                                                                                         
  prometheus.io/port: "8080"                                                                                                                                                           
  prometheus.io/scrape: "true"

并配合以下Relabel配置，提示这些资源需要作为Prometheus的抓取目标：

relabel_configs:
  - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
    action: keep
    regex: true
  - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_path]
    action: replace
    target_label: __metrics_path__
    regex: (.+)
  - source_labels: [__address__, __meta_kubernetes_pod_annotation_prometheus_io_port]
    action: replace
    regex: ([^:]+)(?::\d+)?;(\d+)
    replacement: $1:$2
    target_label: __address__ 

重打标签是动态修改目标的标签集的强大工具。每个抓取配置可以定义多个重打标签步骤，这些步骤按照声明顺序依次执行、在实际抓取指标数据之前执行。

在一开始，除了为每个目标配置的标签之外，目标的：

1. job标签被设置为抓取配置的job_name字段
2. __address__标签被设置为目标的<host>:<port>

在重打标签之后，目标的：

1. instance标签默认被设置为__address__，如果没有此标签的话
2. __scheme__标签被设置为http或https
3. __metrics_path__标签被设置为目标的指标路径，即URL路径
4. __param_<name>标签为请求时使用的每个参数

在重打标签期间，额外的 __meta_ 开头的元标签可用，这些标签由服务发现机制自动添加。

在重打标签结束后，以__开头的标签会被移除。

如果某个步骤需要临时的设置一些标签，仅仅作为后续步骤的输入，应当以__tmp作为前缀。

每个重打标签步骤（relabel_configs的元素）具有以下子配置项：

# 从已有的标签中选取值
[ source_labels: '[' <labelname> [, ...] ']' ]
# 并且使用下面的分隔符连接那些值
[ separator: <string> | default = ; ]
# 然后基于下面的正则式进行匹配，或者保留，或者替换，或者删除

# 对于替换操作来说，替换为的目标标签的名字，可以使用正则式捕获组
[ target_label: <labelname> ]

# 用于匹配源标签值的正则式
[ regex: <regex> | default = (.*) ]

# 用于获取源标签值的哈希的模数
[ modulus: <uint64> ]

# 如果正则式匹配，使用什么替换值，可以使用正则式捕获组
[ replacement: <string> | default = $1 ]

# 如果正则式匹配，执行何种操作
# replace 如果正则式匹配source_labels的值，则设置target_label为指定的内容
# keep 如果正则式匹配，维持目标不变
# drop 如果正则式匹配，丢弃目标
# hashmod 设置target_label标签名为source_labels的值的哈希的取模
# labelmap 针对所有标签名来匹配regex，然后将匹配的标签的值拷贝到replacement所指定的新标签中
# labeldrop 针对所有标签来匹配regex，不匹配的标签都丢弃
# labelkeep 针对所有标签来匹配regex，匹配的标签都丢弃
[ action: <relabel_action> | default = replace ]

重打标签配置示例：

# 将元标签__meta_kubernetes_pod_node_name替换为nodename
- source_labels: [__meta_kubernetes_pod_node_name]
  action: replace
  target_label: nodename 

在存储（ingestion）样本数据之前，作为最后一个步骤，配置同上。可以用于屏蔽存储成本过高的时间序列。

Prometheus使用YAML格式的配置文件，默认的配置文件内容如下：

# Prometheus服务器的全局配置
global:
  # 拉取Target的间隔，默认1分钟
  scrape_interval:     15s 
  # 执行Rule的间隔，默认1分钟
  evaluation_interval: 15s 
  # 拉取Target的超时时间
  scrape_timeout: 10s      

# 报警管理器配置
alerting:
  alertmanagers:
  - static_configs:
    - targets:
      - alertmanager:9093

# 加载规则文件，并每evaluation_interval执行规则一次
rule_files:
  - "first_rules.yml"
  - "second_rules.yml"

# 拉取配置，说明Prometheus需要监控什么
scrape_configs:
  # 这个默认抓取任务，监控Prometheus服务器自己（Prometheus通过HTTP暴露了自己的Metrics）
  - job_name: 'prometheus'
    metrics_path: /metrics
    scheme: http
    static_configs:
      # 此Job仅具有一个目标
      - targets: ['localhost:9090']

Prometheus提供了一种查询语言，用来实时的查询、聚合时间序列数据。查询结果可以在Prometheus的WebUI中展示，或者通过HTTP API暴露给第三方系统。

# 返回一个指标的所有时间序列
http_requests_total
# 返回一个指标具有特定Label的时间序列
http_requests_total{job="apiserver", handler="/api/comments"}
# 在满足上一条的前提下，返回5分钟内所有时间序列，并形成范围矢量（range vector）
http_requests_total{job="apiserver", handler="/api/comments"}[5m]
# 支持使用正则式来匹配Label
http_requests_total{job=~".*server"}
# 反向匹配
http_requests_total{status!~"4.."}

# 以最近5分钟的范围矢量为基础，统计每秒的数据增量
rate(http_requests_total[5m])

# 按Label job进行分组统计
sum(rate(http_requests_total[5m])) by (job)
# 如果两个指标具有相同的Label（维度信息），则可以对指标值进行运算
sum(
  instance_memory_limit_bytes - instance_memory_usage_bytes
) by (app, proc) / 1024 / 1024

# 取前三
topk(3, sum(rate(instance_cpu_time_ns[5m])) by (app, proc))

匹配单个时间点的一个或多个时间序列的采样：

# 选择指标的所有时间序列
http_requests_total
# 根据标签匹配
http_requests_total{job="prometheus",group="canary"}

匹配标签时可以使用四种操作符：=、!=、=~、!~，前两者用于精确匹配，后两者用于正则式匹配：

http_requests_total{environment=~"staging|testing|development",method!="GET"}

只需要在瞬时矢量选择器后面添加

[timePeriod]

http_requests_total{job="prometheus"}[5m]

# 获取相对当前查询时间，之前5分钟的数据
http_requests_total offset 5m

# 一周前的每秒请求数
rate(http_requests_total[5m] offset 1w)

算术：加减乘除、取模、乘方（^）。可以在两个标量、标量vs瞬时矢量、 两个瞬时矢量之间进行。

比较：== != > >= < <=。可以在两个标量、标量vs瞬时矢量、 两个瞬时矢量之间进行。

逻辑：and or unless。仅仅用于两个瞬时矢量之间：

1. and，取v1 v2中具有完全一致Label的那些时间序列，构成v3返回
2. or，取v1所有时间序列，外加v2中那些Label在v1中不存在的时间序列，构成v3返回
3. unless，取v1中那些没有在v2中具有相同Label的时间序列

对两个瞬时矢量应用操作符时，牵涉到如何找到左侧矢量元素在右侧矢量中的匹配元素的问题。匹配都是基于Label的。

矢量匹配的行为有两种：1对1匹配，1对多匹配：

vector1 <operator> vector2

# 匹配时忽略一些标签
<vector expr> <bin-op> ignoring(<label list>) <vector expr>
# 仅仅针对某些标签进行匹配
<vector expr> <bin-op> on(<label list>) <vector expr>

# 500错误占比分析
method_code:http_errors:rate5m{code="500"} / ignoring(code) method:http_requests:rate5m

操作符列表：

操作符	说明	操作符	说明
min	最小值	max	最大值
sum	求和	avg	求平均
count	统计数量	count_values	统计同值元素量
bottomk	最小N元素	topk	最大N元素
quantile	分位数（例如求中位数）

语法：

<aggr-op>([parameter,] <vector expression>) [without|by (<label list>)]
# parameter：仅count_values, quantile, topk, bottomk需要
# without：从结果矢量中移除指定的标签
# by：仅仅保留指定的标签

# 示例：
sum(http_requests_total) without (instance)
sum(http_requests_total) by (application, group)
count_values("version", build_version)
topk(5, http_requests_total)

不能对已经聚合过的数据再进行rate，只能对原始counter进行rate。正确的示例：

# 对平均值，按service进行分组
    # 对每个指标求每分钟平均值
sum(rate(dubbo_consumer_elapsed_ms{kubernetes_namespace="$namespace"}[2m]) * 60) by (service)    /
# 分组之后的数据仍然可以进行算术运算，按service值分别进行运算
sum(rate(dubbo_consumer_success_count{kubernetes_namespace="$namespace"}[2m]) * 60) by (service)

这里使用Helm Chart方式安装，Chart的源码位于：

https://git.gmem.cc/alex/helm-charts/src/branch/master/prometheus。

安装脚本如下：

rm -rf prometheus
helm fetch gmem/prometheus --untar
helm install prometheus --name=prometheus --namespace=kube-system  -f prometheus/overrides/gmem.yaml

上面的Chart默认配置了以下Job：

启动Prometheus后，访问http://localhost:9090/metrics可以查看Prometheus本身的指标信息：

# curl http://localhost:9090/metrics
# 输出示意片断
# HELP http_requests_total Total number of HTTP requests made.
# TYPE http_requests_total counter
# 指标名             {标签=值,标签=值...}                       指标值
http_requests_total{code="200",handler="graph",method="get"} 3
http_requests_total{code="200",handler="label_values",method="get"} 5
http_requests_total{code="200",handler="prometheus",method="get"} 4105
http_requests_total{code="200",handler="query",method="get"} 13
http_requests_total{code="200",handler="query_range",method="get"} 3
http_requests_total{code="200",handler="static",method="get"} 26
http_requests_total{code="304",handler="static",method="get"} 20
# 在http://localhost:9090/graph的控制台中输入http_requests_total进行查询，也可以得到上面的输出

http_requests_total是Prometheus暴露（Export）的关于自身的指标 —— 接受的HTTP请求总数，包括了多个时间序列数据。这些时间序列数据的指标名都一样，但是具有不同的标签，这些标签用于区分不同类型的HTTP请求。

我们可以在控制台输入

http_requests_total{code="200"}

类似的，还可以使用表达式

count(http_requests_total)

在http://localhost:9090/graph页面，点击Graph选项卡，可以生成图表。例如表达式

rate(http_requests_total[1m])

Node Exporter是Prometheus提供的，用于监控Linux系统的组件。对于Windows，则有功能类似的WMIExporter。

下载NodeExporter后运行，它默认会在9100端口上暴露本机的各项指标。你可以访问http://localhost:9100/metrics来查看。修改Prometheus默认配置文件尾部的9090端口为9100即可采集这些指标。

这个项目是Google开源的，专门采集容器资源用量、性能指标。cAdvisor嵌入在kubelet中运行。

此项目可以暴露JMX管理Beans给Prometheus采集。它作为Java Agent运行，开启一个HTTP端口，对外提供本地JVM的各项指标。

为JVM添加参数：

-javaagent:jmx_prometheus_javaagent-0.3.1.jar=9100:config.yaml

格式为YAML：

# 延迟于JVM启动HTTP端口的时间
startDelaySeconds: 0
# 如果连接到远程JVM，采集JMX信息，则要么指定hostPort，要么指定jmxUrl
hostPort: 127.0.0.1:1234
jmxUrl: service:jmx:rmi:///jndi/rmi://127.0.0.1:1234/jmxrmi
# 远程JMX身份验证信息
username: 
password: 
# 远程JMX是否通过SSL连接
ssl: false
# 是否小写化指标名、标签名
lowercaseOutputName: false
lowercaseOutputLabelNames: false
# 是否采集的ObjectNames的白、黑名单。默认采集所有mBeans
whitelistObjectNames: ["org.apache.cassandra.metrics:*"]
blacklistObjectNames: ["org.apache.cassandra.metrics:type=ColumnFamily,*"]
# 规则列表，从上往下执行，遇到匹配的规则则终止
# 不匹配的Attributes不被采集，默认情况下，以默认格式采集所有
rules:
    # 匹配mBean Attributes的正则式
  - pattern: 'org.apache.cassandra.metrics<type=(\w+), name=(\w+)><>Value: (\d+)'
    # 指标名
    name: cassandra_$1_$2
    # 指标值
    value: $3
    # 指标值需要乘以的系数
    valueFactor: 0.001
    # 标签，可以使用捕获组
    labels: {}
    # 指标帮助信息
    help: "Cassandra metric $1 $2"
    # 指标类型
    type: GAUGE
    # 转换为下划线 + 小写风格
    attrNameSnakeCase: false

如果没有任何配置内容，则以默认格式采集本地JVM的所有指标。

官方提供了若干中间件的示例配置文件。 

传递给配置文件rules.pattern的格式为：

# domain mBean的名称，JMX ObjectNames的冒号前的部分
# beanProperyName/Value mBean属性列表，JMX ObjectNames的冒号后的部分
# keyN 如果是组合或表格数据，则包含键列表
# attrName 属性的名称，如果是表格数据，则为列名称。如果设置了attrNameSnakeCase则转换为下划线小写
# value 属性值
domain<beanpropertyName1=beanPropertyValue1, beanpropertyName2=beanPropertyValue2, ...><key1, key2, ...>attrName: value 

不经配置，输出的默认指标格式为：

domain_beanPropertyValue1_key1_key2_...keyN_attrName{beanpropertyName2="beanPropertyValue2", ...}: value 

Prometheus提供了主流语言的客户端库。要使用Prometheus的Go客户端库，导入：

import "github.com/prometheus/client_golang/prometheus"

该结构是任何Prometheus指标都需要使用的描述符，它本质上是指标（Metrics）的不可变元数据：

struct {
	// 全限定名称，由命名空间 - 子系统 - 名称组成
	fqName string
	// 指标的帮助信息
	help string
	// 常量标签键值
	constLabelPairs []*dto.LabelPair
	// 可变标签的名字
	variableLabels []string
	// 基于ConstLabels和fqName生成的哈希，所有注册的Desc都必须具有独特的值
        // 以作为Desc的唯一标识
	id uint64
	// 维度哈希，所有常量/可变标签的哈希，所有具有相同fqName的Desc必须具有相同的dimHash
	// 这意味着每个fqName对应的标签集是固定的
	dimHash uint64
	// 构造时出现的错误，注册时报告
	err error
}

所有指标的通用接口，表示需要导出到Prometheus的单个采样值+关联的元数据集 。此接口的实现包括Gauge、Counter、Histogram、Summary、Untyped。

type Metric interface {
	// 幂等的返回该指标的、不可变的描述符
	// 不能描述子集的指标，必须返回一个无效的描述符。无效描述符通过NewInvalidDesc创建
	Desc() *Desc
	// 将指标对象编码为ProtoBuffer数据传输对象
	// 指标实现必须考虑并发安全性，因为对指标的读可能随时发生，任何阻塞操作都会影响
	// 所有已经注册的指标的整体渲染性能
	// 理想的实现应该支持并发读
	//
	// 除了产生dto.Metric，实现还负责确保Metric的ProtoBuf合法性验证
	// 建议使用字典序排序标签，LabelPairSorter可能对指标实现者有帮助
	Write(*dto.Metric) error
}

此结构表示用于bundle全限定名称、标签值有所不同的指标。通常不会直接使用此结构，而是将它作为具体指标向量GaugeVec, CounterVec, SummaryVec,  UntypedVec的一部分：

type MetricVec struct {
	mtx      sync.RWMutex // 保护元素的锁
	children map[uint64][]metricWithLabelValues // 所有指标实例（值+标签集）
	desc     *Desc // 描述符

	newMetric   func(labelValues ...string) Metric  // 以指定的标签值创建新指标
	hashAdd     func(h uint64, s string) uint64
	hashAddByte func(h uint64, b byte) uint64
} 

创建大部分的指标类型时，可以通过该接口提供选项：

type Opts struct {
	// Namespace, Subsystem, Name是指标的全限定名称的组成部分，这些部分使用下划线连接
	// 仅仅Name是必须的
	Namespace string
	Subsystem string
	Name      string

	// 帮助信息，单个全限定名称，其帮助信息必须一样
	Help string

	// 常量标签用于为指标提供固定的标签，单个全限定名称，其常量标签集的所包含的标签名必须一致
	// 注意在大部分情况下，标签的值会变化，这些标签通常由指标矢量收集器（metric vector collector）来
	// 处理，例如CounterVec、GaugeVec、UntypedVec，而ConstLabels则仅用于特殊情况，例如：
	// vector collector (like CounterVec, GaugeVec, UntypedVec). ConstLabels
	// 1、在整个处理过程中，标签的值绝不会改变。这种标签例如运行中的二进制程序的修订版号
	// 2、在具有多个收集器（collector）来收集相同全限定名称的指标的情况下，那么每个收集器收集的
	//    指标的常量标签的值必须有所不同
	// 如果任何情况下，标签的值都不会改变，它可能更适合编码到全限定名称中
	ConstLabels Labels
}

任何Prometheus用来收集指标的对象，都需要实现此接口：

type Collector interface {
	// 将此收集器收集的指标的所有可能的描述符发送到参数提供的通道。并且在最后一个描述符
	// 发送成功后返回。发送的描述符必须满足Desc文档声明的一致性、唯一性要求
	// 
	// 同一收集器发送重复的描述符是允许的，重复自动忽视
	// 但是两个收集器不得发送重复的描述符
	//
	// 如果不发送任何描述符，则收集器标记为unchecked状态，也就是说在注册时，不会进行任何检查
	// 收集器以后可能产生任何匹配它的Collect方法签名的指标
	//
	// 该方法在收集器的生命周期里，幂等的发送相同的描述符
	// 
	// 该方法可能被并发的调用，实现时需要注意线程安全问题
	//
	// 如果在执行该方法的过程中收集器遇到错误，务必发送一个无效的描述符（NewInvalidDesc）来提示注册表
	Describe(chan<- *Desc)
	// 在收集指标时，该方法被Prometheus注册表（Registry）调用。方法的实现必须将所有它收集到的指标
	// 经由参数提供的通道发送，并且在最后一个指标发送后返回
	// 
	// 每个发送的指标的描述符，必须是Describe方法提供的之一（除非收集器是Unchecked）
	// 发送的共享相同描述符的指标，其标签集必须有所不同
	// 
	//
	// 该方法可能被并发的调用，实现时需要注意线程安全问题
	// 
	// 阻塞会导致影响所有已注册的指标的渲染性能，理想情况下，实现应该支持并发读
	Collect(chan<- Metric)
} 

收集器必须被注册（Registerer.Register）才能收集指标值。

内置的指标类型实现了此接口，包括GaugeVec、CounterVec、HistogramVec、SummaryVec。

注册表，此结构实现了Registerer、Gatherer接口。

Registerer接口为注册表提供注册/反注册功能：

type Registerer interface {
	// 注册一个需要包含在指标集中的收集器。如果收集器提供的描述符非法、
	// 或者不满足metric.Desc的一致性/唯一性需求，则返回错误
	//
	// 如果相等的收集器已经注册过，返回AlreadyRegisteredError，其中包含先前注册的收集器的实例
	//
	// 其Describe方法不产生任何Desc的收集器，视为Unchecked，对这种收集器的注册总是成功
	// 重现注册它时也不会有检查。因此，调用者必须负责确保不会重复注册
	Register(Collector) error
	// 注册多个收集器，并且在遇到第一个失败时就Panic
	MustRegister(...Collector)
	// 反注册
	Unregister(Collector) bool
}

Gatherer为注册表提供汇集（gathering）功能 —— 将已经收集的指标汇集到若干指标族（MetricFamily）中：

type Gatherer interface {
	// 该方法调用所有已经注册的收集器的Collect方法，然后将获得的指标存放到一个字典序排列
	// 的MetricFamily的切片中。该方法保证返回的切片是有效的、自我一致的，可以用于对外
	// 暴露（给Prometheus服务器）该方法容忍相同指标族中具有不同标签集的指标
	//
	// 即时发生错误，该方法也会尝试尽可能收集更多的指标。因此，当该方法返回非空error时
	// 同时返回的dto.MetricFamily切片可能是nil（意味着致命错误）或者包含一定数量的
	// MetricFamily —— 切片可能是不完整的
	Gather() ([]*dto.MetricFamily, error)
} 

表示gauge类型的指标： 

type Gauge interface {
	// 实现的接口
	Metric
	Collector

	// 设值
	Set(float64)
	// 增1
	Inc()
	// 减1
	Dec()
	// 加上一个值
	Add(float64)
	// 减去一个值
	Sub(float64)
}

要创建一个Gauge，可以调用：

func NewGauge(opts GaugeOpts) Gauge {
	// func newValue(desc *Desc, valueType ValueType, val float64, labelValues ...string) *value
	return newValue(NewDesc(
		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
		opts.Help,
		nil,
		opts.ConstLabels,
	), GaugeValue, 0)
}

GaugeVec表示Gauge的向量：

type GaugeVec struct {
	*MetricVec
}

表示histogram类型的指标。

Histogram对可配置的Bucket（观察值的区间）中的事件或样本流，基于Bucket进行独立计数观察。它支持对观察值（observations）进行计数，或者求和。

在Prometheus中，分位数可以基于Histogram，通过函数histogram_quantile计算得到。Histogram依赖于用户定义的、适当的buckets，一般来说精确度相对较低，但是和Summary比起来，Histogram的性能成本较低。

type Histogram interface {
	Metric
	Collector

	// 添加一个观察值
	Observe(float64)
}

默认的Buckets如下，主要用于测量网络响应延迟的场景：

DefBuckets = []float64{.005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10}

对于其它场景，你应当自己定义Buckets。 

我们不会直接操控指标，而是使用它们的向量 —— GaugeVec、CounterVec、HistogramVec、SummaryVec。这些向量都是Collector接口的实现。

要创建向量，需要调用prometheus.New***Vec方法，例如：

func NewGaugeVec(opts GaugeOpts, labelNames []string) *GaugeVec {
// 描述符，关键信息是全限定名 + 标签集
	desc := NewDesc(
		BuildFQName(opts.Namespace, opts.Subsystem, opts.Name),
		opts.Help,
		labelNames,
		opts.ConstLabels,
	)
	return &GaugeVec{
		metricVec: newMetricVec(desc, func(lvs ...string) Metric {
// 第二个参数是回调，标签集创建一个Metric —— 指标，准确的说是时间序列
			if len(lvs) != len(desc.variableLabels) {
				panic(makeInconsistentCardinalityError(desc.fqName, desc.variableLabels, lvs))
			}
			result := &gauge{desc: desc, labelPairs: makeLabelPairs(desc, lvs)}
			result.init(result) // Init self-collection.
			return result
		}),
	}
} 

下面的例子创建一个Gauge向量：

weight := prometheus.NewGaugeVec(prometheus.GaugeOpts{
	Subsystem: "flagger",
	Name:      "canary_weight",
	Help:      "The virtual service destination weight current value",
}, []string{"workload", "namespace"})  // 注意标签顺序

获取具有指定标签值的Gauge（时间序列）： 

// 注意标签值的顺序，和上面对应
gauge := cr.weight.WithLabelValues(cd.Spec.TargetRef.Name, cd.Namespace)

产生一个指标值：

gauge.Set(float64(canary))

下面的例子使用默认Bucket创建Histogram向量：

duration := prometheus.NewHistogramVec(prometheus.HistogramOpts{
	Subsystem: controllerAgentName,
	Name:      "canary_duration_seconds",
	Help:      "Seconds spent performing canary analysis.",
	Buckets:   prometheus.DefBuckets,
}, []string{"name", "namespace"})

产生一个指标值：

cr.duration.WithLabelValues(cd.Spec.TargetRef.Name, cd.Namespace).Observe(duration.Seconds())

Prometheus客户端提供了开箱即用的默认注册表：

prometheus.DefaultRegisterer

你可以调用以下函数来创建注册表：

// 不预先注册任何收集器的注册表
func NewRegistry() *Registry {
	return &Registry{
		collectorsByID:  map[uint64]Collector{},
		descIDs:         map[uint64]struct{}{},
		dimHashesByName: map[string]uint64{},
	}
}

// 创建一个严格的注册表。该注册表在收集期间，检查
// 1、每个指标是否和它的Desc一致
// 2、指标的Desc是否已经注册到注册表
// Unchecked的收集器不被检查
func NewPedanticRegistry() *Registry {
	r := NewRegistry()
	r.pedanticChecksEnabled = true
	return r
}

示例：

registry = prometheus.NewPedanticRegistry()

// 进行注册
if err := registry.Register(gauge); err != nil {
// 如果已经注册
	if are, ok := err.(prometheus.AlreadyRegisteredError); ok {
// 返回先前注册的收集器
		return are.ExistingCollector, nil
	}
	return nil, err
} 

Prometheus客户端不能直接将指标发送给Prometheus服务器。只能通过网络端口暴露一个Exporter。

如果要基于HTTP协议暴露，将promhttp包提供的Handler传递给你的HTTP服务器，每个Handler读取单个注册表，从中收集指标信息，生成HTTP响应：

// 使用默认注册表创建Handler
func Handler() http.Handler {
	return InstrumentMetricHandler(
		prometheus.DefaultRegisterer, HandlerFor(prometheus.DefaultGatherer, HandlerOpts{}),
	)
}

如果你需要使用非默认注册表，直接调用：

func HandlerFor(reg prometheus.Gatherer, opts HandlerOpts) http.Handler {}

 然后将Handler传递给你的ServeMux即可：

mux := http.NewServeMux()
import "github.com/prometheus/client_golang/prometheus/promhttp"
mux.Handle("/metrics", promhttp.Handler())

The post Prometheus学习笔记 appeared first on 绿色记忆.

InfluxDB是一个用于存储和分析时间序列数据的开源数据库。它的特性包括：

1. 支持HTTP接口
2. 支持类SQL的查询 —— InfluxQL
3. 高效的数据读写

InfluxDB默认使用两个端口：8086用于HTTP接口，8088用于备份/恢复数据的RPC服务。

curl -sL https://repos.influxdata.com/influxdb.key | sudo apt-key add -
source /etc/lsb-release
echo "deb https://repos.influxdata.com/${DISTRIB_ID,,} ${DISTRIB_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/influxdb.list

sudo apt-get update
sudo apt-get install influxdb
sudo service influxdb start

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: influxdb-pvc
  namespace: dev
spec:
  storageClassName: rook-block
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi

---

apiVersion: v1
kind: Pod
metadata:
  namespace: dev
  name: influxdb
  labels:
    app: influxdb
  annotations:
    "cni.projectcalico.org/ipAddrs": "[\"172.27.0.20\"]"
spec:
  terminationGracePeriodSeconds: 10
  containers:
  - name: influxdb
    image: docker.gmem.cc/influxdb
    ports:
    - containerPort: 8086
      name: http
    - containerPort: 8082
      name: ifql
    volumeMounts:
      - name: influxdb-pv
        mountPath: /var/lib/influxdb
  volumes:
    - name: influxdb-pv
      persistentVolumeClaim:
        claimName: influxdb-pvc

--- 

apiVersion: v1
kind: Service
metadata:
  name: influxdb
  namespace: dev
spec:
  ports:
  - name: http
    port: 8086
    protocol: TCP
    targetPort: 8086
  selector:
    app: influxdb
  sessionAffinity: None
  type: ClusterIP

执行下面命令进入CLI：

kubectl -n dev exec -it influxdb  influx -- -precision rfc3339

命令格式类似于MySQL：

CREATE DATABASE metrics
SHOW DATABASES
# name: databases
# name
# ----
# _internal
# metrics
USE metrics

InfluxDB中存放的是时间序列数据，包括0-N个数据点。数据点由以下部分组成：

1. time，时间戳
2. measurement，此指标的名字。例如CPU_LOAD
3. field，至少一个，KV对，V为数值例如value=6.12
4. tag，0-N个，指标的元数据。 host=zircon

指标的模式（Schema）是自由的，你可以任意添加字段、Tag。但是字段类型不可以改变，如果你第一次写入host的值类型是字符串，就不能在以后写入数字。

写入数据点时，你需要遵守如下格式的行协议：

<measurement>[,<tag-key>=<tag-value>...] <f1-key>=<f1-val>[,<f2-key>=<f2-val>...] [unix-nano-timestamp]
# 示例：
load,host=xenial-100,group=k8s value=3.1

通过CLI差入数据的InfluxQL语法为：

INSERT load,host=xenial-100,group=k8s value=3.1

类似的，可以用SELECT查询指标数据：

SELECT * FROM load
# name: load
# time                group host       value
# ----                ----- ----       -----
# 1522746924735704773 k8s   xenial-100 3.1

# 每个Tag、字段都可以作为列名
SELECT "group", host,value FROM "load"

FROM子句中，支持使用正则式来匹配指标名：

SELECT * FROM /.*/ LIMIT 1

WHERE子句也是支持的。

export URL=http://influxdb.dev.svc.k8s.gmem.cc:8086

# 执行InfluxQL             格式化响应JSON                   查询语句
curl -i -XPOST $URL/query?pretty=true --data-urlencode "q=SHOW DATABASES"
curl -i -XPOST $URL/query?pretty=true --data-urlencode "q=CREATE DATABASE metrics" 

# 写入操作，响应码204，数据正常写入
# 时间戳（纳秒）可以不传，这样自动使用InfluxDB本地时间
curl -i -XPOST $URL/write?db=metrics --data-binary 'host=xenial-100,group=k8s value=3.1 1434055562000000000'

# 可以同时写入多个数据点，使用换行符分隔

# 导入文件中的数据点、
curl -i -XPOST $URL/write?db=metrics --data-binary @load.txt 

curl -G $URL/query?pretty=true --data-urlencode "db=metrics" --data-urlencode "q=SELECT * FROM load"

结果同样以JSON形式返回。要同时执行多个查询，只需要用分号分开InfluxQL语句。

使用请求参数chunked/chunk_size可以发起分块（Chunked）请求，数据流式返回：

--data-urlencode "chunked=true" --data-urlencode "chunk_size=20000 

Influx提供了持续查询（Continuous Queries，CQ）来处理数据采样。CQ是按照时间进行聚合的InfluxQL语句，周期性的在Influx数据库内部运行。示例：

-- 查询数据库metrics的指标network的inbound、outbuound字段，对两者取平均值
-- 每30分钟分组聚合一次
-- 聚合结果存放到RP为one_year的指标sampled_load中，该指标具有字段mean_inbound、mean_outbound
CREATE CONTINUOUS QUERY "cq_30m" ON "metrics" BEGIN
    SELECT mean("inbound") AS "mean_inbound",mean("outbound") AS "mean_outbound"
    INTO "one_year"."sampled_load"
    FROM "network"
    GROUP BY time(30m)
END

配合使用CQ和RP，可以实现近期数据高精度保留，远期数据低精度保留甚至删除。 

Retention Policy（RP）定义了InfluxDB保留历史数据的时长。示例：

# 为指标load定义一个驻留策略，时长2小时
# REPLICATION为数据复制的份数，对于单节点InfluxDB，必须设置为1
CREATE RETENTION POLICY "two_hours" ON "load" DURATION 2h REPLICATION 1 DEFAULT 

 配置文件默认位于/etc/influxdb/influxdb.conf。

# 禁止向usage.influxdata.com发送使用情况信息
reporting-disabled = false

# 数据备份/恢复服务绑定地址
bind-address = "127.0.0.1:8088"


[meta]
# metadata/raft数据库的存放位置
dir = "/var/lib/influxdb/meta"
# 创建数据库时，自动创建默认的驻留策略
retention-autocreate = true
# 为meta service打印日志
logging-enabled = true


[data]
# TSM存储引擎在何处存储TSM文件
dir = "/var/lib/influxdb/data"
# TSM存储引擎在何处存储TWAL文件
wal-dir = "/var/lib/influxdb/wal"
# 写操作fsync到磁盘的延迟，大于0的值可以用于慢速磁盘，以及WML写出现竞态的情况
# 对于非SSD磁盘，推荐取值范围0-100ms
wal-fsync-delay = "0s"
# 新分片使用的分片索引（Shard index）类型，默认是内存索引，重启后会重新创建
# 取值tsi1使用基于磁盘的索引，支持大cardinality数据集
index-version = "inmem"
# 是否启用tsm引擎的冗长日志 
trace-logging-enabled = false
# 是否启用查询日志
query-log-enabled = true
### TSM引擎配置 ###
# 在拒绝写入操作之前，分片缓存占用的内存最大量
cache-max-memory-size = "1g"
# 当缓存达到多大时，引擎产生其快照，并写入到TSM文件，以释放内存空间
cache-snapshot-memory-size = "25m"
# 如果分片持续多久没有接收到新的写入/删除操作，则引擎产生缓存的快照，并写入到新的TSM文件
cache-snapshot-write-cold-duration = "10m"
# 如果引擎持续多久没有接收到分片的新的写入/删除操作，它将压缩分片的所有TSM文件
compact-full-write-cold-duration = "4h"
# 压缩并行度
max-concurrent-compactions = 0
# 在丢弃写操作之前，每个数据库允许的最大序列（Series）数量
# 可以在数据库级别解决高Cardinality问题，设置为0则禁用
max-series-per-database = 1000000
# 在丢弃写操作之前，每个Tag的最大值数量
# 可以解决Tag值的高Cardinality问题，设置为0则禁用
max-values-per-tag = 100000


# 集群服务配置
[coordinator]
# 写操作超时时间
write-timeout = "10s"
# 同时执行的查询的最大数量
max-concurrent-queries = 0
# 查询超时：在查询被系统杀掉之前，经过的最大时间
query-timeout = "0s"
# 缓慢查询阈值，超过此阈值的被记录到缓慢日志
log-queries-after = "0s"
# 一个SELECT最多能处理的数据点数量
max-select-point = 0
# 一个SELECT可以处理的Series的最大数量
max-select-series = 0
# 一个SELECT最多创建的Group by 时间桶（Time Bucket）数量
max-select-buckets = 0


# 驻留策略配置，驻留策略决定了如何清除老旧数据
[retention]
# 是否启用驻留策略，也就是说是否清除老旧数据
enabled = true
# 每隔多久进行运行驻留策略
check-interval = "30m"


# 控制分配的预创建，这样在数据到达前分片即可用
[shard-precreation]
# 是否启用分片预创建服务
enabled = true
# 预创建服务运行间隔
check-interval = "10m"

advance-period = "30m"


# 系统自我监控、统计和诊断
[monitor]
# 是否在内部进行统计信息
store-enabled = true
# 存储统计信息的目标数据库
store-database = "_internal"
# 每隔多久记录一次统计信息
store-interval = "10s"


[http]
# 是否启用HTTP端点
enabled = true
# HTTP服务的绑定地址
bind-address = ":8086"
# 是否启用用户身份验证
auth-enabled = false
# 基于HTTP基本认证时，发送给客户端的Realm信息
realm = "InfluxDB"
# 是否记录HTTP请求日志
log-enabled = true
# 访问日志路径
access-log-path = ""
# 是否启用详细的写日志
write-tracing = false
# 是否启用pprof端点，用于调试和诊断
pprof-enabled = true
# 是否启用HTTPS
https-enabled = false
# SSL整数路径
https-certificate = "/etc/ssl/influxdb.pem"
# 可以指定单独的私钥路径
https-private-key = ""
# SON web token共享密钥
shared-secret = ""
# 结果集大小限制，防止查询耗尽InfluxDB内存
# 仅仅限制非分块的HTTP API请求，分块请求不受限制
max-row-limit = 0
# 最大连接数
max-connection-limit = 0
# 是否使用UNIX域套接字
unix-socket-enabled = false
# UNIX域套接字路径
bind-socket = "/var/run/influxdb.sock"
# 客户端请求体大小
max-body-size = 25000000


[ifql]
# 是否启用RPC服务
enabled = true
# 是否进行额外的日志记录
log-enabled = true
# 绑定地址
bind-address = ":8082"


[logging]
# 日志格式
format = "auto"
# 日志级别
level = "info"
# 是否禁止显示LOGO
suppress-logo = false


# 控制订阅，订阅可以用于获取整个数据集的拷贝
[subscriber]
# 是否启用订阅者服务
enabled = true
# 写到订阅者的HTTP请求的超时
http-timeout = "30s"
# 是否允许到订阅者的不安全连接
insecure-skip-verify = false
# 数字证书位置
ca-certs = ""
# Goroutine数量
write-concurrency = 40
# 写缓冲区大小
write-buffer-size = 1000


[continuous_queries]
# 是否启用持续查询服务
enabled = true
# 是否记录CQ日志
log-enabled = true
# 是否记录统计信息
query-stats-enabled = false
# 多久检查CQ服务是否需要运行
run-interval = "1s"

The post InfluxDB学习笔记 appeared first on 绿色记忆.

Apache Drill是一个模式自由（Schema-free ）的、低延迟的、分布式的、可扩容的SQL查询引擎，可以让你使用熟悉的SQL语法对各种非关系型数据库进行操作。Drill支持针对PB级别数据的即席查询。Drill支持大量NoSQL数据和文件系统，包括MongoDB、HBase、HDFS。支持对不同数据源中的数据进行join操作。Drill支持Windows/Linux/Mac系统，可以很容易的在服务器集群中扩容。

Drill的优势包括：

1. 支持模式自由的JSON模型，Drill是第一个、目前也是唯一的不对Schema做任何要求的分布式SQL引擎。这种模式自由类似于MongoDB。Drill在查询执行过程中可以自动发现Schema
2. 即席的查询复杂的、半结构化的数据。你不需要对数据进行任何转换，Drill对SQL进行了直观的扩展，方面处理内嵌数据，就好像内嵌数据是普通的SQL列一样
3. 真实的SQL语言，Drill支持标准的SQL 2003语法。支持DATE, INTERVAL, TIMESTAMP, VARCHAR等数据类型，以及关联子查询、JOIN子句
4. 方便的和既有BI工具集成
5. 针对Hive表的交互式查询
6. 同时访问多个数据源
7. 用户自定义函数支持，直接支持Hive用户定义函数
8. 高性能、可扩容

Drill的核心是Drillbit服务，它负责接受客户请求、处理查询、返回查询结果。Drillbit可以被安装到并运行在数据库集群的所有节点上，这样在执行查询时可以减少网络流量。Drill通过ZooKeeper来维护集群成员状态、检查健康状况。

当你以SQL的形式发起一个查询时，查询被发送给Drill集群中的一个Drillbit，这个Drillbit成为领头（Foreman），它负责协作其它Drillbit以完成查询执行：

1. 解析SQL语句，将SQL操作符转换为Drill理解的逻辑操作符。这些逻辑操作符共同组成了逻辑执行计划，描述了生成查询结果所需的操作、哪些数据源需要参与其中
2. Foreman把逻辑计划发送给基于成本的优化器，优化操作符的顺序，最终转换为物理执行计划
3. Foreman中的并行器（parallelizer）把物理计划分为多个阶段 —— major/minor fragments。这些片断会并行的在所配置的数据源中执行

构成执行计划的一个阶段，每个阶段可以由1-N个主片断构成，这些片断代表完成此阶段Drill必须执行的操作。Drill为每个主片段分配一个ID。

例如，为了针对两个文件进行哈希聚合，Drill可能创建具有两个阶段的查询计划，每个计划包含一个主片断。第一个阶段专注于扫描文件，第二个阶段则专注于数据的聚合。

Drill使用exchange operator来分隔多个主片段，所谓exchange可以是：

1. 数据位置的变化，或/和
2. 物理计划的并行化

一个exchange由sender/receiver组成，允许数据在节点之间流动。

主片断本身不负责任何查询任务的实际执行。每个主片段包含若干个从片断，从片断负责执行并完成查询。

你可以获得物理计划的JSON表示，修改之，然后通过Drill的SUBMIT PLAN命令提交执行。

每个主片断被并行化为多个从片断。从片断是运行在一个线程内的逻辑工作单元（也叫slice）。每个从片断被分配一个ID。

Foreman中的并行器在执行期间把一个主片段拆分为1-N个从片断。Drill会根据数据局部性（data locality）把从片断调度到特定的节点上，并尽快的执行从片断（根据上流数据需求）。

从片断包含1-N个关系操作符，关系操作符执行关系型操作，例如scan, filter, join,group by。

从片断们可以形成树形结构，并分为root、intermediate、leaf三种角色。这种执行树仅仅包含一个运行在Foreman上的root从片断，需要执行的操作逐级下发，直到leaf从节点。leaf从节点与存储层交互或者访问磁盘数据，得到部分的结果，由上级节点进行聚合操作。 

每个Drillbit都由以下模块组成：

Drill暴露的低资源消耗的RPC协议，用于客户端连接。客户端可以直接连接到Drillbit，或者通过ZooKeeper连接。推荐使用后一种方式，以隔离Drill集群变化造成的影响。

基于开源SQL解析器Calcite实现，用于解析客户端请求。解析结果是语言无关、计算机友好的逻辑计划。

屏蔽特定数据存储的差异性。存储插件的功能包括：

1. 从数据源获取元数据
2. 读写数据
3. 数据位置感知、一系列优化规则

访问Drill的途径包括：

1. Drill Shell
2. Drill Web Console
3. ODBC/JDBC
4. C++ API

如果仅仅在单个节点上使用Drill，可以使用嵌入式安装。这种模式下，不需要安装ZooKeeper，也不需要进行配置。当你启动Drill shell时，本地的Drillbit服务自动启动。

安装步骤：

wget http://apache.mirrors.hoobly.com/drill/drill-1.11.0/apache-drill-1.11.0.tar.gz
tar xzf apache-drill.tar.gz

要运行Drill，执行下面的命令以打开Drill Shell：

drill-embedded
0: jdbc:drill:zk=local> 
# 命令提示符说明：
# 0 表示连接到drill的连接数
# jdbc为连接类型
# zk=local 作为ZooKeeper的代替

或者执行

sqlline -u "jdbc:drill:zk=local"

要退出Drill Shell，在Shell中输入

!quit

要访问Web Console，在浏览器地址栏输入

http://127.0.0.1:8047/

要在Hadoop集群环境下使用Drill，可以使用分布式安装。ZooKeeper的分布式集群是必须的前提，你也需要对Drill进行配置，才能连接到各种数据源。

下载、解压后，修改配置文件：

drill.exec: {
  # Drill集群标识符
  cluster-id: "drillbits",
  # ZooKeeper连接字符串
  zk.connect: "172.21.0.1:2181,172.21.0.2:2181,172.21.0.3:2181"
}

要以集群模式启动Drill，首先需要在集群的每个节点上启动守护程序Drillbit：

# 命令格式：drillbit.sh [--config <conf-dir>] (start|stop|status|restart|autorestart)
/home/alex/JavaEE/middleware/drill/bin/drillbit.sh --config /home/alex/JavaEE/middleware/drill/conf start

要连接到分布式部署的Drill Shell，可以：

1. 执行drill-conf，此脚本使用conf/drill-override.conf配置
2. 执行drill-localhost连接到运行在本机的ZooKeeper 

连接上以后，可以执行

SELECT * FROM sys.drillbits;

参考如下Dockerfile：

FROM openjdk:8-jre

ENV CLUSTER_ID drillbits
ENV ZK_CONNECT 172.21.0.1:2181


RUN apt-get install -y wget tar

ADD docker-entrypoint.sh .
ADD apache-drill.tar.gz  .

RUN chmod +x docker-entrypoint.sh && mv apache-drill-1.11.0 /opt/drill

ENTRYPOINT ["/docker-entrypoint.sh"]

入口脚本：

#!/usr/bin/env bash

cat << EOF  > /opt/drill/conf/drill-override.conf
drill.exec: {
  cluster-id: "$CLUSTER_ID",
  zk.connect: "$ZK_CONNECT"
}
EOF

/opt/drill/bin/drillbit.sh --config /opt/drill/conf run

创建并运行容器： 

docker run -e ZK_CONNECT=172.21.0.1:2181,172.21.0.2:2181,172.21.0.3:2181 --name drill-14 \
           --network local --ip 172.21.1.14 -d docker.gmem.cc/drill 

你可以配置分配给Drillbit的用于处理查询的直接内存的量。默认配置是8G，在高负载下可能需要16G或者更多。

Drill使用Java的直接内存来存储执行中的操作，除非必须，它不会使用磁盘。这和MapReduce不同，后者将任务每个阶段的输出都存放在磁盘上。JVM的堆内存不限制Drillbit能够使用的直接内存。Drillbit的堆内存通常设置到4-8G就足够了，因为Drill避免在堆中写数据。

从1.5版本开始，Drill使用新的直接内存分配器，可以更好的使用、跟踪直接内存。由于这一变化，sort操作符可能因为内存不足而失败。

系统选项 planner.memory.max_query_memory_per_node 设置单个Drillbit中每个查询的sort操作符能够使用的内存量。如果一个查询计划中包含多个sort操作符，它们共享这一内存。如果sort查询出现内存问题，考虑增加此选项的值。如果问题仍然存在，考虑减小系统选项planner.width.max_per_node的值，该值控制单个节点的并行度。

在drill-env.sh中设置环境变量：

# 如果堆内存没有设置，将其设置为4G
export DRILL_HEAP=${DRILL_HEAP:-"4G”}  
# 如果直接内存没有设置，将其设置为8G
export DRILL_MAX_DIRECT_MEMORY=${DRILL_MAX_DIRECT_MEMORY:-"8G"}

Drill提供两种角色：

用户身份模拟（Impersonation）允许一个服务代表客户端执行某个操作。默认的，身份模拟被关闭。

Drill支持基于Linux PAM的身份验证。PAM允许和系统密码文件（/etc/passwd）或者LDAP等PAM实体进行交互以完成身份验证。

使用PAM验证时，运行Drill查询的用户必须存在于每一个Drill节点上。

Drill支持Kerberos v5网络认证、客户端 - Drill的通信加密。需要配合JDBC驱动来使用该认证方式。

在启动时，一个Drillbit必须被验证。在运行时Drill使用和KDC共享的keytab文件，Drill使用该文件来验证票据的合法性。

配置

security.user.encryption.sasl.enabled

你需要为Drill创建principal，可以：

kadmin
# 一个集群使用单个实体
# addprinc  <username>/<clustername>@<REALM>.COM 
addprinc  drill/drillbits@GMEM.CC

你需要为上面的principal创建一个keytab文件：

ktadd -k /home/alex/JavaEE/middleware/drill/conf/drill.keytab drill/drillbits@GMEM.CC

然后，为Drill配置文件添加：

drill.exec: {
  security: {
  	user.auth.enabled: true,
  	user.encryption.sasl.enabled: true,
  	auth.mechanisms: ["KERBEROS"],
  	auth.principal: "drill/drillbits@GMEM.CC",
  	auth.keytab: "/home/alex/JavaEE/middleware/drill/conf/drill.keytab"
  }
}

并重启。

你可以在conf/drill-override.conf中配置启动选项，其中最常用的如下表：

Drill通过存储插件（Storage）连接到底层数据源。存储插件通常负责：

1. 连接到数据源，例如数据库、文件
2. 优化Drill查询的执行
3. 提供数据的位置信息
4. 配置工作区、文件格式以读取数据

常用的几个存储插件跟随Drill一起安装

所谓插件配置，就是连接到目标数据源的配置信息。Drill默认注册了这几个默认的插件配置：

通过Web Console连接（地址示例：http://172.21.1.14:8047/storage），可以注册插件配置。

点击Disable按钮可以禁用当前的配置，禁用后，show databases中对应的条目消失。点击Enable可以启用某个可用配置。输入存储插件名称，点击Create，可以建立新的插件配置。

插件配置都是JSON格式，MongoDB配置的示例：

{
  "type": "mongo",
  "connection": "mongodb://root:root@mongo-s1.gmem.cc:27017/",
  "enabled": true
}

打开drill-conf，输入命令验证连接是否正常：

0: jdbc:drill:> show databases;
+---------------------+
|     SCHEMA_NAME     |
+---------------------+
| INFORMATION_SCHEMA  |
| mongo.admin         |
| mongo.bais          |
| mongo.config        |
| sys                 |
+---------------------+

# 上面的结果意味着已经连接到此配置，注意数据库名称的前缀，就是配置的名称

use mongo.bais;
select regNo,stocks[0].stockName as stock0Name from corps;
+----------------+-------------+
|     regNo      | stock0Name  |
+----------------+-------------+
| 3208261000000  | 汪震          |
+----------------+-------------+

# 上面的结果意味着查询测试成功 

除了Shell、Web Console以外，Drill还提供C++ API以及JDBC、ODBC驱动。

添加依赖以使用此驱动：

<dependency>
    <groupId>org.apache.drill.exec</groupId>
    <artifactId>drill-jdbc</artifactId>
    <version>1.11.0</version>
</dependency>

# jdbc:drill:zk={ZooKeeper连接字符串}/drill/{Drill集群标识符};schema={存储插件配置.数据库名称}
jdbc:drill:zk=zookeeper-1.gmem.cc:2181,zookeeper-2.gmem.cc:2181,zookeeper-3.gmem.cc:2181/drill/drillbits;schema=mongo.bais

Class.forName( "org.apache.drill.jdbc.Driver" );
String url = "jdbc:drill:zk=zookeeper-1.gmem.cc:2181/drill/drillbits;schema=mongo.bais";
Connection connection = DriverManager.getConnection( url );
Statement st = connection.createStatement();
ResultSet rs = st.executeQuery( "select regNo,stocks[0].stockName as stock0Name from corps" );
while ( rs.next() ) {
    System.out.println( rs.getString( 2 ) );
}

所谓复杂数据结构，是指与关系型数据库那种简单的表格形式（行、字段）不同的，具有复杂数据类型字段（内嵌结构）的数据结构。

Drill可以在执行查询请求的时候，发现数据的结构。类似于JSON、Parquet之类的嵌套数据结构不仅仅可以被简单的访问，Drill还提供特殊的操作符、函数对其进行钻取操作。这些操作符、函数能够：

1. 引用内嵌数据结构的值
2. 访问数组元素、嵌套数组

你可以使用SQL标准的join子句来连接两个表或/和文件。示例：

select c.regNo, c.corpName, o.name from corps as c join orgs as o on c.belongOrg = o._id where c.regCapi > 10000;

-- 访问内嵌文档
select c.address.detail as addr from corps as c;
-- 访问内嵌数组
select c.stocks[0].stockName from corps as c;
select c.stocks[0].stockName, c.stocks[0].subsCapi from corps as c;

Drill使用Logback作为默认的日志系统，日志配置位于conf/logback.xml。

默认的，日志被输出到文件系统，位于$DRILL_HOME/logs目录下，你可以在drill-env.sh中设置$DRILL_HOME环境变量。在每个Drill节点上，文件drillbit_queries.json记录每个查询的ID、profile信息。

要获得查询的执行计划，执行

explain plan for

explain plan for select regNo,corpName from bais.corps;

从输出结果中，可以看到Drill如何访问底层数据源：

# explain plan for select regNo,corpName from bais.corps where regNo like '3208%';
00-00    Screen
00-01      Project(regNo=[$0], corpName=[$1])
00-02        UnionExchange
01-01          Scan(groupscan=[MongoGroupScan [MongoScanSpec=MongoScanSpec
                   [dbName=bais, collectionName=corps, filters=null], columns=[`regNo`, `corpName`]]])
                                                       # 没有过滤器，意味着需要全表扫描
# explain plan for select regNo,corpName from bais.corps where regNo > '320800100' and regNo < '320800200' limit 10;
00-00    Screen
00-01      Project(regNo=[$0], corpName=[$1])
00-02        SelectionVectorRemover
00-03          Limit(fetch=[10])
00-04            UnionExchange
01-01              SelectionVectorRemover
01-02                Limit(fetch=[10])
01-03                  Scan(groupscan=[MongoGroupScan [MongoScanSpec=MongoScanSpec 
                     [dbName=bais, collectionName=corps, 
                     filters=Document{{$and=[Document{{regNo=Document{{$gt=320800100}}}}, 
                     Document{{regNo=Document{{$lt=320800200}}}}]}}], columns=[`regNo`, `corpName`]]])
                                                       # 这里可以看到使用了MongoDB的查询过滤，可能利用到索引

Drill支持ANSI标准SQL，你可以使用统一的语法查询各种数据源。为了支持嵌套数据结构，Drill提供特殊的操作符和函数。

使用CAST、CONVERT TO/FROM、TO_CHAR、TO_DATE、TO_NUMBER、TO_TIMESTAMP，可以进行显式的类型转换。某些类型之间可以进行隐式转换，NULL可以转换到任何类型。示例代码：

-- CAST (<expression> AS <data type>)
CAST( regNo as INT )

-- 把目标列转换为字节
CONVERT_TO (column, type)
-- 把regNo作为大端整数，转换为字节
CONVERT_TO(regNo , 'INT_BE')

-- 把字节转换为type
CONVERT_FROM(column, type)
-- 把字符串转换为JSON map
CONVERT_FROM('{x:100, y:215.6}' ,'JSON')

-- TO_CHAR (expression, 'format') 转换数字、日期、时间、时间戳为字符串形式
SELECT TO_CHAR(1256.789383, '#,###.###') FROM (VALUES(1));   -- 1,256.789
TO_CHAR((CAST('2008-2-23' AS DATE)), 'yyyy-MMM-dd')          -- 2008-Feb-23 
TO_CHAR(CAST('12:20:30' AS TIME), 'HH mm ss'                 --  12 20 30
TO_CHAR(CAST('2015-2-23 12:00:00' AS TIMESTAMP), 'yyyy MMM dd HH:mm:ss')
                                                             -- 2015 Feb 23 12:00:00 

-- TO_DATE (expression [, 'format']) 转换字符串或者UNIX时间戳为日期
TO_DATE('2015-FEB-23', 'yyyy-MM-dd')
-- TO_TIME (expression [, 'format']) 转换为时间
TO_TIME('12:20:30', 'HH:mm:ss')
TO_TIME(82855000)
-- TO_TIMESTAMP (expression [, 'format'])
TO_TIMESTAMP('2008-2-23 12:00:00', 'yyyy-MM-dd HH:mm:ss')

主要分为数学、日期、字符串、聚合等函数，参考官方文档。

窗口函数针对一系列行进行计算操作，并为每一行返回单个值。这些值虽然归属到某个行，但是它可能取决于其它多个行（这些行就是所谓窗口）。

你可以使用

OVER()

1. 定义对行进行分组（partition）的标准，聚合函数在这些分组上进行。这通过PARTITION BY子句实现
2. 在一个分组内部，对行进行排序。这通过ORDER BY子句实现

对于窗口函数，你需要注意：

1. 仅仅支持在查询的SELECT、ORDER BY字句中使用窗口函数
2. Drill在WHERE, GROUP BY, HAVING之后处理窗口函数
3. 在聚合函数之后跟随OVER()导致其作为窗口函数使用
4. 使用窗口函数，你可以针对窗口帧中任意数量的行进行聚合
5. 如果要针对FLATTEN子句的生成的结果集执行窗口函数，应该在子查询中使用FLATTEN

窗口函数完整的调用语法：

-- window_function指定一种窗口函数，这些函数可能和普通的聚合函数同名，识别它是否为窗口函数的唯一方法就是看看
-- 后面有没有OVER关键字。窗口函数在窗口内部进行聚合
-- expression 为列表达式
-- PARTITION BY关键字定义了窗口：
-- expr_lists 可以是  expression | column_name [, 其它expr_list ]
-- ORDER BY 定义窗口内排序规则，如果没有PARTITION BY则针对整个表格排序
--  order_lists 可以是 expression | column_name [ASC | DESC] [ NULLS { FIRST | LAST } ] [, 其它 order_list ]  
-- frame_clause 可以是：
-- { RANGE | ROWS } frame_start
-- { RANGE | ROWS } BETWEEN frame_start AND frame_end
-- frame_start 格式：UNBOUNDED PRECEDING 或者 CURRENT ROW 
-- frame_end 格式：CURRENT ROW 或者 UNBOUNDED FOLLOWING 
window_function (expression) OVER (
    [ PARTITION BY expr_list ]
    [ ORDER BY order_list ][ frame_clause ] )

-- 查询企业信息，为结果集的每一行增加列：当前企业类型的平均注册资金
select 
    cast(c.corpName as char) corpName, c.corpType, 
    avg( c.regCapi ) over( partition by c.corpType) as avgRegCapi  
from bais.corps c where c.regNo >= '320100100' and c.regNo < '320100200';

嵌套数据函数用于访问内嵌式的数据结构，包括数组、映射、重复标量类型。不要在GROUP BY、ORDER BY子句或者在比较操作符中使用前述内嵌数据。Drill不支持 VARCHAR:REPEATED之间的比较。

把嵌套数据结构分解为单独的记录（行），示例：

-- 每个企业包含多个股东，股东为数组
SELECT FLATTEN(stocks) FROM bais.corps  WHERE stocks IS NOT NULL;

从一个映射中抽取键值对

返回数组的长度：

REPEATED_COUNT (array)

在数组中搜索指定的关键字：

REPEATED_CONTAINS(array_name, keyword)

原因：DNS将当前主机名解析到本地环回地址，可能需要更改/etc/hosts文件

原因：DNS没有正确配置

解决办法：如果网络中没有启用DNS服务，可以静态的修改/etc/hosts文件

可以用这种方式来指定中文查询条件：

select * from bais.trades where name like _UTF16'%农产品%';

原因：如果分片集群启用了身份验证，不但需要建立集群上的用户，还要为每个复制集创建本地用户。如果报错信息中有servers=[{address=****而且地址是分片的（而不是mongos的）地址，说明就是分片的身份验证出错。

The post Apache Drill学习笔记 appeared first on 绿色记忆.

OpenTSDB是一个开源的、被广泛使用的时间序列数据库。它提供了一整套和监控有关的功能，可以用来构建分布式、可扩容的监控系统。使用OpenTSDB可以不损失统计精度的永久保存监控数据，统计精度可以达到毫秒级。OpenTSDB的底层是Hadoop/HBase，可以扩容到每秒百万级的监控数据写操作。OpenTSDB自带了前端组件，并且支持通过HTTP Pull API拉取数据，这样你可以选择自己喜爱的前端组件。

The post OpenTSDB学习笔记 appeared first on 绿色记忆.

Graphite是一个开源项目，可以作为时间序列数据库（TSDB）使用，当你需要存储随着时间变化的数值时，应当考虑使用时间序列数据库。

除了数据的存储、查询外，Graphite还提供数据可视化（UI层）功能，它可以很好的在廉价的硬件上运行。你可以使用Graphite来监控网站、应用程序、网络服务器等的性能数据（Metrics），轻松实现基于时间维的分析。

Graphite本身不负责性能数据的采集，但是它提供了简单易用的接口，公共这些接口你可以把基于数字的性能数据存储到Graphite中。

Graphite由三个组件构成：

1. Carbon：一个基于Twisted（Python事件驱动网络框架）的守护程序，负责监听外部的时间序列数据
2. Whisper：一个简单的存储时间序列数据的数据库，设计上和RRDtool类似 
3. Graphite-Web：一个基于Django（Python Web框架）的Web应用，使用Cairo（一个2D图形库）来渲染性能数据的图表，使用ExtJS作为基础UI框架

下面是Graphite的架构图：

一旦你把数据送给Carbon，它就立刻可以在Webapp的图表中显示，因为数据在被写入文件系统之前，会驻留在缓存中。

除了使用Graphite Webapp，你也可以通过URL API，将图表嵌入到自己的应用程序中去。如何使用Graphite

使用Graphite来监控你的性能数据，你需要完成以下工作：

1. 理解Graphite组件的职责和相互关系
2. 安装Graphite及其依赖
3. 基础的配置，让Graphite能运行起来
4. 设计Metrics路径
5. 配置Metrics的驻留规则、聚合规则等
6. 向Graphite发送Metrics
7. 从Graphite获取Metrics并展示

Metrics路径由点号分隔的字符串构成，类似于Python的包名称。路径是Metrics的标识。

你应当仔细的设计此路径的命名空间，以反映出所有Metrics之间的层次关系。例如servers.zircon.cpu，这个三级路径设计中，第一级表示设备类别，第二级表示设备名称，第三级表示监测点类型。

Carbon由一系列的守护进程组成，这些守护进程共同组成Graphite的存储后端。在最小化的安装下，只有一个守护进程carbon-cache.py。根据需要你可以启用carbon-relay.py、carbon-aggregator.py以便实现Metrics分发、定制聚合规则。各Carbon守护进程简介如下：

Whisper是一个固定大小（fixed-size）的数据库，其设计和用途与RRD（round-robin-database）类似。它能提供快速、可靠的数值数据的存储。

Whisper能够对最近的数据进行高分辨率的存储，而对久远的历史数据，自动降低其存储精度（减少样本数量）。

在大多数场景下，Whisper有足够好的性能。它比RRDtool慢，主要原因是Whisper基于Python编写，这个性能差异很小，通常不需要考虑。

Whisper数据库以文件方式存放在磁盘上，扩展名.wsp。Carbon会为每个Metrics创建一个.wsp文件，路径的最后一节作为文件的basename，路径的其它部分形成目录层次。

在Whisper中存储的每一个数值，称为数据点（Data Points）。

在磁盘上，数据点以大端、双精度浮点数存储。每个数据还附带一个时间戳信息，时间戳为1970-01-01到数据采集时间的秒数。

一个Whisper数据库文件可以包含一个或者多个“归档”，归档是数据文件中的逻辑段。

每个归档具有不同的数据分辨率（一定时间段内，数据点数量越多，则分辨率越高）。归档以最高分辨率（最小驻留时间） —— 最低分辨率（最长驻留时间）的顺序，在数据库文件中顺序排列。

为了精确的从高分辨率向低分辨率的归档聚合，高分辨率归档和它之后的低分辨率归档，其分辨率应当具有整除关系。例如，第一个归档分辨率为60秒/数据点，那么第二个归档可以是300秒/数据点，第三个归档可以是3600秒/数据点。

一个数据库的总计驻留时间（存放的数据点跨越的时间），由最长驻留时间的（最后一个）归档确定。因为之前的那些归档，时间区间都是它的子区间。

把数据点转移到低分辨率归档时，面临着如何把多个数据点转变为单个数据点的问题。Whisper支持average、sum、last、max、min等聚合函数。

注意，这里的聚合和Carbon提供的前置聚合不是一回事。

当Whisper向一个多归档数据写入Metrics时，数据点将被同时写入到所有的归档中。这意味着聚合动作随时可能发生。

当从Whisper中获取数据时，第一个能完整覆盖所需区间的归档被使用。

Whisper的磁盘利用效率不高，因为：

1. 每个数据点要附加一个时间戳信息
2. 由于归档的时间区间有重叠，因此数据存在冗余
3. 归档中的时间槽位（time-slots）总是占据着磁盘空间，不管有没有值存储在其中

这些特征是故意的，主要出于性能方面的考虑。

1. RRD不能去填充以前的时间槽位。这意味着每一条数据都必须是更新的，不会“补录”
2. RRD不能很好的支持不规则的数据更新。如果RRD接收到一条数据，但是后续数据没有到来，则前一条数据可能丢失

git clone https://github.com/graphite-project/graphite-web.git
graphite-web/check-dependencies.py
# 根据输出的提示来判断缺少哪些依赖，然后安装

yum -y install python-devel     # Carbon 依赖于 Python Development Headers

yum install pycairo             # Cairo库的Python绑定

pip install django              # Web框架
pip install django-tagging

pip install pytz

yum install fontconfig

yum install -y memcached        # 可选，缓存支持
pip install python-memcached    
                                # 可选，RDDTool
yum install cairo-devel libxml2-devel pango-devel pango libpng-devel freetype freetype-devel libart_lgpl-devel rrdtool-devel

pip install python-rrdtool      # 可选，RRD支持

pip install whitenoise          # 用于Web静态文件处理

yum install pyOpenSSL           # OpenSSL的Python绑定
pip install service_identity    # SSL相关

pip install https://github.com/graphite-project/ceres/tarball/master
pip install whisper
pip install carbon
pip install graphite-web

sudo groupadd graphite
sudo usermod -a -G graphite root
sudo usermod -a -G graphite apache
sudo chgrp -R graphite /opt/graphite/storage
sudo chmod -R 770 /opt/graphite/storage

Whisper被安装到Python全局site-packages目录，另外两个Graphite组件安装到

/opt/graphite

$GRAPHITE_ROOT

$STORAGE_DIR

你需要让Graphite-web的底层框架Django执行数据库的初始化。此数据库被用来存放用户设置、仪表盘，以及支持事件功能。

默认情况下，Graphite-web使用位于$STORAGE_DIR/graphite.db的SQLite数据库。如果要运行多个Graphite-web实例，则必须使用MySQL等数据库以便多个实例可以共享数据。 

执行下面的命令初始化SQLite数据库：

PYTHONPATH=/opt/graphite/webapp django-admin.py migrate --settings=graphite.settings --run-syncdb
# 完毕后 $STORAGE_DIR/graphite.db自动创建

Django应用需要在Web服务器中运行，Web服务器需要对SQLite数据文件有读写权限。假设你使用Apache2，运行Apache2的用户为apache，则需要执行：

sudo chgrp graphite /opt/graphite/storage/graphite.db

Graphite不建议修改settings.py，所有定制化的配置，都应该在此文件中进行。常用的设置项如下表：

rrdtool flushcached

DEFAULT_CACHE_POLICY = [
    (0, 60), # 默认缓存60秒
    (7200, 120) # >= 2小时以上时间范围的查询，缓存2分钟
] 

# 如果报Unknown command: 'collectstatic' 说明INSTALLED_APPS中缺少
# django.contrib.staticfiles	
PYTHONPATH=/opt/graphite/webapp django-admin.py collectstatic 
    --noinput --settings=graphite.settings

Alias /static/ "/opt/graphite/static"

我们的配置如下：

# 如果不设置，会导致报错：AttributeError: 'Settings' object has no attribute 'URL_PREFIX
URL_PREFIX = '/'

多种Web服务器可以用于运行基于Django的Web应用，这里我们选择Apache2。在CentOS下安装Apache2：

yum install httpd

要让Apache2能够运行Python Web应用，需要安装模块mod_wsgi。参考Django学习笔记完成mod_wsgi的构建与安装。

在/opt/graphite/examples/目录下，example-graphite-vhost.conf可以作为Apache虚拟主机的模板，复制该文件到/etc/httpd/conf.d/目录下，然后修改：

<IfModule !wsgi_module.c>
    LoadModule wsgi_module modules/mod_wsgi.so
</IfModule>
WSGISocketPrefix run/wsgi
<VirtualHost *:7767>
        ServerName xcentos7.local
        DocumentRoot "/opt/graphite/webapp"
        ErrorLog /opt/graphite/storage/log/webapp/error.log
        CustomLog /opt/graphite/storage/log/webapp/access.log common
        WSGIDaemonProcess graphite processes=5 threads=5 display-name='%{GROUP}' inactivity-timeout=120
        WSGIProcessGroup graphite
        WSGIApplicationGroup %{GLOBAL}
        WSGIImportScript /opt/graphite/conf/graphite.wsgi process-group=graphite application-group=%{GLOBAL}
        WSGIScriptAlias / /opt/graphite/conf/graphite.wsgi
        Alias /content/ /opt/graphite/webapp/content/
        <Directory /opt/graphite/webapp/content/>
            Require all granted
        </Directory>
        <Directory /opt/graphite/conf/>
            Require all granted
        </Directory>
</VirtualHost>

如果配置没有问题，启动Web服务器后访问：

http://GRAPHITE_HOST:GRAPHITE_PORT/render

所有Carbon守护进程可以基于多种通信协议，监听时间序列数据，并且对数据进行不同的处理。

Carbon的配置文件位于/opt/graphite/conf/目录，默认情况下没有预置的配置文件，但是Graphite提供了若干配置文件样例。你可以复制这些配置文件并定制：

pushd /opt/graphite/conf
cp carbon.conf.example carbon.conf
cp storage-schemas.conf.example storage-schemas.conf

这是主配置文件，为每个Carbon守护进程定义配置项。该配置文件按段区分不同守护进程的配置：

这个配置文件用于定义Metrics的驻留率（ retention rates）——即Metrics的数据点（datapoints）以什么频率保存，保存多长时间。关于该配置文件，需要注意：

1. 该配置文件可以由多个段（Section）组成。每个段定义一个存储规则
2. 这些规则按照从上到下的顺序对Metrics进行匹配，第一个匹配的规则对Metrics生效
3. 匹配Metrics时，采用的是正则表达式
4. 对于一个Metrics，其存储规则在接收到第一个数据时固化。因而修改此配置文件不会影响到既有的.wsp文件。要应用到既有的.wsp可以调用whisper-resize.py

每个规则由三个部分组成：

# 段名称（规则名称），主要是文档用途。在匹配段的Metrics被创建时，日志creates.log中会显示此名称
[rulename]
# 匹配Metrics路径（Metrics的全限定名称，点号分隔）的正则式
# 举例：^servers\.www.*\.workers\.busyWorkers$
pattern=regex
# 驻留率表达式，数据点间隔:存留天数，时间后缀s,m,h,d,y分别表示秒、分、小时、天、年
# 举例：10s:14d 表示每个数据点表示10秒（相当于每10秒采集数据一次），并且存储14天的数据
retentions=retention rate

注意，你可以指定多重驻留率表达式（retention rate），逗号分隔每个表达式。一般从最高精度:最短存留时间开始指定，直到最低精度:最长存留时间。例如：

15s:7d,1m:21d,15m:5y

设置多重驻留率表达式，可以在保存足够长时间的历史数据的前提下，尽量减少磁盘I/O和消耗的存储空间。当跨越驻留表达式的时间区间（上例中7天，21天）后，whisper会自动降低采样率（downsamples），默认算法是取平均值，可以通过storage-aggregation.conf定制聚合方式

这个配置文件定义如何在降低采样率（转换为低精度存储时） 如何对数据进行聚合。该文件的格式与storage-schemas.conf类似：

[rulename]
pattern = rexexp
# 0-1之间的浮点数，默认0.5。聚合区间内的值，至少多少比例为非空，聚合后的值才是非空
xFilesFactor = 0.5
# 数据聚合方式，默认average
aggregationMethod = average | sum | min | max | last

同样的，修改此文件不会影响已经生成的.wsp文件， 要应用到既有的.wsp文件，可以调用whisper-set-aggregation-method.py。

这个配置文件指定中继规则——即需要把何种Metrics转发给何种后端。中继由Carbon的中继进程负责执行。该文件格式如下：

[rulename]
pattern = regex
servers = ip:port,ip:port,...

该配置文件定义聚合出来的Metrics——由几个Metrics聚合而成的新的Metrics。聚合由Carbon的聚合进程负责执行。

注意：这里的聚合storage-aggregation.conf提及的聚合不同。后者用于单一Metrics的降低采样，而前者用于生成新的Metrics。

与其它配置文件不同，该文件一旦更改，立即生效。

该文件的格式如下：

# 捕获任何匹配input_pattern的Metrics，使用method聚合成新的Metrics：output_template
# frequency：每隔多久执行一次聚合
# method：可选sum/avg
output_template (frequency) = method input_pattern

举例，假设你的Metrics的命名规则是：

<env>.applications.<app>.<server>.<metric>

这是你可以配置如下聚合规则，来计算所有应用程序的请求的总数：

<env>.applications.<app>.all.requests (60) = sum <env>.applications.<app>.*.requests

在此规则下，下面的Metrics：

test.applications.pems.221.request
test.applications.pems.6.request
test.applications.pems.5.request
test.applications.pems.201.request

会每个60秒求和并生成 

test.applications.pems.all.request

该配置文件定义Metrics名称的改写规则。 与其它配置文件不同，该文件一旦更改，立即生效。该文件的格式如下：

[pre]
# pre段的规则，在接收到数据后立即执行改写
[post]
# post段的规则，在聚合完毕后执行改写
regex-pattern = replacement-text

 举例：

# \1表示第一个捕获，即[a-z0-9]+
^collectd\.([a-z0-9]+)\. = \1.system.
# collectd.prod.cpu-0.idle-time 会被改写为 prod.system.cpu-0.idle-item

Carbon提供黑白名单功能。白名单：仅仅接受其中列出的Metrics；黑名单：拒绝其中列出Metrics。

要启用黑白名单功能，需要修改carbon.conf，设置

USE_WHITELIST = True

如何启动Graphite Webapp依赖于其运行的Web服务软件，以Apache为例：

# CentOS 7
systemctl restart httpd

Carbon组件需要执行下面的命令来启动：

/opt/graphite/bin/carbon-cache.py start

SQLite是一个“文件数据库”，不需要启动。如果Graphite Webapp使用其它数据库，例如MySQL，则需要启动之。 

你可以通过多种方式向Graphite（的Carbon组件）发送Metrics数据点。主要的三种数据格式是：Plaintext、Pickle、AMQP 

这种方式非常简单，你可以用如下格式来发送一条Metrics数据点：

<metric path> <metric value> <metric timestamp>
# 举例：
servers.zircon.cpu 85 1470303923

出于测试目的，你可以直接通过命令向Carbon发送Metrics数据：

PORT=2003
SERVER=127.0.0.1
echo "servers.zircon.cpu 85 `date +%s`" | nc ${SERVER} ${PORT}

Pickle是Python下的对象串行化框架，Pickle协议即它的串行化格式协议。使用该协议，你可以一次发送多个Metrics，并且串行化后的数据比较紧凑，因此Pickle协议性能更好。

下面是构建Pickle报文的示例代码：

listOfMetricTuples = [
    (path, (timestamp, value)),
    ...
]
payload = pickle.dumps(listOfMetricTuples, protocol=2)
header = struct.pack("!L", len(payload))
message = header + payload
# 然后通过Socket把message发送出去即可

import pickle
import socket
import struct
import sys
import time
from time import sleep

import psutil


def get_cpu_load():
    load = psutil.cpu_percent()
    print load
    return load


if __name__ == '__main__':
    CARBON_HOST = '172.16.87.132'
    CARBON_PORT = 2004
    s = socket.socket()
    try:
        s.connect((CARBON_HOST, CARBON_PORT))
        while True:
            data = [
                ('servers.zircon.cpu', (time.time(), get_cpu_load()))
            ]
            pkg = pickle.dumps(data, 1)
            s.sendall(struct.pack('!L', len(pkg)))
            s.sendall(pkg)
            sleep(5)
    except socket.error:
        raise SystemExit("Failed to connect to %(host)s:%(port)" % {'host': CARBON_HOST, 'port': CARBON_PORT})
    except KeyboardInterrupt:
        sys.stderr.write("\nExiting on CTRL-C\n")
        sys.exit(0) 

要从Graphite获取数据用于展示，可以使用Graphite Webapp暴露的Render URL API（RUA）。你可以通过

http://GRAPHITE_HOST:GRAPHITE_PORT/render

访问此API。要向RUA传递参数，可以使用URL请求参数方式：

&name=value

下面列出几个RUA的URL示例：

# Zircon的CPU负载图，获取800x600的图片
http://graphite/render?target=servers.zircon.cpu&height=800&width=600
# 最近12小时，所有服务器的CPU负载平均值
http://graphite/render?target=averageSeries(servers.*.load)&from=-12hours
# 获取原始数据而不是图片，JSON格式
http://graphite/render?target=servers.zircon.cpu&format=json

该参数用来指定从何处获取数据，你可以指定：

1. 单个Metrics路径
2. 带有通配符的的Metrics路径，匹配多个Metrics
3. 函数调用，针对作为入参的Metrics进行各种转换、合并操作

你可以在路径中使用三种风格的通配符：

1. *

    可以匹配0-N个字符，例如

   servers.dev-*.cpu

    ，可以匹配所有开发服务器的CPU负载Metrics。

2. [...]

    可以匹配列表中枚举的单个字符，例如

   servers.dev-[a-z0-9].cpu

    ，可以匹配dev-0、dev-1等服务器的CPU负载Metrics。

3. {...}

    可以匹配列表中枚举的单个字符串，例如

   servers.{dev-0,dev-1}.cpu

    ，匹配dev-0、dev-2的CPU负载Metrics。

注意：所有通配符都不能跨越点号。 

你可以指定target为template函数调用，从而在Metrics路径中使用变量，例如：

# $varname 用来声明变量占位符
# template[varname]参数用来传递变量值
&target=template(servers.$servername.cpu)&template[servername]=zircon

# 可以使用数字代替变量名
&target=template(servers.$1.cpu)&template[1]=zircon

# template可以内嵌其它函数
&target=template(constantLine($number))&template[number]=123

可用的函数较多，这里不一一列举说明，参见官方文档。

这两个可选参数用来指定相对或者绝对的时间区间（time period）。from表示区间起点，如果忽略，默认值是24小时之前；until表示区间终点，如果或略，默认值是当前时间点。

如果要使用相对时间，需要加上

-

你可以指定

HH:MM_YYYYMMDD

YYYYMMDD

 MM/DD/YY

该参数用来指定要获取的数据的格式。 支持以下取值：

<target name>,<start timestamp>,<end timestamp>,<series step>|[data]*

entries,1311836008,1311836013,1|1.0,2.0,3.0,5.0,6.0

entries,2011-07-28 01:53:28,1.0
entries,2011-07-28 01:53:29,2.0
entries,2011-07-28 01:53:30,3.0
entries,2011-07-28 01:53:31,5.0
entries,2011-07-28 01:53:32,6.0

[{
  "target": "entries",
  "datapoints": [
    [1.0, 1311836008],
    [2.0, 1311836009],
    [3.0, 1311836010],
    [5.0, 1311836011],
    [6.0, 1311836012]
  ]
}]

{
  "labels" : [
    "Time",
    "entries"
  ],
  "data" : [
    [1468791890000, 0.0],
    [1468791900000, 0.0]
  ]
}

[{
  "target": "entries",
  "datapoints": [{
    "y": 0.0,
    "x": 1468791890
  }, {
    "y": 0.0,
    "x": 1468791900
  }]
}]

[
  {
    'name' : 'summarize(test.data, "30min", "sum")',
    'start': 1335398400,
    'end'  : 1335425400,
    'step' : 1800,
    'values' : [None, None, 1.0, None],
  }
]

你可以指定多个参数，来控制生成的图形的样式：

# 颜色名称
&bgcolor=blue
# HEX代码
&bgcolor=2222FF
# HEX代码，包含透明度
&bgcolor=5522FF60

上一章内容我们讨论了如何获取Graphite数据。通过Render URL API，我们不但可以获得文本数据，还可以直接获得渲染好的图片。这意味着通过Render URL API本身就可以实现Metrics的渲染，你只需要把生成的图片嵌入到自己的应用程序中即可。

Graphite Webapp本身提供了基于ExtJS的一个管理界面，你可以通过

http://GRAPHITE_HOST:GRAPHITE_PORT/admin

Graphite生成的Metrics曲线的图片，不是非常美观，而静态图片也缺乏交互性。因此，实际项目中常常结合使用第三方基于JavaScript的Charts库来做展示，例如：

1. Grafana：UI比较绚丽，支持设计仪表盘、时间区间联动。参见：使用Grafana展示时间序列数据
2. Graphene：一个较为简单的，基于D3.js和Backbone.js的Graphite仪表盘工具

除了简单的，基于Key/Value的Metrics数据，Graphite还可以存储、展示随机出现的数据——事件。

事件不适合存储在Whisper中，因此它被存储在Graphite的Webapp的数据库中（默认使用SQLite）。

通过向

http://GRAPHITE_HOST:GRAPHITE_PORT/events/

{ 
    "what": "事件类型", 
    "tags": "标签",
    "data": "事件相关的数据" 
}

指定target为

event(*tags)

/render

[
   {
      "target" : "events(mytag)",
      "datapoints" : [
         [
            1,
            1388966651
         ],
         [
            3,
            1388966652
         ]
      ]
   }
]

你也可以通过

/render/events/get_data

[
   {
      "when" : 1392046352,
      "tags" : "mytag",
      "data" : "...",
      "id" : 2,
      "what" : "Event - deploy"
   }
] 

Django的request对象曾经有一个属性REQUEST，用来获得通过GET或者POST请求传递的请求参数，在1.9版本中此属性已经移除。

Graphite代码没有即时更新，存在不兼容的问题，修改一下即可：

def parseOptions(request):
   queryParams = request.GET # request.REQUEST已经被移除

还有很多其它views.py存在同样的问题，最好搜索一下一并修改。如果觉得麻烦可以安装兼容版本的Django：

pip install django==1.8.14

The post Graphite学习笔记 appeared first on 绿色记忆.

MongoDB是一个开源的文档数据库（Document Database），具有高性能、高可用性、自动化的可扩容性。

高性能的持久化能力，主要体现在：

1. 对内嵌数据模型的支持，减少了数据库系统的I/O活动
2. 支持索引，加快了查询速度。可以包含来自内嵌文档、数组的索引键

高可用性由MongoDB的数据复制机制 —— 复制集（Replica set，一系列持有相同数据集的MongoDB实例）提供，主要体现在：

1. 自动的故障转移
2. 数据冗余

水平可扩容性主要体现在：

1. 分片（Sharding）机制，在集群中分布数据
2. 从3.4开始，支持基于分片键（Shard key）来划分数据区域（Zone）。在平衡化的集群中，MongoDB把读写操作定向到包含目标数据的区域中

所谓文档数据库，是指数据库中的每一条记录是一个“文档”。MongoDB的记录（文档）格式类似于JSON，由一系列字段组成，每个字段的值可以是文档、文档的数组、简单的值。文档格式的优势在于：

1. 文档很自然的对应了主流编程语言中的原生数据结构（对象）
2. 内嵌的文档、数组避免了关系型数据库昂贵的Join操作
3. 由于支持动态Schema（动态字段），因此对动态的支持很轻松

MongoDB提供了富查询语言（Rich Query Language），除了支持读写操作以外，还支持数据聚合、文本搜索、地理空间查询。

MongoDB支持可拔插的存储引擎，你可以自己依据API开发存储引擎，或者使用开箱即用的WiredTiger、MMAPv1

MongoDB存储记录 —— BSON文档（JSON的二进制形式）到集合（Collection）中，数据库中包含多个集合。集合的概念类似于RDBMS的表。

要指定使用的数据库，可以通过use语句：

use newdb
# 下面的命令列出现有的数据库 
show dbs

如果newdb不存在，MongoDB会在你第一次向其中存储数据时自动创建。类似的，使用不存在的集合时，也会自动的创建：

// 执行下面的语句时，会自动创建数据库newdb和集合newcoll
db.newcoll.insertOne({x:1});

// 你也可以显式的创建集合，并提供参数，例如最大尺寸、文档验证规则
db.createCollection()

在3.2版本之前，集合中存放的文档的Schema是任意的。3.2开始，你可以提供文档验证规则（Document Validation Rules）来限制某个集合中文档的结构。插入/更新文档时，必须满足规则。

除了定义数据记录之外，MongoDB在很多地方使用文档结构，包括但是不限于：

1. 查询过滤器
2. 更新规格文档（update specifications documents）
3. 索引规格文档（update specifications documents）

BSON类似于JSON，但是它的字段具有更丰富的类型，例如：

var mydoc = {
    // 类似于UUID，但是支持快速生成，且有序
    _id: ObjectId( "5099803df3f4948bd2f98391" ),
    // 内嵌文档
    name: { first: "Alan", last: "Turing" },
    // 日期
    birth: new Date( 'Jun 23, 1912' ),
    death: new Date( 'Jun 07, 1954' ),
    // 数组
    contribs: [ "Turing machine", "Turing test", "Turingery" ],
    views: NumberLong( 1250000 )
}

BSON字段的命名限制：

1. 名称_id保留用作主键，即指必须在集合中唯一、不可变。其类型可以是除了数组之外的任何类型
2. 字段名不得以 $开头
3. 字段名不得包含 . 号
4. 字段名不得包含空字符（\0）

BSON支持重名字段，但是大部分MongoDB客户端使用哈希呈现文档，哈希不支持重名key。MongoDB进程产生的某些文档会使用重名字段，但是绝不会向用户定义的文档中添加重名字段。

对于被索引集合（Indexed collections），被索引的字段的值的长度，受到最大索引键长度的约束。

要访问内嵌文档、数组的元素，需要使用点号标记：

mydoc.name.first
mydoc.contribs.2

BSON文档的最大尺寸是16MB。要存储更大的文档，可以使用GridFS API。

文档中字段的顺序，和插入文档时指定的顺序一致，除了两点例外：

1. _id总是作为第一个字段
2. 重命名字段名的操作可能导致文档中的字段重排序。从2.6开始，MongoDB积极的尝试保持字段顺序

db.test.insertOne( { ts: new Timestamp() } );
db.test.find()
# { "_id" : ObjectId("542c2b97bac0595474108b48"), 
#   "ts" : Timestamp(1412180887, 1) }

集合中的每一个文档，都必须具有作为主键的_id字段。

如果用户没有指定该字段，MongoDB驱动会自动生成一个ObjectId类型的_id，如果驱动没有生成_id则mongod会生成ObjectId类型的_id。此规则适用于插入操作，以及指定了upsert: true的更新操作。

在创建集合的过程中，MongoDB在_id上创建唯一性索引。

你可以考虑使用以下数据类型作为_id：

1. ObjectId类型
2. 可以考虑使用自然键，可以节省空间并减少索引
3. 使用自增长数字
4. 在应用程序中生成UUID，可以保存为BinData以节省空间

当比较不同BSON类型的值时，MongoDB使用如下（从低到高）比较顺序：MinKey、Null、Numbers (ints, longs, doubles, decimals)、Symbol, String、Object、Array、BinData、ObjectId、Boolean、Date、Timestamp、Regular Expression、MaxKey (internal type)

在比较时，MongoDB把某些BSON类型当做一种类型看待，例如各种数字类型。

比较字符串时，默认使用简单的二进制比较的方式。从3.4开始，支持所谓排序规则（Collation） —— 用于指定语言相关（是否大小写敏感、是否有声调）的排序算法。排序规则的规格如下：

{
   locale: <string>,  // 该字段必须
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

比较数组时，小于比较/升序排序基于数组的最小元素进行，大于比较/降序排序基于数组的最大元素进行。

比较BinData时，按照以下顺序进行：

1. 比较数据的长度
2. 根据BSON单字节子类型比较
3. 执行逐字节比较 

从3.4版本开始，MongoDB支持在现有的集合、其它视图之上，创建只读的视图（View）。

要创建视图，你可以使用create命令，指定viewOn、pipeline选项，可选的，指定一个collation选项：

db.runCommand( { 
    create: <view>, viewOn: <source>, pipeline: <pipeline>, collation: <collation> 
} )

// 也可以使用新引入的Shell助手：
db.createView(<view>, <source>, <pipeline>, <collation> )

那些用于列出集合列表的操作，例如db.getCollectionInfos()、db.getCollectionNames()，它们的输出包含视图。

要删除视图，可以使用命令：

db.collection.drop()

1. 只读，对视图进行写操作导致错误
2. 索引与排序：视图使用其底层的集合上的索引，你不能在视图上使用$natural排序
3. 投影操作限制：在视图上进行find()操作，不支持以下投影操作：$、$elemMatch、$slice、$meta
4. 视图的名字不可改变 

视图在读操作发生时，按需的进行计算。在视图上执行的读操作，是底层聚合管道（ aggregation pipeline）的一部分，因此，视图不支持：

1. db.collection.mapReduce()
2. $text操作符，因为聚合中的$text仅仅对于第一阶段（first stage）有效
3. geoNear命令以及$geoNear管道阶段（pipeline stage） 

如果底层集合是分片的，则视图也是分片的。因此不能为$lookup、$graphlookup操作的from字段指定一个分片的视图。

1. 在创建视图时，可以指定一个默认的排序规则（collation，判断两个比较项谁大谁小的准则）。如果不指定，视图的默认排序规则是简单的二进制比较排序规则。视图不会从底层集合继承排序规则
2.  在视图上进行字符串比较，使用视图默认排序规则。尝试修改视图默认排序规则的操作会失败
3. 如果基于其它视图创建新视图，你不能指定不同于源视图的排序规则
4. 当执行牵涉到多个视图的聚合操作时，例如$lookup、$graphlookup，所有牵涉到的视图必须具有一致的排序规则

定长集合（Capped Collections）是用于支持高吞吐量操作（插入、按插入顺序读取）的、具有固定尺寸的集合。定长集合的工作方式类似于环形缓冲，一旦空间占满，最老的文档会被覆盖。

创建定长集合的方法：

// size 集合的最大字节数，小于4096则MongoDB自动设置为4096。否则，自动舍入到最接近的256的倍数
db.createCollection( "log", { capped: true, size: 100000 } )
// 可以指定max，集合包含的文档的最大数量
db.createCollection("log", { capped : true, size : 5242880, max : 5000 } )

当你使用find()来操作定长集合，并且没有指定顺序时，MongoDB保证结果的顺序和文档插入的顺序一致。要逆插入序获得结果，可以：

db.cappedCollection.find().sort( { $natural: -1 } )

可以使用集合的isCapped方法检测定长集合：

db.collection.isCapped()

普通集合可以被转换为定长集合：

db.runCommand({"convertToCapped": "mycoll", size: 100000});

1. 定长集合记住文档的插入顺序， 查询时不需要基于索引以得到文档。没有了维护索引的负担，定长集合支持更高的插入吞吐量
2. 定长集合具有 _id 字段，并在其上默认建立了索引
3. 如果你需要对定长集合中的文档进行update操作，应当建立索引，避免全集合扫描
4. 定长集合不支持删除文档，如果更新/替换操作改变了文档的尺寸，会失败
5. 定长集合不支持分片
6. 聚合管道操作符$out不能把结果输出到定长集合

# 在容器中运行MongoDB
docker run --name mongodb -p 27017:27017 -v ~/Docker/volumes/mongodb/data/db:/data/db -d mongo:3.4
# 登录到MongoDB管理Shell
docker exec -it mongodb mongo admin

Mongo Shell是交互式的、基于JavaScript语言的MongoDB接口。使用此Shell你可以查询、插入数据，或者执行管理任务。

要启动Mongo Shell，cd到安装目录，执行mongo命令。不加任何参数时，Shell尝试连接到localhost:27017。Shell启动时默认会读取~/.mongorc.js文件，并执行其中的JavaScript脚本。

# 连接到本地 27017
mongo
# 连接到复制集
mongo --host rs1/mongo-11.gmem.cc,mongo-12.gmem.cc,mongo13.gmem.cc
# 使用指定的用户登陆到服务器，连接到bais数据库，基于admin数据库进行身份验证
mongo -u root -p root --host  mongo-11.gmem.cc --authenticationDatabase admin bais

// 显示当前正在使用的数据库
db
// 切换数据库
use mydb
// Shell不支持使用名字中包含空格或者以数字开始的集合，需要改变语法：
mydb.3test.find()    // 错误
mydb["3test"].find()
mydb.getCollection("3test").find()

// 美化输出
db.myCollection.find().pretty()

// 打印输出
print()
// 转换为JSON并打印，等价于printjson() 
print(tojson(obj))

// 退出Shell
quit()

当输入行以花、圆、方括号结尾时，下面的行自动以...开头，直到所有开括号的匹配关闭括号都输入了，再回车，输入才会被估算。

默认的命令提示符是

>

// 显示计数器
cmdCount = 1;
prompt = function() {
    return (cmdCount++) + "> ";
}

// 显示数据库和主机信息
host = db.serverStatus().host;
prompt = function() {
   return db+"@"+host+"$ ";
}

你可以在MongoDB Shell中使用自己喜欢的编辑器，只需要在启动Shell之前设置环境变量： 

export EDITOR=vim

这样，你就可以编辑变量或者函数了：

edit myFunc

db.collection.find()会返回一个游标，但是，在Shell中没有把游标赋值给一个变量的情况下，Shell会自动迭代游标20次，并打印结果到屏幕上。这个迭代的次数是可以定制的：

DBQuery.shellBatchSize = 10;

 你可以使用JavaScript语言编写一段脚本，交由Shell执行，以完整数据操控、管理工作：

# 命令行中提供脚本
mongo test --eval "printjson(db.getCollectionNames())"
# 文件方式提供脚本
mongo localhost:27017/test myjsfile.js
# 在Shell中加载JS
load("myjstest.js")

conn = new Mongo();
db = conn.getDB("myDatabase");

// 也可以使用connect函数
db = connect("localhost:27020/myDatabase");

不能在JavaScript中使用任何Shell助手，因为不是合法的JavaScript表达式。等价写法如下表：

BSON提供了很多数据类型，不同驱动都根据其宿主编程语言，提供了Native的类型映射。Shell类似，提供了助手类以支持这些数据类型。

ISODate('2008-08-08T08:08:08.888Z')

new ObjectId

ObjectId()

NumberLong("1111")

 要检测对象的数据类型，可以使用：

mydoc._id instanceof ObjectId
// 或者
typeof mydoc._id

在MongoDB中，写操作在单个文档上是原子的，即使在修改多个内嵌的文档的情况下。

相反的，当一个写操作操控了多个文档的情况下，整个操作默认不是原子的。多个写操作可能会发生交叉（interleave）、而且不会在中途出错后回滚

如果要为影响了多个文档的单个写操作建立隔离性语义，可以使用

$isolated

注意：

1. 该操作符不能与分片集群（Sharded Clusters）协同工作
2. 该操作符不能提供all-or-nothing的原子性语义。如果中途发生错误，已经发生的修改不会回滚
3. 该操作符符导致当前操作获得目标集合上的独占锁，即使在使用支持文档级锁的引擎（WiredTiger）的情况下

$isolated产生的隔离效果，在修改了第一个文档后显现。

由于MongoDB支持内嵌文档，因此在很多应用场景下，单文档级别的原子性足够应付。

如果多个写操作需要在单个事务中执行，可以考虑在代码中实现两阶段提交（two-phase commit ）模式 。注意这只能提供类似于事务的语义，用于保证数据一致性，却不能避免中间结果被其它操作看到

一致性控制允许多个程序并发的执行，而不导致数据不一致或者冲突。

实现一致性控制的可选方式：

1. 在应当具有唯一性值的（一个或者多个）字段上创建一个唯一性索引，以阻止重复的数据插入
2. 使用查询断言（Query predicate）指定某个字段的当前期望值

为保证数据一致性，MongoDB使用锁机制来管理多客户端的并发读写。

MongoDB使用多粒度的锁，操作可能在全局、数据库、集合级别进行锁定。同时允许存储引擎实现更加细粒度的锁定，例如WiredTiger支持文档级别的锁定。

MongoDB使用读写锁（共享锁S，独占锁X），允许多个读操作共享同一资源。对于MMAPv1，写操作权限仅仅能赋予单个写操作。

除了S、X锁以外，MongoDB还支持读意向锁（IS）、写意向锁（IX），表示操作将要对（比被意向锁定的资源）更加细粒度的资源进行读写操作，IX是可以共享的，意向锁可以减少不必要的锁检查。当在某一级别进行锁定时，更高级别（粗粒度）资源被意向锁定。举例来说，当X锁一个集合进行写操作时，对应的数据库、全局必须上IX锁。

单个数据库可以同时被IS、IX锁。X锁不能与其它锁共存。S锁仅仅能和IS锁共存。

MongoDB的锁是公平的，操作依据排队的顺序被授予锁。但是为了吞吐量的考虑，兼容的锁可能被一并授予，而不考虑排队情况。

某些情况下，读写操作可能让出它们占有的锁。长时间运行的读写操作，可能在多种情况下让出锁。对于影响到多个文档的操作，锁让出可能在修改每个文档前后发生。

MMAPv1引擎会在认为需要读取的数据不在物理内存的时候，让出锁，等MongoDB把目标数据加载到内存之后，再重新获得锁。

MongoDB游标可能出现反常行为 —— 迭代同一个文档超过一次。发生这种现象的原因是，在游标迭代期间，某个写操作交叉进来并修改了某个文档。如果：

1. 被修改文档存储位置发生移动（例如文档大小增长导致）
2. 或者查询所使用的索引对应的字段值被修改

则可能出现重复迭代。

要防止此情形的出现，你可以使用

cursor.snapshot()

1. 该调用不能保证查询返回的数据是某个时间点的快照，不能和其它写操作隔离
2. 不支持分片集群
3. 不能和游标方法sort()、hint()联用

另一个防止此情形的方法是，在不会修改的字段上建立唯一索引，然后使用hint()强制使用该索引，可以产生类似于snapshot()的效果。

所为单调写（Monotonic Writes），是指写操作扩散的顺序和它们逻辑上的顺序一致。MongoDB针对单实例mongod、复制集、分片集群提供单调写保证。

3.4引入的新特性。

针对在主节点上执行的读、写操作。使用linearizable读关注发起的读操作，和使用m:majority发起的写操作，如果这些读写操作针对单个文档进行操作，其效果就好像单个线程在执行这些读写一样，也就是说它们的实时顺序获得保证。

使用分片集群，你可以在多个mongod组成的服务器群中进行数据的分区，该分区对于应用程序来说几乎是透明的。

在分片集群中，客户端向关联到集群的某个mongos（路由器）实例发起操作请求，后者将请求转发给适当的分片：

当被转发到单个特定的分片上时，针对分片集群的读操作效率最高。

针对分片集合的查询，应当包含集合的分片键（Shard key），这样mongos可以基于集群元数据（来自配置服务器）进行准确的路由。如果不包含分片键，则必须向所有mongod实例转发请求并聚合响应，这种分散 - 聚集（scatter gather ）模式通常效率不高。

对于复制集分片，发送给从节点的读操作可能和主节点的最新状态不一致（不确定的延迟）。这种行为可能导致牵涉到多个从节点的非单调读 —— 后入库的数据比先入库的数据先被读到。 

默认情况下，客户端针对复制集的主节点进行读操作。但是客户端可以使用Read perference把读请求定向到复制集的其它成员。例如，客户端可以配置以便从最近的节点进行读取以达成以下目标：

1. 在跨数据中心部署的情况下，减少延迟
2. 可以分散大量读请求以增大吞吐量
3. 执行备份操作
4. 在新的主节点被选举出来前，仍然可以执行读操作

针对从节点进行读操作，得到的可能不是主节点的最新状态，重定向到不同从节点的读操作可能导致非单调读。

对于分片集群中的分片集合，mongos负责把写操作分发到负责对应数据集的那些分片，路由时mongos从配置数据库（config database，位于config server）中查询元数据信息，并判断如何分发写操作。

MongoDB依据分片键的值范围（支持Hash方式么）来进行数据分区，之后把这些分区（chunks）发布到某些分片上（Shard，即mongod实例）。

对于update类操作来说，如果：

1. 针对单个文档，更新操作必须包含分片键或者_id字段
2. 针对多个文档，如果更新操作包含分片键性能在某些情况下会更好，但是有时仍然会广播操作到所有分片

如果分片键的值在每次插入时总是递增/递减，那么连续的很多插入操作会落到同一个分片中，产生性能瓶颈。 

在复制集中，所有写操作都针对主节点。 主节点应用写操作，然后把操作记录在自己的操作日志（oplog）中。oplog是可重做的写操作流水，所有从节点都会复制该日志并应用，从节点的操作均是异步的，因此不能假设何时主从节点状态完全一致。

这是一种编程模式，当你进行多文档“事务”操作时，你可以实现类似关系型数据库的回滚功能。

在MongoDB中单文档的写操作总是原子的，但是写操作牵涉到多个文档时（通常称为多文档事务）则没有原子性保证。由于MongoDB支持任意复杂度的内嵌文档，因此很多应用场景下不需要多文档操作。

尽管如此，某些情况下你不得不进行多文档写操作。当执行由一系列写操作序列构成的事务时，可能面临以下需求：

1. 原子性：如果操作中途失败，前面已经完成的操作需要回滚
2. 一致性：如果重大错误（网络、硬件）中断了事务，数据库必须有能力恢复到一个一致性的状态

考虑转账的应用场景：你需要从账户A转账到账户B。使用关系型数据库时，你需要在单个事务中，减去A账户的余额并加到B账户中去。使用MongoDB时，你可以手工实现两阶段提交，模拟一个类似的结果。

在该场景中，我们使用集合accounts来存储账户信息，transactions存储交易信息。

正常交易流程的代码如下：

// 初始化账户信息，下面的调用返回一个BulkWriteResult对象
db.accounts.insert(
    [
        { _id: "A", balance: 1000, pendingTransactions: [] },
        { _id: "B", balance: 1000, pendingTransactions: [] }
    ]
)
// 初始化交易（转账）信息，state反应交易的状态，可以取值initial, pending, applied, done, canceling,canceled
db.transactions.insert(
    { _id: 1, source: "A", destination: "B", value: 100, state: "initial", lastModified: new Date() }
)

// 使用两阶段提交来转账
// 1、找到一个初始状态的交易记录
var t = db.transactions.findOne( { state: "initial" } )
// 2、更新交易状态，如果返回值的nMatched、nModified为零，说明被上一步找到的记录，被其它客户端处理过，
//    返回第1步，获取下一条记录
db.transactions.update(
    { _id: t._id, state: "initial" },
    {
        $set: { state: "pending" },
        $currentDate: { lastModified: true }
    }
)
// 3、把交易关联到两个账户，过滤条件pendingTransactions可以防止重复转账
db.accounts.update(
    { _id: t.source, pendingTransactions: { $ne: t._id } },
    { $inc: { balance: -t.value }, $push: { pendingTransactions: t._id } }
)
db.accounts.update(
    { _id: t.destination, pendingTransactions: { $ne: t._id } },
    { $inc: { balance: t.value }, $push: { pendingTransactions: t._id } }
)
// 4、更新交易状态为applied
db.transactions.update(
    { _id: t._id, state: "pending" },
    {
        $set: { state: "applied" },
        $currentDate: { lastModified: true }
    }
)
// 5、更新账户第pending交易列表
db.accounts.update(
    { _id: t.source, pendingTransactions: t._id },
    { $pull: { pendingTransactions: t._id } }
)
db.accounts.update(
    { _id: t.destination, pendingTransactions: t._id },
    { $pull: { pendingTransactions: t._id } }
)
// 6、设置交易状态为done
db.transactions.update(
    { _id: t._id, state: "applied" },
    {
        $set: { state: "done" },
        $currentDate: { lastModified: true }
    }
)

交易的关键之处在于，能够从各种错误场景中恢复，而不是简单完成上述6个步骤。

两阶段提交模式允许应用程序应用程序执行一个操作序列，以便恢复事务到一致性的状态 —— 这种能力由代码中刻意安排的filter保证。你可以在应用程序启动时，或者周期性的执行恢复操作，以便捕获并处理那些未完成的事务。

事务经历多就没有完成，则需要恢复，取决于应用程序的需要，我们刻意使用lastModified判断事务的最后操作时间。

找到需要恢复的事务后，根据state确定尚未完毕的后续步骤，并执行。

某些时候（例如交易被撤销，或者目标账户在交易过程中被关闭），你需要回滚（撤销，传统意义的回滚，在MongoDB中rollback这个术语通常情况下不是这个含义）一个事务操作。 

两阶段提交模式中，你需要手工实现“补偿行为”来进行回滚。

各类驱动连接MongoDB时，均需要提供一个连接字符串，其格式为：

mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]
# 示例
mongodb://172.21.3.1:27017,172.21.3.2:27017/?replicaSet=rs3&connectTimeoutMS=300000

其中：

# 指定两类tags和一个空tag
readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags= 

这类操作添加新的文档到集合中，如果目标集合不存在，会自动创建。MongoDB提供以下插入文档的方法：

# 插入一个文档
db.collection.insertOne()
# 插入多个文档
db.collection.insertMany()

 从单个文档级别上来看，所有MongoDB的写操作都是原子的。

use local
db.users.insertOne({ name : 'Alex', age : 29, gender : 'M'})
db.users.insertMany([
    { name: 'Meng', age: 26, gender : 'F'},
    { name: 'Cai', age: 2, gender : 'F'},
    { name: 'Dang', age: 0, gender : 'M'},
])

from pymongo import MongoClient
if __name__ == '__main__':
    client = MongoClient('mongodb://localhost:27017/')
    db = client.local  # 或者 client['local']
    db.users.insert_one({
        'name': 'FengYu',
        'age': 59,
        'gender': 'F'
    })

引入依赖：

<!-- 同步驱动 -->
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver</artifactId>
    <version>3.4.2</version>
</dependency>

<!-- 异步驱动，支持更快的非阻塞的IO -->
<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongodb-driver-async</artifactId>
    <version>3.4.2</version>
</dependency>

MongoDB的Java驱动提供了同步、异步两套接口。同步代码示例：

package cc.gmem.study;

import com.mongodb.MongoClient;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import org.bson.Document;
import org.junit.Test;

public class CRUDTest {

    @Test
    public void insertDoc() {
        MongoClient client = new MongoClient( "localhost", 27017 );
        MongoDatabase db = client.getDatabase( "local" );
        MongoCollection<Document> coll = db.getCollection( "users" );
        Document doc = new Document( "name", "CongHua" ).append( "age", 55 ).append( "gender", "M" );
        coll.insertOne( doc );
    }
}

异步代码示例： 

package cc.gmem.study;

import com.mongodb.async.SingleResultCallback;
import com.mongodb.async.client.MongoClient;
import com.mongodb.async.client.MongoClients;
import com.mongodb.async.client.MongoCollection;
import com.mongodb.async.client.MongoDatabase;
import org.bson.Document;
import org.junit.Test;

import java.util.concurrent.CountDownLatch;

public class CRUDTest {

    @Test
    public void insertDoc() throws InterruptedException {
        // 这个客户端相当于连接池，即使你有很多并发操作，也不需要第二个实例
        MongoClient client = MongoClients.create( "mongodb://localhost" );
        MongoDatabase db = client.getDatabase( "local" );
        MongoCollection<Document> coll = db.getCollection( "users" );
        Document doc = new Document( "name", "GuangFang" ).append( "age", 55 ).append( "gender", "F" );
        // 这里采用同步机制等待异步操作完成
        final CountDownLatch latch = new CountDownLatch( 1 );
        coll.insertOne( doc, ( result, t ) -> {
            System.out.println( "OK" );
            latch.countDown();
        } );
        latch.await();
    }
}

安装MongoDB的Node.js驱动：

npm install mongodb

const mongo = require( 'mongodb' );
let client = mongo.MongoClient;
client.connect( 'mongodb://localhost:27017/local' ).then( db => {
    return db.collection( 'users' ).insertOne( {
        name: 'GuangLiang',
        age: 55,
        gender: 'M'
    } );
} ).then( result => console.log( result.insertedId ) );

这类操作从集合中检索并返回若干文档。MongoDB提供以下方法：

db.collection.find(<query>, <projection>)
# 可以指定一个参数作为查询文档（Query Document），查询文档提供查询条件
db.collection.find( { 'name' : 'Alex' } )

client = MongoClient('mongodb://localhost:27017/')
db = client['local']
# 传入空文档作为查询过滤器，得到所有文档，返回值是一个游标
cursor = db.users.find({})
# { <field1>: <value1> } 表示相等过滤，例如
cursor = db.users.find({'gender': 'F'})
# { <field1>: { <operator1>: <value1> } } 使用查询操作符，例如
cursor = db.users.find({'age': {'$gt': 30}})
# 逻辑与
cursor = db.users.find({'gender': 'F', 'age': {'$gt': 30}})
# 逻辑或
cursor = db.users.find({
    '$or': [{'gender': 'F'}, {'age': {'$gt': 30}}]
})

查询操作的返回值是一个游标。你可以对其进行遍历操作：

cursor = db.trades.find({'state': 'A'})
for trade in cursor:
    print(trade)

# 对于PyPy、Jython以及其它不使用引用计数垃圾回收的Python实现，需要调用
cursor.close()

上面代码中，$or、$gt等以$开头的键，属于查询操作符（Query Operator），是操作符的一种。常用的查询操作符如下表：

# 存在qty字段，且该字段的值不是5或者15
{ qty: { $exists: true, $nin: [ 5, 15 ] } }

# 匹配qty为12的文档，因为12%4 = 0
{ qty: { $mod: [ 4, 0 ] } }

{ <field>: { $regex: /pattern/, $options: '<options>' } }
{ <field>: { $regex: 'pattern', $options: '<options>' } }
{ <field>: { $regex: /pattern/<options> } }

{
  $text:
    {
      # 搜索内容，一个字符串，包含多个搜索关键词时进行逻辑或操作，除非指定为短语
      $search: <string>,
      # 可选，用于确定搜索的停用词（stop word）列表，以及词干分析器（Stemmer）
      # 和分词器（tokenizer）使用的规则，默认使用索引的语言
      $language: <string>,
      # 是否大小写敏感
      $caseSensitive: <boolean>,
      # 是否声调敏感
      $diacriticSensitive: <boolean>
    }
}

this

obj

# results字段中，至少有一个元素的值在80-85之间
{ results: { $elemMatch: { $gte: 80, $lt: 85 } } }

要根据内嵌文档进行查询过滤，只需要依次指出内嵌文档各字段的值：

# bson.son.SON类似于Python的字典，但是保持字段的顺序
# 匹配宽高为21/14cm的货物：
{"size": SON([("h", 14), ("w", 21), ("uom", "cm")])}
# 这种匹配，要求内嵌文档与查询条件完全相同，包括字段的顺序

要根据内嵌文档的某个字段进行查询过滤，可以使用点号导航：

db.inventory.find({"size.uom": "cm"})
# 和简单字段一样，可以使用查询操作符
db.inventory.find({"size.h": {"$lt": 15}})

# 匹配标签字段等于["red", "blank"]的存货
db.inventory.find({"tags": ["red", "blank"]})
# 匹配标签字段包含"red", "blank"这两个元素的存货
db.inventory.find({"tags": {"$all": ["red", "blank"]}})
# 匹配标签字段包含"red"元素的存货
db.inventory.find({"tags": "red"})
# 匹配size数组中至少有一个元素大于25的存货
db.inventory.find({"size": {"$gt": 25}})
# 匹配dim_cm数组中至少有一个元素大于15的存货、一个元素小于20的存货。可以单个元素同时满足连个条件
db.inventory.find({"dim_cm": {"$gt": 15, "$lt": 20}})
# 匹配dim_cm数组中至少有一个元素同时满足多个条件的存货
db.inventory.find({"dim_cm": {"$elemMatch": {"$gt": 22, "$lt": 30}}})
# 限定dim_cm的第2个元素的最小值
db.inventory.find({"dim_cm.1": {"$gt": 25}})
# 限定数组的大小
db.inventory.find({"tags": {"$size": 3}})

默认情况下，查询操作返回匹配文档的全部字段。为了减少传递给应用程序的数据量，你可以指定一个投影文档（Projection document）以限制返回的字段：

# 仅仅返回name字段
# 投影文档（第二个参数）的字段值，1表示结果包含此字段，0表示不包含，默认的_id被包含
db.users.find( { gender: 'F' }, { name: 1, _id: 0 } )

注意，除了_id字段之外，所有投影文档字段的值必须相等，当值：

1. 都为0的时候，表示结果排除这些字段
2. 都为1的时候 ，表示结果仅包含这些字段

要包含/排除内嵌文档中字段到查询结果，可以使用点号导航：

# 包含地址的邮编字段
db.users.find( {}, { name: 1, address.zip: 1 } )
# 包含最后一个孩子
db.users.find( {}, { name: 1, children: { "$slice": -1 } } )

上例中的$slice也是操作符，它属于投影操作符的一种：

db.collection.find( { array: value ... }, { "array.$": 1 } )
db.collection.find( { array.field: value ...}, { "array.$": 1 } )

client = MongoClient('mongodb://localhost:27017/')
db = client['local']
db.users.drop()
db.users.insert_many([
    {
        'name': 'Alex',
        'age': 30,
        'children': [{'name': 'Dang', 'age': 0}, {'name': 'Cai', 'age': 2}]
    },
    {
        'name': 'Meng',
        'age': 26,
        'children': [{'name': 'Dang', 'age': 0}, {'name': 'Cai', 'age': 2}]
    },
    {
        'name': 'FengYu',
        'age': 59,
        'children': [
            {'name': 'Alex', 'age': 30}, {'name': 'Meng', 'age': 26}, {'name': 'WenJun', 'age': 26}
        ]
    }
])
db.users.find({'children': {'$elemMatch': {'age': {'$lt': 1}}}}, {'name': 1, '_id': 0, 'children': 1})
# { "name" : "Alex", "children" : [ { "name" : "Dang", "age" : 0 }, { "name" : "Cai", "age" : 2 } ] }
# { "name" : "Meng", "children" : [ { "name" : "Dang", "age" : 0 }, { "name" : "Cai", "age" : 2 } ] }
db.users.find({'children': {'$elemMatch': {'age': {'$lt': 1}}}}, {'name': 1, '_id': 0, 'children.$': 1})
# { "name" : "Alex", "children" : [ { "name" : "Dang", "age" : 0 } ] }
# { "name" : "Meng", "children" : [ { "name" : "Dang", "age" : 0 } ] }

db.users.find(
    {'children': {'$elemMatch': {'age': {'$lt': 1}}}}, 
    {'name': 1, '_id': 0, 'children' : {'$elemMatch': {'age': {'$gt': 1}}}})
# { "name" : "Alex", "children" : [ { "name" : "Cai", "age" : 2 } ] }
# { "name" : "Meng", "children" : [ { "name" : "Cai", "age" : 2 } ] }

# 返回最前面5个元素
db.posts.find( {}, { comments: { $slice: 5 } } )
# 返回最后面5个元素
db.posts.find( {}, { comments: { $slice: -5 } } )
# 先跳过前20个元素，然后返回接着的10个元素
db.posts.find( {}, { comments: { $slice: [ 20, 10 ] } } )
#从倒数第20个元素开始，返回10个元素
db.posts.find( {}, { comments: { $slice: [ -20, 10 ] } } )

注意，针对视图进行的find()操作不支持上表中的投影操作符。

不同查询操作符处理null值的方式是不一样的，需要注意：

1. 等于操作符：

   { item : null }

   匹配item为null或者不包含item字段的文档
2. 类型检查操作符：

   { item : { $type: 10 } }

   仅仅匹配item值为null的文档
3. 存在性检查：

   { item : { $exists: false } }

   仅仅匹配不包含item字段的文档

这类操作修改既有的文档，MongoDB提供以下方法：

# 更新文档
db.collection.updateOne(<filter>, <update>, <options>)
db.collection.updateMany(<filter>, <update>, <options>)
# 替换掉文档
db.collection.replaceOne(<filter>, <replacement>, <options>)

参数filter类似于查询文档，update表示更新文档 —— 使用更新操作符来指定哪些字段需要怎么样被更新，replacement则是替换文档，直接替换掉原有的文档。

更新文档的格式：

{
  <update operator>: { <field1>: <value1>, ... },
  <update operator>: { <field2>: <value2>, ... },
  ...
}

更新代码示例：

db.inventory.update(
    # 过滤器，指定查询条件：item为paper
    {'item': 'paper'},
    # 更新文档：
    {
        # 可以同时设置多个字段
        '$set': {'size.uom': 'cm', 'status': 'P'},
        '$currentDate': {'lastModified': True}
    }
)

# 更新多个满足条件的文档
db.inventory.update_many(
    {'qty': {'$lt': 50}},
    {
        '$set': {'size.uom': 'in', 'status': 'P'},
        '$currentDate': {'lastModified': True}
    }
)

1. 原子性：对于单个文档来说，更新操作总是原子性的
2. _id字段：该字段不能被更新
3. 文档大小：当更新后，文档的尺寸大于先前分配的空间，则另外在磁盘上分配空间给它
4. 字段顺序：_id总是保持在最前面。包含重命名操作的更新操作可能会改变字段的顺序

{ $currentDate: { <field1>: <typeSpecification1>, ... } }
# 其中 typeSpecification格式：
# true，表示设置为当前日期
# { $type: "timestamp" }或者 { $type: "date" }明确的设置为当前时间戳或者日期

{ $bit: { <field>: { <and|or|xor>: <int> } } } 

db.foo.update(
    { status : "A" , $isolated : 1 },
    { $inc : { count : 1 } },
    { multi: true }
) 

{ "<arrayField>.$" : value }

{ $addToSet: { <field>: { $each: [ <value1>, <value2> ... ] } } }
{ $push: { <field>: { $each: [ <value1>, <value2> ... ] } } } 

{
  $push: {
     <field>: {
       $each: [ <value1>, <value2>, ... ],
       $slice: <num>
     }
  }
}

所谓替换，就是指替换掉文档的所有字段 —— _id除外。

这类操作删除既有的文档。MongoDB提供以下方法：

db.collection.deleteOne(<filter>)
db.collection.deleteMany(<filter>)  # 如果过滤文档为空文档，则集合中所有文档被删除

db.collection.remove()              # 删除匹配过滤文档的文档，有多少删除多少

过滤文档的格式参考查询文档。

1. 原子性：对于单个文档来说，删除操作是原子的
2. 对索引的影响：删除操作不会drop掉索引，即使集合中所有文档都被删除

MongoDB为客户端提供了批量写操作能力。批量写操作影响单个集合。 应用程序可以为批量写操作指定一个可接受的确认级别（acknowledgement level）。

下面的方法用于执行批量插入、更新或者删除操作：

db.collection.bulkWrite(<bulkOperationArray>, <options>)

bulkWrite支持insertOne、updateOne、updateMany、replaceOne、deleteOne、deleteMany这些写操作：

client.connect( 'mongodb://localhost:27017/local' ).then( db => {
    // 批量写仍然是针对单个集合的操作
    return db.collection( 'users' ).bulkWrite( [
        { insertOne: { document: { _id: 1, name: 'Alex', age: 30 } } },
        { insertOne: { document: { _id: 2, name: 'Meng', age: 27, gender: 'F' } } },
        {
            updateOne: {
                filter: { name: 'Alex' },
                update: {
                    $set: { gender: 'M' }
                }
            }
        }
    ] );
} ).then( result => console.log( result ) );

批量写操作支持有序、无序两种方式：

1. 有序：串行化的执行，如果其中某个操作失败，则MongoDB会返回，不处理后续的操作
2. 无序：并发的执行，如果其中某个操作失败，别的操作不受其影响

对于分片集合，无序批量写操作通常比有序的快。

默认的，MongoDB进行有序批量写，除非你指定选项：

ordered : false

大批量的数据插入操作可能影响分片集群（Sharded cluster）的性能，对于批量插入，考虑以下策略：

1. 集合预切分（Pre-split）：如果分片集合当前是空的，则集合仅仅包含一个位于单个分片中的初始块（initial chunk）。MongoDB必须花费时间来接收数据、切分数据，然后把切分好的数据块发送到可用的分片中。要避免此性能损失，可以考虑集合的与切分
2. 使用无序写：使用无序写选项可以提高性能，MongoDB会尝试把数据同时发送给多个分片
3. 避免单调递增瓶颈（Monotonic Throttling）：如果你的分片键（ shard key ）在插入过程中单调的递增，则所有插入的数据都会进入集合的最后一个块 —— 总是在单个分片上

查询选项

readConcern

readConcern: { level: <"majority"|"local"|"linearizable"> }

支持该选项的操作包括：find、aggregate 、distinct、count 、parallelCollectionScan 、geoNear 、geoSearch。

注意：节点上的最新数据，不代表是复制集系统中的最新数据

该选项可以取以下值：

写关注（Write concern）描述写操作请求的确认级别。这些写操作可以应用在单独的mongod、复制集或者分片集群。 对于分片集群，mongos实例会把写关注级别传递给分片。

从2.6开始，写操作的新协议集成了写关注，你不再需要在写操作之后紧跟着一个getLastError调用来指定写关注级别。

写关注相关的选项包括： 

{ w: <value>, j: <boolean>, wtimeout: <number> }

其中：

1. w选项：要求当前写操作已经传播到指定数量的mongod实例，或者具有指定tag的mongod实例
2. j选项：要求当前写操作已经写入到磁盘日志
3.  wtimeout：等到上述两个条件达成的超时，防止无限阻塞

j: true

从3.2开始，该选项导致写操作仅仅在：指定数量（w选项）的复制集节点都写了日志后才返回，之前仅仅要求主节点写了日志就返回（因而就不存在主节点故障转移导致的回滚问题？）

指定一个毫秒的限制，但是仅仅用于w取值大于1的情况。如果不指定此选项或者指定为0，可能导致永久的阻塞。

当超时到达后，调用立即以一个错误返回，然而后续所要求的写关注可能成功。 当返回后，MongoDB不会撤销已经执行的数据修改。

默认情况下，当客户端消费了游标中所有结果集后，MongoDB会自动关闭游标。

但是，对于定长（Capped）集合来说，你可以使用可追加游标（Tailable Cursor）。该游标在客户端耗尽所有结果集后仍然保持打开状态。从概念上来说，这种游标类似于UNIX命令tail -f。当客户端插入新数据到集合中后，可追加游标会继续取回文档。

在高写入量、不适用索引的定长集合上，可以使用这种游标。例如，MongoDB本身的复制机制，就是在主节点的oplog这个定长集合上使用可追加游标。

注意可追加游标的以下特性：

1. 该游标不使用索引，以自然顺序—— 在磁盘上的存储顺序 ——返回文档
2. 由于不使用索引，可追加游标的最初扫描代价很高，但是一旦最初扫描的结果被耗尽后，再取回新的文档，成本很低
3. 可追加游标可能变得不可用，可能的情况包括：
   1. 查询返回结果为空
   2. 游标返回位于集合尾部的文档，而应用程序随后删除了此文档

MongoDB的查询优化器会分析查询，然后选择最高效的执行计划。后续执行相同查询时，会使用同样的执行计划。

查询优化器会缓存执行计划，但是仅仅缓存那些可以有多个执行路径的查询形状（Query shape，指查询断言、排序、投影的组合）。

查询规划器（query planner ）针对每个查询，搜索执行计划缓存，寻找匹配查询形状的计划。如果匹配的计划不存在，查询规划器会生成候选的计划，在“试用期间”评估它们，然后选取其中最高效的，并缓存该执行计划。

如果匹配的计划存在，查询规划器则会通过replanning机制重新评估其性能，如果评估不通过对应的缓存条目被清除。在发生清除的情况下，查询规划器会按照正常流程重新选择执行计划并缓存。

上述逻辑的流程图如下：

你可以使用

db.collection.explain()

cursor.explain()

当mongod重新启动或者关闭后，所有执行计划的缓存都被清除。

从2.6开始，提供了一些方法来控制缓存：

PlanCache.clear()

PlanCache.clearPlansByQuery()

索引过滤器决定查询优化器使用哪些索引来评估查询形状。当为查询形状指定了索引过滤器时，仅过滤器中包含的索引会被用来优化查询。

索引过滤器存在时，MongoDB会忽略

hint()

要检查索引过滤器是否存在，获取db.collection.explain()或者cursor.explain()返回值的

indexFilterSet

在服务器关闭后，索引过滤器不会持久化。MongoDB也提供了手工移除索引过滤器的命令。

本节内容简单的介绍一些优化查询的方向。

通过减少查询操作需要处理的数据的量，索引可以提升读操作、更新操作以及聚合管线部分阶段的性能。

如果你的业务通常基于某个、某些字段对集合进行查询，你可以考虑在字段上创建索引、复合索引。这可以避免查询操作进行全集合扫描。创建索引的示例代码：

db.inventory.createIndex( { type: 1 } )

除了优化读操作外，索引还可以用来支持排序操作、优化存储空间利用。

由于MongoDB支持升序、降序读取索引，因此对于单键索引来说，其方向不重要。

在大部分情况下，查询优化器都会选择合适的索引。如果你需要强制指定一个索引，可以调用

hint()

该操作符用于增加或者减少字段的值。它在服务器端工作，不需要把原先的值取到客户端。

该操作符也避免了多个客户端同时get-and-set时的竞态条件。

如果知道需要返回的数据的量，可以使用limit()：

db.posts.find().sort( { timestamp : -1 } ).limit(10)

另外，可以使用投影，仅仅返回需要的字段。 

Query Selectivity用来度量查询断言（条件）过滤掉集合中文档的强度，针对主键的唯一性查询的选择性最高 —— 因为它只会匹配单个文档。查询选择性决定了是否能高效的使用索引，甚至是能否使用索引。

低选择性的常见例子是$nin、$ne查询操作符，它们通常都会匹配索引值域的很大一部分。这导致使用索引有时还不如直接全文档扫描快，因此索引不被使用。

如果使用正则式来指定字段值（条件），查询的选择性取决于正则式本身

所谓Covered Query是指索引即可满足查询所需的全部字段，不需要执行文档扫描的情况，需要配合投影使用：

# 复合索引
db.inventory.createIndex( { type: 1, item: 1 } )
# 覆盖查询
db.inventory.find(
    { type: "food", item:/^c/ },
    { item: 1, _id: 0 }  # 被覆盖，注意指定_id:0排除了主键字段，确保了覆盖
)

覆盖查询通常具有很高的性能（相对那些需要检索文档的查询），原因包括：

1. 索引键值通常要比对应的文档小
2. 索引常常驻留内存，或者在磁盘上顺序的分布 

以下情况下，索引无法覆盖查询：

1. 任意索引字段，在任意一个文档中存储了数组时。当索引字段存储了数组后，索引称为多键索引（Multi-key Index），这种索引不支持覆盖查询
2. 任何断言字段（条件）、投影字段（返回）是位于嵌入文档中的字段时

针对分片集群的限制：当索引不包含分片键的时候，它不能覆盖针对分片集合的查询。一个例外是，查询断言仅针对_id且投影仅仅返回_id，即使_id不是分片键，也可以做到覆盖查询。

使用

db.collection.explain()

集合上的每个索引，都增加了写入操作的成本。

对于插入/删除操作，MongoDB需要插入/删除集合上所有索引中的文档键。更新操作可能导致索引的一个子集的变更。

对于使用MMAPv1引擎的mongod，更新操作可能导致文档增长，超过为其分配的空间。这时MMAPv1需要把文档移动到一个新的地方，并更新索引索引，指向文档的新位置。这些成本较高，但是发生频率较低。

通常来说，索引带来的读性能提升，值得损耗写性能。尽管如此，不要盲目的创建索引，要评估既有索引是否真的有用。

更新操作可能会改变文档的尺寸，例如添加新的字段。

对于MMAPv1引擎来说，如果更新操作导致文档尺寸超过当前分配尺寸，MongoDB会在磁盘上重新分配文档，确保有足够的连续空间可以存放文档。需要重新分配空间的更新操作，其效率更加低，特别是结合使用索引的情况下，因为需要修改文档的位置信息。

默认的，从3.0开始MongoDB总是分配2的N次方大小的空间。这可以尽量减少重新分配、高效的重用删除操作回收的空间，但是不能消除重新分配。

存储系统的硬件因子——随机存取能力、磁盘预读取、RAID等——对MongoDB写操作的性能影响很大。对于随机性的工作负载，SSD能够提供比HDD高100倍的性能。

为了防止意外宕机导致数据丢失，MongoDB使用预写式日志（write ahead logging）—— 变更首先发生在内存中，然后首先写入到日志。不直接写入存储引擎是因为日志文件是顺序写，速度快。如果MongoDB需要终止服务进程或者遭遇错误，可以使用日志文件恢复，把尚未完成的操作应用到存储引擎的数据文件中。

日志和数据文件的写入，存在对存储能力的争用，特别是二者保存在同一物理设备上时。

如果应用程序指定包含j选项的写关注，则mogod会减少日志写操作之间的间隔，从而增大总体的写负载。

日志写间隔可以通过运行时配置

commitIntervalMs

使用db.collection.explain()、cursor.explain()方法以及explain命令都可以获得执行计划相关的信息（包括执行统计信息）。

执行计划（上述方法或命令的结果）以阶段（stage）树的形式呈现。每个stage把自身的结果（例如文档或者索引键）传递给父节点。叶子节点访问文档或者索引，中间节点操控文档或者索引键，根节点是最终的stage，MongoDB从中获得结果集。

Stage是操作的描述，例如：

1. COLLSCAN 全集合扫描
2. IXSCAN 索引键扫描
3. FETCH  读取文档
4. SHARD_MERGE 合并来自分片的结果
5. AND_SORTED 可在索引交叉时出现
6. AND_HASH 可在索引交叉时出现

执行计划以JSON格式输出，重要的字段包括：

{
   "queryPlanner" : {
      "plannerVersion" : <int>,
      "namespace" : <string>,
      "indexFilterSet" : <boolean>,
      "parsedQuery" : {
         ...
      },
      "winningPlan" : {
         "stage" : <STAGE1>,
         ...
         "inputStage" : {
            "stage" : <STAGE2>,
            ...
            "inputStage" : {
               ...
            }
         }
      },
      "rejectedPlans" : [
         <candidate plan 1>,
         ...
      ]
  }
}

"executionStats" : {
   "executionSuccess" : <boolean>,
   "nReturned" : <int>,
   "executionTimeMillis" : <int>,
   "totalKeysExamined" : <int>,
   "totalDocsExamined" : <int>,
   "executionStages" : {
      "stage" : <STAGE1>
      "nReturned" : <int>,
      "executionTimeMillisEstimate" : <int>,
      "works" : <int>,
      "advanced" : <int>,
      "needTime" : <int>,
      "needYield" : <int>,
      "isEOF" : <boolean>,
      ...
      "inputStage" : {
         "stage" : <STAGE2>,
         ...
         "nReturned" : <int>,
         "executionTimeMillisEstimate" : <int>,
         "keysExamined" : <int>,
         "docsExamined" : <int>,
         ...
         "inputStage" : {
            ...
         }
      }
   },
   "allPlansExecution" : [
      { <partial executionStats1> },
      { <partial executionStats2> },
      ...
   ]
}

准备数据：

db.collection( 'inventory' ).insertMany(
    [
        { "_id": 1, "item": "f1", type: "food", quantity: 500 },
        { "_id": 2, "item": "f2", type: "food", quantity: 100 },
        { "_id": 3, "item": "p1", type: "paper", quantity: 200 },
        { "_id": 4, "item": "p2", type: "paper", quantity: 150 },
        { "_id": 5, "item": "f3", type: "food", quantity: 300 },
        { "_id": 6, "item": "t1", type: "toys", quantity: 500 },
        { "_id": 7, "item": "a1", type: "apparel", quantity: 250 },
        { "_id": 8, "item": "a2", type: "apparel", quantity: 400 },
        { "_id": 9, "item": "t2", type: "toys", quantity: 50 },
        { "_id": 10, "item": "f4", type: "food", quantity: 75 }
    ]
)

获取不使用索引时的执行计划： 

require( 'promise.prototype.finally' ).shim();
client.connect( 'mongodb://localhost:27017/local' ).then( db => {
    db.collection( 'inventory' ).find(
        { quantity: { $gte: 100, $lte: 200 } }
    ).explain( "executionStats" ).then( r => {
        console.log( r.queryPlanner.winningPlan.stage );    // COLLSCAN 表示全集合扫描
        console.log( r.executionStats.nReturned );          // 匹配并返回3条数据
        console.log( r.executionStats.totalDocsExamined );  // 总计检查10条（全部）数据
    } ).catch( e => console.log( e ) ).finally( () => process.exit() );
} );

创建一个索引：

db.collection( 'inventory' ).createIndex( { quantity: 1 } )

执行计划现在为：

console.log( r.queryPlanner.winningPlan.inputStage.stage );  // IXSCAN 表示索引扫描（在子Stage完成）
console.log( r.queryPlanner.winningPlan.stage );             // FETCH 直接抓取数据
console.log( r.executionStats.nReturned );                   // 匹配并返回3条数据
console.log( r.executionStats.totalDocsExamined );           // 总计检查3条数据

// 打印整个计划：
const util = require( 'util' );<br>console.log( util.inspect( r, { depth: null, colors: true } ) );
// 输出：
{ queryPlanner: 
   { plannerVersion: 1,
     namespace: 'local.inventory',
     indexFilterSet: false,
     parsedQuery: { '$and': [ { quantity: { '$lte': 200 } }, { quantity: { '$gte': 100 } } ] },
     winningPlan: 
      { stage: 'FETCH',
        inputStage: 
         { stage: 'IXSCAN',
           keyPattern: { quantity: 1 },
           indexName: 'quantity_1',
           isMultiKey: false,
           multiKeyPaths: { quantity: [] },
           isUnique: false,
           isSparse: false,
           isPartial: false,
           indexVersion: 2,
           direction: 'forward',
           indexBounds: { quantity: [ '[100, 200]' ] } } },
     rejectedPlans: [] },
  executionStats: 
   { executionSuccess: true,
     nReturned: 3,
     executionTimeMillis: 0,
     totalKeysExamined: 3,
     totalDocsExamined: 3,
     executionStages: 
      { stage: 'FETCH',
        nReturned: 3,
        executionTimeMillisEstimate: 0,
        works: 4,
        advanced: 3,
        needTime: 0,
        needYield: 0,
        saveState: 0,
        restoreState: 0,
        isEOF: 1,
        invalidates: 0,
        docsExamined: 3,
        alreadyHasObj: 0,
        inputStage: 
         { stage: 'IXSCAN',
           nReturned: 3,
           executionTimeMillisEstimate: 0,
           works: 4,
           advanced: 3,
           needTime: 0,
           needYield: 0,
           saveState: 0,
           restoreState: 0,
           isEOF: 1,
           invalidates: 0,
           keyPattern: { quantity: 1 },
           indexName: 'quantity_1',
           isMultiKey: false,
           multiKeyPaths: { quantity: [] },
           isUnique: false,
           isSparse: false,
           isPartial: false,
           indexVersion: 2,
           direction: 'forward',
           indexBounds: { quantity: [ '[100, 200]' ] },
           keysExamined: 3,
           seeks: 1,
           dupsTested: 0,
           dupsDropped: 0,
           seenInvalidated: 0 } },
     allPlansExecution: [] },
  serverInfo: 
   { host: '226ce0b60d62',
     port: 27017,
     version: '3.4.5',
     gitVersion: '520b8f3092c48d934f0cd78ab5f40fe594f96863' },
  ok: 1 
}

本节介绍几种评估MongoDB操作性能的技术。

MongoDB提供了一个数据库剖析器（database profiler ），它能够显示数据库中每个查询的性能特征。使用该剖析器可以定位运行缓慢的读写操作。

该调用可以显示当前mongod实例上正在执行的操作的各项参数。调用方式：

db.currentOp({filterDocument})
// 示例
db.currentOp( { query: { $exists: true } , ns: 'bais.corps' } ).inprog

可以传递一个过滤文档作为参数，该文档可以包含以下字段：

1. $ownOps，如果设置为true，仅仅显示当前用户的操作
2. $all，如果设置为true，返回所有操作的信息，包括那些空闲连接上的操作、系统操作
3. 任何输出字段都可以作为过滤条件使用 

在单个mongod实例、复制集上，该调用的输出格式为：

{
    "inprog" : [/* 正在执行的操作列表 */], 
    "ok" : 1.0
}

在分片集群的mongos上，该调用的输出格式为：

{ 
    // 每个分片的情况
    "raw" : {
        // 分片名称为键
        "rs1/mongo-11.gmem.cc:27017,mongo-12.gmem.cc:27017,mongo-13.gmem.cc:27017" : {
            "inprog" : [/* 正在执行的操作列表 */], 
            "ok" : 1.0, 
            "$gleStats" : {
                "lastOpTime" : Timestamp(0, 0), 
                "electionId" : ObjectId("7fffffff000000000000000e")
            }
        }
    }, 
    // 当前mongos上的情况
    "inprog" : [/* 正在执行的操作列表 */], 
    "ok" : 1.0
}

上述输出的核心是inprog属性，它包括以下字段：

"client" : "172.21.1.1:44938" 

db.killOp()

<database>.<collection>

这是一个命令行工具，查看读写最繁忙的集合。该命令不能在mongos上执行。示例：

mongotop -u root -p root --authenticationDatabase admin

#                   ns    total    read    write    2017-08-25T15:33:53+08:00
#       local.oplog.rs      1ms     1ms      0ms                             
#   admin.system.roles      0ms     0ms      0ms                             
#   admin.system.users      0ms     0ms      0ms                             
# admin.system.version      0ms     0ms      0ms                             
#           bais.corps      0ms     0ms      0ms                             
#       bais.corptypes      0ms     0ms      0ms                             
#            bais.orgs      0ms     0ms      0ms                             
#  bais.system.indexes      0ms     0ms      0ms                             
#          bais.trades      0ms     0ms      0ms                             
#             local.me      0ms     0ms      0ms

这是一个命令行工具，可以快速的查看当前mongos/mongod的概览信息，类似于vmstat：

mongostat -u root -p root --authenticationDatabase admin
# insert query update delete getmore command flushes mapped vsize   res faults qrw arw net_in net_out conn                time
#    *0    *0     *0     *0       0     2|0       0     0B  300M 19.0M      0 0|0 0|0   288b   16.8k    8 Aug 25 15:15:14.827

该命令的输出，反映每秒的平均统计指标。字段列表：

方法

cursor.explain()

db.collection.explain()

你可以在queryPlanner、executionStats 、allPlansExecution三种模式下运行这些方法，获取多或少的信息。

聚合操作处理数据记录，并返回计算过后的结果。这类操作将多个文档中的数值进行分组，通过多种数学计算将其合并为单个数值。

MongoDB提供三种聚合操作途径：聚合管线（aggregation pipeline）、Map-Reduce函数（map-reduce function）、单意图聚合方法（single purpose aggregation methods） 。

MongoDB的聚合框架，以数据处理管线的概念进行建模 —— 多个文档进入由多个阶段（stage）构成的管道，并被管道转换为单个聚合后的结果。每个阶段都会对文档进行某种转换。每个阶段的输入、输出文档没有一一对应关系，一个文档可以产生多个新文档，多个文档也可能被合并为单个文档。

最基本管线stage，提供过滤器功能，工作方式类似于查询和文档转换，修改输出文档的形式。

其它管线stage，提供依据指定字段来分组、排序文档的工具，以及聚合数组（包括文档的数据）内容的工具。此外，管线stage可以使用操作符来计算平均值、连接字符串…等操作。

通过MongoDB内置的native操作，管线可以提供高效的数据聚合能力。管线是最优选的聚合途径。

聚合管线可以支持分片集合。

在某些stage，聚合管线会利用索引来改善性能。聚合管线声明周期中，具有内部的优化阶段。

要使用聚合管线，可以调用

db.collection.aggregate( arrayOfStages )

aggregate

某些stage需要一个管线表达式来作为操作数，管线表达式说明如何来转换输入文档。表达式的格式类似于文档，并且可以包含其它表达式。

管线表达式仅可以操作管线中的当前文档，无法引用其它文档中的数据。通常来说，表达式都是无状态的，例外是那些累加器表达式。累加器用在

$group

从3.2开始，某些累加器可以用在

$project

聚合管线操控单个集合，在逻辑上，是把整个集合推到管线上进行处理。为了优化性能，仅可能的使用以下策略避免全集合扫描：

1. 管线操作符和索引：当出现在管线的开头时，$match、$sort等管线操作可以使用索引。$geoNear 可以使用地理空间索引。从3.2开始，索引可以覆盖聚合管线，而避免扫描集合
2. 尽早的过滤：如果聚合操作仅仅需要集合的一个子集，可以使用$match、$limit、$skip等stage来限制进入管线开头的文档数量
3. 内部优化阶段（optimization phase）

聚合管线内部有一个优化阶段，会尝试对管线进行塑形，以改善性能。要了解此优化阶段是如何工作的，以explain选项来调用aggregate()方法。随着MongoDB的版本发布，管线优化的实现可能会变化。

聚合管线支持针对分片集合进行操作，但是具有一些特殊的行为。

如果管线以精确匹配针对某个分片键的$match开头，则整个管线在匹配的分片上运行。在3.2之前的行为是，管线分拆在所有管线上运行，并且由主分片负责合并最后结果。

对于必须运行在多个分片上的聚合操作，如果不是必须在主分片上运行，这些操作会把结果路由到随机的分片上，由该分片负责合并结果，避免增加主分片的负担。$out、$lookup操作必须在主分片上运行。

db.collection.aggregate()方法的参数是一个数组，每个数组元素表示一个阶段（Stage）。阶段是单键对象，键的名称以$开头，列于下面的表格中。

除了

$out

$geoNear

{
  $collStats:
    {
      // 在输出文档中添加延迟统计信息，histogram:true表示添加延迟直方图信息
      latencyStats: { histograms: <boolean> },
      // 在输出文档中添加存储统计信息
      storageStats: {}
    }
}

{ $project: { <specification(s)> } }

<field>: <1 or true>

_id: <0 or false>

<field>: <expression>

<field>:<0 or false>

{ $match: { <query> } }

{ $redact: <expression> }

{ $limit: <positive integer> }

{ $skip: <positive integer> }

# 1表示升序，-1表示降序。前面的字段优先排序
{ $sort: { <field1>: <sort order>, <field2>: <sort order> ... } }

{
    $geoNear: {
        spherical: 'boolean = false，使用2dsphere索引时应设为true，决定如何计算距离',
        limit: 'number = 100，返回的最大文档数',
        num: '功能和limit相同，优先级高',
        maxDistance: 'number，可返回文档距离中心点的最远多少',
        query: 'document，对输入文档进行过滤',
        distanceMultiplier: 'number，对查询结果的距离字段进行倍乘',
        near: '中心点，使用2dsphere索引时类型为GeoJSON点或者坐标对，使用2d索引时类型为坐标对',
        distanceField: 'string，输出文档字段，该字段包含计算出的距离，可以使用点号来指定为嵌入文档字段',
        minDistance: 'number，可返回文档距离中心点的最近多少',
        includeLocs:'string，可选，存放用来计算距离的那个点的坐标的输出文档字段'
    }

}

db.places.aggregate([
   {
     $geoNear: {
        near: { type: "Point", coordinates: [ -73.99279 , 40.719296 ] },
        // 距离字段
        distanceField: "dist.calculated",
        maxDistance: 2,
        query: { type: "public" },
        // 存放用来计算到中心点距离的输入值的字段
        includeLocs: "dist.location", 
        num: 5,
        spherical: true
     }
   }
])

// 输出文档示例：
{
   "_id" : 8,
   "name" : "Sara D. Roosevelt Park",
   "type" : "public",
   "location" : {
      "type" : "Point",
      "coordinates" : [ -73.9928, 40.7193 ]
   },
   "dist" : {
      "calculated" : 0.9539931676365992,
      "location" : {
         "type" : "Point",
         "coordinates" : [ -73.9928, 40.7193 ]
      }
   }
}

{
   $lookup:
     {
       from: '被左外连接的集合',
       localField: '输入文档中用于匹配（等于）的字段',
       foreignField: '被连接集合中用于匹配的字段',
       as: '被连接文档在输出中对应的字段名'
     }
}

// 订单左外连接库存
db.orders.aggregate([
    {
      $lookup:
        {
          from: "inventory",
          localField: "item",
          foreignField: "sku",
          as: "inventory_docs"
        }
   }
])
// 输出文档示例
{
  "_id" : 1,
   "item" : "abc",
  "price" : 12,
  "quantity" : 2,
  // 匹配的被连接文档，数组形式
  "inventory_docs" : [
    { "_id" : 1, "sku" : "abc", description: "product 1", "instock" : 120 }
  ]
}

{ $out: "<output-collection>" }

{
  $bucket: {
      // 分组的依据，针对每个输入文档进行评估
      groupBy: <expression>,
      // 桶的划分边界，[)区间，3个值确定2个区间，起始值作为桶的_id
      boundaries: [ <lowerbound1>, <lowerbound2>, ... ],
      // 如果groupBy的值没有落到boundaries声明的任何区间，则归入此_id为此值的桶
      default: <literal>,
      // 每个桶的输出字段列表，_id不需要指定
      output: {
         <output1>: { <$accumulator expression> },
         ...
         <outputN>: { <$accumulator expression> }
      }
   }
}

// 油画拍卖的例子
{ "_id" : 1, "title" : "社会的支柱", "artist" : "格罗斯", "year" : 1926,"price" : 199 }
// 聚合管线
db.artwork.aggregate( [
  {
    $bucket: {
      // 根据价格区间分组
      groupBy: "$price",
      boundaries: [ 0, 200, 400 ],
      default: "Other",
      output: {
        // 输出油画总数
        "count": { $sum: 1 },
        // 油画名称的数组
        "titles" : { $push: "$title" }
      }
    }
  }
] )
// 输出
{
  "_id" : 0,
  "count" : 1,
  "titles" : [
    "The Pillars of Society"
  ]
} 

{
  $bucketAuto: {
      groupBy: <expression>,
      // 期望的分组的数量
      buckets: <number>,
      output: {
         <output1>: { <$accumulator expression> },
         ...
      }
      granularity: <string>
  }
} 

{ $sortByCount:  <expression> }
// 等价于以下两个Stage的组合：
{ $group: { _id: <expression>, count: { $sum: 1 } } },
{ $sort: { count: -1 } }

{ $addFields: { <newField>: <expression>, ... } } 

{ $count: <field_name> }

{
   $graphLookup: {
      // 被搜索的集合的名称
      from: <collection>,
      // 指定connectFromField的初始值
      startWith: <expression>,
      // 指定起始文档中用于匹配的字段名
      connectFromField: <string>,
      // 指定与起始文档进行匹配的，目标文档的字段名
      connectToField: <string>,
      // 保存被匹配文档链条的字段名
      as: <string>,
      // 递归匹配的最大深度
      maxDepth: <number>,
      // 添加到匹配文档链条中每个元素的“深度”字段的名字
      depthField: <string>,
      // 查询文档，为匹配指定额外的条件
      restrictSearchWithMatch: <document>
   }
}

// 示例：
{ "_id" : 1, "name" : "Dev" }
{ "_id" : 2, "name" : "Eliot", "reportsTo" : "Dev" }
{ "_id" : 3, "name" : "Ron", "reportsTo" : "Eliot" }
// 聚合管线：
db.employees.aggregate( [
   {
      $graphLookup: {
         from: "employees",
         startWith: "$reportsTo",
         connectFromField: "reportsTo",
         connectToField: "name",
         as: "reportingHierarchy"
      }
   }
] )
// 输出
{
   "_id" : 1,
   "name" : "Dev",
   "reportingHierarchy" : [ ]
}
{
   "_id" : 2,
   "name" : "Eliot",
   "reportsTo" : "Dev",
   "reportingHierarchy" : [
      { "_id" : 1, "name" : "Dev" }
   ]
}
{
   "_id" : 3,
   "name" : "Ron",
   "reportsTo" : "Eliot",
   "reportingHierarchy" : [
      { "_id" : 1, "name" : "Dev" },
      { "_id" : 2, "name" : "Eliot", "reportsTo" : "Dev" }
   ]
}

使用聚合管线时，很多的值可以使用表达式。表达式包括：

表达式类型	说明
字段路径	用于读取输入文档中的字段，包括内嵌文档字段，以前缀 $ 开始，例如$user、$user.name
系统变量	一些预置的特殊对象，以前缀 $$ 开始。例如 $$CURRENT 通常表示当前正在被处理的输入文档，因此$$CURRENT.<field>通常等价于$<field>
字面值	可以使用 { $literal: <value> } 形式指定，例如： { $literal: { $add: [ 2, 3 ] } } // { "$add" : [ 2, 3 ] } { $literal: { $literal: 1 } } // { "$literal" : 1 }
操作符表达式	类似于接受参数的函数： // 接受多参数的操作符 { <operator>: [ <argument1>, <argument2> ... ] } // 接受单参数的操作符 { <operator>: <argument> }  MongoDB提供了很多聚合管线专用操作符，对应了各类操作符表达式，主要包括： 布尔表达式：$and、$or、$not 集合表达式：对数组进行集合操作，把数组当作集合处理——忽略重复元素 比较表达式：进行比较操作，除了$cmp之外均返回boolean 算术表达式：进行算术操作，某些操作符支持日期 字符串表达式：进行字符串查找、子串提取、分割等操作 文本搜索表达式 数组表达式：处理数组 变量表达式： $let ，定义在子表达式范围内可见的变量，并返回子表达式的值 日期表达式：处理日期和时间
累加器表达式	聚合管线专用操作符中有一类特殊的累加器操作符，只能用于$group阶段，从3.2开始，部分可用在$project阶段（stage）。主要包括：$sum、$avg、$first、$last、$max、$min、$push、$addToSet等

// 每条数据的结构
{
    "_id": "10280",        // 邮编
    "city": "NEW YORK",    // 市
    "state": "NY",         // 州
    "pop": 5574,           // 人口
    "loc": [               // 经纬
        -74.016323,
        40.710537
    ]
}
// 人口大于1000万的州
db.zipcodes.aggregate( [
    // 输出文档的_id作为分组的依据
    // 该stage决定的输出文档的结构，使用$xxx可以引用输入文档的字段
    // totalPop字段通过$sum操作符（聚合表达式）计算出
    { $group: { _id: "$state", totalPop: { $sum: "$pop" } } },
    // 该stage针对上一stage的结果进行匹配
    { $match: { totalPop: { $gte: 10 * 1000 * 1000 } } }
] );

// 返回每州的平均城市人口
db.zipcodes.aggregate( [
    // 支持依多字段分组。先获得 州 - 市 - 人口总和
    { $group: { _id: { state: "$state", city: "$city" }, pop: { $sum: "$pop" } } },
    // 再次分组，州总人口除以城市数量。注意点号导航
    { $group: { _id: "$_id.state", avgCityPop: { $avg: "$pop" } } }
] );

// 返回每个州里面最大和最小的城市
db.zipcodes.aggregate( [
    {
        // 按照州、市进行分组，统计人口总数
        $group: {
            _id: { state: "$state", city: "$city" },
            pop: { $sum: "$pop" }
        }
    },
    // 根据人口升序排列
    { $sort: { pop: 1 } },
    // 第二次分组，$last、$first分别取最后、最前的组内文档中的值
    {
        $group: {
            _id: "$_id.state",
            biggestCity: { $last: "$_id.city" },
            biggestPop: { $last: "$pop" },
            smallestCity: { $first: "$_id.city" },
            smallestPop: { $first: "$pop" }
        }
    },
    // 投影stage，重命名_id字段为state字段
    // 把城市名称、人口合并为文档
    // 注意投影是针对输入文档每个条目执行的
    {
        $project: {
            _id: 0,  // 设置为0表示明确的在输出文档中禁用该字段
            state: "$_id",
            biggestCity: { name: "$biggestCity", pop: "$biggestPop" },
            smallestCity: { name: "$smallestCity", pop: "$smallestPop" }
        }
    }
] );

20// 每条数据的结构
{
    _id : "jane",
    joined : ISODate("2011-03-02"),
    likes : ["golf", "racquetball"]
}
{
    _id : "joe",
    joined : ISODate("2012-07-02"),
    likes : ["tennis", "golf", "swimming"]
}

// 规范化数据结构，_id转换为大写，命名为name，然后根据name升序排列
db.users.aggregate(
    [
        { $project: { name: { $toUpper: "$_id" }, _id: 0 } },
        { $sort: { name: 1 } }
    ]
);


// 根据加入的月份升序排列
db.users.aggregate(
    [
        {
            $project: {
                // 取得月份
                month_joined: { $month: "$joined" },
                name: "$_id",
                _id: 0 // 明确禁用_id字段，该字段是默认包含的
            }
        },
        { $sort: { month_joined: 1 } }
    ]
);
// 获得每月加入的总数，根据月份升序排列
db.users.aggregate(
    [
        { $project: { month_joined: { $month: "$joined" } } },
        { $group: { _id: { month_joined: "$month_joined" }, number: { $sum: 1 } } },
        { $sort: { "_id.month_joined": 1 } }
    ]
);
// 获得五个最被喜爱的体育运动
db.users.aggregate(
    [
        // 展开likes数组，意味着对于likes.lengt = 5的输入文档，将展开为5个输出文档
        { $unwind: "$likes" },
        // 根据喜爱的单项体育运动分组，统计总数（每个人只能喜爱一次，因此sum:1）
        { $group: { _id: "$likes", number: { $sum: 1 } } },
        // 逆序排列
        { $sort: { number: -1 } },
        // 取前五条
        { $limit: 5 }
    ]
);

Map-reduce是一种数据处理范式，用于浓缩海量的数据为有意义的聚合数据。

MongoDB支持map-reduce风格的聚合操作。总体上说，map-reduce操作由以下阶段组成：

1. map阶段，处理多个文档，并针对每个输入文档产生一个或者多个键值对。此阶段由map函数中的emit语句完成
2. reduce阶段，处理map阶段的输出，把这些输出合并起来。对于具有相同键的所有值，应用reduce函数，聚合（累积）为一个值
3. 可选的finalize阶段，对结果进行最终的修改

类似于其它聚合操作，map-reduce也允许指定查询条件、排序方式、限制输入文档数量。

你需要自定义JavaScript函数来提供map、reduce、finalize逻辑。和聚合管线比起来，JavaScript函数可以提供巨大的灵活性，但是更加低效和复杂。

在Shell中，你可以调用

mapReduce

db.collection.mapReduce()

db.collection.mapReduce(
    // map函数关联一个value到key，在map阶段之后产生若干key:[values]形式的键值对，作为reduce阶段的输入
    // map函数要求：
    // 1、使用this引用当前文档
    // 2、不得出于任何目的访问数据库
    // 3、必须是纯函数，不得有任何副作用
    // 4、单个emit调用可产生半数于BSON最大文档尺寸的键值对
    // 5、可以调用多次emit(key,value)以产生键值对
    <map>,
    // reduce整个[values]为单个对象，可以作为finalize阶段的输入
    // reduce函数要求：
    // 1、不得出于任何目的访问数据库
    // 2、不得影响外部系统
    // 3、对于只包含一个值的key，MongoDB不会调用reduce函数
    // 4、可以访问定义在scope中的全局变量
    // 5、由于针对同一key，reduce函数可能被调用多次，因此reduce函数的返回值的类型必须和map函数emit的value类型一致
    // 6、以下表达式必须成立：
    //    associative    reduce(key, [ C, reduce(key, [ A, B ]) ] ) == reduce( key, [ C, A, B ] )
    //    idempotent     reduce(key, [ reduce(key, valuesArray) ] ) == reduce( key, valuesArray )
    //    commutative    reduce( key, [ A, B ] ) == reduce( key, [ B, A ] )
    <reduce>,
    // 选项：
    {
        // 指定mapReduce结果的输出目的地，你可以指定
        // 1、一个集合的名字
        // 2、action:collection_name，输出到集合前应用指定的action
        // 3、inline，针对主节点进行mapReduce时可以输出到集合，针对从节点则只能inline
        out: {
            // action取值：
            // replace 如果collectionName存在，则替换其内容
            // merge  合并当前结果到collectionName，如果存在相同的key则覆盖之
            // reduce reduce当前结果到collectionName，对于相同的key（_id），使用此mapReduce的reduce函数进行reduce
            // collectoinName中文档的原型：{ "_id" : key, "value" : reducedValue }
            <action>: <collectionName>,
            // 在内存中完成mapReduce操作，并返回结果，指定此字段，则不能指定任何其它out字段
            inline : 1                    //
            [, db: <dbName>]              // 可以选择其它数据库
            [, sharded: <boolean> ]       // 设置为true则对输出集合启用分片，使用_id（即map的key）字段对输出集合进行分片
            [, nonAtomic: <boolean> ]     // 如果设置为true，则mapReduce的后处理阶段不会全局锁
        },
        // 用于过滤输入文档
        query: <document>,
        // 用于排序输入文档，可以优化性能。如果sort和emit的键一致，则可以减少reduce操作的次数。必须是集合的某个索引字段
        sort: <document>,
        // 限制进入map阶段的最大文档数量
        limit: <number>,
        // 早reduce完成之后，对最终结果进行修改，例如求平均
        finalize: <function>,
        // 定义map、reduce、finalize函数中可以访问的全局变量
        scope: <document>,
        jsMode: <boolean>,
        // 如果为true，则在result信息中包含耗时统计信息
        verbose: <boolean>
    }
)

map-reduce支持将分片集合作为输入，并且其结果可以输出到分片集合上。

当作为输入时，MongoDB会自动把map-reduce任务派发到各分片上来并行执行，并等到所有分片上的任务全部完成。

当作为输出时，如果mapReduce的out字段具有sharded值，则MongoDB自动以_id为分片键，输出到分片集合中。

Map-reduce操作由一系列的任务组成，这些任务的职责包括：从输入集合读取数据、执行map函数、执行reduce函数、在处理过程中输出到临时集合、写入到输出集合等。

在处理过程中，Map-reduce持有以下锁：

1. 在读阶段，持有读锁，每次锁100个文档
2. 写入临时集合时，持有写锁，每次写操作持有一次
3. 如果输出集合不存在，创建输出集合时持有写锁
4. 如果输出集合存在，则输出操作（merge、replace、reduce等）持有写锁。此写锁是全局的，会阻塞mongod实例上所有其它操作

考虑一个订单集合，其文档原型如下：

{
    cust_id: "1000",   // 客户号
    ord_date: new Date( "2015-01-05" ),  // 订单日期
    status: 'A',
    price: 25,  // 订单金额
    // 订单详情
    items: [ { sku: "mmm", qty: 5, price: 3 }, { sku: "nnn", qty: 5, price: 2 } ] 
}

下面的map-reduce操作，可以获得每个客户的订单总额：

db.collection( 'order' ).mapReduce(
    // 注意map函数必须是纯函数
    function () {
        // this为当前正在处理的文档
        // 调用emit可以生成输出文档
        emit( this.cust_id, this.price );
    },
    // 按照客户ID分组，所有价格构成数组。这样一个键值对送给reduce函数处理
    function ( keyCustId, valuesPrices ) {
        return Array.sum( valuesPrices );
    },
    // 选项，指定结果的输出集合
    { out: "order_prices" }
)

如果需要被处理的数据集持续增长，你可能需要进行增量mapReduce，而不是每次都针对完整数据集进行mapReduce。

要进行增量mapReduce，你需要：

1. 针对当前集合执行mapReduce，把结果存放到另外一个集合中
2. 当更多的数据入库时，执行后续的mapReduce操作。使用query参数来过滤，仅仅匹配新的文档
3. 使用finalize处理reduce之后的数据，例如求平均值

统计用户会话时长信息的例子：

文档原型：

// ts为登录时间戳，是增量mapReduce的关键
{ userid: "a", ts: ISODate('2011-11-03 14:17:00'), length: 95 }

增量mapReduce：

db.collection( 'sessions' ).mapReduce(
    // map，注意平均时间仅仅是占位符
    function () {
        var key = this.userid;
        var value = {
            userid: this.userid,
            total_time: this.length,
            count: 1,
            avg_time: 0
        };
        emit( key, value );
    },
    // reduce，总计在线时间、登录次数累加，平均登录时间再此无法计算
    function ( key, values ) {

        var reducedObject = {
            userid: key,
            total_time: 0,
            count: 0,
            avg_time: 0
        };

        values.forEach( function ( value ) {
                reducedObject.total_time += value.total_time;
                reducedObject.count += value.count;
            }
        );
        return reducedObject;
    },
    {
        // 增量：仅仅处理新增数据
        query: { ts: { $gt: ISODate( '2011-01-01 00:00:00' ) } },
        // reduce到统计集合，此集合必须最初的全量mapReduce初始化
        out: { reduce: "session_stat" },
        // 本次增量数据reduce到统计集合之后，才能计算平均时间
        finalize: function ( key, reducedValue ) {
            if ( reducedValue.count > 0 )
                reducedValue.avg_time = reducedValue.total_time / reducedValue.count;
            return reducedValue;
        }
    }
) 

db.collection.count()

db.collection.distinct()

MongoDB支持对字符串内容进行检索查询。为了使用这种文本搜索功能，你需要使用文本索引（text index）以及

$text

全文检索不是MongoDB的核心功能，如果有复杂的搜索需求，建议配合使用全文搜索引擎，例如Solr。

MongoDB的全文搜索会忽略一些语言相关的单词，例如英语中的there、and、the等单词，这些词作为搜索关键字，没有意义。

如果某个文档包含单词blueberry，则你搜索blue不会有结果，但是搜索blueberries则匹配。即全文搜索支持复数形式的识别。

这类索引用于支持对字符串内容的检索。文本索引可以包含任何类型为字符串、字符串数组的字段。要支持文本搜索，你必须首先为集合创建文本索引：

db.stores.insert(
    [
        { _id: 1, name: "Java Hut", description: "Coffee and cakes" }
    ]
)
# 创建文本索引，该索引将针对name、description两个字段
db.stores.createIndex( { name: "text", description: "text" } )

# 删除文本索引，需要先查询到索引的名字
db.collection.getIndexes()
# 传入名字以删除
db.trades.dropIndex("name_text")

注意：每个集合只能拥有一个文本索引，但是该索引可以覆盖多个字段。

使用该操作符，可以对启用了文本索引的集合进行文本搜索：

// 返回包含 java、coffee shop两个词语的文档
db.stores.find( { $text: { $search: "java \"coffee shop\"" } } )
// 返回包含java、shop，但是不包含coffee的文档
db.stores.find( { $text: { $search: "java shop -coffee" } } )

$search用于指定关键字，多个关键字使用空格分隔，如果某个关键字内部包含空格，必须以双引号包围整个关键字。MongoDB对所有关键字进行逻辑或操作。 

文本搜索的结果默认是无序的。文本搜索会为每个匹配的文档计算一个相关性分数（relevance score），你可以访问该分数用来排序：

db.stores.find(
   { $text: { $search: "java coffee shop" } },
   // 把相关性分数投影为score字段
   { score: { $meta: "textScore" } }
).sort( { score: { $meta: "textScore" } } )

在聚合框架中使用文本搜索时，你需要在$match阶段使用$text操作符。类似的，要进行排序，你需要在$sort阶段使用$meta投影操作符。

在聚合管线中使用文本搜索，受到以下限制：

1. 包含$text操作符的$match必须是管线的第一个Stage
2. $text操作符仅能够在管线中出现一次
3. $text操作符不可出现在$and或者$or内部
4. 默认搜索结构没有按照相关性排序，请使用$sort 阶段实现

文本搜索支持多种语言，从3.2开始，MongoDB Enterprise可以支持中文全文检索。

为了支持中文和阿拉伯文等语言，MongoDB Enterprise集成了RLP（ Basis Technology Rosette Linguistics Platform ），来完成正规化、分词、分句、词干提取（stemming）、符号化等全文检索领域的职责。

在MongoDB中，你可以GeoJSON对象的形式或者遗留的坐标对形式，来存储地理空间数据。

要沿着类似于地球的球面，进行几何计算，你应当使用GeoJSON来存储位置数据。即使用这样的内嵌文档：

1. 包含一个名为type的字段，指定此GeoJSON对象的类型，例如Point、LineString、Polygon等
2. 包含一个名为coordinates的字段，指定构成此GeoJSON对象的所有坐标值。如果指定经纬度坐标，则经度在前、纬度在后

GeoJSON对象示例：

// 格式：
<field>: { type: <GeoJSON type> , coordinates: <coordinates> }
// 点：
location: {
    type: "Point",
    coordinates: [-73.856077, 40.848447]
}
// 线
scope: {
    type: "LineString", 
    coordinates: [ [ 40, 5 ], [ 41, 6 ] ]
}

针对GeoJSON类型字段上的查询，计算行为是在球面上进行的，使用WGS84坐标参考系统。 

要在欧几里得平面上计算距离，在坐标对中存储位置信息同时使用2d索引。

通过 2dsphere索引并且把坐标对转换为GeoJSON对象，MongoDB支持遗留坐标对的球面计算。

坐标对的示例：

// 数组形式，推荐
<field>: [ <x>, <y> ]
<field>: [<longitude>, <latitude> ]

// 内嵌文档形式
<field>: { <field1>: <x>, <field2>: <y> }

这种索引用于支持在类似于地球的球面上执行几何计算。创建这类索引的方法为：

// location field必须为GeoJSON或者坐标对字段
db.collection.createIndex( { <location field> : "2dsphere" } )

这种索引用于支持在二维平面上进行的几何运算。尽管这种索引可以支持 $nearSphere以实现球面几何运算，最好还是使用2dsphere索引。创建这类索引的方法为：

db.collection.createIndex( { <location field> : "2d" } )

地理空间索引不能作为分片键使用，但是分片集合的普通字段上可以存在地理空间索引。

对于分片集合，$near、$nearSphere等查询操作符不被支持，你可以考虑使用$geoNear聚合管线。

地理空间索引不能够覆盖任何查询。

相关的查询操作符包括：$geoWithin、$geoIntersects、$near、$nearSphere。

相关的查询命令为：geoNear。

相关的聚合管线Stage为：$geoNear。 

关系型数据库具有严格的Schema —— 例如表结构定义，但是MongoDB则允许你使用非常灵活的Schema，集合中文档的结构不被限制。这种灵活性可以让文档很方便的对应到一个复杂的实体。

实践中，一个集合中的文档的结构都是相似的。

对实体进行建模的关键挑战是在应用程序需求、数据库引擎的性能特征、数据检索图式之间寻求平衡。 

为MongoDB设计数据模型的关键决策是，如何表示数据之间的关系。关系的表达有两种风格：引用、内嵌文档。

规范化数据模型：使用一个字段来引用目标对象的_id，来建立两者的关系。

以下情况下，考虑使用引用：

1. 当内嵌文档会导致数据冗余，但是却不能提供足够高效的读性能时（相对其数据冗余的代价）
2. 表示复杂的M2M关系时
3. 对大型的层次化结构进行建模时

引用的缺点是，客户端可能需要发起更多的查询请求。

非规范化数据模型：把目标对象的全部/部分数据以内嵌文档的形式，直接存放在当前对象中。这样，访问关联对象的时候不需要发出额外的查询。

以下情况下，考虑使用内嵌文档：

1. 两个实体之间是合成关系
2. O2M关系中，M总是通过O来访问时

需要注意，内嵌文档/数组在MMAPv1引擎下，可能导致文档增长而产生磁盘数据块移动、碎片化，影响性能。

从3.0开始MongoDB使用2^N尺寸的空间分配，以最小化数据碎片化的可能性。

多个方面的因素影响你如何建模。

某些update操作会导致即有文档尺寸增长，例如添加数组元素、增加字段。

使用MMAPv1引擎时，文档增长是影响建模的考虑因素。因为文档尺寸超过预分配的大小时，引擎会重新在磁盘上分配空间，则意味着数据移动和可能的碎片化。

如果需要进行频繁的改变文档大小的update操作，考虑使用引用而非内嵌文档。你也可以使用预分配（pre-allocation）策略来避免文档增长。

从3.0开始的2^N尺寸分配可以减少重新分配空间的几率，并有效的重用因为移动文档而释放的空间。

在MongoDB中，针对单个文档的写操作是原子的。因此内嵌文档风格可以用来保证原子性需求。

如果以读操作为主，考虑增加索引。索引可以提升查询性能，MongoDB自动为_id创建唯一索引。注意索引的以下行为：

1. 每个索引至少要求8KB的空间
2. 索引对写操作有一定的负面影响。对于写读比很高的集合，索引的代价相对较高
3. 每一个活动的索引都消耗磁盘、内存空间。

通常情况下，使用大量的集合对性能没有太大影响，但是可能改善性能。创建大量集合时，要注意：

1. 每个集合需要至少占用若干KB的空间
2. 每个集合至少有一个索引，因此需要占用至少8KB空间
3. 对于每个数据库，一个名字空间文件<database>.ns存储了数据库的所有元数据。这些元数据包含每个集合及其索引的信息
4. MMAPv1限制了名字空间的数量，可以

   db.system.namespaces.count()

   查询

如果某个集合中存放了大量的小文档（例如GPS轨迹记录），你可能需要考虑使用内嵌文档或数组，以改善性能。小文档本身表示了独立实体时例外。

如果小文档仅仅包含几个字节，需要考虑存储空间的优化：

1. 明确指定_id字段。如果不指定，MongoDB默认生成12字节的ObjectId，可能太长了
2. 使用简短的字段名，MongoDB会把字段名附带在每一个文档中

集合可以具有TTL特性，让文档在一定时间后自动过期而被删除。

如果应用程序仅仅需要使用最近插入的文档，考虑定长集合。

索引用于提升查询性能，没有索引，MongoDB查询必须进行全集合扫描，性能低下。

索引是一种特殊的数据结构，它有序的保存了集合的一小部分信息。索引存储的是特定字段、字段集的值，以值的大小顺序存储 —— 因而能够支持高效的相等性查找、范围查找。 从算法上讲，MongoDB和RDBMS的索引类似。

索引可以在后台构建，这样可以避免影响运行中的应用程序。

要创建索引，可以调用：

db.collection.createIndex( <key and index type specification>, <options> )

在集合最初被创建时，MongoDB在_id字段上创建唯一性索引。

使用分片集合时，如果_id不作为分片键，则应用程序负责确保在集群范围内_id的唯一性。

顾名思义，就是针对单个字段创建的索引。

针对直接字段创建索引的示例：

// 升序索引
db.records.createIndex( { score: 1 } )
// 降序索引
db.records.createIndex( { score: -1 } )

对于单字段索引，升序/降序并不重要，因为MongoDB可以两端访问索引。

类似的，还可以在内嵌文档字段上创建索引：

// 使用点号导航
db.records.createIndex( { "location.state": 1 } )

MongoDB支持复合索引，即持有多个字段引用的单个索引。复合索引最多引用31个字段。要创建复合索引，调用：

// type取值1或者-1
db.collection.createIndex( { <field1>: <type>, <field2>: <type2>, ... } )

注意：

1. 已经创建了哈希索引的字段不能包含在复合索引中
2. 字段的顺序非常重要，第一个字段最优先排序，该字段值相同的记录，按照第二字段排序。注意索引按此排序存储在磁盘上
3. 复合索引支持针对索引前缀（Prefix）的查询，例如字段一、字段二或者字段一。如果查询条件不包含第一个字段，则索引肯定无法使用

复合索引中，字段的索引类型（升降）决定了索引能否支持排序操作。例如：

db.events.createIndex( { "username" : 1, "date" : -1 } )
// 上述索引可以支持下面两种排序操作
db.events.find().sort( { username: 1, date: -1 } )  // 正序访问索引，读出的就是排序好的
db.events.find().sort( { username: -1, date: 1 } )  // 逆序访问索引，读出的就是排序好的
// 而不能支持下面的排序操作
db.events.find().sort( { username: 1, date: 1 } )   // 无论以什么方向读取索引，都需要额外的处理才能获得正确的顺序

为了能够索引数组字段，MongoDB需要为每个数组元素创建索引键。这种多键（每元素）索引可以很好的支持针对数组字段的查询。

创建多键索引不需要特殊的API，MongoDB会自动发现目标字段是数组，进而自动创建多键索引。

从3.2开始，MongoDB引入了第3版的全文索引，关键特性包括：

1. 改善大小写不敏感性
2. 支持音调不敏感
3. 额外的分界符

要创建全文索引，以text作为索引类型：

// 在comments字段上创建全文索引
db.reviews.createIndex( { comments: "text" } )
// 针对多个字段的全文索引
db.reviews.createIndex( { subject: "text", comments: "text" } )
// 针对所有包含字符串数据的字段进行索引
db.collection.createIndex( { "$**": "text" } )

基于Hash的分片需要在分片键上使用这种索引。使用哈希分片可以更加随机的分布数据。

要创建哈希索引，以hashed为索引类型：

db.collection.createIndex( { _id: "hashed" } )

创建了哈希索引的字段，不能包含在复合索引中。 

创建索引时，第二个参数文档可以指定以下选项：

// 针对烹调风格、餐馆名称创建索引，指对排名大于5的餐馆进行索引
db.restaurants.createIndex(
   { cuisine: 1, name: 1 },
   { partialFilterExpression: { rating: { $gt: 5 } } }
)

// 该查询可以用到上面的部分索引
db.restaurants.find( { cuisine: "Italian", rating: { $gte: 8 } } )
// 下面的两个查询都不能使用上面的部分索引
db.restaurants.find( { cuisine: "Italian", rating: { $lt: 8 } } )
db.restaurants.find( { cuisine: "Italian" } )

db.eventlog.createIndex( { "lastModifiedDate": 1 }, { expireAfterSeconds: 3600 } )

{ <storage-engine-name>: <options> }

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   // 用于指定索引是否大小写敏感
   strength: <int>,     
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
} 

从2.6开始，复制集的从节点支持在后台构建索引，而之前的版本从节点必须在前台构建。

当主节点在后台构建好索引后，从节点自动在后台开始构建索引。对于分片集群，mongos会发送createIndex命令到每个分片上的复制集的主节点。

推荐使用本节的步骤来为复制集构建索引，避免影响数据库性能。

注意：

1. 确保oplog足够大，这样当索引创建操作完毕后，从节点不会太过落后而无法赶上主节点的节奏
2. 该推荐步骤每次把一个成员移出复制集，因此不会影响所有从节点

要为从节点构建索引，针对所有从节点执行：

1. 停止一个从节点，并以独立模式启动（不带 --replSet选项）：
   

   // 不使用默认的27017端口，防止构建索引期间，复制集的成员、客户端连接到该节点
   mongod --port 47017

2. 使用createIndex命令创建索引
3. 重新启动mongod，并添加到复制集中：
   

   mongod --port 27017 --replSet rs0

   该节点将和主节点同步 

要为主节点构建索引，你可以：

1. 在主节点上触发后台索引构建
2. 或者，调用

   rs.stepDown()

   让主节点优雅的变成从节点，集群会重新选择主节点。然后，对其执行从节点构建索引的推荐步骤

从2.6开始，MongoDB能够使用多个索引的交叉来满足查询。典型的索引交叉牵涉到两个索引，但是MongoDB支持多个索引、内嵌索引的交叉。

假设集合orders在qty和item上有索引，则查询：

db.orders.find( { item: "abc123", qty: { $gt: 15 } } )

会用到索引交叉 —— 即使用item、qty两个索引的扫描结果进行逻辑与操作。查看执行计划，你可以看到AND_SORTED或者AND_HASH这样的Stage。

复合索引的前缀可以参与到索引交叉中。

由于字段顺序、升序/降序都对复合索引有影响，复合索引可能无法满足某些查询：

1. 没有指定合理前缀作为查询条件
2. 不匹配的升/降序排序规则

这些情况下，索引交叉能够代替复合索引提升查询性能。

创建哪些索引最合适，取决于很多因素，例如：

1. 期望的查询的形状
2. 读写比
3. 系统的可用内存

如果能够让整个索引位于内存之中，则可以避免磁盘扫描，获得很快的处理速度。执行：

db.collection.totalIndexSize()

注意：索引并非总是需要完全载入内存。假设索引字段的值随着insert不断增长，而且查询总是针对最新添加的文档，则MongoDB仅仅需要在内存中载入部分索引内容。

查看集合上现存的索引：

db.collection.getIndexes()

移除单个索引：

db.collection.dropIndex()

移除除了_id之外的全部索引：

db.collection.dropIndexes()

重新构建集合上的全部索引：

// 对于复制集，该操作不会传播到从节点
// 如果索引在创建时，指定了background:true，则索引会在后台重新创建
// 但是，_id的索引总是在前台创建，导致数据库写锁定
db.collection.reIndex()

你可以使用这一聚合管线Stage来获得索引的使用情况统计信息。

在 executionStats模式下获得执行计划，可以获得查询的统计信息，包括使用的索引、扫描的文档数量、消耗的时间。

要强制查询使用某个索引，可以调用此方法：

db.people.find(
   { name: "John Doe", zipcode: { $gt: "63000" } }
)
// 强制使用zipcode索引
.hint( { zipcode: 1 } )
// 阻止使用任何索引
.hint( { $natural: 1 } )

存储引擎是MongoDB的一个核心组件，它决定了数据如何被存储（内存和磁盘）。MongoDB支持多存储引擎，以便你根据不同的工作负载进行选择。

从3.2开始，这是默认的存储引擎。适用于大部分工作负载，推荐新项目使用该引擎。 

WiredTiger提供文档级的并发模型、检查点、压缩以及其它特性。

最初的存储引擎，3.2之前的默认存储引擎。适用于大量读写的工作负载，以及in-place更新。

仅在MongoDB Enterprise中可用，在内存中保存数据，速度快。 

WiredTiger使用文档级并发来控制写操作。因此，多个客户端可以在同时修改某个集合中的不同文档。 

对于大部分的读写操作，WiredTiger使用乐观并发控制。它仅仅在全局、数据库、集合级别使用意向锁。当引擎检测到两个操作之间存在冲突时，会透明的重试其中会引起写冲突的操作。 

某些全局操作，通常是牵涉多个数据库的短暂操作，仍然使用全局（实例级别）的锁。某些其它操作，例如drop集合，仍然需要数据库级别的独占锁。

WiredTiger支持多版本并发控制（ MultiVersion Concurrency Control ，MVCC）。在操作开始时，引擎提供数据集在那个时间点的精确快照 —— 位于内存中的一致性视图。

当写入到磁盘时，引擎以一种一致性的方式，把快照中的数据写入到所有相关的数据文件中。快照中的数据集，在数据文件中可以作为检查点（checkpoint），数据库可以恢复到检查点之前的状态。

默认的，WiredTiger每60秒、或者每产生2GB日志文件后，创建检查点。

在写入新检查点的过程中，以前的检查点仍然可用。因此，如果正在写入检查点时MongoDB崩溃，重启后它能够恢复到上一个检查点。

当WiredTiger原子的把对检查点的引用写入到元数据表（metadata table）之后，新的检查点变得可访问、永久化。一旦新检查点变得可访问，旧检查点的页被释放。

使用WiredTiger时，即使没有启用日志（journaling）。MongoDB仍然能够从上一个检查点恢复。但是要想恢复上一检查点后面的变动，需要日志的配合。

WiredTiger使用预写式（Write-ahead）日志，联合检查点，来确保数据的安全性。日志（Journal）对上一个检查点以来的所有数据修改都进行了持久化。如果MongoDB宕机，可以重放（Replay）从上一检查点依赖的所有数据修改。日志文件存放在

$dbPath/journal/WiredTigerLog.<sequence>

WiredTiger为客户端发起的每一个操作，创建一条日志记录（journal record），该记录操作触发Mongod对数据库进行修改（包括集合、索引）的全部信息。

WiredTiger使用内存来作为日志记录的缓冲，多个线程协作以分配、拷贝自己的那部分缓冲。在以下情况下，日志记录缓冲被刷入磁盘：

1. 从3.2开始，每50ms
2. 一旦检查点被创建
3. 使用写关注j:true执行了写操作后
4. 每当新的日志文件被创建后。MongoDB限制日志文件大小为100MB，因此每超过此大小，就同步日志缓冲到磁盘

WiredTiger日志利用snappy库进行压缩，你可以通过

storage.wiredTiger.engineConfig.journalCompressor

设置

storage.journal.enabled

使用WiredTiger引擎时，MongoDB支持所有集合、索引的压缩。压缩通过CPU时间来换取存储空间的节省。

默认的，WiredTiger利用snappy库对集合、索引前缀进行压缩。对于集合来说，还可选zlib进行压缩。你可以设置：

1. storage.wiredTiger.collectionConfig.blockCompressor

   来改变集合的压缩算法

2. storage.wiredTiger.indexConfig.prefixCompression

   来禁用索引前缀压缩

压缩可以在集合、索引级别设置，你可以在创建集合、索引的时候指定对应的选项。

在大部分的工作负载下，默认压缩算法在时间和空间之间保持了一个平衡。

使用WiredTiger时，MongoDB同时利用WiredTiger内部缓存、文件系统缓存。

从3.4开始，WiredTiger 内部缓存的内存用量，默认取内存总量/2 -1GB 和256MB两个值中较大的那个。参数

storage.wiredTiger.engineConfig.cacheSizeGB

通过文件系统缓存，MongoDB可以利用所有空闲内存，文件系统缓存中的数据是被压缩的。

这是MongoDB最初的，基于内存映射文件的引擎。当面临大量插入、读取、原地（in-place，不需要移动文档）更新时，性能比WiredTiger更好。从3.2开始，该引擎不再是MongoDB的默认存储引擎。

当写操作发生时，MMAPv1更新内存视图。如果启用了日志内存中的改变首先被写到日志中而不是直接写到数据文件中。

为了确保所有数据集能够正确的持久化。MMAPv1使用磁盘日志，写磁盘日志比数据文件更加频繁，因为其效率较高。

使用默认配置的情况下，MMAPv1每60秒写一次磁盘（可以通过

storage.syncPeriodSecs

storage.journal.commitIntervalMs

MMAPv1的所有文档都是连续的存储在磁盘上的。如果文档update后变得过大，则必须重新分配磁盘空间。这意味着文档本身的移动、全部索引的更新，会影响性能并引起存储碎片化。

从3.0开始，MongoDB使用2^N尺寸的空间分配策略，多余的空间作为补白（padding），可以降低文档移动的几率。原来的精确适合（exact fit）空间分配策略，使用不包含update/delete操作的场景。

MMAPv1自动使用机器的全部空闲内存作为它的缓存，但是，一旦其它进程需要使用内存，MongoDB占据的内存会立即释放。

典型情况下，操作系统的虚拟内存系统管理MongoDB的内存使用，如果内存不够，MongoDB缓存会被交换到磁盘中。配备足够的内存，可以很大程度的提高性能。

GridFS是一套规范，用于存放那些大于BSON文档尺寸限制（16MB）的文件。

GridFS不是把文件存放在文档中，而是将其切分成多个部分（chunks），然后把这些部分分别存放在文档中。默认情况下，GridFS使用255KB的chunk，因此除了最后一个之外的chunk具有一致的大小。

GridFS使用两个集合来存放文件：

1. fs.chunks

   ，用于存放文件的chunks，文档原型如下：
   

   {
       "_id" : <ObjectId>,         // 块的唯一标识
       "files_id" : <ObjectId>,    // 所属的文件的唯一标识  
       "n" : <num>,                // 从0开始的序号
       "data" : <binary>           // BinData类型的数据块
   } 

2. fs.files

   ，用于存放文件的元数据，文档原型如下：
   

   {
       "_id" : <ObjectId>,            // 文件的唯一标识
       "length" : <num>,              // 文件的长度
       "chunkSize" : <num>,           // 块的数量
       "uploadDate" : <timestamp>,    // 存放到GridFS中的时间
       "md5" : <hash>,                // 散列值
       "filename" : <string>,         // 人类可读的可选的文件名
       "contentType" : <string>,      // 可选的MIME类型
       "aliases" : <string array>,    // 别名数组
       "metadata" : <dataObject>,     // 任意额外的自定义元数据
   } 

当你查询GridFS以取回文件时，驱动程序负责把chunks装配成文件。GridFS支持针对文件进行范围查询，或者skip一定的长度。

如果你需要存放大于16MB的文件时，应当使用GridFS。否则，考虑使用BinData类型存储在集合中。

某些情况下，在MongoDB中存储大文件比在文件系统中直接存放更加高效：

1. 如果文件系统限制目录中最大文件数，MongoDB没有此限制
2. 如果你想访问大文件的一小部分，而不希望把整个文件加载到内存
3. 如果你想获得复制集带来的文件安全性

chunks、files两个集合自带一部分索引（由驱动创建），以提升性能。你也可以创建自己的索引，以满足需要。

chunks上具有唯一性的复合索引：files_id + n，这让chunk的检索非常高效，示例查询：

db.fs.chunks.find( { files_id: myFileID } ).sort( { n: 1 } )

如果驱动没有创建此索引（不满足规范），可以手工创建：

db.fs.chunks.createIndex( { files_id: 1, n: 1 }, { unique: true } );

files上具有filename、uploadDate两个索引，你可以很方便的根据名称、日志进行文件检索。

如果驱动没有创建此索引（不满足规范），可以手工创建：

db.fs.files.createIndex( { filename: 1, uploadDate: 1 } );

如果需要分片chunks，考虑以

{ files_id : 1, n : 1 }

{ files_id : 1 }

files集合仅仅包含元数据，通常不需要分片。 

复制集（replica set ）是指一组mongod进程，它们维护相同的数据集。复制集提供了数据冗余、高可用性，对于生产环境来说复制集基本是标配。

在某些情况下，复制集可以提供额外的读容量，因为客户端可以把请求分发给复制集中的任意成员。对于跨地域部署的应用程序来说，分别在不同数据中心的复制集节点可以大大降低网络延迟。

每个复制集可以具有N个数据存储节点，和一个可选的仲裁（arbiter）节点。存储节点中有且仅有一个是主（primary）节点，其它均为从（secondary）节点。

主节点接收所有写操作请求，此节点负责确认{ w: "majority" }写关注。主节点把自己对数据集的全部变更存放在日志 —— oplog中。这些oplog随后被异步的传播到所有从节点，确保所有节点的数据集一致：

当主节点不可用时（和其它成员超过10s不进行通信），一个从节点会被选举为新的主节点。你可以额外配置一个mongod实例作为仲裁节点，这类节点不维护数据集，它的职责仅仅是响应心跳、应答其它节点的选举（投票）请求。当存储节点数量为偶数时，添加一个仲裁节点，可以满足投票的大多数（majority）原则。仲裁节点不需要专用的硬件，可以和某个存储节点部署在一起。

尽管所有成员都可以接受读请求，但是默认的，应用程序会把读请求重定向给主节点。

这类从节点没有称为主节点的资格，没有资格触发选举（从节点总是自荐为主节点以触发选举），但是可以进行投票。在多数据中心部署的情况下，要避免某个数据中心产生主节点，则将其中的节点均配置为priority0从节点。

默认的，没有任何节点是priority0从节点。你需要手工设置节点的priority为0。

注意当前主节点不支持设置priority为0，因此，如果你想把主节点变为priority，先需要将其变为从节点。

rs.reconfig()

调用

cfg = rs.conf()

members

members[n].priority = 0

rs.reconfig(cfg)

之类从节点维持主节点数据集的拷贝，但是对客户端不可见。隐藏从节点必须是priority0节点。

由于对客户端不可见，隐藏从节点的流量仅仅包括来自主节点的数据复制流。你可以使用隐藏从节点执行专门任务，你如报表分析、备份。在分片集群中，mongos不会和隐藏从节点交互。

当使用隐藏从节点执行备份时，需要注意：

1. 如果使用MMAPv1引擎，使用

   db.fsyncLock()

   和

   db.fsyncUnlock()

   操作可以在备份期间flush所有写操作并且锁定mongod，这样可以不必为了备份而停止隐藏节点
2. 从3.2开始db.fsyncLock()可以保证数据文件不改变，不管使用MMAPv1还是WiredTiger 引擎，因此可以保证备份期间的数据一致性。在之前的版本，不保证WiredTiger下的数据一致性

延迟从节点也维持主节点数据集的拷贝，但是其状态对应了主节点一个早先的状态，例如一小时前。

由于此特性，延迟从节点可以用做滚动备份（rolling backup），当出现人为操作错误时，可以恢复到先前的数据状态。

延迟节点必须是priority0节点，而且应当是隐藏节点。配置文档示例： 

{
   "_id" : <num>,
   "host" : <hostname:port>,
   "priority" : 0,
   "slaveDelay" : <seconds>,
   "hidden" : true
}

仲裁者节点不维护数据拷贝，不能变为主节点，它仅仅在选举主节点时起作用。 仲裁者总是具有1张选票，因此它可用于确保总是有奇数张选票，以满足大多数原则。

注意：不要在部署了复制集主节点、从节点的机器上部署仲裁节点。

一个节点被作为仲裁者加入到复制集之前，行为与普通mongod无异，它会创建一系列的数据文件、全尺寸的日志文件。为了最小化默认文件的创建，可以配置仲裁节点的配置文件：

1. 设置

   storage.journal.enabled

   为false
2. 对于MMAPv1 引擎，设置

   storage.mmapv1.smallFiles

   为true

为复制集添加仲裁节点的参考步骤如下：

1. 指定复制集名称、数据库路径，启动mongod：
   

   mongod --port 30000 --dbpath /data/arb --replSet rs

2.  在复制集主节点中执行先的命令，把上一步的mongod添加为仲裁者：
   

   rs.addArb("HOST:30000") 

操作日志（Oplog）是一个特殊的定长集合，保存了所有修改了数据集的操作的滚动记录。MongoDB会在主节点上应用写操作，并将这些操作记录到主节点的Oplog。 复制集中的从节点会在之后异步的读取此定长集合，并将其中的操作应用到自己本地的数据库。

所有复制集成员都在

local.oplog.rs

Oplog中的条目是幂等的，也就是说，这些条目应用一次还是多次，其产生的效果是一致的。

当以第一次复制集成员身份启动mongod时，会自动创建默认尺寸的Oplog。默认尺寸对于In-Memory引擎来说是5%内存大小，对于其它引擎默认5%磁盘空闲空间大小。

在第一次启动前，你可以指定

oplogSizeMB

某些可能需要大尺寸Oplog的场景：

1. 同时更新很多文档：为了确保幂等性，Oplog必须把批量更新操作拆分成很多单条操作
2. 删除的文档和更新的文档数量相近：这种情况下，数据库文件可能增长不大，但是Oplog会较大
3. 还量的In-place更新

调用

rs.printReplicationInfo()

在某些异常情况下，从节点的Oplog更新可能过于延迟，达不到性能要求。在从节点调用

db.getReplicationInfo()

为了维护最新的共享数据集，从节点需要从其它节点同步（sync）或者拷贝数据。MongoDB使用两种形式的数据同步：

1. 初始同步（initial sync）：为新的从节点提供完整的数据集
2. 复制（replication）：在初始数据集之上同步增量数据

MongoDB执行初始同步的流程如下：

1. 克隆除了local之外的所有数据库，注意：
   1. 从3.4开始，所有的索引也被构建，之前的版本仅仅克隆_id索引
   2. 从3.4开始，在克隆过程中新产生的Oplog也被拉取过来。你需要确保新的从节点的local数据库有足够的磁盘空间
2. 新从节点应用所有克隆来的数据，并应用Oplog

初始同步完毕后，新从节点的复制集成员状态从STARTUP2变为SECONDARY

为了防止偶发的网络错误，初始同步内置了重试逻辑作为容错措施。

在初始同步之后，从节点会不断的复制增量数据 —— 异步的拷贝Oplog并应用到数据库中。

从节点会根据PING延迟、其它节点的复制状态，自动切换拷贝Oplog的源节点。 但是：

1. 从3.2开始，投票权1的节点不得把投票权0的节点作为源
2. 会避免将延迟从节点、因从从节点作为源
3. 如果当前节点的复制集配置

   members[n].buildIndexes

   为true，则仅此配置也为true的其它节点，才能作为源。此配置默认true

为了增强性能，MongoDB会使用多线程来应用Oplog，日志中的条目被按照名字空间（MMAPv1）、文档标识（WiredTiger）分组，每个组一个线程，同时入库。日志的入库顺序总是和主节点上相同，在分组批量入库期间，从节点阻塞所有读请求，因此不会读到主节点上不存在的数据

对于MMAPv1引擎来说，MongoDB会抓取包含了受到影响的数据、索引的内存页，用于辅助增强应用Oplog条目的性能。

此索引预抓取可以最小化应用Oplog时持有写锁的时间，默认的从节点预抓取所有索引。配置项

secondaryIndexPrefetch

复制集的架构影响其容量和能力。

通常情况下，生产环境中使用3成员的复制集，这保证了数据冗余和容错，同时也避免过于复杂的部署。请结合应用程序需要，并注意：

1. 复制集最多具有50个成员，但是能投票的最多7个成员。因此，如果复制集已经有7个成员，再添加节点必须是非投票成员
2. 投票成员数量应为奇数，必要时添加一个仲裁节点，确保此规则
3. 为了满足特殊的需求，考虑添加延迟、隐藏从节点
4. 负载均衡与大量读负载：如果应用面临很高的读负载，可以将负载分发到从节点以提升性能。如果应用跨地域分布，可以考虑在不同数据中心部署从节点
5. 异地灾备：为了防止数据中心出现重大灾难而导致数据丢失，至少应当部署一个异地的从节点。为了确保主数据中心的的节点优先被选举为主节点，配置异地节点的

   members[n].priority

   为更小的值
6. 为从节点应用标签集（Tag set）：你可以为节点应用一系列标签，从而把读操作引向特定的节点，或者定制写关注——从其它节点获得请求确认
7. 使用日志防止断电导致的数据丢失：MongoDB默认启用了写前日志（journaling ），可以有效的防止断电、宕机导致的数据丢失
8. 网络、计算资源受限的节点，应该避免称为主节点，使用priority0

如果你的应用程序连接到多个复制集，则每个复制集需要具有唯一的名称，某些驱动根据此名称对复制集进行分组。

这是典型的、最小化的复制集架构。三个成员中，可以有一个作为仲裁节点。

使用三个数据节点时，数据具有三份拷贝，提供了容错和HA。如果主节点宕机，一个从节点会被选举为新主节点。宕机主节点恢复后，自动重新加入复制集。

在异地数据中心部署节点，可以抵御断电、网络中断甚至自然灾害。

要实现异地灾备，至少在其它数据中心部署一个从节点。可能的话，使用奇数个数的数据中心。要尽可能保证，即使一个数据中心完全不可用，复制集仍然能保证majority原则。

部署示例：

1. 三成员复制集：
   1. 两数据中心：DC1两成员，DC2一成员，如果有仲裁者，部署在DC1。当DC1不可用时复制集变为只读；当DC2不可用时DC1继续运行（大多数原则）
   2. 三数据中心：每个数据中心一个节点。不管哪个数据中心不可用，复制集仍然可读写
2. 五成员复制集：
   1. 两数据中心：DC1三成员，DC2两成员。当DC1不可用时复制集变为只读；当DC2不可用时DC1继续运行（大多数原则）
   2. 三数据中心：DC1两成员，DC2两成员，DC3一成员。不管哪个数据中心不可用，复制集仍然可读写（大多数原则）

利用自动的故障转移机制，复制集提供高可用性。故障转移即当主节点不可用时，某个从节点被选举为新主节点的过程。

从3.2开始，MongoDB引入版本1（(protocolVersion: 1）的复制协议，降低了故障转移消耗的时间，加速重复主节点检测速度。新创建的复制集会自动使用版本1的协议。

复制集使用选举机制来确定谁作为主节点，在以下情况下，发生选举：

1. 初始化一个复制集时
2. 当主节点变得不可用时

主节点的选举需要时间，在选举完成之前，复制集不能接受写请求，所有节点呈只读状态。

如果复制集的大部分节点对于主节点不可访问，则主节点会setp down并变成从节点。这样复制集就不能接受写请求了，但是如果配置了在从节点上执行查询，则剩余节点仍然支持读操作。

影响主节点选举的因素包括：

1. 复制协议：从3.2引入的版本1提高了性能
2. 心跳：复制集成员每2秒向各成员发送心跳，如果心跳应答10秒没有返回，标记为不可达（inaccessible）
3. 成员优先级：选举算法会仅可能的让高优先级的从节点触发选举。优先级影响选举的耗时和结果，因为高优先级的节点会更快的触发选举并很可能赢得选举。但是，低优先级的成员也可能临时的被选举为主节点，此时选举会继续，直到最高优先级的成员当选
4. 数据中心不可用：多数据中心部署的情况下，某个数据中心整体不可用可能导致无法选举
5. 否决：版本1协议取消了否决机制。但是版本0中任何成员均具有否决权

复制集成员的配置

members[n].votes

1. members[n].votes=1

   的节点具有投票资格，要禁止某个节点投票，可以设置为0。从3.2开始，非投票节点的priority必须为0
2. 仅仅以下状态的节点可以参与投票：PRIMARY、SECONDARY、RECOVERING、ARBITER、ROLLBACK

回滚导致前主节点上的写操作被撤销，当此“前主节点”重新加入到复制时。回滚仅仅在主节点已经应用了写操作，但是此写操作没有来得及在step down之前被成功复制的情况下。回滚保证了数据一致性。

如果写操作被任意从节点复制，并且此从节点可以被大多数节点访问，则回滚不会发生。

对于复制集，默认写关注

{w: 1}

w: "majority"

1. 如果writeConcernMajorityJournalDefault设置为false，即使使用前面的写关注，仍然不能保证不会回滚，因为写操作可能没有持久化到磁盘
2. 不管写关注设置为什么，local读关注都可能看到甚至没有被写者确认的数据。local可能读到之后被回滚的数据

一个mongod不支持回滚超过300MB的数据。你可以在mongod日志中看到：

[replica set sync] replSet syncThread: 13410 replSet too much data to roll back 

如果系统需要回滚超过300MB的数据，你必须手工介入，强制初始同步 —— 删除前主节点的dbPath目录。

从客户端角度来说，mongod以独立方式运行，还是作为复制集成员，是透明的。但是，MongoDB提供了额外的读写选项，提供数据一致性保证。

对于复制集，默认写关注仅要求来自主节点的确认。你可以改变此选项，要求来自指定数量/大多数节点的确认。例如，使用w:2时写操作的处理流程如下：

要修改默认写关注选项，可以为复制集配置

settings.getLastErrorDefaults

cfg = rs.conf()
cfg.settings.getLastErrorDefaults = { w: "majority", wtimeout: 5000 }
rs.reconfig(cfg)

读设置描述MongoDB如何把读操作请求路由到某个复制集成员。默认情况下，应用程序把读请求发送给复制集中的主节点。读设置与直接连接到单个mongod的那些客户端没有关系。修改读设置时需要小心，从节点可能返回陈旧的数据，原因是复制的异步性。

使用Shell时，可以调用游标的

cursor.readPref(mode,tagset)

// 从最近的节点读取数据，仅仅从东部数据中心读取（根据节点的标签集）
db.collection.find().readPref('nearest', [ { 'dc': 'east' } ])

读设置的mode可以取值：

标签集用于指定仅具有特定标签的复制集成员才可以接收读操作请求。除了primary模式外，都可以指定该选项。

3.4引入的

maxStalenessSeconds

读设置适用于通过mongos连接到分片集群的客户端。mongos连接到某个以复制集形式出现的分片时，遵守此读设置。

使用非主读设置的应用场景：

1. 运行不影响前端应用程序的系统操作
2. 对跨地域分布的应用程序提供本地读功能，考虑使用读设置

   nearest

   ，以获得低延迟
3. 在故障转移期间维持可用性，考虑使用读设置

   primaryPreferred

   ，这样正常情况下读取主节点，如果主节点不可用则允许读取（只读）可能陈旧的数据

在一般场景下，不要使用

secondary

secondaryPreferred

1. 复制集中的大部分成员的写流量是差不多的，因而，从节点不会比主节点具有更大的读能力
2. 复制是异步进行的，你可能读取到过时的数据，从不同的从节点读取数据，可能导致非单调读
3. 对于针对分片集合的查询，对于启用负载均衡器的集群，由于不完整的chunk迁移，从节点可能返回重复的、丢失的数据

要扩容，分片通常是更加优先的选择，因为它利用了多台机器的计算资源。

每个mongod都拥有一个名为local的数据库，其中存放有关工作集复制处理过程用到的数据、以及其它实例相关的数据，该数据库对Replication是不可见的。

该数据库包含以下集合：

rs.conf()

下表仅仅列出没有对应Shell方法的数据库命令：

解决扩容性问题的两种手段，主要是：

1. 垂直扩容（Vertical Scaling）：增加单机的能力，例如更换更强的CPU、增加内存条、增加硬盘等。这种扩容方式有极限，而且成本是指数级增加的。使用云服务时，则不能进行垂直扩容
2. 水平扩容（Horizontal Scaling）：将数据集切分到多个廉价服务器上，通过增加服务器即可提升系统容量

分片（Sharding）是跨越多态机器分发、存储数据的手段，属于水平扩容。MongoDB使用分片来支持海量数据集和高吞吐量需求。MongoDB在集合的级别进行分片。

分片的优势包括：

1. 读/写：进行分片后，MongoDB的读写操作均可以被很好的扩容。当查询包含分片键（前缀）条件时，mongos仅仅发送查询请求给相关的Shard
2. 存储容量：可以使用廉价硬件无限扩展
3. 高可用性：在部分Shard不可用的情况下，仍然能够进行部分的读写操作。配置服务器可以作为复制集部署，保证高可用性

执行分片前，应当考虑：

1. 分片增加了调试、运维的复杂度
2. 小心的选择分片键，不合理的选择会影响性能
3. 某些需要scatter/gather，因而消耗较多时间

一个MongoDB分片集群（sharded cluster ）由以下成员组成：

1. 分片（Shard）：由单个mongod或者一个复制集组成，维护一个数据分片。在生产环境下，每个分片可以定义为3成员复制集
2. 路由器（mongos）：作为查询路由器存在，作为客户端应用和分片集群之间的接口。你可以在每个应用服务器上都部署mongos，或者定义一组mongos并提供前置负载均衡器/代理给应用程序使用
3. 配置服务器：保存分片集群的元数据、配置信息。从3.4开始，复制服务器必须作为复制集部署（CSRS）。在生产环境下，可以定义为3成员复制集

下图示意了这些成员之间的关系：

应用程序（MongoDB客户端）要想和集群进行交互，必须连接到mongos —— 不管你要使用的是分片还是非分片集合，客户端绝不该直接连接到某个Shard，除了执行分片本地管理、维护工作的时候。

分片集群中的每个数据库都有一个主分片（Primary Shard），该分片存放数据库上所有未分片的集合。

当创建新数据库时，mongos会选取集群中保存数据最少的分片，作为数据库的主分片。要改变主分片，可以调用

movePrimary

执行

sh.status()

1. 数据库的主分片信息
2. Chunk在Shard中的分布情况

这类服务器存放分片集群的元数据，元数据记录了：

1. 分片集群中所有数据、组件的状态和组织
2. Chunk对应的值范围
3. 每个分片包含的Chunks

此外，配置服务器还：

1. 存储身份验证配置信息，例如基于角色的访问控制、内部验证设置
2. 管理分布式锁

mongos会缓存以上信息，以便对读写操作进行路由。当元数据变更后mogos的缓存会自动更新。

从3.4开始，配置服务器必须使用满足以下要求的复制集：

1. 具有0个仲裁者
2. 不存在延迟节点
3. 任何节点的buildIndexes设置不得为false

配置服务器具有config、admin数据库。

admin数据库包含与认证/授权相关的集合，以及 system.*集合（内部使用）。

config数据库包含了分片集群的元数据，当元数据变更（例如chunk迁移、chunk分裂）时MongoDB会写此数据库，而mongos会读取该数据库。客户端不应该直接写此数据库。读写此数据库时，均使用关注级别majority。

如果配置服务器复制集的主节点宕机，并且不能选举出新的主节点，则集群的元数据变为只读状态。你仍然可以对分片进行读写操作，但是不能进行Chunk迁移、分裂。

如果配置服务器复制集完全不可用，则分片集群不支持任何操作。但是mongos会缓存元数据，因而在重新启动mongos之前，仍然能进行分片的读写。

由于配置服务器非常重要，并且数据量很小，应该重视对其进行备份。

路由器（mongos）这样路由查询：

1. 确定需要接收查询请求的Shard列表
2. 在所有目标分片上建立一个游标
3. 合并各Shard返回的查询结果，返回结果文档给客户端

要确保客户端连接到的是MongoDB实例是路由器，你可以执行isMaster命令，其返回值：

{
   "ismaster" : true,
   "msg" : "isdbgrid",
   "maxBsonObjectSize" : 16777216,
   "ok" : 1
}

中的msg字段如果为isdbgrid，则说明他是mongos。

进行分片时，需要决定每一条数据应该存放到哪个Shard上，这依赖于分片键。分片键由集合中每个文档都具有的、不变的（immutable）字段构成。一旦选择好分片键，以后就不能再修改，每个分片集合有且只有一个分片键。分片键的选择影响性能、可扩容性。

要对某个集合进行分片，执行：

# namespace：<database>.<collection>
# key 索引规格文档，用于指定分片键
# unique 对分片键进行唯一性约束，哈希分片键不支持。非空集合的唯一性索引必须提前手工创建好
# options.numInitialChunks 使用哈希分片键来创建空的分片集群时，最初创建的Chunk的数量
sh.shardCollection( namespace, key, unique, options )

分片集合必须有一个支持分片键的索引：此索引要么在分片键上创建，要么以分片键开头。如果：

1. 集合是空的，并且分片键上没有索引，则sh.shardCollection()自动在分片键上创建索引
2. 集合是非空，你必须在调用sh.shardCollection()之前，手工创建索引

对于分片集合，仅仅_id、位于分片键字段的索引、以分片键字段开头的索引可以是唯一性索引。不满足此条件的集合无法分片，分片后你无法在不满足此条件的字段上新建唯一性索引。

如果对分片键使用唯一性索引（sh.shardCollection指定unique为true），则MongoDB可以保证分片键取值的唯一性。如果分片键包含多个字段，则保证其整体上的唯一性而非某个字段。

分片键长度不能超过512字节。要么对索引键进行索引，要么以其为索引前缀。可以对分片键建立哈希索引。多键索引、文本索引、地理空间索引均不支持。

分片键是不可变的，如果你必须改变分片键的值，按以下步骤：

1. 把索引数据Dump出来
2. Drop原先的分片集合
3. 使用新的分片键进行分片
4. Pre-split分片键范围，确保均匀的数据分布
5. 把Dump出的数据导入到数据库

分片键的值是不可变的：你不能修改分片键字段的值。

理想的分片键，应该让MongoDB仅可能均匀的把文档分发到各分片上。

分片键的基数（cardinality，候选取值数量）决定了负载均衡器能够创建的Chunks的最大数量，进而影响水平扩容的有效性。一个特定的分片键值，任何时刻仅仅能存在于一个Chunk上，因此如果分片键的基数为4，则最多创建4个Chunk，因而最多使用4个分片（服务器），添加额外的服务器得不到任何好处。

如果数据模型要求在低基数字段上分片，可以考虑联合某个高基数字段建立联合索引。

尽管具有高基数的分片键可以更好的支持水平扩容，但是它不能保证数据均匀分布在各分片，因为各键值对应的记录数量（Frequency）差异可能很大。分片键频率（Shard Key Frequency）用来描述一个特定的分片键值出现的频率。如果某些分片键取值具有非常高的Frequency，那么存储高Frequency的Chunks将出现性能瓶颈，并且这些Chunk可能无法再次分裂（单个键值无法再分裂）。

如果数据模型要求在高Frequency字段上分片，可以考虑联合某个低Frequency/Unique字段建立联合索引。

单调变化的分片键可能限制集群的插入吞吐量。因为一段时间内索引的插入可能都被分发到同一个分片（开区间的第一个、最后一个Chunk）上：

在上图中，如果分片键单调递增，则后续所有insert都分发到Chunk C；如果单调递减，则都分发到Chunk A。

如果数据模型要求在单调递增字段上分片，可以考虑使用哈希分片。

MongoDB支持两种分片策略。

所谓哈希分片，是指使用单字段的哈希索引来作为分片键的分片策略。哈希分片导致基于分片键的范围查询难以匹配单个/少量分片（查询隔离，Query Isolation），往往需要广播到所有分片。但是，哈希分片让数据更加均匀的分布在各Shard中，特别是在分片键单调递增/减的情况下（例如自增长）。

这种分片策略需要对每一个分片键字段的值计算哈希，每个Chunk对应一个哈希值区间。

如果对空集合进行哈希分片，MongoDB默认为每个Shard创建两个空的Chunk，所有这些Chunks覆盖哈希值域。在执行分片时，可以指定numInitialChunks来定制Chunk的数量。

用作哈希分片的字段，应当具有高基数（大量不同的取值），哈希分片适用于时间戳、ObjectId之类的单调变化的值类型，你可以基于自动生成的_id进行哈希分片。

要执行哈希分片，调用命令：

sh.shardCollection( "database.collection", { <field> : "hashed" } )

 注意：MongoDB的哈希索引会在计算哈希值之前，把浮点数截断为64-bit的整数，并且不支持大于2^53的浮点数。为防止哈希冲突，你可能需要将分片键乘以10^N后存储。

这是MongoDB默认的分片策略，它直接根据分片键字段的值来划分Chunk，分片键值相近的文档，可能分布在同一个Shard/Chunk中。这样，进行范围查询时往往能够实现查询隔离。

选择范围分片键时，要注意前文所述的：高基数、低Frequency、非单调变化原则。

要执行范围分片，调用命令：

sh.shardCollection( "database.collection", { <shard key> } )

MongoDB把数据划分为Chunk。 MongoDB可以使用分片集群负载均衡器进行跨Shard的Chunk迁移，以保证每个Shard被合理利用。

每个Shard上存储0-N个Chunk，每个Chunk对应了一个分片键取值区间，区间总是[ 闭，开 ) 形式的。所有Chunk正好覆盖分片键的键空间。

将数据集和Chunk而不是Shard进行关联，其好处是：

1. 可以按需添加新的机器（Shard），然后轻易的再平衡数据集（迁移Chunk）
2. 在必要时（假设某个Chunk过大），可以进行Chunk分裂，然后进行再平衡

如果块增长超过配置的尺寸，MongoDB会执行块分裂（Split），插入、更新操作都可能引发块分裂。只要块包含超过1个的分片键值，就可以被分裂。

MongoDB默认的Chunk尺寸是64MB。修改此默认值时，要注意：

1. 小尺寸的Chunk可以让数据分布更加均匀，代价是更加频繁的数据迁移。性能影响产生在mongos层
2. 大尺寸的Chunk导致的迁移较少，因而从网络、mongos角度是高效的。但是可能导致数据不均匀分布
3. Chunk尺寸影响Chunk能够包含的最大文档数量（一旦超过此数量就会发生分裂）
4. 分片既有集合时，Chunk尺寸影响集合的最大尺寸
5. 实际的分裂行为只能被插入、更新操作触发
6. 分裂不能被撤销，如果你增大Chunk尺寸，那些分裂产生的Chunk不会合并回去

在实际应用中，不要为了追求一点点更加平均的分布，而盲目设置过小的Chunk尺寸。

块分裂本身是高效的元数据级别的操作，不牵涉到数据迁移（跨Shard）。但是，当数据分布不均匀时，集群的负载均衡器可能会自动重新分布Chunks。

为了在Shard之间更加均匀的分布数据，MongoDB会执行块的迁移 —— 将一个Chunk移动到另外一个Shard上并更新元数据。

块迁移可以：

1. 手工执行，你仅仅在一些特殊情况下才需要进行手工迁移
2. 自动执行，当超过迁移阈值时，负载均衡器自动执行

负载均衡器（balancer）是专门负责Chunk迁移的后台进程。如果拥有最大、最小数量Chunk的Shards的Chunk数量差超过迁移阈值，负载均衡器启动迁移。Zone的配置影响负载均衡器的行为。

如果一个Chunk仅仅包含一个分片键值，则它可能超过Chunk尺寸而继续增大，成为巨块（jumbo chunk）。因为近包含一个分片键值，这种块无法再分裂，可能形成性能瓶颈。

2.6/3.0版本的

sharding.archiveMovedChunks

如果迁移过程中出现错误，这些归档文件可以用于数据恢复。一旦迁移完成，这些文件不再有用，你可以将其删除。要判断迁移是否已经完成，连接到mongos并执行命令

sh.isBalancerRunning()

某些场景下，MongoDB自动创建的Chunk不足以满足吞吐量需求。这些场景例如：

1. 当你希望对位于单个Shard上的大集合进行分片时
2. 当你希望导入大量数据到一个负载不均衡的集群，或者导入可能导致负载不均衡时 —— 例如使用范围分片的情况下进行单调递增数据导入

上面的场景对资源敏感，原因是：

1. 块迁移要求将Chunk中所有数据进行跨Shard的移动
2. 任何Shard在同一时刻仅仅能参与一次迁移活动，负载均衡器会串行化的迁移Chunk。从3.4开始限制解除，变为：具有n个分片的集群，负载均衡器最多同时进行n/2个迁移活动
3. 块分裂仅仅会在数据插入/更新后发生

要进行预分裂（Pre-split，创建满足需要的Chunks数量），你可以执行

split

警告：你只能在空集合上执行预分裂操作。如果集合已经包含数据，MongoDB在你执行集合分片时自动创建Chunks。后续再进行手工创建Chunks可能导致不可预测的Chunk范围/尺寸，以及低效的负载均衡行为。

当Chunk尺寸到达限制后，MongoDB会自动分裂Chunk。但是某些场景下你可能期望手工执行分裂，例如：

1. 你有少量Chunks，但是要部署大量的数据到集群中
2. 你需要部署大量可能落到单个Chunk/Shard中的数据，例如分片键值200-500归属于一个Chunk，现在你要插入海量分片键值300-400之间的数据

根据需要，负载均衡器可能立即迁移刚刚分裂出来的Chunk，不考虑它是自动还是手工创建的。

调用

sh.status()

sh.splitFind()

sh.splitAt()

调用

mergeChunks

以下场景下，你可能需要手工合并：

1. 预创建（Pre-split）了过多的块
2. 你删除了很多文档，导致某些Chunk变空

如果Chunk包含的文档数量大于：

1. 250000，或者
2. 1.3 * Chunk尺寸 / 平均文档尺寸。平均文档尺寸通过db.collection.stats().avgObjSize得到

则此Chunk无法被移动。

在分片集群中，你可以依据分片键来创建分片数据的区域（zone）。一个Zone可以关联1-N个Shard，每个Shard可以关联到任意个不冲突的Zone（多对多）。在启用负载均衡的集群里，Chunk仅仅在Zone内部迁移。

需要使用Zone的场景包括：

1. 在一个Shard集上，隔离某个数据子集
2. 确保相关的数据分布于地理位置相近的Shard上
3. 根据Shard的硬件性能来路由

考虑下面这个Zone配置：

分片键值位于1-10之间的，归属于Zone A；10-20之间的归属于Zone B。Shard A属于Zone A，Shard B属于Zone A和B。这样，键值位于1-10之间的数据子集仅仅能在Shard A、B之间迁移。

每个Zone可以覆盖1-N个键值区间。这些区间总是[ 闭，开 ) 形式的。所有Zone的键值区间不得重叠，一个Zone的每个键值区间也不能重叠。

负载均衡器会尝试把分片集合的Chunks均匀分发在所有Shard上。

对于标记为待迁移的Chunk，负载均衡器根据Zone配置来确定其可选的目标Shard。如果Chunk的值范围没有落到任何Zone里，则可能被迁移到任意Shard上。

如果负载均衡器发现任何Chunk违反了Zone定义（例如进行了Zone配置），它会将其进行迁移。

进行了Zone配置后，集群可能需要一定时间来执行Chunk迁移，迁移由负载均衡器在下一次 balancing rounds执行。

定义Zone覆盖的值范围时，必须使用分片键或者分片键前缀字段。

MongoDB的集群负载均衡器是一个后台进程，它监控每个Shard上Chunk的数量。当最多 - 最少Chunk数量（按Shard）打到迁移阈值后，负载均衡器尝试进行Chunk迁移，使所有Shard持有仅可能平均数量的Chunks。

负载均衡器的行为对于用户、应用程序是完全透明的，但是迁移过程可能对性能产生影响。

从3.4开始，负载均衡器在配置服务器的主节点上运行。一旦其进程激活，就会修改配置服务器的lock集合上的一个文档，获得一个“锁”，这个锁一直不会释放。

从2.6开始，负载均衡器可能影响磁盘使用，因为迁移会导致源Shard对被迁移chunk进行归档。

负载均衡器会带来带宽、工作负载方面的成本，从而影响数据库的整体性能。它通过下面的措施使影响最小化：

1. 任何时刻仅能执行一个Chunk的迁移。从3.4开始，允许N个Shard的集群同时进行N/2个块迁移
2. 仅仅当到达迁移阈值（migration threshold）时才启动负载均衡周期（balancing round）

你可以临时的禁用负载均衡器，以执行维护任务。你也可以限制负载均衡器运行的时间窗口，防止对生产环境产生不利影响。

添加Shard到集群时，会导致负载不均衡的出现，因为新的Shard不持有任何Chunk，达到再平衡需要一定的时间。

从集群中移除Shard时，其中的Chunk必须被重新分发，达到再平衡需要一定的时间，切勿再迁移完成前关闭被移除Shard对应的服务器。

所有块迁移均遵循以下流程：

1. 负载均衡器向源Shard发送moveChunk命令
2. 源Shard使用内部moveChunk命令启动。在迁移完成之前，路由到被移动Chunk的读写请求仍然由源Shard负责
3. 目标Shard构建接纳Chunk所需要的、尚不存在的索引
4. 目标Shard开始请求Chunk中的文档，接收数据拷贝并入库
5. 接收完最后一个文档后，目标Shard启动一个同步进程，确保在迁移过程中，对被迁移Chunk的写操作被应用
6. 当完全同步后，源Shard连接到配置数据库，并更新集群元数据，写入Chunk的新位置
7. 元数据写入完毕后，一旦没有针对打开的被迁移Chunk的游标，源Shard删除本地的Chunk数据拷贝。如果负载均衡器需要针对源Shard进行下一个Chunk迁移，它不会等待删除操作的完成。从2.6开始，被迁移Chunk会在源Shard归档

此阈值考虑Shard上的Chunk数量的最大差。默认取值：

配置项_secondaryThrottle的值，决定了负载均衡器何时处理Chunk中下一个被迁移的文档（在目标Shard？）：

1. 如果取值为true，则当前文档必须至少被复制到一个从节点，才处理下一个文档，相当于写关注{ w :2 }
2. 如果取值为false，则不等待复制到从节点，直接处理下一个文档

从3.4开始，如果使用 WiredTiger引擎，该配置的默认值false， MMAPv1引擎的默认值仍然为true。

此外，不管_secondaryThrottle如何取值，迁移工作流的某些阶段，遵行如下复制策略：

1. 在更新集群元数据（第6步）之前，MongoDB会短暂的暂停针对源Shard上被迁移集合的读写操作。在更新元数据的前后，要求移动Chunk的写操作被复制集大多数节点确认
2. 在执行源Shard清理（第7步）或者新的Chunk迁移之前，写操作必须被目标Shard复制集的大多数节点确认

下表仅仅列出没有对应Shell方法的数据库命令：

启动mongos、mongod实例时，可以指定一个配置文件，提供必要的选项。MongoDB的配置文件是YAML-based格式的，不支持tab，要使用space代替。

要使用配置文件，指定命令行选项：

#  -f 是 --config 的别名
mongod --config /etc/mongod.conf
mongos --config /etc/mongos.conf

# 日志选项
systemLog:
   # 默认日志级别，0-5之间，默认0，越大日志越详细
   # 要指定某个MongoDB组件的日志级别，使用 systemLog.component.<name>.verbosity
   verbosity: <int>
   # 安静模式，布尔，可以减少日志输出
   quiet: <boolean>
   # 截断异常信息，布尔
   traceAllExceptions: <boolean>
   # 记录到syslog使用的facility级别，默认user
   syslogFacility: <string>
   # 输出到指定的文件，而不是syslog中
   path: <string>
   # 默认false，是否追加内容到日志文件中
   logAppend: <boolean>
   # 日志轮转方式，rename / reopen
   logRotate: <string>
   # 日志记录目标，syslog / file ，选择file则必须设置systemLog.path
   destination: <string>
   # 日志时间戳格式，ctime / iso8601-utc / iso8601-local
   # 默认iso8601-local，示例 1969-12-31T19:00:00.000-0500
   timeStampFormat: <string>
   # 配置特定MongoDB组件的日志选项
   # 组件：accessControl / command / control / ftdc / geo / index / network / query /
   #       replication / sharding / storage / storage.journal / write 
   component:
      accessControl:
         verbosity: <int>
      command:
         verbosity: <int>

# 进程管理选项
processManagement:
   # 默认false，是否以daemon方式来启动mongos/mongod，默认不是daemon方式
   # MongoDB的Linux包期望此选项为默认值
   fork: <boolean>
   # PID文件的路径
   pidFilePath: <string>

# 网络选项
net:
   # 监听连接的端口，默认27017
   port: <int>
   # 监听的网络接口，默认0.0.0.0
   bindIp: <string>
   # mongos/mongod允许的最大连接数，默认65536
   maxIncomingConnections: <int>
   # 默认true，对每个客户端请求进行校验，防止插入无效、恶意的BSON到数据库
   wireObjectCheck: <boolean>
   # 默认false，是否启用IPv6支持
   ipv6: <boolean>
   # 在UNIX Domain套接字上监听
   unixDomainSocket:
      # 是否启用
      enabled: <boolean>
      # 套接字路径前缀，默认/tmp
      pathPrefix: <string>
      # 套接字文件权限，默认 0700
      filePermissions: <int>
   # 提供RESTful API的HTTP接口，不要在生产环境使用
   http:
      # 是否启用
      enabled: <boolean>
      # 是否支持JSONP
      JSONPEnabled: <boolean>
      # 是否提供RESTful接口
      RESTInterfaceEnabled: <boolean>
   ssl:
      # SSL的运作模式：disabled禁用；allowSSL服务器互联不使用，允许客户端连接使用；
      #              preferSSL服务器互联默认使用，允许客户端不适用；requireSSL 强制所有连接使用SSL
      mode: <string>
      # 同时包含证书和密钥的.pem文件
      # 如果连接时没有指定--sslCAFile则使用系统CA来验证服务器证书
      PEMKeyFile: <string>
      # 如果.pem加密，这里提供密码
      PEMKeyPassword: <string>
      # 用于集群成员、复制集成员相互认证的pem文件
      clusterFile: <string>
      # 如果.pem加密，这里提供密码
      clusterPassword: <string>
      # 包含了根证书链的.pem文件
      CAFile: <string>
      # 包含了证书吊销列表的.pem文件
      CRLFile: <string>
      # 是否允许客户端不提供证书（单向认证）
      allowConnectionsWithoutCertificates: <boolean>
      # 是否允许使用无效证书（集群中其它服务器）
      allowInvalidCertificates: <boolean>
      # 是否允许 TLS/SSL 证书和主机名不匹配
      allowInvalidHostnames: <boolean>
      # 禁用的入站协议类型TLS1_0、TLS1_1、TLS1_2
      disabledProtocols: <string>
      # 是否启用OpenSSL的FIPS模式
      FIPSMode: <boolean>
   # 是否启用服务器之间，服务器与Shell之间的数据压缩
   compression:
      compressors: <string>  # 压缩器，例如snappy

# 安全选项
security:
   # 对分片集群、复制集中其它成员进行认知的共享密钥所在的文件
   keyFile: <string>
   # 集群的认证方式：keyFile共享密钥文件；sendKeyFile发送共享密钥但是也允许其它节点以X509方式请求本节点
   #              sendX509发送X509但是也允许其它节点以共享密钥方式请求本节点；x509 推荐，仅X509
   clusterAuthMode: <string>
   # 默认disabled，可选disabled。是否启用基于角色的访问控制（RBAC），对应命令行选项 --auth
   authorization: <string>
   # 默认false，3.4新增。允许mongos/mongd接受/创建到其它mongos/mongd的认证/非认证连接
   transitionToAuth: <boolean>
   # 是否启用服务器端的JS执行，默认true。如果禁用，则无法使用$where、db.collection.mapReduce()、db.collection.group()等
   javascriptEnabled:  <boolean>

# 设置MongoDB服务器参数
setParameter:
   <parameter1>: <value1>
   <parameter2>: <value2>

# 存储选项
storage:
   # mongod实例存储数据的位置，默认/data/db 
   dbPath: <string>
   # 默认true，是否在下一次启动时构建未完成的索引
   indexBuildRetry: <boolean>
   # 当mongod以--repair进行修复启动时，使用的工作目录
   repairPath: <string>
   # 是否启用日志，64bit默认true，32bit默认false
   journal:
      # 是否启用
      enabled: <boolean>
      # 允许写入日志的最小间隔，默认100ms
      commitIntervalMs: <num>
   # 是否为每个数据库新建子目录，默认false
   directoryPerDB: <boolean>
   # 每隔多久把数据刷入数据文件中，默认60s，通常不需要修改。如果设置为0从不把内存映射文件刷入磁盘
   syncPeriodSecs: <int>
   # 使用的存储引擎，mmapv1 / wiredTiger / inMemory
   engine: <string>
   # 引擎特定选项
   mmapv1:
      # 是否预分配数据文件的磁盘空间
      preallocDataFiles: <boolean>
      # 名字空间文件的大小，每个集合、索引都被认为是名字空间
      # 默认16MB，允许大概24000个名字空间
      nsSize: <int>
      quota:
         # 是否限制每个数据库能够拥有的数据文件的数量
         enforced: <boolean>
         # 每个数据库的最大数据文件数量，默认8
         maxFilesPerDB: <int>
      # 使用小数据文件，设置为true则减小数据文件的初始大小，且不允许超过512MB
      # 设置为true，同时导致日志文件的最大尺寸从1G变为128MB
      # 可能导致创建大量的数据文件，从而影响性能
      smallFiles: <boolean>
      journal:
         debugFlags: <int>
         commitIntervalMs: <num>
   # 引擎特定选项
   wiredTiger:
      engineConfig:
         # 为所有数据准备的内部缓存的大小，最小256MB，默认RAM /2 - 1GB
         # 避免修改此配置，因为该引擎可以利用OS所有空闲内存作为缓存
         # 使用容器时，配合容器可用内存设置该选项
         cacheSizeGB: <number>
         # 日志的压缩算法 snappy / zlib
         journalCompressor: <string>
         # 是否在不同子目录存放索引、数据
         directoryForIndexes: <boolean>
      collectionConfig:
         # 集合的默认压缩算法 none / snappy / zlib
         # 你可以在创建集合的时候覆盖
         blockCompressor: <string>
      indexConfig:
         # 是否启用索引前缀压缩
         prefixCompression: <boolean>
   # 引擎特定选项
   inMemory:
      engineConfig:
         # 使用的内存量
         inMemorySizeGB: <number>

# 性能剖析选项
operationProfiling: 
   # 超过多少ms，操作被剖析器认为是缓慢的
   slowOpThresholdMs: <int>
   # 剖析模式： off / slowOp / all
   mode: <string>

# 复制集选项
replication:
   # Oplog的大小，对于64bit系统，默认5%可用磁盘空间
   oplogSizeMB: <int>
   # 该实例所属的复制集的名称
   replSetName: <string>
   # 仅mmapv1引擎，是否预抓取索引
   secondaryIndexPrefetch: <string>
   # 设置读关注为majority
   enableMajorityReadConcern: <boolean>
   # 以下子项仅仅用于mongos
   localPingThresholdMs: <int>

# 分片选项
sharding:
   # 当前分片在集群中的角色，configsvr / shardsvr
   clusterRole: <string>
   # 是否对被迁移的Chunk进行归档保存
   archiveMovedChunks: <boolean>
   # 以下子项仅仅用于mongos
   configDB: <string>

# 审计选项
auditLog:
   # 审计日志的目的地 syslog / console / file
   destination: <string>
   # 审计日志格式 JSON / BSON
   format: <string>
   # 审计日志存放路径
   path: <string>
   # 过滤器文档，不匹配的不记录
   filter: <string>

# SNMP监控选项
snmp:
   # 是否作为subagent运行
   subagent: <boolean>
   # 是否作为master运行
   master: <boolean>

# 全文搜索选项
basisTech
   # Basis Technology Rosette Linguistics Platform 安装目录
   basisTech.rootDirectory

# 启动mongod进程，默认数据目录/data/db，端口27017
mongod
# 以守护进程的方式启动，并把日志记录到指定位置
mongod --fork --logpath /var/log/mongodb.log

# 停止服务
use admin
db.shutdownServer()

# 停止服务，方式二
mongod --shutdown

主节点的mongod的停止流程如下：

1. 检查从节点的复制进度
2. 如果没有任何从节点延迟小于10s，mongod会返回一个信息，提示不能停止。要强行停止，可以为shutdown命令提供force参数：
   

   db.adminCommand({shutdown : 1, force : true})

   如果要持续检查指定的时间，在此时间内有从节点跟上复制进度则关闭，跟不上则不关闭，可以执行：

   db.adminCommand({shutdown : 1, timeoutSecs : 5})
   # 或者
   db.shutdownServer({timeoutSecs : 5})

3. 如果由节点延迟小于10s，主节点会Stepdown，并等待从节点跟上复制进度
4. 从节点跟上复制进度，或者60s之后，主节点关闭 

可以指定查询、命令的最长执行耗时：

db.collection.find(...).maxTimeMS(30)
db.runCommand( { maxTimeMS: 45 } )

# 如果查询、命令因为超时而被终止，可以通过db.getLastError() 或者db.getLastErrorObj()得到相关信息

你可以调用

db.killOp(<opId>)

db.currentOp()

你应当总是在受信任的网络中运行MongoDB，使用合理的防火墙策略来阻止非受信任的机器、系统、网络。通常，仅仅应用服务器、监控服务、其它MongoDB组件需要MongoDB的访问权限。

默认情况下，MongoDB的授权系统是关闭的，任何人都可以访问，需要注意。

MongoDB提供了一个用于检查服务器状态、执行查询的HTTP接口，此接口默认是关闭的，不要在生产环境中开启此接口。

避免盲目调整mongos/mongod的连接池大小，以满足你的需要。

connPoolStats

storage.wiredTiger.engineConfig.cacheSizeGB

serverStatus

使用SSD，MongoDB可以获得更好的性能、更高的性价比。 SSD的随机I/O能力可以很好的适应MMAPv1的更新模型。

注意为系统分配Swap，避免内存争用，或者因为OOM导致mongod被杀死。当使用MMAPv1时，其映射数据文件到内存的行为，导致永远不会使用Swap空间。

当面向MongoDB性能低下时，其原因往往和数据库访问策略、硬件、并发操作数有关、错误/不当索引、低效的Schema设计相关。排除了前述可能性之后，数据库可能已经满载运行了，或许需要进行水平扩容。

你应该保证应用的工作集（Working set，最常使用的数据）能够全部装入内存，这样对性能提升有很大帮助，特别是使用MMAPv1引擎时。

某些情况下性能问题是临时的，通常由于突发的高并发导致。

为了确保数据一致性，MongoDB采用了一套锁系统。长时间运行、队列形式的操作可能导致性能降低，因为它们持有锁导致后续请求被迫等待。

要查看锁是否影响了系统性能，执行命令：

db.runCommand( { serverStatus: 1 } )

locks.timeAcquiringMicros /  locks.acquireWaitCount的结果近似的反映了等待某种特定锁模式所消耗的平均时间。

locks.deadlockCount表示锁请求导致死锁的次数。

如果globalLock.currentQueue.total计数总是很高，意味着可能大量的操作在等待一个锁，提示存在影响性能的并发问题。

如果globalLock.totalTime / uptime的比值较高，意味着数据库很长时间处于一个锁状态。

耗时漫长的操作可能由于：

1. 低效的索引
2. 低效的Schema设计
3. 低效的查询语句
4. 内存不足，导致页错误而产生磁盘读操作

MMAPv1引擎使用内存映射文件来存储数据。对于一个尺寸足够大的数据集，MMAPv1会分配尽可能多的系统内存供其使用。

判断内存是否对于数据集来说是足够的并不容易，查看 serverStatus的mem段可以查看MongoDB的内存使用情况。mem.resident记录MongoDB驻留工作集使用的内存，如果该值超过系统可用内存，并且还有很多数据没有映射到内存中，说明达到了系统的最大容量。

mem.mapped字段记录了MongoDB使用的内存映射文件大小，如果此值操作系统内存总大小，意味着某些读操作会触发页面错误而导致磁盘读。

serverStatus.extra_info.page_faults记录了MongoDB发生页面错误的数量。如果此计数快速增加，则可能是：

1. 系统内存过小
2. 正在访问大量数据、扫描整个集合

导致。偶尔发生的页面错误不要紧，但是大量累积的页面错误意味着存在I/O性能问题。

当遇到页面错误的时候，MongoDB可能放弃读锁，这样在换页期间其它数据库进场可以进行读写操作，这种行为提升了吞吐量、并发能力。

处理内存不足的方法是，水平或者垂直扩容。

某些情况下，客户端和数据库之间的连接数会超过服务器的处理能力。serverStatus输出的以下字段可以提供相关信息：

1. globalLock.activeClients，当前正在执行操作、或者排队等待操作的客户端数量
2. connections.current，连接到服务器的客户端数量
3. connections.available，空闲的可以供新客户端使用的连接数

如果并发连接数持续的高，可能系统需要扩容。对于读过载的应用考虑复制集，对于写过载的应用考虑分片集群。

MongoDB本身没有对并发连接数的限制，操作系统本身的限制，例如UNIX，考虑设置ulimit。

MongoDB自带了一个剖析器，用于识别和分析低效的查询、操作。要为某个数据库启用剖析器，执行：

# 0 不启用剖析
# 1 仅仅剖析缓慢操作，设置项slowOpThresholdMs决定了缓慢查询的判断标准
# 2 剖析所有操作
db.setProfilingLevel(1)
# 输出示例：
{"was" : 0, "slowms" : 100, "ok" : 1 }

# 先的命令检查剖析设置
db.getProfilingStatus()

要为整个mongod启用剖析器，使用选项：

mongod --profile 1 --slowms 15

注意，剖析对数据库性能具有负面影响，因而默认是关闭的。你可以针对单个mongod实例、单个数据库进行设置，这些设置不会传播到整个复制集或者分片集群。不支持对整个分片集群设置剖析，你必须针对单个mongod进行设置。

剖析器收集MongoDB写操作、游标、数据库命令的细粒度信息。收集的信息被存放到定长集合

system.profile

show profile

db.system.profile.find( { millis : { $gt : 100 } } )

{
   // 操作类型
   "op" : "query",
   // 操作针对的对象
   "ns" : "test.c",
   // 使用的查询文档，对于insert操作来说，则是插入的文档
   "query" : {
      "find" : "c",
      "filter" : {
         "a" : 1
      }
   },
   // 执行update操作时，使用的更新文档
   "updateobj" :..,
   // query、getmore操作使用的游标ID
   "cursorid" :...,
   // 执行的命令
   "command" : ..,
   // 别名system.profile.nscanned，为了完成操作MongoDB扫描的索引值数量
   "keysExamined" : 2,
   // 别名system.profile.nscannedObjects，为了完成操作MongoDB扫描的文档数量
   "docsExamined" : 2,
   // 仅MMAPv1引擎，为了完成操作，在磁盘上移动文档的数量
   "nmoved" :...,
   // 操作删除的文档数量
   "ndeleted" :...,
   // 操作插入的文档数量
   "ninserted" :...,
   // update操作修改文档的数量
   "nModified" :...,
   // 是否为upsert操作
   "upsert" :...,
   // 如果通过索引不能得到需要的排序，则出现此Stage
   "hasSortStage" : ...,
   "cursorExhausted" : true,
   // 写操作插入的索引键数量
   "keysInserted" : 0,
   // 删除的索引键数量
   "keysDeleted" : 0,
   // 写操作冲突文档数量，所谓冲突即多个update操作尝试修改同一文档的情况
   "writeConflicts" : 0,
   // 让出锁以便其它操作能够进行的次数，这意味着当前操作需要读取不在内存中的数据
   "numYield" : 0,
   // 原来该字段叫lockStats
   "locks" : {
      // 锁类型：{剖析信息}
      // Global 全局锁
      // MMAPV1Journal 该引擎特定的，用于同步日志写操作的锁
      // Database 数据库锁
      // Collection 集合锁
      // Metadata 元数据锁
      // oplog Oplog锁
      "Global" : {
         // 请求锁的次数
         "acquireCount" : {
            // 锁模式：
            // R 共享锁，W 独占锁，r 意向共享锁，w 意向独占锁
            "r" : NumberLong(2)
         }
         "acquireWaitCount" :...,      // 等待获得锁的次数
         "timeAcquiringMicros" :...,   // 累积等待锁消耗的微秒数
         "deadlockCount" :...,         // 等待锁时遭遇死锁的次数
      }
   },
   // 操作返回文档的数量
   "nreturned" : 2,
   // 返回文档的字节长度
   "responseLength" : 108,
   // 从mongod角度来看，操作完整消耗的时间
   "millis" : 0,
   // 执行统计信息，参考执行计划
   "execStats" : {},
   // 操作的时间戳
   "ts" : ISODate("2015-09-03T15:26:14.948Z"),
   // 发起操作的客户端地址
   "client" : "127.0.0.1",
   // 发起操作的应用名称，驱动支持设置应用名称
   "appName" : "MongoDB Shell",
   // 当前会话认证的所有用户的数组
   "allUsers" : [ ],
   // 执行此操作的用户
   "user" : ""
}

需要修改剖析日志的容量时，参考以下步骤：

db.setProfilingLevel(0)
db.system.profile.drop()
db.createCollection( "system.profile", { capped: true, size:4000000 } )
db.setProfilingLevel(1)

# 如果要修改从节点的剖析日志容量，首先需要以standalone模式启动之，然后执行上述修改

透明巨页（Transparent Huge Pages）是一种Linux的内存管理系统，用于减少转译后备缓冲区（Translation Lookaside Buffer ，TLB）的查询成本。由于THP倾向于导致稀疏而非连续的内存访问模式，因而不适合数据库工作负载。

要禁用透明巨页特性，参考：

# Ubuntu
sudo update-rc.d disable-transparent-hugepages defaults
# CentOS
sudo chkconfig --add disable-transparent-hugepages

 大部分类UNIX系统提供了按用户/进程来控制文件、线程、网络连接等系统资源使用数量的手段 —— ulimits。

ulimit的默认值对于MongoDB可能太低了，需要调整。

可以基于Linux下的LVM进行文件系统级的备份/恢复。创建快照的命令示意：

# 针对卷组vg0中的mongodb卷创建一个名为mdb-snap01的快照
# 快照容量100M，存放此快照与文件系统最终状态的diff
lvcreate --size 100M --snapshot --name mdb-snap01 /dev/vg0/mongodb

# 归档压缩
umount /dev/vg0/mdb-snap01
dd if=/dev/vg0/mdb-snap01 | gzip > mdb-snap01.gz

要基于快照恢复，可以执行：

# 在卷组vg0中创建一个名为mdb-new的逻辑卷，大小1G（根据实际MongoDB占用磁盘空间确定）
lvcreate --size 1G --name mdb-new vg0
# 把之前的快照导入到逻辑卷
gzip -d -c mdb-snap01.gz | dd of=/dev/vg0/mdb-new
# 挂载逻辑卷，挂载点直线
mount /dev/vg0/mdb-new /srv/mongodb

命令mongodump/mongorestore实现基于BSON格式的备份与恢复，适合小型数据库。要实现弹性、无缝的备份，建议使用文件系统、块设备级别的快照功能进行备份。

mongodump/mongorestore需要和运行中的mongod进行交互，因而会影响数据库性能。除了网络流量方面的开销外，这两个工具还需要通过内存来读取数据。MongoDB会因此载入很少使用的数据并把常用数据清除出内存。

备份命令示例：

mongodump --host 172.21.2.1 --port 27017   --out /data/backup/
          # 可以限制导出的数据库，甚至集合
          --db cluster --collection corps
          # 如果服务器启用了身份验证，可以指定密码
          --username user --password "passwd" 
          # 在dump期间收集oplog，形成指向特定时间点的备份
          --oplog

恢复命令示例：

mongorestore --host 172.21.2.1 --port 27017 
             # 重做oplog
             --oplogReplay
             # 备份所在位置
             /data/backup/

如果单机mongod禁用了日志，则意外宕机可能导致数据处于不一致状态，启动时报错： Detected unclean shutdown - mongod.lock is not empty。在数据文件目录下会存在非空的 mongod.lock 文件。这种情况下，你需要修复数据库：

1. 备份数据文件目录
2. 以修复模式启动数据库：

   mongod --dbpath /data/db --repair

    

要读取复制集的配置对象，调用

rs.conf()

db.runCommand( { replSetGetConfig: 1 } )

要修改复制集配置，调用

rs.reconfig()

{
  // 复制集的名称，一旦设置，不可更改。必须和配置replication.replSetName或者命令行参数--replSet一致
  _id: <string>,
  // 递增的配置版本号，用于区分复制集配置的修订版
  version: <int>,
  // 选举协议的版本，从3.2开始默认1
  protocolVersion: <number>,
  // 3.4新增，protocolVersion为1默认true，否则默认false。指示{ w: "majority" }是否隐含{ j: true }
  writeConcernMajorityJournalDefault: <boolean>,
  // 指示当前复制集是否用作分片集群的配置服务器
  configsvr: <boolean>,
  // 成员配置文档的数组
  members: [
    {
      // 成员标识符，0-255，一旦设置不得修改
      _id: <int>,
      // 成员主机名，或者host:port，主机名必须可以从任何复制集成员进行DNS解析
      host: <string>,
      // 布尔，用于指示该成员是否为仲裁者
      arbiterOnly: <boolean>,
      // 默认true，mongod是否在此成员上构建索引。仅在添加复制集成员时可以设置，不得改变
      // 在下列条件全部满足时，设置为false可能有用：
      // 1、仅仅使用该成员执行mongodump
      // 2、该成员从不接受查询
      // 3、维护索引的成本让硬件受不了
      // 即使设置为false，也会构建_id索引
      // 设置为false时必须同时设置priority为0
      // 其它成员不能从buildIndexes = false的成员进行复制
      buildIndexes: <boolean>,
      // 如果设置为true，db.isMaster()的输出不包含此成员，阻止读操作转发给该成员
      hidden: <boolean>,
      // 默认1.0，0-100之间，优先级权重，值越高，越有资格被选举为主节点
      priority: <number>,
      // 标签集文档，可以包含任意键值对映射。用于定制读写关注，使其感知数据中心
      tags: <document>,
      // 单位秒，默认0，用于配置延迟从节点
      slaveDelay: <int>,
      // 投票权，默认1，可选0。仲裁者总是1
      votes: <number>
    },
    ...
  ],
  settings: {
    // 默认true，如果true，则允许从节点从其它从节点复制，而不仅仅时主节点
    chainingAllowed : <boolean>,
    // 内部使用，复制集成员需要不断的相互发送心跳，确认可达性
    heartbeatIntervalMillis : <int>,
    // 心跳超时时间，默认10s
    heartbeatTimeoutSecs: <int>,
    // 默认10000ms，用于检测主节点不可用的延迟时间。高取值延长故障转移时间但是降低对不稳定网络的敏感性
    electionTimeoutMillis : <int>,
    // 新选举的主节点，其数据可能不是最新的，此时需要从最新的从节点同步
    // 高取值避免从节点回滚数据的可能，但是延长了故障转移时间
    // 同步完成之前，主节点不接受写请求
    catchUpTimeoutMillis : <int>,
    // 用于定义扩展的写关注值，可以提供数据中心感知，例如：
    // { getLastErrorModes: { eastCoast: { "east": 1 } } } 允许使用写关注：
    // { w: "eastCoast" }，表示要求写操作传播到具有east:1标签的节点上
    getLastErrorModes : <document>,
    // 用于指定默认的写关注
    getLastErrorDefaults : <document>,
    // 此复制集的内部唯一标识，自动创建不可更改
    replicaSetId: <ObjectId>
  }
}

调用

rs.status()

{
    // 复制集名称
    "set" : "replset",
    // 当前时间
    "date" : ISODate("2016-11-02T20:02:16.543Z"),
    // 当前节点的复制状态
    "myState" : 1,
    // 选举发生的次数（本节点知晓的），使用协议版本0时总是返回-1
    "term" : NumberLong(1),
    // 心跳频率
    "heartbeatIntervalMillis" : NumberLong(2000),
    // 用于了解复制信息细节的时间信息
    "optimes" : {
          // 从当前节点角度看，最近一次已经传播到大部分复制集成员的写操作的发生时间
          "lastCommittedOpTime" : {
             "ts" : Timestamp(1478116934, 1),  // 操作发生的时间
             "t" : NumberLong(1)               // 操作发生在那次term
          },
          // 从当前节点角度看，最近一次能满足majority读关注的操作的发生时间
          "readConcernMajorityOpTime" : {
             "ts" : Timestamp(1478116934, 1),
             "t" : NumberLong(1)
          },
          // 从当前节点角度看，最近一次应用到当前节点的操作的发生时间
          "appliedOpTime" : {
             "ts" : Timestamp(1478116934, 1),
             "t" : NumberLong(1)
          },
          // 从当前节点角度看，最近一次应用到当前节点、且已经写入日志的操作的发生时间
          "durableOpTime" : {
             "ts" : Timestamp(1478116934, 1),
             "t" : NumberLong(1)
          }
       },
    // 复制集成员状态
    "members" : [
        {
            "_id" : 0,
            "name" : "m1.example.net:27017",
            // 仅当前节点出现：用于指示当前节点
            "self" : true,
            // 仅非当前节点出现：是否宕机
            "health" : 1,
            // 复制集成员状态
            "state" : 1,
            "stateStr" : "PRIMARY",
            // 此成员已经在线的时间
            "uptime" : 269,
            // 该成员最后一次从oplog应用写操作的时间
            "optime" : {
                        "ts" : Timestamp(1478116934, 1),
                        "t" : NumberLong(1)
            },
            "optimeDate" : ISODate("2016-11-02T20:02:14Z"),
            "infoMessage" : "could not find member to sync from",
            // 选举发生的时间
            "electionTime" : Timestamp(1478116933, 1),
            "electionDate" : ISODate("2016-11-02T20:02:13Z"),
            // 该成员最后一次从oplog应用写操作、且已经写入日志的时间
            "optimeDurable" : {
               "ts" : Timestamp(1478116934, 1),
               "t" : NumberLong(1)
            },
            "optimeDurableDate" : ISODate("2016-11-02T20:02:14Z"),
            // 最后一次该成员发送心跳的时间
            "lastHeartbeat" : ISODate("2016-11-02T20:02:15.619Z"),
            // 最后一次从该成员收到心跳的时间，与上一字段的差值体现了两节点之间的网络延迟
            "lastHeartbeatRecv" : ISODate("2016-11-02T20:02:14.787Z"),
            // PING该节点消耗的时间
            "pingMs" : NumberLong(0),
            // 该节点的复制源
            "syncingTo" : "m1.example.net:27018",
            // 该节点使用的复制集配置版本号
            "configVersion" : 1
        }
    ],
    "ok" : 1
}

成员状态的含义参考复制集成员状态。

在生产环境下部署复制集，应当保证以下前置条件：

1. 仅可能把mongod部署在不同的物理机器上。如果使用虚拟机，应当使虚拟机对应不同的物理机器。应当确保物理机器之间有冗余电路、冗余网络路径
2. 保证所有节点可以相互通信

配置文件添加复制集配置：

replication:
  replSetName: rs0

创建三成员复制集：

# 创建三个mongod实例
docker run --name mongo-00 --network local --ip 172.21.0.100 -d  docker.gmem.cc/mongo --config /etc/mongod.conf
docker run --name mongo-01 --network local --ip 172.21.0.101 -d  docker.gmem.cc/mongo --config /etc/mongod.conf
docker run --name mongo-02 --network local --ip 172.21.0.102 -d  docker.gmem.cc/mongo --config /etc/mongod.conf

启动所有实例，然后在其中一个实例上，打开MongoDB Shell，执行：

rs.initiate( {
   _id : "rs0",
   members: [ { _id : 0, host : "172.21.0.100:27017" } ]
})

现在可以执行

rs.conf()

rs.add("172.21.0.101:27017")
rs.add("172.21.0.102:27017")

现在调用

rs.status()

注意以下几点：

1. 每个复制集最多7个投票成员，如果已经有7个成员，再添加成员必须设置votes=0，或者移除既有成员的投票权
2. 可以添加先前被移除的成员，如果该成员的数据没有被删除且足够新，它有可能跟得上oplog的节奏而不需要完全同步
3. 如果你拥有既有成员的足够新的数据备份，拷贝备份到新成员对应dbPath目录下，可以快速添加新成员

以类似创建上面三成员的方式，再创建一个成员，启动后，在既有成员节点上执行：

rs.addArb("172.21.0.103:27017")

可以执行命令：

rs.remove("172.21.0.102:27017")

或者：

cfg = rs.conf()
cfg.members.splice(2,1)
rs.reconfig(cfg)

cfg = rs.conf()
cfg.members[0].host = "172.21.0.105"
rs.reconfig(cfg) 

cfg = rs.conf()

# 设置优先级，范围0-1000，非投票节点的优先级必须是0
cfg.members[0].priority = 0.5
# 设置优先级为0可以阻止它成为主节点
cfg.members[1].priority = 0

# 隐藏成员对客户端不可见， isMaster的输出中不包含
cfg.members[0].hidden = true

# 配置复制延迟
cfg.members[0].slaveDelay = 3600

# 禁用投票权
cfg.members[4].votes = 0

# 设置标签集
cfg.members[1].tags = { "dc": "east", "use": "reporting" }

# 必须重新配置才能生效
# 注意，下面的方法会导致主节点step down然后触发选举，step down期间MongoDB会关闭所有客户端连接
# 这可能耗时10-20秒
rs.reconfig(cfg)

这类环境下，你可能没有足够多的机器可用，只需要在命令行指定合适的端口、数据库路径、参与的复制集名称，就可以在一台机器上部署属于多个复制集的mongod：

mongod --port 27010 --dbpath /data/rs0-0 --replSet rs0 --smallfiles --oplogSize 128
mongod --port 27011 --dbpath /data/rs0-1 --replSet rs0 --smallfiles --oplogSize 128
mongod --port 27012 --dbpath /data/rs0-2 --replSet rs0 --smallfiles --oplogSize 128

通过MongoDB Shell连接时，指定端口即可连接到不同实例：

mongo --port 27010

注意以下几点：

1. 网络安全性：保证成员之间、客户端与复制集之间流量的安全性。手段包括VPN、防火墙配置、启用MongoDB认证和授权机制
2. 使用标签集实现数据中心感知 
3. 最好能保证某个数据中心完全不可用时，复制集仍然能够工作
4. 不要超过7个投票成员

要对复制集成员进行维护，一般性流程如下：

1. 首先对各从节点执行维护，最后对主节点进行维护
2. 对于每一个节点，执行：
   1. 以独立模式重启mongod，对于主节点要stepDown
   2. 在独立模式运行的mongod下执行维护任务
   3. 以复制集成员方式重新启动mongod 

oplog本质上是一个定长集合，默认的尺寸通常够用。可能需要增大oplog的场景例如：执行影响大量数据的update操作。

如果要修改复制集的oplog，你必须轮流对每个成员进行操作：

1. 将被操作成员切换到独立运行模式：
   1. 如果该成员是主节点，一定要通过

      rs.stepDown()

      将其优雅的变为从节点
   2. 调用

      db.shutdownServer()

      关闭从节点
   3. 不带--replSet参数、以不同端口重新启动该成员
2.  可选的，创建oplog的备份：

   mongodump --db local --collection 'oplog.rs' --port 37017

    
3. 以新尺寸创建oplog集合：
   

   # 或者 db = db.getSiblingDB('local')
   use local
   # 创建一个临时集合，存放oplog集合的内容
   db.temp.drop()
   # 备份oplog，以自然反序排列（最新条目排在最前）
   db.temp.save( db.oplog.rs.find( { }, { ts: 1, h: 1 } ).sort( {$natural : -1} ).limit(1).next() )
   
   # 删除oplog
   db.oplog.rs.drop()
   
   # 重建oplog
   db.runCommand( { create: "oplog.rs", capped: true, size: (2 * 1024 * 1024 * 1024) } )
   
   # 导入临时集合中最后（最新）的oplog条目
   db.oplog.rs.save( db.temp.findOne() ) 

4. 以复制集成员的方式重新启动该节点

要强制某个从节点成为主节点，你可以将其优先级调为最高；类似的，优先级设置为0则可以让从节点永远不能成为主节点。