You signed in with another tab or window.Reload to refresh your session.You signed out in another tab or window.Reload to refresh your session.You switched accounts on another tab or window.Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jul 6, 2021. It is now read-only.
Copy file name to clipboardExpand all lines: README.md
+56-18Lines changed: 56 additions & 18 deletions
Original file line number
Diff line number
Diff line change
@@ -1,41 +1,77 @@
1
1
#About
2
-
Postgres Checkup ([postgres-checkup](https://gitlab.com/postgres-ai-team/postgres-checkup)) is a new-generation diagnostics tool that allows to collect deep analysis of a Postgres database health. It aims to detect and describe all current and potential issues in the fields of database performance, scalability and security, advising how to resolve or prevent them.
3
-
4
-
Compared to a monitoring system, postgres-checkup goes deeper in database system and environment analysis, it combines numerious database internal characteristics with data about resources and OS into multiple comprehensive reports. These reports use formats which are easy readable both by humans and machines and are extremely oriented to DBA problems solving. Monitoring systems constantly collect telemetry, they help to react to issues quicker and do post-mortem analyses. Checkups are needed for a different purpose: detect issues at very early stage, advising on how to prevent them. This procedure is to be done on a regular basis — weekly, monthly, or quarterly. Additionally, it is recommended to run it right right before and right after any major change in database server.
is a new-generation diagnostics tool that allows users to collect deep analysis
4
+
of the health of a Postgres database. It aims to detect and describe all current
5
+
and potential issues in the fields of database performance, scalability, and
6
+
security, providing advices how to resolve or prevent them.
7
+
8
+
Compared to a monitoring system, postgres-checkup goes deeper into the analysis
9
+
of the database system and environment. It combines numerous internal
10
+
characteristics of the database with data about resources and OS, producing
11
+
multiple comprehensive reports. These reports use formats which are easily
12
+
readable both by humans and machines and which are extremely oriented to DBA
13
+
problem-solving. Monitoring systems constantly collect telemetry, help to react
14
+
to issues more quickly, and are useful for post-mortem analyses. At the same
15
+
time, checkups are needed for a different purpose: detect issues at a very early
16
+
stage, advising on how to prevent them. This procedure is to be done on a
17
+
regular basis — weekly, monthly, or quarterly. Additionally, it is recommended
18
+
to run it immediately before and after any major change in the database server.
5
19
6
20
The three key principles behind postgres-checkup:
7
21
8
-
- *Unobtrusiveness*: postgres-checkup’s impact on the observing system is close to zero. It does not use any heavy queries, keeping resource usage very low, avoids having the “observer effect”.
22
+
- *Unobtrusiveness*: postgres-checkup’s impact on the observing system is
23
+
close to zero. It does not use any heavy queries, keeping resource usage
24
+
very low, and avoiding having the [“observer effect.”](https://en.wikipedia.org/wiki/Observer_effect_(information_technology))
9
25
10
-
- *Zero install* (on observed machines): it is able to analyze any Linux machine (including virtual machines), as well as Cloud Postgres instanced (such as Amazon RDs or Google Cloud SQL), not requiring any additional setup or any changes. It does, hovewer, require the privileged access (a DBA usually has it anyway).
26
+
- *Zero install* (on observed machines): it is able to analyze any Linux
27
+
machine (including virtual machines), as well as Cloud Postgres instances
28
+
(such as Amazon RDs or Google Cloud SQL), not requiring any additional setup
29
+
or any changes. It does, hovewer, require a privileged access (a DBA usually
30
+
has it anyway).
11
31
12
-
- *Complex analysis*: unlike most monitoring tools, which provide raw data, postgres-checkup combines data from various parts of the system (w.g.: internal Postgres stats are combined with knowledge about system resources in autovacuum setting and behavior analysis). Also, it analyzes the master database server together with all its replicas (e.g. to build the list of unused indexes).
32
+
- *Complex analysis*: unlike most monitoring tools, which provide raw data,
33
+
postgres-checkup combines data from various parts of the system (e.g.,
34
+
internal Postgres stats are combined with knowledge about system resources
35
+
in autovacuum setting and behavior analysis). Also, it analyzes the master
36
+
database server together with all its replicas (e.g. to build the list of
37
+
unused indexes).
13
38
14
39
#Reports Structure
15
-
Thetwo kinds of reports postgres-checkup produces for every check:
40
+
Postgres-checkup producestwo kinds of reports for every check:
16
41
17
-
- JSON reports (*.json) — can be consumed by any program or service, or stores in some database.
42
+
- JSON reports (*.json) — can be consumed by any program or service, or
43
+
stores in some database.
18
44
19
-
- Markdown reports (*.md) — the main format for humans, may contain lists, tables, pictures. Being of native format for GitLab and GitHub, such reports are ready to be used, for instance, in their issue trackers, simplifying workflow. Markdown reports are derived from JSON reports.
45
+
- Markdown reports (*.md) — the main format for humans, may contain lists,
46
+
tables, pictures. Being of native format for GitLab and GitHub, such reports
47
+
are ready to be used, for instance, in their issue trackers, simplifying
48
+
workflow. Markdown reports are derived from JSON reports.
20
49
21
50
Markdown reports can be converted to different formats such as HTML or PDF.
22
51
23
52
Each report consists of three sections:
24
53
25
-
1. "Observations": automatically collected data. This is to be consumed by an expert DBA.
26
-
1. "Conclusions": what we conclude from the Observations, what is good, what is bad (right now, it is to be manually filled for most checks).
27
-
1. "Recommendations": actions items, what to do to fix issues found. Both "Conclusions" and "Recommendations" are to be consumed by an engineers who will make decisions what, how and when to optimize, how to react to the findings.
54
+
1. "Observations": automatically collected data. This is to be consumed by
55
+
an expert DBA.
56
+
1. "Conclusions": what we conclude from the Observations—what is good, what
57
+
is bad (right now, it is to be manually filled for most checks).
58
+
1. "Recommendations": action items, what to do to fix the discovered issues.
59
+
Both "Conclusions" and "Recommendations" are to be consumed by engineers who
60
+
will make decisions what, how and when to optimize, and how to react to the
61
+
findings.
28
62
29
63
#Installation and Usage
30
64
31
65
##Requirements
32
66
33
-
The supported OS of the observer machine (those from which the tool is to be executed):
67
+
The supported OS of the observer machine (those from which the tool is to be
68
+
executed):
34
69
35
-
* Linux (modern RHEL/CentOS or Debian/Ubuntu; others should work as well, but not yet tested);
70
+
* Linux (modern RHEL/CentOS or Debian/Ubuntu; others should work as well, but
71
+
are not yet tested);
36
72
* MacOS.
37
73
38
-
It has to havethefollowing programs:
74
+
The following programs must be installed ontheobserver machine:
39
75
40
76
* bash
41
77
* psql
@@ -45,13 +81,15 @@ It has to have the following programs:
45
81
* awk
46
82
* sed
47
83
48
-
Nothing special has to be istalled on the observed machines. However, these machines must run Linux (again: modern RHEL/CentOS or Debian/Ubuntu; others should work as well, but not yet tested).
84
+
Nothing special has to be installed on the observed machines. However, these
85
+
machines must run Linux (again: modern RHEL/CentOS or Debian/Ubuntu; others
86
+
should work as well, but are not yet tested).
49
87
50
88
:warning: Only Postgres version 9.6 and higher are currently supported.
51
89
52
90
##How to Install
53
91
54
-
Use`git clone`. This is the onlyway of installation currently supported.
92
+
Use`git clone`. This is the onlymethod of installation currently supported.
55
93
56
94
##Example of Use
57
95
@@ -85,7 +123,7 @@ As a result of postgres-checkup we have got two directories with .json files and
85
123
Each of generated files contains information about "what we check" and collected data for