Skip to content

Commit 1967a3d

Browse files
dmitriimaksimovdevelopclaude
dmitriimaksimovdevelop
and
claude
committed
docs: add Quick Start guide (EN + RU)
2-minute guide: install → run → read → fix → verify Includes CLI reference, collection profiles, and "what's next" table. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 07525f4 commit 1967a3d

2 files changed

Lines changed: 233 additions & 0 deletions

File tree

‎doc/en/00-quickstart.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
# Quick Start
2+
3+
From zero to diagnosis in 2 minutes.
4+
5+
## 1. Install
6+
7+
```bash
8+
# One-liner (Linux amd64/arm64)
9+
curl -sSL https://melisai.dev/install | sh
10+
11+
# Or build from source
12+
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o melisai ./cmd/melisai/
13+
sudo mv melisai /usr/local/bin/
14+
```
15+
16+
## 2. Run Your First Scan
17+
18+
```bash
19+
# Quick health check (10 seconds, no BCC tools needed)
20+
sudo melisai collect --profile quick -o report.json
21+
```
22+
23+
You'll see:
24+
25+
```
26+
melisai v0.4.1 | profile=quick | duration=10s
27+
28+
Tier 1 (procfs) ████████████████████████████████████████ 8/8 2.1s
29+
Tier 2 (BCC) ████████████████████████████████████████ 4/4 10.3s
30+
31+
Health Score: 68 / 100 ⚠️
32+
Anomalies: cpu_utilization CRITICAL (98.7%)
33+
load_average WARNING (3.2x CPUs)
34+
Recommendations: 2
35+
36+
Report saved to report.json
37+
```
38+
39+
## 3. Read the Results
40+
41+
```bash
42+
# Health score (0-100)
43+
jq '.summary.health_score' report.json
44+
45+
# What's wrong?
46+
jq '.summary.anomalies[]' report.json
47+
48+
# How to fix it
49+
jq '.summary.recommendations[] | {type, title, commands}' report.json
50+
```
51+
52+
## 4. Apply Fixes
53+
54+
Recommendations include copy-paste commands:
55+
56+
```bash
57+
# Example: melisai recommends enabling BBR
58+
sysctl -w net.core.default_qdisc=fq
59+
sysctl -w net.ipv4.tcp_congestion_control=bbr
60+
```
61+
62+
## 5. Verify the Fix
63+
64+
```bash
65+
# Run again and compare
66+
sudo melisai collect --profile quick -o after.json
67+
melisai diff report.json after.json
68+
```
69+
70+
The diff shows what improved, what regressed, and health score delta.
71+
72+
## What's Next?
73+
74+
| Goal | Command |
75+
|------|---------|
76+
| Full analysis with all 67 BCC tools | `sudo melisai collect --profile standard -o report.json` |
77+
| Deep dive (stacks, memleak, biotop) | `sudo melisai collect --profile deep -o report.json` |
78+
| Focus on network only | `sudo melisai collect --profile standard --focus network -o net.json` |
79+
| Profile a specific process | `sudo melisai collect --profile standard --pid 12345 -o app.json` |
80+
| Profile a container | `sudo melisai collect --profile standard --cgroup /sys/fs/cgroup/system.slice/nginx.service -o cg.json` |
81+
| Install BCC tools (first time) | `sudo melisai install` |
82+
| Use with Claude/Cursor (MCP) | `melisai mcp` → [MCP setup guide](13-ai-integration.md) |
83+
| Check system capabilities | `melisai capabilities` |
84+
85+
## Collection Profiles
86+
87+
| Profile | Duration | What runs | Best for |
88+
|---------|----------|-----------|----------|
89+
| **quick** | 10s | Tier 1 + 4 essential BCC tools | Health checks, CI gates |
90+
| **standard** | 30s | All Tier 1 + all 67 BCC tools | Regular diagnostics |
91+
| **deep** | 60s | Everything + memleak, biostacks, wakeuptime | Root cause analysis |
92+
93+
## CLI Reference
94+
95+
```
96+
melisai collect Collect metrics and produce JSON report
97+
--profile quick|standard|deep (default: standard)
98+
--focus cpu,memory,disk,network,stacks (comma-separated)
99+
--pid Filter to specific PID
100+
--cgroup Filter to cgroup path
101+
--duration Override profile duration (e.g., 15s, 1m)
102+
--ai-prompt Include AI analysis prompt in output
103+
--output, -o Output file (- for stdout)
104+
--quiet, -q Suppress progress output
105+
--verbose, -v Debug logging
106+
107+
melisai diff Compare two reports
108+
<baseline.json> <current.json>
109+
--output, -o Output diff file
110+
111+
melisai install Install BCC tools and dependencies
112+
--dry-run Show what would be installed
113+
114+
melisai mcp Start MCP server (stdio JSON-RPC)
115+
116+
melisai capabilities Show available tools and kernel features
117+
```
118+
119+
---
120+
121+
*Next: [Introduction — How melisai Works](00-introduction.md)*

‎doc/ru/00-quickstart.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
# Быстрый старт
2+
3+
От нуля до диагноза за 2 минуты.
4+
5+
## 1. Установка
6+
7+
```bash
8+
# Один команда (Linux amd64/arm64)
9+
curl -sSL https://melisai.dev/install | sh
10+
11+
# Или сборка из исходников
12+
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -o melisai ./cmd/melisai/
13+
sudo mv melisai /usr/local/bin/
14+
```
15+
16+
## 2. Первый запуск
17+
18+
```bash
19+
# Быстрая проверка (10 секунд, BCC tools не обязательны)
20+
sudo melisai collect --profile quick -o report.json
21+
```
22+
23+
Вы увидите:
24+
25+
```
26+
melisai v0.4.1 | profile=quick | duration=10s
27+
28+
Tier 1 (procfs) ████████████████████████████████████████ 8/8 2.1s
29+
Tier 2 (BCC) ████████████████████████████████████████ 4/4 10.3s
30+
31+
Health Score: 68 / 100 ⚠️
32+
Anomalies: cpu_utilization CRITICAL (98.7%)
33+
load_average WARNING (3.2x CPUs)
34+
Recommendations: 2
35+
36+
Report saved to report.json
37+
```
38+
39+
## 3. Чтение результатов
40+
41+
```bash
42+
# Оценка здоровья (0-100)
43+
jq '.summary.health_score' report.json
44+
45+
# Что не так?
46+
jq '.summary.anomalies[]' report.json
47+
48+
# Как починить
49+
jq '.summary.recommendations[] | {type, title, commands}' report.json
50+
```
51+
52+
## 4. Применение исправлений
53+
54+
Рекомендации содержат готовые команды:
55+
56+
```bash
57+
# Пример: melisai рекомендует включить BBR
58+
sysctl -w net.core.default_qdisc=fq
59+
sysctl -w net.ipv4.tcp_congestion_control=bbr
60+
```
61+
62+
## 5. Проверка результата
63+
64+
```bash
65+
# Запустить снова и сравнить
66+
sudo melisai collect --profile quick -o after.json
67+
melisai diff report.json after.json
68+
```
69+
70+
Diff покажет что улучшилось, что ухудшилось, и дельту health score.
71+
72+
## Что дальше?
73+
74+
| Цель | Команда |
75+
|------|---------|
76+
| Полный анализ (все 67 BCC tools) | `sudo melisai collect --profile standard -o report.json` |
77+
| Глубокий анализ (стеки, memleak) | `sudo melisai collect --profile deep -o report.json` |
78+
| Только сеть | `sudo melisai collect --profile standard --focus network -o net.json` |
79+
| Конкретный процесс | `sudo melisai collect --profile standard --pid 12345 -o app.json` |
80+
| Контейнер | `sudo melisai collect --profile standard --cgroup /sys/fs/cgroup/.../nginx.service -o cg.json` |
81+
| Установить BCC tools | `sudo melisai install` |
82+
| Использовать с Claude/Cursor | `melisai mcp` → [гайд по MCP](13-ai-integration.md) |
83+
84+
## Профили сбора
85+
86+
| Профиль | Время | Что запускается | Для чего |
87+
|---------|-------|-----------------|----------|
88+
| **quick** | 10с | Tier 1 + 4 основных BCC | Проверка здоровья, CI |
89+
| **standard** | 30с | Все Tier 1 + все 67 BCC | Обычная диагностика |
90+
| **deep** | 60с | Всё + memleak, biostacks | Поиск корневой причины |
91+
92+
## Справка по CLI
93+
94+
```
95+
melisai collect Сбор метрик и генерация JSON-отчёта
96+
--profile quick|standard|deep (по умолчанию: standard)
97+
--focus cpu,memory,disk,network,stacks
98+
--pid Фильтр по PID
99+
--cgroup Фильтр по cgroup
100+
--duration Переопределить длительность (например, 15s, 1m)
101+
--ai-prompt Включить AI-промпт в отчёт
102+
--output, -o Файл вывода (- для stdout)
103+
104+
melisai diff Сравнение двух отчётов
105+
melisai install Установка BCC tools
106+
melisai mcp MCP сервер (stdio JSON-RPC)
107+
melisai capabilities Доступные инструменты и возможности ядра
108+
```
109+
110+
---
111+
112+
*Далее: [Введение — Как работает melisai](00-introduction.md)*

0 commit comments

Comments
 (0)