附录：测试环境

本附录介绍测试环境的启动和使用方法。理解本书并不一定需要这个环境，但在阅读过程中使用它可能会很有帮助。利用该环境可以重现书中给出的所有示例，也可以进行各种与监控相关的实验。

基本信息

该环境基于 Docker 容器构建，包含以下组件：

两节点 PostgreSQL 流复制集群。该集群用于演示复制监控工具和方法。
pgSCV 指标导出器。这是一个从 PostgreSQL 节点收集统计信息并以 Prometheus 格式提供这些信息的监控代理。该监控代理属于实验性产品，不建议用于生产环境。
基于 Victoriametrics 和 Vmagent 的监控系统。该监控系统从 pgSCV 代理收集指标，并将其保存两天。
基于 pgbench 工具、用于产生工作负载的应用。环境中运行着多个 pgbench 实例，它们的任务是持续为 PostgreSQL 集群生成动态负载。
Grafana 可视化系统。它作为监控系统的前端，可以创建各种高度可配置的图表。

依赖项

请确认运行测试环境的系统中已经安装以下工具：

Docker-compose，版本 ⩾ 1.29.2；
Docker Engine，版本 ⩾ 20.10.12；
GNU Make，版本 ⩾ 4.2.1。

不保证测试环境能够在更早版本上运行。

可以按照官方说明安装 docker-compose，说明地址为 docs.docker.com/compose/install/。Docker Engine 也应按照官方说明安装：docs.docker.com/engine/install/#server。GNU Make 软件包可以使用软件包管理器，从适用于操作系统的官方软件包仓库中安装。

安装好所有依赖项后，就可以启动环境了。

启动环境

可以通过 Makefile 使用基本命令，但用户也可以直接调用 docker 和 docker-compose 工具来执行其他命令。

执行以下命令进入测试环境目录，然后查看可用 make 目标的帮助：

$ git clone https://github.com/lesovsky/postgresql-monitoring-book.git
$ cd postgresql-monitoring-book/playground
$ make help
Makefile available targets:
* help         Display this help screen
* up           Start playground environment
* ps           Show current status of playground services
* down         Stop playground environment (without cleanup)
* destroy      Stop playground environment and clean up related resources
* %/logs       Show service logs; % - service name, e.g. primary or standby
* %/logs/tail  Tail service logs; % - service name, e.g. primary or standby
* %/shell      Start shell session; % - service name, e.g. primary or standby
* %/psql       Start psql session; % - service name, e.g. primary or standby
* %/pgcenter   Start pgcenter session; % - service name, e.g. primary or standby

make 目标提供了启动和停止测试环境、连接容器中服务的简便方式，后续操作会用到这些目标。执行目标时，第一行会输出实际执行的命令，因此无需使用 Makefile，也可以直接执行该命令。

启动测试应用：

$ make up

首次启动时会构建容器、初始化服务，并将数据加载到测试数据库（约 300 MB）。这一过程可能需要一段时间，具体取决于设备的性能。

基本可用性检查

初始化完成后，应检查环境是否已经准备就绪。首先需要了解容器和服务的总体状态：

$ make ps
docker-compose ps
NAME                         COMMAND                   SERVICE          STATUS     PORTS
playground-app1-1            "docker-entrypoint.s…"   app1             running    5432/tcp
playground-app2-1            "docker-entrypoint.s…"   app2             running    5432/tcp
playground-app3-1            "docker-entrypoint.s…"   app3             running    5432/tcp
playground-app4-1            "docker-entrypoint.s…"   app4             running    5432/tcp
playground-grafana-1         "/run.sh"                 grafana          running    0.0.0.0:3000->3000/tcp
playground-pgscv-1           "pgscv"                   pgscv            running    0.0.0.0:9890->9890/tcp
playground-primary-1         "docker-entrypoint.s…"   primary          running    5432/tcp
playground-standby-1         "/docker-entrypoint.…"   standby          running    5432/tcp
playground-victoriametrics-1 "/victoria-metrics-p…"   victoriametrics  running    8428/tcp
playground-vmagent-1         "/vmagent-prod -prom…"   vmagent          running    8429/tcp

所有容器的 STATUS 字段都应为 running。两个数据库服务都应显示已准备好接受客户端连接，两个节点之间的复制也应正常工作。可以这样检查主节点的服务器日志：

$ make primary/logs
...
primary_1 | 2022-03-03 08:57:44 UTC [1] LOG: listening on IPv4 address "0.0.0.0", port 5432
primary_1 | 2022-03-03 08:57:44 UTC [1] LOG: listening on IPv6 address "::", port 5432
primary_1 | 2022-03-03 08:57:44 UTC [1] LOG: listening on Unix socket "/var/run/postgresql/.s.PGSQL.5432"
primary_1 | 2022-03-03 08:57:44 UTC [63] LOG: database system was shut down at 2022-03-03 08:57:44 UTC
primary_1 | 2022-03-03 08:57:44 UTC [1] LOG: database system is ready to accept connections

备用节点也可以用类似的方法检查：

$ make standby/logs
...
standby_1 | 2022-03-03 08:57:50 UTC [24] LOG: consistent recovery state reached at 0/11000100
standby_1 | 2022-03-03 08:57:50 UTC [1] LOG: database system is ready to accept read-only connections
standby_1 | 2022-03-03 08:57:50 UTC [28] LOG: started streaming WAL from primary at 0/12000000 on timeline 1

现在启动连接到集群主节点的会话，作为可用性检查：

$ make primary/psql
psql (15.0)
Type "help" for help.

postgres=#

在打开的会话中，可以向服务器发送 SQL 查询：

postgres=# SELECT * FROM pg_stat_activity;
...
postgres=# SELECT * FROM pg_stat_replication;
...

查询结果会以表格形式显示。在读完本书之前，不必理解这些查询及其结果的含义；统计信息就是这样使用的：针对所需视图编写 SQL 查询，将其发送给服务器，然后以表格形式得到结果，其中包含若干行（有时一行也没有）。

除非特别说明，书中的所有查询都在主节点上执行。

Grafana

Grafana 前端的地址是 127.0.0.1:3000。登录时不需要用户名和密码。要创建图表，可以使用 Explore 模式，也可以创建一个单独的面板集合，并在其中添加图表面板。

停止和删除

要停止测试环境，请执行以下命令：

$ make down

如果不再需要测试环境，可以停止它并删除所有相关组件：

$ make destroy