Skip to content

Commit a6bc656

Browse files
VonngVonng
committed
chore: polish document
1 parent 0506b50 commit a6bc656

File tree

10 files changed

+272
-90
lines changed

10 files changed

+272
-90
lines changed

‎NOTICE‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -13,21 +13,22 @@ under AGPL-3.0. These modules have separate LICENSE files in their directories.
1313

1414
License texts:
1515
- Apache-2.0: LICENSE
16-
- AGPL-3.0: roles/infra/LICENSE, roles/minio/LICENSE, files/grafana/LICENSE
16+
- AGPL-3.0: roles/minio/LICENSE, files/grafana/LICENSE
1717

1818
For detailed licensing information:
1919
- https://pigsty.io/docs/about/license/
2020
- https://pigsty.cc/docs/about/license/
2121

2222
The following optional components are licensed under AGPL-3.0 (Grafana, MinIO):
2323

24-
roles/infra/ Infrastructure module (Grafana integration)
25-
roles/minio/ MinIO object storage module
26-
files/grafana/ Grafana dashboards and datasources
27-
infra.yml INFRA module playbook
28-
infra-rm.yml INFRA module removal playbook
29-
minio.yml MinIO module playbook
30-
minio-rm.yml MinIO module removal playbook
24+
roles/minio/ # MinIO object storage module
25+
minio.yml # MinIO module playbook
26+
minio-rm.yml # MinIO module removal playbook
27+
28+
roles/infra/tasks/grafana.yaml # grafana playbook
29+
roles/infra/templates/grafana.yaml # grafana templates
30+
files/grafana/ # grafana dashboards
31+
3132

3233
Pigsty is modular by design. The PostgreSQL HA cluster and all extensions can
3334
run independently without these components. So AGPLv3 is purely optional.

‎README.md‎

Lines changed: 34 additions & 34 deletions
Large diffs are not rendered by default.

‎cache.yml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -127,11 +127,11 @@
127127
# Workflow
128128
#==============================================================#
129129
#
130-
# 1. Ensure Pigsty is installed: ./install.yml
130+
# 1. Ensure Pigsty is installed: ./deploy.yml
131131
# 2. Create offline package: ./cache.yml -l infra
132132
# 3. Transfer to air-gapped env: scp dist/v4.0.0/*.tgz target:/tmp/
133133
# 4. Bootstrap with package: ./bootstrap -p /tmp/pigsty-pkg-*.tgz
134-
# 5. Configure and install: ./configure && ./install.yml
134+
# 5. Configure and install: ./configure && ./deploy.yml
135135
#
136136
#==============================================================#
137137
...

‎files/cmdb.sql‎

Lines changed: 16 additions & 17 deletions
Large diffs are not rendered by default.

‎files/grafana/README.md‎

Lines changed: 196 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,35 +1,207 @@
1-
# Dashboards
1+
# Grafana Dashboards
22

3-
This directory contains grafana dashboard definitions.
3+
This directory contains Grafana dashboard definitions for Pigsty monitoring system.
44

5-
* [Pigsty Home](pigsty.json)
6-
* [INFRA Dashboards](infra)
7-
* [Node DAshboards](node)
8-
* [PGSQL Dashboards](pgsql)
9-
* [REDIS Dashboards](redis)
10-
* [Application Dashboards](app)
5+
> **License**: AGPLv3 - GNU Affero General Public License v3.0
6+
>
7+
> The Grafana dashboards and related tooling in this directory are licensed under AGPLv3.
8+
> See [LICENSE](LICENSE) for the full license text.
9+
>
10+
> Copyright 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
1111
12-
## Utils
1312

14-
There's a utils script [`grafana.py`](grafana.py) to load / dump /clean grafana dashboards.
13+
## Overview
1514

16-
You can pass the following environment variables to the script:
15+
Pigsty provides **57 built-in dashboards** organized by module:
1716

18-
```bsah
19-
# Grafana Endpoint / Username / Password
20-
ENDPOINT = os.environ.get("GRAFANA_ENDPOINT", 'http://i.pigsty/ui')
21-
USERNAME = os.environ.get("GRAFANA_USERNAME", 'admin')
22-
PASSWORD = os.environ.get("GRAFANA_PASSWORD", 'pigsty')
17+
| Directory | Count | Description |
18+
|-----------------|-------|-------------------------------------------------------------------------|
19+
| [pgsql](pgsql/) | 29 | PostgreSQL cluster, instance, database, and query monitoring |
20+
| [infra](infra/) | 11 | Infrastructure components (VictoriaMetrics, Grafana, Nginx, etcd, etc.) |
21+
| [node](node/) | 8 | Host-level metrics (CPU, memory, disk, network, HAProxy, VIP) |
22+
| [redis](redis/) | 3 | Redis cluster and instance monitoring |
23+
| [app](app/) | 2 | Application dashboards (PostgreSQL logs analysis) |
24+
| [minio](minio/) | 2 | MinIO S3-compatible storage monitoring |
25+
| [mongo](mongo/) | 1 | MongoDB/FerretDB monitoring |
26+
| - | 1 | [pigsty.json](pigsty.json) - Main home dashboard |
2327

24-
# Replace default domain names
25-
UPSTREAM = os.environ.get("NGINX_UPSTREAM", "")
26-
NGINX_SSL = os.environ.get("NGINX_SSL_ENABLED", "false")
28+
29+
## Dashboard Catalog
30+
31+
### Home
32+
33+
- **[pigsty.json](pigsty.json)** - Pigsty home dashboard with global overview
34+
35+
### PGSQL Dashboards
36+
37+
Core PostgreSQL monitoring dashboards:
38+
39+
| Dashboard | Description |
40+
|---------------------|-------------------------------------------------|
41+
| `pgsql-overview` | Global PostgreSQL overview across all clusters |
42+
| `pgsql-cluster` | Single cluster view with all instances |
43+
| `pgsql-instance` | Single PostgreSQL instance detailed metrics |
44+
| `pgsql-database` | Single database metrics |
45+
| `pgsql-databases` | Multiple databases comparison |
46+
| `pgsql-table` | Single table detailed metrics |
47+
| `pgsql-tables` | Multiple tables comparison |
48+
| `pgsql-query` | Query performance analysis (pg_stat_statements) |
49+
| `pgsql-session` | Active sessions and connections |
50+
| `pgsql-activity` | Database activity and workload |
51+
| `pgsql-xacts` | Transaction statistics |
52+
| `pgsql-replication` | Streaming replication metrics |
53+
| `pgsql-persist` | Storage and persistence metrics |
54+
| `pgsql-proxy` | Connection pooler metrics |
55+
| `pgsql-pgbouncer` | PgBouncer detailed metrics |
56+
| `pgsql-patroni` | Patroni HA cluster status |
57+
| `pgsql-service` | Service-level metrics |
58+
| `pgsql-pitr` | Point-in-time recovery (pgBackRest) |
59+
| `pgsql-alert` | PostgreSQL alerting dashboard |
60+
| `pgsql-exporter` | pg_exporter status |
61+
| `pgsql-shard` | Sharding/Citus cluster view |
62+
| `pgrds-cluster` | AWS RDS/Aurora cluster monitoring |
63+
| `pgrds-instance` | AWS RDS/Aurora instance monitoring |
64+
65+
PGCAT (Catalog Analysis) dashboards:
66+
67+
| Dashboard | Description |
68+
|------------------|-------------------------------|
69+
| `pgcat-instance` | Catalog analysis for instance |
70+
| `pgcat-database` | Catalog analysis for database |
71+
| `pgcat-schema` | Schema object analysis |
72+
| `pgcat-table` | Table catalog details |
73+
| `pgcat-query` | Query plan analysis |
74+
| `pgcat-locks` | Lock analysis |
75+
76+
### Node Dashboards
77+
78+
| Dashboard | Description |
79+
|-----------------|------------------------------|
80+
| `node-overview` | Global node overview |
81+
| `node-cluster` | Node cluster view |
82+
| `node-instance` | Single node detailed metrics |
83+
| `node-disk` | Disk I/O and storage |
84+
| `node-haproxy` | HAProxy load balancer |
85+
| `node-vip` | Virtual IP (vip-manager) |
86+
| `node-vector` | Vector log collector |
87+
| `node-alert` | Node alerting dashboard |
88+
89+
### Infra Dashboards
90+
91+
| Dashboard | Description |
92+
|-------------------------|-------------------------|
93+
| `infra-overview` | Infrastructure overview |
94+
| `vmetrics-instance` | VictoriaMetrics TSDB |
95+
| `vlogs-instance` | VictoriaLogs |
96+
| `vtraces-instance` | VictoriaTraces |
97+
| `vmalert-instance` | VMAlert rules engine |
98+
| `alertmanager-instance` | Alertmanager |
99+
| `grafana-instance` | Grafana self-monitoring |
100+
| `nginx-instance` | Nginx web server |
101+
| `etcd-overview` | etcd cluster status |
102+
| `logs-instance` | Log analysis (legacy) |
103+
| `inventory-cmdb` | CMDB inventory view |
104+
105+
### Redis Dashboards
106+
107+
| Dashboard | Description |
108+
|------------------|-----------------------|
109+
| `redis-overview` | Global Redis overview |
110+
| `redis-cluster` | Redis cluster view |
111+
| `redis-instance` | Single Redis instance |
112+
113+
### MinIO Dashboards
114+
115+
| Dashboard | Description |
116+
|------------------|------------------------|
117+
| `minio-overview` | MinIO overview |
118+
| `minio-instance` | MinIO instance metrics |
119+
120+
### MongoDB Dashboards
121+
122+
| Dashboard | Description |
123+
|------------------|---------------------------|
124+
| `mongo-overview` | MongoDB/FerretDB overview |
125+
126+
### Application Dashboards
127+
128+
| Dashboard | Description |
129+
|------------------|----------------------------------|
130+
| `pglog-overview` | PostgreSQL log analysis overview |
131+
| `pglog-session` | PostgreSQL log session analysis |
132+
133+
134+
## Utilities
135+
136+
The [`grafana.py`](grafana.py) script provides utilities to manage Grafana dashboards.
137+
138+
### Environment Variables
139+
140+
```bash
141+
# Grafana connection settings
142+
export GRAFANA_ENDPOINT='http://i.pigsty/ui' # Grafana URL
143+
export GRAFANA_USERNAME='admin' # Username
144+
export GRAFANA_PASSWORD='pigsty' # Password
145+
146+
# Optional: Domain replacement
147+
export NGINX_UPSTREAM=""
148+
export NGINX_SSL_ENABLED="false"
149+
```
150+
151+
### Commands
152+
153+
```bash
154+
# Initialize baseline dashboards
155+
./grafana.py init
156+
157+
# Dump all dashboards to current directory
158+
./grafana.py dump .
159+
160+
# Load dashboards from current directory
161+
./grafana.py load .
162+
163+
# Remove dashboards and folders from Grafana
164+
./grafana.py clean .
27165
```
28166

167+
### Makefile Shortcuts
168+
169+
From the Pigsty root directory:
29170

30171
```bash
31-
./grafana.py init # init pigsty baseline dashboards
32-
./grafana.py dump . # dump pigsty dashboards to current dir
33-
./grafana.py load . # load pigsty dashboards from current dir
34-
./grafana.py clean . # remove target grafana dashboards & folders
35-
```
172+
make di # dashboard init - Initialize dashboards
173+
make dd # dashboard dump - Export dashboards to files
174+
make dc # dashboard clean - Remove dashboards from Grafana
175+
```
176+
177+
178+
## Data Sources
179+
180+
Dashboards use the following Grafana data sources:
181+
182+
| UID | Name | Type | Description |
183+
|-----------------|------------|-----------------|-------------------------------|
184+
| `ds-prometheus` | Prometheus | VictoriaMetrics | Time-series metrics (default) |
185+
| `ds-meta` | Meta | PostgreSQL | CMDB metadata queries |
186+
| `ds-vlogs` | Loki | VictoriaLogs | Log queries |
187+
188+
189+
## Customization
190+
191+
To customize dashboards:
192+
193+
1. Export existing dashboards: `./grafana.py dump .`
194+
2. Edit the JSON files as needed
195+
3. Reload dashboards: `./grafana.py load .`
196+
197+
Dashboard JSON files follow the standard Grafana dashboard format and can be edited using:
198+
- Grafana UI (export after editing)
199+
- Direct JSON editing
200+
- Grafana dashboard provisioning
201+
202+
203+
## References
204+
205+
- [Pigsty Monitoring Documentation](https://pigsty.io/docs/infra/grafana/)
206+
- [Grafana Dashboard JSON Model](https://grafana.com/docs/grafana/latest/dashboards/json-model/)
207+
- [VictoriaMetrics Documentation](https://docs.victoriametrics.com/)

‎infra-rm.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@
77
# Mtime : 2025-12-11
88
# Path : infra-rm.yml
99
# Docs : https://pigsty.io/docs/infra/playbook
10-
# License : AGPLv3 @ https://pigsty.io/docs/about/license/
10+
# License1 : Apache-2.0 @ https://pigsty.io/docs/about/license/
11+
# License2 : AGPLv3 for Grafana related stuff
1112
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
1213
#==============================================================#
1314

‎infra.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@
77
# Mtime : 2025-12-25
88
# Path : infra.yml
99
# Docs : https://pigsty.io/docs/infra/playbook
10-
# License : AGPLv3 @ https://pigsty.io/docs/about/license/
10+
# License1 : Apache-2.0 @ https://pigsty.io/docs/about/license/
11+
# License2 : AGPLv3 for Grafana related stuff
1112
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
1213
#==============================================================#
1314

‎roles/cache/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -212,15 +212,15 @@ ls -la /www/pigsty/
212212

213213
```bash
214214
# On internet-connected build machine:
215-
1. Install Pigsty normally: ./bootstrap && ./configure && ./install.yml
215+
1. Install Pigsty normally: ./bootstrap && ./configure && ./deploy.yml
216216
2. Create offline package: ./cache.yml -l infra
217217

218218
# Transfer tarball to air-gapped environment
219219

220220
# On air-gapped target machine:
221221
3. Bootstrap with package: ./bootstrap -p pigsty-pkg-*.tgz
222222
4. Configure: ./configure
223-
5. Install: ./install.yml
223+
5. Install: ./deploy.yml
224224
```
225225

226226

‎roles/infra/meta/main.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ galaxy_info:
44
description: init infra module on pigsty managed nodes
55
min_ansible_version: "2.9"
66
author: 'Ruohang Feng / @Vonng / rh@vonng.com'
7-
license: AGPLv3
7+
license: Apache-2.0 and AGPLv3.0 for Grafana
88
platforms:
99
- name: EL
1010
versions: [ 10, 9, 8 ]

‎roles/infra/tasks/grafana.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,12 @@
11
---
2+
#==============================================================#
3+
# File : grafana.yml
4+
# Desc : init grafana on infra nodes
5+
# Docs : https://pigsty.io/docs/infra/
6+
# License : AGPLv3 @ https://pigsty.io/docs/about/license/
7+
# Copyright : 2018-2026 Ruohang Feng / Vonng (rh@vonng.com)
8+
#==============================================================#
9+
210
#--------------------------------------------------------------#
311
# Install Grafana [grafana_install]
412
#--------------------------------------------------------------#

0 commit comments

Comments
 (0)