Уровни уверенности в инструкции pg_expecto.1.1

Четыре ступени достоверности.

Уровни достоверности выводов (краткое описание)

ℹ️Каждое утверждение в анализе должно сопровождаться уровнем достоверности:

1️⃣Уровень‑1: Подтверждено данными — значение непосредственно из метрик, логов или прямое математическое следствие. Не требует интерпретации.

• Пример: «Доля ожиданий IO = 34% (Уровень‑1).»

2️⃣Уровень‑2: Вероятно, но требует проверки — вывод основан на корреляциях, трендах или типовых практиках. Необходимы дополнительные данные для подтверждения.

• Пример: «Рост temp_files, вероятно, связан с нехваткой work_mem (Уровень‑2).»

3️⃣Уровень‑3: Предположение / недостаточно данных — гипотеза без косвенных подтверждений в отчёте. Требуются отсутствующие метрики или инструментальное исследование.

• Пример: «Причина падения SPEED не установлена — нет логов блокировок (Уровень‑3).»

4️⃣Уровень‑4: Невозможно оценить — метрика или аспект не фигурируют в отчёте, их значение не выводимо из имеющихся данных.

• Пример: «Оценить утечку соединений нельзя — нет временного ряда numbackends (Уровень‑4).»

Уровни достоверности выводов (подробное описание)

Данный раздел определяет шкалу достоверности для каждого утверждения, формируемого в процессе анализа. Использование уровней обязательно для всех выводов отчёта. Уровень указывается в скобках после утверждения, например: «Средняя операционная скорость (SPEED) за период составила 241 876 (Уровень‑1)».

5.1. Уровень‑1: Подтверждено данными

Критерии присвоения:

• Значение получено непосредственно из предоставленных метрик (например, numbackends, temp_files, hit_ratio) и не подвергалось интерпретации.
• Вывод является прямым математическим следствием из имеющихся данных (например, сумма значений ожиданий по типам wait_event_type равна общему числу ожиданий).
• Утверждение основано на прямых измерениях СУБД (pg_stat_*, pg_locks, логи ошибок) и не требует косвенных допущений.

Примеры:

• Медианное значение SPEED во втором временном интервале (с 14:00 до 15:00) = 241 876 (Уровень‑1).
• Доля ожиданий типа IO в общей структуре ожиданий за период = 34,2% (Уровень‑1).
• Количество временных файлов (temp_files) в базе данных app_db за сутки выросло с 120 до 540 (Уровень‑1).

Ограничения:

Уровень‑1 не гарантирует, что значение «правильное» с точки зрения физического смысла (например, метрика может быть ошибочно собрана агентом мониторинга). При обнаружении противоречий между разными метриками уровня‑1 применяется иерархия доверия (см. раздел 6 «Протокол обработки противоречий»).

5.2. Уровень‑2: Вероятно, но требует проверки

Критерии присвоения:

• Вывод основан на косвенных признаках: корреляциях (коэффициент Пирсона > |0,5|), трендах (монотонный рост, периодические пики) или статистических зависимостях, которые не являются строгим доказательством причинно‑следственной связи.
• Утверждение опирается на общеизвестные практики эксплуатации PostgreSQL (например, «рост temp_files при низком значении work_mem может указывать на дисковые сортировки»).
• Для полного подтверждения необходимы дополнительные данные (план запроса, конфигурация приложения, профилирование ОС), которые не входят в текущий отчёт.

Правила формулировки:

• Использовать модальные глаголы и указание на предположительный характер: «вероятно», «может указывать на», «есть основания полагать».
• Обязательно указать, каких именно данных не хватает для перевода вывода в уровень‑1.

Примеры:

• Вероятно, рост ожиданий DataFileRead связан с последовательным сканированием большой таблицы (требуется план запроса для подтверждения) (Уровень‑2).
• Монотонный рост temp_bytes при стабильной нагрузке может указывать на запросы, использующие work_mem недостаточного размера (необходимо собрать статистику по sort/hash из pg_stat_statements) (Уровень‑2).
• Высокая корреляция (r=0,82) между переключениями контекста (cs) и временем системы (sy) при низком I/O (wa<3%) вероятно свидетельствует о частых системных вызовах (требуется профилирование strace/perf) (Уровень‑2).

⚠️Недопустимо:

Выдавать уровень‑2 за установленный факт или делать окончательные рекомендации по изменению конфигурации без оговорки о необходимости проверки.

5.3. Уровень‑3: Предположение / недостаточно данных

Критерии присвоения:

• Вывод является гипотезой, основанной на общей логике или опыте, но в предоставленных данных нет даже косвенных подтверждений.
• Для проверки гипотезы необходимо собрать метрики, которые полностью отсутствуют в текущем отчёте, либо провести инструментальное исследование (запрос планов, логирование блокировок, нагрузочное тестирование).
• Данные устарели (период сбора закончился более чем за 30 дней до момента анализа) или их точность/полнота вызывает сомнения.

Примеры:

• Точная причина падения SPEED в 09:15 не установлена — отсутствуют логи ошибок и метрики блокировок за этот период (Уровень‑3).
• Предположительно, частые контрольные точки связаны с низким значением max_wal_size, но в отчёте нет данных о размере WAL (Уровень‑3).
• Возможно, на производительность влияет сетевая задержка между приложением и БД, однако метрики времени приёма/передачи (pg_stat_database) не предоставлены (Уровень‑3).

Действия аналитика:

При присвоении уровня‑3 необходимо явно перечислить, каких именно данных не хватает, и предложить конкретные инструменты или срезы для их получения (например, «включите pg_stat_statements на 1 час, соберите EXPLAIN (ANALYZE, BUFFERS) для пяти самых долгих запросов»).

5.4. Уровень‑4: Невозможно оценить

Критерии присвоения:

• Термин, метрика или аспект системы не фигурируют в отчёте, и их значение не может быть выведено из доступных данных.
• Запрашиваемый вывод относится к компоненте, которая не отслеживалась в принципе (например, сетевая статистика, размер таблиц, использование расширений).
• Данные по метрике существуют, но их формат или агрегация не позволяют провести анализ (например, временной ряд отсутствует, есть только среднее за неделю).

Правила использования:

• Уровень‑4 не является «ошибкой» аналитика или заказчика — это констатация границы применимости текущих данных.
• Если для ответа на вопрос пользователя требуется метрика, имеющая уровень‑4, следует прямо заявить: «Для оценки X необходимо предоставить Y (Уровень‑4)».

Примеры:

• Оценить наличие утечки соединений невозможно — в отчёте отсутствует временной ряд numbackends с дискретизацией не реже 1 минуты (Уровень‑4).
• Проверка параметра random_page_cost относительно типа дисков (SSD/HDD) невозможна: нет метрик времени ввода‑вывода (r_await, await) из iostat или vmstat (Уровень‑4).
• Анализ effective_cache_size относительно свободной памяти ОС требует данных free или buff/cache из системных метрик (Уровень‑4).

5.5. Правила применения уровней в отчёте

☑️Каждое утверждение в разделах «Детальный анализ», «Проблемы инфраструктуры» и «Выводы» должно сопровождаться указанием уровня достоверности.

• Исключение: прямая цитата из предоставленных данных (например, «в логах найдена строка …») может не маркироваться уровнем, если это не является интерпретацией.

☑️Уровни не следует использовать для ранжирования важности проблем — только для описания уверенности в конкретном факте. Проблема с уровнем‑2 может быть критичнее, чем с уровнем‑1, если последний касается второстепенной метрики.

☑️При наличии противоречий между выводами разных уровней приоритет имеет уровень‑1 (прямые измерения СУБД) над уровнем‑2 (косвенные корреляции).

☑️Если противоречат друг другу два утверждения уровня‑1, применяется протокол из раздела 6 (иерархия: pg_stat_* > данные ОС > косвенные метрики).

Повышение уровня достоверности:

1. Вывод может быть переведён из уровня‑2 в уровень‑1 только после предоставления прямых подтверждающих данных (например, плана запроса, логов, точных измерений). Аналитик не должен «додумывать» недостающие данные.

Понижение уровня достоверности:

1. Если в процессе анализа обнаруживается, что ранее полученная метрика (уровень‑1) не согласуется с другими прямыми измерениями, следует пересмотреть её статус. Возможно, метрика содержит артефакт агрегации — тогда она помечается как уровень‑3 с указанием на возможную ошибку сбора.

5.6. Примеры корректного использования в тексте отчёта

• «Медианное значение SPEED за период 10:00–11:00 = 305 420 (Уровень‑1).»
• «Вероятно, падение SPEED в 10:15 связано с ростом ожиданий LWLock:buffer_content (коэффициент корреляции r=0,74). Для подтверждения необходим анализ блокировок страниц (Уровень‑2).»
• «Точная причина роста temp_files не установлена — отсутствуют данные о размере work_mem и планы запросов (Уровень‑3).»
• «Оценить утечку памяти в процессах PostgreSQL невозможно: в отчёте нет тренда RSS по каждому бэкенду (Уровень‑4).»

5.7. Недопустимые конструкции⚠️

• «Очевидно, что проблема в нехватке памяти» (без указания уровня) → нарушение.⚠️
• «Уровень‑2: проблема точно в autovacuum» (противоречие — уровень‑2 не допускает слова «точно») → нарушение.⚠️
• «Производительность упала из-за блокировок (Уровень‑1)» — если блокировки не измерялись напрямую, а только предполагаются по корреляции → неверное завышение уровня.⚠️

ℹ️ Соблюдение данной классификации обеспечивает прозрачность анализа и позволяет заказчику отчёта понимать, на какие выводы можно опираться при принятии решений, а какие требуют дополнительной верификации.