dev, v3.0: add monitoring TiDB in K8s and log collecting

dev/how-to/maintain/tidb-in-kubernetes/log-collecting.md

@@ -0,0 +1,90 @@
+---
+title: 日志收集
+category: how-to
+---
+
+# 日志收集
+
+系统与程序的运行日志对排查问题以及实现一些自动化操作可能非常有用。本文将简要说明收集 TiDB 及相关组件日志的方法。
+
+## TiDB 与 Kubernetes 组件运行日志
+
+通过 TiDB Operator 部署的 TiDB 各组件默认将日志输出在容器的 `stdout` 和 `stderr` 中。对于 Kubernetes 而言，这些日志会被存放在宿主机的 `/var/log/containers` 目录下，并且文件名中包含了 Pod 和容器名称等信息。因此，对容器中应用的日志收集可以直接在宿主机上完成。
+
+如果在你的现有基础设施中已经有用于收集日志的系统，只需要通过常规方法将 Kubernetes 所在的宿主机上的 `/var/log/containers/*.log` 文件加入采集范围即可；如果没有可用的日志收集系统，或者希望部署一套独立的系统用于收集相关日志，也可以使用你熟悉的任意日志收集系统或方案。
+
+Kubernetes 官方文档中提供了 [ElasticSearch](https://kubernetes.io/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana/) 和 [Stackdriver](https://kubernetes.io/docs/tasks/debug-application-cluster/logging-stackdriver/) 两种日志收集方案可供参考。
+
+常见的可用于收集 Kubernetes 日志的开源工具有：
+
+- [Fluentd](https://www.fluentd.org/)
+- [Fluent-bit](https://fluentbit.io/)
+- [Filebeat](https://www.elastic.co/products/beats/filebeat)
+- [Logstash](https://www.elastic.co/products/logstash)
+
+收集到的日志通常可以汇总存储在某一特定的服务器上，或存放到 ElasticSearch 等专用的存储、分析系统当中。
+
+一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的日志收集方案可以选择。
+
+如果不通过单独的日志收集工具汇总日志，你也可以直接使用 `kubectl` 工具查看某个容器的运行日志，但这一方法无法查看已销毁容器的日志：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+kubectl logs -n ${namespace} ${tidbPodName}
+```
+
+若需查看容器重启之前的日志，可以在执行上述命令时添加 `-p` 参数。
+
+如果需要从多个 Pod 获取日志，可以使用 [`stern`](https://github.com/wercker/stern)：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+stern -n ${namespace} tidb -c slowlog
+```
+
+## TiDB 慢查询日志
+
+对于 3.0 之前的版本，在默认情况下，TiDB 会打印慢查询日志到标准输出，和应用日志混在一起。
+
+- 如果 TiDB 版本 <= v2.1.7，你可以通过关键字 `SLOW_QUERY` 来筛选慢查询日志，例如：
+
+    {{< copyable "shell-regular" >}}
+
+    ```shell
+    kubectl logs -n ${namespace} ${tidbPodName} | grep SLOW_QUERY
+    ```
+
+- 如果 TiDB 版本 >= v2.1.8，由于慢查询日志格式发生变化，不太方便分离慢查询日志，建议参考下面内容配置 `separateSlowLog: true` 单独查看慢查询日志。
+
+在一些情况下，你可能希望使用一些工具或自动化系统对日志内容进行分析、处理。TiDB 各组件的应用日志使用了[统一的日志格式](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)以便于程序解析，但由于慢查询日志使用的是与 MySQL 兼容的多行格式，与应用日志混在一起时可能会对解析造成困难。
+
+如果希望将慢查询日志和应用日志区分开，可以在 `values.yaml` 文件中配置 `separateSlowLog` 参数，将慢查询日志输出到一个专用的旁路容器中，这样慢查询日志在宿主机上会被输出到一个单独的文件，和应用日志分开。
+
+修改方法为编辑 `values.yaml` 文件，将 `separateSlowLog` 参数设置为 `true`：
+
+```yaml
+# Uncomment the following line to enable separate output of the slow query log
+    separateSlowLog: true
+```
+
+之后再运行 `helm upgrade` 使配置生效，然后可以通过名为 `slowlog` 的 sidecar 容器查看慢查询日志：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+kubectl logs -n ${namespace} ${tidbPodName} -c slowlog
+```
+
+对于 3.0 及更新的版本，TiDB 将慢查询日志输出到独立的 `slowlog.log` 文件中，并且 `separateSlowLog` 是默认开启的，所以可以直接通过 sidecar 容器查看慢查询日志，无需额外设置。
+
+> **注意：**
+>
+> 慢查询日志的格式与 MySQL 的慢查询日志相同，但由于 TiDB 自身的特点，其中的一些具体字段可能存在差异，因此解析 MySQL 慢查询日志的工具不一定能完全兼容 TiDB 的慢查询日志。
+
+## 系统日志
+
+系统日志可以通过常规方法在 Kubernetes 宿主机上收集，如果在你的现有基础设施中已经有用于收集日志的系统，只需要通过常规方法将相关服务器和日志文件添加到收集范围即可；如果没有可用的日志收集系统，或者希望部署一套独立的系统用于收集相关日志，也可以使用你熟悉的任意日志收集系统或方案。
+
+上文提到的几种常见日志收集工具均支持对系统日志的收集，一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的日志收集方案可以选择。

dev/how-to/maintain/tidb-in-kubernetes/tidb-cluster.md

@@ -215,55 +215,11 @@ kubectl get pv -l app.kubernetes.io/namespace=${namespace},app.kubernetes.io/man
 
 TiDB 通过 Prometheus 和 Grafana 监控 TiDB 集群。TiDB 集群创建时，会同时创建、配置 Prometheus 和 Grafana pod 收集并展示监控指标。
 
-监控数据默认没有持久化，如果由于某些原因监控容器重启，数据会丢失。可以在 `values.yaml` 中设置 `monitor.persistent` 为 `true` 来持久化监控数据。
+配置与访问监控系统的细节请参阅[监控系统部署](/how-to/monitor/tidb-in-kubernetes.md)。
 
-可以通过 `kubectl portforward` 查看监控面板：
+## 日志
 
-{{< copyable "shell-regular" >}}
-
-```shell
-kubectl port-forward -n ${namespace} svc/${releaseName}-grafana 3000:3000 &>/tmp/portforward-grafana.log
-```
-
-然后在浏览器中打开 [http://localhost:3000](http://localhost:3000)，默认用户名和密码都为 `admin`。
-
-Grafana 服务默认通过 `NodePort` 暴露，如果 Kubernetes 集群支持负载均衡器，你可以修改为 `LoadBalancer`，然后通过负载均衡器访问面板。详请参阅[访问 Kubernetes 上的 TiDB 集群](/how-to/deploy/orchestrated/tidb-in-kubernetes/access-tidb.md)。
-
-### 查看 TiDB 慢查询日志
-
-* 如果 `values.yaml` 中没有显示配置 `separateSlowLog: true`，那么 TiDB 会打印慢查询日志到标准输出，和正常日志混在一起。
-
-    如果 TiDB 版本 <= v2.1.7，你可以通过 `grep` 关键词 `SLOW_QUERY` 查看慢查询日志：
-
-    {{< copyable "shell-regular" >}}
-
-    ```shell
-    kubectl logs -n ${namespace} ${tidbPodName} | grep SLOW_QUERY
-    ```
-
-    如果 TiDB 版本 >= v2.1.8，由于慢查询日志格式发生变化，不太方便分离慢查询日志，建议参考下面内容配置 `separateSlowLog: true` 单独查看慢查询日志。
-
-* 配置 `separateSlowLog: true` 输出慢查询日志到一个 sidecar 容器：
-
-    ```yaml
-    separateSlowLog: true
-    ```
-
-    运行 `helm upgrade` 使配置生效，然后你可以通过名为 `slowlog` 的 sidecar 容器查看慢查询日志：
-
-    {{< copyable "shell-regular" >}}
-
-    ```shell
-    kubectl logs -n ${namespace} ${tidbPodName} -c slowlog
-    ```
-
-    如果要从多个 Pod 获取日志，推荐 [`stern`](https://github.com/wercker/stern)。
-
-    {{< copyable "shell-regular" >}}
-
-    ```shell
-    stern -n ${namespace} tidb -c slowlog
-    ```
+查看与收集日志的方法请参阅[日志收集](/how-to/maintain/tidb-in-kubernetes/log-collecting.md)文档。
 
 ## 备份和恢复
 

dev/how-to/monitor/tidb-in-kubernetes.md

@@ -0,0 +1,97 @@
+---
+title: 监控系统部署
+category: how-to
+---
+
+# 监控系统部署
+
+基于 Kubernetes 环境部署的 TiDB 集群监控可以大体分为两个部分：对 TiDB 集群本身的监控、对 Kubernetes 集群及 TiDB Operator 的监控。本文将对两者进行简要说明。
+
+## TiDB 集群的监控
+
+TiDB 通过 Prometheus 和 Grafana 监控 TiDB 集群。在通过 TiDB Operator 创建新的 TiDB 集群时，对于每个 TiDB 集群，会同时创建、配置一套独立的监控系统，与 TiDB 集群运行在同一 Namespace，包括 Prometheus 和 Grafana 两个组件。
+
+监控数据默认没有持久化，如果由于某些原因监控容器重启，已有的监控数据会丢失。可以在 `values.yaml` 中设置 `monitor.persistent` 为 `true` 来持久化监控数据。开启此选项时应将 `storageClass` 设置为一个当前集群中已有的存储，并且此存储应当支持将数据持久化，否则仍然会存在数据丢失的风险。
+
+在 [TiDB 集群监控](/how-to/monitor/monitor-a-cluster.md)中有一些监控系统配置的细节可供参考。
+
+### 查看监控面板
+
+可以通过 `kubectl port-forward` 查看监控面板：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+kubectl port-forward -n ${namespace} svc/${releaseName}-grafana 3000:3000 &>/tmp/portforward-grafana.log
+```
+
+然后在浏览器中打开 [http://localhost:3000](http://localhost:3000)，默认用户名和密码都为 `admin`。
+
+Grafana 服务默认通过 `NodePort` 暴露，如果 Kubernetes 集群支持负载均衡器，你可以在 `values.yaml` 中将 `monitor.grafana.service.type` 修改为 `LoadBalancer`，然后在执行 `helm upgrade` 后通过负载均衡器访问面板。
+
+如果不需要使用 Grafana，可以在部署时在 `values.yaml` 中将 `monitor.grafana.create` 设置为 `false` 来节省资源。这一情况下需要使用其他已有或新部署的数据可视化工具直接访问监控数据来完成可视化。
+
+### 访问监控数据
+
+对于需要直接访问监控数据的情况，可以通过 `kubectl port-forward` 来访问 Prometheus：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+kubectl port-forward -n ${namespace} svc/${releaseName}-prometheus 9090:9090 &>/tmp/portforward-prometheus.log
+```
+
+然后在浏览器中打开 [http://localhost:9090](http://localhost:9090)，或通过客户端工具访问此地址即可。
+
+Prometheus 服务默认通过 `NodePort` 暴露，如果 Kubernetes 集群支持负载均衡器，你可以在 `values.yaml` 中将 `monitor.prometheus.service.type` 修改为 `LoadBalancer`，然后在执行 `helm upgrade` 后通过负载均衡器访问监控数据。
+
+## Kubernetes 的监控
+
+随集群部署的 TiDB 监控只关注 TiDB 本身各组件的运行情况，并不包括对容器资源、宿主机、Kubernetes 组件和 TiDB Operator 等的监控。对于这些组件或资源的监控，需要在整个 Kubernetes 集群维度部署监控系统来实现。
+
+### 宿主机监控
+
+对宿主机及其资源的监控与传统的服务器物理资源监控相同。
+
+如果在你的现有基础设施中已经有针对物理服务器的监控系统，只需要通过常规方法将 Kubernetes 所在的宿主机添加到现有监控系统中即可；如果没有可用的监控系统，或者希望部署一套独立的监控系统用于监控 Kubernetes 所在的宿主机，也可以使用你熟悉的任意监控系统。
+
+新部署的监控系统可以运行于独立的服务器、直接运行于 Kubernetes 所在的宿主机，或运行于 Kubernetes 集群内，不同部署方式除在安装配置与资源利用上存在少许差异，在使用上并没有重大区别。
+
+常见的可用于监控服务器资源的开源监控系统有：
+
+- [CollectD](https://collectd.org/)
+- [Nagios](https://www.nagios.org/)
+- [Prometheus](http://prometheus.io/) & [node_exporter](https://github.com/prometheus/node_exporter)
+- [Zabbix](https://www.zabbix.com/)
+
+一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的监控解决方案可以选择。
+
+我们推荐通过 [Prometheus Operator](https://github.com/coreos/prometheus-operator) 在 Kubernetes 集群内部署基于 [Node Exporter](https://github.com/prometheus/node_exporter) 和 Prometheus 的宿主机监控系统，这一方案同时可以兼容并用于 Kubernetes 自身组件的监控。
+
+### Kubernetes 组件监控
+
+对 Kubernetes 组件的监控可以参考[官方文档](https://kubernetes.io/docs/tasks/debug-application-cluster/resource-usage-monitoring/)提供的方案，也可以使用其他兼容 Kubernetes 的监控系统来进行。
+
+一些云服务商可能提供了自己的 Kubernetes 组件监控方案，一些专门的性能监控服务商也有各自的 Kubernetes 集成方案可以选择。
+
+由于 TiDB Operator 实际上是运行于 Kubernetes 中的容器，选择任一可以覆盖对 Kubernetes 容器状态及资源进行监控的监控系统即可覆盖对 TiDB Operator 的监控，无需再额外部署监控组件。
+
+我们推荐通过 [Prometheus Operator](https://github.com/coreos/prometheus-operator) 部署基于 [Node Exporter](https://github.com/prometheus/node_exporter) 和 Prometheus 的宿主机监控系统，这一方案同时可以兼容并用于对宿主机资源的监控。
+
+## 报警配置
+
+### TiDB 集群报警
+
+在随 TiDB 集群部署 Prometheus 时，会自动导入一些默认的报警规则，可以通过浏览器访问 Prometheus 的 Alerts 页面查看当前系统中的所有报警规则和状态。
+
+我们目前暂不支持报警规则的自定义配置，如果确实需要修改报警规则，可以手动下载 charts 进行修改。
+
+默认的 Prometheus 和报警配置不能发送报警消息，如需发送报警消息，可以使用任意支持 Prometheus 报警的工具与其集成。推荐通过 [AlertManager](https://prometheus.io/docs/alerting/alertmanager/) 管理与发送报警消息。
+
+如果在你的现有基础设施中已经有可用的 AlertManager 服务，可以在 `values.yaml` 文件中修改 `monitor.prometheus.alertmanagerURL` 配置其地址供 Prometheus 使用；如果没有可用的 AlertManager 服务，或者希望部署一套独立的服务，可以参考官方的[说明](https://github.com/prometheus/alertmanager)部署。
+
+### Kubernetes 报警
+
+如果使用 Prometheus Operator 部署针对 Kubernetes 宿主机和服务的监控，会默认配置一些告警规则，并且会部署一个 AlertManager 服务，具体的设置方法请参阅 [kube-prometheus](https://github.com/coreos/kube-prometheus) 的说明。
+
+如果使用其他的工具或服务对 Kubernetes 宿主机和服务进行监控，请查阅该工具或服务提供商的对应资料。

v3.0/how-to/maintain/tidb-in-kubernetes/log-collecting.md

@@ -0,0 +1,90 @@
+---
+title: 日志收集
+category: how-to
+---
+
+# 日志收集
+
+系统与程序的运行日志对排查问题以及实现一些自动化操作可能非常有用。本文将简要说明收集 TiDB 及相关组件日志的方法。
+
+## TiDB 与 Kubernetes 组件运行日志
+
+通过 TiDB Operator 部署的 TiDB 各组件默认将日志输出在容器的 `stdout` 和 `stderr` 中。对于 Kubernetes 而言，这些日志会被存放在宿主机的 `/var/log/containers` 目录下，并且文件名中包含了 Pod 和容器名称等信息。因此，对容器中应用的日志收集可以直接在宿主机上完成。
+
+如果在你的现有基础设施中已经有用于收集日志的系统，只需要通过常规方法将 Kubernetes 所在的宿主机上的 `/var/log/containers/*.log` 文件加入采集范围即可；如果没有可用的日志收集系统，或者希望部署一套独立的系统用于收集相关日志，也可以使用你熟悉的任意日志收集系统或方案。
+
+Kubernetes 官方文档中提供了 [ElasticSearch](https://kubernetes.io/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana/) 和 [Stackdriver](https://kubernetes.io/docs/tasks/debug-application-cluster/logging-stackdriver/) 两种日志收集方案可供参考。
+
+常见的可用于收集 Kubernetes 日志的开源工具有：
+
+- [Fluentd](https://www.fluentd.org/)
+- [Fluent-bit](https://fluentbit.io/)
+- [Filebeat](https://www.elastic.co/products/beats/filebeat)
+- [Logstash](https://www.elastic.co/products/logstash)
+
+收集到的日志通常可以汇总存储在某一特定的服务器上，或存放到 ElasticSearch 等专用的存储、分析系统当中。
+
+一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的日志收集方案可以选择。
+
+如果不通过单独的日志收集工具汇总日志，你也可以直接使用 `kubectl` 工具查看某个容器的运行日志，但这一方法无法查看已销毁容器的日志：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+kubectl logs -n ${namespace} ${tidbPodName}
+```
+
+若需查看容器重启之前的日志，可以在执行上述命令时添加 `-p` 参数。
+
+如果需要从多个 Pod 获取日志，可以使用 [`stern`](https://github.com/wercker/stern)：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+stern -n ${namespace} tidb -c slowlog
+```
+
+## TiDB 慢查询日志
+
+对于 3.0 之前的版本，在默认情况下，TiDB 会打印慢查询日志到标准输出，和应用日志混在一起。
+
+- 如果 TiDB 版本 <= v2.1.7，你可以通过关键字 `SLOW_QUERY` 来筛选慢查询日志，例如：
+
+    {{< copyable "shell-regular" >}}
+
+    ```shell
+    kubectl logs -n ${namespace} ${tidbPodName} | grep SLOW_QUERY
+    ```
+
+- 如果 TiDB 版本 >= v2.1.8，由于慢查询日志格式发生变化，不太方便分离慢查询日志，建议参考下面内容配置 `separateSlowLog: true` 单独查看慢查询日志。
+
+在一些情况下，你可能希望使用一些工具或自动化系统对日志内容进行分析、处理。TiDB 各组件的应用日志使用了[统一的日志格式](https://github.com/tikv/rfcs/blob/master/text/2018-12-19-unified-log-format.md)以便于程序解析，但由于慢查询日志使用的是与 MySQL 兼容的多行格式，与应用日志混在一起时可能会对解析造成困难。
+
+如果希望将慢查询日志和应用日志区分开，可以在 `values.yaml` 文件中配置 `separateSlowLog` 参数，将慢查询日志输出到一个专用的旁路容器中，这样慢查询日志在宿主机上会被输出到一个单独的文件，和应用日志分开。
+
+修改方法为编辑 `values.yaml` 文件，将 `separateSlowLog` 参数设置为 `true`：
+
+```yaml
+# Uncomment the following line to enable separate output of the slow query log
+    separateSlowLog: true
+```
+
+之后再运行 `helm upgrade` 使配置生效，然后可以通过名为 `slowlog` 的 sidecar 容器查看慢查询日志：
+
+{{< copyable "shell-regular" >}}
+
+```shell
+kubectl logs -n ${namespace} ${tidbPodName} -c slowlog
+```
+
+对于 3.0 及更新的版本，TiDB 将慢查询日志输出到独立的 `slowlog.log` 文件中，并且 `separateSlowLog` 是默认开启的，所以可以直接通过 sidecar 容器查看慢查询日志，无需额外设置。
+
+> **注意：**
+>
+> 慢查询日志的格式与 MySQL 的慢查询日志相同，但由于 TiDB 自身的特点，其中的一些具体字段可能存在差异，因此解析 MySQL 慢查询日志的工具不一定能完全兼容 TiDB 的慢查询日志。
+
+## 系统日志
+
+系统日志可以通过常规方法在 Kubernetes 宿主机上收集，如果在你的现有基础设施中已经有用于收集日志的系统，只需要通过常规方法将相关服务器和日志文件添加到收集范围即可；如果没有可用的日志收集系统，或者希望部署一套独立的系统用于收集相关日志，也可以使用你熟悉的任意日志收集系统或方案。
+
+上文提到的几种常见日志收集工具均支持对系统日志的收集，一些云服务商或专门的性能监控服务提供商也有各自的免费或收费的日志收集方案可以选择。