Диагностика системы¶

Инструменты и процедуры для сбора диагностической информации о состоянии Р13.Орбита.

Быстрая диагностика¶

Базовый health check¶

#!/bin/bash
# quick-check.sh

echo "=== Р13.Орбита Health Check ==="
echo

echo "1. Container status:"
docker ps | grep orbita || echo "⚠️  Container not running"
echo

echo "2. Health endpoint:"
curl -s http://localhost:8000/health | jq '.' || echo "⚠️  Health endpoint not responding"
echo

echo "3. Resource usage:"
docker stats orbita --no-stream
echo

echo "4. Recent logs:"
docker logs orbita --tail 20
echo

echo "=== Check complete ==="

Сохраните как quick-check.sh, сделайте исполняемым:

chmod +x quick-check.sh
./quick-check.sh

Сбор логов¶

Логи Docker контейнера¶

# Последние 100 строк
docker logs orbita --tail 100

# Логи за последний час
docker logs orbita --since 1h

# Логи в реальном времени
docker logs orbita --follow

# Только ошибки
docker logs orbita 2>&1 | grep -i "error\|exception\|failed"

# Сохранить логи в файл с timestamp
docker logs orbita > "orbita-logs-$(date +%Y%m%d-%H%M%S).txt" 2>&1

Логи зависимых сервисов¶

# ClickHouse
docker logs clickhouse --tail 100

# PostgreSQL
docker logs postgres-metadata --tail 100

# Redis (если используется)
docker logs redis --tail 100

# Все сервисы через Docker Compose
docker-compose logs --tail=100

Логи системы (host)¶

# Linux - системные логи
sudo journalctl -u docker --since "1 hour ago"

# Docker daemon logs
sudo tail -f /var/log/docker.log

# macOS
tail -f ~/Library/Containers/com.docker.docker/Data/log/host/*.log

Проверка конфигурации¶

Проверка переменных окружения¶

# Показать все переменные (ВНИМАНИЕ: содержит секреты!)
docker exec orbita env

# Показать только публичные переменные
docker exec orbita env | grep -v "PASSWORD\|API_KEY\|SECRET"

# Проверить конкретную переменную
docker exec orbita printenv CLICKHOUSE_HOST

# Проверить .env файл на хосте (без паролей)
cat .env | grep -v "PASSWORD\|API_KEY\|SECRET"

Проверка конфигурации доменов¶

# Список доменов
ls -la ~/orbita/domains/

# Проверить синтаксис YAML
docker run --rm -v $(pwd)/domains:/domains python:3.11 \
  python -c "import yaml; yaml.safe_load(open('/domains/ecommerce.yaml'))" \
  && echo "✅ Valid YAML" || echo "❌ Invalid YAML"

# Показать структуру домена
cat ~/orbita/domains/ecommerce.yaml | head -50

Проверка подключений¶

ClickHouse¶

# HTTP порт (8123)
curl http://localhost:8123
# Должен вернуть: Ok.

# Проверить из контейнера Р13.Орбита
docker exec orbita curl http://clickhouse:8123

# Проверить список БД
clickhouse-client --query "SHOW DATABASES"

# Проверить таблицы
clickhouse-client --query "SHOW TABLES FROM ecommerce"

# Тестовый запрос
clickhouse-client --query "SELECT version()"

# Проверить время ответа
time clickhouse-client --query "SELECT count() FROM ecommerce.orders"

PostgreSQL¶

# Проверить что сервис запущен
docker exec postgres-metadata pg_isready -U orbita_user
# Должен вернуть: accepting connections

# Список баз данных
docker exec postgres-metadata psql -U postgres -c "\l"

# Подключиться к БД Р13.Орбита
docker exec -it postgres-metadata psql -U orbita_user -d orbita

# В psql выполнить:
# \dt  -- список таблиц
# \d chats  -- структура таблицы chats
# SELECT COUNT(*) FROM chats;  -- количество чатов

LLM Provider¶

# OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY" \
  | jq '.data[] | .id'

# GigaChat
curl https://gigachat.devices.sberbank.ru/api/v1/models \
  -H "Authorization: Bearer $LLM_API_KEY"

# Ollama (локальный)
curl http://localhost:11434/api/tags | jq '.models'

# Проверить время ответа
time curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"Hello"}],"max_tokens":5}'

Проверка ресурсов¶

Использование ресурсов контейнером¶

# Текущее использование
docker stats orbita --no-stream

# В реальном времени
docker stats orbita

# Подробная информация
docker inspect orbita | jq '.[0].HostConfig | {Memory, MemorySwap, NanoCpus, CpuShares}'

Использование диска¶

# Размер контейнера
docker ps -s | grep orbita

# Размер volumes
docker exec orbita du -sh /app/domains /app/logs

# Размер БД метаданных (PostgreSQL)
docker exec postgres-metadata psql -U orbita_user -d orbita -c "
SELECT pg_size_pretty(pg_database_size('orbita'));
"

# Размер БД метаданных (SQLite)
ls -lh ~/.orbita/metadata.db

# Общее использование Docker
docker system df

Использование памяти¶

# Память на хосте
free -h

# Память внутри контейнера
docker exec orbita cat /proc/meminfo | grep -E "MemTotal|MemFree|MemAvailable"

# Top процессы по памяти
docker exec orbita ps aux --sort=-%mem | head -10

Тестирование функциональности¶

Тест API endpoints¶

#!/bin/bash
# test-api.sh

API_URL="http://localhost:8000"

echo "Testing Р13.Орбита API..."

# Health check
echo -n "Health check: "
curl -s "$API_URL/health" | jq -r '.status' || echo "FAILED"

# Docs (Swagger UI)
echo -n "Swagger UI: "
curl -s -o /dev/null -w "%{http_code}" "$API_URL/docs" | grep 200 && echo "OK" || echo "FAILED"

# List domains
echo -n "List domains: "
curl -s "$API_URL/api/v1/domains" | jq -r '.domains | length' || echo "FAILED"

# Test query
echo -n "Test query: "
curl -s -X POST "$API_URL/api/v1/queries" \
  -H "Content-Type: application/json" \
  -d '{"query": "покажи список доменов"}' \
  | jq -r '.response' | grep -q "домен" && echo "OK" || echo "FAILED"

echo "Tests complete."

Тест подключений¶

#!/bin/bash
# test-connections.sh

echo "Testing connections..."

# ClickHouse
echo -n "ClickHouse: "
docker exec orbita curl -s http://clickhouse:8123 | grep -q "Ok" && echo "✅ OK" || echo "❌ FAILED"

# PostgreSQL
echo -n "PostgreSQL: "
docker exec orbita python -c "
import psycopg2
from os import getenv
try:
    conn = psycopg2.connect(getenv('METADATA_DB_URL'))
    print('✅ OK')
except Exception as e:
    print(f'❌ FAILED: {e}')
"

# LLM Provider
echo -n "LLM Provider: "
docker exec orbita python -c "
from orbita_core.llm.factory import create_llm_provider
from orbita_core.config import get_config
try:
    config = get_config()
    provider = create_llm_provider(config)
    print('✅ OK')
except Exception as e:
    print(f'❌ FAILED: {e}')
"

echo "Connection tests complete."

Диагностический пакет¶

Автоматический сбор всей информации¶

#!/bin/bash
# collect-diagnostics.sh

TIMESTAMP=$(date +%Y%m%d-%H%M%S)
DIAG_DIR="orbita-diagnostics-$TIMESTAMP"

mkdir -p "$DIAG_DIR"

echo "Collecting diagnostics to $DIAG_DIR..."

# 1. System info
echo "Collecting system info..."
uname -a > "$DIAG_DIR/system-info.txt"
docker version >> "$DIAG_DIR/system-info.txt"
docker-compose version >> "$DIAG_DIR/system-info.txt" 2>/dev/null

# 2. Container status
echo "Collecting container status..."
docker ps -a > "$DIAG_DIR/docker-ps.txt"
docker inspect orbita > "$DIAG_DIR/orbita-inspect.json" 2>/dev/null

# 3. Logs
echo "Collecting logs..."
docker logs orbita > "$DIAG_DIR/orbita.log" 2>&1
docker logs clickhouse --tail 500 > "$DIAG_DIR/clickhouse.log" 2>&1
docker logs postgres-metadata --tail 500 > "$DIAG_DIR/postgres.log" 2>&1

# 4. Configuration (без секретов!)
echo "Collecting configuration..."
cat .env | grep -v "PASSWORD\|API_KEY\|SECRET" > "$DIAG_DIR/env-sanitized.txt"
cp -r domains/ "$DIAG_DIR/domains/" 2>/dev/null

# 5. Resource usage
echo "Collecting resource usage..."
docker stats orbita --no-stream > "$DIAG_DIR/docker-stats.txt"
free -h > "$DIAG_DIR/memory.txt"
df -h > "$DIAG_DIR/disk.txt"

# 6. Network
echo "Collecting network info..."
docker network ls > "$DIAG_DIR/networks.txt"
docker network inspect $(docker inspect orbita -f '{{range $key, $value := .NetworkSettings.Networks}}{{$key}}{{end}}') \
  > "$DIAG_DIR/network-details.json" 2>/dev/null

# 7. Connectivity tests
echo "Testing connectivity..."
docker exec orbita curl -s http://clickhouse:8123 > "$DIAG_DIR/clickhouse-test.txt" 2>&1
docker exec orbita curl -s http://localhost:8000/health > "$DIAG_DIR/health-test.json" 2>&1

# Create archive
echo "Creating archive..."
tar -czf "$DIAG_DIR.tar.gz" "$DIAG_DIR/"
rm -rf "$DIAG_DIR"

echo "✅ Diagnostics collected: $DIAG_DIR.tar.gz"
echo ""
echo "Please send this file to support or attach to issue report."
echo "IMPORTANT: Check that the archive doesn't contain sensitive data before sharing!"

Использование:

chmod +x collect-diagnostics.sh
./collect-diagnostics.sh

Анализ логов¶

Поиск ошибок¶

# Все ошибки
docker logs orbita 2>&1 | grep -i "error" | tail -50

# Критические ошибки
docker logs orbita 2>&1 | grep -i "critical\|fatal"

# Исключения Python
docker logs orbita 2>&1 | grep -A 10 "Traceback"

# Проблемы с БД
docker logs orbita 2>&1 | grep -i "database\|connection\|sql"

# Проблемы с LLM
docker logs orbita 2>&1 | grep -i "llm\|openai\|gigachat\|ollama"

Анализ производительности¶

# Время обработки запросов
docker logs orbita 2>&1 | grep "Request took" | tail -20

# Медленные запросы (> 10 секунд)
docker logs orbita 2>&1 | grep "Request took" | awk '{if ($NF+0 > 10000) print}'

# Количество запросов по времени
docker logs orbita 2>&1 | grep "POST /api/v1/queries" | awk '{print $1,$2}' | cut -c 1-13 | uniq -c

# SQL запросы
docker logs orbita 2>&1 | grep "Executing SQL" | tail -10

Статистика использования¶

# Топ пользователей (если auth включен)
docker logs orbita 2>&1 | grep "user_id" | awk '{print $NF}' | sort | uniq -c | sort -nr | head -10

# Топ доменов
docker logs orbita 2>&1 | grep "domain:" | awk '{print $NF}' | sort | uniq -c | sort -nr

# HTTP status codes
docker logs orbita 2>&1 | grep "HTTP" | awk '{print $(NF-1)}' | sort | uniq -c

Мониторинг в реальном времени¶

Live логи с фильтрацией¶

# Только ошибки
docker logs orbita -f 2>&1 | grep --line-buffered -i "error"

# Только SQL запросы
docker logs orbita -f 2>&1 | grep --line-buffered "SELECT\|INSERT\|UPDATE"

# Только API запросы
docker logs orbita -f 2>&1 | grep --line-buffered "POST\|GET\|PUT\|DELETE"

# Цветной вывод для уровней логирования
docker logs orbita -f 2>&1 | \
  grep --line-buffered --color=auto -E "ERROR|WARNING|INFO|DEBUG"

Мониторинг ресурсов¶

# Использование ресурсов каждые 5 секунд
watch -n 5 'docker stats orbita --no-stream'

# Рост использования памяти
while true; do
  docker stats orbita --no-stream | awk '{print $4}'
  sleep 5
done

# Логи + статистика (split screen с tmux)
tmux new-session \; \
  split-window -v \; \
  send-keys 'docker logs orbita -f' C-m \; \
  select-pane -t 0 \; \
  send-keys 'watch -n 2 docker stats orbita --no-stream' C-m

Отладка проблем¶

Интерактивная отладка¶

# Запустить shell в работающем контейнере
docker exec -it orbita /bin/bash

# Внутри контейнера:
# - Проверить процессы
ps aux

# - Проверить сеть
curl http://clickhouse:8123
ping clickhouse

# - Проверить переменные окружения
env | grep CLICKHOUSE

# - Проверить файлы
ls -la /app/domains/

# - Запустить Python для отладки
python3
>>> from orbita_core.config import get_config
>>> config = get_config()
>>> print(config.clickhouse.host)

Запуск в debug режиме¶

# Остановить обычный контейнер
docker stop orbita

# Запустить с DEBUG логами
docker run -it --rm \
  --name orbita-debug \
  -p 8000:8000 \
  --env-file .env \
  -e LOG_LEVEL=DEBUG \
  -v $(pwd)/domains:/app/domains \
  your-registry.company.com/orbita:latest

# Логи будут более детальные

Профилирование производительности¶

# Включить профилирование (если поддерживается)
docker exec orbita python -m cProfile -o /tmp/profile.out \
  -m orbita_cli chat --query "покажи продажи"

# Анализ профиля
docker exec orbita python -c "
import pstats
stats = pstats.Stats('/tmp/profile.out')
stats.sort_stats('cumulative')
stats.print_stats(20)
"

Контрольный список диагностики¶

При возникновении проблемы проверьте:

Базовые проверки¶

Контейнер запущен (docker ps | grep orbita)
Health check работает (curl http://localhost:8000/health)
Логи не содержат критических ошибок
Достаточно ресурсов (CPU, память, диск)

Подключения¶

ClickHouse доступен (curl http://localhost:8123)
PostgreSQL доступен (docker exec postgres-metadata pg_isready)
LLM API доступен (проверить вручную через curl)
Сетевая связность между контейнерами

Конфигурация¶

.env файл существует и правильно заполнен
Домены настроены в domains/
Таблицы существуют в ClickHouse
API ключи валидны

Данные¶

БД метаданных инициализирована
Миграции применены (alembic current)
Достаточно места на диске

Сохранение диагностической информации¶

Для отправки в поддержку¶

# 1. Соберите диагностический пакет
./collect-diagnostics.sh

# 2. Проверьте содержимое (удалите секреты!)
tar -tzf orbita-diagnostics-*.tar.gz

# 3. Опционально: удалите чувствительную информацию
tar -xzf orbita-diagnostics-*.tar.gz
cd orbita-diagnostics-*/
# Удалите или отредактируйте файлы с секретами
nano env-sanitized.txt
cd ..
tar -czf orbita-diagnostics-clean.tar.gz orbita-diagnostics-*/

# 4. Отправьте файл администратору или в службу поддержки

Следующие шаги¶

Проблемы установки - если диагностика выявила проблемы с установкой
Проблемы подключения - если найдены проблемы с подключениями
Проблемы производительности - если система медленно работает