Elasticsearch是一个基于Apache Lucene的全文检索和分析引擎，可以扩容到上百台服务器，处理PB级结构化/非结构化数据。

ES的应用场景举例：

1. 支持在线搜索、自动完成（搜索建议）功能
2. 作为ELK栈的一部分，收集、聚合、分析日志/事务数据
3. 海量数据的即席分析

Elasticsearch 尽可能地屏蔽了分布式系统的复杂性，它在后台自动执行的操作包括：

1. 分配文档到不同的容器或分片中，文档可以储存在一个或多个节点中
2. 按集群节点来均衡分配这些分片，从而对索引和搜索过程进行负载均衡
3. 复制每个分片以支持数据冗余，从而防止硬件故障导致的数据丢失
4. 将集群中任一节点的请求路由到存有相关数据的节点
5. 集群扩容时无缝整合新节点，重新分配分片以便从离群节点恢复

ES是一个准实时（Near Realtime）的搜索平台，从你开始索引一个文档，到该文档可以被搜索，有个较小的延迟，通常秒级。

唯一的依赖是JDK，请预先安装好JDK8（建议1.8.0_131+），然后：

wget https://artifacts.elastic.co/downloads/elasticsearch/elasticsearch-6.2.3.tar.gz
tar xzf elasticsearch-6.2.3.tar.gz
mv elasticsearch-6.2.3 6.2.3

# 启动ES，-d以守护进程方式运行，默认端口9200
./elasticsearch -d
# 指定集群和节点名称
./elasticsearch -Ecluster.name=es.gmem.cc -Enode.name=es-10.gmem.cc

# 停止ES
kill -SIGTERM $ES_PID

所有节点、客户端都应该使用一样的JDK版本。

ES的Docker镜像基于CentOS:7。相关镜像的列表参考：https://www.docker.elastic.co/。

镜像分为三种风格：basic包含基本的X-Pack特性，自动激活免费License；platinum包含全部X-Pack特性，默认30天试用；oss不支持X-Pack，仅仅包含ES。

执行下面的命令拉取镜像：

docker pull docker.elastic.co/elasticsearch/elasticsearch:6.2.3
docker pull docker.elastic.co/elasticsearch/elasticsearch-platinum:6.2.3
docker pull docker.elastic.co/elasticsearch/elasticsearch-oss:6.2.3

参考如下命令部署容器：

docker run -p 9200:9200 -p 9300:9300 -e "discovery.type=single-node" docker.elastic.co/elasticsearch/elasticsearch:6.2.3

内核参数vm.max_map_count至少要增大到262144：

sysctl -w vm.max_map_count=262144

参考kubernetes-elasticsearch-cluster搭建集群。注意点：

1. ES的Pod需要超级用户权限运行init容器，避免设置某些VM选项。因此你需要以--allow-privileged选项运行kubelet
2. ES_JAVA_OPTS的默认值为-Xms256m -Xmx256m，非常小。你可以按需调整
3. 数据节点Pod默认在一个emptyDir中存储数据，请根据实际情况修改
4. PROCESSORS的默认值为1，如果需要调整，请设置resources.limits.cpu、livenessProbe
5. 支持1.9.3+版本的K8S

从下面的仓库下载K8S资源定义文件：

git clone https://github.com/pires/kubernetes-elasticsearch-cluster.git es
cd es

docker pull quay.io/pires/docker-elasticsearch-kubernetes:6.2.2_1
docker tag quay.io/pires/docker-elasticsearch-kubernetes:6.2.2_1 docker.gmem.cc/elasticsearch-kubernetes:6.2.2
docker push docker.gmem.cc/elasticsearch-kubernetes:6.2.2

docker pull busybox:1.27.2
docker tag busybox:1.27.2 docker.gmem.cc/busybox:1.27.2
docker push docker.gmem.cc/busybox:1.27.2

# Master节点服务
kubectl create -f es-discovery-svc.yaml
# Data节点服务
kubectl create -f es-svc.yaml
# Master节点的Deployment，默认3个Replica，init容器调用sysctl
kubectl create -f es-master.yaml
# 等待所有Master节点就绪
kubectl -n dev rollout status -f es-master.yaml
# Client节点的Deployment，默认2个Replica，init容器调用sysctl
kubectl create -f es-client.yaml
# 等待所有Client节点就绪
kubectl rollout status -f es-client.yaml

# 数据节点，使用本地目录
kubectl create -f es-data.yaml
kubectl rollout status -f es-data.yaml

# 基于SS的数据节点（推荐）
kubectl create -f stateful/es-data-svc.yaml
kubectl create -f stateful/es-data-stateful.yaml

资源规格定义如下：

apiVersion: v1
kind: Service
metadata:
  name: elasticsearch-discovery
  namespace: dev
  labels:
    component: elasticsearch
    role: master
spec:
  selector:
    component: elasticsearch
    role: master
  ports:
  - name: transport
    port: 9300
    protocol: TCP

apiVersion: v1
kind: Service
metadata:
  name: elasticsearch
  namespace: dev
  labels:
    component: elasticsearch
    role: client
spec:
  selector:
    component: elasticsearch
    role: client
  ports:
  - name: http
    port: 9200

apiVersion: apps/v1beta1
kind: Deployment
metadata:
  name: es-master
  namespace: dev
  labels:
    component: elasticsearch
    role: master
spec:
  replicas: 3
  template:
    metadata:
      labels:
        component: elasticsearch
        role: master
    spec:
      initContainers:
      - name: init-sysctl
        image: docker.gmem.cc/busybox:1.27.2
        command:
        - sysctl
        - -w
        - vm.max_map_count=262144
        securityContext:
          privileged: true
      containers:
      - name: es-master
        image: docker.gmem.cc/elasticsearch-kubernetes:6.2.2
        env:
        - name: NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: CLUSTER_NAME
          value: gmemes
        - name: NUMBER_OF_MASTERS
          value: "2"
        - name: NODE_MASTER
          value: "true"
        - name: NODE_INGEST
          value: "false"
        - name: NODE_DATA
          value: "false"
        - name: HTTP_ENABLE
          value: "false"
        - name: ES_JAVA_OPTS
          # ES要求堆最大最小值一样
          value: -Xms256m -Xmx256m
        - name: PROCESSORS
          valueFrom:
            resourceFieldRef:
              resource: limits.cpu
        resources:
          limits:
            cpu: 1
        ports:
        - containerPort: 9300
          name: transport
        livenessProbe:
          tcpSocket:
            port: transport
        volumeMounts:
        - name: storage
          mountPath: /data
      volumes:
          # Pod第一次调度到节点上创建一个空白目录，除非重新调度到其它节点，不会重新创建
          - emptyDir:
              medium: ""
            name: "storage"

apiVersion: apps/v1beta1
kind: Deployment
metadata:
  name: es-client
  namespace: dev
  labels:
    component: elasticsearch
    role: client
spec:
  replicas: 2
  template:
    metadata:
      labels:
        component: elasticsearch
        role: client
    spec:
      initContainers:
      - name: init-sysctl
        image: docker.gmem.cc/busybox:1.27.2
        command:
        - sysctl
        - -w
        - vm.max_map_count=262144
        securityContext:
          privileged: true
      containers:
      - name: es-client
        image: docker.gmem.cc/elasticsearch-kubernetes:6.2.2
        env:
        - name: NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: CLUSTER_NAME
          value: gmemes
        - name: NODE_MASTER
          value: "false"
        - name: NODE_DATA
          value: "false"
        - name: HTTP_ENABLE
          value: "true"
        - name: ES_JAVA_OPTS
          value: -Xms256m -Xmx256m
        - name: NETWORK_HOST
          value: _site_,_lo_
        - name: PROCESSORS
          valueFrom:
            resourceFieldRef:
              resource: limits.cpu
        resources:
          limits:
            cpu: 1
        ports:
        - containerPort: 9200
          name: http
        - containerPort: 9300
          name: transport
        livenessProbe:
          tcpSocket:
            port: transport
        readinessProbe:
          httpGet:
            path: /_cluster/health
            port: http
          initialDelaySeconds: 20
          timeoutSeconds: 5
        volumeMounts:
        - name: storage
          mountPath: /data
      volumes:
          - emptyDir:
              medium: ""
            name: storage

apiVersion: v1
kind: Service
metadata:
  name: elasticsearch-data
  namespace: dev
  labels:
    component: elasticsearch
    role: data
spec:
  ports:
  - port: 9300
    name: transport
  clusterIP: None
  selector:
    component: elasticsearch
    role: data

apiVersion: apps/v1beta1
kind: StatefulSet
metadata:
  name: es-data
  namespace: dev
  labels:
    component: elasticsearch
    role: data
spec:
  serviceName: elasticsearch-data
  replicas: 5
  template:
    metadata:
      labels:
        component: elasticsearch
        role: data
    spec:
      affinity:
        podAntiAffinity:
          # 不得存在role=data的其它pod
          preferredDuringSchedulingIgnoredDuringExecution:
          - weight: 100
            podAffinityTerm:
              labelSelector:
                matchExpressions:
                - key: role
                  operator: In
                  values:
                  - data
              # 当前节点上
              topologyKey: kubernetes.io/hostname
      initContainers:
      - name: init-sysctl
        image: docker.gmem.cc/busybox:1.27.2
        command:
        - sysctl
        - -w
        - vm.max_map_count=262144
        securityContext:
          privileged: true
      containers:
      - name: es-data
        image: docker.gmem.cc/elasticsearch-kubernetes:6.2.2
        env:
        - name: NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: NODE_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        - name: CLUSTER_NAME
          value: gmemes
        - name: NODE_MASTER
          value: "false"
        - name: NODE_INGEST
          value: "false"
        - name: HTTP_ENABLE
          value: "false"
        - name: ES_JAVA_OPTS
          value: -Xms256m -Xmx256m
        - name: PROCESSORS
          valueFrom:
            resourceFieldRef:
              resource: limits.cpu
        resources:
          limits:
            cpu: 1
        ports:
        - containerPort: 9300
          name: transport
        livenessProbe:
          tcpSocket:
            port: transport
          initialDelaySeconds: 20
          periodSeconds: 10
        volumeMounts:
        - name: es-data-pvc
          mountPath: /data
  volumeClaimTemplates:
  - metadata:
      name: es-data-pvc
      namespace: dev
    spec:
      storageClassName: rook-block
      accessModes: [ ReadWriteOnce ]
      resources:
        requests:
          storage: 4Gi 

helm repo add gmem https://chartmuseum.gmem.cc
helm install --name=es --namespace=kube-system gmem/elasticsearch 

# 检查集群健康状态
curl http://es-elasticsearch.kube-system.svc.k8s.gmem.cc:9200/_cat/health?v

一系列节点的集合，它们在整体上持有完整的数据集，提供联合的索引（Federated indexing），并在整体上对外提供搜索功能。

每个集群以名字来识别，默认名字elasticsearch，每个节点只能属于单个集群。如果部署多套集群，注意确保集群名字不重复。

节点是集群中的单个服务器。节点的唯一标识也是名称，默认是节点启动时随机生成的UUID。

当一个节点被选举成为主节点时， 它将负责管理集群范围内的所有变更，例如增加、删除索引，或者增加、删除节点等。 而主节点并不需要涉及到文档级别的变更和搜索等操作，所以当集群只拥有一个主节点的情况下，即使流量的增加它也不会成为瓶颈。 任何节点都可以成为主节点。

用户可以将请求发送到 集群中的任何节点 ，包括主节点。每个节点都知道任意文档所处的位置，并且能够将请求直接转发到存储所需文档的节点。

索引是一系列具有相近特性的文档的集合。例如客户数据可以对应一个索引，商品目录可以对应另一个索引。ES中的索引类似于RDBMS中的表。索引的唯一标识是名称，名称必须全小写。

当索引作为动词使用时，表示将一个文档存储到索引（名词）中，是其支持全文检索的过程。

Mapping用于描述数据的每个字段如何存储。ES自动生成一个_all字段，其类型为字符串，属于全文字段。ES会根据文档内容进行猜测，动态产生一个映射。

Elasticsearch 支持 如下简单域类型：

1. 字符串：string
2. 整数：byte, short, integer, long
3. 浮点数：float, double
4. 布尔型：boolean
5. 日期：date

当你索引一个包含新字段的文档时，ES自动进行动态映射。JSON类型到上述类型的转换比较直白，除了要注意2018-04-03这样的字符串会被自动解析为date类型。

除了上述的简单标量类型外，JSON中的null、数组、对象，都是被ES支持的。

空字段不会被索引，包括：null、null、[ null ]

Lucene不理解嵌套对象，Lucene文档由一组键值对的列表构成。为了支持复杂类型的处理，ES必须对文档进行扁平化。

多值域以数组形式表示，数组的元素类型必须相同。尽管提取文档时，数组元素顺序不会丢失，但是索引是以无序的多值域形式进行的：

{
    "followers": [
        { "age": 35, "name": "Mary White"},
        { "age": 26, "name": "Alex Jones"},
        { "age": 19, "name": "Lisa Smith"}
    ]
}
# 被扁平化为
{
    # 扁平化后，age和name之间的关系丢失
    # 如果要查询是否有名为alex的26岁的follower，需要使用嵌套对象
    "followers.age":    [19, 26, 35],
    "followers.name":   [alex, jones, lisa, smith, mary, white]
}

类似的，为了让ES有效的索引嵌套对象，同样需要扁平化：

{
    "tweet":            [elasticsearch, flexible, very],
    "user.id":          [@johnsmith],
    "user.gender":      [male]
}?

Analysis是处理全文字段，使其可以被搜索的过程。分析包含下面的步骤：

1. 首先，将一块文本分成适合于倒排索引的独立的词条
2. 之后，将这些词条统一化为标准格式以提高它们的“可搜索性”

分析器负责执行上面的工作。 分析器实际上是将三个功能封装到了一个包里：

1. 字符过滤器：首先，字符串按顺序通过每个字符过滤器 。他们的任务是在分词前整理字符串。一个字符过滤器可以用来去掉HTML，或者将 & 转化成and
2. 分词器：其次，字符串被分词器分为单个的词条。一个简单的分词器遇到空格和标点的时候，可能会将文本拆分成词条
3. Token过滤器：最后，词条按顺序通过每个Token过滤器 。这个过程可能会：
   1. 改变词条，例如小写化?
   2. 删除词条，例如像 a， and， the这样的无用词
   3. 增加词条，例如像像 jump 和 leap 这种同义词

ES提供了开箱即用的字符过滤器、分词器、Token过滤器，它们可以自由的组合成分析器，满足不同应用场景。

1. 当索引一个文档时，它的全文域被分析成词条以用来创建倒排索引
2. 当在全文字段上执行搜索时，查询字符串也需要类似的分析过程

当查询一个精确值字段时，分析器不会介入。

当ES在你的文档中检测到一个新的字符串域 ，它会自动设置其为一个全文字符串域，使用标准分析器对它进行分析。某些情况下你可能需要改变此默认行为：

1. 你想使用一个不同的分析器，适用于你的数据使用的语言
2. 你想要一个字符串域就是一个精确值，不需要分析

可以通过自定义映射来满足上述需求。

总体来说，ES中的字段可以分为精确值、全文两个大类。

精确值包括日期、数字，字符串也可以表示精确值。精确值是大小写敏感的。精确值很容易查询，它要么匹配，要么不匹配查询条件。

查询全文字段则要复杂的多，通常不会对全文字段进行精确匹配查询。全文字段匹配查询条件时有个相关度的概念，表现为分数（Scoure）。搜索引擎应该能够识别缩写、词根、同义词，并给出适当的相关度。

对全文检索的支持依赖于分析，在分析之后需要创建倒排索引。

ES使用一种称为倒排索引的结构来支持快速的全文检索。

倒排索引的结构类似于RDBMS的位图索引，对于索引中出现的任何不重复的词的标准模式，生成包含该此的文档列表。标准模式提取了词干、同义词。

默认情况下，查询返回结果是按相关性倒序排列的。每个文档都有相关性评分，用一个正浮点数字段 _score 来表示 。 _score 的评分越高，相关性越高。

查询语句会为每个文档生成一个 _score 字段。评分的计算方式取决于查询类型。不同的查询语句用于不同的目的：fuzzy 查询会计算与关键词的拼写相似程度。terms 查询会计算找到的内容与关键词组成部分匹配的百分比。

通常我们说的 relevance 是我们用来计算全文本字段的值相对于全文本检索词相似程度的算法。ES的相似度算法被定义为检索词频率/反向文档频率， 包括以下内容：

1. 检索词频率：检索词在该字段出现的频率？出现频率越高，相关性也越高
2. 反向文档频率：每个检索词在索引中出现的频率？频率越高，相关性越低
3. 字段长度准则：字段本身的长度是多少？长度越长，相关性越低

Type用于对索引进行分区/分类，允许你在一个索引里存储不同类型的文档。从6.0开始Type被弃用。

可被索引的、最小的信息单元。以JSON形式表示。?

一个索引的数据量可以超过硬盘的物理容量限制，ES使用分片来突破此限制。每个分片都是独立的、完整功能的“子索引”

创建索引时，你可以指定分片的数量。但是，分片如何分配给节点，分片中的文档如何被聚合以响应查询，完全由ES管理，对用户透明。

每个分片可以创建0-N个副本，这样可以避免单点故障。

ES的API通过JSON over RESTful HTTP暴露。除非特别强调，所有API都遵守本节描述的约定。

大部分支持index参数的API，都能够跨越多个索引执行。你可以用以下形式指定多个索引：

# 枚举
test1,test2,test3
# 所有索引
_all
# 使用通配符
test*
# 排除索引
-test3

所有支持多索引的API，均识别以下URL参数：

指定索引名时，你可以提供一些特殊符号，以匹配时间序列索引集中的一个范围，这样可以避免全集群扫描过滤。

几乎所有支持index参数的API，均可以指定如下格式的索引名：

<static_name{date_math_expr{date_format|time_zone}}>
# static_name 索引名中固定的部分
# date_math_expr 动态计算为时间点的表达式
# date_format 日期展示格式，默认YYYY.MM.dd
# time_zone 时区，默认UTC

示例：

运算符：

+1d

-1d

/d

/h

now-1h/d

日期字段：y年、M月、w周、d日、h时、m分、s秒

REST参数（使用HTTP时对应URL参数）使用小写+下划线的风格。

某些查询/API支持非精确的“模糊查询”，你可以指定fuzziness参数。

当针对text或keyword字段进行模糊查询时，“模糊”被解释为编辑距离（Levenshtein Edit Distance）——为了让一个字符串变为另一个，所需改变的字符个数。

某些库不支持非POST请求的请求体，此时你可以将请求体作为source查询参数传递。

需要同时传递参数source_content_type来指定内容类型，例如application/json。

必须通过请求头Content-Type来设置请求体格式，大部分API支持 JSON, YAML, CBOR,SMILE这些格式。批量/多搜索API支持NDJSON,JSON,SMILE。

curl http://localhost:9200/_cat/health?v
# status取值含义：
# green   一切正常，集群功能完整
# yellow  所有数据可用，但是某些副本分片（Replica）没有分配。集群功能完整
# red    某些数据不可用，存在没有运行的主分片

// curl http://es-elasticsearch.kube-system.svc.k8s.gmem.cc:9200/_nodes/os?pretty

{
  "_nodes" : {
    "total" : 12,
    "successful" : 12,
    "failed" : 0
  },
  "cluster_name" : "es",
  "nodes" : {
    "CmHIMj5aReqUPXL4yglVjQ" : {
      "name" : "es-client-695458dd5c-4dt26",
      "transport_address" : "172.27.208.114:9300",
      "host" : "172.27.208.114",
      "ip" : "172.27.208.114",
      "version" : "6.2.4",
      "build_hash" : "ccec39f",
      "roles" : [
        "ingest"
      ],
      "os" : {
        "refresh_interval_in_millis" : 1000,
        "name" : "Linux",
        "arch" : "amd64",
        "version" : "4.15.18-041518-generic",
        // 可用的CPU数量
        "available_processors" : 4,
        // ES可用的CPU数量
        "allocated_processors" : 1
      }
    }
  }
}

# PUT /index_name/_settings
{
   "number_of_replicas" : 2
}

默认副本份数是1，要为将来创建的索引修改副本份数，执行：

# 未来创建的以fluentd开头的索引，副本份数为0

curl -XPUT "localhost:9200/_template/logstash_template" -H 'Content-Type: application/json' -d'
{
  "index_patterns": ["fluentd*"],
  "settings": {
    "number_of_replicas": 0
  }
}
'

你可以使用 analyze API 来看文本是如何被分析的：

# GET /_analyze
{
  "analyzer": "standard",
  "text": "Text to analyze"
}

使用_mapping API可以获取1-N个索引的1-N个字段的映射信息：

# 获取索引gb的tweet（文档）类型的映射信息
# GET /gb/_mapping/tweet

{
   "gb": {
      "mappings": {
         "tweet": {
            # 字段列表
            "properties": {
               "date": {
                  "type": "date",
                  "format": "strict_date_optional_time||epoch_millis"
               },
               "name": {
                  "type": "string"
               },
               "tweet": {
                  "type": "string"
               },
               "user_id": {
                  "type": "long"
               }
            }
         }
      }
   }
}

# 具有内嵌对象的文档的映射形式
{
  "gb": {
    "tweet": { 
      "properties": {
        "tweet":            { "type": "string" },
        # 内嵌文档
        "user": { 
          "type":             "object",
          "properties": {
            "id":           { "type": "string" },
            # 内嵌文档
            "name":   { 
              "type":         "object",
              "properties": {
                "first":    { "type": "string" },
                "last":     { "type": "string" }
              }
            }
          }
        }
      }
    }
  }
}

_validate 可以用来验证查询是否合法：

# GET /gb/tweet/_validate/query
# 显示查询不合法的原因
# GET /gb/tweet/_validate/query?explain
{
   "query": {
      "tweet" : {
         "match" : "really powerful"
      }
   }
}

curl -X PUT http://localhost:9200/media?pretty

{
  "acknowledged" : true,
  "shards_acknowledged" : true,
  "index" : "media"
}

尽管在很多情况下基本域数据类型已经够用，但你经常需要为单独域自定义映射 ，特别是字符串域。自定义映射允许你执行下面的操作：

1. 全文字符串域和精确值字符串域的区别
2. 使用特定语言分析器
3. 优化域以适应部分匹配
4. 指定自定义数据格式

指定字段映射时，最重要的属性是type，对于非string字段，通常仅仅需要设置type。

首次创建一个索引时，你可以指定自定义映射，以后，你可以使用_mapping API创建新字段的映射，或者修改现有字段的映射。注意一个限制：不能把字段从analyzed修改为not_analyzed。

首次创建索引时指定映射的例子：

# PUT /gb 
{
  "mappings": {
    "tweet" : {
      "properties" : {
        "tweet" : {
          "type" :    "string",
          # analyzed 设置为全文字段；not_analyzed 设置为精确值字段；no 不索引此字段，不支持检索
          "index" : "analyzed",
          # 分析器，默认standard
          "analyzer": "english"
        },
        "date" : {
          "type" :   "date"
        },
        "name" : {
          "type" :   "string"
        },
        "user_id" : {
          "type" :   "long"
        }
      }
    }
  }
}

修改某个文档类型的某个字段的映射的例子：

# PUT /gb/_mapping/tweet
{
  "properties" : {
    "tag" : {
      "type" :    "string",
      "index":    "not_analyzed"
    }
  }
} 

curl http://localhost:9200/_cat/indices?v
# health status index uuid                   pri rep docs.count docs.deleted store.size pri.store.size
# yellow open   media EGuJhl4oSMy-FAhgK0bPJQ   5   1          0            0      1.1kb          1.1kb
# 由于没有额外的Replica，存在单点风险，因此yellow   包含5个分片，副本份数1

插入一个文档：

curl -X PUT 'localhost:9200/customer/_doc/1?pretty' -H 'Content-Type: application/json' -d'{"name":"Alex"}'

{
  "_index" : "customer",   # 文档所在的索引
  "_type" : "_doc",        # 文档的类型，不同规格的文档可以共享类似的Schema，这些文档放在同一个索引中，以type区分
  "_id" : "1",             # 文档标识符，从URL参数获得
  "_version" : 1,          # 文档版本号
  "result" : "created",
  "_shards" : {            # 索引操作的复制处理情况
    "total" : 2,           # 有多少分片（包括主分片、复制分片）执行了索引操作
    # 成功完成索引操作的分片个数，至少为1才意味着索引操作成功。默认情况下仅主分片成功后就会返回
    "successful" : 1,      
    "failed" : 0           
  },
  "_seq_no" : 0,
  "_primary_term" : 1
}

使用相同URL再次PUT，则对标识符为1的文档进行替换（Reindex）操作。

插入文档时，可以不显式指定ID，ES会自动随机生成一个：

POST /customer/_doc?pretty ...

如果索引文档时，目标索引不存在，则：

1. 自动创建索引，设置选项action.auto_create_index=false，可以禁用
2. 自动创建一个类型映射，设置选项index.mapper.dynamic=false，可以禁用

每个被索引的文档都具有对应的版本号，此版本号作为响应的一部分返回。默认情况下，索引从1开始，每次更新（即使没有做任何改变）、删除操作后增1。

请求可以直接指定版本号，这种情况下ES自动进行乐观并发控制：PUT index_name/_doc/1?version=2。乐观并发控制的典型应用场景是读后更新。

版本化是完全实时的，不受检索操作的准实时性影响。如果不提供version参数，则ES不对操作进行版本检查。

版本号可以存放在ES外部，要启用此特性，设置version_type=external。这种情况下，请求参数中的版本号会和当前被索引的文档中的版本号进行比较，如果请求中的版本号大则新文档被存储、索引。

指定

op_type=create

默认情况下，文档ID的哈希值决定了它被存放到哪个分片上。你可以使用请求参数

routing

根据路由的结果，索引操作在相应的主分片（所在的节点）上执行。当主分片的索引操作完成后，更新操作复制到可用的从分片。

为了提升可靠性，ES允许配置为必须等待一定数量的分片的写操作完成，在此之前，请求必须等待、重试，或者超时。默认情况下只需要等待主分片，即index.write.wait_for_active_shards=1。你也可以针对请求来设置wait_for_active_shards参数。设置为all则需要等待所有分片操作完成。

执行索引操作时，主分片可能处于不可用状态，默认情况下，ES会等待1分钟，此超时时间可以通过请求参数timeout定制。

除了插入/替换文档之外，我们还可以进行更新操作。注意，实际上ES是不支持In-place更新的，它仅仅是把更新信息merge到原文档中，然后替换掉原文档。示例：

curl -XPOST 'localhost:9200/customer/_doc/1/_update?pretty' -H 'Content-Type: application/json' -d'
{
  # 可以指定一个需要merge from的文档
  "doc": { "name": "Wong", "age": 30 }
  # 也可以指定一段脚本
  "script" : "ctx._source.age += 1"
}
' 

这类API允许基于ID来取得JSON格式的文档：

curl http://localhost:9200/customer/_doc/1?pretty

{
  "_index" : "customer",
  "_type" : "_doc",
  "_id" : "1",
  "_version" : 4,
  "found" : true,
  "_source" : {           # 文档的完整JSON
    "name" : "Alex"
  }
}

你也可以使用HEAD方法来检查目标文档是否存在：HEAD customer/_doc/id

默认情况下get操作是实时的，不受到索引刷新率的影响。

如果所请求的文档已经更新，但是尚未刷新，则此API会即席的发起一次刷新操作。设置请求参数realtime=false禁用此自动刷新行为。

默认情况下此API获取源文档的所有内容，即_source字段。设置_source=false则不返回源文档的任何内容。

如果需要返回某些字段，使用_source_include请求参数；如果需要排除某些字段，使用_source_exclude字段，示例：

# 可以使用通配符
_source_include=*.id&_source_exclude=entities
# 如果仅仅使用include，可以直接简写为_source
_source=*.id,retweeted

要仅仅返回响应文档的_source字段，使用请求：customer/_doc/1/_source

如果索引文档时使用routing来指定路由，则提取文档时必须传入相同的routing参数。

使用参数preference，可以指定在什么分片上提取文档。默认值是随机选取分片。取值_primary则仅仅在主分片上提取，取值_local则尽可能在本地分配的分片上提取。

分片副本份数越多，则操作的性能越好。

使用参数refresh=true，可以在提取之前刷新相关的分片。使用此参数时要注意对系统性能的潜在影响。

传递version参数，则仅在当前文档版本号匹配时，才返回。

使用mget API可以同时提取多个文档：

# GET /_mget
{
   "docs" : [
      {
         "_index" : "website",
         "_type" :  "blog",
         "_id" :    2
      },
      {
         "_index" : "website",
         "_type" :  "pageviews",
         "_id" :    1,
         "_source": "views"
      }
   ]
}
# 其它变体
# GET /index_name/_mget

# 如果索引、类型都相同，则仅指定一个ids数组即可
# GET /index_name/type/_mget
{
    "ids" : [ "2", "1" ]
}

返回值包含一个docs数组

根据ID来删除一个已被索引的文档：

curl -X DELETE 'localhost:9200/customer/_doc/1?pretty' 

版本化、路由、分布式、刷新、超时类似于索引文档。

可以将匹配查询条件的文档删除：

curl -X POST "/twitter/_delete_by_query" -H 'Content-Type: application/json' -d'
{
  "query": { 
    "match": {
      "message": "some message"
    }
  }
}
'

此API会获取其被调用时的索引的快照，并基于此快照中匹配文档的内部版本号，执行删除操作。

注意：由于内部版本化不支持版本号0， 因此version=0的文档无法被_delete_by_query删除。 

curl -X DELETE 'localhost:9200/customer?pretty'

{
  "acknowledged" : true
}

ES提供了批量操作的API，可以把多个CRUD操作组合在一起执行：

# 插入两个文档
curl -X POST 'localhost:9200/customer/_doc/_bulk?pretty' -H 'Content-Type: application/json' -d'
{"index":{"_id":"1"}}
{"name": "John Doe" }     # Source Document
{"index":{"_id":"2"}}
{"name": "Jane Doe" }
'

# 更新一个文档，删除一个文档
curl -XPOST 'localhost:9200/customer/_doc/_bulk?pretty' -H 'Content-Type: application/json' -d'
{"update":{"_id":"1"}}
{"doc": { "name": "John Doe becomes Jane Doe" } }
{"delete":{"_id":"2"}}
'

# 注意删除操作不需要指定的Source Document

如果批处理中的某个操作失败，则它会继续处理。最终，所有操作的执行结果会返回给调用者。

准备数据：

wget https://raw.githubusercontent.com/elastic/elasticsearch/master/docs/src/test/resources/accounts.json
# 从文件读取批处理的输入
curl -H "Content-Type: application/json" -X POST "localhost:9200/bank/_doc/_bulk?pretty&refresh" --data-binary "@accounts.json"

当执行搜索时，请求会广播给索引的全部分片，并以RR算法选择分片的Replica。使用routing参数可以强制在匹配哈希值的分片上执行搜索，你可以为routing指定逗号分隔的多个值。

除了默认的RR轮询算法以外，ES还支持自适应Replica选择，自动选取最适当的Replica。选取准则包括：

1. 根据协调（coordinating）节点向数据节点转发请求的响应时间
2. 在数据节点上执行请求所消耗的时间
3. 数据节点的搜索线程池大小

要启用该特性，设置集群选项：

# PUT /_cluster/settings
{
    "transient": {
        "cluster.routing.use_adaptive_replica_selection": true
    }
}

除了在每个请求中设置超时之外，ES还支持全局性的搜索超时search.default_search_timeout，此设置没有默认值，设置为-1可以取消先前设置的值。

搜索可以通过标准的任务取消机制来取消。默认情况下ES仅仅在段边界（segment boundaries）来检查请求是否已经被取消，因此取消操作可能由于大段而延迟。要降低取消操作的响应时间，可以设置search.low_level_cancellation=true，但是要注意此设置会导致更加频繁的检查。

默认情况下ES不限制搜索请求牵涉到的分片数量，你可以设置软限制 action.search.shard_count.limit 来拒绝命中太多分片的请求。

参数max_concurrent_shard_requests可以限制搜索请求最多同时在多少个分片上执行，可以防止单个搜索请求消耗整个集群的资源。 此参数的默认值取决于集群中数据节点的数量，最多256。

检索API支持两种传递查询参数的方式：通过URL参数、通过请求体。

要检索特定索引上，任何类型的文档，使用：/index_name/_search

要检索特定索引上，特定类型的文档，使用：/index_name/type1,type2.../_search

要检索多个索引上，具有特定标签的，使用：/index1,index2/_search?q=tag:tag1

要检索任何的索引，使用：/_all/_search

示例：

# q=* 匹配所有文档，不指定field默认使用_all字段，此字段是String类型

# q=field:value 仅field字段匹配value的文档

# sort=account_number:asc  根据账号升序排列结果
curl -XGET 'localhost:9200/bank/_search?q=*&sort=account_number:asc&pretty'

注意，并非所有检索选项支持URL方式传参。

query参数传递Query DSL，示例：

curl -XGET 'localhost:9200/bank/_search?pretty' -H 'Content-Type: application/json' -d'
{
  "from" : 0, "size" : 10,
  "query": { "match_all": {} },
  "sort": [
    { "account_number": "asc" }
  ]
}
'

可用参数：

{
  "took" : 10,               # 执行搜索消耗的时间
  "timed_out" : false,       # 搜索是否超时
  "_shards" : {              # 多少分片参与到搜索
    "total" : 5,
    "successful" : 5,     
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {                 # 搜索结果
    "total" : 1000,          # 匹配的总数
    "max_score" : null,      # 最大分数
    "hits" : [               # 实际匹配文档的数组
      {
        "_index" : "bank",   
        "_type" : "_doc",
        "_id" : "0",
        "_score" : null,     # 分数表示文档匹配查询的程度，值越大，匹配程度越高
        "_source" : {
          "account_number" : 0,
          "balance" : 16623,
          "firstname" : "Bradshaw",
          "lastname" : "Mckenzie",
          "age" : 29,
          "gender" : "F",
          "address" : "244 Columbus Place",
          "employer" : "Euron",
          "email" : "bradshawmckenzie@euron.com",
          "city" : "Hobucken",
          "state" : "CO"
        },
        "sort" : [
          0
        ]
      },
      {
        "_index" : "bank",
        "_type" : "_doc",
        "_id" : "1",
        "_score" : null,
        "_source" : {
          "account_number" : 1,
          "balance" : 39225,
          "firstname" : "Amber",
          "lastname" : "Duke",
          "age" : 32,
          "gender" : "M",
          "address" : "880 Holmes Lane",
          "employer" : "Pyrami",
          "email" : "amberduke@pyrami.com",
          "city" : "Brogan",
          "state" : "IL"
        },
        "sort" : [
          1
        ]
      },
      ...
    ]
  }
}

一旦搜索结果返回，ES就不会在服务器端存留任何资源，例如游标。这个特性和关系型数据库不同。

# 返回所有文档
{
  "query": { "match_all": {} }
}
# 返回第一个匹配的文档，size默认为10
{
  "query": { "match_all": {} },
  "size": 1
}
# 分页，返回11-20个文档
{
  "query": { "match_all": {} },
  "from": 10,
  "size": 10
}

默认情况下，返回的结果是按照相关性（评分）进行排序的——最相关的文档排在最前，默认按照_score字段降序排序。

你也可以定制排序方式：

# 根据balance升序排列
{
  "query": { "match_all": {} },
  "sort": { "balance": { "order": "desc" } }
}

# 多值字段排序
{
   "query" : {
      "term" : { "country" : "china" }
   },
   "sort" : [
      {"population" : {"order" : "asc", "mode" : "avg"}}
   ]
}

ES支持根据数组字段、多值字段进行排序，此时可以设置sort.mode字段：

ES支持依据文档中的嵌套字段进行排序，示例：

{
   "query" : {
      "term" : { "product" : "chocolate" }
   },
   "sort" : [
       {
          # 根据嵌套字段排序
          "offer.price" : {
             # 取嵌套字段平均值
             "mode" :  "avg",
             # 升序排列
             "order" : "asc",
             # 嵌套字段信息
             "nested": {
                # 导航路径
                "path": "offer",
                # 过滤条件
                "filter": {
                   "term" : { "offer.color" : "blue" }
                }
             }
          }
       }
    ]
}

使用missing指定可以指定当某个文档没有参与排序的字段时该怎么办，默认值为_last，可以取值_first或者自定义一个用于排序的数值：

{
    "sort" : [
        { "price" : {"missing" : "_last"} }
    ]
}

ES支持根据二维平面上的距离值来排序，示例：

{
    "sort" : [
        {
            "_geo_distance" : {
                # 支持多种形式的坐标：
                "pin.location" : { "lat" : 40, "lon" : -70 },
                "pin.location" : "40,-70",
                "pin.location" : [[-70, 40], [-71, 42]],
                "pin.location" : [-70, 40],  # 排序的字段: 计算距离时的中心点
                "order" : "asc",             # 升降序
                "unit" : "km",
                "mode" : "min",              # 如果排序字段中包含多个Geo点，如何处理
                "distance_type" : "arc"      # 可以取值plane，速度快但是长距离、近极地时不准确
            }
        }
    ]
}

排序算法可以由自定义的脚本提供：

{
    "sort" : {
        "_script" : {
            "type" : "number",
            "script" : {
                "lang": "painless",
                "source": "doc['field_name'].value * params.factor",
                "params" : {
                    "factor" : 1.1
                }
            },
            "order" : "asc"
    }
}

当使用排序时，默认不会计算匹配分数，要改变此行为设置track_scores = true

当执行排序时，排序相关的字段被载入内存。每个分片都需要具有足够的内存来容纳这些字段：

1. 对于参与排序的字符串类型，不应该被analyzed/tokenized
2. 对于参与排序的数字类型，尽可能使用更短的类型

# 不返回任何字段
{
    "_source": false
}

# 返回account_number、balance两个字段
{
  "query": { "match_all": {} },
  "_source": ["account_number", "balance"]
}

# 使用通配符指定字段
{
    "_source": [ "obj1.*", "obj2.*" ]
}

# 指定需要包含、排除的字段
{
    "_source": {
        "includes": [ "obj1.*", "obj2.*" ],
        "excludes": [ "*.description" ]
    }
}

允许根据现有字段，进行计算，衍生出新的字段：

{
    "query" : {
        "match_all": {}
    },
    "script_fields" : {
        "test2" : {
            # 使用doc更快，内存消耗高（因为目标字段的terms被载入内存）。仅能返回简单的值（不能返回JSON文档）
            "script" : {
                "lang": "painless",
                "source": "doc['my_field_name'].value * params.factor",
                "params" : {
                    "factor"  : 2.0
                }
            },
            # 使用_source非常慢，因为整个文档需要载入并解析
            "script" : "params['_source']['my_field_name']"
        }
    }
}

通常的规则是，使用 查询（query）语句来进行全文搜索或者其它任何需要影响相关性得分的搜索。除此以外的情况都使用过滤（filters)。

本节以Query DSL语法说明如何指定查询条件。

# 查询语句典型结构
{
    QUERY_NAME: {
        ARGUMENT: VALUE,
        ARGUMENT: VALUE,...
    }
}
# 针对特定字段的查询语句结构
{
    QUERY_NAME: {
        FIELD_NAME: {
            ARGUMENT: VALUE,
            ARGUMENT: VALUE,...
        }
    }
}

# 全部匹配
"query": {}
"query": {
    "match_all": {}
}

# 账号为20
{
  "query": { "match": { "account_number": 20 } }
}
# 地址中包含mill字样
{
  "query": { "match": { "address": "mill" } }
}
# 地址中包含mill或者lane字样
{
  "query": { "match": { "address": "mill lane" } }
}
# 地址中包含"mill lane"这个短语
{
  "query": { "match_phrase": { "address": "mill lane" } }
}

# 在多个字段上进行匹配
{
    "multi_match": {
        "query":    "full text search",
        "fields":   [ "title", "body" ]
    }
}

# 查询落在指定区间的时间、数字
{
    "range": {
        "age": {
            "gte":  20,
            "lt":   30
        }
    }
}

# 精确匹配查询
{ "term": { "age":    26           }}
{ "term": { "date":   "2014-09-01" }}
{ "term": { "public": true         }}
{ "term": { "tag":    "full_text"  }}

# 精确匹配查询（多值，匹配任意一个即可）
{ "terms": { "tag": [ "search", "full_text", "nosql" ] }}


# 存在性查询
{
    # 存在title字段
    "exists":   {
        "field":    "title"
    }
    # 不存在title字段
    "missing":   {
        "field":    "title"
    }
}

{
  "query": {
    "bool": {
      # 与：地址中同时包含mill和lane
      "must": [
        { "match": { "address": "mill" } },
        { "match": { "address": "lane" } }
      ]
    }
  }
}
{
  "query": {
    "bool": {
      # 或：地址中包含mill或lane
      "should": [
        { "match": { "address": "mill" } },
        { "match": { "address": "lane" } }
      ]
    }
  }
}
{
  "query": {
    "bool": {
      # 非：地址中不得包含mill或lane
      "must_not": [
        { "match": { "address": "mill" } },
        { "match": { "address": "lane" } }
      ]
    }
  }
}

{
  "query": {
    # 返回年龄为40，且不住在爱达荷州的顾客账户
    "bool": {
      "must": [
        { "match": { "age": "40" } }
      ],
      "must_not": [
        { "match": { "state": "ID" } }
      ]
    }
  }
}

过滤查询（Filtering queries）只是简单的检查包含或者排除，这就使得计算起来非常快。过滤查询不进行评分，结果可以被缓存。

相反，评分查询（scoring queries）不仅仅要找出 匹配的文档，还要计算每个匹配文档的相关性，计算相关性使得它们比不评分查询费力的多。同时，查询结果并不缓存。

由于倒排索引（inverted index），一个简单的评分查询在匹配少量文档时可能与一个涵盖百万文档的filter表现的一样好，甚至会更好。但是在一般情况下，一个filter 会比一个评分的query性能更优异，并且每次都表现的很稳定。

注意filter可以放在不同位置，仅仅其引用的查询条件不影响评分，而不是整个查询不支持评分。过滤查询示例：

{
  "query": {
    "bool": {
      # 返回地址中包含lane（默认大小写不敏感），且余额在2w到3w之间的账户
      "must": { "match": { "address": "lane" } },
      "filter": {
        "range": {
          # 下面的条件不影响评分
          "balance": {
            "gte": 20000,
            "lte": 30000
          }
        }
      }
    }
  }
} 

ES支持修改搜索结果，为匹配搜索的字段添加HTML标签，以便高亮显示：

{
    "highlight": {
        "fields" : {
            # 默认情况下，about字段中匹配搜索条件的部分会被<em>标签包围
            "about" : {}
        }
    }
}

示例：

{
  # 不返回聚合前的结果集，我们仅仅关注聚合
  "size": 0,
  "aggs": {
    # 聚合结果的键
    "group_by_state": {
      "terms": {
        # 根据state字段进行分组
        "field": "state.keyword"
      },
      # 聚合函数默认是统计总数
    }
  }
}

# 类似于SQL：SELECT state, COUNT(*) FROM bank GROUP BY state ORDER BY COUNT(*) DESC

执行结果如下：

{
  "took" : 28,
  "timed_out" : false,
  "_shards" : {
    "total" : 5,
    "successful" : 5,
    "skipped" : 0,
    "failed" : 0
  },
  # 聚合前的结果集
  "hits" : {
    "total" : 1000,
    "max_score" : 0.0,
    "hits" : [ ]
  },
  # 聚合
  "aggregations" : {
    # 键
    "group_by_state" : {
      "doc_count_error_upper_bound" : 20,
      "sum_other_doc_count" : 770,
      "buckets" : [
        {
          "key" : "ID",
          "doc_count" : 27
        },
        {
          "key" : "TX",
          "doc_count" : 27
        }
        ...
      ]
    }
  }
}

你可以指定聚合函数、排序方式：

{
  "size": 0,
  "aggs": {
    "group_by_state": {
      "terms": {
        "field": "state.keyword",
        # 根据平均余额降序排列
        "order": {
          "average_balance": "desc"
        }
      },
      # 聚合函数：对账户余额取平均值
      "aggs": {
        "average_balance": {  # 字段名
          "avg": {
            "field": "balance"
          }
        }
      }
    }
  }
}

ES提供了很适当的默认配置，需要很少的定制化。大部分配置项都可以在运行时更新。 

ES的配置文件主要有三个：

1. elasticsearch.yml 主配置文件
2. jvm.options 使用的JVM参数
3. log4j2.properties 日志配置

这些配置文件位于conf目录，具体位置和你使用的安装方式有关。可以通过环境变量定制：

ES_PATH_CONF=/path/to/my/config ./bin/elasticsearch

主配置文件基于YML格式，支持通过${VAR_NAME}来引用环境变量，例如：

node.name:    ${HOSTNAME}
network.host: ${ES_NETWORK_HOST}

主要的配置项如下：

path:
  # 日志存放目录
  logs: /var/log/elasticsearch
  # 数据存放目录
  data: /var/data/elasticsearch
  # 可以指定多个存储位置
  data:
    - /mnt/elasticsearch_1
    - /mnt/elasticsearch_2
    - /mnt/elasticsearch_3

# 当前节点所属集群名称
cluster.name: logging-prod

# 当前节点的名称
node.name: ${HOSTNAME}

# 绑定的监听地址
network.host: 10.0.0.1

 
# 节点的相互发现
# ES实现了所谓Zen Discovery，用于节点发现、Master选举
# 不进行任何配置的情况下，ES会扫描localhost的9300-9305来寻找相同服务器上运行的节点
# 在实际集群中，你需要指定当前节点需要连接的其它节点
discovery.zen.ping.unicast.hosts:
   - 192.168.1.10:9300
   - 192.168.1.11 
   - seeds.mydomain.com 
# 节点列表可以不指定端口，默认使用transport.profiles.default.port
# 如果transport.profiles.default.port没有配置则使用transport.tcp.port

# 为了防止数据丢失，需要配置每个有资格成为Master的节点能够看到的，其它有资格成为Master的节点的最小数量
# 如果不设置此选项，在网络分区的情况下，集群会分裂为两个独立的小集群，即脑裂。脑裂会导致数据丢失
# 为了防止脑裂，需要设置此选项为 (master_eligible_nodes / 2) + 1
discovery.zen.minimum_master_nodes: 2
  zen:
    # 故障发现，默认1秒执行一次，超时30秒，超时3次则剔除节点。可能导致索引重新分配
    ping_interval: 1
    ping_timeout: 30s
    ping_retries: 3

默认情况下，ES使用固定大小的1G堆内存。关于JVM参数配置的建议包括：

1. 设置堆的最小值和最大值相同
2. 堆越大，ES越可以缓存更多的东西。但是大堆意味着更长的GC停顿
3. Xmx不要设置超过50%的物理内存。为内核和系统缓存留下空间 

ES使用Java安全管理器。JVM默认无限期的缓存DNS解析记录，如果你依赖于动态解析的DNS，则需要配置安全管理器：

networkaddress.cache.ttl=<timeout>、
networkaddress.cache.negative.ttl=<timeout>

Swap可能导致JVM堆甚至可执行页被交换到磁盘中，对性能有非常不利的影响。Swap可能导致GC从毫秒级变为分钟级完成、导致节点响应异常缓慢甚至脱离集群。因此，宁愿让OS把节点杀掉也不要启用Swap。

你可以执行下面的命令来禁用所有交换文件：

sudo swapoff -a

注释掉/etc/fstab中的相关行，可以永久禁用Swap。

设置systctl参数vm.swappiness为1，可以减小Linux内核进行Swap的倾向，让它在通常情况下不会Swap。

或者，你可以利用Linux的mlockall，将ES进程的地址空间锁定在内存中，配置ES：

bootstrap.memory_lock: true

ES需要使用大量的文件描述符/文件句柄。确保运行ES的用户可以打开65536或者更多的文件描述符。

ES默认使用一个mmapfs目录来存储其索引，OS的mmap计数默认值很低，可能导致OOM异常。执行下面命令修改：

sysctl -w vm.max_map_count=262144
# 一个进程可以拥有的VMA(虚拟内存区域)的数量，虚拟内存区域是一个连续的虚拟地址空间区域
# 在进程的生命周期中，每当程序尝试在内存中映射文件，链接到共享内存段，或者分配堆空间的时候，这些区域将被创建

ES需要创建很多线程来完成不同的操作，你最少要保证ES能够创建4096个线程：ulimit -u 4096或者设置nprocs

对于Gold/Platinum类型的License，如果你启用了安全，则必须同时启用TLS。

你可以使用外部提供的CA证书，或者通过下面的命令生成：

bin/x-pack/certutil ca 

可以使用下面的命令生成p12格式的私钥、证书：

bin/x-pack/certutil cert --ca elastic-stack-ca.p12

默认情况下，此证书不包含SAN字段，因此可以所有节点共享。如果需要更加严格的身份验证，可以传入--name, --dns --ip参数。

你可以可以使用外部提供的证书。

把密钥拷贝到节点的config/certs目录下

添加以下ES配置项：

xpack.security.transport.ssl.enabled: true
xpack.security.transport.ssl.verification_mode: certificate 
xpack.security.transport.ssl.keystore.path: certs/elastic-certificates.p12 
xpack.security.transport.ssl.truststore.path: certs/elastic-certificates.p12

验证模式默认certificate，不检查SAN，如果需要更加严格的身份验证，设置为full。

重启服务后，集群节点间的TLS通信OK，你可以使用Gold/Platinum的License了。

curl -u elastic:$PSWD 'http://es-elasticsearch.kube-system.svc.k8s.gmem.cc:9200/_xpack/license' \
     -H "Content-Type: application/json" -d @eslic.json
                                            # license文件路径

登陆到客户端节点，执行下面的命令，可以随机生成elastic、kibana、logstash_system的新密码：

bin/x-pack/setup-passwords auto

 或者，你也可以交互式的设置密码：

bin/x-pack/setup-passwords interactive 

添加ES配置项：

xpack.security.authc:
  anonymous:
    # 匿名用户的名称
    username: anonymous
    # 授予的角色，逗号分隔
    roles: transport_client

启用身份验证后，如果没有修改内置用户密码，则kibana登陆界面会提示：Login is currently disabled. Administrators should consult the Kibana logs for more details.

你需要更改kibana的配置项elasticsearch.password，如果在Docker中运行Kibana，也可以修改环境变量ELASTICSEARCH_PASSWORD。然后使用setup-passwords命令更改内置用户密码。

建议把节点分为三类：

1. Master节点，仅仅负责集群管理，不存储数据，不提供HTTP API
2. Client节点，和客户端通信，不存储数据，提供HTTP API
3. Data节点，仅仅负责存储、索引数据，不提供HTTP API

对于超过32GB的堆，无法使用压缩普通对象指针（Compressed Ordinary Object Pointer），指针大小变为64bit。这导致50GB的堆，能存储的对象数量和30GB的堆差不多。

堆的最大、最小值应该设置为一致。

低水位：默认情况下，节点磁盘用量超过85%后，ES不会分发新的分片到该节点。即便如此，已有的分片仍然可能继续增大。

高水位：默认情况下，节点磁盘用量超过90%后，ES会停止写入，并且将该节点上的分片重现分配给磁盘空闲的其它节点。

副本：默认情况下使用1个副本，这意味着两倍的磁盘空间

分片：更大的分片，在存储上越高效。但是节点失败导致数据迁移的成本也越高。

索引是存储文档并让其可检索的过程。文档必须落盘，才能被搜索。

默认的落盘间隔是一秒，由参数refresh_interval指定。如果将此参数改为半分钟甚至更大，则能极大的增加ES的吞吐量：

PUT fluentd-2018.12.26/_settings
{
  "index" : {
    "refresh_interval" : "10s"
  }
}

每次落盘，ES都会创建一个新的段（segment ）。

设置更多的分片，插入数据的并发度更高：

PUT /_template/logstash_template
{
  "index_patterns": ["fluentd*"],
  "settings": {
    "number_of_shards" : 12, 
    "number_of_replicas": 0,
    "refresh_interval" : "10s"
  }
}

字段数据（Field Data ）反转倒排索引。如果你需要知道某个字段包含哪些值，则ES需要反转字段的倒排索引，并产生字段数据。

字段数据存放在堆中，不加任何限制可能充满整个堆。参数indices.fielddata.cache.size用于控制字段数据的内存用量，可以指定百分比或者绝对值。

如果写入量非常大，则需要保证内存中的索引缓冲足够大，对应的参数是indices.memory.index_buffer_size。可以设置高达512MB/分片。

ES 6.x的查询缓存使用LRU算法清除，其内存用量通过indices.queries.cache.size配置。 

批量请求比针对单个文档的请求性能要好很多。批次的最佳大小需要基准测试才能得出。

可以使用多个客户端并发的进行批量请求，单线程往往不能用尽ES的吞吐能力。

交换分区会导致严重的性能下降。

在进行IO操作时，需要使用文件系统缓存。你应该保证有一半的ES节点内存用于文件系统缓存。

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

参考：ElasticSearch学习笔记

Fluentd是一个C编写的开源的日志收集器，支持100+不同系统的日志收集处理。

定义Fluentd的输入，需要指定一个输入插件。例如：

<source>
  # 使用什么插件
  @type http
  # 你可以这样推送日志：http://localhost:8888/tag.name?json={...}
  port 8888
  bind 0.0.0.0
</source>

定义了一个HTTP输入。Fluentd会在8888端口上监听，等待外部传入事件。事件的例子：

curl -i -X POST -d 'json={"action":"login","user":2}' http://localhost:8888/test.cycle

source捕获到的Fluentd事件，交由Fluentd路由引擎处理。

多个filter可以构成事件处理流水线。使用filter你可以将不需要的事件过滤掉，不再继续下一步处理。例如：

<filter test.cycle>
  @type grep
  <exclude>
    key action
    pattern ^logout$
  </exclude>
</filter>

根据正则式匹配输入事件的action字段，如果匹配，路由给match处理，否则丢弃。

定义Fluentd的输出，并将匹配的事件传递给目标。例如：

<match test.cycle>
  @type stdout
</match>

会匹配具有Tag：test.cycle的输入事件，并传递给stdout这个输出插件。

用于定义一个可以被跳转到的路由片段，打破默认的从上到下的路由搜索顺序。该指令内部可以包含filter、match指令。示例：

<source>
  @type http
  bind 0.0.0.0
  port 8888
  # 指定路由标签
  @label @STAGING
</source>

<filter test.cycle>
</filter>

# http源直接跳转到这里，不使用上面的filter
<label @STAGING>
  <filter test.cycle>
    @type grep
    <exclude>
      key action
      pattern ^logout$
    </exclude>
  </filter>

  <match test.cycle>
    @type stdout
  </match>
</label>

可以位于source、match、filter指令的内部。对于那些支持的插件，用于解析原始数据。示例：

<source>
  @type tail
  # 输入插件的参数
  <parse>
    # 解析插件的类型
    @type apache2
    # 解析插件的参数
  </parse>
</source>

每个Parser都可以覆盖这些参数的值：

可以位于match指令的内部，指定如何对事件进行缓冲（避免对输出的目的地造成压力）。Fluentd内置了两种缓冲插件：memory、file。

使用buffer指令时，你也需要通过@type来指定插件类型。如果省略@type，则使用输出插件（match）指定的默认插件，或者使用memory。

你可以为buffer指定分块键：

# 为空，或者逗号分隔的字符串
<buffer ARGUMENT_CHUNK_KEYS>
</buffer>

分块键决定了事件被收集到哪个缓冲块：

1. 如果不指定分块键（并且输出插件也没有指定默认分块键），则输出插件将所有的事件都写到单个块中，直到此块充满
2. 如果分块键被设置为“tag”，则不同标签（Tag）的事件被收集到不同的缓冲块
3. 如果分块键被设置为“time”，且指定了timekey参数，则每个Time Key对应一个缓冲块：
   

   <buffer time>
     # 如果不指定单位，默认为秒
     timekey      1h # 每小时一个块
     timekey_wait 5m # 延迟5分钟刷出缓冲
   </buffer>

4. 如果分块键被设置为其它值，则认为是事件记录的字段名
5. 使用事件记录的嵌套字段也支持：

   <buffer $.nest.field> # 访问记录的nest.field字段

6. 联用多个分块键也支持：

   <buffer tag,time,$.nest.field>

某些输出插件，可以使用分块键作为变量：

<match log.*>
  @type file
  path  /data/${tag}/access.${key1}.${$.nest.field}.log # 输出文件名使用变量，不同块输出到不同文件
  <buffer tag,key1,$.nest.field>
  </buffer>
</match>

部分插件支持在内部包含format指令，用来指定如何对日志记录进行格式化。match、filter指令内部可以包含format指令：

<match tag.*>
  @type file
  <format>
    @type json
  </format>
</match>

内置的插件包括：out_file、json、ltsv、csv、msgpack、hash、single_value。下面的配置，将事件的log字段存储到文件：

<match **>
  @type file
  path  /var/log/kubernetes
  <format>
    @type single_value
    message_key log
  </format>
</match>

可以位于match、filter指令内部，向事件记录注入额外的字段。

可以位于source、match、filter指令内部，从事件记录中抽取值。

部分插件支持此指令，用于指定如何存储插件的内部状态。可以位于source、match、filter指令内部。

使用server插件助手的source、match、filter插件，支持在内部配置该指令。用于说明如何处理网络连接。

该指令用于包含其它配置文件

该指令用于进行系统级的配置，包括配置项：

每个Fluentd事件包含以下部分：

1. Tag：标签，用于说明事件的“来源”，用于事件路由。标签是点号（.）分隔的多个字符串
2. Time：事件发生的时间，必须是UNIX time格式
3. Record：实际的日志内容，JSON对象形式

标签（Tag）是日志事件的一种属性。filter、match指令可以指定一个匹配Pattern，来声明它负责处理哪些事件：

Fluentd根据配置文件中声明的顺序，自上而下的尝试匹配，一旦找到匹配日志事件的filter、match就不再继续。

如果通过td-agent包安装，则配置文件位置为/etc/td-agent/td-agent.conf。

如果通过Ruby Gem安装，则配置文件位置为/etc/fluent/fluent.conf。

要修改配置文件的位置，使用环境变量FLUENT_CONF，或者命令行选项 -c

任何一个Fluentd插件都暴露若干可配置参数。

["key1", "key2"]

key1,key2

{"key1":"value1", "key2":"value2"}

key1:value1,key2:value2

Fluentd定义了一系列以@开头的参数：

type, id 和 log_level是对应上面几个参数，向后兼容用。

你可以在字符串中包含

#{}

host_param "#{Socket.gethostname}"
env_param "foo-#{ENV["FOO_BAR"]}"

这是一个内置插件，不需要额外的安装步骤。该插件从目标配置文件的尾部开始读取新产生的日志。

# 仅仅读取default命名空间的日志
path /var/log/containers/*_default_*.log
# 日期
path /path/to/%Y/%m/%d/*

exclude_path ["/path/to/*.gz", "/path/to/*.zip"]

读取并解析Systemd日志。示例：

<source>
  @type systemd
  @id in_systemd_kubelet
  # 读取Kubelet.service的0-5级别的日志
  matches [{ "_SYSTEMD_UNIT": "kubelet.service", "PRIORITY": [0,1,2,3,4,5] }]
  <storage>
    @type local
    persistent true
    path /var/log/fluentd-journald-kubelet-cursor.json
  </storage>
  <entry>
    fields_strip_underscores true
  </entry>
  read_from_head false
  tag kubelet
</source>

支持以多种方式来修改事件。

<filter kubernetes.**>
  @type record_transformer
  enable_ruby
  <record>
    # 添加主机名
    hostname "#{Socket.gethostname}"
    # 将事件的标签存储为记录字段
    tag ${tag}
    # 读取事件标签的第2部分
    service_name ${tag_parts[1]}
    # 读取记录的字段并进行运算
    avg ${record["total"] / record["count"]}
    # 一个名为message的字段，使用$进行字符串插值
    message yay, ${record["message"]}
  </record>
</filter>

<filter kubernetes.**>
  @type record_transformer
  enable_ruby
  remove_keys [ "log" ]
  <record>
    # 从%-5p %d{yyyy-MM-dd HH:mm:ss.SSS} ::: [%15.15t] %-48.48c{36} ::: %m%n%ex
    # 形式的Logback Pattern中抽取字段
    level ${record["log"][0,5].strip}
    timestamp ${record["log"][6,23]}
    thread ${record["log"][35,15].strip}
    class  ${record["log"][52,49].strip}
    message ${record["log"][105..-1].strip}
  </record>
</filter>

# 将记录转换为JSON
${record.to_json}
# 格式化时间
${time.strftime('%Y-%m-%dT%H:%M:%S%z')}
# 取标签的最后一段
${tag_parts.last}
# 访问嵌套字段
${record["payload"]["key"]}

根据事件的字段进行过滤，不匹配的记录被丢弃。

参数	类型	说明
<and>	directive	内部指定几个其它指令，进行与操作： <and> <exclude> </exclude> <exclude> </exclude> </and>
<or>	directive	内部指定几个其它指令，进行或操作
<regexp>	directive	指定基于正则式的匹配规则，不匹配的事件会被排除： <regexp> # 检查的字段 key price # 匹配的正则式 pattern /[1-9]\d*/ </regexp>
<exclude>	directive	类似上面，但是匹配的事件会被排除

示例：

# 针对所有以calico-node开头的日志
<filter kubernetes.var.log.containers.calico-node-*.log>
  @type grep
  @id filter_grep_container_calico_node
  <regexp>
    # 针对日志记录的log字段
    key log
    # 仅仅保留警告、错误日志
    pattern ^.{25}(W|E)
  </regexp>
</filter>

# 仅仅保留具有标签tier=application的Pod产生的日志
<filter kubernetes.**>
  @type grep
  @id filter_grep_kubernetes
  <regexp>
    key $.kubernetes.labels.tier
    pattern ^application$
  </regexp>
</filter>

解析日志的字符串字段，并把事件记录替换为解析结果：

示例，解析ElasticSearch的JSON格式的日志，并把Wrapping Docker日志替换掉：

<filter kubernetes.var.log.containers.es-master-*.log>
  @type parser
  @id filter_parser_containers_es_master
  key_name log
  reserve_time true
  reserve_data true
  remove_key_name_field true
  <parse>
    @type json
    time_format %Y-%m-%dT%H:%M:%S.%NZ
  </parse>
</filter>

该插件非内置，执行

gem install fluent-plugin-concat

用于将多个日志事件合并为一个。具有工作三种模式：

1. n_lines 将连续的N个事件合并为一个
2. multiline_start_regexp ... 根据正则式匹配来确定该事件是否作为合并后的第一个、中间事件、最后一个
3. partial_key 取源事件中的某个字段，如果该字段的值为partial_value指定的值，则认为它应该合并到前面的事件

注意： 如果超时后仍然没有接收到被合并序例的的最后一个事件，则整个序列会被丢弃。

下面的示例用于处理被Docker的日志驱动按行收集的Java Logback日志信息，它会将日志中的异常栈合并到一起，然后与它们之前的（紧靠着的）那个事件合并：

<filter kubernetes.**>
  @type concat
  @log_level trace
  key log
  multiline_start_regexp /^(TRACE|DEBUG|INFO|WARN|ERROR|FATAL)/
  timeout_label @ES
</filter>

<match kubernetes.**>
  @type relabel
  @label @ES
</match>

<label @ES>
...
</label>

根据正则式来解析日志。指定的正则式至少需要指定一个命名捕获，命名捕获会作为记录的字段，名字为time的命名捕获，会作为事件的发生时间。

expression /^(?<time>.{30}) (?<stream>\w+) . (?<log>.*)$/ 

types <field_name_1>:<type_name_1>,<field_name_2>:<type_name_2>
# 示例
types user_id:integer,paid:bool,paid_usd_amount:float

regexp的多行版本，支持将多行日志合并为一个事件，特别适用于解析异常栈。

Java异常日志的例子：

<parse>
  @type multiline
  # 识别新记录的正则式
  format_firstline /\d{4}-\d{1,2}-\d{1,2}/
  # 解析完整记录的正则式
  format1 /^(?<time>\d{4}-\d{1,2}-\d{1,2} \d{1,2}:\d{1,2}:\d{1,2}) \[(?<thread>.*)\] (?<level>[^\s]+)(?<message>.*)/
</parse>

# 第一个记录
2013-3-03 14:27:33 [main] INFO  Main - Start
# 第二个记录
2013-3-03 14:27:33 [main] ERROR Main - Exception
javax.management.RuntimeErrorException: null
    at Main.main(Main.java:16) ~[bin/:na]
# 第三个记录
2013-3-03 14:27:33 [main] INFO  Main - End

Rails日志的例子：

<parse>
  @type multiline
  # 识别新记录的正则式
  format_firstline /^Started/
  # 分为多个参数，每个参数对应一行日志信息
  format1 /Started (<method>[^ ]+) "(<path>[^"]+)" for (<host>[^ ]+) at (<time>[^ ]+ [^ ]+ [^ ]+)\n/
  format2 /Processing by (<controller>[^\u0023]+)\u0023(<controller_method>[^ ]+) as (<format>[^ ]+)\n/
  format3 /(  Parameters: (<parameters>[^ ]+)\n)/
  format4 /  Rendered (<template>[^ ]+) within (<layout>.+) \([\d\.]+ms\)\n/
  format5 /Completed (<code>[^ ]+) [^ ]+ in (<runtime>[\d\.]+)ms \(Views: (<view_runtime>[\d\.]+)ms \| ActiveRecord: (<ar_runtime>[\d\.]+)ms\)/
</parse>

# 第一个记录
Started GET "/users/123/" for 127.0.0.1 at 2013-06-14 12:00:11 +0900
Processing by UsersController#show as HTML
  Parameters: {"user_id"=>"123"}
  Rendered users/show.html.erb within layouts/application (0.3ms)
Completed 200 OK in 4ms (Views: 3.2ms | ActiveRecord: 0.0ms)

在Fluentd 1.0，允许三种输出插件的缓冲/刷出模式：

1. 无缓冲模式，直接写出到外部系统
2. 同步缓冲模式，使用缓冲块（事件集），缓冲块排队等候刷出。行为由buffer段控制
3. 异步缓冲模式，类似2，但是输出插件在后台异步的提交请求给外部系统

每个插件可以支持全部3种模式，也可以仅仅支持一种模式。如果对不支持缓冲的插件配置buffer段，fluentd会出错并终止。

该插件非内置，执行

gem install fluent-plugin-route

fluent-plugin-route支持修改标签，支持定义多个路由规则。可以实现事件复制分发：

<match worker.**>
  @type route
  # 修改标签前缀
  remove_tag_prefix worker
  add_tag_prefix metrics.event

  # 复制事件，走路由规则一
  <route **>
    copy # 不使用COPY会导致路由在此结束
  </route>
  # 复制事件，走路由规则二
  <route **>
    copy
    @label @BACKUP
  </route>
</match>

# 路由规则一
<match metrics.event.**>
  @type stdout
</match>

# 路由规则二
<label @BACKUP>
  <match metrics.event.**>
    @type file
    path /var/log/fluent/bakcup
  </match>
</label>

fluent-plugin-rewrite-tag-filter支持根据日志事件的内容来修改标签。示例：

<match app.**>
  @type rewrite_tag_filter
  # 根据内容的message字段，对齐进行正则式匹配，获取日志级别，捕获为$1，作为Tag的前缀
  rewriterule1 message ^\[(\w+)\] $1.${tag}
</match>

# 错误消息路由到这里
<match error.app.**>
  @type mail
</match>
# 其它消息路由到这里
<match *.app.**>
  @type file
</match>

将日志记录输出到ES中。插件参数：

#{logstash_prefix}-#{formated_date}

示例：

<match *.**>
  @type elasticsearch
  host 10.0.10.2
  port 9200
  user logstash_system
  password logstash_system
  logstash_format true
  logstash_prefix openstack
  enable_ilm true
  index_date_pattern "now/m{yyyy.mm}"
  flush_interval 10s
</match>

简单的丢弃事件，示例：

<match fluent.**>
    @type null
</match>

将日志写入到Kafka主题中。

执行下面的命令安装此插件：

fluent-gem install fluent-plugin-kafka

配置示例：

<match pattern>
  @type kafka_buffered

  # 种子代理列表
  brokers <broker1_host>:<broker1_port>,<broker2_host>:<broker2_port>

  # 缓冲设置
  buffer_type file
  buffer_path /var/log/td-agent/buffer/td
  flush_interval 3s

  # Kafka主题
  default_topic messages

  # 数据类型设置
  output_data_type json
  compression_codec gzip

  # 生产者配置
  max_send_retries 1
  required_acks -1

</match>

此插件用于给事件重新打标签，例如：

<match pattern>
  @type relabel
  @label @foo
</match>

<label @foo>
  <match pattern>
    ...
  </match>
</label>

会给Tag匹配pattern的事件全部打上@foo标签，这些事件会全部交由名为@foo的label区段处理。

将事件写入到文件。不是记录写入后立即就生成文件，只有time_slice_format条件满足时文件才生成，默认情况下该插件每天生成一个文件。

插件参数：

# append false
log.20140608_0.log
log.20140608_1.log
log.20140609_0.log
log.20140609_1.log

# append true
log.20140608.log
log.20140609.log 

一个实例：

<label @K8S_OUT_FILE>
  <match **>
    @type file
    # 目录 %Y-%m-%d.%H.${$.kubernetes.labels.application} 中会存放缓冲文件，每小时（3600）刷出
    # 文件名称示意 2018-11-14.17.account.log.gz，  log.gz自动添加，不需要在path中声明
    path  /var/log/kubernetes/%Y-%m-%d.%H.${$.kubernetes.labels.application}
    append true
    # 压缩文件可以这样浏览：gzip -dc 2018-11-14.17.account.log.gz  | grep ERROR
    compress gzip
    <buffer time,$.kubernetes.labels.application>
      timekey 3600
      timekey_wait 10
      timekey_zone +0800
    </buffer>
    <format>
      @type single_value
      message_key log
    </format>
  </match>
</label> 

为了保证节点的时间戳精确，你需要安装NTP守护程序，例如chrony、ntpd。

文件描述符数量：

root soft nofile 65536
root hard nofile 65536
* soft nofile 65536
* hard nofile 65536

对于高负载、多个Fluentd的环境，需要修改网络参数：

net.core.somaxconn = 1024
net.core.netdev_max_backlog = 5000
net.core.rmem_max = 16777216
net.core.wmem_max = 16777216relabel
net.ipv4.tcp_wmem = 4096 12582912 16777216
net.ipv4.tcp_rmem = 4096 12582912 16777216
net.ipv4.tcp_max_syn_backlog = 8096
net.ipv4.tcp_slow_start_after_idle = 0
net.ipv4.tcp_tw_reuse = 1

重启或者

sysctl -p

如果日志的目的地是远程设备、存储，可以使用该选项来并行化输出（默认1）。使用多线程可以缓和网络延迟的影响。

所有输出插件支持该参数。

Ruby提供了若干GC参数，你可以通过环境变量来设置它们。

要减少内存占用，可以设置RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR为较小的值，此参数默认值2.0。资源受限环境下可以设置为1.2-

处理10亿级别的日志输入时，CPU会出现瓶颈，这时考虑增加工作进程数量：

<system>
  workers 8
</system>

Kibana是一个开源的分析和可视化平台，必须配合ES一起使用。可以使用Kibana来检索、分析ES索引中的数据，日志分析是最常用的应用场景。

用于交互式的日志查询，使用Lucene查询语法：

Visualize用于设计一个小器件，例如饼图、曲线图。Dashboard则可以将小器件组合为仪表盘。

这里以曲线图为例，点击曲线图的图标，首先要选择数据源，也就是索引。点选fluentd-*索引，看到如下界面：

点击顶部的Add a filter，可以添加过滤条件。

Metrics区域用于定义统计指标（度量），支持多个度量。

Buckets区域用于指定如何分组展示，示例：

可以选取在“可视化“中定义的小器件，并拖拽以布局，效果示例：

首页是总体状态信息，包括ES、Kibana的健康状态，已用/可用的各类硬件资源信息：

如果Elasticsearch的健康状态为red，则说明集群存在问题。截图中的情况是主分片尚未分配到节点导致。

点击上图Elasticsearch区域的Overview连接，可以看到ES集群更多的信息：

本页面显示ES的读（检索）、写（索引）性能指标，包括QPS和延迟。

Shard Activity通常是空的，上图中的情况是正在应用事务日志到ES数据节点。Translog是一种写前日志，记录所有针对ES的写操作。

此页面显示索引的列表，如果有红色说明索引存在问题。下图中第一个索引有一个分片不正常。

每个索引包含的文档数量、占用的磁盘空间、读写速率也显示在页面上。

该页面显示单个索引文档数量、占用的磁盘空间、读写速率随时间的变化曲线，以及索引各分片的状态。

上图中，es-data-0分配了序号为4的分片，并且此分片正在初始化。其它分配均正常。

捆绑了X-pack的ElasticSearch镜像：https://git.gmem.cc/alex/docker-elasticsearch

ElasticSearch+Kibana的Helm Chart：https://git.gmem.cc/alex/oss-charts/src/branch/master/elasticsearch

Fluentd的Helm Chart：https://git.gmem.cc/alex/oss-charts/src/branch/master/fluentd

iotop看到fluentd进程有高达200M/s的读操作，但是定位不到针对的是什么文件

使用csysdig跟踪进程系统调用，发现大量内存映射操作，针对/var/log/journal/4f2be1039e944e028f2e86e02fe410e1目录，删除目录后问题消失。

设置Kibana的环境变量XPACK_MONITORING_UI_CONTAINER_ELASTICSEARCH_ENABLED为false 

The post 基于EFK构建日志分析系统 appeared first on 绿色记忆.

Apache Curator（音标[kjʊ(ə)'reɪtə]）Framework是ZooKeeper的Keeper（动物园管理员的管理员）。它是一个Java库，提供了比ZooKeeper更加高层的API，更加易用、可靠。Curator的推荐的ZooKeeper版本是 3.5+，但它也和3.4兼容。

Curator实现了自动的连接管理，当会话过期后，你需要重新创建ZooKeeper客户端，并重新设置Watcher。Curator可以透明的重新创建、重试连接。

Curator以组标识

org.apache.curator

当前版本是4.0.0，通常你需要引用下面这个构件。此构件对curator-framework、curator-client有依赖：

<dependency>
    <groupId>org.apache.curator</groupId>
    <artifactId>curator-recipes</artifactId>
    <version>4.0.0</version>
</dependency>

Curator内置了重连逻辑，因此你不再需要手工Watch和管理了：

String zookeeperConnectionString = "172.21.0.1:2181,172.21.0.2:2181,172.21.0.3:2181";
// 重试策略，如果连接不上ZooKeeper集群如何重连
RetryPolicy retryPolicy = new ExponentialBackoffRetry( 1000, 3 );
CuratorFramework client = CuratorFrameworkFactory.newClient( zookeeperConnectionString, retryPolicy );
client.start();
// 创建znode
client.create().forPath( "/tmp", EMPTY );

client.create().withMode(CreateMode.EPHEMERAL_SEQUENTIAL).forPath("/user", new byte[0]);

client.delete().inBackground().forPath("/user");

client.getData().watched().inBackground().forPath("/user");

Recipes封装了很多高层语义，例如互斥锁、Leader选举，你不再需要手工实现了：

// 分布式互斥锁用法：
InterProcessMutex lock = new InterProcessMutex(client, lockPath);
if ( lock.acquire(maxWait, waitUnit) ) {
    try{
        // 临界区
    }
    finally{
        lock.release();
    }
}

// 在多个进程之间选择Leader
LeaderSelectorListener listener = new LeaderSelectorListenerAdapter() {
    public void takeLeadership(CuratorFramework client) throws Exception {
        // 如果当前进程被选择为Leader则此回调被调用
        // 除非当前进程想放弃Leader地位，不要退出此方法
    }
}

LeaderSelector selector = new LeaderSelector(client, path, listener);
selector.autoRequeue();
selector.start();

Curator提供了此接口，用于处理连接中断：

public interface ConnectionStateListener {
    public void stateChanged(CuratorFramework client, ConnectionState newState);
} 

使用某些Recipe时，你应该通过Listenable.addListener注册此接口的实现。

Recipes是Curator提供的高层封装。大部分Recipes都会自动创建所需要的父znode。

在分布式计算领域，多个同类型服务器（节点）通常需要指定其中一员作为Leader，例如主从复制场景下需要指定主节点（Leader）。

Leader通常通过选举产生，在选举前，任何节点均不知道Leader是谁，选举完毕后，则所有节点对Leader是谁达成共识。

Curator提供了两个Recipes来支持选举。其中LeaderSelectorListener已经在起步一章示例过。

用法示例：

String id = "websvr0";
LeaderLatch ll = new LeaderLatch( client, "/pems/websvr", id );
// 需要先启动
// 一旦启动，LeaderLatch会自动联系其它选举参与者，并随机选择一个作为Leader
ll.start();
// 任何时候，你可以调用下面的接口来判断当前进程是否为Leader
ll.hasLeadership();
// 一直等待，知道变为Leader
ll.await();
// 把当前进程从被选举人列表中移除，如果当前是Leader则放弃此权利，其它进程会被选举为Leader
ll.close();

LeaderLatch会添加一个ConnectionStateListener来监控连接问题：

1. 当连接变为SUSPENDED/LOST状态后，当前Leader的hasLeadership()调用返回false（丢失Leader权限）
2. 当断开的连接变为RECONNECTED，LeaderLatch会删除之前创建的znode，并创建新的

这是一个分布式的可重入（锁的持有者可以反复获得锁）的共享锁，保证任何时刻只能有一个客户端占有锁。

用法示例：

InterProcessMutex mutex = new InterProcessMutex( client, "/mutex/resource" );
// 阻塞，直到获得锁。返回true
mutex.acquire();
// 阻塞一定时间，尝试获得锁，返回true/false
mutex.acquire( 1000, TimeUnit.SECONDS );
// 释放锁，仅仅当调用线程是当初获得锁的线程时，才可以释放
mutex.release();

// 使得锁可被撤销，当其它进程/线程attemptRevoke此锁时，你会得到通知
mutex.makeRevocable( forLock -> {
    // 得到通知后，你可以选择释放锁
    forLock.release();
} );

// 尝试撤销锁
Revoker.attemptRevoke(client,"/mutex/resource" );

你应当设置一个ConnectionStateListener来监听SUSPENDED/LOST状态变更：

1. 当连接变为SUSPENDED状态后，你无法确定当前是否仍然持有锁，除非恢复到RECONNECTED状态
2. 当连接变为LOST状态后，你肯定已经丢失了锁 

API类似于InterProcessMutex，对应类InterProcessSemaphoreMutex。此锁不可以重入。

这是一个可重入的读写锁，所有JVM中的所有线程共享一个分布式的临界区域。此外，该锁是“公平的” —— 每个请求者按照其请求的顺序（ZooKeeper角度）来获得锁。

读写锁维护一对相关联的锁，一个用于读，一个用于写。其中读锁可以被多个进程共同持有，而写锁则是独占的（也不允许读锁被持有）。

持有写锁者，可以继续请求读锁，反之则不行。通过获取写锁 —— 获取读锁 —— 释放写锁，可以实现锁降级。

代码示例：

InterProcessReadWriteLock lock = new InterProcessReadWriteLock( client, "/resource" );
// 获取两个相关的锁，然后调用InterProcessMutex的API即可
InterProcessMutex readLock = lock.readLock();
InterProcessMutex writeLock = lock.writeLock();

你应当设置一个ConnectionStateListener来监听SUSPENDED/LOST状态变更。 

这是一个分布式的信号量。所谓信号量，是一个有限数量的资源集，进程可以租借/归还信号量。此信号量实现是“公平的” —— 每个请求者按照其请求的顺序（ZooKeeper角度）来获得信号量。

确定信号量资源数的方式有两种：

1. 由SharedCountReader类提供
2. 静态声明信号量数量，这要求所有参与者声明相同的数值

代码示例：

// 声明一个具有10个资源的信号量
InterProcessSemaphoreV2 semaphore = new InterProcessSemaphoreV2( client, "/semaphore", 10 );
// 通过SharedCount指定资源数量
SharedCountReader sc = new SharedCount( client, "/sharedcount", 10 );
semaphore = new InterProcessSemaphoreV2( client, "/semaphore", sc );

// 租借一个资源，可选参数等待时间
Lease lease = semaphore.acquire();
// 租借N个资源，可选参数等待时间
Collection<Lease> leases = semaphore.acquire( 2 );

// 归还资源
lease.close();
// 或者：
semaphore.returnLease( lease );
semaphore.returnAll( leases );

你应当设置一个ConnectionStateListener来监听SUSPENDED/LOST状态变更。

持有一系列InterProcessLock的引用，客户端要么获取所有锁，要么失败。当释放时，所有锁一起被释放。

所谓屏障，是一个同步点。每一个进程到达此点都要等待，直到所有进程都到达，则继续。

代码示例： 

DistributedBarrier barrier = new DistributedBarrier( client, "/barrier" );
// 设置屏障，每个客户端设置一次
barrier.setBarrier();

// 等待所有客户端都到达，如果连接丢失，此方法会抛出异常
barrier.waitOnBarrier();

双重屏障，在协作开始之前同步，当足够数量的进程加入到屏障后，开始协作，当所有进程完毕后离开屏障。

代码示例：

// 建立一个10个资源的屏障
DistributedDoubleBarrier barrier = new DistributedDoubleBarrier( client, "/barrier", 10 );
// 进入屏障，当有10个客户端进入屏障后，阻塞解除
barrier.enter();
// 这里是协作逻辑 ...
// 离开屏障，当所有客户端都尝试离开时，阻塞解除
barrier.leave();

如果连接丢失，则enter/leave会抛出异常。 

一个共享的整数，所有客户端均看到一致性的、最新的数值。

代码示例：

// 第三个参数为初始值，假设路径不存在，则自动设置为此值
SharedCount counter = new SharedCount( client, "/counter", 0 );
// 此计数器需要启动
counter.start();
// 设置计数值
counter.setCount( 10 );
// 获取计数值
counter.getCount();
counter.addListener( new SharedCountListener() {
    @Override
    public void countHasChanged( SharedCountReader sharedCount, int newCount ) throws Exception {
        // 计数值变化后异步回调
    }

    @Override
    public void stateChanged( CuratorFramework curatorFramework, ConnectionState connectionState ) {
        // 连接数量变化后的异步回调
        // 如果连接变为SUSPENDED状态，你必须假设计数器的值不再精确
        // 如果连接变为LOST状态，则计数器永久性失效
    }
} );

Curator提供了一个基于Java 8 Completion Stage的纯异步客户端实现。要使用此实现，添加依赖：

<dependency>
    <groupId>org.apache.curator</groupId>
    <artifactId>curator-x-async</artifactId>
    <version>4.0.0</version>
</dependency>

String zookeeperConnectionString = "172.21.0.1:2181,172.21.0.2:2181,172.21.0.3:2181";
RetryPolicy retryPolicy = new ExponentialBackoffRetry( 1000, 3 );
CuratorFramework client = CuratorFrameworkFactory.newClient( zookeeperConnectionString, retryPolicy );
client.start();


// 此包装器提供异步API
AsyncCuratorFramework async = AsyncCuratorFramework.wrap( client );
//    检查znode /user是否存在             如果存在，打印状态结构
async.checkExists().forPath( "/user" ).thenAccept( stat -> LOGGER.debug( stat.toString() ) );

// 获取数据
async.getData().forPath( "/user" ).thenAccept( data -> LOGGER.debug( new String( data ) ) );

// 在最前面添加watched()调用，可以增加Watcher
// 使用AsyncStage（CompletionStage子类型）的event()方法，设置Watcher的回调
async.with( WatchMode.successOnly) // 不关心连接丢失类的事件
     .watched().getData().forPath( "/user" ).event().thenAccept( ev -> LOGGER.debug( ev.toString() ) );

// 同步化
async.create().forPath("/user").toCompletableFuture().get();

通过串行化机制，Apache Curator支持在ZooKeeper的znode中存储类型化的数据。这一功能由Modeled Curator组件负责。

MC不使用原始的字符串形式的路径，而是使用ZPath来抽象ZooKeeper路径。ZPath可以是简单的字符串，也可以包含路径变量，这些变量可以根据需要替换为动态的取值：

// 静态路径
ZPath staticPath = ZPath.parse( "/static/path" );
// 动态路径，使用 {} 包围路径变量，路径变量又叫ID，其中可以包含任何东西，例如{ any thing}但是没有什么意义
// 路径变量（ID）总是从左向右依次解析
ZPath path = ZPath.parseWithIds( "/static/{}/{}" );
// 路径变量可以被替换，如果用于替换的对象是NodeName，则调用其nodeName()方法，否则调用toString()方法
ZPath resolvedPath = path.resolved( "path", new NodeName() {
    public String nodeName() {
        return "name";
    }
}  );
// 输出内容：/static/path/name
System.out.println( resolvedPath );

// 路径可以被部分的解析：
System.out.println( path.resolved( "path" ) );

此类型包含对ZooKeeper路径进行操作（存取强类型对象）所需的全部元数据：

1. 一个ZPath
2. 用于串行化对象的串行化器
3. 关于如何创建znode的选项（顺序、压缩、TTL等）
4. 针对znode的ACL
5. 如何删除znode（是否删除子节点）

要写入一个数据模型到znode的关联数据，参考如下代码： 

public static class ServerInfo implements NodeName {
    private String name;
    private String type;

    @Override
    public String nodeName() {
        return getName();
    }
}

ModelSpec<ServerInfo> spec = ModelSpec.builder(
        ZPath.parseWithIds("/servers/{}"),
        JacksonModelSerializer.build(ServerInfo.class)
).build();
// 依赖异步客户端
ModeledFramework<ServerInfo> modeledClient = ModeledFramework.wrap(async, spec);

ServerInfo info = new ServerInfo();
info.setType("webserver");
info.setName("tk.gmem.cc");
// 输出：/servers/hk.gmem.cc，这个路径是把模型传入ZPath而解析得到的，因为模型实现了NodeName，因此调用其nodeName()替换路径变量
modeledClient.set(info).thenAccept(path -> LOGGER.debug(path)).toCompletableFuture().get();

本例使用JacksonJSON作为串行化机制的实现，需要引入依赖：

<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
    <version>LATEST</version>
</dependency>

ModelSpec<ServerInfo> spec = ModelSpec.builder(
        ZPath.parseWithIds("/servers/hk.gmem.cc"),
        JacksonModelSerializer.build(ServerInfo.class)
).build();
ModeledFramework<ServerInfo> modeledClient = ModeledFramework.wrap(async, spec);
modeledClient.read().whenComplete((info, e) -> {
    if (e != null) {
        
    } else {
        LOGGER.debug(info.getType());
    }
}).toCompletableFuture().get();

这一功能允许你在一个事务中，执行一系列的ZooKeeper操作。你可以使用迁移来保证某个ZooKeeper子树的数据一致性。示例：

// 一系列操作组成一个迁移
CuratorOp op1 = async.transactionOp().create().forPath("/parent");
CuratorOp op2 = async.transactionOp().create().forPath("/parent/one");
CuratorOp op3 = async.transactionOp().create().forPath("/parent/two");
CuratorOp op4 = async.transactionOp().create().forPath("/parent/three");
// Migration是一个函数式接口，本质上就是一系列操作
Migration migration = () -> Arrays.asList(op1, op2, op3, op4);
// 迁移集可以包含若干个迁移，迁移集必须有个ID
MigrationSet set = MigrationSet.build("main", Collections.singletonList(migration));

// 迁移管理器，负责执行迁移
// 迁移管理器会监控迁移集的执行状态，它只会应用那些没有应用的迁移
MigrationManager manager = new MigrationManager(client,
        lockPath,       // 迁移管理器会锁定此路径
        metaDataPath,   // 存储元数据的路径
        executor,       // 异步执行器
        lockMax         // 锁定最长时间
);
manager.migrate(set).exceptionally(e -> {
    if (e instanceof MigrationException) {
        // migration checksum failed, etc.
    } else {
        // some other kind of error
    }
    return null;
});

在SOA/分布式系统中，服务需要能够相互发现。例如，一个Web服务需要发现缓存服务。可以使用服务发现系统（Service Discovery system）来避免服务位置的硬编码。服务发现系统的功能包括：

1. 允许服务注册自己，便于其它服务调用之
2. 定位某种服务的但个实例
3. 当服务的实例发生变化，可以发出通知

Curator服务发现功能由单独的子项目实现：

<dependency>
    <groupId>org.apache.curator</groupId>
    <artifactId>curator-x-discovery</artifactId>
    <version>4.0.0</version>
</dependency>

这个类代表一个服务的实例，具有名称（同一类型服务共享）、标识符、地址、端口、可选的附加详细信息。服务实例被串行化在znode中，路径为/basePath/serviceName/id。

基于提供策略（provider strategy）对某个特定的命名服务的发现服务进行封装，所谓提供策略，决定了如何从多个服务实例中选择一个实例。内置的策略包括循环选择（Round Robin）、随机、粘性（Sticky，总选择一个实例）。

ServiceProviderBuilder作为ServiceProvider的工厂，由ServiceDiscovery提供。ServiceProviderBuilder允许你设置服务的名称以及其它可选的属性。

ServiceProvider必须在

start()

close()

getInstance()

noteError()

由ServiceDiscoveryBuilder创建，此类负责提供ServiceProviderBuilder。

ServiceProvider必须在

start()

close()

// 当前JVM提供的服务实例
ServiceInstance<InstanceDetail> thisService = ServiceInstance.<InstanceDetail>builder()
        .name( "cacheService" )
        .payload( new InstanceDetail() )
        .address( "192.168.0.89" )
        .port( 8088 )
        .uriSpec( new UriSpec( "http://{address}:{port}" ) )
        .build();

// 服务发现
JsonInstanceSerializer<InstanceDetail> serializer = new JsonInstanceSerializer<InstanceDetail>( InstanceDetail.class );
ServiceDiscovery<InstanceDetail> discovery = ServiceDiscoveryBuilder
        .builder( InstanceDetail.class )
        .client( client )
        .basePath( "/sd" )
        .serializer( serializer )
        .thisInstance( thisService )
        .build();
// 需要启动
discovery.start();

// 服务提供者
ServiceProvider<InstanceDetail> sp = discovery
        .serviceProviderBuilder()
        .serviceName( "cacheService" )
        // 随机选取服务实例
        .providerStrategy( new RandomStrategy<>() )
        // 如果在一分钟内，有10此noteError则认为目标实例宕机
        .downInstancePolicy( new DownInstancePolicy( 60, TimeUnit.SECONDS, 10 ) )
        .build();
// 需要启动
sp.start();


LOGGER.debug( sp.getInstance().buildUriSpec() );

为了让非JVM应用使用服务发现功能，Curator提供了RESTful的WebService，你可以通过HTTP协议来注册、移除、查询服务。

Curator提供了JAX-RS组件，你可以在任何Web容器中，配合JAX-RS提供者（例如Jersey）使用该组件。

可能原因是ZooKeeper服务器的版本与工程声明的ZooKeeper客户端版本不兼容导致。

The post Apache Curator学习笔记 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 绿色记忆.

Apache Storm是一个分布式的实时计算系统，它能够可靠的对无边界的数据流进行处理。与Hadoop的批量处理方式不同，Storm对数据进行的是实时处理。Storm很简单，支持很多编程语言。

Storm的应用场景包括：实时分析、在线机器学习、持续计算、分布式RPC、分布式ETL。

Storm的性能很好，每个节点在一秒内能够处理多达100万个元组。Storm支持无限制扩容、容错、并且保证数据能够被处理。

你可以让既有的数据库、消息队列系统和Storm进行集成。Storm拓扑消费数据流，以任意复杂的方式处理数据流，数据流可以在任何计算阶段（Stage）重新分区。

实时计算的逻辑被封装到Storm拓扑中，拓扑和MapReduce的Job类似。一个关键的区别是，MapReduce Job最终会结束，而拓扑则一直运行下去。

你可以使用TopologyBuilder构建一个拓扑。

Storm把每个具体的工作委托给多种类型的组件处理。这些组件都装配在拓扑中。

拓扑可以跨越Storm集群的多个工作节点运行。

流是Storm的核心抽象，它是无边界的元组的序列。流以分布式的风格被并行的创建、处理。流的元素是元组，元组可以包含整数、字符串、浮点数、布尔、比特数组等类型的字段。你可以自己实现串行化器，支持任何自定义数据类型。

你可以使用OutputFieldsDeclarer来声明流以及流的Schema。在声明的时候，每个流被赋予一个标识符。仅仅释放单个流的Spout很常见，因此OutputFieldsDeclarer提供了声明单个流的便捷方法，不需要指定标识符，流的标识符自动设置为default。

Storm中被处理的数据的基本单元，本质上就是一个预定义的字段的值列表。

Spout可以释放出元组，不同的Bolt可以读取同一Spout产生的元组，并释放不同格式的元组，供其它Bolt消费。

在拓扑中，Spout是流的来源。一般来说，Spout从外部读取元组，并释放（Emit）出元组的流（Spout本意即喷射口）。Spout可以是可靠的（Reliable ）或者不可靠的。可靠的Spout支持在处理失败后重复（Replay）元组。所有Spout必须实现IRichSpout接口。

Spout可以释放不止一个流，你可以多次调用

OutputFieldsDeclarer

declareStream

SpoutOutputCollector.emit

Spout的主要方法是nextTuple，调用它可以释放一个新的元组到拓扑中，如果没有可用的元组，该方法应该简单的返回。Storm强制要求所有Spout实现类的nextTuple方法是非阻塞性的，因为Storm在单个线程中调用Spout的所有方法。

其它重要的方法包括ack、fail，这些方法仅仅针对可靠Spout调用，分别在元组顺利通过拓扑后、处理失败后调用，将处理结果通知给Spout。

Spout将数据传递给Bolt这种组件进行实质上的逻辑处理。拓扑中最主要的内容就是Bolt构成的链条。

拓扑中所有处理逻辑发生在Bolt中，Bolt可以进行过滤、聚合、Join等操作，可以和数据库进行交互。

Bolt可以进行简单的流变换（Stream Transformation），复杂的流变换通常需要多个步骤，也就需要多个Bolt。

Bolt可以释放不止一个流，你可以多次调用

OutputFieldsDeclarer

declareStream

OutputCollector.emit

在声明Bolt的输入流时，你需要订阅其它组件的某个特定流，如果要订阅某个组件的多个流，你需要逐个订阅。InputDeclarer提供了订阅具有默认标识符的流的快捷方法，例如

declarer.shuffleGrouping("1")

DEFAULT_STREAM_ID

Bolt的主要方法是execute，此方法接受一个元组输入。Bolt使用OutputCollector对象释放新的元组。Bolt会针对每个输入元组调用OutputCollector.ack方法，以通知Storm目标元组已经处理成功，这些ack调用最终导致Spout.ack被调用。大部分Bolt根据输入元组输出0-N个输出元组。IBasicBolt提供自动确认（Ack）功能。

在Bolt中启动新线程进行异步处理是很好的做法，OutputCollector是线程安全的，你可以在任何时候调用它。

Bolt的基础接口是IRichBolt。要设计进行过滤、简单function的Bolt可以选择实现IBasicBolt接口。Bolt调用OutputCollector来释放元组到它的输出流中。

定义拓扑的一部分工作是，指定每个Bolt能够接受哪些流作为其输入。流分组（Stream Grouping）指定了如何在Bolt的Task之间进行流的分区（Partition）。

Storm可以保证每个元组都被拓扑处理。为了确认元组的处理过程，Storm对Spout释放出的元组树进行跟踪，并以此确定何时元组树被成功处理。每个拓扑都具有一个消息超时属性，如果在此超时到达之前没有检测到元组已经处理成功，则认定处理失败，并Replay目标元组。

之所有叫元组树，是因为在任何一个Bolt中，一个源元组可能产生多个目标元组，这样经过多个Bolt后，就形成树状依赖关系。注意，目的和源的依赖关系需要编程式的声明，一个目标元组可以依赖于多个源元组。

每个Spout、Bolt在集群中执行一定数量的Task，每个Task对应一个执行线程。流分组决定了元组如何从一组Task分发到另外一组Task。调用TopologyBuilder的setSpout/setBolt方法可以设置并发度。

Topology跨越1-N个工作进程执行，每个工作进程都是一个JVM实例，负责执行拓扑中所有Task的一个子集。Storm会尝试尽可能平均的分配Task给Worker。例如，一个总和并行度为300的拓扑，分配了50个工作进程，则每个进程需要执行6个Task。

Storm集群包含两类节点：

1. 主节点（Master）：这类节点运行一个名为Nimbus的守护程序。此程序负责在集群中分发代码（处理逻辑）、向工作节点分配Task、监控Task是否执行失败
2. 工作节点（Worker）：这类节点运行一个名为Supervisor的守护程序。此程序负责执行拓扑的某个部分

Storm支持在本地磁盘或者ZooKeeper上保存集群的所有状态信息，因此守护程序宕机不会对系统的健康状况产生影响。

Storm和Hadoop的核心概念的对应关系如下图：

Storm提供四类内置的调度器： DefaultScheduler, IsolationScheduler, MultitenantScheduler, ResourceAwareScheduler。

Storm有两种运行模式（Operation Modes）。

在此模式下，Storm的拓扑在本地机器中单个JVM中运行。此模式主要用于开发、测试和调试。

在此模式下，我们需要将定义好的拓扑提交到Storm集群中。集群通常由运行在很多机器中的进程组成。远程模式下不会显示调试信息，通常用于产品环境。

你也可以在单台机器上进行远程模式的部署。

Storm包含若干不同的守护进程，Nimbus能够调度Worker进程，Supervisors负责启动、杀死Worker进程。Logger View让你能够访问日志。Web服务器让你能够通过GUI查看Storm状态。

当Worker进程死掉后，Supervisor会重新启动它。如果Worker反复死掉并且不能完成到Nimbus的心跳检测，Nimbus会重新调度此Worker。

当节点宕机后，Nimbus会重新分配在节点上执行的Task给其它节点。

Nimbus/Supervisor被设计为无状态的，所有状态信息存放在ZooKeeper或者磁盘上。因此它们宕机后，你可以安全的重启它们。你应该考虑使用daemontools/monit之类的工具监控这类进程的状态，并在它们死掉后立即重启。

如果Nimbus节点（Master）宕机，Worker节点仍然会继续工作。此外Supervisor仍然会自动重启死掉的Worker进程。但是没有Nimbus就不能把Worker节点分配到其它机器上。从1.0.0开始，Storm支持Nimbus的HA。

在本章，我们创建一个简单的，分析动力环境监测值的拓扑。

此类型模拟监测值采集程序，以随机的方式产生监测值：

package cc.gmem.study.storm.mv;

import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.commons.lang3.RandomUtils;
import org.apache.commons.lang3.Range;
import org.apache.commons.lang3.mutable.MutableInt;
import org.apache.commons.lang3.tuple.Pair;
import org.slf4j.Logger;

import java.util.*;
import java.util.concurrent.TimeUnit;

import static org.slf4j.LoggerFactory.getLogger;

public class MessageSource extends Thread {

    private Map<String, Pair<Double, Double>> config;

    private ObjectMapper om;

    Queue<String> messages;

    private static final Logger LOGGER = getLogger( MessageSource.class );

    private boolean term;

    public MessageSource( Map<String, Pair<Double, Double>> config ) {
        super();
        this.config = config;
        this.messages = new LinkedList<>();
        this.om = new ObjectMapper();
        start();
    }

    @Override
    public void run() {
        setName( "MessageSource" );
        LOGGER.debug( "Starting monitoring value source thread" );
        while ( true ) {
            if ( term ) {
                LOGGER.debug( "Terminating monitoring value source" );
                break;
            }
            List<Map<String, Object>> mvs = new ArrayList<>();
            MutableInt idPfx = new MutableInt( 10 );
            config.forEach( ( type, pair ) -> {
                int n = RandomUtils.nextInt( 1, 5 );
                for ( int i = 0; i < n; i++ ) {
                    Map<String, Object> mv = new LinkedHashMap<>();
                    double value = RandomUtils.nextDouble( pair.getLeft(), pair.getRight() );
                    mv.put( "id", idPfx.intValue() + RandomUtils.nextInt( 1, 5 ) );
                    mv.put( "type", type );
                    mv.put( "value", value );
                    mvs.add( mv );
                }
                idPfx.add( 10 );
            } );
            LOGGER.debug( "Generated new message with {} monitoring value", mvs.size() );
            try {
                String msg = om.writeValueAsString( mvs );
                messages.offer( msg );
                TimeUnit.SECONDS.sleep( 10 );
            } catch ( Exception e ) {
                LOGGER.error( e.getMessage(), e );
            }
        }
    }

    public boolean available() {
        return !messages.isEmpty();
    }

    public String nextMessage() {
        return messages.poll();
    }

    public void singalTerm() {
        this.term = true;
    }
} 

MessageReader是此拓扑中唯一的Spout，从MessageSource中读取监测值报文并直接传递给Bolt处理。

任何Spout需要实现IRichSpout接口，你可以选择继承缺省适配BaseRichSpout。

package cc.gmem.study.storm.mv;

import org.apache.commons.lang3.tuple.ImmutablePair;
import org.apache.commons.lang3.tuple.Pair;
import org.apache.storm.spout.SpoutOutputCollector;
import org.apache.storm.task.TopologyContext;
import org.apache.storm.topology.IRichSpout;
import org.apache.storm.topology.OutputFieldsDeclarer;
import org.apache.storm.tuple.Fields;
import org.apache.storm.tuple.Values;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.concurrent.TimeUnit;

public class MessageReader implements IRichSpout {

    private static final Logger LOGGER = LoggerFactory.getLogger( MessageReader.class );

    private MessageSource msgSrc;

    private SpoutOutputCollector collector;


    /**
     * 当前组件的任一个Task在集群的某个工作节点中初始化时，自动调用此方法
     *
     * @param conf      配置信息，在创建拓扑时指定的配置合并到当前机器的集群配置而成
     * @param context   拓扑的上下文信息，可以获得组件ID、Task ID、输入输出信息
     * @param collector 输出收集器，线程安全，应该作为实例变量
     *                  此收集器可以在任何时候调用，以释放元组供下游组件消费
     */
    @Override
    public void open( Map conf, TopologyContext context, SpoutOutputCollector collector ) {
        LOGGER.debug( "Spout {}/{} opening", context.getThisComponentId() ,context.getThisTaskId());
        Map<String, Pair<Double, Double>> config = new LinkedHashMap<>();
        // 读取配置信息
        List<List<Object>> msgSrcCfg = (List<List<Object>>) conf.get( "msgSrcCfg" );
        msgSrcCfg.forEach( typeCfg -> {
            config.put( (String) typeCfg.get( 0 ), new ImmutablePair( (Double) typeCfg.get( 1 ), (Double) typeCfg.get( 2 ) ) );
        } );
        this.msgSrc = new MessageSource( config );
        this.collector = collector;
    }

    /**
     * 当此Spout即将被关闭时调用
     * <p>
     * 注意：此方法通常不保证一定被调用，因为在集群中Supervisor会以kill -9杀死工作进程。
     * 当以本地模式运行Storm时，此方法保证被调用
     */
    @Override
    public void close() {
        LOGGER.debug( "Spout closing" );
        msgSrc.singalTerm();
    }

    /**
     * 当Spout被激活后调用，激活后nextTuple很快被调用
     * 使用Storm客户端可以激活或者禁用Spout
     */
    @Override
    public void activate() {

    }

    /**
     * 当Spout被禁用后调用，处于禁用状态的Spout的nextTuple不会被调用
     */
    @Override
    public void deactivate() {

    }

    /**
     * 此方法会被周期性的调用，释放下一个元组
     */
    @Override
    public void nextTuple() {
        if ( !msgSrc.available() ) {
            try {
                // 休眠至少10ms再返回，避免无限制的CPU占用
                TimeUnit.MILLISECONDS.sleep( 10 );
                return;
            } catch ( InterruptedException e ) {
            }
        }
        // Values是对ArrayList<Object>的简单封装，其值可以是任何可串行化的Java对象
        String msg = msgSrc.nextMessage();
        LOGGER.debug( "Emit new tuple: {}", msg );
        this.collector.emit( new Values( msg ) );
    }

    /**
     * 当此Spout释放出的具有指定ID的元组已经成功通过拓扑之后，Storm调用此方法
     * 此方法的典型实现是，将对应数据从队列中移除并且阻止它被Replay
     *
     * @param msgId 元组的ID
     */
    @Override
    public void ack( Object msgId ) {
        LOGGER.debug( "Tuple with id {} acknowledged", msgId );
    }

    /**
     * 当此Spout释放出的具有指定ID的元组在某个环节处理失败后，Storm调用此方法
     * 此方法的典型实现是，将对应数据放回队列，以便后续Replay
     *
     * @param msgId 元组的ID
     */
    @Override
    public void fail( Object msgId ) {
        LOGGER.debug( "Tuple with id {} failed", msgId );
    }

    /**
     * 此方法来自IComponent接口，用于声明针对此组件的配置。仅topology.*之下的配置可以被覆盖
     * 当通过TopologyBuilder构建拓扑时，这里声明的配置可能被覆盖
     *
     * @return
     */
    @Override
    public Map<String, Object> getComponentConfiguration() {
        return null;
    }

    /**
     * 此方法来自IComponent接口，声明输出元组包含的字段
     */
    @Override
    public void declareOutputFields( OutputFieldsDeclarer declarer ) {
        // 为当前组件的默认输出流声明字段
        // 你还可以调用 declarer.declareStream( streamId,fields ) 声明新的输出流
        declarer.declare( new Fields( "message" ) );
    }
}

这是一个Bolt，读取监测值报文并解析之，释放多个监测值信息元组。 

任何Bolt都需要实现IRichBolt接口。你可以选择实现IBasicBolt（继承BaseBasicBolt），这样Storm会自动进行元组确认（Ack），使用IBasicBolt时你可以抛出FailedException表示当前元组处理失败。

package cc.gmem.study.storm.mv;

import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.commons.lang3.mutable.MutableInt;
import org.apache.storm.task.OutputCollector;
import org.apache.storm.task.TopologyContext;
import org.apache.storm.topology.IRichBolt;
import org.apache.storm.topology.OutputFieldsDeclarer;
import org.apache.storm.tuple.Fields;
import org.apache.storm.tuple.Tuple;
import org.apache.storm.tuple.Values;
import org.slf4j.Logger;

import java.io.IOException;
import java.util.List;
import java.util.Map;

import static org.slf4j.LoggerFactory.getLogger;

public class MessageParser implements IRichBolt {

    private static final Logger LOGGER = getLogger( MessageParser.class );

    private ObjectMapper om;

    private OutputCollector collector;

    /**
     * 当前组件的任一个Task在集群的某个工作节点中初始化时，自动调用此方法
     * 类似Spout的open方法
     */
    @Override
    public void prepare( Map stormConf, TopologyContext context, OutputCollector collector ) {
        LOGGER.debug( "Bolt {}/{} preparing", context.getThisComponentId(), context.getThisTaskId() );
        om = new ObjectMapper();
        this.collector = collector;
    }

    /**
     * 处理单个输入元组，每当接收到新元组此方法都被调用
     * Tuple对象包含一些元数据信息：此元组来自什么component/stream/task
     * 调用Tuple#getValue可以获得元组的实际数据
     * <p>
     * Bolt不一定要立刻处理元组，例如你可能暂存它并在后续进行聚合或连接操作
     * 每个元组都需要在未来某个时刻被ack/fail，否则Storm无法确认Spout释放的原初元组释放已经被完整除了
     * 子接口IBasicBolt支持在execute()执行完毕后自动ack
     * <p>
     * 如果此Bolt要释放元组，需要调用prepare传入的OutputCollector
     *
     * @param input The input tuple to be processed.
     */
    @Override
    public void execute( Tuple input ) {
        // 一个Bolt获得的元组可能来自不同的流
        LOGGER.debug( "Received input tuple from {}", input.getSourceStreamId() );
        // 元组字段可以根据名称或者索引读取
        String msg = input.getStringByField( "message" );
        try {
            List<Map<String, Object>> mvs = om.readValue( msg, List.class );
            MutableInt count = new MutableInt( 0 );
            mvs.forEach( mv -> {
                collector.emit( new Values( mv.get( "id" ), mv.get( "type" ), mv.get( "value" ) ) );
                count.increment();
            } );
            LOGGER.debug( "{} monitoring value parsed", count.intValue() );
        } catch ( IOException e ) {
            collector.fail( input );
        }
        collector.ack( input );
    }

    /**
     * 此Bolt即将被关闭时调用，此调用不保证一定发生
     * 类似Spout的close方法
     */
    @Override
    public void cleanup() {

    }

    @Override
    public void declareOutputFields( OutputFieldsDeclarer declarer ) {
        declarer.declare( new Fields( "id", "type", "value" ) );
    }

    @Override
    public Map<String, Object> getComponentConfiguration() {
        return null;
    }
}

这是一个Bolt，它读取MessageParser释放的监测值元组，然后进行实时统计分析。

package cc.gmem.study.storm.mv;

import org.apache.storm.task.TopologyContext;
import org.apache.storm.topology.BasicOutputCollector;
import org.apache.storm.topology.OutputFieldsDeclarer;
import org.apache.storm.topology.base.BaseBasicBolt;
import org.apache.storm.tuple.Tuple;
import org.slf4j.Logger;

import java.math.BigDecimal;
import java.math.RoundingMode;
import java.util.Map;

import static java.math.BigDecimal.ONE;
import static java.math.BigDecimal.ZERO;
import static org.slf4j.LoggerFactory.getLogger;

public class MonitorValueCounter extends BaseBasicBolt {

    private static final Logger LOGGER = getLogger( MonitorValueCounter.class );

    BigDecimal[] counter;

    @Override
    public void prepare( Map stormConf, TopologyContext context ) {
        LOGGER.debug( "Bolt {}/{} preparing", context.getThisComponentId(), context.getThisTaskId() );
        counter = new BigDecimal[]{ ZERO /*计数*/, ZERO /*平均*/, BigDecimal.valueOf( Integer.MAX_VALUE ) /*最小*/, ZERO /*最大*/ };
    }

    @Override
    public void execute( Tuple input, BasicOutputCollector collector ) {
        String type = input.getStringByField( "type" );
        BigDecimal value = BigDecimal.valueOf( input.getDoubleByField( "value" ) );
        if ( counter[2].compareTo( value ) > 0 ) counter[2] = value;
        if ( counter[3].compareTo( value ) < 0 ) counter[3] = value;
        if ( counter[0].equals( ZERO ) ) {
            counter[0] = ONE;
            counter[1] = value;
        } else {
            BigDecimal newCount = counter[0].add( ONE );
            counter[1] = counter[1].multiply( counter[0] ).add( value ).divide( newCount, RoundingMode.HALF_EVEN );
            counter[0] = newCount;
        }
        LOGGER.debug( "Type: " + type + ", Count: {}, Avg: {}, Min: {}, Max: {}", counter );
    }

    @Override
    public void declareOutputFields( OutputFieldsDeclarer declarer ) {
    }
}

主程序，创建拓扑并提交到集群中执行：

package cc.gmem.study.storm.mv;


import org.apache.storm.Config;
import org.apache.storm.LocalCluster;
import org.apache.storm.generated.StormTopology;
import org.apache.storm.topology.TopologyBuilder;
import org.apache.storm.tuple.Fields;
import org.apache.storm.tuple.Values;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.TimeUnit;

public class MonitorValueStatTopology {

    public static void main( String[] args ) throws InterruptedException {
        TopologyBuilder builder = new TopologyBuilder();
        // 每个组件都具有一个ID，供其它组件引用，以消费此组件的输出
        builder.setSpout( "message-reader", new MessageReader() );

        builder.setBolt( "message-parser", new MessageParser() )
               .shuffleGrouping( "message-reader" ); // 消费message-reader的默认流，随机、均匀分发元组给当前Bolt

        builder.setBolt( "monitor-value-counter", new MonitorValueCounter() )
               // 设置并发度
               .setNumTasks( 3 )
               // 消费message-parser的默认流，根据输入元组的type字段分发到不同的Task
               // 如果Task数量不足，则type字段值不同的元组会被分发给同一个Task
               .fieldsGrouping( "message-parser", new Fields( "type" ) );

        Config conf = new Config();
        List<Values> msgSrcCfg = new ArrayList<>();
        msgSrcCfg.add( new Values( "温度", new Double( 0 ), new Double( 40 ) ) );
        msgSrcCfg.add( new Values( "湿度", new Double( 0 ), new Double( 100 ) ) );
        msgSrcCfg.add( new Values( "电压", new Double( 0 ), new Double( 360 ) ) );
        conf.put( "msgSrcCfg", msgSrcCfg );

        conf.setDebug( true );
        // 对于每一个Spout Task，处于未决状态的元组最大数量
        // 所谓未决，即元组尚未被ack/fail
        conf.put( Config.TOPOLOGY_MAX_SPOUT_PENDING, 1 );

        // 创建一个本地模式的Storm集群
        LocalCluster cluster = new LocalCluster();
        // 创建拓扑
        StormTopology topology = builder.createTopology();
        // 提交拓扑到集群
        cluster.submitTopology( "monitor-value-stat-topology", conf, topology );

        TimeUnit.SECONDS.sleep( 60 );

        // 关闭集群
        cluster.shutdown();
    }
}

Storm对于下述运行在集群中的拓扑中的实体：

1. 工作进程（Worker processes）
2. 执行器（Executors，线程）
3. 任务（Task）

进行了明确的区分：

1. Storm集群中的节点（机器）可以运行0-N个工作进程，这些工作进程可以属于1-N个拓扑。每个工作进程就是一个JVM，它仅仅为单个拓扑运行Executor。也就是说Worker不能被两个拓扑共享
2. 单个Worker进程中可以运行1-N个Executor，每个Executor都是Worker进程产生的线程。每个Executor运行单个拓扑的单个组件的1-N个Task。也就是说Executor不能被两个组件共享
3. 任务进行实际的数据处理，它执行Spout或者Bolt中的代码逻辑。它由Executor来执行

可以看到：

1. 工作进程执行一个拓扑的子集，它只能属于一个拓扑
2. 工作进程可以运行多个执行器线程，这些线程可以运行不同的组件。但是每个线程只能运行一种组件的任务
3. 任务必须在执行器线程内部运行

要对并行度进行配置，参考并发度配置。

流分组指定了如何在Bolt的Task之间进行流的分区（Partition）——流的每个元组应该由哪个Task处理。

在定义拓扑的时候，你可以为Bolt指定流分组，指定流分组的同时也就指定了Bolt的数据源。你可以针对一个bolt多次指定流分组，也就是指定多个输入流：

builder.setBolt( "monitor-value-counter", new MonitorValueCounter() )
       .fieldsGrouping( "message-parser", new Fields( "type" ) )
       // 为Bolt指定另一个输入：signals-reader组件的signals流
       .allGrouping("signals-reader","signals"); 

要实现自己的流分组，需要实现CustomStreamGrouping接口。通常情况下，你应该优先考虑使用Storm内置的流分组。

// 获得某个下游组件的所有Task Id
Set<Integer> taskIds = context.getTaskToComponent( "downstream-bolt-id" ).keySet();
// 发送给目标Task
collector.emitDirect( taskId,tuple );

实现CustomStreamGrouping、Serializable接口：

package cc.gmem.study.storm.mv;


import org.apache.storm.generated.GlobalStreamId;
import org.apache.storm.grouping.CustomStreamGrouping;
import org.apache.storm.task.WorkerTopologyContext;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.io.Serializable;
import java.util.List;

import static org.slf4j.LoggerFactory.getLogger;
// 实现Serializable接口，Storm需要跨JVM分发此对象
public class DeviceStreamGrouping implements CustomStreamGrouping, Serializable {

    private static final Logger LOGGER = getLogger( DeviceStreamGrouping.class );

    private List<Integer> targetTasks;

    /**
     * 初始化流分组实例，告知流分组必要的信息
     *
     * @param context     拓扑上下文
     * @param stream      此分组应用到的流
     * @param targetTasks 接收流的bolt的Task Id的列表
     */
    @Override
    public void prepare( WorkerTopologyContext context, GlobalStreamId stream, List<Integer> targetTasks ) {
        LOGGER.debug( "Apply grouping on stream {}.{}", stream.get_componentId(), stream.get_streamId() );
        this.targetTasks = targetTasks;
    }

    /**
     * 确定元组分发到哪个Task
     *
     * @param taskId 源组件产生当前元组的那个Task的Id
     * @param values 当前元组
     * @return 接受此元组的Task Id列表
     */
    @Override
    public List<Integer> chooseTasks( int taskId, List<Object> values ) {
        return targetTasks;
    }
}

使用上述自定义流分组：

builder.setBolt(...).customGrouping( "message-parser", new DeviceStreamGrouping() );

此类用于在当前JVM中建立一个本地模式的集群。通常在开发阶段使用，可以方便的对各种拓扑进行调试：

LocalCluster cluster = new LocalCluster();
StormTopology topology = builder.createTopology();
// 提交到本地集群
cluster.submitTopology( "topology-name", conf, topology );

此类用于将拓扑提交到一个远程Storm集群中运行。与本地模式不同，你不能对远程集群进行控制。

StormSubmitter.submitTopology("monitor-value-stat-topology", conf, builder.createTopology());

下文有一个实际的例子。

通过storm客户端命令，也可以将拓扑提交到远程集群。首先你需要打JAR包，然后执行：

# 提交执行，需要指定main方法及其参数，main方法调用了StormSubmitter.submitTopology
storm jar topology.jar cc.gmem.study.storm.mv.MonitorValueStatTopology arg0 arg1...
# 要终止提交的拓扑，需要传入其Id
storm kill monitor-value-stat-topology

注意，JAR的入口函数必须调用submitTopology。

本节列出常见的拓扑模式（Pattern）。

很多情况下，出于效率的考虑，你可能希望一批批的处理元组，而不是一个个的。例如，你可能希望批量的将元组入库，以利用数据库的吞吐能力。

你可以简单的将元组存储到实例变量中，等到积累的足够多了，批量的处理它们然后统一Ack。

如果执行批处理的Bolt释放元组，你可能需要使用多重锚定，确定输出元组和输入元组之间的因果关系。

很多Bolt都是读取一个输入元组、处理后根据此元组释放0-N个元组，最后对输入元组进行Ack。基于IBasicBolt可以获得此模式的封装。

经过字段分组之后，该字段一样的元组总是由同一个Bolt处理。假设Bolt需要根据该字段进行某种转换，那么在Bolt实例变量中缓存这种转换结果，其缓存性能会较高。

例如，一个Bolt负责接收短URL并展开它，展开需要通过HTTP来调用第三方服务，因此缓存展开URL很有必要。可以在Bolt中创建一个短URL到展开URL的HashMap作为缓存。配合字段分组，让相同短URL总是分发给同一Bolt实例，这样上述缓存的命中率会比不分组高得多。

某些情况下，你需要处理很多输入元组，并且释放出其中最xx的10个元组。

最简单的方案是，使用全局流分组，也就是让所有元组都输入到单个Bolt实例中。这种方案可能会导致性能瓶颈。

一个改进的方案是，让多个Bolt都进行TopN计算，在一个下游的Bolt中，重新进行一次TopN计算：

builder.setBolt("rank", new RankObjects(), parallelism)
    .fieldsGrouping("objects", new Fields("value"));  // 字段分组，每个实例进行自己的TopN计算
builder.setBolt("merge", new MergeObjects())
    .globalGrouping("rank");   // 全局分组，但是要处理的数据量很少，不会出现瓶颈

我们知道，基于ack/fail可以保证消息：

1. 要么完全通过拓扑
2. 要么，可选的，进行Replay

问题是，如果进行Replay时，如何保证事务性？或者说，如何保证某些逻辑不会重复执行。

从0.7开始，Storm引入了事务性拓扑，可以保证Replay安全的进行，确保它们仅仅被处理一次。

在事务性拓扑中，Storm混合使用并行、串行的元组处理流。Spout生成的一批元组，被并行的发送给Bolt处理。某些Bolt被称为Committer，它们按照严格有序的方式提交已经被处理过的元组批次。

例如，Spout释放两个元组批次，每个批次包含5个元组，这两个元组被并发的交付Bolt处理，但是，如果链条中存在Committer Bolt，则在此Bolt批次必须严格有序的串行化 —— 它不会在第一个批次成功提交之前，提交第二个批次。

Storm事务由两个部分阶段组成：

1. 处理阶段：完全并行阶段，很多批次可以被同时的执行
2. 提交阶段：完全有序阶段，保证批次按照顺序逐一执行

我们以一个Twitter分析工具的例子来了解事务性拓扑的工作机制。此工具的逻辑如下：

1. 读取Tweets并存储到Redis
2. 通过若干Bolt处理Tweets
3. 将处理结果存放到另一个Redis数据库，处理结果包括：所有主题标签（Hashtag）的及其出现次数、用户及其出现在Tweet中的次数、主题标签和用户出现在同一Tweet中的次数

用于构建此工具的拓扑示意如下：

说明如下：

1. TweetsTransactionalSpout连接到数据源，读取并释放元组批次到拓扑
2. 随后的两个Bolt会接受所有元组
   1.  UserSplitterBolt，从Tweet中搜索用户（@之后的单词）
   2. HashatagSplitter，从Tweet中搜索主题标签（#之后的单词）
3. 后面的UserHashtagJoinBolt，对前面两个Bolt的结果进行Join，获得每个用户+标签的组合同时出现的次数。此Bolt是BaseBatchBolt的子类型
4. 最后的RedisCommitterBolt是一个Committer，它接受3个流。进行各种统计，并在处理完一批次后进行入库

相关说明已经附加在源码注释：

package cc.gmem.study.storm.twt;

import org.apache.storm.coordination.BatchOutputCollector;
import org.apache.storm.task.TopologyContext;
import org.apache.storm.topology.BasicOutputCollector;
import org.apache.storm.topology.OutputFieldsDeclarer;
import org.apache.storm.topology.base.BaseBasicBolt;
import org.apache.storm.topology.base.BaseBatchBolt;
import org.apache.storm.topology.base.BaseTransactionalBolt;
import org.apache.storm.topology.base.BaseTransactionalSpout;
import org.apache.storm.transactional.ICommitter;
import org.apache.storm.transactional.ITransactionalSpout;
import org.apache.storm.transactional.TransactionAttempt;
import org.apache.storm.transactional.TransactionalTopologyBuilder;
import org.apache.storm.tuple.Fields;
import org.apache.storm.tuple.Tuple;
import org.apache.storm.tuple.Values;
import redis.clients.jedis.Jedis;
import redis.clients.jedis.Transaction;

import java.io.Serializable;
import java.math.BigInteger;
import java.util.*;

public class TwitterAnalyticsTool {

    /* 封装Redis相关操作 */
    public static class RQ {

        // 存放下一个读取游标的键
        public static final String NEXT_READ = "NEXT_READ";

        // 存放下一个写入游标的键
        public static final String NEXT_WRITE = "NEXT_WRITE";

        Jedis jedis;

        public RQ() {
            jedis = new Jedis( "localhost" );
        }

        /* 可读Tweet量 */
        public long getAvailableToRead( long current ) {
            return getNextWrite() - current;
        }

        public long getNextRead() {
            String sNextRead = jedis.get( NEXT_READ );
            if ( sNextRead == null )
                return 1;
            return Long.valueOf( sNextRead );
        }

        public long getNextWrite() {
            return Long.valueOf( jedis.get( NEXT_WRITE ) );
        }

        public void close() {
            jedis.disconnect();
        }

        public void setNextRead( long nextRead ) {
            jedis.set( NEXT_READ, "" + nextRead );
        }

        /* 从指定游标from开始，读取quantity条Tweet */
        public List<String> getMessages( long from, int quantity ) {
            String[] keys = new String[quantity];
            for ( int i = 0; i < quantity; i++ ) keys[i] = "" + ( i + from );
            return jedis.mget( keys );
        }
    }

    /**
     * 事务元数据，释放元组批次时用到此元数据：
     * from 事务的起始游标
     * quantity 事务处理Tweet的数量
     * <p>
     * 元数据必须包含Replay此事务所牵涉到的批次的所需要的全部信息
     */
    public static class TransactionMetadata implements Serializable {

        private static final long serialVersionUID = 1L;

        long from;

        int quantity;

        public TransactionMetadata( long from, int quantity ) {
            this.from = from;
            this.quantity = quantity;
        }
    }

    /**
     * 协调器，整个拓扑中仅仅有单个协调器实例
     */
    public static class TweetsTransactionalSpoutCoordinator implements ITransactionalSpout.Coordinator<TransactionMetadata> {

        private static final long MAX_TRANSACTION_SIZE = 16;

        RQ rq = new RQ();

        long nextRead = 0;

        public TweetsTransactionalSpoutCoordinator() {
            nextRead = rq.getNextRead();
        }

        /**
         * 根据上一次事务的元数据，确定本次事务的元数据
         * <p>
         * 元数据必须包含Replay此事务所牵涉到的批次的所需要的全部信息
         * <p>
         * 元数据被存放在ZooKeeper中，以txid为键。如果事务失败，Storm可以通过Emtter重放此事务
         *
         * @param txid         本次事务标识符，此事务从未被提交过
         * @param prevMetadata 上一个事务的元数据
         * @return 本次事务的元数据
         */
        @Override
        public TransactionMetadata initializeTransaction( BigInteger txid, TransactionMetadata prevMetadata ) {
            long quantity = rq.getAvailableToRead( nextRead );
            quantity = quantity > MAX_TRANSACTION_SIZE ? MAX_TRANSACTION_SIZE : quantity;
            TransactionMetadata ret = new TransactionMetadata( nextRead, (int) quantity );
            nextRead += quantity;
            return ret;
        }

        /**
         * 如果可以发起新事务，返回true。如果不可以，应当睡眠一段时间然后返回false
         * 如果此方法返回true，initializeTransaction()被调用
         *
         * @return
         */
        @Override
        public boolean isReady() {
            return rq.getAvailableToRead( nextRead ) > 0;
        }

        @Override
        public void close() {
            rq.close();
        }
    }

    /**
     * 发射器，根据事务元数据，从数据源读取一批次数据，并释放到流中
     */
    public static class TweetsTransactionalSpoutEmitter implements ITransactionalSpout.Emitter<TransactionMetadata> {

        RQ rq = new RQ();

        /**
         * 释放一个批次，此方法的实现一定要能够重复执行 ———— 根据txId、txMeta必须可以重新释放此批次
         *
         * @param tx        当前事务尝试
         * @param txMeta    事务元数据
         * @param collector 用于释放元组
         */
        @Override
        public void emitBatch( TransactionAttempt tx, TransactionMetadata txMeta, BatchOutputCollector collector ) {
            // 移动读游标
            if ( tx.getAttemptId() == 0 ) { // attempt id存放当前事务重复的次数，由此可以推断是否Replay
                rq.setNextRead( txMeta.from + txMeta.quantity );
            }
            // 读取一批消息
            List<String> messages = rq.getMessages( txMeta.from, txMeta.quantity );
            long tweetId = txMeta.from;
            // 下面释放的消息都在批次中
            for ( String message : messages ) {
                collector.emit( new Values( tx, String.valueOf( tweetId ), message ) );
                tweetId++;
            }
        }

        @Override
        public void cleanupBefore( BigInteger txid ) {
        }

        @Override
        public void close() {
            rq.close();
        }
    }

    /**
     * 和普通的Spout不同，事务性Spout扩展自泛型接口BaseTransactionalSpout
     */
    public static class TweetsTransactionalSpout extends BaseTransactionalSpout<TransactionMetadata> {

        /* 指定用来协调批次生成的协调器 */
        @Override
        public Coordinator<TransactionMetadata> getCoordinator( Map conf, TopologyContext context ) {
            return new TweetsTransactionalSpoutCoordinator();
        }

        /* 指定发射器，负责读取源中的一批元组，并释放到流中 */
        @Override
        public Emitter<TransactionMetadata> getEmitter( Map conf, TopologyContext context ) {
            return new TweetsTransactionalSpoutEmitter();
        }

        @Override
        public void declareOutputFields( OutputFieldsDeclarer declarer ) {
            declarer.declare( new Fields( "txid", "tweet_id", "tweet" ) );
        }
    }

    /* 针对当前Tweet中每个@的用户，释放一个 tweetId,userId 元组 */
    public static class UserSplitterBolt extends BaseBasicBolt {

        private static final long serialVersionUID = 1L;

        @Override
        public void execute( Tuple input, BasicOutputCollector collector ) {
            String tweetId = input.getStringByField( "tweet_id" );
            String tweet = input.getStringByField( "tweet" );
            StringTokenizer strTok = new StringTokenizer( tweet, " " );
            TransactionAttempt tx = (TransactionAttempt) input.getValueByField( "txid" );
            HashSet<String> users = new HashSet<String>();
            while ( strTok.hasMoreTokens() ) {
                String user = strTok.nextToken();
                // 如果一个Tweet中，用户出现两次，仅仅计算一次
                if ( user.startsWith( "@" ) && !users.contains( user ) ) {
                    // 释放到users流
                    collector.emit( "users", new Values( tx, tweetId, user ) );
                    users.add( user );
                }
            }
        }

        @Override
        public void declareOutputFields( OutputFieldsDeclarer declarer ) {
            // 声明非默认流
            declarer.declareStream( "users", new Fields( "txid", "tweet_id", "user" ) );
        }
    }

    /* 针对当前Tweet中每个主题标签，释放一个 tweetId,hashTag 元组 */
    public static class HashtagSplitterBolt extends BaseBasicBolt {

        @Override
        public void execute( Tuple input, BasicOutputCollector collector ) {
            String tweet = input.getStringByField( "tweet" );
            String tweetId = input.getStringByField( "tweet_id" );
            StringTokenizer strTok = new StringTokenizer( tweet, " " );
            TransactionAttempt tx = (TransactionAttempt) input.getValueByField( "txid" );
            HashSet<String> words = new HashSet<String>();
            while ( strTok.hasMoreTokens() ) {
                String word = strTok.nextToken();
                if ( word.startsWith( "#" ) && !words.contains( word ) ) {
                    collector.emit( "hashtags", new Values( tx, tweetId, word ) );
                    words.add( word );
                }
            }
        }

        @Override
        public void declareOutputFields( OutputFieldsDeclarer declarer ) {
            // 声明非默认流
            declarer.declareStream( "hashtags", new Fields( "txid", "tweet_id", "hashtag" ) );
        }
    }

    /**
     * UserHashtagJoinBolt是一个BaseBatchBolt，这意味着：
     * 1、execute处理接收到的元组，但是不释放任何新元组
     * 2、在本批次的元组处理完毕后，Storm自动调用finishBatch
     */
    public static class UserHashtagJoinBolt extends BaseBatchBolt {

        /* 每个Tweet都有哪些Tag */
        private Map<String, Set<String>> tweetHashtags;

        /* 每个用户都被哪些Tweet @ */
        private Map<String, Set<String>> userTweets;

        private BatchOutputCollector collector;

        private Object id;

        private void add( Map<String, Set<String>> map, String key, String val ) {
            Set<String> vals = map.get( key );
            if ( vals == null ) {
                vals = new HashSet<>();
                map.put( key, vals );
            }
            vals.add( val );
        }

        /**
         * 对于每一个事务，都会调用此方法
         *
         * @param id 事务标识符
         */
        @Override
        public void prepare( Map conf, TopologyContext context, BatchOutputCollector collector, Object id ) {
            tweetHashtags = new HashMap<>();
            userTweets = new HashMap<>();
            this.collector = collector;
            this.id = id;
        }

        /* 生成两个映射关系 */
        @Override
        public void execute( Tuple tuple ) {
            String source = tuple.getSourceStreamId();
            String tweetId = tuple.getStringByField( "tweet_id" );
            if ( "hashtags".equals( source ) ) {
                String hashtag = tuple.getStringByField( "hashtag" );
                add( tweetHashtags, tweetId, hashtag );
            } else if ( "users".equals( source ) ) {
                String user = tuple.getStringByField( "user" );
                add( userTweets, user, tweetId );
            }
        }

        /* 处理完当前批次后调用。进行JOIN操作，得到每个用户和每个主题标签一起被提及的频率 */
        @Override
        public void finishBatch() {
            for ( String user : userTweets.keySet() ) {
                Set<String> tweets = getUserTweets( user );
                HashMap<String, Integer> hashtagsCounter = new HashMap<String, Integer>();
                for ( String tweet : tweets ) {
                    Set<String> hashtags = getTweetHashtags( tweet );
                    if ( hashtags != null ) {
                        for ( String hashtag : hashtags ) {
                            Integer count = hashtagsCounter.get( hashtag );
                            if ( count == null ) count = 0;
                            count++;
                            hashtagsCounter.put( hashtag, count );
                        }
                    }
                }
                for ( String hashtag : hashtagsCounter.keySet() ) {
                    int count = hashtagsCounter.get( hashtag );
                    collector.emit( new Values( id, user, hashtag, count ) );
                }
            }
        }

        private Set<String> getTweetHashtags( String tweet ) {
            return tweetHashtags.get( tweet );
        }

        private Set<String> getUserTweets( String user ) {
            return userTweets.get( user );
        }

        @Override
        public void declareOutputFields( OutputFieldsDeclarer declarer ) {
            declarer.declare( new Fields( "txid", "user", "hashtag", "count" ) );
        }
    }

    /**
     * RedisCommiterCommiterBolt是一个Committer，这是由标记性接口ICommitter指定的。
     * 你也可以TransactionalTopologyBuilder.setCommiterBolt将一个Bolt设置为Committer
     * <p>
     * 和普通BaseBatchBolt不同之处是，Committer的finishBatch方法仅仅在可以提交的时候才执行，也就是说
     * 只有当前面的所有事务均成功提交之后，Committer才会提交当前事务。
     * <p>
     * 同一拓扑中所有事务，在Committer都是串行执行的
     */
    public static class RedisCommiterCommiterBolt extends BaseTransactionalBolt implements ICommitter {

        public static final String LAST_COMMITED_TRANSACTION_FIELD = "LAST_COMMIT";

        TransactionAttempt id;

        BatchOutputCollector collector;

        Jedis jedis;

        HashMap<String, Long> hashtags = new HashMap<String, Long>();

        HashMap<String, Long> users = new HashMap<String, Long>();

        HashMap<String, Long> usersHashtags = new HashMap<String, Long>();

        private void count( HashMap<String, Long> map, String key, int count ) {
            Long value = map.get( key );
            if ( value == null ) value = (long) 0;
            value += count;
            map.put( key, value );
        }

        @Override
        public void prepare( Map conf, TopologyContext context, BatchOutputCollector collector, TransactionAttempt id ) {
            this.id = id;
            this.collector = collector;
            this.jedis = new Jedis( "localhost" );
        }

        @Override
        public void execute( Tuple tuple ) {
            String origin = tuple.getSourceComponent();
            if ( "users-splitter".equals( origin ) ) {
                String user = tuple.getStringByField( "user" );
                count( users, user, 1 );
            } else if ( "hashtag-splitter".equals( origin ) ) {
                String hashtag = tuple.getStringByField( "hashtag" );
                count( hashtags, hashtag, 1 );
            } else if ( "user-hashtag-merger".equals( origin ) ) {
                String hashtag = tuple.getStringByField( "hashtag" );
                String user = tuple.getStringByField( "user" );
                String key = user + ":" + hashtag;
                Integer count = tuple.getIntegerByField( "count" );
                count( usersHashtags, key, count );
            }
        }

        /**
         * 一定要记住：保存上一次事务的ID，在执行提交时，再次检查此ID是否和当前事务ID重复
         *
         * 这样可以防止Replay时，入库逻辑被重复执行
         */
        @Override
        public void finishBatch() {
            // 获得上一次事务ID
            String lastCommitedTransaction = jedis.get( LAST_COMMITED_TRANSACTION_FIELD );
            String currentTransaction = String.valueOf( id.getTransactionId() );
            // 当前事务已经提交过，直接返回
            if ( currentTransaction.equals( lastCommitedTransaction ) ) return;
            // 开启Redis事务
            Transaction multi = jedis.multi();
            // 更新上一次事务ID
            multi.set( LAST_COMMITED_TRANSACTION_FIELD, currentTransaction );
            Set<String> keys = hashtags.keySet();
            // 更新统计信息
            for ( String hashtag : keys ) {
                Long count = hashtags.get( hashtag );
                multi.hincrBy( "hashtags", hashtag, count );
            }
            keys = users.keySet();
            for ( String user : keys ) {
                Long count = users.get( user );
                multi.hincrBy( "users", user, count );
            }
            keys = usersHashtags.keySet();
            for ( String key : keys ) {
                Long count = usersHashtags.get( key );
                multi.hincrBy( "users_hashtags", key, count );
            }
            multi.exec();
        }

        @Override
        public void declareOutputFields( OutputFieldsDeclarer declarer ) {

        }

    }

    @SuppressWarnings( "deprecation" )
    public static void main( String[] args ) {
        // 可以使用TransactionalTopologyBuilder构建事务性拓扑，目前此类的功能已经被Trident代替
        String topoId = "twitter-analytics-tool";  // 拓扑的标识符，Storm基于此标识符在ZooKeeper中存储事务性Spout的状态
        String spoutId = "spout";                  // Spout的标识符
        TransactionalTopologyBuilder builder = new TransactionalTopologyBuilder( topoId, spoutId, new TweetsTransactionalSpout() );
        builder.setBolt( "users-splitter", new UserSplitterBolt(), 4 ).shuffleGrouping( "spout" );
        builder.setBolt( "hashtag-splitter", new HashtagSplitterBolt(), 4 ).shuffleGrouping( "spout" );
        builder.setBolt( "user-hashtag-merger", new UserHashtagJoinBolt(), 4 )
               .fieldsGrouping( "users-splitter", "users", new Fields( "tweet_id" ) )
               .fieldsGrouping( "hashtag-splitter", "hashtags", new Fields( "tweet_id" ) );
        builder.setBolt( "redis-committer", new RedisCommiterCommiterBolt() )
               .globalGrouping( "users-splitter", "users" )
               .globalGrouping( "hashtag-splitter", "hashtags" )
               .globalGrouping( "user-hashtag-merger" );
    }
}

事务性拓扑提供了一种可靠的批量处理语义，其关键在于：

1. 提供了组装元组批次，也就是事务的机制，并且信息持久化在ZooKeeper中，不会因为宕机而丢失
2. 提供了串行有序执行语义，你只需要记录一个事务标识符 —— 上一个事务的标识符，因为任何时刻只会有一个事务正在准备提交

流是连续不断的元组序列。任何Spout、Bolt都可以释放0-N个流。

通过

JoinBolt

每个参与合并的流，必须是根据Join字段进行分fieldsGrouping，也就是说，Join字段一样的元组必须由同一Task处理。

考虑如下SQL语句：

select  userId, key4, key2, key3
from        table1
inner join  table2  on table2.userId =  table1.key1
inner join  table3  on table3.key3   =  table2.userId
left join   table4  on table4.key4   =  table3.key3

对应的流连接如下：

JoinBolt jbolt =  new JoinBolt("spout1", "key1")                   // from        spout1  
                    //         我组件       我键       他组件
                    .join     ("spout2", "userId",  "spout1")      // inner join  spout2  on spout2.userId = spout1.key1
                    .join     ("spout3", "key3",    "spout2")      // inner join  spout3  on spout3.key3   = spout2.userId   
                    .leftJoin ("spout4", "key4",    "spout3")      // left join   spout4  on spout4.key4   = spout3.key3
                    // 选择输出字段
                    .select  ("userId, key4, key2, spout3:key3")   // chose output fields
                    // 滚动窗口，时长10分钟
                    .withTumblingWindow( new Duration(10, TimeUnit.MINUTES) ) ;
                    // 你也可以调用withWindow()配置滑动窗口

topoBuilder.setBolt("joiner", jbolt, 1)
            // 参与连接的流必须以Join字段分组
            .fieldsGrouping("spout1", new Fields("key1") )
            .fieldsGrouping("spout2", new Fields("userId") )
            .fieldsGrouping("spout3", new Fields("key3") )
            .fieldsGrouping("spout4", new Fields("key4") );

在Join某个流之前，你必须先引入它： 

new JoinBolt( "spout1", "key1") 
      // arg0引入              arg2连接到                
  .join( "spout2", "userId",  "spout3") // 错误：spout3尚未引入
  .join( "spout3", "key3",    "spout1");

实际Join发生的顺序，就是用户声明的顺序。

上面流连接的例子中，都使用了组件名称，而不是流名称。Storm支持基于流名称连接，但是很多组件仅仅释放一个流，且流名称默认为default，要基于流名称连接，必须先定义好命名流。

// 提示此JoinBolt基于流名称而非组件名称引用参与连接的流
new JoinBolt(JoinBolt.Selector.STREAM,  "stream1", "key1").join("stream2", "key2");
topoBuilder.setBolt("joiner", jbolt, 1)
    //              配置流分组时要指定流的名称
    .fieldsGrouping("bolt1", "stream1", new Fields("key1") )

1. 目前仅仅支持内连接（INNER）和左连接（LEFT）
2. SQL支持针对一个表，通过多个字段分别Join。Storm不支持，每个流有且仅有一个字段能用于Join，该字段用于流分组，确保键相同的分组发送给同一Task
3. 要使用多字段连接，你需要将它们合并为单个字段
4. 连接操作可能占用很高的CPU和内存。当前窗口中累积的数据越多，则连接消耗的时间越长。使用滑动窗口时，越短的滑动间隔导致越频繁的连接操作。因此太长的窗口、太短的滑动间隔都可能导致性能问题
5. 使用滑动窗口时，多个窗口之间可能存在重复的Joined记录，这是因为这些记录的源元组可能跨越多个窗口存在
6. 如果使用消息超时，应当正确设置topology.message.timeout.sec，确保它能够匹配窗口大小，同时考虑拓扑中其它组件可能消耗的时间
7. 连接两个流时，假设窗口大小分别为M、N，那么最坏的情况下可能产生M x N个输出元组，下游Bolt将会释放更多的ACK。这种情况下，Storm的消息子系统可能面临很大的压力，不小心使用可能导致拓扑运行缓慢。下面是管理消息子系统的一些建议：
   1. 增加Worker的堆大小：

      topology.worker.max.heap.size.mb

   2. 如果拓扑不需要ACK，可以禁用它：

      topology.acker.executors=0

   3. 禁用事件记录器：

      topology.eventlogger.executor=0

   4. 禁用拓扑调试功能：

      topology.debug=false

   5. topology.max.spout.pending

      设置要匹配完整窗口需要的大小，附加额外的一些空间。这可以避免消息子系统过载时Spout仍然不停释放元组，该项设置为null时更容易发生此情况
   6. 在能够满足需求的情况下，窗口应该尽量的小

本章主要讨论设计拓扑入口点 —— Spout的通用策略，以及如何让Spout支持容错。

在设计拓扑时，考虑消息可靠性需求是一个重要事项。当一个消息无法完成处理时，你需要决定针对此消息进行怎样的处理？整个拓扑有应该有怎样的行为。打个比方，在处理银行存款业务时，每个交易消息都不能丢失；单是在处理百万级数据的统计信息时，丢失一部分消息则不会对结果精确性产生太大影响。

在Storm中，拓扑的设计者负责保证消息的可靠性。这常常需要权衡考虑，因为拓扑需要更多的资源以管理消息不丢失。

你可以在释放元组时为其指定标识符：

// 此重载版本为SpoutOutputCollector特有，Bolt使用的OutputCollector没有此方法
collector.emit(new Values(...),tupleId)

如果不指定标识符，Storm会自动生成一个。在消费者中可以调用

input.getMessageId()

当消费者针对元组进行ack/fail操作时，生产者的ack/fail回调会被调用，并传入确认/失败的那个元组。至于如何处理失败的元组，需要根据具体业务场景决定，常见的做法是放回消息队列。

引起元组失败的原因有两种：

1. 消费者调用

   collector.fail(tuple)

2. 元组处理的时间超过配置的时限，

   Config.TOPOLOGY_MESSAGE_TIMEOUT_SECS

最简单的接入方式是Spout直接连接到数据源（Message Emitter）。如果数据源是明确的（Well-known）的设备（在这里是一个抽象概念，理解为一般性的数据源即可）或者设备组，这种方式实现起来很简单。

所谓明确的，是指在拓扑启动时设备就就是已知的（Known）并且在拓扑运行期间它保持不变。所谓未知设备，就是在拓扑运行之后才添加进来的。

所谓明确设备组，就是其中所有设备都是已知的一组设备。

下面是一个基于Twitter流API的拓扑，它使用直接连接的接入方式：

package cc.gmem.study.storm.twt;

import com.esotericsoftware.kryo.util.IdentityMap;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.apache.storm.shade.org.apache.http.HttpResponse;
import org.apache.storm.shade.org.apache.http.StatusLine;
import org.apache.storm.shade.org.apache.http.client.CredentialsProvider;
import org.apache.storm.shade.org.apache.http.client.methods.HttpGet;
import org.apache.storm.shade.org.apache.http.impl.client.DefaultHttpClient;
import org.apache.storm.spout.SpoutOutputCollector;
import org.apache.storm.task.TopologyContext;
import org.apache.storm.topology.OutputFieldsDeclarer;
import org.apache.storm.topology.base.BaseRichSpout;
import org.apache.storm.tuple.Fields;
import org.apache.storm.tuple.Values;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.util.Map;

public class TwitterStreamSpout extends BaseRichSpout {

    private static final String STREAMING_API_URL = "...";

    private CredentialsProvider credentialProvider;

    private String track;

    private ObjectMapper om;

    private SpoutOutputCollector collector;

    @Override
    public void open( Map conf, TopologyContext context, SpoutOutputCollector collector ) {
        // 任何组件都可以访问拓扑上下文，其中包含了拓扑的所有全局性信息
        // 获得当前Spout的实例数量
        int spoutsSize = context.getComponentTasks( context.getThisComponentId() ).size();
        // 获得当前Spoput实例的Id
        int myIdx = context.getThisTaskIndex();
        String[] tracks = ( (String) conf.get( "track" ) ).split( "," );
        StringBuffer tracksBuffer = new StringBuffer();
        for ( int i = 0; i < tracks.length; i++ ) {
            // 让各Spout实例处理不同的track关键字
            if ( i % spoutsSize == myIdx ) {
                tracksBuffer.append( "," );
                tracksBuffer.append( tracks[i] );
            }
        }
        this.track = tracksBuffer.substring( 1 );
        this.collector = collector;
    }

    @Override
    public void nextTuple() {
        // 通过HTTP获取消息
        DefaultHttpClient client = new DefaultHttpClient();
        client.setCredentialsProvider( credentialProvider );
        // 让每个Spout实例跟踪不同的track关键字
        HttpGet get = new HttpGet( STREAMING_API_URL + this.track );
        HttpResponse response;
        try {
            response = client.execute( get );
            StatusLine status = response.getStatusLine();
            if ( status.getStatusCode() == 200 ) {
                InputStream inputStream = response.getEntity().getContent();
                BufferedReader reader = new BufferedReader( new InputStreamReader( inputStream ) );
                String in;
                // 逐行读取
                while ( ( in = reader.readLine() ) != null ) {
                    // 解析并释放元组
                    Object json = om.readValue( in, Map.class );
                    collector.emit( new Values( this.track, json ) );
                }
            }
        } catch ( IOException e ) {
            // 连接到Twitter API失败，可以休眠一段时间后重试
        }
    }


    @Override
    public void declareOutputFields( OutputFieldsDeclarer declarer ) {
        declarer.declare( new Fields( "track", "content" ) );
    }
}

注意上面的例子中用到Storm的一个重要特性 —— 在任何组件中访问TopologyContext。利用TopologyContext你可以感知到Spout的Task数量，然后将不同数据源映射到不同的Task，增加拓扑的并行度。

上面是连接到明确的设备的例子，通过类似的方式，可以直接连接到未知设备。但是你需要一个协调（Coordinator）系统来维护可用设备的列表。例如，当进行Web服务器日志分析时，Web服务器的列表可能动态变化。当一个新的Web服务器加入后，Coordinator检测到并为其创建一个Spout。

当建立连接时，应当总是由Spout发起，而不是由数据源发起。因为运行Spout的服务器宕机后Storm可能在另外一台机器上重启此Spout，数据源难以精确的定位到Spout。

除了直接连接，你还可以使用消息队列系统。Spout连接到消息队列读取消息，数据源则把消息发布到消息队列。

消息中间件软件通常都提供可靠性、持久化等保证，这简化了开发任务。使用消息中间件后Spout对数据源毫无感知。

使用消息列队这种接入方式时，如果想增加Spout并行度，可以：

1. 让Spout循环轮询（Round-robin Poll）同一队列
2. 基于哈希再分发：根据哈希值将消息分发给不同Spout，或者分发到不同的子队列。Spout读取子队列。Kafka是一个很好的支持子队列（分区）的消息中间件

Bolt是拓扑中的关键组件，大部分逻辑都发生在Bolt链中。

Bolt这类组件，以元组为输入，可选的，它也能够输出元组。

在创建Bolt时，你需要实现IRichBolt接口。Bolt在客户端创建，然后串行化到拓扑，最后整个拓扑被提交到Storm集群的Master节点。集群会启动工作节点（JVM进程）来运行拓扑组件，Bolt会被反串行化，其prepare方法会被调用，然后开始接受元组。

Storm确保Spout释放的所有元组都能传递给相应的Bolt，至于Bolt是否保证信息堡丢失，由开发人员决定。

拓扑是组件构成的网络，Spout释放的元组，是网络中传递的信息。信息经过不同组件之后，可能分裂、合并，这和Bolt灵活的Tuple处理机制有关：

1. 可以根据一个输入元组产生多个输出元组
2. 可以根据多个输入元组产生一个输出元组

从框架角度来说，无法自动推导输入、输出元组的对应关系。因此在Storm中你需要利用锚定（Anchoring）技术手工指定。

以从Spout发出的原初元组为根，其衍生的任何元组被fail，则此原初元组也就fail，发起此元组的Spout的fail回调自动被调用。

每个Spout/Bolt都可以声明多个输出流，标识符为default的默认流自动声明。要声明新的流，可以调用：

declarer.declareStream( streamId, fields );

要向指定的流释放元组，调用：

collector.emit( streamId, tuple );

前面提到过，要追踪信息流动方向，需要使用锚定技术。也就是指定输入、输出元组之间的关联关系：

// 此重载版本为OutputCollector特有
collector.emit( inputTuple, outputTuple );

有了这种调用后，Storm才可以对原初元组进行有效的追踪。

如果输出元组基于多个输入元组推导出，可以一起锚定它们：

List<Tuple> anchors = new ArrayList<Tuple>();
anchors.add( inputTuple1 );
anchors.add( inputTuple2 );
collector.emit( anchors, outputTuple );

如果outputTuple失败，则产生inputTuple1、inputTuple2的Spout都会得到通知。 

Storm会在此接口的实现的execute()执行后，自动调用ack，如果execute()抛出异常，则自动调用fail。你可以考虑继承BaseBasicBolt。

Storm提供了一个抽象，允许Bolt存储/取回其操作的状态信息。该抽象有两个实现，一个是基于内存的默认实现，另一个以Redis作为后备存储。

需要状态管理功能的Bolt，需要实现IStatefulBolt接口或者继承BaseStatefulBolt，并实现initState方法。Storm在初始化Bolt实例时，调用initState并传入上次存储的状态，调用发生在prepare之后，处理任何元组之前。

当前仅仅支持的状态实现是org.apache.storm.state.KeyValueState。

分布式远程过程调用（Distributed Remote Procedure Call）利用Storm的计算能力进行远程调用。Storm提供了一系列DRPC的支持工具。

DRPC流程示意

说明：

1. 客户端向DRPC服务器发起同步调用
2. DRPC将请求转发给DRPC Spout，进而在拓扑异步的处理
3. 处理结果由最后一个Bolt返回给DRPC服务器。并返回给客户端 

DRPC服务器是客户端和Storm拓扑之间的桥梁，它作为拓扑中Spout的源运行。

DRPC服务器接受需要执行的函数及其参数，它可以执行多个函数，函数通过名称唯一识别。

对于每一次函数调用，服务器分配一个请求Id，用于在拓扑中唯一的识别调用请求。当拓扑中最后一个Bolt执行完毕后，此Bolt必须释放出包含请求Id、调用结果的数组，DRPC会把结果分发给正确的客户端。

注意：目前此类已经被废弃，其功能由Trident代替。

用于构建DRPC拓扑的抽象。此Builder生成的拓扑会：

1. 自动创建DRPCSpouts，连接DRPC服务器读取请求，并释放元组到拓扑的其它部分
2. 对Bolts进行包装，让调用结果从最后一个Bolt返回

所有添加到LinearDRPCTopologyBuilder的Bolt均按序依次执行

要提交拓扑到Storm集群，可以调用LinearDRPCTopologyBuilder的createRemoteTopology（而不是createLocalTopology），此方法会利用Storm配置中的DRPC相关配置。

要连接到DRPC服务器，使用此类，此类是ThriftClient的子类型。

DRPC服务器暴露了基于Thrift的API，可以在很多语言中使用此API。并且，不管DRPC服务器是本地还是远程的，API完全一样。

下面是一个简单的加法计算器：

package cc.gmem.study.storm.drpc;

import org.apache.storm.Config;
import org.apache.storm.LocalCluster;
import org.apache.storm.LocalDRPC;
import org.apache.storm.drpc.LinearDRPCTopologyBuilder;
import org.apache.storm.generated.StormTopology;
import org.apache.storm.topology.BasicOutputCollector;
import org.apache.storm.topology.OutputFieldsDeclarer;
import org.apache.storm.topology.base.BaseBasicBolt;
import org.apache.storm.tuple.Fields;
import org.apache.storm.tuple.Tuple;
import org.apache.storm.tuple.Values;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class DrpcAdder {

    private static final Logger LOGGER = LoggerFactory.getLogger( DrpcAdder.class );

    public static class AdderBolt extends BaseBasicBolt {

        @Override
        public void execute( Tuple input, BasicOutputCollector collector ) {
            // 元组第一个参数是RPC请求Id
            Object rpcId = input.getValue( 0 );
            // 元组第二个参数是RPC请求参数
            String args = input.getString( 1 );
            String[] numbers = args.split( "," );
            Integer added = 0;

            for ( String num : numbers ) {
                added += Integer.parseInt( num );
            }
            collector.emit( new Values( rpcId, added ) );
        }

        @Override
        public void declareOutputFields( OutputFieldsDeclarer declarer ) {
            // 作为最后一个Bolt，需要释放RPC请求Id
            declarer.declare( new Fields( "id", "result" ) );
        }
    }

    public static void main( String[] args ) {
        // 和DRPCClient一样是DistributedRPC.Iface的实现
        LocalDRPC drpc = new LocalDRPC();

        // 拓扑对应一个远程调用函数
        LinearDRPCTopologyBuilder builder = new LinearDRPCTopologyBuilder( "add" );
        builder.addBolt( new AdderBolt(), 2 );

        Config conf = new Config();
        conf.setDebug( true );

        LocalCluster cluster = new LocalCluster();
        // 创建本地拓扑，需要传入客户端对象
        StormTopology topology = builder.createLocalTopology( drpc );
        cluster.submitTopology( "drpc-adder-topology", conf, topology );

        // 进行一次调用
        String result = drpc.execute( "add", "1,-1" );
        LOGGER.debug( "DRPC result {}", result );

        cluster.shutdown();
        drpc.shutdown();
    }
}

Storm使用调度器在集群中进行拓扑的调度，它提供了四种内置的调度器实现：DefaultScheduler, IsolationScheduler, MultitenantScheduler, ResourceAwareScheduler。

要实现自己的调度器，实现IScheduler接口：

package cc.gmem.study.storm;

import org.apache.storm.scheduler.Cluster;
import org.apache.storm.scheduler.IScheduler;
import org.apache.storm.scheduler.Topologies;

import java.util.Map;

public class Scheduler implements IScheduler {

    @Override
    public void prepare( Map conf ) {

    }

    /**
     * 为需要调度的拓扑设置Assignment，调用cluster.getAssignments()可以得到最新设置的Assignment
     *
     * @param topologies 提交到集群中所有的拓扑，某些拓扑需要被调度
     *                   这里的拓扑对象仅仅包含拓扑的静态信息，Assignment、Slot等信息存在于cluster中
     * @param cluster    拓扑所在的Storm集群，此对象包含开发新调度器所需的全部信息，例如：
     *                   Supervisor信息、可用Slot、当前Assignment
     */
    @Override
    public void schedule( Topologies topologies, Cluster cluster ) {
    }
}

要切换调度器，修改配置文件

storm.yaml

storm.scheduler

此调度器可以让多个拓扑安全、简单的共享单个集群。此调度器允许你隔离某些拓扑 —— 让它在一组专用的机器上执行，其它拓扑不能使用这些专用机器。被隔离的拓扑优先享用集群资源，被所有隔离拓扑占用内，剩下的机器，所有非隔离拓扑共享之。

要启用此调度器，在Nimbus节点的配置文件中进行如下设置：

storm.scheduler: org.apache.storm.scheduler.IsolationScheduler
# 拓扑名称：专用机器数量的映射
isolation.scheduler.machines: 
    "my-topology": 8
    "tiny-topology": 1
    "some-other-topology": 3

Storm支持对一组落到同一“窗口”的元组进行统一的处理。所谓窗口，是被特定条件限定的、连续的元组集合。限定条件有两种：

1. 窗口的长度：包含元组的数量，或者持续的时间
2. 窗口的滑动：每隔多长窗口向前滑动

长度/间隔有两种度量方式：时间、元组数量。

窗口具有一定的长度，并且每隔一段时间，窗口就向前滑动一次。例如下面的滑动窗口示意：

........| e1 e2 | e3 e4 e5 e6 | e7 e8 e9 |...
-5      0       5             10         15    -> time
|<------- w1 -->|
        |<---------- w2 ----->|
                |<-------------- w3 ---->|

窗口的长度是10秒，滑动间隔是5秒。注意元组可能属于多个窗口，每个窗口包含的元组数量可以变化。

窗口具有固定的长度，不同元组仅仅会属于单个窗口。下面是滚动窗口的示意：

| e1 e2 | e3 e4 e5 e6 | e7 e8 e9 |...
0       5             10         15   -> time
    w1        w2           w3

窗口长度是5秒，窗口之间不存在重叠。

要获得窗口化支持，Bolt需要实现IWindowedBolt接口：

public interface IWindowedBolt extends IComponent {
    void prepare(Map stormConf, TopologyContext context, OutputCollector collector);
    // 处理落到窗口中的元组，可选的，释放新的元组
    // 每当一个窗口激活（满了）时，该方法就被调用
    void execute(TupleWindow inputWindow);
    void cleanup();
}

通常情况下，你可以选择继承BaseWindowedBolt类，该类提供了一些指定窗口长度、滑动间隔的方法：

builder.setBolt("slidingwindowbolt", 
                     // 滑动窗口长度 30 元组，滑动间隔 10 元组
                     // 要指定滚动窗口，使用withTumblingWindow方法，要基于时间而非长度，使用Duration
                     new SlidingWindowBolt().withWindow(new Count(30), new Count(10)),
                     1).shuffleGrouping("spout");

默认的，窗口以Bolt处理元组的时间为计算窗口边界的基准。Storm还支持以元组字段给出的时间戳为基准：

// 根据fieldName字段指定的时间（Long型）计算窗口边界
// 如果fieldName字段不存在，导致异常
BaseWindowedBolt.withTimestampField(String fieldName); 

// 另外一种方式，提供一个能够从元组中抽取时间戳的回调函数
BaseWindowedBolt.withTimestampExtractor(TimestampExtractor timestampExtractor);

除了指定时间戳获取方式之外，Storm还允许指定一个最大的延迟参数：

BaseWindowedBolt.withLag(Duration duration); 

如果Bolt接收到一个时间戳为06:00:05的元组，且最大延迟为5s，那么后续不应该再接收到时间戳小于06:00:00的元组。如果的确接收到这样的过期（Late）元组，Storm默认不会处理，仅仅在Worker日志中以INFO级别记录。

要改变上述默认行为，可以调用：

// 过期元组将被释放到streamId流中，后续可以通过WindowedBoltExecutor.LATE_TUPLE_FIELD访问此流
// 必须和withTimestampField一起调用，否则IllegalArgumentException
BaseWindowedBolt.withLateTupleStream(String streamId);

当基于元组字段时间戳计算窗口边界时，Storm内部基于接收到的元组的时间戳来计算水位。所谓水位，就是所有输入流中，所有元组中最晚的那个时间戳减去乱序延迟后得到的数值。

Storm周期性的释放出水位时间戳，此时间戳将作为判断窗口边界是否已经到达的标准。周期默认1s，要修改周期可以调用：

BaseWindowedBolt.withWatermarkInterval(Duration interval)

在协同多个输入流，进行窗口化处理时，水位时间戳相当于一个标准时钟。一旦窗口右边界小于等于此时间戳，就会立刻被处理，且小于此时间戳的后续元组均过期。如果多个输入流释放元组的速度差距很大，那么慢的那些流的元组甚至可能全部成为过期元组。

举个例子，假设基于元组字段时间戳的窗口参数如下：

Window length = 20s, sliding interval = 10s, watermark emit frequency = 1s, max lag = 5s

当前墙上时间为09:00:00，在 09:00:00-09:00:01之间接收到以下元组：

e1(6:00:03), e2(6:00:05), e3(6:00:07), e4(6:00:18), e5(6:00:26), e6(6:00:36)

墙上时间到达09:00:01时，水位时间戳06:00:31（最晚元组时间戳-乱序延迟5）被释放，后续任何时间戳小于06:00:31的元组均过期。水位时间戳导致三个窗口被处理：

05:59:50 - 06:00:10  e1 e2 e3
06:00:00 - 06:00:20  e1 e2 e3 e4
06:00:10 - 06:00:30  e4 e5

将第一个元组的时间戳针对滑动间隔向上取整（这确保它落在第一个窗口中），得到06:00:10，作为第一个窗口的右边界。这样有多少个窗口，窗口边界是哪里都可以推算出来。

元组e6没有落在适当的窗口中，因此此时暂不会被处理。

在09:00:01-09:00:02之间接收到以下元组：

e7(8:00:25), e8(8:00:26), e9(8:00:27), e10(8:00:39)

墙上时间戳到达09:00:02时，水位是按戳08:00:34被释放。水位时间戳导致三个窗口被处理：

06:00:20 - 06:00:40  e5 e6
06:00:30 - 06:00:50  e6
08:00:10 - 08:00:30  e7 e8 e9

第一个窗口的左边界，等于上一批次首个窗口的左边界 + 滑动间隔10。第二个窗口继续右滑10s。

向右滑动跳过N多空窗，得到从08:00:10开始的非空窗，包含了e7-e9。e10所属窗口右边界超出水位时间戳，因此暂不处理。

Storm的窗口化功能，可以提供最少一次处理的保证。

在方法

execute(TupleWindow inputWindow)

对于基于时间的窗口，配置参数topology.message.timeout.secs应当远大于windowLength + slidingInterval，否则元组可能来得及处理之前就超时，导致Replay。

对于基于计数的窗口，配置参数topology.message.timeout.secs应当调整，保证windowLength + slidingInterval个元组能够在超时前得到处理。

Storm提供了一个分布式缓存API，利用它可以高效的分发巨大的、在拓扑生命周期内可能变化的文件（或者叫Blob），这些文件的大小可能在KB-GB之间。

对于小的，不需要动态更新的数据集，可以考虑将其嵌入在JAR中。但是过大的文件则不行，会导致拓扑启动非常缓慢。这种情况下使用分布式缓存可以加快拓扑的启动速度。

在拓扑启动时，用户可以指定拓扑所需要的文件集。在拓扑运行期间，用户可以查询分布式缓存中的任何文件，并更换为新版本。更新行为遵从最终一致性模型。在分布式缓存中，文件基于LRU算法管理。Worker负责确认什么文件不再需要，并删除以释放磁盘空间。

分布式缓存的接口是BlobStore，目前它有两种实现：LocalFsBlobStore、HdfsBlobStore

这是基于本地文件系统的缓存实现。

# 复制因子4，任何人可以读写管，键key1，文件内容在README.txt中
storm blobstore create --file README.txt --acl o::rwa --replication-factor 4 key1

文件的创建由接口ClientBlobStore负责，其实现是NimbusBlobStore。在使用基于本地文件系统的缓存时，NimbusBlobStore调用Nimbus，在其本地文件系统创建文件。

拓扑提交时，JAR和配置文件也是在BlobStore的帮助下上传的，就好像一个普通文件一样。

拓扑启动后，被分配负责运行它的节点的Supervisor会从Nimbus下载JAR、配置文件，并根据topology.blobstore.map确定此拓扑需要使用哪些缓存文件并下载到本地。

在提交拓扑的时候，可以指定该拓扑需要使用哪些文件：

storm jar /path/to/jar class 
    # 文件key1在拓扑中基于名称blob_file访问，不压缩
    -c topology.blobstore.map='{"key1":{"localname":"blob_file", "uncompress":"false"},"key2":{}}'

和基于本地文件系统的缓存实现类似，但是容错性已经由HDFS提供了。

LocalFsBlobStore需要在ZooKeeper中存储状态信息，以便支持Nimbus HA。

文件创建、下载、更新由HdfsClientBlobStore负责。

BlobStore基于键、版本来生成一个哈希码，作为Blob的文件名。Blob存放在blobstore.dir指定的目录，默认值对于本地实现来说是storm.local.dir/blobs，对于HDFS实现是一个类似的路径。

一旦Blob被提交，BlobStore即读取配置并为文件创建元数据，元数据用于访问Blob以及对访问者的进行授权。

对于本地实现，Supervisor节点的缓存大小软限制为10240MB，每隔600s会自动根据LRU算法清理超过软限制的那部分blob。

HDFS实现能够减少Nimbus的负载，而且容错性也不受到Nimbus数量的限制。Supervisor进行blob下载时不需要和Nimbus通信，因此减少了对Nimbus的依赖。

Storm的Master是运行在单台机器上的，在监控工具保护下的进程。一般情况下，Nimbus宕机后会由监控工具重启，不会造成太大问题。但是当Nimbus所在机器出现硬件问题时，例如磁盘损坏，Nimbus就无法启动了。

如果Nimbus无法启动，现有的拓扑能够继续运行，但是无法提交新拓扑。现有的拓扑也不能被杀死、激活、禁用。此外，如果某个Supervisor宕掉，Worker重新分配也无法进行。

因此，实现Nimbus的HA是有必要的，以便：

1. 增加Nimbus总体可用时间
2. 允许Nimbus主机在任何时候加入、离开集群
3. 如果Nimbus宕机，不需要进行任何拓扑重提交
4. 活动的拓扑绝不丢失

实现HA，需要在多个Nimbus节点中选择Leader。Nimbus服务器基于如下接口进行Leader选举：

public interface ILeaderElector {
    /**
     * 排队等待获取Leader锁，该方法立即返回，调用者应该检查自己是否Leader
     */
    void addToLeaderLockQueue();

    /**
     * 将自己从等待Leader锁的队列中移除，如果当前持有锁，释放之
     */
    void removeFromLeaderLockQueue();

    /**
     * 当前节点是否持有了Leader锁
     */
    boolean isLeader();

    /**
     * 返回当前Leader的地址，如果当前没有节点持有锁，则抛出异常
     */
    InetSocketAddress getLeaderAddress();

    /**
     * 返回所有Nimbus节点的地址
     */
    List<InetSocketAddress> getAllNimbusAddresses();
}

Storm提供了基于ZooKeeper的ILeaderElector实现。

为实现Nimbus故障转移，所有状态、数据必须在所有Nimbus节点之间复制，或者存储在外部的分布式存储系统中。BlobStore就可以用作这样的存储系统。

用户可以通过

topology.min.replication.count

当使用基于本地文件系统的BlobStore时，所有Blob的元数据在ZooKeeper中存储；而使用基于HDFS的BlobStore时，HDFS负责管理。

基于Storm CLI使用分布式缓存的方法，请参考blobstore命令。本节给出相应的Java API的例子：

import org.apache.storm.utils.Utils;
import org.apache.storm.blobstore.ClientBlobStore;
import org.apache.storm.blobstore.AtomicOutputStream;
import org.apache.storm.blobstore.InputStreamWithMeta;
import org.apache.storm.blobstore.BlobStoreAclHandler;
import org.apache.storm.generated.*;

// 创建BlobStore客户端
Config conf = new Config();
conf.putAll(Utils.readStormConfig());
ClientBlobStore clientBlobStore = Utils.getClientBlobStore(conf);

// 创建ACL
String stringBlobACL = "u:username:rwa";
AccessControl blobACL = BlobStoreAclHandler.parseAccessControl(stringBlobACL);
List<AccessControl> acls = new LinkedList<AccessControl>();
acls.add(blobACL);
SettableBlobMeta settableBlobMeta = new SettableBlobMeta(acls);
settableBlobMeta.set_replication_factor(4);   // ACL的复制因子

// 创建Blob，并授予ACL
AtomicOutputStream blobStream = clientBlobStore.createBlob("some_key", settableBlobMeta);
blobStream.write("Some String or input data".getBytes());
blobStream.close();

// 更新Blob
String blobKey = "some_key";
AtomicOutputStream blobStream = clientBlobStore.updateBlob(blobKey);

// 更改ACL
String blobKey = "some_key";
AccessControl updateAcl = BlobStoreAclHandler.parseAccessControl("u:USER:--a"); // u:USER:-w-
List<AccessControl> updateAcls = new LinkedList<AccessControl>();
updateAcls.add(updateAcl);
SettableBlobMeta modifiedSettableBlobMeta = new SettableBlobMeta(updateAcls);
clientBlobStore.setBlobMeta(blobKey, modifiedSettableBlobMeta); // 设置Blob元数据

// 设置、读取复制因子
String blobKey = "some_key";
BlobReplication replication = clientBlobStore.updateBlobReplication(blobKey, 5);
int replication_factor = replication.get_replication();

// 读取Blob
String blobKey = "some_key";
InputStreamWithMeta blobInputStream = clientBlobStore.getBlob(blobKey);
BufferedReader r = new BufferedReader(new InputStreamReader(blobInputStream));
String blobContents = r.readLine();

// 删除Blob
String blobKey = "some_key";
clientBlobStore.deleteBlob(blobKey);

// 列出所有Blob
Iterator <String> stringIterator = clientBlobStore.listKeys();

从0.6.0版本开始，Storm使用Kryo作为串行化库，Kryo是一个高性能、灵活的Java串行化框架。它可以产生较紧凑的串行化格式。

默认情况下，Storm能够串行化基本类型、字符串、字节数组、ArrayList、HashMap、HashSet、Clojure集合类型。如果你希望在元组中使用其它类型，需要提供自定义的串行化器。

在声明输出字段时，Storm不支持指定字段的类型。你仅仅需要把对象放入元组，Storm负责动态的识别其类型并串行化。

这个行为和Hadoop不同，Hadoop对键、值进行强制类型，这需要你提供大量的注解。Hadoop这种强制静态类型往往得不偿失。除了出于简单的目的，下面两条也是Storm选择动态类型的原因：

1. 没有办法很好的静态确定元组字段类型。Storm很灵活，一个Bolt可能订阅了多个流，这些流释放的元组字段各不相同
2. 为了便于和JRuby、Clojure这样的动态语言配合

要自定义串行化器，你需要实现Kryo的某些接口。要注册这些串行化器，你需要配置拓扑的topology.kryo.register，此配置项的值是一个列表：

topology.kryo.register:
  # 形式一：指定需要串行化的类型，这种情况下使用Kryo的FieldsSerializer来串行化该类型
  - com.mycompany.CustomType1
  # 形式二：指定类型到串行化器（com.esotericsoftware.kryo.Serializer）的映射
  - com.mycompany.CustomType2: com.mycompany.serializer.CustomType2Serializer

调用

Config.registerSerialization

配置项

Config.TOPOLOGY_SKIP_MISSING_KRYO_REGISTRATIONS

如果Storm遇到某个元组字段，它没有可用的串行化器，则转用Java原生的串行化机制。如果该字段无法基于Java串行化，Storm抛出异常。

注意：Java串行化的成本很高，CPU占用高、输出格式尺寸大。应当尽量避免使用。

配置项

Config.TOPOLOGY_FALL_BACK_ON_JAVA_SERIALIZATION

Storm提供了钩子机制，允许你在任何Storm事件发生时注入自定义代码。扩展BaseTaskHook类，覆盖对应你关心事件的方法即可实现钩子。相关方法包括：emit、spoutAck、spoutFail、boltAck、boltFail、boltExecute。

注册钩子的方法有两种：

1. 在Spout的open、Bolt的prepare方法中，调用TopologyContext的方法注册
2. 通过拓扑配置项topology.auto.task.hooks注册，这样钩子会应用到任何Spout、Bolt。在和外部监控系统集成时，可以使用这种方式

Storm暴露了一个度量（metrics）接口，用于报告整个拓扑的统计信息。在Storm内部，此接口用于元组计数、处理延迟统计、Work堆用量统计，等等。

任何度量都需要实现IMetric接口，该接口仅包含一个方法getValueAndReset，此方法用于执行必要的统计并重置度量为初始值。Storm提供的度量子类型有：

incr()

incrBy(n)

你可以在Bolt中编程式的声明度量、并通过TopologyContext注册：

private transient CountMetric countMetric;

public void prepare(Map conf, TopologyContext context, OutputCollector collector) {
    // 注册度量
    countMetric = new CountMetric();
    // 每60秒自动调用countMetric.getValueAndReset()以重置度量
    context.registerMetric("execute_count", countMetric, 60);
}
public void execute(Tuple input) {
    // 更新度量值
    countMetric.incr();
}

要注册Worker级别度量，可以配置：

1. Config.WORKER_METRICS：针对集群中所有Worker
2. Config.TOPOLOGY_WORKER_METRICS：针对某个拓扑的所有Worker 

上述两个配置的取值都是度量名到度量类的HashMap。

Worker级别度量具有以下限制：

1. 通过SystemBolt注册，不暴露给用户Task
2. 基于默认构造器创建，不会进行任何属性或配置的注入

要消费度量值实现

IMetricsConsumer

conf.registerMetricsConsumer(org.apache.storm.metric.LoggingMetricsConsumer.class, 1);

通过配置文件：

topology.metrics.consumer.register:
  - class: "org.apache.storm.metric.LoggingMetricsConsumer"
    parallelism.hint: 1
  - class: "org.apache.storm.metric.HttpForwardingMetricsConsumer"
    # 消费者对应的Bolt的并行度
    parallelism.hint: 1
    # 消费者的prepare方法接收此参数
    argument: "http://example.com:8080/metrics/my-topology/"

注册消费者后，Storm会在内部为每个消费者添加一个MetricsConsumerBolt（到拓扑），每个MetricsConsumerBolt都会订阅来自任何Task的度量信息。

MetricsConsumerBolt的并行度由parallelism.hint指定，其组件ID为

__metrics_consumerClassFQName#SEQ

注意：消费者仅仅是一个普通的Bolt，如果它本身性能低下，则很多度量值会因而出现偏差。

Storm提供了一些内置的度量消费者，你可以使用它们来了解拓扑提供了哪些度量：

为了调整Nimbus、Supervisor、运行中拓扑的行为，Storm提供了多种配置信息。 某些配置信息是系统级的，不能为每个拓扑定制。 

所有配置项的默认值记录在defaults.yaml中。要覆盖默认值，在Nimbus、Supervisor的Classpath下放置一个storm.yaml文件。

通过 StormSubmitter提交拓扑时，你可以连同自定义配置项一起提交，这些配置项必须以topology.开头。

从Storm 0.7开始，某些配置项可以在Spout/Bolt级别上定制，包括：

1. topology.debug
2. topology.max.spout.pending
3. topology.max.task.parallelism
4. topology.kryo.register

通过Java API，你可以为组件指定上述配置信息，途径有两种：

1. 组件内部配置：覆盖getComponentConfiguration方法
2. 组件外部配置：调用TopologyBuilder的setSpout/setBolt的返回值的addConfiguration/addConfigurations方法。此会覆盖途径1的配置项

配置信息的优先级，从低到高：defaults.yaml  ⇨ storm.yaml  ⇨ 拓扑配置 ⇨ 组件内部配置 ⇨ 组件外部配置

通过此助手类，可以为拓扑指定配置，此类包含了很多对应了配置项Key的常量值。

要配置一个拓扑在整个集群上，拥有的工作进程的数量，可以使用Config.TOPOLOGY_WORKERS配置项。

要提示为每个组件创建执行线程的数量，可以在setSpout/setBolt时传递parallelism_hint参数，指定初始的执行器数量。

要设置某个组件的任务数量，可以使用Config.TOPOLOGY_TASKS配置项。或者调用

ComponentConfigurationDeclarer.setNumTasks()

调用命令 storm rebalance 可以在运行期间修改拓扑工作进程数量、拓扑组件的执行器数量，示例：

# 使用5个执行线程
# 组件blue-spout使用3个执行器
# 组件yellow-bolt使用10个执行器
storm rebalance mytopology -n 5 -e blue-spout=3 -e yellow-bolt=10

# Native库的位置
java.library.path: "/usr/local/lib:/opt/local/lib:/usr/lib"

### storm.* 一般性配置
# JAR存放位置
storm.local.dir: "storm-local"
# 使用的日志实现
storm.log4j2.conf.dir: "log4j2"
# 使用的ZooKeeper服务器列表
storm.zookeeper.servers:
    - "localhost"
# 使用的ZooKeeper服务器端口
storm.zookeeper.port: 2181
# 使用的ZooKeeper根节点
storm.zookeeper.root: "/storm"
# 常规性ZooKeeper配置项
storm.zookeeper.session.timeout: 20000
storm.zookeeper.connection.timeout: 15000
storm.zookeeper.retry.times: 5
storm.zookeeper.retry.interval: 1000
storm.zookeeper.retry.intervalceiling.millis: 30000
storm.zookeeper.auth.user: null
storm.zookeeper.auth.password: null
storm.exhibitor.port: 8080
storm.exhibitor.poll.uripath: "/exhibitor/v1/cluster/list"
# 集群运行模式：distributed、local
storm.cluster.mode: "distributed"
storm.local.mode.zmq: false
storm.thrift.transport: "org.apache.storm.security.auth.SimpleTransportPlugin"
storm.thrift.socket.timeout.ms: 600000
storm.principal.tolocal: "org.apache.storm.security.auth.DefaultPrincipalToLocal"
storm.group.mapping.service: "org.apache.storm.security.auth.ShellBasedGroupsMapping"
storm.group.mapping.service.params: null
storm.messaging.transport: "org.apache.storm.messaging.netty.Context"
storm.nimbus.retry.times: 5
storm.nimbus.retry.interval.millis: 2000
storm.nimbus.retry.intervalceiling.millis: 60000
storm.auth.simple-white-list.users: []
storm.auth.simple-acl.users: []
storm.auth.simple-acl.users.commands: []
storm.auth.simple-acl.admins: []
storm.cluster.state.store: "org.apache.storm.cluster_state.zookeeper_state_factory"
storm.meta.serialization.delegate: "org.apache.storm.serialization.GzipThriftSerializationDelegate"
storm.codedistributor.class: "org.apache.storm.codedistributor.LocalFileSystemCodeDistributor"
storm.workers.artifacts.dir: "workers-artifacts"
storm.health.check.dir: "healthchecks"
storm.health.check.timeout.ms: 5000
storm.disable.symlinks: false

### nimbus.* configs are for the master
nimbus.seeds : ["localhost"]
nimbus.thrift.port: 6627
nimbus.thrift.threads: 64
nimbus.thrift.max_buffer_size: 1048576
nimbus.childopts: "-Xmx1024m"
nimbus.task.timeout.secs: 30
nimbus.supervisor.timeout.secs: 60
nimbus.monitor.freq.secs: 10
nimbus.cleanup.inbox.freq.secs: 600
nimbus.inbox.jar.expiration.secs: 3600
# Nimbus节点多久尝试同步本地缺少的代码Blob
nimbus.code.sync.freq.secs: 120
nimbus.task.launch.secs: 120
nimbus.file.copy.expiration.secs: 600
nimbus.topology.validator: "org.apache.storm.nimbus.DefaultTopologyValidator"
# 最低复制因子，拓扑的代码、JAR、配置复制到多少Nimbus节点后，Leader才能将拓扑标记为Active并开始分配Worker
topology.min.replication.count: 1
# 等待topology.min.replication.count满足的最大时间
# 超过此时间，则不等待复制完成，立即启动拓扑
# 设置为-1表示一直等待
topology.max.replication.wait.time.sec: 60
nimbus.credential.renewers.freq.secs: 600
nimbus.queue.size: 100000
scheduler.display.resource: false

### ui.* configs are for the master
ui.host: 0.0.0.0
ui.port: 8080
ui.childopts: "-Xmx768m"
ui.actions.enabled: true
ui.filter: null
ui.filter.params: null
ui.users: null
ui.header.buffer.bytes: 4096
ui.http.creds.plugin: org.apache.storm.security.auth.DefaultHttpCredentialsPlugin
ui.http.x-frame-options: DENY

logviewer.port: 8000
logviewer.childopts: "-Xmx128m"
logviewer.cleanup.age.mins: 10080
logviewer.appender.name: "A1"
logviewer.max.sum.worker.logs.size.mb: 4096
logviewer.max.per.worker.logs.size.mb: 2048

logs.users: null

drpc.port: 3772
drpc.worker.threads: 64
drpc.max_buffer_size: 1048576
drpc.queue.size: 128
drpc.invocations.port: 3773
drpc.invocations.threads: 64
drpc.request.timeout.secs: 600
drpc.childopts: "-Xmx768m"
drpc.http.port: 3774
drpc.https.port: -1
drpc.https.keystore.password: ""
drpc.https.keystore.type: "JKS"
drpc.http.creds.plugin: org.apache.storm.security.auth.DefaultHttpCredentialsPlugin
drpc.authorizer.acl.filename: "drpc-auth-acl.yaml"
drpc.authorizer.acl.strict: false

# 用于Trident拓扑中Spout相关的元数据的存储
# 存储的根路径
transactional.zookeeper.root: "/transactional"
# 用于存储的ZooKeeper集群信息
transactional.zookeeper.servers: null
transactional.zookeeper.port: null

## blobstore configs
# Supervisor用于和BlobStore通信的客户端类
# 如果使用HDFS实现，改为org.apache.storm.blobstore.HdfsClientBlobStore
supervisor.blobstore.class: "org.apache.storm.blobstore.NimbusBlobStore"
# Supervisor上用于并行下载Blob的线程数量
supervisor.blobstore.download.thread.count: 5
# 下载失败后，最大重试次数
supervisor.blobstore.download.max_retries: 3
# 本地缓存最大尺寸
supervisor.localizer.cache.target.size.mb: 10240
# 本地缓存清理间隔，超过最大尺寸的部分，以LRU算法清除
supervisor.localizer.cleanup.interval.ms: 600000
# 分布式缓存实现（BlobStore）实现类
nimbus.blobstore.class: "org.apache.storm.blobstore.LocalFsBlobStore"
# 通过Master和Blobstore交互时，会话过期时间，单位秒
nimbus.blobstore.expiration.secs: 600
# 所有Blob存储的位置，对于本地文件系统实现，对应了Nimbus本地目录，对于HDFS实现，对应hdfs文件路径
blobstore.dir: $storm.local.dir/blobs
# 上传Blob时，缓冲区大小
storm.blobstore.inputstream.buffer.size.bytes: 65536
# Storm客户端用于和BlobStore通信的客户端类
client.blobstore.class: "org.apache.storm.blobstore.NimbusBlobStore"
# BlobStore中每个Blob的复制因子
# topology.min.replication.count用于设置拓扑的数据的复制因子
# topology.min.replication.count 应该小于等于 blobstore.replication.factor
storm.blobstore.replication.factor: 3
# For secure mode we would want to change this config to true
storm.blobstore.acl.validation.enabled: false

### supervisor.* configs are for node supervisors
# Define the amount of workers that can be run on this machine. Each worker is assigned a port to use for communication
supervisor.slots.ports:
    - 6700
    - 6701
    - 6702
    - 6703
supervisor.childopts: "-Xmx256m"
supervisor.run.worker.as.user: false
#how long supervisor will wait to ensure that a worker process is started
supervisor.worker.start.timeout.secs: 120
#how long between heartbeats until supervisor considers that worker dead and tries to restart it
supervisor.worker.timeout.secs: 30
#how many seconds to sleep for before shutting down threads on worker
supervisor.worker.shutdown.sleep.secs: 3
#how frequently the supervisor checks on the status of the processes it's monitoring and restarts if necessary
supervisor.monitor.frequency.secs: 3
#how frequently the supervisor heartbeats to the cluster state (for nimbus)
supervisor.heartbeat.frequency.secs: 5
supervisor.enable: true
supervisor.supervisors: []
supervisor.supervisors.commands: []
supervisor.memory.capacity.mb: 3072.0
#By convention 1 cpu core should be about 100, but this can be adjusted if needed
# using 100 makes it simple to set the desired value to the capacity measurement
# for single threaded bolts
supervisor.cpu.capacity: 400.0

### worker.* configs are for task workers
worker.heap.memory.mb: 768
worker.childopts: "-Xmx%HEAP-MEM%m -XX:+PrintGCDetails -Xloggc:artifacts/gc.log -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps -XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=10 -XX:GCLogFileSize=1M -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=artifacts/heapdump"
worker.gc.childopts: ""

# Unlocking commercial features requires a special license from Oracle.
# See http://www.oracle.com/technetwork/java/javase/terms/products/index.html
# For this reason, profiler features are disabled by default.
worker.profiler.enabled: false
worker.profiler.childopts: "-XX:+UnlockCommercialFeatures -XX:+FlightRecorder"
worker.profiler.command: "flight.bash"
worker.heartbeat.frequency.secs: 1

# check whether dynamic log levels can be reset from DEBUG to INFO in workers
worker.log.level.reset.poll.secs: 30

# control how many worker receiver threads we need per worker
topology.worker.receiver.thread.count: 1

task.heartbeat.frequency.secs: 3
task.refresh.poll.secs: 10
task.credentials.poll.secs: 30
task.backpressure.poll.secs: 30

# now should be null by default
topology.backpressure.enable: false
backpressure.disruptor.high.watermark: 0.9
backpressure.disruptor.low.watermark: 0.4

zmq.threads: 1
zmq.linger.millis: 5000
zmq.hwm: 0


storm.messaging.netty.server_worker_threads: 1
storm.messaging.netty.client_worker_threads: 1
storm.messaging.netty.buffer_size: 5242880 #5MB buffer
# Since nimbus.task.launch.secs and supervisor.worker.start.timeout.secs are 120, other workers should also wait at least that long before giving up on connecting to the other worker. The reconnection period need also be bigger than storm.zookeeper.session.timeout(default is 20s), so that we can abort the reconnection when the target worker is dead.
storm.messaging.netty.max_retries: 300
storm.messaging.netty.max_wait_ms: 1000
storm.messaging.netty.min_wait_ms: 100

# If the Netty messaging layer is busy(netty internal buffer not writable), the Netty client will try to batch message as more as possible up to the size of storm.messaging.netty.transfer.batch.size bytes, otherwise it will try to flush message as soon as possible to reduce latency.
storm.messaging.netty.transfer.batch.size: 262144
# Sets the backlog value to specify when the channel binds to a local address
storm.messaging.netty.socket.backlog: 500

# By default, the Netty SASL authentication is set to false.  Users can override and set it true for a specific topology.
storm.messaging.netty.authentication: false

# Default plugin to use for automatic network topology discovery
storm.network.topography.plugin: org.apache.storm.networktopography.DefaultRackDNSToSwitchMapping

# default number of seconds group mapping service will cache user group
storm.group.mapping.service.cache.duration.secs: 120

### topology.* configs are for specific executing storms
# 是否启用消息处理超时
topology.enable.message.timeouts: true
# 释放禁用拓扑调试
topology.debug: false
topology.workers: 1
# ACK线程的数量，设置为0则禁用ACK
topology.acker.executors: null
# 事件记录器线程数量，设置为0则禁用事件记录
topology.eventlogger.executors: 0
topology.tasks: null
# maximum amount of time a message has to complete before it's considered failed
topology.message.timeout.secs: 30
topology.multilang.serializer: "org.apache.storm.multilang.JsonSerializer"
topology.shellbolt.max.pending: 100
topology.skip.missing.kryo.registrations: false
topology.max.task.parallelism: null
# 对于事务性拓扑，表示能够同时处理的元组批次的数量
# 对于非事务性拓扑，如果启用了消息确认（ACK），则拓扑中尚未ACK的原初元组的数量，超过此数量不再继续释放原初元组
topology.max.spout.pending: null
topology.state.synchronization.timeout.secs: 60
topology.stats.sample.rate: 0.05
topology.builtin.metrics.bucket.size.secs: 60
topology.fall.back.on.java.serialization: true
topology.worker.childopts: null
topology.worker.logwriter.childopts: "-Xmx64m"
topology.executor.receive.buffer.size: 1024 #batched
topology.executor.send.buffer.size: 1024 #individual messages
topology.transfer.buffer.size: 1024 # batched
topology.tick.tuple.freq.secs: null
topology.worker.shared.thread.pool.size: 4
topology.spout.wait.strategy: "org.apache.storm.spout.SleepSpoutWaitStrategy"
topology.sleep.spout.wait.strategy.time.ms: 1
topology.error.throttle.interval.secs: 10
topology.max.error.report.per.interval: 5
topology.kryo.factory: "org.apache.storm.serialization.DefaultKryoFactory"
topology.tuple.serializer: "org.apache.storm.serialization.types.ListDelegateSerializer"
topology.trident.batch.emit.interval.millis: 500
topology.testing.always.try.serialize: false
topology.classpath: null
topology.environment: null
topology.bolts.outgoing.overflow.buffer.enable: false
topology.disruptor.wait.timeout.millis: 1000
topology.disruptor.batch.size: 100
topology.disruptor.batch.timeout.millis: 1
topology.disable.loadaware.messaging: false
topology.state.checkpoint.interval.ms: 1000

# Configs for Resource Aware Scheduler
# topology priority describing the importance of the topology in decreasing importance starting from 0 (i.e. 0 is the highest priority and the priority importance decreases as the priority number increases).
# Recommended range of 0-29 but no hard limit set.
topology.priority: 29
topology.component.resources.onheap.memory.mb: 128.0
topology.component.resources.offheap.memory.mb: 0.0
topology.component.cpu.pcore.percent: 10.0
# Worker进程的最大堆尺寸
topology.worker.max.heap.size.mb: 768.0
topology.scheduler.strategy: "org.apache.storm.scheduler.resource.strategies.scheduling.DefaultResourceAwareStrategy"
resource.aware.scheduler.eviction.strategy: "org.apache.storm.scheduler.resource.strategies.eviction.DefaultEvictionStrategy"
resource.aware.scheduler.priority.strategy: "org.apache.storm.scheduler.resource.strategies.priority.DefaultSchedulingPriorityStrategy"

dev.zookeeper.path: "/tmp/dev-storm-zookeeper"

pacemaker.host: "localhost"
pacemaker.port: 6699
pacemaker.base.threads: 10
pacemaker.max.threads: 50
pacemaker.thread.timeout: 10
pacemaker.childopts: "-Xmx1024m"
pacemaker.auth.method: "NONE"
pacemaker.kerberos.users: []

#default storm daemon metrics reporter plugins
storm.daemon.metrics.reporter.plugins:
     - "org.apache.storm.daemon.metrics.reporters.JmxPreparableReporter"

# configuration of cluster metrics consumer
storm.cluster.metrics.consumer.publish.interval.secs: 60

前面我们提到过，Storm支持两种运行模式：本地模式、远程模式。在本地模式中你可以在单JVM进程中调试整个拓扑。

开发环境就是包含了所有Storm组件的环境，你可以在本地模式下开发、测试Storm拓扑。或者将集群提交到远程集群，启动/停止远程集群上的拓扑。

你的开发机器和远程集群的关系是这样的：远程集群被主节点——Nimbus所管理，你的机器和Nimbus交互，提交JAR格式的拓扑。随后拓扑在集群中被调度、执行。你的机器可以通过命令行客户端storm和Nimbus交互，此客户端仅仅支持远程模式。

首先，下载最新版本的Storm，解压后，把bin子目录放到PATH环境变量中。bin目录中包含客户端脚本。

要想管理远程集群，将集群连接信息存放到

~/.storm/storm.yaml

主要步骤包括：

1. 创建ZooKeeper集群
2. 在Nimbus、Worker节点上安装依赖
3. 在Nimbus、Worker节点上下载并解压Storm
4. 在storm.yaml中添加必须的配置
5. 使用你选择的监控工具，通过storm命令启动守护程序。

请参考：ZooKeeper学习笔记

安装Java 7+以及Python 2.6.6，不赘述。

Python 3应该也可以工作，但是没有经过详尽的测试。

请参考：搭建开发环境

打开$STORM_HOME/ conf/storm.yaml文件，添加以下配置：

# 指定ZooKeeper集群的主机列表：
storm.zookeeper.servers:
    - "zookeeper-1.gmem.cc"
    - "zookeeper-1.gmem.cc"
    - "zookeeper-3.gmem.cc"
storm.zookeeper.port: 2181

# 当前节点的名称，默认自动根据主机名获取
storm.local.hostname: "storm-n1.gmem.cc"

# Nimbus/Supervisor需要在本地文件系统中存放少量状态数据，例如 jars, confs
# 此目录需要提前创建，并授予适当的读写权限
storm.local.dir: "/home/alex/JavaEE/middleware/storm/data/local"

# 工作节点需要知道哪些机器是Master节点的候选，以便从这些节点下载拓扑JAR、配置文件
# 你应该列出目标机器的全限定域名（FQDN）。如果使用Nimbus HA，要列出所有运行Nimbus进程的机器
nimbus.seeds: ["storm-n1.gmem.cc"]

# 对于每个工作节点，你需要指定它运行多少个工作进程。每个工作进程需要独特的端口来接收消息
# 这里指定多少端口，就创建多少工作进程。默认创建6700-6703这4个端口
supervisor.slots.ports:
    - 6700
    - 6701
    - 6702
    - 6703

Storm允许你提供一些脚本，让Supervisor定期的执行，以监控节点的健康状态。如果脚本监测到节点不健康，它应当在标准输出打印一行以ERROR开头的文字。Supervisor会周期性的执行脚本，一旦发现ERROR，就会关闭节点上所有Worker进程并退出。

在监控工具下运行守护进程时，你可以考虑调用storm node-health-check命令确认节点健康状态，进一步决定是否继续运行守护进程。

# 指定健康检测脚本所在目录
storm.health.check.dir: "healthchecks"
# 脚本执行超时时间
storm.health.check.timeout.ms: 5000

如果需要支持外部库、自定义插件，可以把相关的JAR存放到extlib、extlib-daemon目录下。需要注意， extlib-daemon中的JAR仅仅能被守护进程（不能被Worker也就是拓扑逻辑）使用。

你也可以使用STORM_EXT_CLASSPATH、STORM_EXT_CLASSPATH_DAEMON这两个环境变量。

# 仅Nimbus节点

# UI服务器配置
ui.host: 0.0.0.0
ui.port: 6600

# 日志查看器配置
logviewer.port: 6601

强烈推荐在监控工具下（supervision tool）启动守护程序，这样意外崩溃后可以立即重启。Storm守护程序被设计为快速失败、无状态的，重启后拓扑不会受到影响：

1. 要启动Nimbus，执行

   storm nimbus

   命令
2. 要启动Supervisor，在每个Worker节点执行

   storm supervisor

   命令
3. 要运行Storm UI服务器，在Nimbus节点执行

   storm ui

   ，默认Web端口8080

所有守护程序的日志默认存放在logs目录下。

安装此监控工具参考：Ubuntu下使用monit。服务条目示例：

check process storm-nimbus matching daemon.name=nimbus
    start program = "/home/alex/JavaEE/middleware/storm/bin/storm nimbus"
        as uid alex and gid alex
    stop program = "/bin/kill -9 $MONIT_PROCESS_PID"
        as uid alex and gid alex

check process storm-ui matching daemon.name=ui
    start program = "/home/alex/JavaEE/middleware/storm/bin/storm ui"
        as uid alex and gid alex
    stop program = "/bin/kill -9 $MONIT_PROCESS_PID"
        as uid alex and gid alex

check process storm-drpc matching daemon.name=drpc
    start program = "/home/alex/JavaEE/middleware/storm/bin/storm drpc"
        as uid alex and gid alex
    stop program = "/bin/kill -9 $MONIT_PROCESS_PID"
        as uid alex and gid alex

check process storm-log matching daemon.name=logviewer
    start program = "/home/alex/JavaEE/middleware/storm/bin/storm logviewer"
        as uid alex and gid alex
    stop program = "/bin/kill -9 $MONIT_PROCESS_PID"
        as uid alex and gid alex

请参考：官方Docker镜像。 

拉取镜像：

docker pull storm:1.1.1

用法示例：

# 以本地模式运行一个拓扑
docker run -it -v topology.jar:/topology.jar storm storm jar /topology.jar pkg.Topology
# 运行nimbus
docker run -d --restart always --name nimbus storm storm nimbus
# 运行supervisor
docker run -d --restart always --name supervisor storm storm supervisor

此镜像使用的默认配置是defaults.yaml，改变配置的方式由两种：

1. 使用命令行参数，例如

   -c storm.zookeeper.servers='["zookeeper"]'

2. 在容器文件系统路径

   /conf/storm.yaml

   放置配置文件

数据和日志的存储目录位于/data、/logs，这两个目录的所有者为storm。

docker run --name storm-s1 --hostname storm-s1 --network local --ip 172.21.2.1 --dns 172.21.0.1 -d docker.gmem.cc/storm storm supervisor -c storm.local.hostname='storm-s1.gmem.cc'

Storm拓扑的调试主要依赖于日志，特别是在远程集群中运行的情况下。

你可以通过Storm UI或者命令行动态的改变某个包前缀的日志级别，方式类似于设置Log4J的日志级别。

通过Storm UI首页找到需要调试的拓扑，点击链接进入，可以看到类似下面的页面：

此页面提供了和拓扑相关的大量信息：

1. 顶部的搜索栏，可以对Worker的日志进行搜索
2. 按钮区域，提供了激活、禁用、Rebalance、杀死、起停调试功能，还可以设置日志级别
3. 拓扑的名称、状态、Worker数量、Executor数量、Task数量等基本信息
4. 释放、传输（释放并发送给1-N个Bolt）元组的数量、延迟时间，Ack、Fail的数量
5. Spout、Bolt的各类统计信息
6. 拥有的Worker在集群中的分布情况，组件和Worker的对应关系
7. 可以查看图形化的拓扑结构（蓝色表示Spout）
8. 拓扑的配置信息

要通过Storm UI修改日志级别，点击Change Log Level链接，填写表单然后Apply即可。Logger字段可以填写你的代码中使用的日志器前缀（包名前缀）。Timeout指明本次日志级别调整激活多久。

参见命令行客户端。

通过Logviewer不能直接查看Worker的日志文件。Worker的所有日志存放在

${storm.log.dir}/workers-artifacts/${topologyId}/${port}

你可以在上述Storm UI界面的顶部，输入关键字（例如Exception）来搜索Worker日志，右上角的放大镜按钮也可以用来进行搜索（默认针对所有拓扑）。

要进行动态JVM剖析，点击拓扑的某个组件，可以看到Profiling and Debugging面板。点选下面的Executors面板的条目，然后点击对应的按钮：

1. JStack：生成Thread Dump
2. Start：启动剖析
3. Heap：生成Heap Dump

点击My Dump Files可以下载上述按钮生成的剖析文件。

拓扑事件查看器能够用来确定元组如何穿过拓扑的每一个Stage，实时查看元组处理过程时，不会对拓扑运行产生影响。

默认事件记录功能被禁用，你可以设置

topology.eventlogger.executors

要启动事件记录，点击Topolog Actions面板上的Debug按钮。

要查看被处理的元组，进入对应Spout/Bolt组件的页面，在Component summary面板中，点击events链接。

Storm中的日志记录Bolt利用IEventLogger接口实现事件日志，此接口的默认实现是FileBasedEventLogger。你可以扩展此接口实现更加复杂的逻辑，例如记录到数据库。

Storm提供了一个名为storm的客户端程序，用于和远程集群进行交互。

调用格式：

storm jar topology-jar-path class 
    # 逗号分隔
    --jars  your-local-jar.jar,your-local-jar2.jar
    # 逗号分隔，^用于排除依赖
    --artifacts "redis.clients:jedis:2.9.0,org.apache.kafka:kafka_2.10:0.8.2.2^org.slf4j:slf4j-log4j12"
    # 指定下载构件的仓库，^用作分隔符
    --artifactRepositories "jboss-repository^"

调用class的main函数，需要的配置文件和依赖的jar包（例如storm的jar），放置于~/.storm目录。main函数通常调用StormSubmitter，并导致topology-jar-path被上传到Nimbus。

如果存在依赖的、没有打包到topology-jar-path的其它jar包，可以使用--jars选项。如果想使用Maven构件的方式指定依赖，可以使用--artifacts选项。

依赖会同时上传作为Worker进程的classpath条目。

调用格式：

storm sql sql-file topology-name   --jars  --artifacts --artifactRepositories

编译SQL为Trident拓扑，并提交到Storm集群。

调用格式：

storm kill topology-name [-w wait-time-secs]

杀死具有指定名称的拓扑，最多等待wait-time-secs秒。

Storm会首先禁用Spout，然后等待一定时间（默认是拓扑的消息处理超时），让正在处理的消息完成。之后，Storm会关闭Worker进程并清理状态。

调用格式：

storm activate topology-name

激活指定拓扑的Spout

调用格式：

storm deactivate topology-name

禁用指定拓扑的Spout

调用格式：

storm rebalance topology-name [-w wait-time-secs] [-n workers-num] [-e component=parallelism]*

某些时候你希望把拓扑的Worker进程均匀分布到更多的机器上。

举例来说，假设你有个10台机器的集群，每个运行4个工作进程。现在，又添加了10个节点，你需要使用这些机器的运算能力，让每个节点运行2个工作进程。一种方法是，杀死并重新提交拓扑，但是rebalance提供了更加简单的方法。

rebalance首先禁用指定的拓扑Spout（等待到消息超时或者-w），然后，在集群中均匀的创建Worker进程，最后激活拓扑。

rebalance也可以用来改变拓扑的并发度： -n用来改变Worker进程数量；-e用来指定组件的Executor数量（线程数量，和Task数量不是一回事）

调用格式：

storm repl

开启Clojure REPL环境。

调用格式：

storm classpath

调用格式：

storm localconfvalue conf-name

打印配置项conf-name的本地值，本地配置是~/.storm/storm.yaml合并了defaults.yaml的结果。

调用格式：

storm remoteconfvalue conf-name

必须在集群中的节点上执行，打印集群的配置项。集群配置是$STORM-PATH/conf/storm.yaml合并了defaults.yaml的结果。

调用格式：

storm nimbus

调用格式：

storm supervisor

调用格式：

storm ui

调用格式：

storm drpc

调用格式：

storm blobstore cmd

onitor
调用格式：

storm dev-zookeeper

启动一个全新的zookeeper服务器，使用dev.zookeeper.path作为其本地目录，使用storm.zookeeper.port作为其端口。仅仅用于开发/测试。

调用格式：

storm get-errors topology-name

获得指定拓扑的最新的错误信息。返回结果是component-name: component-error的键值对JSON

调用格式：

storm heartbeats [cmd]

调用格式：

storm kill_workers

杀死运行在此Supervisor节点上的Worker进程，必须在Supervisor节点上调用。

调用格式：

storm list

调用格式：

storm logviewer

调用格式：

storm monitor topology-name 
    [-i interval-secs]               # 默认4秒轮询一次
    [-m component-id]                # 默认所有组件
    [-s stream-id]                   # 默认default
    [-w [emitted | transferred]]     # 默认emitted

交互式的对指定拓扑的吞吐量进行监控。 

调用格式：

storm node-health-check

调用格式：

storm pacemaker

调用格式：

storm set_log_level
    # 日志级别ALL, TRACE, DEBUG, INFO, WARN, ERROR, FATAL, OFF
    # timeout 秒，整数
    -l [logger name]=[log level][:optional timeout] 
    -r [logger name] 
    topology-name

# 示例
storm set_log_level -l ROOT=DEBUG:30 my-topology
storm set_log_level -l com.myapp=WARN my-topology

动态的控制拓扑的日志级别。

调用格式：

storm upload_credentials topology-name [credkey credvalue]*

更新credentials集到运行中的拓扑。

Trident（音标/'traɪd(ə)nt/）是Storm提供的另外一种访问接口，它提供一些高层抽象，包括：

1. 精确的一次处理语义
2. 事务性数据持久化
3. 一些通用的流分析功能

使用Trident你可以无缝的将低延迟分布式查询和高吞吐量（每秒百万级消息）、有状态流处理混合。如果你对Pig、Cascading之类的高层批处理工具熟悉，理解起Trident会很容易。Trident有类似的连接（Join）、聚合（Aggregation）、分组（Grouping）、函数（Function）、过滤器（Filter）概念，此外Trident还提供在任何数据库、存储机制基础上进行有状态、增量处理的原语。

考虑两个流处理需求：

1. 从输入流中统计每个姓名出现的次数
2. 能够传入一个姓名列表，获得这些姓名出现的总次数

非线性随机名字生成器：

package cc.gmem.study.bdg;

import org.apache.commons.lang3.RandomUtils;
import org.apache.commons.lang3.StringUtils;

import java.util.function.BiFunction;

public class RandomNameGenerator {

    private static String COMMON_FIRST_NAMES[] = new String[]{
            "伟", "芳", "秀", "英", "娜", "敏", "静", "丽", "强", "磊",
            "军", "洋", "勇", "艳", "杰", "娟", "涛", "明", "超", "兰",
            "霞", "平", "桂", "诚", "先", "敬", "震", "振", "壮", "会",
            "思", "群", "豪", "心", "邦", "承", "乐", "绍", "功", "松",
            "善", "厚", "裕", "河", "哲", "江", "亮", "政", "谦", "亨",
            "奇", "固", "之", "轮", "翰", "朗", "伯", "宏", "言", "海",
            "山", "仁", "波", "宁", "福", "生", "龙", "元", "全", "国",
            "胜", "学", "祥", "才", "发", "武", "新", "利", "毅", "俊",
            "峰", "保", "东", "文", "辉", "力", "永", "健", "世", "广",
            "鸣", "朋", "斌", "行", "时", "泰", "博", "磊", "民", "友",
            "志", "清", "坚", "庆", "若", "德", "彪", "盛", "雄", "琛",
            "钧", "冠", "策", "腾", "楠", "榕", "风", "航", "弘", "义",
            "兴", "良", "飞", "彬", "富", "和", "梁", "栋", "维", "启",
            "克", "伦", "翔", "旭", "鹏", "泽", "晨", "辰", "士", "以",
            "建", "家", "致", "树", "炎", "蕊", "薇", "菁", "梦", "岚",
            "苑", "婕", "馨", "瑗", "琰", "韵", "融", "园", "艺", "咏",
            "卿", "聪", "澜", "纯", "爽", "琬", "茗", "羽", "希", "宁",
            "欣", "飘", "育", "滢", "馥", "筠", "柔", "竹", "霭", "凝",
            "晓", "欢", "霄", "伊", "亚", "宜", "可", "姬", "舒", "影",
            "荔", "枝", "芬", "芳", "燕", "莺", "媛", "珊", "莎", "蓉",
            "好", "君", "琴", "毓", "悦", "昭", "冰", "枫", "芸", "菲",
            "寒", "锦", "玲", "秋", "秀", "娟", "英", "华", "慧", "巧",
            "美", "淑", "惠", "珠", "翠", "雅", "芝", "玉", "萍", "红",
            "月", "彩", "春", "菊", "凤", "洁", "梅", "琳", "怡", "宝"
    };

    private static String COMMON_LAST_NAMES[] = {
            "李", "王", "张", "刘", "陈", "杨", "赵", "黄", "周", "吴",
            "徐", "孙", "胡", "朱", "高", "林", "何", "郭", "马", "罗",
            "梁", "宋", "郑", "谢", "韩", "唐", "冯", "于", "董", "萧",
            "程", "曹", "袁", "邓", "许", "傅", "沈", "曾", "彭", "吕",
            "苏", "卢", "蒋", "蔡", "贾", "丁", "魏", "薛", "叶", "阎",
            "余", "潘", "杜", "戴", "夏", "钟", "汪", "田", "任", "姜",
            "范", "方", "石", "姚", "谭", "廖", "邹", "熊", "金", "陆",
            "郝", "孔", "白", "崔", "康", "毛", "邱", "秦", "江", "史",
            "顾", "侯", "邵", "孟", "龙", "万", "段", "漕", "钱", "汤",
            "尹", "黎", "易", "常", "武", "乔", "贺", "赖", "龚", "文",
            "庞", "樊", "兰", "殷", "施", "陶", "洪", "翟", "安", "颜",
            "倪", "严", "牛", "温", "芦", "季", "俞", "章", "鲁", "葛",
            "伍", "韦", "申", "尤", "毕", "聂", "丛", "焦", "向", "柳",
            "邢", "路", "岳", "齐", "沿", "梅", "莫", "庄", "辛", "管",
            "祝", "左", "涂", "谷", "祁", "时", "舒", "耿", "牟", "卜",
            "路", "詹", "关", "苗", "凌", "费", "纪", "靳", "盛", "童",
            "欧", "甄", "项", "曲", "成", "游", "阳", "裴", "席", "卫",
            "查", "屈", "鲍", "位", "覃", "霍", "翁", "隋", "植", "甘",
            "景", "薄", "单", "包", "司", "柏", "宁", "柯", "阮", "桂",
            "闵", "欧阳", "解", "强", "柴", "华", "车", "冉", "房", "边"
    };


    // 初值即为终值
    public static final BiFunction<Integer, Integer, Integer> REMAPPING_NO = ( value, max ) -> value;

    public static class RemappingFunctionPower implements BiFunction<Integer, Integer, Integer> {

        private Integer powerOf;

        public RemappingFunctionPower( int powerOf ) {
            this.powerOf = powerOf;
        }

        @Override
        public Integer apply( Integer value, Integer max ) {
            double pos = (double) value / (double) max;
            return (int) ( Math.pow( pos, powerOf ) * max );
        }
    }

    // 二次方映射，一系列随机初值的映射结果向靠近0的方向集中
    public static final BiFunction<Integer, Integer, Integer> REMAPPING_POW_2 = new RemappingFunctionPower( 2 );

    // 四次方映射
    public static final BiFunction<Integer, Integer, Integer> REMAPPING_POW_4 = new RemappingFunctionPower( 4 );

    // 八次方映射
    public static final BiFunction<Integer, Integer, Integer> REMAPPING_POW_8 = new RemappingFunctionPower( 8 );


    private BiFunction<Integer, Integer, Integer> remappingFunc;

    private String firstNames[];

    private String lastNames[];

    public RandomNameGenerator() {
        this.firstNames = COMMON_FIRST_NAMES;
        this.lastNames = COMMON_LAST_NAMES;
        this.remappingFunc = REMAPPING_NO;
    }

    public RandomNameGenerator( BiFunction<Integer, Integer, Integer> func ) {
        this();
        this.remappingFunc = func;
    }

    private String randomFirstName() {
        int length = firstNames.length;
        int rand = RandomUtils.nextInt( 0, length );
        return firstNames[remappingFunc.apply( rand, length )];
    }

    private String randomLastName() {
        int length = lastNames.length;
        int rand = RandomUtils.nextInt( 0, length );
        return lastNames[remappingFunc.apply( rand, length )];
    }

    public String randomNameBatch( int size ) {
        String names[] = new String[size];
        for ( int i = 0; i < size; i++ ) {
            String lastName = randomLastName();
            String firstName = randomFirstName();
            if ( RandomUtils.nextInt( 1, 3 ) == 2 ) {
                firstName += randomFirstName();
            }
            names[i] = lastName + firstName;
        }
        return StringUtils.join( names, " " );
    }
}

Storm代码： 

package cc.gmem.study.storm.trident;

import org.apache.commons.lang3.RandomUtils;
import org.apache.commons.lang3.StringUtils;
import org.apache.storm.task.TopologyContext;
import org.apache.storm.trident.TridentState;
import org.apache.storm.trident.TridentTopology;
import org.apache.storm.trident.operation.TridentCollector;
import org.apache.storm.trident.operation.builtin.Count;
import org.apache.storm.trident.operation.builtin.FilterNull;
import org.apache.storm.trident.operation.builtin.MapGet;
import org.apache.storm.trident.operation.builtin.Sum;
import org.apache.storm.trident.spout.IBatchSpout;
import org.apache.storm.trident.testing.MemoryMapState;
import org.apache.storm.trident.testing.Split;
import org.apache.storm.tuple.Fields;
import org.apache.storm.tuple.Values;

import java.util.Map;

public class NameCounterTridentTopology {

    private static final Logger LOGGER = getLogger( NameCounterTridentTopology.class );

    public static final String F_NAMES = "names";

    public static final String F_NAME = "name";

    // IBatchSpout是ITridentDataSource的子接口，作为Trident的数据源
    public static class RandomNameBatchSpout implements IBatchSpout {

        @Override
        public void open( Map conf, TopologyContext context ) {
        }

        // 为一个批次生成元组集，元组集的长度由你决定，注意考虑输入吞吐量的大小
        @Override
        public void emitBatch( long batchId, TridentCollector collector ) {
            // 随机生成一批名字
            int batchSize = RandomUtils.nextInt( 10, 100 );
            for ( int i = 0; i < batchSize; i++ ) {
                int size = RandomUtils.nextInt( 10, 1000 );
                // 每次释放的元组具有单个字段，字段内容是空格分隔的人名
                String names = new RandomNameGenerator( REMAPPING_POW_8 ).randomNameBatch( size );
                LOGGER.debug( "Batch {} item {} : {}", new Object[]{ batchId, i + 1, names } );
                collector.emit( new Values( names ) );
            }
        }


        @Override
        public void ack( long batchId ) {
        }

        @Override
        public void close() {
        }

        @Override
        public Map<String, Object> getComponentConfiguration() {
            return null;
        }

        @Override
        public Fields getOutputFields() {
            return new Fields( F_NAMES );
        }
    }

    public static void main( String[] args ) {
        /**
         * TridentTopology暴露构建Trident计算拓扑的接口
         * 拓扑图由三类节点构成：操作（operation），分区（partition，例如分组和洗牌），Spout
         * 每个操作节点具有finishBatch方法，且可以作为Committer（有序串行化）节点
         */
        TridentTopology topology = new TridentTopology();
        String txId = "randomNamesSpout";  // Trident在ZooKeeper中存储数据使用的键
        TridentState nameCounts = topology
            /**
             * 声明一个Trident输入流，返回值trident.Stream类型。实际项目中常用的输入流包括Kafka、Kestrel等队列代理
             * Trident在ZooKeeper中存储一小部分数据，表示输入流的状态（被消费的情况）
             */
            .newStream( txId, new RandomNameBatchSpout() )
            // 对于上述流的每个元组，执行Function操作，使用Split函数以空格分割，分割的结果存放在字段name中
            // 返回值trident.Stream类型
            .each( new Fields( F_NAMES ), new Split(), new Fields( F_NAME ) )
            // 执行Grouping操作，返回值GroupedStream类型
            .groupBy( new Fields( F_NAME ) )
            // 执行Aggregation操作，聚合方式为统计总数，返回值TridentState类型
            .persistentAggregate( new MemoryMapState.Factory(), new Count(), new Fields( "nameCount" ) )
            .parallelismHint( 2 );
    }
}

Trident以较小的批次的方式来处理输入流，根据输入throughput的不同，一个批次包含的元组数量可以在数千到数百万之间。 

Trident提供了全特性的API，用于处理元组批次。这些API和Pig、Cascading等Hadoop高层抽象很类似。Trident提供了跨越批次进行聚合、持久化存储（可以在内存、Redis等“状态源”中）聚合结果的功能。此外，Trident还具有查询实时状态源的功能，这些状态可以被Trident更新，状态源也可以是独立于Trident维护的。

回到上面的人名统计代码中：

1. Spout释放包含单个字段names的元组，names字段实际上是空格分隔的人名列表
2. 我们使用Split函数对每个names字段进行分割，每个输入元组可能产生多个输出元组，输出元组包含单个字段name。Split函数的实现：
   

   public class Split extends BaseFunction {
      // 处理一个输入元组，可以释放任意个输出元组
      public void execute(TridentTuple tuple, TridentCollector collector) {
          String sentence = tuple.getString(0);
          for(String word: sentence.split(" ")) {
              collector.emit(new Values(word));                
          }
      }
   }

3. 我们使用groupBy对人名进行分组，相同的名字分为一组
4. 我们使用聚合器Count对分组进行聚合，并调用persistentAggregate对聚合结果进行持久化。此方法知道如何存储、更新位于状态源中的聚合结果。在此例中我们使用内存作为状态源，实际项目中你可以使用Memcached、Cassandra、Redis等持久化存储，例如：
   

   .persistentAggregate(MemcachedState.transactional(serverLocations), new Count(), new Fields("nameCount"));

   注意：persistentAggregate所存储的值，是输入流发出的所有批次的总的聚合结果 

5. persistentAggregate把流转换为TridentState对象。在本例中，TridentState对象包含了所有人名的计数结果。使用此TridentState对象可以实现需求的分布式查询部分

Trident的一个很酷的地方是，它提供完全的容错、精确的一次处理语义，这可以很好的简化实时处理逻辑。通过巧妙的存储状态，Trident能够在出错而需要重试时，不会对相同的源数据进行重复的入库（例如聚合到Memcached）。

人名统计需求的第一部分已经实现，拓扑运行后，TridentState不断更新，记录了当前各人名出现的总次数。

需求的第二部分是实现对统计结果的低延迟、实时查询。对于一个空格分隔的人名列表，我们要返回这些名字出现的次数的总和。

package cc.gmem.study.storm.trident;

import org.apache.storm.Config;
import org.apache.storm.security.auth.SimpleTransportPlugin;
import org.apache.storm.security.auth.plain.PlainSaslTransportPlugin;
import org.apache.storm.thrift.TException;
import org.apache.storm.utils.DRPCClient;
import org.slf4j.Logger;

import java.util.Arrays;

import static org.slf4j.LoggerFactory.getLogger;

public class NameCounterQueryClient {

    private static final Logger LOGGER = getLogger( NameCounterQueryClient.class );

    public static void main( String[] args ) throws TException {
        Config conf = new Config();
        conf.put( Config.STORM_ZOOKEEPER_SERVERS, Arrays.asList( "zookeeper-1.gmem.cc", "zookeeper-2.gmem.cc", "zookeeper-3.gmem.cc" ) );
        conf.put( Config.STORM_ZOOKEEPER_PORT, 2181 );
        conf.put( Config.STORM_ZOOKEEPER_CONNECTION_TIMEOUT, 2000 );
        conf.put( Config.STORM_THRIFT_TRANSPORT_PLUGIN, "org.apache.storm.security.auth.SimpleTransportPlugin" );
        conf.put( Config.STORM_NIMBUS_RETRY_TIMES, 3 );
        conf.put( Config.STORM_NIMBUS_RETRY_INTERVAL, 10 );
        conf.put( Config.STORM_NIMBUS_RETRY_INTERVAL_CEILING, 20 );
        conf.put( Config.DRPC_MAX_BUFFER_SIZE, 1048576 );
        DRPCClient client = new DRPCClient( conf, "storm-n1.gmem.cc", 3772 );
        // JSON编码的结果
        String result = client.execute( "nameCountFunc", "汪静好 汪震" );
        LOGGER.debug( result );
    }
}

可以看到，查询客户端和普通的RPC客户端没有区别， 只是它的请求可以在Storm集群中并行的处理。类似于这种小的查询请求，其延迟可以低达10ms。

我们需要对上面的拓扑进行扩展，让它作为DRPC服务器：

topology.newDRPCStream( "nameCountFunc" )  // 供客户端调用的函数名称
        // 对请求参数进行分隔
        .each( new Fields( "args" ), new Split(), new Fields( "name" ) )
        .groupBy( new Fields( "name" ) )
        // 获取每个名字的当前计数，namsCount即TridentState
        .stateQuery( nameCounts, new Fields( "name" ), new MapGet(), new Fields( "nameCount" ) )
        // 过滤空计数
        .each( new Fields( "nameCount" ), new FilterNull() )
        // 求和聚合
        .aggregate( new Fields( "nameCount" ), new Sum(), new Fields( "allNameCount" ) );

查询服务器业务逻辑说明：

1. 每个DRPC请求被作为一个独立的小批处理任务来看待，整个请求参数被作为单个元组处理。此元组仅仅包含一个args字段，对应客户端传递来的请求参数字符串
2. 首先，Split函数对请求参数进行分割
3. 操作符stateQuery能够对TridentState对象进行查询。TridentState对象由拓扑前一部分的persistentAggregate调用暴露 —— 持久化后的聚合结果允许后续的查询操作。stateQuery接受三个参数：
   1. 状态源，在本例中即持久化的人名统计结果
   2. 用于查询的函数，在本例中是MapGet，输入字段name作为函数入参
   3. 查询结果输出字段
4. 上一步的返回值是一个流，我们用FilterNull这个过滤器进行过滤，把空值去掉
5. 最后，调用聚合器Sum进行聚合，结果仍然是一个流。此流会被Trident自动发送给等待结果的客户端

本例中的拓扑需要提交到Storm集群才能运行：

Config conf = new Config();
// 下面4个参数，指定前两个、后两个均可以，不必同时指定
conf.put( Config.NIMBUS_SEEDS, Arrays.asList( "storm-n1.gmem.cc" ) );
conf.put( Config.NIMBUS_THRIFT_PORT, 6627 );
conf.put( Config.STORM_ZOOKEEPER_SERVERS, Arrays.asList( "zookeeper-1.gmem.cc", "zookeeper-2.gmem.cc", "zookeeper-3.gmem.cc" ) );
conf.put( Config.STORM_ZOOKEEPER_PORT, 2181 );
conf.put( Config.DRPC_SERVERS, Arrays.asList( "storm-n1.gmem.cc" ) );
conf.setDebug( true );
conf.setNumWorkers( 8 ); // 此拓扑总计使用的Worker进程数量
// 下面的属性指定打包好的、包含了拓扑依赖的JAR的位置，StormSubmitter会自动读取此属性，并上传JAR到Nimbus
// 此JAR被上传到${storm.local.dir}/nimbus/inbox/目录下
System.setProperty( "storm.jar", "/home/alex/JavaEE/projects/idea/storm-study/target/storm-study-1.0-SNAPSHOT-jar-with-dependencies.jar" );
// 提交拓扑，提交后拓扑立即持续运行，除非被杀死
StormSubmitter.submitTopologyWithProgressBar( "name-counter-trident-topology", conf, topology.build() );

下面是一个纯粹的DRPC拓扑，用于计算按需计算URL的Reach值。Reach值针对单个URI，统计暴露于此URI的用户的数量。具体算法是，针对给定的URI，获取所有推特了此URI的用户、以及这些用户的Follower，并将所有这些用户去重、计数。

计算Reach对于单台机器来说，计算密集度太高了，它可能上千个数据库查询、上千万的元组处理。利用Trident可以很轻松的实现并行处理。

该DRPC拓扑拓扑会读取两个状态源：一个映射URI到推特了此URI的用户的列表；另外一个映射用户到其Follower的列表：

package cc.gmem.study.storm.twt;

import org.apache.storm.trident.TridentState;
import org.apache.storm.trident.TridentTopology;
import org.apache.storm.trident.operation.Aggregator;
import org.apache.storm.trident.operation.CombinerAggregator;
import org.apache.storm.trident.operation.builtin.Count;
import org.apache.storm.trident.operation.builtin.MapGet;
import org.apache.storm.trident.state.StateFactory;
import org.apache.storm.trident.tuple.TridentTuple;
import org.apache.storm.tuple.Fields;

public class ReachCounter {

    public static void main( String[] args ) {
        TridentTopology topology = null;

        // 创建两个代表外部数据库的TridentState对象，注意针对这些状态源的查询会自动批量处理以提升性能
        TridentState urlToTweeters = topology.newStaticState( getUrlToTweetersState() );
        TridentState tweetersToFollowers = topology.newStaticState( getTweeterToFollowersState() );

        // 定义一个reach函数
        topology.newDRPCStream( "reach" )
                // 读取参数URI，查询urlToTweeters获得推特了此URI的用户，结果存入tweeters字段
                .stateQuery( urlToTweeters, new Fields( "args" ), new MapGet(), new Fields( "tweeters" ) )
                // 展开列表
                .each( new Fields( "tweeters" ), new ExpandList(), new Fields( "tweeter" ) )
                // 下一步查询的计算密集度很高，因此洗牌，让所有tweeter平均的分布到拓扑的所有Worker中
                .shuffle()
                // 针对每个用户，查询其Followers
                .stateQuery( tweetersToFollowers, new Fields( "tweeter" ), new MapGet(), new Fields( "followers" ) )
                // 并行度提示
                .parallelismHint( 200 )
                // 展开Follower并分组
                .each( new Fields( "followers" ), new ExpandList(), new Fields( "follower" ) )
                .groupBy( new Fields( "follower" ) )
                // 使用聚合器One进行聚合，实际上就是去重
                .aggregate( (Aggregator) new One(), new Fields( "one" ) )
                .parallelismHint( 20 )
                // 统计总数
                .aggregate( new Count(), new Fields( "reach" ) );
    }

    // CombinerAggregator知道如何进行局部聚合，避免发送大量网络数据
    public static class One implements CombinerAggregator<Integer> {

        // 根据未聚合前的元组，计算其单个元素的聚合值
        public Integer init( TridentTuple tuple ) {
            return 1;
        }

        // 聚合两个值
        public Integer combine( Integer val1, Integer val2 ) {
            return 1;
        }

        public Integer zero() {
            return 1;
        }
    }
}

Trident能够智能的决定如何执行拓扑，让性能最大化。在上面的例子中，我们应当注意一些有趣的细节：

1. 对于需要对状态源进行读、写的操作（persistentAggregate、stateQuery），会自动的批量式的和源交互。如果当前批次需要对状态源进行20个更新操作，Trident会自动将这20个操作进行批量提交，不管是20个写还是读。也就是说Trident仅仅和状态源进行一次交互
2. Trident的聚合器是高度优化的，它不会把分组中所有的元组传递给单台机器，然后进行聚合。它会尽可能的多执行局部聚合，避免跨越网络发送不必要的流量。例如聚合器Count会在每个节点上进行部分计数，把部分计数通过网络发送，最终获得总合计数。这种行为特点和MapReduce的combiners类似

Trident数据模型由TridentTuple表示，和普通Storm元组一样，它也是命名值的列表。

在Trident拓扑中，操作节点通常将若干输入字段作为参数，并释放一系列函数字段（function Fields），这些新字段被添加到元组中。

考虑一个流stream，释放三元素x、y、z构成的元组，下面的过滤器仅仅把y字段作为输入：

// 将每一个元组的y字段暴露给过滤器处理
stream.each(new Fields("y"), ( new BaseFilter() {
   // 此操作节点仅仅能够访问y字段
   public boolean isKeep(TridentTuple tuple) {
       return tuple.getInteger(0) < 10;
   }
})());

上述过滤器将仅保留y小于10的那些元组。 再看看下面的函数：

stream.each( new Fields( "x", "y" ), ( new BaseFunction() {
    public void execute ( TridentTuple tuple, TridentCollector collector){
        int i1 = tuple.getInteger( 0 );
        int i2 = tuple.getInteger( 1 );
        // 释放两个字段
        collector.emit( new Values( i1 + i2, i1 * i2 ) );
    }
}),new Fields( "added", "multiplied" ) /* 定义函数释放字段的名称 */);

该函数以x、y字段为输入字段，同时定义了两个输出字段 —— 这些输出字段是添加到输入元组上的，这导致输入元组现在有5个字段：x、y、z、added、multiplied。

使用聚合器的情况下，输出字段则是代替了输入字段，此外输入输出元组也不是一一对应关系：

// 收集所有输入元组的x字段并求和，求和存放到唯一一个输出元组的sum字段
stream.aggregate(new Fields("x"), new Sum(), new Fields("sum"));

使用分组+聚合器的情况下，输出字段同时包含分组所依据的字段：

stream.groupBy(new Fields("x"))
     .aggregate(new Fields("y"), new Sum(), new Fields("sum"));
// 输出字段为x,sum

类似于原始Storm API，Trident的数据来源也是Spout。

你可以在Trident中使用原始的Spout，这种Spout是非事务性的：

// 所有Trident拓扑中的Spout必须具有唯一性的id。注意，必须是全局唯一，在集群中所有拓扑里都唯一
// Trident使用此id在ZooKeeper中记录Spout被消费的状态，包括txid以及其它相关元数据
topology.newStream("spoutid", new IRichSpout(){/**/});

要定制ZooKeeper相关参数，修改transactional.zookeeper.*配置项。 

Trident拓扑的默认行为是，每次处理一个批次。当前批次成功或者失败后，才可能处理下一个批次。

通过管线化批次的处理流，可以大大提升拓扑的吞吐能力、降低单个批次的处理延迟。要定制同时能够处理的批次的最大数量，修改topology.max.spout.pending参数。

即使同时处理多个批次，Trident的严格有序语义保持不变 —— 状态更新总是串行化、有序的执行。以单词统计为例，当Batch 1进行全局聚合的时候，Batch 2...10不能进行全局聚合，但是它们可以进行分区的部分聚合。

Trident提供以下专有类型的Spout：

实时计算的一个关键问题是，如何管理状态——包括外部数据源的状态、拓扑的内部状态——以确保当失败、重试发生时，对状态的更新是幂等的。 在生产环境中，失败是常态，当节点宕机或者出现其它问题，只能重试处理元组批次。所谓幂等，可以简单的理解为，每个元组批次导致的状态更新，仅仅发生一次。

Trident确保幂等性的机制是：

1. 每个元组批次被赋予唯一性的ID，所谓事务ID。如果发生重试，批次的事务ID保持不变
2. 不同批次之间的状态更新，是严格有序的。也就是说，Batch3对状态源的更新动作不会发生，直到Batch2的状态更新动作完成

这种处理机制和Storm中的事务性拓扑类似。但是，你不需要像事务性拓扑那样，自己记录txid、比较txid、存储多个数据项，这些工作已经由Trident的状态抽象封装起来了。

你可以选择任何期望的策略来存储状态。例如存放在外部数据库中、存放在内存中并以HDFS作为后备。

状态信息也非必须永久保存，你可以考虑使用内存状态存储，并仅仅保留最近N个小时的数据。

可能和容错相关的Spout有三类：非事务性的、事务性的、不透明事务性的，相应的，对应了三类状态对象：

["man"] ["man"] ["dog"]

# 一定要保证，状态和txid原子性的入库
man => [count=3, txid=1]        # After [count=5, txid=3]
dog => [count=4, txid=3]        # After [count=4, txid=3]
apple => [count=10, txid=2]

man => (
    // 对于每个单词，存储三个字段，这些字段仍然需要原子的更新
    value => 4,        // 本次事务更新后的值
    prevValue => 1,    // 本次事务更新前的值
    txid => 2          // 本次事务ID
)

["man"] ["man"]

man => ( value => 3, prevValue => 1,txid => 2 )

["man"] ["man"]

man => ( value => 5, prevValue => 3,txid => 3 )

三种Spout必须搭配对应类型的状态实现使用：

其中非透明事务性状态具有最强的容错能力，但是要为每个状态数据存储额外的两个字段。事务性状态仅需要存储一个额外的字段，但是它只能和事务性Spout搭配使用。

上节讨论的复杂的存储细节，并不需要开发者自行实现。Trident已经把它们全部封装到状态API中了。

调用partitionPersist、persistentAggregate等方法，即可创建一个状态对象，例如： 

TridentState wordCounts =
      topology.newStream("spout", spout)
        .each(new Fields("sentence"), new Split(), new Fields("word"))
        .groupBy(new Fields("word"))
        // 所有管理不透明事务状态的逻辑，都封装在MemcachedState.opaque()返回的状态（工厂）中
        // 更新的批量处理逻辑，也被封装在状态中
        .persistentAggregate(MemcachedState.opaque(serverLocations), new Count(), new Fields("count"))                
        .parallelismHint(6);

状态（源）是一个接口，它很简单：

public interface State {
    // 更新开始时，获得通知
    void beginCommit(Long txid);
    // 更新结束时，获得通知
    void commit(Long txid);
}

Trident不对你的状态的工作方式做任何假设，它不规定调用什么方法可以更新状态，调用什么方法可以读取状态。

假设有一个存储用户位置的数据库，你想通过Trident访问它，可以这样实现State：

public class LocationDB implements State {
    public void beginCommit(Long txid) {    
    }

    public void commit(Long txid) {    
    }

    public void setLocation(long userId, String location) {
      // 更新位置
    }

    public String getLocation(long userId) {
      // 读取位置
    }
}

// 除了实现State，还需要提供配套的StateFactory
public class LocationDBFactory implements StateFactory {
   public State makeState(Map conf, int partitionIndex, int numPartitions) {
      return new LocationDB();
   } 
}

为了支持状态的查询，Trident提供了QueryFunction接口。 为了支持状态的更新，Trident提供了StateUpdater接口。状态和状态的支持的操作被解耦，如此设计是因为Trident难以对特定状态源的工作方式作出合理假设。

沿用上面的例子，QueryFunction的实现示例如下：

// QueryFunction总是针对状态源 + 结果类型的组合（泛型参数）
public class QueryLocation extends BaseQueryFunction<LocationDB, String> {
    // 第一步：以输入元组inputs为查询参数，获得一系列结果
    // 结果的元素和inputs的元素一一对应，输入元组有几个，则输出结果有几个
    public List<String> batchRetrieve(LocationDB state, List<TridentTuple> inputs) {
        List<String> ret = new ArrayList();
        // State可以暴露批量查询的接口，避免类似下面这种细粒度的交互
        for(TridentTuple input: inputs) {
            ret.add(state.getLocation(input.getLong(0)));
        }
        return ret;
    }
    // 第二步：每对输入-输出的组合，被传递给下面的方法。你可以在此释放元组，供拓扑的下一节点处理
    public void execute(TridentTuple tuple, String location, TridentCollector collector) {
        collector.emit(new Values(location));
    }    
}

使用上述QueryFunction的代码示例：

TridentState locations = topology.newStaticState(new LocationDBFactory());
topology.newStream("spout", spout)
        // 通过QueryFunction对State发起查询，输入元组字段userid，查询结果保存字段location
        .stateQuery(locations, new Fields("userid"), new QueryLocation(), new Fields("location"));

StateUpdater的实现示例如下：

public class LocationUpdater extends BaseStateUpdater<LocationDB> {
    // 将一批元组tuples更新到状态源state中
    public void updateState(LocationDB state, List<TridentTuple> tuples, TridentCollector collector) {
        List<Long> ids = new ArrayList<Long>();
        List<String> locations = new ArrayList<String>();
        for(TridentTuple t: tuples) {
            ids.add(t.getLong(0));
            locations.add(t.getString(1));
        }
        // 应当实现批量更新
        state.setLocationsBulk(ids, locations);
    }
}

// 你可以调用collector来释放新的元组，这些元组的流可以通过TridentState.newValuesStream()方法获得

使用上述StateUpdater的代码示例：

TridentState locations = 
    topology.newStream("locations", locationsSpout)
        // 将输入元组的分区入库
        .partitionPersist(new LocationDBFactory(), new Fields("userid", "location"), new LocationUpdater());
// 返回代表将会被更新的状态源

除了partitionPersist，Trident提供的另外一类可以更新状态源的API是persistentAggregate。此API是建立在partitionPersist上的一层抽象，它知道如何使用Trident聚合器，将聚合后的数据更新到状态源。

你可以针对GroupedStream调用persistentAggregate，参数必须提供MapState接口的实现。此接口的签名如下：

public interface MapState<T> extends State {
    // 以多个元组（keys）作为参数，获取对应的值
    List<T> multiGet(List<List<Object>> keys);
    // 对每个元组，用相应的ValueUpdater更新之
    List<T> multiUpdate(List<List<Object>> keys, List<ValueUpdater> updaters);
    // 存储多个元组及其对应的状态值
    void multiPut(List<List<Object>> keys, List<T> vals);
}

如果要对非分组流进行（全局性）聚合，State对象必须实现下面的接口：

public interface Snapshottable<T> extends State {
    T get();
    T update(ValueUpdater updater);
    void set(T o);
}

MemoryMapState、MemcachedState 实现了 MapState、Snapshottable接口。

当实现自己的MapState时，你不需要从零开始。Trident提供了OpaqueMap、TransactionalMap、NonTransactionalMap类，并把容错相关逻辑封装其中。你需要做的是，为这三个类提供IBackingMap实现：

// 你仅仅需要关注如何读取、存储键值
public interface IBackingMap<T> {
    List<T> multiGet(List<List<Object>> keys); 
    // 对于OpaqueMap，T必须是OpaqueMap；对于TransactionalMap，T必须是TransactionalValue；
    // 对于NonTransactionalMap，T就是裸的聚合值
    void multiPut(List<List<Object>> keys, List<T> vals); 
}

Trident提供了基于LRU缓存算法的IBackingMap实现：CachedMap，继承它以实现具有缓存特性的状态源。

Trident提供了SnapshottableMap，可以把MapState转变为Snapshottable，其实就是全局使用单个key进行分组。

Trident拓扑会被尽可能编译为高效的Storm拓扑，仅仅在发生数据重分区（例如洗牌、分组）时，元组才通过网络传输。

一个可能的Trident拓扑和Storm拓扑的对应关系如下图：

可以看到，Storm以分区节点为界，从Trident拓扑划分出多个Bolt。这些Bolt内部可能包含了多个Trident节点，它们可能被分配到一个Worker中执行，避免了不必要的网络数据拷贝。

Trident的核心数据模型是流，流由一系列的元组批次构成。流可能跨越集群的多个节点而分区，应用到流的操作针对每个分区并行执行。

Trident的操作包含五种类型：

1. 在分区本地运行，不牵涉到网络流量的
2. 重新分区操作，仅仅对流进行重新分区，不改变流的内容
3. 聚合操作，产生一定的网络流量
4. 针对分组（Grouped）流的操作
5. 合并、连接操作

// 仅仅保留b、d两个字段
stream.project(new Fields("b", "d"))

stream.partitionAggregate(new Fields("price"), new Sum(), new Fields("sum"));
// 输出元组包含一个字段 

这类操作运行一个函数，来决定分组如何在不同Task之间分配。重新分区后，分区数量可能改变，你可以调用

parallelismHint()

重新分区操作可能导致网络流量，支持的重新分区函数有：

Trident提供两个全局性（针对所有分区）的聚合操作：

这些定义在TridentTopology上的API用于把不同的流合并到一起：

topology.merge(stream1, stream2, stream3);

// userStream包含字段 id, personId, loginName
// personStream包含字段 id, personName
topology.join(
    userStream, new Fields("personId"), personStream, new Fields("id"),
    // 连接后的流的字段，第一个字段对应用于连接的那个字段
    // 后续一次是前一个、后一个流中，不属于连接字段的所有字段，按照顺序逐一对应
    new Fields("personId","userId","loginName","personName")
);

注意：针对全局性聚合使用：

1. ReducerAggregator或者Aggregator时，流首先被重分区到单个分区，然后聚合器在此新分区上执行
2. CombinerAggregator时，首先进行局部聚合，然后重分区到单个分区，最后完成聚合操作

局部聚合可以大大减少网络流量，因此应该尽可能使用CombinerAggregator。

partitionAggregate、aggregate、persistentAggregate等操作，在调用时需要传入聚合器。聚合器相关的接口有三种：

public interface CombinerAggregator<T> extends Serializable {
    // 针对每个输入元组，进行初始化，产生一个值
    T init(TridentTuple tuple);
    // 每个元组产生的值，一次被送入下面的函数进行reduce，直到仅剩一个值
    T combine(T val1, T val2);
    // 如果没有任何输入元组，调用此函数
    T zero();
}

public interface ReducerAggregator<T> extends Serializable {
    // 初始值
    T init();
    // 针对每个输入元组进行reduce
    T reduce(T curr, TridentTuple tuple);
}

public interface Aggregator<T> extends Operation {
    // 在处理每个批次之前，调用返回值是一个代表了聚合状态的对象，会被传递给后面两个方法
    T init(Object batchId, TridentCollector collector);
    // 针对批次分区中每个输入元组调用。此方法会更新state，还可以释放元组
    void aggregate(T state, TridentTuple tuple, TridentCollector collector);
    // 当批次分区中所有输入元组都被处理之后调用此方法
    void complete(T state, TridentCollector collector);
}

某些情况下，你需要连续执行多个聚合器，参考如下方式：

stream.chainedAgg()  // 开始链式聚合
        .partitionAggregate(new Count(), new Fields("count"))
        .partitionAggregate(new Fields("b"), new Sum(), new Fields("sum"))
        .chainEnd();  // 结束链式聚合
// 上述代码针对流进行计数、求和操作，其结果是两个元素构成的单一元组 ["count", "sum"]

Trident支持窗口化（Windowing），即对元组批次中，处于同一窗口中的那些元组进行处理，并释放聚合后的结果给下一个操作。

两种风格的窗口被支持：

1. 滚动窗口（Tumbling window）—— 元组依据单个窗口分组，分窗要么基于处理时间要么基于元组计数。每个元组只能属于一个窗口（不重叠）：
   

   /**
    * 返回一个新流，新流元组由当前流窗口内元组基于aggregator聚合而成
    * 窗口为滚动窗口，每隔windowCount个元组，新建一个窗口
    */
   public Stream tumblingWindow(int windowCount, WindowsStoreFactory windowStoreFactory,
       Fields inputFields, Aggregator aggregator, Fields functionFields);
   
   /**
    * 返回一个新流，新流元组由当前流窗口内元组基于aggregator聚合而成
    * 窗口为滚动窗口，每隔windowDuration这么长时间，新建一个窗口
    */
   public Stream tumblingWindow(BaseWindowedBolt.Duration windowDuration, WindowsStoreFactory windowStoreFactory,
       Fields inputFields, Aggregator aggregator, Fields functionFields);

2. 滑动窗口（Sliding window）—— 分窗依据和上面类似，但是每个一定的间隔（处理时间或元组计数），窗口就向前滑动。元组可以属于多个窗口（重叠）：
   

   /**
    * 滑动窗口，每个窗口包含windowCount个元组，每处理slideCount个元组则窗口向前滑动
    */
   public Stream slidingWindow(int windowCount, int slideCount, WindowsStoreFactory windowStoreFactory,
       Fields inputFields, Aggregator aggregator, Fields functionFields);
   
   /**
    * 滑动窗口，每个窗口时长为windowDuration，每经过slidingInterval则窗口向前滑动
    */
   public Stream slidingWindow(BaseWindowedBolt.Duration windowDuration, BaseWindowedBolt.Duration slidingInterval,
       WindowsStoreFactory windowStoreFactory, Fields inputFields, Aggregator aggregator, Fields functionFields);

除了上面两套API外，Trident还支持一个通用的窗口API：

/**
 * 创建一个窗口
 * @param windowConfig 可以是以下之一：
 *        SlidingCountWindow.of(int windowCount, int slidingCount)
 *        SlidingDurationWindow.of(BaseWindowedBolt.Duration windowDuration, BaseWindowedBolt.Duration slidingDuration)
 *        TumblingCountWindow.of(int windowLength)
 *        TumblingDurationWindow.of(BaseWindowedBolt.Duration windowLength)
 * @param windowStoreFactory  用于存储接收到的元组以及聚合结果，HBaseWindowsStoreFactory是基于HBase的一个实现
 * @param inputFields
 * @param aggregator
 * @param functionFields
 * @return
 */
public Stream window( WindowConfig windowConfig, WindowsStoreFactory windowStoreFactory, Fields inputFields,
    Aggregator aggregator, Fields functionFields );

Trident的资源感知调度器（Resource Aware Scheduler，RAS）API可以用于限制Trident拓扑的资源消耗。此API和基本的Storm RAS API类似，区别只是该API针对Trident流而非Bolts、Spouts调用。示例：

TridentTopology topo = new TridentTopology();
// 默认资源配额，每个Bolt至少获得这么多资源
topo.setResourceDefaults(new DefaultResourceDeclarer();
    .setMemoryLoad(128)
    .setCPULoad(20));
TridentState wordCounts = topology
    .newStream("words", feeder)
    // 针对特定操作步骤（除了grouping、shuffling、shuffling）进行资源配额
    // 由于多个操作可能被合并为单个Bolt，因而结果Bolt的资源是组成它的操作的资源之和
    .parallelismHint(5)
    .setCPULoad(20)
    .setMemoryLoad(512,256)
    .each( new Fields("sentence"),  new Split(), new Fields("word"))
    .setCPULoad(10)
    .setMemoryLoad(512)
    .each(new Fields("word"), new BangAdder(), new Fields("word!"))
    .parallelismHint(10)
    .setCPULoad(50)
    .setMemoryLoad(1024)
    .each(new Fields("word!"), new QMarkAdder(), new Fields("word!?"))
    .groupBy(new Fields("word!"))
    .persistentAggregate(new MemoryMapState.Factory(), new Count(), new Fields("count"))
    .setCPULoad(100)
    .setMemoryLoad(2048);

1. 元组处理代码要尽可能轻量，execute方法中的代码要能够尽快执行完毕。当扩容部署时，性能影响会成倍增加
2. 当内存需求较小（1GB以下）时，考虑使用Guava实现Bolt本地缓存
3. 当需要跨越多个Bolt共享数据时，考虑使用HBase、Phoenix、Redis或者Memcached
4. 尽可能将配置信息外部化到属性文件中，可以避免运维期间不必要的代码重编译

要防止拓扑重部署后，消息被重复处理。使用KafkaSpout时，要确保：

1. SpoutConfig的id、zkroot在重部署后要保持不变。Storm使用这这两个属性决定偏移量在ZooKeeper中的存储路径
2. 注意在生产环境中设置forceFromStart为false。如果设置为true，KafkaSpout会忽略ZooKeeper中存储的偏移量信息，从头开始消费。开发环境下经常设置为true，以重复测试一批消息
3. 如果需要部署同一拓扑的多个版本，则应当分配不同的ClientID，Kafka将不同ClientID作为单独Consumer看待，可以独立的跟踪偏移量

1. 工作进程的个数，设置为节点（机器）数量的整数倍。并行度设置为工作进程数量的整数倍。kafka分区的数量设置为Spout并行度的整数倍
2. 考虑为每个(拓扑,机器)组合启动单个Worker进程
3. 启动较少较大的聚合组件，这类组件在Worker节点上运行一个实例
4. 每个Worker使用一个Acker，0.9开始这是默认值
5. 监控JVM垃圾回收器活动，如果一切正常，应该很少出现Major GC
6. 设置Trident的批量处理延迟为你的应用的端对端延迟的1/2
7. 将Spout最大未决元组数量的初值设置的很小，对于Trident可以设置为1或者拓扑执行器线程数量。然后逐步增加设置值，直到流运行状况稳定。最终到达的值可能接近于：\[2 \times \frac{throughputInSecs}{sec} \times endToEndLatency \]

Worker进程的总数由Supervisor来设置。每个Supervisor都管理若干JVM Slot。你在拓扑上设置的参数，实际上是声明Slot的数量。

对于每个(拓扑,机器)的组合，没有太大必要使用超过1个的Worker。对于一个运行在3个8核节点上的拓扑，并行能力提示是24，每个Bolt在每个机器上配备8个执行器线程。3工作进程 x 8执行器线程的方案，比起24工作进程的方案，有三个优势：

1. 数据被重新分区（shuffle/group-bys）时，分发给的执行器如果在同一进程内，不需要进程间传递数据。本机进程间传递数据缓存需要Work发送 - 本地套接字 - Work接收，尽管不需要使用网卡，仍然比进程内直接调用慢
2. 对于执行聚合功能的组件来说3个使用大后备缓存（backing cache）的组件比起24个使用小缓存的组件，具有更小的effect of skew和更高的LRU效能
3. 较少的Worker进程，意味着较少的控制逻辑流量

1. 检查是否对日志目录具有写权限
2. 检查JVM的堆大小
3. 检查是否所需的库都安装到Worker进程
4. 检查ZooKeeper连接配置
5. 是否正确的为每个Worker节点设置了唯一性机器名，并且写到Storm配置文件中
6. 检查防火墙，允许所有Worker节点、Master节点、ZooKeeper之间的双向通信

典型症状：本地模式下运行正常，但是部属到集群中后工作节点启动即崩溃

可能原因：子网的配置可能有问题，导致节点无法根据hostname相互发现。有时ZeroMQ会因为无法解析主机名而崩溃

解决方案：

1. 在hosts文件中配置主机名和IP地址的映射关系
2. 使用内部DNS服务器

典型症状：

1. 所有的元组均处理失败
2. 处理流程不工作

解决方案：

1. 注意Storm不支持IPv6，可以考虑设置Supervisor的 Child JVM系统属性-Djava.net.preferIPv4Stack=true
2. 子网配置可能有问题，参考上一个问题

典型症状：

1. 一开始处理正常，但是一段时间后，突然停止处理，Spout的元组开始集体fail

解决方案：

1. 可能和ZeroMQ版本有关，可以从2.1.10降级为2.1.7

典型症状：

1. 某些Supervisor不出现在Storm UI中
2. Storm UI刷新后，Supervisor列表发生变化

解决方案：

1. 确保每个Supervisor的本地目录是独立的，不要通过NFS共享本地目录
2. 尝试删除Supervisor的本地目录并重启守护程序。由于Supervisor会为自己创建一个UUID并存放在本地，如果此ID复制到其它节点，Storm集群会出现问题

一定要保证构建JAR时使用的Storm版本和集群使用的Storm版本一致

输出元组中的对象必须实现不变模式。一旦你释放元组到OutputCollector，你就不应该在修改它。

在Storm生命周期中，拓扑会被串行化并存储到ZooKeeper中。这意味着Spout/Bolt必须支持串行化，包括它们的属性。如果某些属性无法支持串行化，考虑在Spout/Bolt的prepare方法中初始化它。这些方法在拓扑组件被分发给Worker进程后才会执行。

报错信息：Caused by: java.lang.RuntimeException: java.io.IOException: Found multiple defaults.yaml resources. You're probably bundling the Storm jars with your topology jar. [jar:file:/apache-storm-1.1.1/storm-local/supervisor/stormdist/name-counter-trident-topology-2-1508312849/stormjar.jar!/defaults.yaml, jar:file:/apache-storm-1.1.1/lib/storm-core-1.1.1.jar!/defaults.yaml]

报错原因：打包时把Storm的JAR包也打到拓扑的JAR包中会导致这个情况的发生。

配置拓扑时，需要指明DRPC服务器的位置：

conf.put( Config.DRPC_SERVERS, Arrays.asList( "storm-n1.gmem.cc" ) );

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

当前比较流行的实时计算框架包括Apache Storm、Apache Spark等。这些框架的功能强大而全面，但是具有以下缺点：

1. 复杂度高，应对某些简单的工作显得笨重
2. 部署Storm、Spark等分布式框架需要预留集群支持，增加开发负担 

Kafka Streams是一个实时计算框架，其特点是：

1. 低门槛：你可以很快的编写一段代码，在单机上运行。要扩容支持生产环境只需要简单的启动多个实例。利用Kafka的并行模型，Kafka Streams能够透明的处理多个实例之间的负载均衡。相比之下，Storm虽然也有本地集群，但是其运行环境和远程集群并不一样
2. 简单而轻量：轻松的嵌入到任何Java应用中，轻松的和现有打包、部署、操作工具整合
3. 没有额外的依赖：除了Kafka本身，没有其它依赖
4. 支持容错的本地状态：可以进行快速有效的有状态操作，例如窗口化Join、聚合
5. 支持精确一次性处理语义：不管是Streams客户端还是Kafka代理出现失败，都能保证一次且仅一次的处理
6. 对于单记录的处理，实现毫秒级延迟。支持基于事件时间对一系列记录进行窗口操作
7. 提供必要的流处理原语，同时提供高层的DSL和低级的Processor API

Kafka Streams针对来自1-N个主题的输入进行持续计算，并把计算结果输出到0-N个输出主题中。

每个KafkaStreams实例可以包含1-N个线程，线程数量在配置中指定，这些线程用于执行数据处理任务。

KafkaStreams实例与其他具有相同Application ID的实例进行协作，这些实例可能分布在同一JVM、不同JVM进程或者不同的机器上。所有相同Application ID的实例的整体，构成一个流处理程序。通过分配输入主题的分区给不同的实例，实现处理任务的划分。如果某个实例宕机，其它实例会瓜分它持有的分区，进行负载再平衡，同时确保任何分区都被消费。

流是Kafka Streams中最重要的一个抽象，它：

1. 是一个无边界的、持续更新的数据集
2. 是一个有序的、容错的、不变的数据记录的序列。数据记录以键值对的形式定义

流处理程序是指，利用Kafka Streams库，以处理器拓扑（Processor Topologies）的形式定义计算逻辑的应用程序。处理器拓扑是节点（流处理器）的有向图，节点通过流连接。

流处理器，以及拓扑节点，它每次从上游流接受一个输入记录，进行转换、处理，可选的释放一或多个记录到下游流中。有两种特殊的流处理器：

1. Source处理器：它没有上游处理器，通过读取Kafka主题，消费其中的记录，并释放到下游流中
2. Sink处理器：它没有下游处理器，负责将记录存储到Kafka主题中

拓扑中的节点可以调用任何外部系统，因而有机会将记录存储在外部，而非必须存储在Kafka主题中。

KafkaStreams的计算逻辑可通过两种方式来定义：

1. 基于 Processor API 定义，生成一个Processor组成的有向无环图（DAG）拓扑。可以访问状态存储
2. 基于StreamsBuilder定义，此类提供一个高层的DSL。支持map、filter、join、aggregation等常见操作

处理器拓扑仅仅是逻辑的抽象，在运行时，该逻辑拓扑会被实例化，并在应用中复制，以增强并行处理能力。

对于流处理来说时间是个很重要的概念，窗口化等操作依赖时间来确定边界。Kafka Streams中有三种时间：

事件时间、吸收时间是二选一的。由Kafka配置参数（在代理或者主题级别）确定，从0.10开始时间戳自动嵌入到Kafka消息中。

接口TimestampExtractor用于抽取时间戳，分配给每个记录，此接口的默认实现简单的从Kafka消息中获取上述嵌入时间戳。抽取到的时间戳被称为Stream Time。TimestampExtractor的实现可以提供不同的Stream Time语义，它可以从记录的任意字段推导出时间戳，或者直接使用墙上时间。

当Sink处理器将记录写入到Kafka主题时，也需要为记录授予时间戳，具体方式取决于上下文：

1. 如果输出记录通过处理某些输入记录而得到，例如在process()中调用了context.forward()方法，输出记录的时间戳直接从输入记录继承
2. 如果输出记录由周期性函数，例如Punctuator#punctuate()生成，则时间戳使用当前Task的内部时间，此内部时间通过context.timestamp()获取
3. 对于聚合操作，结果记录的时间戳更新为最后一个参与聚合的输入记录的时间戳

某些流处理程序需要记录一些状态信息，例如，聚合类的操作需要随时暂存当前的聚合结果。Kafka Streams DSL包含很多状态性的操作。

Kafka Stream引入状态存储（State Store）的概念，流处理程序可以针对其进行状态的读写。每个流处理Task都可以嵌入一个或多个状态存储。转台存储可以实现为持久化键值对存储、内存哈希表或者其他的形式。Kafka Stream为本地状态存储提供容错、自动恢复功能。

交互式查询（Interactive Queries）这一特性，允许进程内部、外部的代码对流处理程序创建的状态存储进行只读的操作。

关于流处理框架的最常见的提问是，该框架能否保证每个记录被处理一次且仅一次，即使在处理过程中出现失败的情况下？

某些业务场景不允许数据丢失或者重复，因此常常引入面向批处理的框架，配合流处理管线，这被称为Lambda架构。

在0.11版本之前，Kafka仅仅提供至少一次性递送保证，因此任何基于Kafka的流处理系统都不能保证端对端的精确一次性。

从0.11版本开始，Kafka支持生产者向不同的分区甚至主题进行事务性、幂等性的消息发送，利用这一特性，Kafka Streams可以支持精确一次性处理：

1. 对于任何从源主题读取来的记录，其处理结果在目的主题上精确的体现一次
2. 对于任何从源主题读取来的记录，其处理结果在有状态操作的状态存储上精确的体现一次

与其他实时处理框架不同的是，Kafka Streams和底层的Kafka存储机制紧密集成，确保对输入主题偏移量的提交、对状态存储的更新、对输出主题的写入能够原子的完成。

要启用精确一次性保证，需要配置processing.guarantee=exactly_once。默认值是at_least_once。

本章引入一个简单的，基于StreamBuilder的流处理程序，作为入门的例子。

下面是一个人名个数统计的例子，它能够在生产环境中弹性（动态增加硬件）、可扩容的部署：

package cc.gmem.study.kafka;

import org.apache.kafka.common.serialization.Serdes;
import org.apache.kafka.streams.KafkaStreams;
import org.apache.kafka.streams.StreamsBuilder;
import org.apache.kafka.streams.StreamsConfig;
import org.apache.kafka.streams.kstream.KStream;
import org.apache.kafka.streams.kstream.KTable;
import org.apache.kafka.streams.kstream.Materialized;
import org.apache.kafka.streams.kstream.Produced;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.util.Arrays;
import java.util.Properties;
import java.util.concurrent.TimeUnit;

public class NameCountApplication {

    private static final Logger LOGGER = LogManager.getLogger( NameCountApplication.class );

    public static void main( final String[] args ) throws Exception {
        Properties config = new Properties();
        // 应用的标识符，不同的实例依据此标识符相互发现
        config.put( StreamsConfig.APPLICATION_ID_CONFIG, "names-counter-application" );
        // 启动时使用的Kafka服务器
        config.put( StreamsConfig.BOOTSTRAP_SERVERS_CONFIG, "kafka-1.gmem.cc:9092" );
        // 键值串行化类
        config.put( StreamsConfig.DEFAULT_KEY_SERDE_CLASS_CONFIG, Serdes.String().getClass() );
        config.put( StreamsConfig.DEFAULT_VALUE_SERDE_CLASS_CONFIG, Serdes.String().getClass() );
        // High Level DSL for building topologies
        StreamsBuilder builder = new StreamsBuilder();
        // KStream是记录（KeyValue）流的抽象
        KStream<String, String> nameBatches = builder.stream( "names" );
        KTable<String, Long> nameCounts = nameBatches
                // 一到多映射，分割字符串
                .flatMapValues( nameBatch -> Arrays.asList( nameBatch.split( "\\W+" ) ) )
                // 根据人名分组
                .groupBy( ( key, name ) -> name )
                // 进行聚合，结果存放到StateStore中
                .count( Materialized.as( "names-count-store" ) );
        // 输出到目标
        nameCounts.toStream().to( "names-count", Produced.with( Serdes.String(), Serdes.Long() ) );
        // 构建流处理程序并启动
        KafkaStreams streams = new KafkaStreams( builder.build(), config );
        LOGGER.trace( "Prepare to start stream processing." );
        streams.start();

        TimeUnit.DAYS.sleep( 1 );  // 阻塞主线程
    }
}

首先，创建输入、输出主题：

kafka-topics.sh --create --zookeeper zk-1.gmem.cc:2181/kafka --replication-factor 1 --partitions 1 --topic names
kafka-topics.sh --create --zookeeper zk-1.gmem.cc:2181/kafka --replication-factor 1 --partitions 1 --topic names-count

然后，通过命令行准备一批空格分隔的人名。并准备好输出主题的消费者：

topic-consume names-count --formatter kafka.tools.DefaultMessageFormatter
    --property print.key=true --property print.value=true 
    --property key.deserializer=org.apache.kafka.common.serialization.StringDeserializer
    --property value.deserializer=org.apache.kafka.common.serialization.LongDeserializer

启动上面的流处理程序，上面的消费者开始输出：

Meng	2
Zhen	2
Cai	4
Dang	3
Ya	4
Alex	5
Alex	6  # 计数更新，发布新记录

每个名字的计数更新后，流处理程序都会在names-count上发布一个记录，其键位人名，值为计数。记录被逐个打印在消费者的标准输出中。 

本章介绍Kafka Streams的底层API。

拓扑是各种处理器和Kafka主题共同构成的网络，要创建拓扑可以参考：

Topology topology = new Topology();
// 指定拓扑的输入，也就是Kafka主题
topology.addSource( "SOURCE", "src-topic" )
        // 添加一个处理器PROCESS1，其上游为拓扑输入（通过名称引用）
        .addProcessor( "PROCESS1", () -> new Processor1(), "SOURCE" )
        // 添加另一个处理器PROCESS2，以PROCESS1为上游
        .addProcessor( "PROCESS2", () -> new Processor2(), "PROCESS1" )
        // 添加另一个处理器PROCESS3，仍然以PROCESS1为上游，注意拓扑分叉了
        .addProcessor( "PROCESS3", () -> new Processor3(), "PROCESS1" )
        // 添加一个输出处理器，输出到sink-topic1，以PROCESS1为上游
        .addSink( "SINK1", "sink-topic1", "PROCESS1" )
        // 添加一个输出处理器，输出到sink-topic2，以PROCESS2为上游
        .addSink( "SINK2", "sink-topic2", "PROCESS2" )
        // 添加一个输出处理器，输出到sink-topic3，以PROCESS3为上游
        .addSink( "SINK3", "sink-topic3", "PROCESS3" );

该接口用于定义一个流处理器，也就是处理器拓扑中的节点。流处理器以参数化类型的方式限定了其键、值的类型。你可以定义任意数量的流处理器，并且连同它们关联的状态存储一起，组装出拓扑。

Processor.process()方法针对收到的每一个记录进行处理。Processor.init()方法实例化了一个ProcessorContext，流处理器可以调用上下文：

1. context().schedule，调度一个Punctuation函数，周期性执行
2. context().forward，转发新的或者被修改的键值对给下游处理器
3. context().commit，提交当前处理进度

下面是基于Processor API的人名个数统计处理器示例：

package cc.gmem.study.kafka.streams.low;

import org.apache.kafka.streams.KeyValue;
import org.apache.kafka.streams.processor.Processor;
import org.apache.kafka.streams.processor.ProcessorContext;
import org.apache.kafka.streams.processor.PunctuationType;
import org.apache.kafka.streams.state.KeyValueIterator;
import org.apache.kafka.streams.state.KeyValueStore;

public class NameCounterProcessor implements Processor<String, String> {

    private ProcessorContext context;

    private KeyValueStore<String, Long> kvStore;

    @Override
    public void init( ProcessorContext context ) {
        // 保存引用，类似于Storm的TopologyContext
        this.context = context;
        // 从上下文中取回一个状态存储
        this.kvStore = (KeyValueStore<String, Long>) context.getStateStore( "NameCounts" );
        // 以墙上时间为准，每秒执行Punctuator逻辑
        this.context.schedule( 1000, PunctuationType.WALL_CLOCK_TIME, timestamp -> {
            NameCounterProcessor.this.punctuate( timestamp );
        } );
    }

    /**
     * 接收一个记录（人名列表）并处理
     *
     * @param dummy 记录的键，无用
     * @param line  记录的值
     */
    @Override
    public void process( String dummy, String line ) {
        String[] names = line.toLowerCase().split( " " );

        // 在键值存储中更新人名计数
        for ( String name : names ) {
            Long oldCount = this.kvStore.get( name );

            if ( oldCount == null ) {
                this.kvStore.put( name, 1L );
            } else {
                this.kvStore.put( name, oldCount + 1L );
            }
        }
    }

    @Override
    public void punctuate( long timestamp ) {
        // 获得键值存储的迭代器
        KeyValueIterator<String, Long> iter = this.kvStore.all();

        while ( iter.hasNext() ) {
            KeyValue<String, Long> entry = iter.next();
            // 转发记录给下游处理器
            context.forward( entry.key, entry.value.toString() );
        }

        /**
         * 调用者必须要负责关闭状态存储上的迭代器
         * 否则可能（取决于底层状态存储的实现）导致内存、文件句柄的泄漏
         */
        iter.close();

        // 请求提交当前流状态（消费进度）
        context.commit();
    }

    @Override
    public void close() {
        // 在此关闭所有持有的资源，但是状态存储不需要关闭，由Kafka Stream自己维护其生命周期
    }
}

要位拓扑中每个Processor提供状态存储，调用：

Topology topology = new Topology();
topology.addSource("Source", "source-topic")
    .addProcessor("Process", () -> new WordCountProcessor(), "Source")
    // 为处理器Process提供一个状态存储 
    .addStateStore(countStoreSupplier, "Process");

为了支持容错、支持无数据丢失的状态迁移， 状态存储可以持续不断的、在后台备份到Kafka主题中。上述用于主题被称为状态存储的changelog主题，或者直接叫changelog。

你可以启用或者禁用状态存储的备份特性。

持久性的KV存储是容错的，它备份在一个紧凑格式的changelog主题中。使用紧凑格式的原因是：

1. 防止主题无限增长
2. 减少主题占用的存储空间
3. 当状态存储需要通过Changelog恢复时，缩短需要的时间

持久性的窗口化存储也是容错的，它基于紧凑格式、支持删除机制的主题备份。窗口化存储的changelog的键的一部分是窗口时间戳，过期的窗口对应的段会被Kafka的日志清理器清理。changelog的默认存留时间是Windows#maintainMs() + 1天。指定StreamsConfig.WINDOW_STORE_CHANGE_LOG_ADDITIONAL_RETENTION_MS_CONFIG可以覆盖之。

启动应用程序时，状态存储通常不需要根据changelog来恢复，直接加载磁盘上持久化的数据就可以。但以下场景中：

1. 宕机导致本地状态丢失
2. 运行在无状态环境下的应用程序重启

状态存储需要基于changelog进行完整的恢复。

如果changelog中的数据量很大，则恢复过程可能相当的耗时。在恢复完成之前，处理器拓扑不能处理新的数据。

要监控状态存储的恢复进度，你需要实现org.apache.kafka.streams.processor.StateRestoreListener接口，并调用KafkaStreams#setGlobalStateRestoreListener注册之。监听器示例：

import org.apache.kafka.common.TopicPartition;
import org.apache.kafka.streams.processor.StateRestoreListener;
// 监听器会被所有org.apache.kafka.streams.processor.internals.StreamThread实例共享，并必须线程安全
public class ConsoleGlobalRestoreListerner implements StateRestoreListener {
    // 在恢复过程开始时回调
    public void onRestoreStart(
            final TopicPartition topicPartition,  // 主题分区
            final String storeName,               // 状态存储名称
            final long startingOffset,            // 需要恢复的起点
            final long endingOffset               // 需要恢复的终点
    ) {}

    // 在恢复一批次数据后回调
    public void onBatchRestored( final TopicPartition topicPartition,
            final String storeName,
            final long batchEndOffset,
            final long numRestored 
    ) {}

    // 恢复完成后回调
    public void onRestoreEnd( final TopicPartition topicPartition,
            final String storeName,
            final long totalRestored ) {}
}

禁用changelog之后，状态存储失去容错性：

// 启用：StateStoreBuilder#withLoggingEnabled(Map<String, String>);
// 禁用：StateStoreBuilder#withLoggingDisabled();

KeyValueBytesStoreSupplier countStoreSupplier = Stores.inMemoryKeyValueStore("Counts");
StateStoreBuilder builder = Stores
    .keyValueStoreBuilder(countStoreSupplier,Serdes.String(),Serdes.Long())
    .withLoggingDisabled();

启用changelog时，你可以为changelog主题提供配置信息：

Map<String, String> changelogConfig = new HashMap();
// 覆盖主题参数
changelogConfig.put("min.insyc.replicas", "1");

Stores...withLoggingEnabled(changelogConfig);

除了使用Kafka内置的StateStore实现之外，你还可以自定义状态存储。 

状态存储的核心接口是org.apache.kafka.streams.processor.StateStore，一些扩展的接口包括KeyValueStore。

你还需要一个创建状态存储的工厂，其接口是org.apache.kafka.streams.processor.state.StoreSupplier。

你可以提供一个org.apache.kafka.streams.processor.StateRestoreCallback，用于从changelog中恢复状态存储。要注册此回调，实现StateStore的init方法：

public void init(ProcessorContext context, StateStore store) {
    context.register(store, false, stateRestoreCallBackIntance);
}

你可以实现org.apache.kafka.streams.processor.BatchingStateRestoreCallback，代替StateRestoreCallback。后者每次恢复一条数据，前者支持批量式的数据恢复。

抽象类AbstractNotifyingRestoreCallback、AbstractNotifyingBatchingRestoreCallback分别实现了StateRestoreCallback、BatchingStateRestoreCallback接口，并同时实现了StateRestoreListener接口。

开发人员可以利用StreamsBuilder，基于Kafka Streams的领域特定语言（DSL）来构建拓扑。

高级API引入了表的概念，表和流可以看做是相同数据集不同视图：

1. Stream as Table：一个流可以看做是一个表的changelog。流中的每条记录都捕获了表的一次状态变更，通过Replay changelog，流可以转变为表。流记录和表行不一定是1:1对应关系，流记录可能经过聚合，更新到表中的一行
2. Table as Stream：表可以看做是某个瞬间的、流中每个键的最终值构成的快照。迭代表中的键值对很容易将其转换为流

在Kafka Streams中，状态存储的跨机器复制（容错，基于changelog）就利用了流表二元性。

该接口是对记录的流的抽象，每个记录是无边界的数据集中的一个自包含的数据。 

对于发送到KStream的两个记录("Alex", 1)、("Alex", 3)，假设流处理程序进行sum（人名统计）操作，则返回结果是4。

该接口是对changelog流的抽象，此流中的每个记录代表了针对某个特定key的数据更新。 

对于发送到KTable的两个记录("Alex", 1)、("Alex", 3)，相当于对键Alex进行两次更新，返回结果是3。

类似于KTable，但是跨越所有KafkaStreams实例进行复制。 GlobalKTable支持通过key来查询value，在进行Join操作时，需要使用这种查询。

通过读取Kafka主题，即可为Kafka Streams提供输入流。首先你需要实例化一个StreamsBuilder：

StreamsBuilder builder = new StreamsBuilder();

KStream<String, Long> nameCounts = builder.stream( 
    "names-counts-input-topic",  // 输入主题名称
    Consumed.with(Serdes.String(), Serdes.Long()) // 指定键值的串行化器
);

KStream对应了从输入主题读取的、分区化的记录的流。流处理程序的每个实例，都会消费输入主题的分区的子集，并且在整体上保证所有分区都被消费。

KTable<String, Long> nameCounts = builder.table(
    Serdes.String(), /* 键串行化器 */
    Serdes.Long(),   /* 值串行化器 */
    "name-counts-input-topic", /* 输入主题 */
    "name-counts-partitioned-store" /* 表名 */);

可以把任何主题看做是changelog，并将其读入到KTable。当：

1. 记录的键不存在时，相当于执行INSERT操作
2. 记录的键存在，值不为null时，相当于执行UPDATE操作
3. 记录的键存在，值为null时，相当于执行DELETE操作

KTable对应了从输入主题读取的、分区化的记录的流。流处理程序的每个实例，都会消费输入主题的分区的子集，并且在整体上保证所有分区都被消费。

你可以为KTable提供一个名称，此名称也是KTable对应的状态存储的名称。只有命名的KTable才支持交互式查询。

GlobalKTable<String, Long> nameCounts = builder.globalTable(
    Serdes.String(), /* 键串行化器 */
    Serdes.Long(),   /* 值串行化器 */
    "name-counts-input-topic", /* 输入主题 */
    "name-counts-global-store" /* 表名 */);

KStream和KTable支持一系列的转换操作，这些高层操作都可以被转换为1-N个连接在一起的处理器。由于KStream、KTable都是强类型的，因此这些转换操作都以泛型的方式定义。

某些KStream转换操作可以产生一个（例如filter/map）或多个（例如branch）KStream对象，另外一些则产生一个KTable对象（例如aggregation）。

对于KTable来说，所有的转换操作都只能产生另一个KTable。

不依赖于任何状态即可完成转换，不要求流处理器有关联的StateStore。

KStream<String, Long> stream = ...;
KStream<String, Long>[] branches = stream.branch(
        (key, value) -> key.startsWith("A"), /* 以A开头的键  */
        (key, value) -> key.startsWith("B"), /* 以B开头的键 */
        (key, value) -> true                 /* 所有其它的记录均发往此流  */
);

// 仅保留正数值
stream.filter((key, value) -> value > 0);
// 针对一个KTable进行过滤，结果物化到一个StageStore中
Materialized m = Materialized.<String, Long, KeyValueStore<Bytes, byte[]>>as("filtered")
table.filter((key, value) -> value != 0, m);

KStream<String, Integer> transformed = stream.flatMap(
    (key, value) -> {
        // 键值对的列表
        List<KeyValue<String, Integer>> result = new LinkedList<>();
        result.add(KeyValue.pair(value.toUpperCase(), 1000));
        result.add(KeyValue.pair(value.toLowerCase(), 9000));
        return result;
    }
);

stream.foreach((key, value) -> System.out.println(key + " => " + value));

KGroupedStream<byte[], String> groupedStream = stream.groupByKey(
    // 如果键值的类型不匹配配置的默认串行化器，则需要明确指定：
    Serialized.with(
         Serdes.ByteArray(),
         Serdes.String())
);

KGroupedStream<String, String> groupedStream = stream.groupBy(
    (key, value) -> value,  // 产生键值对value:value并依此分组
    Serialize.with(
         Serdes.String(), /* 键的类型发生改变 */
         Serdes.String())  /* value */
); 

KGroupedTable<String, Integer> groupedTable = table.groupBy(
    // 产生键值对  value:length(value)，并依此分组
    (key, value) -> KeyValue.pair(value, value.length()),
    Serialized.with(
        Serdes.String(), /* 键的类发生改变 */
        Serdes.Integer()) /* 值的类型发生改变  */
);

KStream<byte[], String> stream = ...;
KStream<String, Integer> transformed = stream.map(
    (key, value) -> KeyValue.pair(value.toLowerCase(), value.length()));

stream.print(Printed.toFile("stream.out"));

KStream<String, String> rekeyed = stream.selectKey((key, value) -> value.split(" ")[0])

table.toStream();

这类转换操作需要依赖于某些状态信息。例如在聚合性操作中，会使用窗口化状态存储来保存上一个窗口的聚合结果。在Join操作中，会使用窗口化状态存储到目前为止接收到的、窗口边界内部的所有记录。

状态存储默认支持容错，如果出现失败，则Kafka Streams会首先恢复所有的状态存储，然后再进行后续的处理。

高级的有状态转换操作包括：聚合、Join，以及针对两者的窗口化支持。

KGroupedStream<Bytes, String> groupedStream = null;
KGroupedTable<Bytes, String> groupedTable = null;
// 聚合一个分组流，值类型从字符串变为整数
KTable<Bytes, Long> aggregatedStream = groupedStream.aggregate(
        () -> 0L, /* 初始化器 */
        ( aggKey, newValue, aggValue ) -> aggValue + newValue.length(), /* 累加器 */
        Serdes.Long(), /* 值的串行化器 */
        "aggregated-stream-store" /* 状态存储的名称 */ );

KTable<Bytes, Long> aggregatedTable = groupedTable.aggregate(
        () -> 0L, /* 初始化器 */
        ( aggKey, newValue, aggValue ) -> aggValue + newValue.length(), /* 累加器 */
        ( aggKey, oldValue, aggValue ) -> aggValue - oldValue.length(), /* 减法器 */
        Serdes.Long(), /* 值的串行化器 */
        "aggregated-table-store" /* 状态存储的名称 */ );

KGroupedStream<String, Long> groupedStream = null;

// 基于时间的窗口化（滚动窗口）
KTable<Windowed<String>, Long> timeWindowedAggregatedStream = groupedStream
        .windowedBy( TimeWindows.of( TimeUnit.MINUTES.toMillis( 5 ) ) )
        .aggregate(
                () -> 0L, /* 初始化器 */
                ( aggKey, newValue, aggValue ) -> aggValue + newValue, /* 累加器 */
                /* 状态存储 */
                Materialized.<String, Long, WindowStore<Bytes, byte[]>>as( "time-windowed-aggregated-stream-store" )
                        .withValueSerde( Serdes.Long() ) );
// 基于会话的窗口化
KTable<Windowed<String>, Long> sessionizedAggregatedStream = groupedStream
        .windowedBy( SessionWindows.with( TimeUnit.MINUTES.toMillis( 5 ) ) ) /* 窗口定义 */
        .aggregate(
                () -> 0L, /* 初始化器 */
                ( aggKey, newValue, aggValue ) -> aggValue + newValue, /* 累加器 */
                ( aggKey, leftAggValue, rightAggValue ) -> leftAggValue + rightAggValue, /* 会话合并器 */
                Materialized.<String, Long, SessionStore<Bytes, byte[]>>as( "sessionized-aggregated-stream-store" ).withValueSerde( Serdes.Long() ) );

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

Apache Kafka（音标/'ka:fka:/）是一个分布式的实时数据处理的基础平台，能够处理每秒百万条数据。它具有三大功能：

1. 订阅/发布：类似于传统MOM的功能，将队列、主题合二为一
2. 流处理：支持编写可扩容的流处理程序，对实时事件做出响应
3. 存储：安全的存储数据流，支持分布式、复制的、容错等特性

Kafka非常适用于以下几类应用场景：

1. 构建能够可靠的在系统或应用程序之间收发实时流的数据管线
2. 构建能够转换、处理流数据的实时应用程序

Kafka天生使用集群架构，由1-N个服务器构成的集群组成。Kafka集群对流记录进行分类存储，每个类别叫做主题（Topic）。每个流记录包含一个键、一个值、一个时间戳。

Kafka提供四类核心API：

1. Producer API：允许应用程序发布流记录到Kafka主题
2. Consumer API：允许应用程序订阅主题，并处理发布到这些主题的流记录
3. Streams API：允许一个应用程序作为流处理器（Strem Processor），消费来自1-N个主题的输入流，并向1-N个主题释放输出流 —— 也就是高效的进行流转换
4. Connector API： 允许构建可重用的生产者、消费者，把Kafka和既有的应用程序和数据系统连接起来。例如，针对RDBMS的连接器能够捕获针对表的每一个写操作

客户端和Kafka的通信协议基于简单、高效、语言无关的方式设计，以TCP协议为基础，支持版本化（向后兼容）。Kafka提供了Java以及其它语言的客户端。

主题即记录的流，Kafka中的主题可以具有多个订阅者。对于每个主题，Kafka集群维护分区化（partitioned）存储的日志：

1. 每个分区是有序的、不可变的记录的序列，仅仅支持向序列的尾部添加记录
2. 分区中的每个记录被分配一个序列号 —— offset，此序列号在分区中唯一的标识记录
3. 集群在一个可配置的时间段内保留记录，不管记录有没有消费过，这个行为不同于传统MOM，后者不保留消费过的消息。不管配置的保留时间有多长，都不会影响Kafka的性能，这意味着你可以将Kafka作为数据库使用

每个消费者需要记录它当前正在消费的记录的偏移量（游标），通常情况下，消费者会线性的向前单步移动偏移量，这和传统MOM消费者的行为对应。但是，Kafka允许消费者任意移动游标，这个特性可用于实现Replay功能。

上述主题日志的分区，可以：

1. 跨越Kafka集群中多个服务器存储
2. 每个分区可以具有可配置数量的副本，用于容错

在启用复制的情况下，持有同一分区的多个服务器，其中一个被选举为Leader，其它则作为Followers。Leader处理所有针对分区的读写请求，Followers则仅仅进行复制。每个服务器都作为一些分区的Leader，另一些分区的Follower，以实现负载均衡。

生产者负责发布记录到主题上，它决定把哪个记录分配到哪个分区上。可选的策略例如循环轮询（round-robin）、某种和应用语义有关的方式（依据记录的某些键）。

Kafka的一个重要设计特点是，不区分主题、队列。这个特点是它灵活的消费模型提供的。

消费者可以将自己标记为属于某个消费者组（consumer group），发布到主题的每个记录会递送给消费者组消费，仅仅组中一个成员可以消费某个记录。这意味着：

1. 某个主题仅仅包含单个消费者组：这种配置相当于传统MOM的多消费者的队列
2. 某个主题包含多个单成员的消费者组：这种配置相当于传统MOM的主题

Kafka中消费行为的实现方式是：根据消费者数量，对日志分区进行划分。在任意时刻，每个消费者都公平的享有某一部分分区，此行为由Kafka协议动态处理。如果新的消费者加入，它将从其它消费者那里接管一部分分区。如果某个消费者宕机，它拥有的分区将由剩余的消费者瓜分。

Kafka仅仅在分区内部保证顺序性，在大部分情况下，基于记录键的分区+分区内有序是足够满足需要的。如果一定需要全局性顺序保证，你可以设计仅仅包含单个分区的主题，并且对于每个消费者组，仅仅有单个消费者。

Kafka提供以下保证：

1. 一个生产者发布到某个特定分区的记录，保证按照其发送顺序附加到日志的尾部
2. 消费者看到的记录顺序，和它们在分区中存储的顺序一致
3. 对于具有复制因子N的主题，Kafka允许N-1服务器同时宕机，而不丢失任何已经提交到日志的记录

传统的消息系统模型有两种：队列、订阅/发布。队列的优势是容易实现消费者的负载均衡，但是消息一旦被消费就消失不能供多人消费，订阅/发布（主题）的优缺点则刚好相反。

Kafka的创新之处在于，将队列、主题合而为一。

Kafka还提供比传统MOM更强的有序性。尽管传统MOM支持多个消费者，消息也是按序被消费的，但是这些消费者接收消息是异步的，顺序无法保证。Kafka的分区机制能够增强有序性，分区被特定单个消费者消费，不会出现顺序混乱的情况。

Kafka主题中的记录被消费后，不会消失，这让它可以作为in-flight消息的存储系统。

事实上，Kafka是一个优秀的存储系统，因为：

1. 写入的数据被复制，支持容错。Kafka允许生产者等待一个Ack —— 记录被合理复制、持久化后才认为操作成功
2. 磁盘数据结构非常可扩容，不管是存储10KB还是10TB记录，性能不会有显著变化

Kafka不仅仅能够用来读取、写入、存储数据流，它还能用来进行实时流处理。

在Kafka中，一个流处理器是这样的一个程序：它接受持续不断的数据流输入（从主题），处理后产生持续不断的数据流输出（到主题）。

使用Producer/Consumer可以实现先单的流处理器，更复杂的需求可以基于Streams API实现。Streams API支持聚合、连接等操作，支持乱序数据处理、输入再加工、有状态计算等应用场景。

Streams API在Kafka提供的核心原语上构建，它使用生产者/消费者API作为输入，使用Kafka作为状态存储，使用组机制实现多个流处理器的负载均衡。

联用Kafka的存储+低延迟订阅功能，可以让你处理历史、未来数据的方式变得一致 —— 基于Kafka的应用程序可以处理历史数据，当它处理完最后一个记录时，不需要退出，只需要等待未来的数据到达即可继续处理。Kafka的可靠存储功能，让你可以很容易的集成某些需要定期下线维护的系统。

消息代理可以用于解耦消息生产者和消费者、缓冲待处理消息，Kafka可以作为传统消息代理的替代品。

和大部分消息代理相比，Kafka具有更好的吞吐能力，并内置数据分区、容错等特性。

Kafka的一个原始的应用场景是，辅助重建用户活动跟踪的管线。用户的活动（页面浏览、搜索等）被按照活动类型收集并发布到不同的主题上。订阅这些主题后，可以进行实时处理、实时监控、加载到Hadoop以便离线处理。

活动跟踪的数据量通常情况下比消息传输大的多。

Kafka可以用记录、处理监控数据。它可以从分布式应用中获取度量信息并进行聚合操作。

Kafka可以用来从多个服务器上收集日志，并集中起来（例如存储到HDFS）以处理。Kafka抽象掉日志文件的概念，日志编程一系列消息组成的流。

从0.10开始Kafka内置了一个轻量的流处理框架Kafka Streams，使用此框架可以构建数据处理管线，针对数据进行聚合、转换等操作。

Apache Storm等流处理框架可以和Kafka很好的集成。

Kafka可以作为分布式系统的外部提交日志（commit-log）。提交日志用于辅助节点之间的数据复制、失败节点的再同步。Kafka的log compaction特性用于支持这一应用场景，在这种场景下Kafka类似于Apache BookKeeper。

到Kafka官网下载压缩包，并解压。Kafka是基于JVM的应用，因此你需要事先安装好JRE。

Kafka依赖于ZooKeeper，你可以使用外部的ZooKeeper服务器。或者，利用Kafka提供的脚本，创建一个简单的单节点ZooKeeper实例：

pushd ~/JavaEE/middleware/kafka/ > /dev/null
# 启动ZooKeeper
zookeeper-server-start.sh config/zookeeper.properties

kafka-server-start.sh config/server.properties

# 连接到ZooKeeper，来操控Kafka
# replication-factor 复制因子，也就是数据复制的份数
# partitions 分区数量
kafka-topics.sh --create --zookeeper localhost:2181 --replication-factor 1 --partitions 1 --topic test

除了手工创建主题外，还可以配置，让代理在有客户端尝试发布消息时自动创建不存在的主题。

执行下面的命令可以列出现有的主题：

kafka-topics.sh --list --zookeeper localhost:2181

Kafka提供了一个命令，用于从标准输入或者文件中读取信息，并发布到到主题上：

kafka-console-producer.sh --broker-list localhost:9092 --topic test

默认的每一行输入都作为单独的消息发送。

Kafka提供了一个命令，用于消费消息并将其内容打印到标准输出：

# 从头开始消费
kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic test --from-beginning

如果你在两个Terminal同时打开生产者、消费者，然后在生产者那里输入文字并回车，文字会原样的出现在消费者窗口中。

对于Kafka来说，单个代理也是集群，也就是说它天然是集群的。要配置包含多个代理实例的集群，没有什么特别之处。本节演示如何创建三个实例组成的集群。

cp config/server.properties config/server-1.properties
cp config/server.properties config/server-2.properties

参考下面的示例修改：

# 对于每个集群中的任何一个节点，id必须是唯一的、永久不变的
broker.id=1
# 由于我们准备在一台机器上启动多个代理实例，因此需要定制某些参数：
listeners=PLAINTEXT://:9093
log.dir=/tmp/kafka-logs-1

执行下面的命令启动两个额外的实例，加上本章最初创建的那个，组成三成员的集群：

kafka-server-start.sh config/server-1.properties
kafka-server-start.sh config/server-2.properties

# 复制因子3，表示数据复制三份
# 分区数量1
kafka-topics.sh --create --zookeeper localhost:2181 --replication-factor 3 --partitions 1  --topic reptest

执行下面的命令，可以看到刚刚创建的主题的相关信息，以及各代理实例和主题的关系：

kafka-topics.sh --describe --zookeeper localhost:2181 --topic reptest
# Topic:reptest	PartitionCount:1	ReplicationFactor:3	Configs:
# 对于每个分区（本主题只有一个分区），列出以下信息
# Leader 负责该分区所有读写操作的节点（代理实例）ID
# Replicas 复制此分区的所有节点列表，不管是否alive，不管是否leader
# Isr 和Leader保持同步（in-sync）的节点，这些节点必然是alive的
# 	Topic: reptest	Partition: 0	Leader: 0	Replicas: 0,1,2	Isr: 0,1,2 

使用Kafka Connect这一工具，你可以从其它数据源导入数据到kafka，或者将Kafka中的数据导出到其它系统。对于很多系统来说，导入导出不需要手工编写集成代码。

Kafka Streams是一个客户端库，用于构建输入/输出数据存储于Kafka集群的实时应用或者微服务，并满足可扩容、弹性、容错、分布式的质量需求。

Kafka提供了5类核心API：

要使用此API，可以引入Maven依赖：

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
    <version>1.0.0</version>
</dependency>

此类是一个Kafka客户端，用于发送记录到Kafka集群。此类是线程安全的，使用单个实例通常性能更好。示例代码：

package cc.gmem.study.kafka;

import org.apache.kafka.clients.producer.KafkaProducer;
import org.apache.kafka.clients.producer.Producer;
import org.apache.kafka.clients.producer.ProducerRecord;

import java.util.Properties;

/**
 * Entrypoint
 */
public class Application {

    public static void main( String[] args ) {
        // 指定生产者配置
        Properties props = new Properties();
        props.put( "bootstrap.servers", "172.21.3.1:9092,172.21.3.2:9092,172.21.3.3:9092" );
        props.put( "acks", "all" );  // 仅当所有Replica确认后，才认为记录提交成功
        props.put( "retries", 0 );   // 不重试，注意重试可能引起重复消息
        props.put( "batch.size", 16384 ); // 每个分区可以占用的缓冲区大小
        props.put( "linger.ms", 1 ); // 即使缓冲区有空间，批次也可能立即被发送，此配置引入延迟
        props.put( "buffer.memory", 33554432 ); // 最大可用缓冲区
        // 如何把键值转换为字节
        props.put( "key.serializer", "org.apache.kafka.common.serialization.StringSerializer" );
        props.put( "value.serializer", "org.apache.kafka.common.serialization.StringSerializer" );
        /**
         * 创建生产者
         * 生产者主要由一个缓冲池（存放尚未发送到服务器的记录）和一个后台IO线程（负责将记录转换为请求发送）组成
         *
         */
        Producer<String, String> producer = new KafkaProducer<>( props );

        for ( int i = 0; i < 10; i++ ) {
            String topic = "TEST";
            String key = "KEY-" + Integer.toString( i );
            String value = "VALUE-" + Integer.toString( i );
            /**
             * 生产者记录：需要发送到特定Kafka主题的键值对
             *
             * 你可以为记录指定一个分区号，这样记录会发送到该分区中。如果不指定分区号但是给出了键，则键的哈希
             * 用于确定分区号。如果分区号、键都没有指定，则以循环轮流的方式发送到所有可用分区
             *
             * 你还可以为记录指定一个时间戳，如果不指定默认使用当前时间
             * 如果主题配置为TimestampType#CREATE_TIME，则上述时间戳将被代理使用
             * 如果主题配置为TimestampType#LOG_APPEND_TIME，则代理覆盖记录的时间戳，以实际添加到日志时代理的本地时间为准
             * 实际生效的时间戳将通过RecordMetadata返回给客户端
             *
             */
            ProducerRecord<String, String> record = new ProducerRecord<>( topic, key, value );
            /**
             * 发送方法是异步的，它只是把消息存放到缓冲区中然后立即返回
             * 处于效率考虑，生产者可能批量的发送记录
             */
            producer.send( record );
        }
        /**
         * 必须要保证生产者的关闭，否则线程、缓冲区资源无法释放
         */
        producer.close();
    }
}

从0.11开始KafkaProducer支持两种额外的模式：幂等模式、事务模式。

该模式增强了递送语义，将至少一次递送增强为精确的一次递送。注意：

1. 这种幂等性仅仅在单个会话内部保证
2. 客户端的retry不会引发记录的重复

要启用该模式，需要配置

enable.idempotence=true

幂等模式下，API的调用方式无变化。

该模式允许客户端原子的向多个分区、甚至多个主题发送数据。

要启用该模式，需要设置

transactional.id

为了保证端到端的事务性，消费者应该设置为仅仅读取已提交消息。

transactional.id的目的能够跨越单个生产者实例的多个会话进行事务恢复。此ID通常根据分片的、有状态的应用程序的分片标识符（Shard Identifier）产生。对于一个分片应用程序中的每个生产者实例来说，此ID必须唯一。

事务性的API是阻塞的，并且失败时会抛出异常，示例：

Properties props = new Properties();
props.put( "bootstrap.servers", "localhost:9092" );
// 每个生产者同时只能打开一个事务
props.put( "transactional.id", "my-transactional-id" );
Producer<String, String> producer = new KafkaProducer<>( props, new StringSerializer(), new StringSerializer() );
/**
 * 在事务模式下，必须首先调用下面的方法。此方法的行为如下：
 * 1、确保由先前实例发起的、相同ID的事务已经完成。如果先前实例在进行事务的过程中失败了，其事务在此被中止
 *    如果上一个事务正在提交，此方法会等待其完成
 * 2、获得内部的生产者id、epoch，并在所有事务性消息上使用
 */
producer.initTransactions();

try {
    // 只要启用了事务模式，任何记录都必须在事务中发送
    // 启动一个新事务
    producer.beginTransaction();
    for ( int i = 0; i < 10; i++ ) {
        String topic = "test";
        String key = "KEY-" + Integer.toString( i );
        String value = "VALUE-" + Integer.toString( i );
        // 不需要注册send的回调或者使用get()获得Future对象
        producer.send( new ProducerRecord<>( topic, key, value ) );
    }
    /**
     * 提交事务，此方法会首先刷出所有尚未发送的消息，然后再提交
     * 任何一次send()调用出现不可恢复的错误，该方法会再接收到错误后立即抛出异常，事务无法提交 
     * 为了事务能提交，所有send()必须按序的成功
     */
    producer.commitTransaction();
} catch ( ProducerFencedException | OutOfOrderSequenceException | AuthorizationException e ) {
    // 无法从这些异常中恢复
    producer.close();
} catch ( KafkaException e ) {
    // 对于其他类型的异常，可以中止然后重试
    // 中止后，所有已经成功的写操作会被标记为aborted
    producer.abortTransaction();
}
producer.close(); 

要使用此API，可以引入Maven依赖：

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
    <version>1.0.0</version>
</dependency>

使用该类能够从Kafka集群消费记录。此客户端：

1. 能够透明的处理代理实例的失败。也就是说，如果代理失败导致分区迁移到其他代理，不需要手工处理
2. 可以使用消费者组，与代理进行交互，让一组消费者进行负载均衡

与生产者不同，消费者不是线程安全的。

消费者需要维持到必要的代理的TCP连接，以抓取数据。不再使用消费者后，必须关闭它，否则这些连接会泄漏。

Kafka为分区中每个记录都维护一个数字的偏移量（Offset），这个偏移量是记录在分区中的唯一标识。

偏移量也用于标记消费者针对分区的当前消费位置（Position），例如消费者当前位置为5则意味着它已经消费过0-4记录并且下一个将被消费的记录是5。

对于消费者来说，“位置”有两层含义：

1. 下一个将要读取的记录的偏移量，比消费者消费的最后一个记录的偏移量大1。每当消费者poll(long)了新记录后此位置自动更新
2. 已提交位置（Committed Position），指已经被安全存储的偏移量值。消费者如果失败，重启后将根据此值进行恢复。该位置信息可以自动的定期提交。或者调用commitSync/commitAsync显式的提交

Kafka引入消费者组（Consumer Group）的概念，来允许一池子的消费者划分消费、处理记录的工作。这些消费者可以运行在同一台或者多台机器上允许。任何具有相同

group.id

通过subscribe接口，组中的每个消费者都可以动态的订阅主题。Kafka会把每个消息递送给组中的单个消费者，具体实现方式是，通过负载均衡，让主题的任一分区仅供单个消费者来消费，组中的消费者会被尽可能的分配相同个数的分区。

组中的成员是动态维护的，如果某个消费者宕掉，分配给它的分区会重新分配给组中其它成员。当新消费者加入后，既有消费者持有的分区会转移给它。此所谓再平衡（Rebalancing）。当发生再平衡时，消费者可以通过 ConsumerRebalanceListener得到通知，从而进行状态清理、手工位置提交等操作。

从概念上，你可以把组看做单个逻辑的消费者。这个逻辑消费者不会重复的消费某个消息。

当订阅1-N个主题后，消费者首次调用poll(long)时会加入到消费者组。poll的实现能够监测消费者是否失败。只要你继续调用poll，消费者就会保持组成员的身份，并且持续的接收消息。在底层，消费者会定期的发送心跳给代理，如果消费者失败且代理在session.timeout.ms内没有收到心跳，就革除消费者的组成员资格并触发再平衡。

某些情况下，消费者虽然没有崩溃，但是它却进入一种livelock的状态。也就是说，尽管消费者仍然在正常发送心跳，但是它已经不能进行任何消息处理了。为了检测这一情况Kafka引入了max.poll.interval.ms配置，如果消费者在此时间内没有发起过poll()调用，代理会主动革除其组成员资格并触发再平衡。如果这种革除操作发生后，消费者进行位置提交时会收到CommitFailedException。为了保持组成员资格，消费者必须不断的poll。

增大max.poll.interval.ms参数，消费者可以用更充足的时间来处理poll()得到的记录。这样做的缺点是，再平衡可能延迟，因为仅在poll()调用时，消费者才能参与到再平衡中。

配置max.poll.records参数可以限制单次poll()操作能够返回的记录数量。通过减小此参数，你就能相应的调低max.poll.interval.ms。

如果消息处理时间无法估算，你可能需要将处理消息的逻辑从poll()线程中转移出去，由独立的线程处理。这样做的话你需要小心的管理提交位置，因为只有前述的独立线程才知道何时消息处理完毕。通常情况下需要禁用自动的位置提交，由独立线程手工的进行提交。

如果消息抓取的快而处理的相对较慢，你可以考虑pause()目标分区，这样poll()操作就不会抓取新的记录。

使用自动偏移量提交，可以保证最少一次递送语义。前提是，你必须在后续调用（或者关闭消费者）之前，消费上一次poll()返回的全部数据。如果无法保证全部消费，自动提交的偏移量可能比实际成功消费的偏移量大，导致记录遗漏。

自动偏移量提交的消费者代码示例：

Properties props = new Properties();
props.put( "bootstrap.servers", "172.21.3.1:9092,172.21.3.2:9092,172.21.3.3:9092" );
props.put( "group.id", "group0" );
// 启用自动的位置提交
props.put( "enable.auto.commit", "true" );
// 自动提交的间隔
props.put( "auto.commit.interval.ms", "1000" );
props.put( "key.deserializer", "org.apache.kafka.common.serialization.StringDeserializer" );
props.put( "value.deserializer", "org.apache.kafka.common.serialization.StringDeserializer" );
KafkaConsumer<String, String> consumer = new KafkaConsumer<>( props );
// 可以同时订阅多个主题
consumer.subscribe( Arrays.asList( "test", "hello" ) );
while ( true ) {
    // poll并等待100ms
    ConsumerRecords<String, String> records = consumer.poll( 100 );
    for ( ConsumerRecord<String, String> record : records ) {
        String topic = record.topic();
        int partition = record.partition();
        long offset = record.offset();
        String key = record.key();
        String value = record.value();
        LOGGER.debug( "Record from {}/{}, offset: {}, Key: {}, Value: {}", topic, partition, offset, key, value );
    }
}

手工偏移量提交的消费者代码示例：

// ...
props.put( "enable.auto.commit", "false" );
// ...
final int minBatchSize = 200;
while ( true ) {
    ConsumerRecords<String, String> records = consumer.poll( 100 );
    buffer.add( records );
    if ( buffer.size() >= minBatchSize ) {
        // 在这里进行批量处理，例如持久化
        // 手工提交一次偏移量，这意味着之前收到的消息均被标记为已提交
        consumer.commitSync();
        buffer.clear();
    }
}

某些情况下，你可能希望对偏移量的提交进行细粒度的控制，例如按分区单独提交：

try {
    while ( running ) {
        ConsumerRecords<String, String> records = consumer.poll( Long.MAX_VALUE );
        // 按分区处理
        for ( TopicPartition partition : records.partitions() ) {
            // 获取当前分区的所有记录
            List<ConsumerRecord<String, String>> partitionRecords = records.records( partition );
            for ( ConsumerRecord<String, String> record : partitionRecords ) {
                // 消费
            }
            // 获取最后一个记录的偏移量
            long lastOffset = partitionRecords.get( partitionRecords.size() - 1 ).offset();
            // 提交当前分区的消费偏移量：必须指向下一个需要被消费的记录
            consumer.commitSync( Collections.singletonMap( partition, new OffsetAndMetadata( lastOffset + 1 ) ) );
        }
    }
} finally {
    consumer.close();
}

上面的两个例子中，分区由Kafka公平的分配给组中的消费者实例。某些情况下，你可能需要更细粒度、主动的控制，例如：

1. 消费者在本地存储了状态，这些状态和特定的分区相关。因此消费者仅应抓取目标分区的记录
2. 消费者本身具有HA特性，例如它被YARN之类的集群管理框架管理、属于Storm等流处理框架的一部分。这种情况下，不需要Kafka进行故障检测，因为消费者失败后会自动的重新启动

要手工分配分区，可以使用assign代替subscribe调用：

String topic = "test";
TopicPartition partition0 = new TopicPartition(topic, 0);
TopicPartition partition1 = new TopicPartition(topic, 1);
// 将分区0、1分配给消费者
consumer.assign(Arrays.asList(partition0, partition1));

执行上述分配后，你就可以进行poll。消费者的配置参数group.id仍然用于偏移量的提交。除非再次调用assign，分区和消费者的映射关系不会发生变化，因为手工分配模式下组协调器不生效，消费者失败不会导致再平衡。

尽管不同消费者实例可以共享组ID，但是它们是独立工作的。为了避免偏移量提交冲突，手工分配模式下，通常为每个消费者指定唯一性的组ID。

注意：自动分区分配（subscribe）和手工分区分配不能一起使用。 

尽管Kafka内置的消费偏移量的存储机制，但是你并不一定要使用它。

应用程序独立管理消费偏移量的情况很常见，记录处理结果往往需要和消费偏移量原子的写入到同一存储系统，提供更强的精确一次性语义。典型的例子：

1. 如果在RDBMS中存储消费后的结果，那么你可以在单个事务中同时提交消费偏移量和消费结果
2. 如果在本地存储消费后的结果，连带存储消费偏移量也能带来好处。假设你希望基于某个分区的数据构建一个索引，索引数据可以和偏移量一起存储。只要能保证索引写和偏移量写原子的进行，那么即使宕机导致数据没有同步到磁盘，后续仍然可以恢复而不丢失数据

每个记录都自带了偏移量信息，因此，要外部存储偏移量，你只需要：

1. 配置

   enable.auto.commit=false

2. 手工存储ConsumerRecord提供的偏移量
3. 消费者重启后，调用

   seek(TopicPartition, long)

   恢复上次消费位置

上述步骤配合手工分区分配，最为简单。

如果配合自动分区分配，则需要考虑可能的再平衡的影响。你需要调用 subscribe(Collection/Pattern, ConsumerRebalanceListener)并提供一个ConsumerRebalanceListener监听器：

1. 实现onPartitionsRevoked(Collection)方法，这样当分区从消费者处拿走时，当前消费者有机会存储偏移量
2. 实现onPartitionsAssigned(Collection)，这样当消费者被授予新分区时，当前消费者能够读取先前存储的偏移量并seek到适当的位置

ConsumerRebalanceListener还可以用于，在分区迁移时，刷出应用程序维护的和目标分区相关的任何缓存信息。

大部分情况下，消费者只是简单的从头开始消费，定期的提交消费偏移量。

Kafka也允许消费者任意的指定消费位置：

1. 消费者可以跳转到更小的偏移量，对历史数据进行重新消费。某些情况下消费者可能需要在重启后从头消费，已建立本地的缓存状态
2. 消费者可以跳转到更大的偏移量，跳过一部分未消费的数据。在时间敏感的记录处理程序中会这样跳转，当消费者处理速度赶不上时，可能直接跳过一部分记录

和跳转相关的消费者方法包括：

1. seek(TopicPartition, long)

   ，跳转到指定偏移量

2. seekToBeginning(Collection)

   ，跳转到最小的偏移量

3. seekToEnd(Collection)

   ，跳转到最大的偏移量

如果给消费者分配了多个分区，它默认会尝试同时读取所有分区中的可用数据，也就是分区的优先级是一样的。

某些情况下，可能需要优先读取某个分区的数据，仅仅在有空闲的时候才消费其它分区的数据。例如：

1. 在流处理程序中，你抓取两个主题的数据，并对两个流进行Join操作。如果其中一个流的消费进度远远拉下，则无法有效的Join。这时可能需要把消费快的那个流暂停下来
2. 同时需要抓取历史数据和实时数据时，可能需要优先抓取实时数据

调用

pause(Collection)

resume(Collection)

从0.10引入的事务支持，允许生产者原子的写入多个分区、主题的数据。为了配合事务性生产者，消费者必须配置

isolation.level=read_committed

启用读取已提交这一隔离级别后，消费者仅会读取已经成功提交的事务性消息。对于非事务性消息，读取方式和以前一致。

读取已提交模式下，客户端并没有缓冲机制。这种模式下消费者针对分区的读偏移量，是该分区中第一个属于进行中事务的记录的偏移量。此偏移量被称为最后稳定偏移量（Last Stable Offset，LSO）。一个进行中的事务可以影响多个分区甚至主题的LSO。

读取已提交模式下的消费者，会最多读取到LSO的前一个位置，并且会过滤掉所有Aborted的任何事务性消息。消费者调用seekToEnd(Collection)、endOffsets(Collection)的结果也会执行LSO。度量值抓取延迟（Fetch Lag）也相对于LSO计算。

包含了事务性消息的分区，会包含提交、中止（Abort）标记，用以说明事务的成功与否。这些标记体现为主题日志中的记录，并且这些记录不会返回给客户端。插入在日志中的标记会导致消费者看到消息偏移量之间出现空隙，不管是哪种隔离级别的消费者都会看到这种空隙。对于读取已提交的消费者，空隙还可能由于中止的事务导致。

KafkaConsumer是非线程安全的。所有的网络IO发生在调用线程中。多线程访问时的同步必须由调用者保证，未同步访问可能导致ConcurrentModificationException。

唯一不需要同步的例外是wakeup()调用。此调用通常在其它线程中发起，中断正在进行中的poll()操作以便关闭消费者：

public class KafkaConsumerRunner implements Runnable {
     private final AtomicBoolean closed = new AtomicBoolean(false);
     private final KafkaConsumer consumer;

     public void run() {
         try {
             consumer.subscribe(Arrays.asList("topic"));
             while (!closed.get()) {
                 ConsumerRecords records = consumer.poll(10000);
                 // 处理抓取到的记录
             }
         } catch (WakeupException e) {
             // poll()被中断会导致该异常
             if (!closed.get()) throw e;
         } finally {
             consumer.close();
         }
     }

     // 下面的方法可以被外部线程调用
     public void shutdown() {
         closed.set(true);
         // 中断正在进行中的poll()方法
         consumer.wakeup();
     }
 }

Kafka没有设计消费者的线程模型，开发者可以按需开发。

每个消费者独占一个线程的方式，其优势为：

1. 容易实现
2. 由于不需要跨线程的协调，往往是最快的方式
3. 按照分区保证消息处理顺序很容易实现，线程简单的根据获得消息的顺序消费它们

其缺点是：

1. 多个消费者之间，无法合并请求来批量发送给服务器处理，降低了吞吐能力
2. 线程的总数受限于分区的总数，因为每个消费者至少需要独占一个分区

为了避免上述线程模型的缺点，可以将消息的消费和处理进行解耦。由一个或者多个消费者线程抓取数据，并将数据ConsumerRecords存放到阻塞队列中。由一个处理线程池来处理队列中的记录。该方式的优势是：

1. 可以独立的对消费者、处理者线程进行扩容
2. 需要注意数据的处理顺序问题，由于线程调度的随机性，旧记录实际的处理时间可能在新记录的后面。如果不关注顺序性则不是问题
3. 手工的消费偏移量提交变得困难，需要协调多个线程，确认针对分区的消费已经完成

要使用Kafka Streams API，可以引入Maven依赖：

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-streams</artifactId>
    <version>1.0.0</version>
</dependency>

详细的讨论参考Streams API一章。 

很多场景下，你不需要直接使用Connect API，只需要使用内置的Connector就可以了。

详细的讨论参考Connect API一章。

要使用此API，可以引入Maven依赖：

<dependency>
    <groupId>org.apache.kafka</groupId>
    <artifactId>kafka-clients</artifactId>
    <version>1.0.0</version>
</dependency>

使用AdminClient.create()可以创建管理客户端的实例（KafkaAdminClient）。此管理客户端可以用于管理、查看主题、代理、配置、ACL。代理的版本必须在0.10.0以上。

参考Kafka Streams学习笔记

Kafka Connect是用于在Kafka和其它系统之间进行可扩容、可靠的流传输的工具。使用它你可以快速的定义将大量数据输入到Kafka或者从Kafka输出的“连接器”。

使用Kafka Connect可以读取整个数据库，收集来自所有应用程序的度量信息并存入Kafka主题，并让这些数据适合用于实时的流处理。 

使用Kafka Connect可以将主题数据导出到存储系统、查询系统或者批处理系统，便于离线分析。

本节给出一个简单的例子，说明如何配置、运行、管理单实例的Kafka Connect。

单实例模式下，所有工作都在单个进程（Worker）内部完成。单实例模式可能适用于日志文件收集这样的场景，但是不能利用Kafka Connect的容错特性。

启动单实例连接器的命令格式如下：

# 第一个参数：Worker的配置
# 后续参数：各连接器的配置
connect-standalone.sh config/connect-standalone.properties connector1.properties connector2.properties ...

分布式模式下，负载均衡被自动处理，允许随时按需扩容。多实例模式提供活动Task、配置信息、偏移量提交数据的容错：

# 不支持通过命令行提供连接器配置
connect-distributed.sh config/connect-distributed.properties

单实例和分布式模式会执行不同的Java类，这两个类会读取Worker配置并决定在何处存储配置信息、如何分配任务、在何处存储偏移量和任务状态

基础的通用配置项：

单实例Worker专有配置如下：

上面的Worker配置供Kafka Connect创建的生产者、消费者使用，以便访问配置、偏移量、状态主题。

对于Kafka Source和Sink任务，上述配置可以前缀consumer.和.producer，来针对任务进行配置。唯一从Worker继承来的配置项是 bootstrap.servers。

分布式模式下，Kafka Connect在Kafka主题中存储偏移量、配置和任务状态。你应当手工创建用于存放这些信息的主题，以便定制分区数量和复制因子。如果Kafka Connect启动时这些主题不存在，将以默认参数自动创建。

分布式Worker专有配置如下：

你可以指定多个连接器配置，但是这些连接器都是在Worker进程内使用不同的线程运行。

注意：分布式模式下，连接器配置不通过命令行参数指定。你需要通过REST API来创建、修改、销毁连接器。

连接器配置项也是键值对形式，具体包含的配置项取决于不同的连接器。公共的配置项包括：

Kafka Connect允许通过REST API来管理连接器。Web服务默认暴露在8083端口，目前支持的端点如下表：

通过配置，可以让连接器对消息进行修改或者叫转换，转换可以形成一个链条：

这里给出一个示例：内置的文件源连接器 + 添加静态字段的转换器。

本示例使用模式自由的JSON数据格式，因此需要修改Worker 配置文件：

key.converter.schemas.enable=false
value.converter.schemas.enable=false

在本示例中文件源连接器读取文件的每一行，将其包装为Map，然后添加一个字段用于识别数据来源。为完成这些逻辑，我们需要添加两个转换器：

1. HoistField：将输入纳入到一个Map中
2. InsertField：添加一个字段

修改后的连接器配置如下：

name=local-file-source
# 从文件读取数据（文件作为源），输出到Kafka主题
connector.class=FileStreamSource
tasks.max=1
# 连接器专有配置
file=test.txt
topic=connect-test
# 指定转换器列表
transforms=MakeMap, InsertSource
# 将输入消息转换为键line的值
transforms.MakeMap.type=org.apache.kafka.connect.transforms.HoistField$Value
# 转换器的配置项
transforms.MakeMap.field=line
# 添加一个静态键值
transforms.InsertSource.type=org.apache.kafka.connect.transforms.InsertField$Value
transforms.InsertSource.static.field=data_source
transforms.InsertSource.static.value=test-file-source

应用此连接器后，主题的记录形式如下：

{"line":"hello","data_source":"test-file-source"}
{"line":"world","data_source":"test-file-source"}

常用的内置转换器如下表：

!

?

开发连接器仅仅需要实现Connector、Task两个接口。

从文件读取记录的源连接器和任务：

package cc.gmem.study.kafka;

import org.apache.kafka.common.config.ConfigDef;
import org.apache.kafka.connect.connector.Task;
import org.apache.kafka.connect.source.SourceConnector;

import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

public class FileStreamSourceConnector extends SourceConnector {

    private String filename;

    private String topic;

    private final String FILE_CONFIG = "filename";

    private final String TOPIC_CONFIG = "topic";

    /**
     * 此连接器的任务实现类
     * 需要在Worker中实例化的，实际的从外部读取数据的任务的Java类
     */
    public Class<? extends Task> taskClass() {
        return FileStreamSourceTask.class;
    }

    /**
     * 生命周期回调，启动连接器
     * 该方法仅仅会在"干净"的连接器上面调用，所谓干净，要么是刚刚实例化、初始化的
     * 要么是已经被停止的
     *
     * @param props 传入的配置信息
     */
    public void start( Map<String, String> props ) {
        filename = props.get( FILE_CONFIG );
        topic = props.get( TOPIC_CONFIG );
    }

    /**
     * 声明周期回调，停止连接器
     */
    public void stop() {

    }

    /**
     * 产生最多max个任务的配置信息
     */
    @Override
    public List<Map<String, String>> taskConfigs( int max ) {
        List<Map<String, String>> configs = new ArrayList<>();
        // 仅仅支持单个任务
        Map<String, String> config = new HashMap<>();
        config.put( FILE_CONFIG, filename );
        config.put( TOPIC_CONFIG, topic );
        configs.add( config );
        return configs;
    }

    /**
     * 返回此连接器的版本
     */
    @Override
    public String version() {
        return null;
    }

    /**
     * 定义连接器的配置
     */
    @Override
    public ConfigDef config() {
        return null;
    }

}

package cc.gmem.study.kafka;

import org.apache.commons.io.IOUtils;
import org.apache.kafka.connect.data.Schema;
import org.apache.kafka.connect.source.SourceRecord;
import org.apache.kafka.connect.source.SourceTask;

import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.IOException;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;
import java.util.Map;

public class FileStreamSourceTask extends SourceTask {

    private String filename;

    private InputStream stream;

    private String topic;

    /**
     * 启动任务，在此处理任务配置，打开需要的资源
     * <p>
     * 实际应用时，还要考虑从Offset恢复的情况
     *
     * @param props 任务配置
     */
    @Override
    public void start( Map<String, String> props ) {
        filename = props.get( FileStreamSourceConnector.FILE_CONFIG );
        stream = openStream( filename );
        topic = props.get( FileStreamSourceConnector.TOPIC_CONFIG );
    }

    /**
     * Task被分配给专用的线程，此线程可能永久的阻塞，需要从Worker的其它线程调用stop方法才能停止
     */
    @Override
    public synchronized void stop() {
        IOUtils.closeQuietly( stream );
    }

    /**
     * 从外部系统拉取数据并构建源记录，如果没有可用的记录此方法应该阻塞
     *
     * @return 源记录的集合
     * @throws InterruptedException 当阻塞时被中断
     */
    @Override
    public List<SourceRecord> poll() throws InterruptedException {
        try {
            List<SourceRecord> records = new ArrayList<>();
            while ( records.isEmpty() ) {
                LineAndOffset line = readToNextLine( stream );
                if ( line != null ) {
                    records.add(
                            // 源记录，主要包含四个元素
                            new SourceRecord(
                                    // 源分区（相当于流的标识符），这里只有一个源分区，也就是唯一的输入文件
                                    Collections.singletonMap( "filename", filename ),
                                    // 源偏移量，这里即文件中的字节偏移量
                                    Collections.singletonMap( "position", streamOffset ),
                                    // 输出主题
                                    topic,
                                    // 输出值及其Schema。这里的Schema提示输出永远是一个字符串
                                    Schema.STRING_SCHEMA, line
                            )
                    );
                } else {
                    Thread.sleep( 1 );
                }
            }
            return records;
        } catch ( IOException e ) {
        }
        return null;
    }

    @Override
    public String version() {
        return null;
    }

    private InputStream openStream( String filename ) {
        try {
            return new FileInputStream( filename );
        } catch ( FileNotFoundException e ) {
            throw new RuntimeException( e.getCause() );
        }
    }
}

注意上面Task所释放出的源记录，每个记录都关联了流标识符（文件名）和偏移量信息。Connect框架会利用这些信息，进行周期性的偏移量提交。这样，一旦Task出现失败，可以基于偏移量进行恢复，尽可能减少重复处理、重复记录。

偏移量提交完全由框架负责，Kafka Connect暴露了接口供Task读取偏移量：

@Override
public void initialize( SourceTaskContext context ) {
    super.initialize( context );
    stream = new FileInputStream( filename );
    // 获取偏移量阅读器
    OffsetStorageReader offsetStorageReader = context.offsetStorageReader();
    // 读取指定分区的偏移量，偏移量是一个字典而不是简单的数值
    Map<String, Object> offset = offsetStorageReader.offset( Collections.singletonMap( "filename", filename ) );
    if ( offset != null ) {
        Long lastRecordedOffset = (Long) offset.get( "position" );
        if ( lastRecordedOffset != null )
            seekToOffset( stream, lastRecordedOffset );
    }
}

Sink连接器的接口和Source类似。但是SinkTask和SourceTask则不同，因为后者使用的是拉模式而前者是推模式：

public abstract class SinkTask implements Task {
    public void initialize(SinkTaskContext context) {
        this.context = context;
    }
    // 逻辑集中在此方法中，需要将SinkRecord进行转换，最终输出到外部系统
    // 此方法不一定需要保证数据完全写入到外部系统中，可以提前返回
    // SinkRecord包含的信息基本和SourceRecord一致
    public abstract void put(Collection<SinkRecord> records);
    // 在偏移量提交阶段调用下面的方法，此方法应该刷出未写入到外部系统的数据，并阻塞等待操作完成
    // currentOffsets可以用于实现精确一次性语义（和写入到外部系统的数据原子的一同写入）
    public void flush(Map<TopicPartition, OffsetAndMetadata> currentOffsets) {
    }
}

Kafka Connect的主要价值是用于定义大批量的数据拷贝Job，例如，Job通常用来拷贝整个数据库而非单张表。这种设计意味着连接器的输入/输出流（表、文件等等）会动态的变化。

在实现SourceConnector时，你应当考虑源系统中的变化，例如表的增加或删除。当检测到变化后应当调用ConnectorContext来通知框架：

if (inputsChanged())
    this.context.requestTaskReconfiguration();

在上述调用之后，框架会立即请求新的配置，并更新Tasks。在重新配置Task之前，框架允许Task优雅的完成提交操作。

某些情况下，和输入流更新有关的逻辑仅仅存在于Connector中。另外一些情况下，Task可能受到影响，需要适当的异常处理。例如，表的删除可能导致Task在拉取数据时出现错误，并且此错误可能在Connector检测到输入流的变化之前发生。 

SinkConnector通常仅需要处理新增的Kafka流，Kafka Connect使用正则式订阅来监控SinkConnector的输入主题集的变化，并通知SinkConnector。SinkTask可能需要接收新的流，并在外部系统创建资源。如果多个SinkTask接收同一流则可能出现尝试重复创建同一资源（例如同一张表）的情况，需要注意。

Kafka Connect支持在提交连接器之前，对提供的配置信息进行验证。要使用此功能，你需要实现config()方法：

private static final ConfigDef CONFIG_DEF = new ConfigDef()
    .define(FILE_CONFIG, Type.STRING, Importance.HIGH, "Source filename.")
    .define(TOPIC_CONFIG, Type.STRING, Importance.HIGH, "The topic to publish data to");
 
public ConfigDef config() {
    return CONFIG_DEF;
}

ConfigDef.define方法的重载版本允许你提供一个Validator，用于针对单配置项自定义验证规则。

此外，覆盖Connector.validate()方法可以提供配置验证逻辑。

要处理符合结构定义的数据，你需要使用Kafka Connect的Data API。大部分的结构化记录需要和Schema、Struct这两个类交互。这两个类都用于定义Schema：

Schema schema = SchemaBuilder.struct().name(NAME)
    .field("name", Schema.STRING_SCHEMA)
    .field("age", Schema.INT_SCHEMA)
    .field("admin", new SchemaBuilder.boolean().defaultValue(false).build())
    .build();
 
Struct struct = new Struct(schema)
    .put("name", "Barbara Liskov")
    .put("age", 75);

在开发SourceConnector时，你需要考虑何时生成Schema。如果Schema是静态的，可以静态块中生成。

但是很多连接器都需要面对动态Schema。例如数据库连接器，这种连接器可能需要处理多张表，就算处理单张表，表的结构也可能随着时间改变。你必须检测这些改变并且做出适当的处理。

Kafka使用properties风格的配置文件。在通过命令行启动Kafka时，你可以指定配置文件路径，或者使用配置项的命令行参数版本。

最基本的配置项包括：broker.id、log.dirs、zookeeper.connect。

# 支持ZooKeeper的chroot语法，在尾部添加 /kafka表示所有数据存放在此znode下
zookeeper.connect=zk:2181,zk-2:2181,zk-3:2181/kafka

主题可以从服务器默认值继承配置，并且可以覆盖。要指定主题专有配置，可以：

kafka-topics.sh --zookeeper localhost:2181 --create --topic my-topic --partitions 1 --replication-factor 
   # 使用下面的选项来覆盖配置
   --config max.message.bytes=64000
   --config flush.messages=1

在主题创建之后，你仍然可以修改配置：

kafka-configs.sh --zookeeper localhost:2181 --entity-type topics --entity-name my-topic
    # 修改配置
    --alter --add-config max.message.bytes=128000
    # 移除配置
    --alter --delete-config max.message.bytes

执行下面的命令，可以查看一个主题的配置覆盖情况：

kafka-configs.sh --zookeeper localhost:2181 --entity-type topics --entity-name my-topic --describe

重要配置项如下：

下表列出Java生产者可以使用的配置项：

从0.9.0.0版本开始，Kafka引入新的Java消费者实现，代替原先基于Scala的简单、高层实现。下表的配置可以用于新、老消费者实现：

推荐使用Java8的最新版本，例如LinkedIn就使用Java8 + G1回收器，JVM配置如下：

-Xmx6g -Xms6g -XX:MetaspaceSize=96m -XX:+UseG1GC
-XX:MaxGCPauseMillis=20 -XX:InitiatingHeapOccupancyPercent=35 -XX:G1HeapRegionSize=16M
-XX:MinMetaspaceFreeRatio=50 -XX:MaxMetaspaceFreeRatio=80

LinkedIn最繁忙的集群，由60个代理、5万个分区（复制因子2），输入消息数量80万每秒，输入流量300MB/s、输出流量1GB+ /s。 基于上述JVM配置，90%的GC停顿时间小于21ms，每秒Young GC次数小于1次。

LinkedIn使用24GB内存的4核Xeon机器。你需要为读写保留足够的缓冲内存空间。假设需要能够缓冲30s，则需要的大概内存是写吞吐量 * 30

LinkedIn使用8个7200RPM的SATA硬盘阵列，磁盘的吞吐能力很重要，因为这经常是瓶颈的所在。可以配备更多数量的磁盘以增强吞吐能力。如果配置更加频繁的Flush，则更高转速的磁盘会让你受益，当然价格也更贵。

Kafka可以很好的运行在所有类UNIX系统上，相比之下Windows平台下则有一些问题。

通常不需要进行很多OS级别的调优，主要考虑一下两个参数：

推荐使用多块磁盘，以增强吞吐能力。不建议和应用程序日志、其它OS文件系统活动共享磁盘，因为这会影响Kafka的处理延迟。

将多块磁盘RAID成单个卷，或者分别挂载为不同的目录，都是可以的。由于Kafka天然的容错性，RAID提供的冗余能力可能不需要，其提高单个逻辑磁盘的能力更有意义。

如果为Kafka配置多个数据目录，则分区会循环分配到这些目录，每个分区仅仅会存放在单个目录中。如果数据不是分区均衡的，则磁盘负载可能不均衡。

RAID在底层进行了负载均衡，因此可能（不一定）避免上述问题。RAID的劣势是它通常对写吞吐量有较大不利影响，并且减少了磁盘可用容量。

RAID另一个潜在的优势是，提高磁盘硬件容错。然而，重建RAID阵列非常IO敏感，几乎让服务器不可用，也就是说RAID不能提升可用性。

Kafka没有消息的内存缓冲池，它总是立即把数据写入到文件系统。由于OS页缓存（Pagecache）的存在，写入操作可能并没有持久化到硬盘中，具体写入时机，要么是应用程序显示调用fsync，要么是OS自行调度。在2.6.32以后的内核中，一系列pdflush线程负责在后台fsync。

你可以配置一个刷出策略，以便在一定时间后、累计一定消息数量后，fsync数据到磁盘。

需要注意：意外宕机不会导致数据丢失，因为通常主题的复制因子都大于1，缺少的数据可以从其它Replica上同步。因此Kafka的默认刷出策略是，应用程序不会触发fsync。fsync只会由OS或者Kafka后台线程完成。

启用应用程序级别的fsync，其缺点是：

1. 比较低效的磁盘使用模式，因为显式fsync让OS不能进行写重排序以优化性能
2. 大部分Linux文件系统中fsync是阻塞的操作

Kafka没有对文件系统有硬性依赖，但是XFS比起EXT4更加适合Kafka的负载。

1. 必须具有很高的吞吐能力，以支持高容量的事件系统，例如实时日志聚合
2. 必须具有优雅的后备排队（Backlog）机制，以便处理来自离线系统的、周期性的负载
3. 为了实现传统的消息递送语义，必须具有低延迟的特点
4. 必须支持分区和分布式，保证弹性和扩容能力
5. 必须具有容错能力，不会因为硬件故障导致数据丢失或者重复

以上目标，导致Kafka更像数据库日志，而非消息队列。

Kafka非常依赖于文件系统来存储、缓存消息。很多人觉得磁盘非常慢，无法提供足够的性能。实际上，磁盘可能运行的比想象的更快或更慢，这取决于你如何使用它。良好设计的磁盘数据结构可以让磁盘IO和网络IO一样快，某些特定情况下，磁盘顺序访问可以比内存随机访问更快。

关于磁盘性能的一个重要事实是，最近十年来磁盘的吞吐能力和磁盘寻道的延迟越来越负相关。六块7200RPM磁盘构成的RAID5，其顺序写可以高达600MB/s，但是随机写仅仅100KB/s，这是一个巨大的反差（6000倍）。在所有使用模式下，线性读写的速度都是最可预测的，并且被操作系统很大程度的优化。现代操作系统都提供了预读（Read-ahead）和后写（Write-behind）技术，支持大块的预抓取数据、分组多个小的逻辑写操作为单个物理写操作。

为了补偿随机磁盘IO的低性能，现代操作系统都激进的利用空闲内存，可能所有的空闲内存都被用作磁盘缓存。所有的磁盘读写操作都经由这个缓存层进行处理。除非使用Direct I/O，这种缓存层无法被跳过，因此即使应用程序在内部维护缓存机制，这些缓存很可能在OS的页缓存中被再次缓存。

对于JVM来说，需要注意以下事实：

1. 对象形式的数据，其空间占用很长大，常常比串行化格式大两倍。这意味着从存储效率方面来说，内存缓存是比较浪费的
2. 随着对空间的占用，垃圾回收器的行为越发复杂和缓慢

因此，使用文件系统进行缓存，依赖于OS的页缓存机制，要比自行在内存中维护缓存更加有效 —— 避免了潜在的重复缓存、避免了JVM中松散的空间结构。在32G内存的机器上，可以有效的缓存28-30G的数据，却可以避免GC带来的性能问题。

使用文件系统缓存的另外一个优势是重启后不需要预热，内存缓存在重启后是空白的，需要重新加载。

使用文件系统缓存，还免去了手工维护内存、磁盘数据的一致性。

当你的磁盘访问风格是顺序读，则操作系统的预读功能将大大的提高读效率。因为预读总是能命中你所需的数据。

Kafka的日志，不在内存中缓存，直接写入到磁盘日志中。

消息系统中的持久化数据结构常常是每个消费者一个队列，附带关联的BTree结构，此数据用于随机访问messages的元数据。BTree是消息系统中最广泛使用的数据结构，用于支持大量事务性、非事务性语义。

但是，BTree结构具有较高的成本。尽管BTree结构本身是对数复杂度（可以近似看做常量复杂度），但是应用到磁盘操作时并非如此。每次磁盘寻道操作大概需要10ms级别，每个磁盘同时仅仅支持单个寻道操作，因此并发度受限，少量的磁盘寻道请求就会导致非常高的Overhead。

存储系统需要混合非常快的页面缓存读写操作，以及非常慢的磁盘寻道操作，因此站在观察者的角度，BTree的性能随着数据量的增加而降低。数据量翻倍后性能降低的超过两倍。

如果以日志系统的风格来设计消息队列，也就是说仅仅支持Append方式的写操作，则所有读写操作都能实现常数的时间复杂度，同时读写操作不会相互阻塞。这种存储风格的一个明显优势是，性能和数据量完全解耦。服务器可以使用廉价、低转速磁盘的全部空间。

性能和数据量解耦后，可以实现在典型消息系统中难以看到的特性。例如，在Kafka中，消息不会在消费后立即被删除（以压缩空间，因为数据量和性能负相关），而是被保留一周甚至更久。这种特性让消费者的行为非常灵活，可以Replay历史数据，或者跳转到未来进行消费。

Kafka的一个主要目标是处理Web活动数据，这种数据的量是非常大的，一次页面访问可能产生数十条数据。为了保证数据的生产和消费都能流畅进行，Kafka必须非常高效。

关于磁盘的效率问题在前面讨论过了。消除磁盘性能问题后，系统中最常见的性能问题通常由于：

1. 过多的微小IO操作：C-S之间的IO和服务器内部的持久化都可能有这种问题。Kafka引入了消息集的概念，批量的发送消息，避免过多的网络请求带来Roundtrip开销。相应的，服务器把消息集整个的Append到日志，消费者也采取批量抓取的方式消费。Kafka的这种设计，让系统性能有了数量级的提升，因为批处理产生了更大的网络包、更大的顺序磁盘IO、更大的连续内存块
2. 过多的字节拷贝：低消息生产速率下不是问题，反之则影响重大。为了避免消息拷贝，Kafka设计了统一的二进制消息格式供生产者、代理、消费者使用，这样数据块就可以直接传输，不需要修改。代理维护的分区日志，本身仅仅是目录中的一系列文件，文件中的消息同样使用标准的二进制格式

通常情况下，将文件传输到套接字中的步骤是：

1. OS在内核空间，读取文件到页面缓存
2. 应用从内核空间读取页面缓存，拷贝到用户空间
3. 应用将用户空间中的文件回写到内核空间（套接字缓冲）
4. OS将套接字缓冲拷贝到网络接口（NIC）缓冲。然后网卡负责发送

很明显上述步骤较为低效，包含了4次拷贝2次系统调用。现代UNIX系统（Linux通过sendfile系统调用）对页面缓存到套接字的传输高度优化，统一消息格式因而受益。具体来说，免去了不必要的拷贝（Zero-copy），仅仅需要将页面缓存拷贝到NIC缓冲即可，不需要用户空间的参与。

Kafka主题通常有多组消费者，那么，日志一旦拷贝到页面缓存，就可以多次的Zero-copy并发送给消费者。这避免了反复拷贝数据到用户空间，记录的消费速率，仅仅受限于网络连接本身。

某些情况下，系统的瓶颈出现在网络带宽，而非磁盘或者CPU。当数据处理管线需要跨越数据中心进行消息收发时尤为如此。

用户可以自己实现压缩，但是客户端代码很难实现高效的压缩。Kafka采取批量压缩的方式，这样多个消息中反复出现的内容可以被有效的处理。

Kafka代理收到压缩消息后，直接存放到日志中，因此日志的磁盘结构也是紧凑的。除非消费者进行消费，消息不会解压缩。Kafka支持GZip、LZ4、Snappy等压缩协议。

生产者直接将消息发送给分区的Leader，Kafka没有引入中介的路由层。为了能让生产者知道向谁发送消息，所有节点都能应答元数据请求，给出服务器状态信息、分区Leader信息。

生产者负责决定将消息发送到哪个分区，可以随机发送、循环轮流发送，或者根据消息内容实现某种语义分区。要使用语义分区，生产者需要给记录一个适当的键，此键的哈希（默认逻辑，分区函数可以被覆盖）决定其被发送到哪个分区。例如，假设记录的键选用UserId，则用户的所有数据都被发送到单个分区。

批量处理是高效性的一个重大驱动力。Kafka生产者倾向于在内存中累计记录，并通过单个请求发送多个记录构成的批次。你可以配置累计记录时最多消耗的时间，或者累计数据的最大字节数。通过调整配置，你可以在更好吞吐量、更低延迟之间做权衡。

消费者通过向Leader分区发送抓取（Fetch）请求来工作。请求中会包含消费者的消费偏移量，代理依据此偏移量发送一批记录作为响应。消费者对偏移量具有很大的控制能力，只要不超过可用的区间，消费者能够倒回（Rewind）以消费历史数据，或者跳转到“未来”（在跟不上生产者的节奏时）进行消费。

消息应该由代理推送给客户端，还是由客户端主动去拉取？Kafka在这方面的设计和典型消息系统是一致的 —— 消息由生产者推送给代理，再由消费者从代理处拉取。

某些以日志为中心的系统，例如Apache Flume，把消息推送给消费者。推和拉各有其优缺点。

当推送消息给消费者时，代理很难针对消费者的特性进行处理，控制数据的推送速率，当生产者速度太快时，消费者很容易过载。拉模式下，消费者可以自由决定拉取速率，并通过某种后备（Backoff）机制缓和生产和消费速率不匹配的问题。拉模式还将将批量抓取的职责转移到消费者端，消费者更知道自己何时能消费大批量数据。

拉模式的缺点是，如果代理上没有可用的消息。消费者的轮询循环会反复进行，浪费CPU。Kafka的解决方式是使用长轮询，你可以配置一个等待时间，如果代理上没有消息可用，则客户端会在套接字上等待，而非立即结束请求。

对于消息系统来说，跟踪哪些消息已经被消费，是对性能有关键影响的地方。

传统消息系统一般都在代理端维护消息的元数据，通过元数据识别哪些消息已经被消费。当客户端抓取消息，或者Ack消息后，代理立即删除此消息。之所有要尽快的删除，是因为传统消息系统的数据结构的扩容性往往较差，倾向于尽可能让此结构更小。

识别消息是否真正被成功消费，并不简单。如果消息被抓取后立即删除，消费者可能在处理消息之前就宕掉。为解决此问题，消息系统通常引入Ack机制。这又引入新的问题，消费者可能在处理消息之后，Ack之前宕掉，并引发重复的消息处理。分布式事务机制可能解决此问题，但是性能很差。

Kafka跟踪消息进度的方式完全不同，它将主题分为若干个消息有序的分区，并引入消费偏移量，标记消费者当前的位置。对于每个消费者和分区的组合，仅仅需要一个整数就可以完成状态记录。

消费偏移量的引入，还让消息没必要立即删除，实际上，只要磁盘空间充足，你可能配置让Kafka在一周或更久后才删除数据。

由于Kafka不会立即删除数据，且数据量的多少和性能无关，因此，那种周期性运行，消费大量数据并存放到离线系统（Hadoop、RDBMS数据仓库）的消费者，可以和Kafka协同工作。

对于Hadoop来说，为每个节点/主题/分区的组合创建一个Map任务，可以很好的实现加载并行化。利用Hadoop提供的任务管理能力，失败的任务可以自动重启而不需要担心数据重复，重启的任务自动从原始的位置开始读取。 

Kafka的bin目录包含很多脚本，可以用于完成日常的管理工作。

主题可以在第一次被使用时自动创建，你可能需要对默认配置进行定制，以便控制默认窗口过程。

要手工添加主题，参考如下命令：

kafka-topics.sh --zookeeper zk_host:port/chroot --create --topic topic_name
      --partitions 20 --replication-factor 3 --config x=y

分区日志存放在Kafka的log目录，每个分区都有自己的目录，目录命名规则为topicname-partitionid。

仍然使用上面的脚本，例如修改分区数可以：

kafka-topics.sh --zookeeper zk_host:port/chroot --alter --topic topic_name
      --partitions 40

注意：

1. 分区可能具有应用语义，添加分区不会自动修改已有分区的数据分布
2. 当前不支持减少分区数量

要添加、删除主题的配置项，参考：

kafka-configs.sh --zookeeper zk_host:port/chroot --entity-type topics --entity-name topic_name 
    --alter --add-config x=y
kafka-configs.sh --zookeeper zk_host:port/chroot --entity-type topics --entity-name topic_name 
    --alter --delete-config x

kafka-topics.sh --zookeeper zk_host:port/chroot --delete --topic topic_name

Kafka集群会自动检测到宕机、有意被关闭（维护目的）的代理，并在必要时为分区选举新的Leader。

对于有意关闭的情况，你可以优雅的停止代理而不是强行关机。优雅关闭的好处是：

1. 会自动同步所有日志到磁盘中，避免在重启时进行日志恢复。日志恢复对日志尾部的所有记录进行校验和操作，需要一定时间才能完成
2. 对于待关闭机器是Leader的分区，执行迁移，将Leader身份迁移给其它代理。这种Leader迁移更快、Leader迁移导致的分区不可用时间仅仅在ms级别

优雅关闭时，上述第1条自动发生。要启用第2条，需要配置：

controlled.shutdown.enable=true

代理宕机后，其Leader身份全部被移除。这意味着，代理重启后，它不是任何分区的Leader，因而不会接受任何客户端的读写请求，其计算能力被浪费。

为了避免这种不平衡，Kafka引入优选Replica的概念。如果某个分区的复制集为1,5,9则1是优选节点，因为它在列表的最前面。要在Replica 1宕机重启后，自动恢复其Leader身份，可以执行：

kafka-preferred-replica-election.sh --zookeeper zk_host:port/chroot

要自动在需要的时候执行上述命令，可以配置：

auto.leader.rebalance.enable=true

从0.10开始Kafka支持机柜感知（Rack awareness），允许将分区的不同Replica分布到不同的Rack中，防止机柜整体断电断网导致Kafka分区完全不可用，Rack可以在地理上远程分布。 

要指定代理所属的机柜，配置broker.rack属性即可。

当创建、修改主题，或者再平衡Replica时，Kafka会尽可能的把分区的每个Replica分散到不同的Rack中。

此脚本提供了一种跨越数据中心进行复制的手段。数据会从源集群中读取，并写到目标集群的同名主题中。实际上此镜像工具就是挂钩在一起的消费者-生产者组合。

为了增强吞吐量和容错能力，你可以运行此脚本的任意数量的实例。当某个实例意外宕掉后，其它实例会接管它的负载。

镜像不能作为完全有效的容错措施，因为源、目标集群是完全独立的，它们的偏移量取值是不一样的。

镜像单个主题的示例：

kafka-mirror-maker.sh
      --consumer.config consumer.properties
      --producer.config producer.properties 
      --whitelist topic-name    # 白名单，仅仅复制这些主题，可以使用正则式

某些部署场景中，需要跨越数据中心复制数据。

Kafka推荐的方式是，在数据中心内部创建集群，应用程序仅仅和当前数据中心的Kafka集群交互。对于跨数据中心的数据复制，利用跨集群镜像实现。

这种部署模式的好处时，让数据中心之间解耦，使它们作为独立的实体运作。同时，跨数据中心的数据复制可以被集中管理。当数据中心之间的链路断开后，各中心可以独立运作，落后的数据复制进度可以在链路恢复后赶上。

如果某个应用需要全数据集的视图，使用跨集群镜像机制来聚合所有数据中心的主题，形成一个新数据中心，那些需要全数据集视图的应用，和新数据中心交互。

除了上述推荐方式以外，你也可以让应用通过WAN访问其它数据中心，但是很明显这会引入访问延迟。

不过，即便在高延迟网络环境下，Kafka天然支持的生产者/消费者批处理能力依然能让应用拥有较高吞吐量。不过你可能需要为代理、生产者、消费者调整socket.send.buffer.bytes、socket.receive.buffer.bytes等参数。

通常情况下，不要创建跨越数据中心的Kafka集群。特别是链路延迟较大的情况下。这会让ZooKeeper、Kafka的复制延迟都很大，此外，如果链路中断，则部分数据中心的Kafka、ZooKeeper会不可用。

要列出集群中的消费者组，执行：

kafka-consumer-groups.sh --bootstrap-server localhost:9092 --list

如果你使用老的High-Level消费者并且在ZooKeeper中存储组元数据（offsets.storage=zookeeper），则传递--zookeeper而非--bootstrap-server。

你可以检查某个消费者组中，每个分区的消费偏移量：

kafka-consumer-groups.sh --bootstrap-server localhost:9092 --describe --group groupname
# 还可以使用如下形式（仅仅显示基于ZooKeeper的消费者，不显示使用Java Consumer API的消费者
kafka-consumer-groups.sh --zookeeper localhost:2181 --describe --group groupname
# 输出示例
# TOPIC PARTITION CURRENT-OFFSET LOG-END-OFFSET LAG CONSUMER-ID 
# 主题   分区号     消费偏移量      日志偏移量       延迟  消费者

要添加新服务器到Kafka集群，你只需要为它分配唯一性的代理ID即可。但是新的代理不会自动被分配数据分区，因此默认情况下除非创建了新的主题，新加入的代理不会有任何作用。

在添加新服务器的同时，你常常会执行迁移，将已有的分区迁移到新服务器中。迁移过程需要手工触发，之后可以自动完成。迁移触发后，Kafka将新服务器作为待迁移分区的Follower节点，当完成数据复制，新服务器成为In-sync节点后，复制集中某个旧节点的数据被清除，成员身份也被解除。

Kafka提供了分区重分配工具，允许你跨越代理移动分区。理想的分区分布，能让所有代理节点具有均匀的数据负载、均匀的数据尺寸。Kafka没有提供自动识别“不均匀”的工具，因而管理员需要手工识别出哪些分区需要移动。

分区重分配工具可以在三个互斥的模式下运行：

1. --generate，给出主题、代理的列表，生成一个候选重分配方案，将列出的主题的所有分区移动到代理中
2. --execute，执行用户给出的重分配方案，方案通过 --reassignment-json-file参数给出
3. --verify，显示上次重分配的执行情况，状态可以是成功、失败、进行中

在添加了新的服务器（扩容Kafka集群）之后，使用分区重分配工具，可以将一部分主题迁移到新添加的代理上，迁移整个主题，要比每次迁移一个分区更加容易。

要执行整个主题的迁移，用户需要指定被迁移的主题、接收主题的代理。迁移后，主题的复制因子保持不变，主题的分区被尽可能均匀的分布到目标代理中。

具体步骤如下：

1. 以JSON格式提供待迁移主题的列表：
   

   {
       // 待迁移主题
       "topics": [{"topic": "foo1"}, {"topic": "foo2"}],
       "version":1
   }

2. 使用分区重分配工具，生成一个候选的重分配置文件：
   

   kafka-reassign-partitions.sh --zookeeper localhost:2181 
       --topics-to-move-json-file topics-to-move.json   # 待迁移主题列表文件
       --broker-list "5,6"                              # 目标代理列表（标识符）
       --generate
   # 输出的前一部分是当前重分配置文件（略）
   # 输出的后一部分是新的重分配置文件，示例：
   # {
   # "version":1,
   #                 # 主题         # 分区编号     # 复制集
   # "partitions":[{"topic":"foo1","partition":2,"replicas":[5,6]},
   #               {"topic":"foo1","partition":0,"replicas":[5,6]},
   #               {"topic":"foo2","partition":2,"replicas":[5,6]},
   #               {"topic":"foo2","partition":0,"replicas":[5,6]},
   #               {"topic":"foo1","partition":1,"replicas":[5,6]},
   #               {"topic":"foo2","partition":1,"replicas":[5,6]}]
   # }

3. 此时重分配尚未发生，你需要备份当前分配置文件，以便回滚。然后将重分配候选保存到JSON文件中，执行：
   

   kafka-reassign-partitions.sh --zookeeper localhost:2181 
       # 重分配配置文件
       --reassignment-json-file expand-cluster-reassignment.json --execute

4. 上述命令会异步执行，你可以随时检查进度：
   

   kafka-reassign-partitions.sh --zookeeper localhost:2181 
       --reassignment-json-file expand-cluster-reassignment.json --verify
   
   # Reassignment of partition [foo1,0] completed successfully
   # Reassignment of partition [foo1,1] is in progress 

除了上节那种自动分配、迁移整个主题的用法之外，分区重分配工具还允许你手工指定迁移特定的分区。如果你明白集群的负载分配情况，并且自动生成的重分配候选不能满足需要，可以进行使用这种定制迁移。

在准备好重分配置文件后，执行上节第3步即可。

增加某个分区的复制因子很简单，只需要在定制的重分配置文件中，为某个分区的replicas列表添加一个代理ID就可以了：

// 为foo的分区0添加一个复制因子，新的副本存放在代理7上
{ "version":1, "partitions": [{"topic":"foo","partition":0,"replicas":[5,6,7]}] }

Kafka支持设置迁移所消耗的带宽的上限，避免集群再平衡、添加/移除代理时Replica在机器之间移动消耗过多的带宽，影响系统性能。

限制带宽的方式有两种：

1. kafka-reassign-partitions.sh --execute —throttle 50000000  # 单位 Bytes/s 

   注意：

   1. 你可以在迁移过程中重新调用上述脚本并指定不同的带宽限制
   2. 在迁移完成后，你必须调用--verify来解除带宽限制，否则，正常的数据复制会一直被限流
2. 调用脚本

   kafka-configs.sh

   来验证相关配置。和限流有关的配置有两对：
   leader.replication.throttled.rate、follower.replication.throttled.rate   限流速率
   leader.replication.throttled.replicas、follower.replication.throttled.replicas 受到限制的Replica

当前Kafka没有提供直接可用的集群缩容工具。这意味着，你需要使用分区重分配工具，将准备移除的代理上所有的分区全部迁移走。

Kafka支持在user,client-id、user、client-id级别进行配额，限制用户对集群资源的占用。默认情况下，资源占用不受限制。

要为用户user1、客户端clientA进行配额，可以：

kafka-configs.sh --zookeeper localhost:2181 --alter
    # 配额        生产速率                  消费速率                 
    --add-config 'producer_byte_rate=1024,consumer_byte_rate=2048,request_percentage=200' 
    # 要仅对用户、客户端进行配额，则指定两项之一
    --entity-type users --entity-name user1 
    --entity-type clients --entity-name clientA

要查看用户user1、客户端clientA的当前配额，可以：

kafka-configs.sh  --zookeeper localhost:2181 --describe --entity-type clients --entity-name clientA

你可以在代理级别上设置默认的配额，对所有客户端生效：

# 仅仅当没有在ZooKeeper中覆盖时生效
quota.producer.default=10485760
quota.consumer.default=10485760  

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

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

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

ZooKeeper是Hadoop的子项目，实现高可靠的分布式协调服务。它可以提供分布式的配置、同步、命名、集群服务。ZooKeeper暴露了一系列简单的接口，具有Java、C语言绑定。

为了正确构建复杂的服务，ZooKeeper提供以下保证：

1. 顺序一致性：来自客户端的更新，按照它们被发送的顺序应用
2. 原子性：更新要么成功要么失败
3. 单一系统镜像：不管客户端连接到哪个ZooKeeper实例，它都看到服务的一致性视图
4. 可靠性：一旦更新被写入，即是永久的
5. Timeliness：客户端看到的系统视图确保在一定时间范围内更新到最新状态

ZooKeeper由以下组件构成：

1. 服务器：运行在ZooKeeper ensemble节点上的Java服务器
2. 客户端：一个Java类库，用于链接到ZooKeeper集群
3. Native客户端：基于C实现的客户端
4. 其它可选组件

Native客户端和可选组件仅仅支持Linux。

除了Request Processor之外，所有ZooKeeper实例持有一模一样的组件：

1. replicated database，一个内存数据库，包含整个名字空间。对此数据库的更新被刷入磁盘，以便重启后恢复
2. 每个ZooKeeper实例都可以接受客户端请求，读请求基于本地的数据库处理，更新服务状态的写请求基于 agreement protocol处理。此协议：
   1. 将一个实例作为leader，其它实例作为followers
   2. follower从leader接收消息提议，并同意消息递送
   3. 消息层负责leader的故障转移、follower与leader的同步
3. ZooKeeper使用一个定制化的原子消息协议，保证消息层是原子性的。这种原子性保证了本地数据库不会出现数据不一致性 

ZooKeeper很简单，它允许分布式进程通过一个共享的、有层次的名字空间来相互交互。这个名字空间的组织就像文件系统一样，名字空间由数据寄存器（data registers） —— 所谓znodes组成，类似于文件系统的目录/文件，ZooKeeper的数据是驻留内存的，而不是像文件系统那样写在磁盘上。

就像被它管理的分布式进程，ZooKeeper本身也倾向于跨越一组宿主机（所谓ensemble）复制，整体上形成一个ZooKeeper服务。只要大部分节点可用，则ZooKeeper服务可用。

客户端连接到单个ZooKeeper节点，通过一个TCP连接来：

1. 发送请求
2. 获得响应
3. 获得监听的事件
4. 发送心跳

如果此TCP连接丢失，客户端可能连接到另外一个节点。

ZooKeeper使用数字标注每个update，以反应所有ZooKeeper事务的顺序。后续操作可以使用此数字序号实现高层次的抽象，例如同步原语。

ZooKeeper非常高速，特别是在读为主的应用场景下。在上千台机器上运行的ZooKeeper应用，其性能在读写比10:1左右最好。

ZooKeeper提供的名字空间非常类似于Linux目录树，由一系列以 / 分隔的路径元素组成，名字空间中的每个节点以完整路径唯一识别。

ZooKeeper使用多种方式来追踪时间：

1. Zxid：即ZooKeeper事务ID。每次对ZooKeeper的状态做出修改，都对应一个这样的ID。这个ID是单调递增的
2. 版本号：对节点的修改会导致其某个版本号字段变更
3. 时间单元（Ticks）：在集群中，ZooKeeper使用时间单元来界定状态上传、会话过期、Peer连接过期的最小时间间隔
4. 真实时间：节点的创建、修改时间使用真实时间记录

客户端利用C/Java语言绑定库建立会话：

1. 客户端发起调用时，可以指定连接字符串、会话超时、默认Watcher等参数，连接字符串包括逗号分隔的多个ZooKeeper实例的host:port列表
2. 客户端创建一个到ZooKeeper服务集群的句柄（Handle），句柄被创建后，进入CONNECTING状态。这时，ZooKeeper会：
   1. 创建一个代表会话ID的64位整数并分配给客户端
   2. 同时，发送一个会话密码给客户端，客户端重连时需要用到此密码
   3. 根据客户端请求的会话超时ms，确定一个允许的（受限于时间单元，必须在2-20倍之间）会话超时
3. 绑定库尝试建立到某个ZooKeeper实例的TCP连接。连接建立后，句柄进入CONNECTED状态
4. 如果出现不可恢复的错误，包括会话过期、身份验证失败、客户端显式的关闭句柄，则句柄进入CLOSED状态
5. 如果客户端发现连接意外断开，则尝试连接列表中下一个实例，直到重新连接上。客户端重新连接时，会在握手时携带自己的会话ID、密码
6. 客户端重新连接上之后，可能发现会话已经过期
7. 默认Watcher可以在会话状态发生变化（例如连接断开、会话过期）后，通知客户端

从3.2开始，连接字符串可以有一个chroot后缀，例如

127.0.0.1:3000,127.0.0.1:3001,127.0.0.1:3002/pems/webmgr

客户端通过发送PING心跳来保活，这样双方都可以知道连接是否断开。

客户端可以变更连接字符串，也就是变更服务器列表。此变更可能触发一个负载均衡算法，并导致客户端重连到其它服务器。

名字空间的每个节点被称为znode，类似于文件系统的目录。znode有以下特点：

1. 路径是znode的唯一标识
2. znode可以具有关联的数据，还可以具有子节点
3. znode关联的数据通常很小，一般最大KB级别
4. znode具有一个状态结构（Stat Structure），存放版本号、数据长度、修改时间戳等信息
5. znode的数据发生变化，版本号就递增
6. znode同时保存数据的多个版本
7. 读写znode数据的操作都是原子性的，写操作替换掉数据
8. 每个节点包含一个访问控制列表（ACL）用于限制谁能做什么
9. znode可以被监控（watch），一旦数据修改、子节点变化，即可通常关注此znode的客户端。这是ZooKeeper的核心特性

所谓临时（EPHEMERAL）节点，仅仅在创建它的Session存在期间存在。ZooKeeper的客户端Session基于TCP长连接，通过心跳来保活。

当创建一个znode时，你可以要求ZooKeeper在路径尾部自动附加单调递增的计数器。对于父节点来说，此计数器具有唯一性。计数器十位左侧补零，示例：

<path>0000000001

计数器的下一个值，存储在父节点中。如果计数超过2147483647 会出现溢出。

3.6版本新增。这类节点的所有子节点都消失后，可能在未来的某个时间点被自动删除。

ZooKeeper支持监控（Watch）的概念——一次性的事件监听器。它有三个要点：

1. 一次性的：当被监控数据发生变化后，事件发送且仅一次。例如

   getData("/znode1", true)

   导致当znode1的关联数据发生变化后客户端得到通知，但是后续znode1的数据再发生变化则不会自动得到通知
2. 发送给客户端：事件被异步的发送给客户端，并且ZooKeeper提供顺序性保证，客户端不可能在收到通知之前就看到目标数据的变化
3. 监控什么数据：getData/exists针对关联数据进行监控，getChildren()则针对子节点进行监控

ZooKeeper中所有的读操作，包括

getData()

getChildren()

exists()

Watch仅仅在客户端所连接到的服务器上维护，但如果客户端发生重连，则新服务器负责维护客户端之前注册的Watch。有一种情况下，Watch会遗漏监控：

1. 客户端设置了exists监控，然后客户端断开
2. 被监控节点创建，然后又被删除
3. 客户端重连，此时它不会收到Watch

客户端可以调用removeWatches来移除监控。

ZooKeeper对Watch提供以下保证：

1. 先发生的事件，其Watcher先被通知
2. 针对同一事件先注册的Watcher先被通知
3. 先得到Watch通知，然后才能看到目标znode数据的变化

使用Watch时需要注意：

1. 一次性，如果需要获得后续变更通知，需要再次注册Watcher
2. 由于再次注册会有网络延迟，这期间目标znode可能已经发生了多次变化，这些变化是捕获不到的
3. 在连接断开期间，接收不到通知

ZooKeeper支持基于ACL对znode进行访问控制。其实现有些类似UNIX文件模式，不同的是，ZooKeeper没有user/group/world这三种角色，它允许定义无限数量的角色（ID），并为这些角色授权。此外ACL不是递归的，也就是子节点不会继承父节点的授权设置。

ZooKeeper支持可拔插的身份验证方案（scheme）。ID的形式则为

scheme:id

当客户端登录ZooKeeper并对自己进行身份验证时，ZooKeeper将所有对应此客户端的ID都分配给它。当客户端访问znode时，这些ID用来进行ACL验证。

ACL中每个条目的格式为

(scheme:expression, perms)

(ip:172.21.0.0/16, READ)

首先保证1.7或者更高版本的JDK已经安装，然后到稳定频道下载二进制压缩包，解压到合适的目录中。

要启动ZooKeeper服务，需要创建一个配置文件conf/zoo.cfg：

# 基本的时间单元对应的毫秒数，心跳每个时间单元发送一次，会话过期最小时间2时间单元
tickTime=2000
# 内存数据库的快照存放目录
dataDir=/data
# 监听客户端连接的端口
clientPort=2181

独立运行的ZooKeeper可以用户开发、测试目的。在产品环境下，你需要在复制（Replication）模式下运行ZooKeeper。一组复制的ZookKeeper称为Quorum，它们必须共享一致的配置文件：

tickTime=2000
dataDir=/var/lib/zookeeper
clientPort=2181
# 连接到Leader超时时间单元
initLimit=5
# Follower最多落后Leader多少时间单元
syncLimit=2
quorumListenOnAllIPs=true
# 服务器列表，server.X中的X是实例ID，在运行时，每个实例检查自己数据目录下的myid文件，其中以ASCII写着自己的ID
# 前一个端口供Follower连接到Leader使用；后一个端口用于选举Leader
server.1=172.21.0.1:2888:3888
server.2=172.21.0.2:2888:3888
server.3=172.21.0.3:2888:3888

每个Quorum最少应该包含3个ZooKeeper实例，并且应当配置奇数个数的实例。

官方镜像的配置文件路径为/conf/zoo.cfg，下面的命令创建容器：

# ZOO_MY_ID 用于设置myid文件，此镜像假设数据目录是/data
docker run -e "ZOO_MY_ID=2" --name zookeeper-2 --network local --ip 172.21.0.2 -d docker.gmem.cc/zookeeper
docker run -e "ZOO_MY_ID=3" --name zookeeper-3 --network local --ip 172.21.0.3 -d docker.gmem.cc/zookeeper

环境变量

ZOO_LOG_DIR

环境变量

ZOO_LOG4J_PROP

ERROR,ROLLINGFILE

# 在后台启动ZooKeeper服务
zkServer.sh start
# 在前台启动ZooKeeper服务
zkServer.sh start-foreground
# 停止ZooKeeper服务
zkServer.sh stop

# 启动CLI客户端
zkCli -server 127.0.0.1:2181

ZooKeeper具有非常简单的编程接口，它仅仅提供以下操作：

<dependency>
    <groupId>org.apache.zookeeper</groupId>
    <artifactId>zookeeper</artifactId>
    <version>3.4.10</version>
</dependency>

使用模式EPHEMERAL可以创建有序节点，反复针对同一路径创建有序节点，会自动后缀单调递增的编号。

ArrayList<ACL> acl = ZooDefs.Ids.OPEN_ACL_UNSAFE;
byte[] data = { 0 };
// 临时节点不支持子节点
try {
    // 同步创建
    zk.create( "/tmp", data, acl, CreateMode.PERSISTENT );
} catch ( KeeperException e ) {
    if ( e.code() != KeeperException.Code.NODEEXISTS ) throw e;
}
// 异步创建
zk.create( "/tmp/no", data, acl, CreateMode.EPHEMERAL_SEQUENTIAL, ( rc, path, ctx, name ) -> {
    // rc: OK path: /tmp/no, name: /tmp/no0000000000
    // rc: OK path: /tmp/no, name: /tmp/no0000000001
    // rc: OK path: /tmp/no, name: /tmp/no0000000002
    LOGGER.debug( "rc: {} path: {}, name: {}", new Object[]{ KeeperException.Code.get( rc ), path, name } );
}, this );
TimeUnit.SECONDS.sleep( 1 );

这个例子中，我们使用一个Agent来：

1. 管理到ZooKeeper的连接，一旦会话过期即重连
2. 转发ZooKeeper发来的事件通知给客户端
3. 对事件机制进行简单封装，实现了：
   1. 隔离客户端和ZooKeeper
   2. 会话过期后，自动重新注册Watch

Agent代码：

package cc.gmem.study;

import org.apache.zookeeper.WatchedEvent;
import org.apache.zookeeper.Watcher;
import org.apache.zookeeper.ZooKeeper;
import org.apache.zookeeper.data.Stat;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.io.IOException;
import java.util.*;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentLinkedDeque;
import java.util.concurrent.ConcurrentLinkedQueue;
import java.util.function.Consumer;

public class ZooKeeperAgent implements Watcher {

    private static final Logger LOGGER = LoggerFactory.getLogger( ZooKeeperAgent.class );


    private ZooKeeper zk;

    private String connectString;

    private int timeout;

    private Map<Event.EventType, Map<String, Queue<Consumer<EventResolver>>>> allListeners;

    // 对WatchedEvent进行简单包装，支持获取znode数据，对客户端屏蔽ZooKeeper
    public class EventResolver {

        private WatchedEvent event;

        public EventResolver( WatchedEvent event ) {
            this.event = event;
        }

        public WatchedEvent getEvent() {
            return event;
        }

        public byte[] getData() {

            return getData( null );
        }

        public byte[] getData( Stat stat ) {
            if ( stat == null ) {
                stat = new Stat();
            }
            try {
                return zk.getData( event.getPath(), false, stat );
            } catch ( Exception e ) {
                throw new RuntimeException( e.getMessage(), e );
            }
        }
    }

    public ZooKeeperAgent( String connectString, int timeout ) {
        this.connectString = connectString;
        this.timeout = timeout;
        allListeners = new ConcurrentHashMap<>();
        allListeners.put( Event.EventType.NodeCreated, new ConcurrentHashMap<>() );
        allListeners.put( Event.EventType.NodeDataChanged, new ConcurrentHashMap<>() );
        allListeners.put( Event.EventType.NodeDeleted, new ConcurrentHashMap<>() );
        allListeners.put( Event.EventType.NodeChildrenChanged, new ConcurrentHashMap<>() );
        allListeners = Collections.unmodifiableMap( allListeners );
        createZooKeeper();
    }

    public void on( Event.EventType eventType, String path, Consumer<EventResolver> listener ) {
        Map<String, Queue<Consumer<EventResolver>>> listenersOfType = this.allListeners.get( eventType );
        Queue<Consumer<EventResolver>> listeners;
        synchronized ( this ) {
            listeners = listenersOfType.get( path );
            if ( listeners == null ) {
                listeners = new ConcurrentLinkedQueue<>();
                listenersOfType.put( path, listeners );
            }
        }
        listeners.add( listener );
        watch( eventType, path );
    }

    private void watch( Event.EventType eventType, String path ) {
        try {
            switch ( eventType ) {
                case NodeCreated:
                    // 这里可以传递一个Watcher类型，也可以传入boolean
                    // 如果为true，使用构造ZooKeeper时提供的Watcher ———— 所谓defaultWatcher
                    zk.exists( path, this );
                    break;
                case NodeDataChanged:
                    Stat stat = new Stat();
                    zk.getData( path, this, stat );
                    break;
                case NodeDeleted:
                    zk.exists( path, this );
                    break;
                case NodeChildrenChanged:
                    zk.getChildren( path, this );
                    break;
            }
        } catch ( Exception e ) {
            LOGGER.error( e.getMessage(), e );
        }
    }

    private void createZooKeeper() {
        try {
            zk = new ZooKeeper( connectString, timeout, this );
            // 新会话，Watch需要重新注册
            allListeners.entrySet().stream().flatMap( entry -> {
                Event.EventType eventType = entry.getKey();
                return entry.getValue().keySet().stream().map( path -> {
                    return new Object[]{ eventType, path };
                } );
            } ).forEach( args -> watch( (Event.EventType) args[0], (String) args[1] ) );
        } catch ( IOException e ) {
            throw new RuntimeException( e.getMessage(), e );
        }
    }

    public void process( WatchedEvent event ) {
        switch ( event.getType() ) {
            case None:
                onKeeperStateEvent( event );
                break;
            default:
                onZnodeEvent( event );
        }
    }

    private void onKeeperStateEvent( WatchedEvent event ) {
        switch ( event.getState() ) {
            case SyncConnected:
                LOGGER.debug( "Connected to server with session id {}", zk.getSessionId() );
                break;
            case Expired:
                LOGGER.debug( "Session expired, recreating" );
                // 一旦会话过期，ZooKeeper对象就废了
                createZooKeeper();
                break;
        }
    }

    private void onZnodeEvent( WatchedEvent event ) {
        Queue<Consumer<EventResolver>> consumers = allListeners.get( event.getType() ).get( event.getPath() );
        if ( consumers != null ) {
            consumers.forEach( consumer -> consumer.accept( new EventResolver( event ) ) );
            // 继续监控
            watch( event.getType(), event.getPath() );
        }
    }

}

客户端代码：

package cc.gmem.study;

import org.apache.zookeeper.KeeperException;
import org.apache.zookeeper.data.Stat;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.concurrent.TimeUnit;

import static org.apache.zookeeper.Watcher.Event.EventType.*;

/**
 * Created by alex on 8/10/16.
 */
public class WatchClient {

    private static final Logger LOGGER = LoggerFactory.getLogger( WatchClient.class );

    public static void main( String[] args ) throws InterruptedException {
        String connectString = "172.21.0.1:2181,172.21.0.2:2181,172.21.0.3:2181";
        ZooKeeperAgent agent = new ZooKeeperAgent( connectString, 2000 * 20 );
        agent.on( NodeCreated, "/user", ( resolver ) -> {
            Stat stat = new Stat();
            LOGGER.debug( "znode craeted with data: {}", new String( resolver.getData( stat ) ) );
        } );
        agent.on( NodeDataChanged, "/user", ( resolver ) -> {
            Stat stat = new Stat();
            LOGGER.debug( "znode data: {}, version: {}", new String( resolver.getData( stat ) ), stat.getVersion() );
        } );
        agent.on( NodeDeleted, "/user", ( resolver ) -> {
            LOGGER.debug( "znode deleted" );
        } );
        TimeUnit.DAYS.sleep( 1 );
    }
}

ZooKeeper名字空间可以直接当做类似于JNDI的命名服务使用，ZooKeeper和JNDI都可以把目录节点关联到特定的资源（但是JNDI的资源是Java对象），ZooKeeper还具有与生俱来的高可用性。

ZooKeeper可以用来管理分布式系统中的配置项，如果多个应用服务实例需要共享很多系统参数，可以交由ZooKeeper来管理，通过Watch的方式，应用服务可以在配置变更后获得通知。

ZooKeeper可以管理服务的集群：

1. 当新增服务器、删除服务器（服务器宕机）时，客户端、ZooKeeper、集群成员可以得到通知。实现原理是：
   1. 每个集群成员启动后，都在某个znode下创建临时子节点，这个子节点依赖于TCP长连接保活
   2. 一旦集群成员宕机，临时子节点由于TCP连接的断开而自动删除
   3. 关注者可以在父节点上调用getChildren( parentPath, true)进行watch，一旦子节点发生增减，此调用即返回
2. 在集群成员中选取Leader（Master）。实现原理是：
   1. 每个成员创建不但是临时，还是有序（SEQUENTIAL）的子节点
   2. 序号最小的成员，总是作为Leader
   3. 如果当前Leader宕机，则次小的成员被选作Leader

要实现独占锁，可以把多个协作者共享的资源抽象为一个znode，然后：

1. 需要占用此资源的协作者，在znode 下创建一个临时、有序子节点
2. 协作者判断自己这个节点序号是否最小：
   1. 如果是，意味着获得锁
   2. 如果否，则在父节点上watch。收到通知后，继续执行步骤2
3.  当需要是否资源时，删除自己创建的子节点即可

所谓屏障（Barrier），即协作者到达某个状态后，等待其它协作者都到达此状态，然后一起继续。基于ZooKeeper可以这样实现屏障：

1. 每个协作者到达状态后，均创建一个子节点
2. 判断子节点总数是否足够：
   1. 如果是，跨越屏障继续执行业务逻辑
   2. 如果否，则在父节点上watch。收到通知后，继续执行步骤2

报错信息：

2017-08-09 17:53:03,750 [myid:1] - ERROR [/172.21.1.1:3888:QuorumCnxManager$Listener@763] - Exception while listening
java.net.BindException: Cannot assign requested address (Bind failed)

解决办法：配置文件添加

quorumListenOnAllIPs=true

可以通过JMX查看，通过Oracle Mission Controll连接到名为 org.apache.zookeeper.server.quorum.QuorumPeerMain  的JVM，在MBean Browser选项卡中可以看到相关信息。

此文件是ZooKeeper运行期间的标准输出，要指定它的存放位置，可以设置

ZOO_LOG_DIR

注意，上述环境变量同时也作为log4j的日志输出目录。

The post ZooKeeper学习笔记 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 }