Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 9ad6e3f

Browse files
author
Dementii Priadko
committed
Merge branch 'polish-readme-and-rules-submodule' into 'main'
Polish README and add rules submodule See merge request postgres-ai/postgres_ai!44
2 parents 8d6ba11 + 1a7472d commit 9ad6e3f

File tree

5 files changed

+103
-21
lines changed

5 files changed

+103
-21
lines changed

‎.cursor‎

Submodule .cursor added at 80f2889

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,4 +34,5 @@ config/pgwatch-prometheus/sources.yml
3434

3535
# Volume data (if accidentally committed)
3636
data/
37-
volumes/
37+
volumes/
38+
.pgwatch-config

‎.gitmodules‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[submodule ".cursor"]
2+
path = .cursor
3+
url = https://gitlab.com/postgres-ai/rules.git

‎README.md‎

Lines changed: 97 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,67 @@
1-
# Postgres AI
1+
# postgres_ai monitoring
22

3-
A complete PostgreSQL monitoring solution with automated performance analysis and reporting.
3+
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
4+
[![GitLab](https://img.shields.io/badge/GitLab-postgres--ai%2Fpostgres__ai-orange?logo=gitlab)](https://gitlab.com/postgres-ai/postgres_ai)
5+
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-14%2B-blue?logo=postgresql)](https://www.postgresql.org/)
46

5-
## Demo
7+
**Expert-level Postgres monitoring tool designed for humans and AI systems**
68

7-
https://demo.postgres.ai (`demo` / `demo`)
9+
Built for senior DBAs, SREs, and AI systems who need rapid root cause analysis and deep performance insights. This isn't a tool for beginners — it's designed for Postgres experts who need to understand complex performance issues in minutes, not hours.
10+
11+
**Part of [Self-Driving Postgres](https://postgres.ai/blog/20250725-self-driving-postgres)** - postgres_ai monitoring is a foundational component of PostgresAI's open-source Self-Driving Postgres (SDP) initiative, providing the advanced monitoring and intelligent root cause analysis capabilities essential for achieving higher levels of database automation.
12+
13+
![postgres_ai monitoring](assets/postgres_ai_pic.png)
14+
15+
## 🎯 Key highlights
16+
17+
- **Top-down troubleshooting methodology**: Follows the Four Golden Signals approach (Latency, Traffic, Errors, Saturation)
18+
- **Expert-focused design**: Assumes deep Postgres knowledge and performance troubleshooting experience
19+
- **Dual-purpose architecture**: Built for both human experts and AI systems requiring structured performance data
20+
- **Comprehensive query analysis**: Complete `pg_stat_statements` metrics with historical trends and plan variations
21+
- **Active Session History**: Postgres's answer to Oracle ASH and AWS RDS Performance Insights
22+
- **Hybrid storage**: Prometheus for metrics, Postgres for query texts — best of both worlds
23+
24+
> 📖 **Read more**: [postgres_ai monitoring v0.7 announcement](https://postgres.ai/blog/20250722-postgres-ai-v0-7-expert-level-postgresql-monitoring) - detailed technical overview and architecture decisions.
25+
26+
## ⚠️ Important notice
27+
28+
**This tool is NOT for beginners.** It requires extensive Postgres knowledge and assumes familiarity with:
29+
- Advanced Postgres internals and performance concepts
30+
- Query plan analysis and optimization techniques
31+
- Wait event analysis and system-level troubleshooting
32+
- Production database operations and incident response
33+
34+
If you're new to Postgres, consider starting with simpler monitoring solutions before using postgres_ai.
35+
36+
## 🚀 Live demo
37+
38+
Experience the full monitoring solution: **https://demo.postgres.ai** (login: `demo` / password: `demo`)
39+
40+
## 📊 Five expert dashboards
41+
42+
1. **Troubleshooting dashboard** - Four Golden Signals with immediate incident response insights
43+
2. **Query performance analysis** - Top-N query workload analysis with resource consumption breakdowns
44+
3. **Single query analysis** - Deep dive into individual query performance and plan variations
45+
4. **Wait event analysis** - Active Session History for session-level troubleshooting
46+
5. **Backups and DR** - WAL archiving monitoring with RPO measurements
47+
48+
## 🏗️ Architecture
49+
50+
- **Collection**: pgwatch v3 (by Cybertec) for metrics gathering
51+
- **Storage**: Prometheus for time-series data + Postgres for query texts
52+
- **Visualization**: Grafana with expert-designed dashboards
53+
- **Analysis**: Structured data output for AI system integration
854

955
## 📋 Requirements
1056

1157
**Infrastructure:**
1258
- **Linux machine** with Docker installed (separate from your database server)
1359
- **Docker access** - the user running `postgres_ai` must have Docker permissions
14-
- **Access (network and pg_hba)** to the PostgreSQL database(s) you want to monitor
60+
- **Access (network and pg_hba)** to the Postgres database(s) you want to monitor
1561

1662
**Database:**
17-
- Supports PostgreSQL versions 14-17
18-
- **pg_stat_statements extension must be created** for db used for connection
63+
- Supports Postgres versions 14-17
64+
- **pg_stat_statements extension must be created** for the DB used for connection
1965

2066
## ⚠️ Security Notice
2167

@@ -29,7 +75,7 @@ This monitoring solution exposes several ports that **MUST** be properly firewal
2975
- **Port 59091** (PGWatch Prometheus endpoint) - Metrics collection
3076
- **Port 55000** (Flask API) - Backend API service
3177
- **Port 55432** (Demo DB) - When using `--demo` option
32-
- **Port 55433** (Metrics DB) - PostgreSQL metrics storage
78+
- **Port 55433** (Metrics DB) - Postgres metrics storage
3379

3480
**Configure your firewall to:**
3581
- Block public access to all monitoring ports
@@ -40,9 +86,9 @@ Failure to secure these ports may expose sensitive database information!
4086

4187
## 🚀 Quick start
4288

43-
Create a new DB user in database to be monitored (skip this if you want just to check out `postgres_ai` monitoring with a synthetic `demo` database):
89+
Create a new DB user in the database to be monitored (skip this if you want to just check out `postgres_ai` monitoring with a synthetic `demo` database):
4490
```sql
45-
-- Create a user for Postgres AI monitoring
91+
-- Create a user for postgres_ai monitoring
4692
begin;
4793
create user postgres_ai_mon with password '<password>';
4894

@@ -81,15 +127,15 @@ curl -o postgres_ai https://gitlab.com/postgres-ai/postgres_ai/-/raw/main/postgr
81127
&& chmod +x postgres_ai
82128
```
83129

84-
Now, start it and wait for a few minutes. To obtain Postgres AI access token for your organization visit https://console.postgres.ai (`Your org name → Manage → Access tokens`):
130+
Now, start it and wait for a few minutes. To obtain a PostgresAI access token for your organization, visit https://console.postgres.ai (`Your org name → Manage → Access tokens`):
85131

86132
```bash
87133
# Production setup with your Access token
88134
./postgres_ai quickstart --api-key=your_access_token
89135
```
90136
**Note:** You can also add your database instance in the same command:
91137
```bash
92-
./postgres_ai quickstart --api-key=your_access_token --add-instance="postgresql://user:pass@host:port/db"
138+
./postgres_ai quickstart --api-key=your_access_token --add-instance="postgresql://user:pass@host:port/DB"
93139
```
94140

95141
Or if you want to just check out how it works:
@@ -103,9 +149,9 @@ That's it! Everything is installed, configured, and running.
103149
## 📊 What you get
104150

105151
- **Grafana Dashboards** - Visual monitoring at http://localhost:3000
106-
- **PostgreSQL Monitoring** - PGWatch with comprehensive metrics
152+
- **Postgres Monitoring** - PGWatch with comprehensive metrics
107153
- **Automated Reports** - Daily performance analysis
108-
- **API Integration** - Automatic upload to PostgreSQL AI
154+
- **API Integration** - Automatic upload to PostgresAI
109155
- **Demo Database** - Ready-to-use test environment
110156

111157
## 🎯 Use cases
@@ -120,16 +166,16 @@ Get a complete monitoring setup with demo data in under 2 minutes.
120166
```bash
121167
./postgres_ai quickstart --api-key=your_key
122168
# Then add your databases
123-
./postgres_ai add-instance "postgresql://user:pass@host:port/db"
169+
./postgres_ai add-instance "postgresql://user:pass@host:port/DB"
124170
```
125171

126172
## 🔧 Management commands
127173

128174
```bash
129175
# Instance management
130-
./postgres_ai add-instance "postgresql://user:pass@host:port/db"
176+
./postgres_ai add-instance "postgresql://user:pass@host:port/DB"
131177
./postgres_ai list-instances
132-
./postgres_ai test-instance my-db
178+
./postgres_ai test-instance my-DB
133179

134180
# Service management
135181
./postgres_ai status
@@ -144,7 +190,7 @@ Get a complete monitoring setup with demo data in under 2 minutes.
144190

145191
After running quickstart:
146192

147-
- **🚀 MAIN: Grafana Dashboard**: http://localhost:3000 (demouser/demopwd)
193+
- **🚀 MAIN: Grafana Dashboard**: http://localhost:3000 (login: `monitoring`; password is shown at the end of quickstart)
148194

149195
Technical URLs (for advanced users):
150196
- **Demo DB**: postgresql://postgres:postgres@localhost:55432/target_database
@@ -157,6 +203,37 @@ Technical URLs (for advanced users):
157203
./postgres_ai help
158204
```
159205

160-
## 🔑 Postgres AI access token
161-
Get your key at [Postgres AI](https://postgres.ai) for automated report uploads and advanced analysis.
206+
## 🔑 PostgresAI access token
207+
Get your access token at [PostgresAI](https://postgres.ai) for automated report uploads and advanced analysis.
208+
209+
## 🛣️ Roadmap
210+
211+
- Host stats for on-premise and managed Postgres setups
212+
- `pg_wait_sampling` and `pg_stat_kcache` extension support
213+
- Additional expert dashboards: autovacuum, checkpointer, lock analysis
214+
- Query plan analysis and automated recommendations
215+
- Enhanced AI integration capabilities
216+
217+
## 🤝 Contributing
218+
219+
We welcome contributions from Postgres experts! Please check our [GitLab repository](https://gitlab.com/postgres-ai/postgres_ai) for:
220+
- Code standards and review process
221+
- Dashboard design principles
222+
- Testing requirements for monitoring components
223+
224+
## 📄 License
225+
226+
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
227+
228+
## 🏢 About PostgresAI
229+
230+
postgres_ai monitoring is developed by [PostgresAI](https://postgres.ai), bringing years of Postgres expertise into automated monitoring and analysis tools. We provide enterprise consulting and advanced Postgres solutions for fast-growing companies.
231+
232+
## 📞 Support & community
233+
234+
- 💬 [Get support](https://postgres.ai/contact)
235+
- 📺 [Postgres.TV (YouTube)](https://postgres.tv)
236+
- 🎙️ [Postgres FM Podcast](https://postgres.fm)
237+
- 🐛 [Report issues](https://gitlab.com/postgres-ai/postgres_ai/-/issues)
238+
- 📧 [Enterprise support](https://postgres.ai/consulting)
162239

‎assets/postgres_ai_pic.png‎

101 KB
Loading[フレーム]

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /