PromQL Insights

A powerful PromQL query analyzer and visualization tool with real-time monitoring data integration.

Features

PromQL Parser & Formatter: Parse and format PromQL queries with syntax highlighting
AST Visualization: Interactive abstract syntax tree with expand/collapse functionality
Dependency Analysis: Extract metrics, labels, functions, and aggregations from queries
Static Analysis: Detect potential issues and provide optimization suggestions
Query Execution: Execute PromQL queries against Prometheus with real-time results
Data Visualization: Interactive charts and table views for query results
Mock Data Generation: Built-in mock data generator for testing

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                     Frontend (Vue 3)                          │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  Monaco Editor  │  AST Tree  │  Charts  │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                            ↓ HTTP API
┌─────────────────────────────────────────────────────────────────────┐
│                  Backend (Go + Hertz)                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  Parser  │  Analyzer  │  Query Proxy  │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘
                            ↓ HTTP API
┌─────────────────────────────────────────────────────────────────────┐
│              Prometheus + Pushgateway (Docker)               │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  Time Series DB  │  Query Engine  │  Pushgateway │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

Tech Stack

Frontend

Framework: Vue 3 (Composition API)
Build Tool: Vite
Language: TypeScript
Editor: Monaco Editor
Charts: ECharts
State Management: Pinia
Router: Vue Router

Backend

Framework: Cloudwego (Hertz)
Language: Go 1.21+
PromQL Parser: Prometheus official parser
JSON Library: Sonic

Monitoring

Time Series DB: Prometheus v2.48.0
Metrics Gateway: Pushgateway v1.6.2
Deployment: Docker

Quick Start

Prerequisites

Go 1.21 or higher
Node.js 16 or higher
npm 8 or higher
Docker (optional, for Prometheus deployment)

One-Click Build & Install

Run the build script to build and install all components:

chmod +x build.sh
./build.sh

This will:

Check all dependencies (Go, Node.js, npm, Docker)
Build the backend binary
Build the frontend distribution
Start Prometheus and Pushgateway containers
Display service URLs and usage instructions

Manual Installation

Backend

cd backend
go mod download
go build -o bin/api cmd/api/main.go
./bin/api

Backend will be available at http://localhost:8888

Frontend

cd frontend
npm install
npm run dev

Frontend will be available at http://localhost:3000

Prometheus (Optional)

# Start Prometheus
docker run -d --name prometheus -p 9090:9090 \
  -v $(pwd)/prometheus.yml:/etc/prometheus/prometheus.yml \
  prom/prometheus:v2.48.0

# Start Pushgateway
docker run -d --name pushgateway -p 9091:9091 \
  prom/pushgateway:v1.6.2

Usage

1. Start Services

# Start backend
cd backend && ./bin/api

# Start frontend (dev mode)
cd frontend && npm run dev

# Start frontend (production)
cd frontend && npm run preview

# Push metrics (optional)
python3 push_metrics.py

2. Access Services

Service	URL	Description
Frontend	http://localhost:3000	PromQL Workbench
Backend API	http://localhost:8888	REST API
Prometheus	http://localhost:9090	Monitoring Data
Pushgateway	http://localhost:9091	Metrics Gateway

3. Use the Application

PromQL Editor

Enter your PromQL query in the Monaco Editor
Click "Format" to format the query
Click "Parse" to analyze the query

AST Visualization

View the abstract syntax tree structure
Click on nodes to expand/collapse
Click on nodes to highlight corresponding code

Dependency Analysis

View extracted metrics, labels, functions
See aggregations and matchers
Understand query dependencies

Static Analysis

Review detected issues (error/warn/info)
See optimization suggestions
Improve query performance

Query Execution

Set time range (start, end, step)
Click "Run" to execute the query
View results in chart or table format
Filter series by labels

API Documentation

POST /api/promql/parse

Parse and analyze a PromQL query.

Request:

{
  "query": "sum(rate(http_requests_total[5m])) by (status)",
  "dialect": "prometheus",
  "options": {
    "format": true,
    "analyze": true
  }
}

Response:

{
  "formatted": "sum by (status) (rate(http_requests_total[5m]))",
  "ast": {
    "type": "AggregateExpr",
    "op": "sum",
    "by": ["status"],
    "expr": { ... }
  },
  "dependencies": {
    "metrics": ["http_requests_total"],
    "labels": ["status"],
    "functions": ["rate"],
    "aggregations": ["sum"]
  },
  "issues": [
    {
      "level": "warn",
      "code": "LARGE_RANGE",
      "message": "Range selector with duration 5m0s is very large"
    }
  ]
}

POST /api/query/range

Execute a PromQL range query.

Request:

{
  "query": "http_requests_total",
  "start": 1700000000,
  "end": 1700003600,
  "step": 15,
  "datasource": "default"
}

Response:

{
  "status": "success",
  "data": {
    "resultType": "matrix",
    "result": [
      {
        "metric": {
          "__name__": "http_requests_total",
          "job": "api",
          "status": "200"
        },
        "values": [
          [1700000000, "500"],
          [1700000015, "520"],
          ...
        ]
      }
    ]
  }
}

Project Structure

insights/
├── backend/                          # Go Backend
│   ├── cmd/
│   │   └── api/
│   │       └── main.go            # Entry point
│   ├── internal/
│   │   ├── handler/               # HTTP handlers
│   │   │   └── promql.go       # API endpoints
│   │   ├── middleware/            # Middleware (CORS)
│   │   ├── dto/                  # Data transfer objects
│   │   └── promql/               # PromQL processing
│   │       ├── parser/            # Parser module
│   │       └── analyzer/          # Analyzer module
│   ├── go.mod                    # Go module definition
│   └── go.sum                    # Go dependencies
├── frontend/                         # Vue Frontend
│   ├── src/
│   │   ├── components/            # Vue components
│   │   │   ├── ASTTree.vue      # AST visualization
│   │   │   ├── ASTNode.vue      # Recursive AST node
│   │   │   ├── Dependencies.vue # Dependencies panel
│   │   │   ├── Issues.vue       # Issues panel
│   │   │   └── QueryResults.vue # Query results
│   │   ├── views/                 # Page views
│   │   │   └── PromQLWorkbench.vue
│   │   ├── router/                # Vue Router
│   │   ├── types/                 # TypeScript types
│   │   └── main.ts               # Entry point
│   ├── package.json
│   ├── vite.config.ts
│   └── tsconfig.json
├── prometheus.yml                    # Prometheus config
├── push_metrics.py                  # Metrics push script
├── build.sh                        # Build & install script
└── README.md                       # This file

Development

Backend Development

cd backend
go run cmd/api/main.go

Frontend Development

cd frontend
npm run dev

Running Tests

# Backend tests
cd backend
go test ./...

# Frontend tests
cd frontend
npm run test

Code Quality

# Backend linting
cd backend
go fmt ./...
go vet ./...

# Frontend linting
cd frontend
npm run lint
npm run type-check

Deployment

Production Build

# Build backend
cd backend
go build -ldflags="-s -w" -o bin/api cmd/api/main.go

# Build frontend
cd frontend
npm run build

Docker Deployment

# Build and start all services
./build.sh

# Or use Docker Compose
docker-compose -f docker-compose.prometheus.yml up -d

Environment Variables

Create a .env file in the project root:

# Backend
BACKEND_PORT=8888
BACKEND_HOST=0.0.0.0

# Frontend
FRONTEND_PORT=3000
VITE_API_BASE_URL=http://localhost:8888

# Prometheus
PROMETHEUS_PORT=9090
PUSHGATEWAY_PORT=9091

Monitoring

Pushing Metrics

Use the provided Python script to push mock metrics:

python3 push_metrics.py

This will push HTTP request metrics every 10 seconds with various labels:

Services: user-service, order-service, payment-service
Methods: GET, POST, PUT, DELETE
Status codes: 200, 201, 400, 500

Prometheus Queries

Access the Prometheus UI to query metrics:

# Query all HTTP requests
http_requests_total

# Query by service
http_requests_total{service="user-service"}

# Query by status
http_requests_total{status="200"}

# Calculate rate
rate(http_requests_total[5m])

# Calculate increase
increase(http_requests_total[1h])

# Group by status
sum by (status) (http_requests_total)

Troubleshooting

Backend won't start

# Check if port is in use
lsof -ti:8888

# Kill process using port
kill -9 <PID>

# Check logs
./bin/api

Frontend won't start

# Clear cache and reinstall
cd frontend
rm -rf node_modules package-lock.json
npm install

# Check port
lsof -ti:3000

Prometheus can't connect to Pushgateway

# Check container status
docker ps

# Check container logs
docker logs prometheus
docker logs pushgateway

# Check network
docker network inspect insights_monitoring

# Restart containers
docker restart prometheus pushgateway

Build errors

# Clean Go cache
cd backend
go clean -cache

# Update dependencies
go mod tidy

# Rebuild
go build -o bin/api cmd/api/main.go

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - see LICENSE file for details

Acknowledgments

Prometheus - Time series database
Cloudwego - Go HTTP framework
Vue.js - Progressive JavaScript framework
Monaco Editor - Code editor
ECharts - Visualization library

Contact

Project Name: PromQL Insights
Issues: GitHub Issues
Discussions: GitHub Discussions

Made with ❤️ by the PromQL Insights Team

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
backend		backend
frontend		frontend
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
DEVELOPMENT.md		DEVELOPMENT.md
Makefile		Makefile
PROJECT_SUMMARY.md		PROJECT_SUMMARY.md
README.md		README.md
STRUCTURE.md		STRUCTURE.md
build.sh		build.sh
docker-compose.prometheus.yml		docker-compose.prometheus.yml
docker-compose.yml		docker-compose.yml
prometheus.yml		prometheus.yml
push_metrics.py		push_metrics.py

yi-nology/promQLInsights

Folders and files

Latest commit

History

Repository files navigation

PromQL Insights

Features

Architecture

Tech Stack

Frontend

Backend

Monitoring

Quick Start

Prerequisites

One-Click Build & Install

Manual Installation

Backend

Frontend

Prometheus (Optional)

Usage

1. Start Services

2. Access Services

3. Use the Application

PromQL Editor

AST Visualization

Dependency Analysis

Static Analysis

Query Execution

API Documentation

POST /api/promql/parse

POST /api/query/range

Project Structure

Development

Backend Development

Frontend Development

Running Tests

Code Quality

Deployment

Production Build

Docker Deployment

Environment Variables

Monitoring

Pushing Metrics

Prometheus Queries

Troubleshooting

Backend won't start

Frontend won't start

Prometheus can't connect to Pushgateway

Build errors

Contributing

License

Acknowledgments

Contact

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages