Skip to content

Commit c3ee266

Browse files
vikin91vikin91
committed
Improve documentation
1 parent 4e6bff5 commit c3ee266

File tree

11 files changed

+675
-59
lines changed

11 files changed

+675
-59
lines changed

‎README.md‎

Lines changed: 11 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -77,66 +77,13 @@ make build
7777
./bin/metrics-analyzer list-rules
7878
```
7979

80-
## TUI Keyboard Shortcuts
81-
82-
| Key | Action |
83-
|-----|--------|
84-
| `↑`/`k`, `↓`/`j` | Navigate up/down |
85-
| `Enter`/`→` | View details |
86-
| `←`/`Esc` | Go back |
87-
| `g`/`Home` | Go to top |
88-
| `G`/`End` | Go to bottom |
89-
| `PgUp`/`PgDn` | Page up/down |
90-
| `/` | Search/filter |
91-
| `1-4` | Filter by status (All/Red/Yellow/Green) |
92-
| `?` | Toggle help |
93-
| `q` | Quit |
94-
95-
## Project Structure
80+
## More Documentation
9681

97-
```
98-
sensor-metrics-analyzer-go/
99-
├── cmd/metrics-analyzer/ # CLI entry point
100-
├── internal/
101-
│ ├── parser/ # Prometheus metrics parser
102-
│ ├── rules/ # TOML rule loader and validator
103-
│ ├── loadlevel/ # Load level detection engine
104-
│ ├── evaluator/ # Rule evaluation logic
105-
│ ├── reporter/ # Report generation (markdown/console)
106-
│ └── tui/ # Interactive terminal UI (Bubble Tea)
107-
├── automated-rules/ # TOML rule definitions
108-
└── templates/ # Report templates
109-
```
110-
111-
## Testing
112-
113-
```bash
114-
# Unit tests
115-
make test
116-
117-
# Integration test (compare with Python output)
118-
python3 analyze_metrics_full.py metrics.txt > /tmp/python-output.txt
119-
./bin/metrics-analyzer analyze --format markdown --output /tmp/go-report.md metrics.txt
120-
go run testdata/compare_outputs.go /tmp/python-output.txt /tmp/go-report.md
121-
```
122-
123-
## Recording Demos
124-
125-
This project uses [VHS](https://github.com/charmbracelet/vhs) for recording terminal demos.
126-
See the [`demo/`](demo/) folder for scripts and instructions.
127-
128-
```bash
129-
# Install VHS
130-
brew install vhs
131-
132-
# Record demos
133-
cd demo
134-
vhs demo.tape # Full TUI demo
135-
vhs demo-cli.tape # CLI mode demo
136-
137-
# Publish to charm servers
138-
vhs publish demo.gif
139-
```
82+
- [TUI Keyboard Shortcuts](docs/usage/tui-shortcuts.md)
83+
- [Project Structure](docs/architecture/project-structure.md)
84+
- [Testing](docs/dev/testing.md)
85+
- [Recording Demos](docs/dev/recording-demos.md)
86+
- [Releasing a New Version](docs/dev/releasing.md)
14087

14188
## Dependencies
14289

@@ -146,6 +93,11 @@ Built with:
14693
- [Bubbles](https://github.com/charmbracelet/bubbles) - TUI components
14794
- [go-pretty](https://github.com/jedib0t/go-pretty) - Table formatting
14895

96+
## Additional Docs
97+
98+
- [Documentation Home](docs/README.md)
99+
- [Rules Wiki](docs/rules/README.md)
100+
149101
## License
150102

151103
Apache 2.0 - See [LICENSE](LICENSE) for details.

‎docs/README.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Documentation
2+
3+
This folder contains topic-focused docs for rule authoring and operations.
4+
5+
## Rule Authoring Wiki
6+
7+
- [Rules Home](./rules/README.md)
8+
- [Rule Types and Examples](./rules/rule-types.md)
9+
- [Advanced Rule Features](./rules/advanced-features.md)
10+
- [Load Detection Rules](./rules/load-detection.md)
11+
12+
## Usage
13+
14+
- [TUI Keyboard Shortcuts](./usage/tui-shortcuts.md)
15+
16+
## Developer Guides
17+
18+
- [Testing](./dev/testing.md)
19+
- [Releasing a New Version](./dev/releasing.md)
20+
- [Recording Demos](./dev/recording-demos.md)
21+
22+
## Architecture
23+
24+
- [Project Structure](./architecture/project-structure.md)
25+

‎docs/architecture/project-structure.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Project Structure
2+
3+
```text
4+
sensor-metrics-analyzer-go/
5+
├── cmd/metrics-analyzer/ # CLI entry point
6+
├── internal/
7+
│ ├── parser/ # Prometheus metrics parser
8+
│ ├── rules/ # TOML rule loader and validator
9+
│ ├── loadlevel/ # Load level detection engine
10+
│ ├── evaluator/ # Rule evaluation logic
11+
│ ├── reporter/ # Report generation (markdown/console)
12+
│ └── tui/ # Interactive terminal UI (Bubble Tea)
13+
├── automated-rules/ # TOML rule definitions
14+
└── templates/ # Report templates
15+
```
16+

‎docs/dev/recording-demos.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Recording Demos
2+
3+
This project uses [VHS](https://github.com/charmbracelet/vhs) for recording terminal demos.
4+
See the [`demo/`](../../demo/) folder for scripts and instructions.
5+
6+
```bash
7+
# Install VHS
8+
brew install vhs
9+
10+
# Record demos
11+
cd demo
12+
vhs demo.tape # Full TUI demo
13+
vhs demo-cli.tape # CLI mode demo
14+
15+
# Publish to charm servers
16+
vhs publish demo.gif
17+
```
18+

‎docs/dev/releasing.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Releasing a New Version
2+
3+
Use this flow to clean old release artifacts, build fresh binaries (linux/amd64 and darwin/arm64), generate checksums, and publish a GitHub release with assets.
4+
5+
```bash
6+
# 1) set the new version in VERSION
7+
echo "0.0.5" > VERSION
8+
9+
# 2) build release artifacts and checksums
10+
make release
11+
12+
# 3) verify artifacts
13+
ls -lh dist/
14+
cat dist/checksums.txt
15+
16+
# 4) commit and push the version bump (if needed)
17+
git add VERSION
18+
git commit -m "Release v0.0.5"
19+
git push
20+
21+
# 5) create and push tag
22+
git tag -a v0.0.5 -m "v0.0.5"
23+
git push origin v0.0.5
24+
25+
# 6) create GitHub release and upload artifacts
26+
gh release create v0.0.5 \
27+
--title "v0.0.5" \
28+
--notes "Release v0.0.5" \
29+
dist/metrics-analyzer-0.0.5-linux-amd64 \
30+
dist/web-server-0.0.5-linux-amd64 \
31+
dist/metrics-analyzer-0.0.5-darwin-arm64 \
32+
dist/web-server-0.0.5-darwin-arm64 \
33+
dist/checksums.txt
34+
```
35+

‎docs/dev/testing.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Testing
2+
3+
```bash
4+
# Unit tests
5+
make test
6+
7+
# Integration test (deprecated)
8+
# This compares the results with the output of the Python script,
9+
# which was historically the initial form of this entire project.
10+
python3 analyze_metrics_full.py metrics.txt > /tmp/python-output.txt
11+
./bin/metrics-analyzer analyze --format markdown --output /tmp/go-report.md metrics.txt
12+
go run testdata/compare_outputs.go /tmp/python-output.txt /tmp/go-report.md
13+
```
14+

‎docs/rules/README.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Rules Wiki
2+
3+
This project evaluates Prometheus metrics using declarative TOML rules from `automated-rules/`.
4+
5+
Use this wiki to understand what rule types exist and how to write new rules.
6+
7+
## Start Here
8+
9+
- [Rule Types and Examples](./rule-types.md)
10+
- [Advanced Rule Features](./advanced-features.md)
11+
- [Load Detection Rules](./load-detection.md)
12+
13+
## Minimal Rule Skeleton
14+
15+
```toml
16+
rule_type = "gauge_threshold"
17+
metric_name = "my_metric_name"
18+
display_name = "my_metric_name"
19+
description = "What this metric means"
20+
21+
[thresholds]
22+
low = 100
23+
high = 1000
24+
higher_is_worse = true
25+
26+
[messages]
27+
green = "{value:.0f} healthy"
28+
yellow = "{value:.0f} elevated"
29+
red = "{value:.0f} critical"
30+
```
31+
32+
## Validate Rules
33+
34+
```bash
35+
# Build CLI
36+
make build
37+
38+
# Validate all rules
39+
./bin/metrics-analyzer validate ./automated-rules
40+
```
41+
42+
## Quick Test With Metrics
43+
44+
```bash
45+
./bin/metrics-analyzer analyze --rules ./automated-rules testdata/fixtures/sample_metrics.txt
46+
```
47+

0 commit comments

Comments
 (0)