Журнал обновлений

Журнал обновлений#

Журнал обновлений предназначен для контроля сессий обновления базы данных.

Журнал позволяет отследить:

  • какие модули обновлялись;

  • какой комплект сборки был установлен;

  • какие скрипты выполнялись;

  • какие миграционные задачи запускались;

  • были ли ошибки при обновлении схемы;

  • какой лог был записан во время сессии обновления;

  • какие отложенные скрипты были зарегистрированы и были ли ошибки при их выполнении.

Форма просмотра реализована в Btk_ReleaseMonitorAvi. Данные создаются и обновляются инфраструктурой обновления базы данных, в том числе через:

  • Btk_DbUpgradeSessionPkg;

  • DatabaseUpgrader;

  • DbGenerator;

  • DbSchemaUpdater;

  • Btk_DbInstallerPkg;

  • Btk_DelayedScriptPkg;

  • Btk_MigrationPkg.

Журнал доступен по пути: Приложение «Настройка системы» > Аудит > Журнал обновлений.

Интерфейс журнала#

Основная форма Btk_ReleaseMonitorAvi.list() работает в режиме просмотра. Основные данные сессии берутся из Btk_DbUpgradeSession, а сведения о наличии и ошибках отложенных скриптов — из Btk_DelayedScriptLog.

В верхней части формы расположен фильтр по дате обновления:

  • Дата с — начало периода;

  • по — окончание периода.

При открытии формы метод beforeOpen() автоматически устанавливает начальную дату фильтра:

  • если текущий день месяца больше 10 — первый день текущего месяца;

  • если текущий день месяца 10 или меньше — первый день предыдущего месяца.

Основная таблица сортируется по dDate DESC.

Колонка

Описание

id сессии обновления

Идентификатор сессии обновления

Дата обновления

Дата и время обновления

Обновленные модули

Модули, которые были обновлены в рамках сессии

Установленный комплект сборки

Комплект сборки, установленный при обновлении

Скрипты обновления схемы и данных

Признак выполнения скриптов обновления схемы и данных

Обновление схемы

Признак выполнения обновления схемы

Скрипты до обновления схемы

Признак выполнения скриптов до обновления схемы

Скрипты после обновления схемы

Признак выполнения скриптов после обновления схемы

Миграционные задачи

Признак выполнения миграционных задач

Отложенные скрипты

Признак регистрации отложенных скриптов в рамках сессии. Если среди них есть скрипты с ошибками выполнения, признак отображается красным

Для выбранной сессии доступны вкладки детализации:

  • Обновление модулей — список обновленных модулей и модулей без изменений.

  • Обновление схемы — DDL-операции обновления схемы и ошибки их выполнения.

  • Скрипты обновления схемы и данных — скрипты, выполненные в рамках обновления.

  • Отложенные скрипты — скрипты, зарегистрированные для последующего выполнения, их тип, дата выполнения и текст ошибки при наличии.

  • Лог обновления — текстовый лог сессии обновления.

  • Скрипты, выполненные до обновления схемы — скрипты, выполненные перед изменением схемы.

  • Скрипты, выполненные после обновления схемы — скрипты, выполненные после изменения схемы.

  • Миграционные задачи upTask — миграционные задачи прямого применения.

  • Миграционные задачи downTask — миграционные задачи отката.

На вкладке Обновление модулей отображается дерево модулей. В нем показываются:

  • обновленные модули;

  • модули без изменений.

Для каждого модуля отображаются новая и предыдущая версии модуля, а также новая и предыдущая версии комплекта сборки.

На вкладке Отложенные скрипты отображаются сведения об отложенных скриптах, связанных с выбранной сессией обновления:

  • наименование скрипта;

  • тип скрипта;

  • текст ошибки, если выполнение завершилось с ошибкой;

  • дата выполнения.

Если отложенный скрипт зарегистрирован, но еще не выполнен, результат его выполнения в журнале еще не заполнен.

Журнал доступен только для просмотра. Данные в форме не создаются и не редактируются вручную.

Настройка журнала#

Таблицы журнала создаются программно методом:

Btk_DbUpgradeSessionPkg.registerTables(connection)

Метод вызывается в контуре обновления базы данных, например из DatabaseUpgrader.

При создании структуры формируются:

  • таблица сессий обновления Btk_DbUpgradeSession;

  • связанные таблицы детализации;

  • индекс Btk_DbUpgradeSession_dDate_desc_idx по dDate DESC;

  • последовательность Btk_DbUpgradeSession_seq.

Детальные таблицы ссылаются на Btk_DbUpgradeSession(id).

События формирования записей#

Журнал заполняется автоматически при выполнении обновления базы данных.

Новая сессия создается через:

Btk_DbUpgradeSessionPkg.getNewSession(...)

Дальнейшие этапы обновления записывают результаты в связанные таблицы.

Заполнение журнала подключено к процессам обновления:

  • DatabaseUpgrader создает сессии обновления и записывает лог;

  • DbGenerator записывает строки в Btk_UpdateDbSchema и обновляет признак bUpdSchema;

  • Btk_DbInstallerPkg регистрирует DbData-скрипты;

  • при регистрации отложенных скриптов создаются записи в Btk_DelayedScriptLog, связанные с текущей сессией по idSession;

  • после фактического выполнения отложенного скрипта связанная запись дополняется датой выполнения и текстом ошибки при наличии;

  • Btk_MigrationPkg регистрирует миграционные задачи upTask и downTask.

Форма Btk_ReleaseMonitorAvi сама данные не создает. Она читает уже записанные таблицы и отображает их в основной форме и детализациях.

Если обновление выполнялось вне штатного процесса или без idUpdateSession, записи в журнале обновлений могут быть неполными или отсутствовать.

Хранение данных#

Журнал хранится не в одной таблице, а в нескольких связанных таблицах.

Btk_DbUpgradeSession хранит заголовок сессии обновления:

  • идентификатор;

  • дату;

  • список обновленных модулей;

  • установленный KIT;

  • признаки выполнения этапов обновления;

  • цветовые признаки ошибок;

  • текстовый лог sLogContext.

Btk_ReleaseModule хранит сведения о версиях модулей в рамках сессии. В форме данные отображаются деревом с двумя группами:

  • обновленные модули;

  • модули без изменений.

Btk_UpdateDbSchema хранит DDL-операции обновления схемы и текст ошибки, если операция завершилась неуспешно.

Btk_DbUpgradeSessionTask хранит задачи сессии:

  • DbData-скрипты;

  • migration upTask;

  • migration downTask.

Для задач сохраняются новая и старая версии, JSON-параметры и текст ошибки.

Btk_DbSchemaVersionScript используется формой для просмотра скриптов, выполненных до и после обновления схемы. В Btk_ReleaseMonitorAvi данные читаются по idSession и sScriptType.

Btk_DelayedScriptLog хранит сведения об отложенных скриптах, зарегистрированных в рамках сессии обновления, и связан с Btk_DbUpgradeSession по idSession.

Хранимые поля#

Сессия обновления#

Основные поля Btk_DbUpgradeSession:

Поле

Назначение

id

Идентификатор сессии обновления

dDate

Дата и время начала сессии

sUpgModules

Список обновленных модулей

sInstKIT

Установленный комплект сборки

bScrInst

Признак выполнения скриптов обновления схемы и данных

bUpdSchema

Признак выполнения обновления схемы

bScrBeforeUpg

Признак выполнения скриптов до обновления схемы

bScrAfterUpg

Признак выполнения скриптов после обновления схемы

bMigTask

Признак выполнения миграционных задач

sLogContext

Текстовый лог сессии обновления

sColorScrInst

Цветовой признак ошибок скриптов обновления схемы и данных

sColorUpdSchema

Цветовой признак ошибок обновления схемы

sColorBeforeUpg

Цветовой признак ошибок скриптов до обновления схемы

sColorAfterUpg

Цветовой признак ошибок скриптов после обновления схемы

sColorMigTask

Цветовой признак ошибок миграционных задач

Признаки отложенных скриптов bDelayedScript и sColorDelayedScript вычисляются в SQL-запросе выборки журнала по данным Btk_DelayedScriptLog:

  • bDelayedScript — признак наличия отложенных скриптов для сессии. Устанавливается, если в Btk_DelayedScriptLog есть хотя бы одна запись с соответствующим idSession;

  • sColorDelayedScript — цветовой признак ошибок отложенных скриптов.

Цветовые признаки sColor..., используемые в журнале обновлений, работают одинаково: если для соответствующего этапа или скрипта зафиксирована ошибка, признак принимает значение GDS_ResType_Error; если ошибок нет, значение не задается.

Модули релиза#

Поля Btk_ReleaseModule:

Поле

Назначение

idSession

Ссылка на сессию обновления

sModuleName

Наименование модуля

sNewVersion

Новая версия модуля

sOldVersion

Предыдущая версия модуля

sNewVersionKit

Новая версия KIT

sOldVersionKit

Предыдущая версия KIT

Обновление схемы#

Поля Btk_UpdateDbSchema:

Поле

Назначение

idSession

Ссылка на сессию обновления

sTextDDL

Текст DDL-операции

sErrorDDL

Текст ошибки DDL-операции

Задачи сессии#

Поля Btk_DbUpgradeSessionTask:

Поле

Назначение

idSession

Ссылка на сессию обновления

sName

Наименование задачи или скрипта

sType

Тип задачи: DbDataScript, MigrationUpTask, MigrationDownTask

sTypeHL

Человекочитаемое отображение типа в форме

nNewVersion

Новая версия

nOldVersion

Предыдущая версия

jData

JSON-параметры задачи

sError

Текст ошибки

Отложенные скрипты#

Btk_DelayedScriptLog хранит данные отложенного скрипта, связанные с сессией обновления. Для работы журнала используются:

Данные

Назначение

idSession

Ссылка на сессию обновления

Наименование скрипта

Позволяет определить зарегистрированный отложенный скрипт

Тип скрипта

Тип зарегистрированного отложенного скрипта

Дата выполнения

Записывается после фактического выполнения скрипта

sError

Текст ошибки выполнения, если она возникла

Скрипты схемы#

Поля Btk_DbSchemaVersionScript, используемые формой:

Поле

Назначение

idSession

Ссылка на сессию обновления

sModuleName

Модуль

sScriptName

Наименование скрипта

sVersion

Версия

sScriptType

Тип скрипта: до или после обновления схемы

Программные интерфейсы#

Основная логика регистрации данных сессии находится в Btk_DbUpgradeSessionPkg. Регистрация и обновление сведений об отложенных скриптах выполняются через Btk_DelayedScriptPkg.

Ключевые методы:

  • registerTables(connection) — создает таблицы, индекс и последовательность;

  • getNewSession(connection) — создает новую сессию обновления и возвращает ее id;

  • registerDbDataScript(...) — регистрирует выполненный DbData-скрипт;

  • registerMigrationUpTask(...) — регистрирует миграционную задачу upTask;

  • registerMigrationDownTask(...) — регистрирует миграционную задачу downTask;

  • updateTask(...) — пересчитывает признаки и цвет ошибки для миграционных задач;

  • updateScript(...) — пересчитывает признаки по скриптам до и после обновления, а также по DbData-скриптам;

  • setLog(...) — дописывает текст в Btk_DbUpgradeSession.sLogContext;

  • resetUpgrade(...) — сбрасывает версии задач к состоянию выбранной сессии.

Для отложенных скриптов используются:

  • Btk_DelayedScriptPkg.registerS — регистрирует отложенный скрипт инсталляции в Btk_DelayedScriptLog;

  • Btk_DelayedScriptPkg.registerC — регистрирует отложенный скрипт объекта схемы в Btk_DelayedScriptLog;

  • Btk_DelayedScriptPkg.updateDelayedScriptLog — записывает дату выполнения и текст ошибки в связанную запись журнала после выполнения скрипта.

Для отчета генератора Btk_DbInstallerPkg.loadDbData формирует данные по обычным скриптам и отдельную карту отложенных скриптов с ошибками.

Ошибки отложенных скриптов в отчете генератора#

Если у отложенных скриптов есть ошибки выполнения, в отчете генератора выводится отдельный блок Ошибки отложенных скриптов.

Для каждой ошибки указываются:

  • имя скрипта;

  • дата исполнения;

  • текст ошибки.

Блок формируется только для записей с непустым текстом ошибки. Данные об отложенных скриптах с ошибками собираются в Btk_DbInstallerPkg.loadDbData.

Особенности эксплуатации#

Журнал ведется автоматически при выполнении штатного обновления базы данных.

Требования к безопасной настройке журналов, разграничению доступа, хранению и использованию журналов при расследовании инцидентов описаны в документе «Логирование, аудит и управление инцидентами», в разделах Защита журналов и Аудит пользовательской активности.

Ошибки в форме подсвечиваются через служебные и вычисляемые признаки sColor.... Они определяются по наличию ошибок:

  • в скриптах;

  • в DDL-операциях;

  • в миграционных задачах;

  • в отложенных скриптах.

Журнал обновлений обычно ценнее обычных технических логов, так как показывает историю обновлений и помогает разбирать проблемы применения релизов.

Объем журнала зависит не только от количества сессий, но и от детализации внутри каждой сессии.

Основной объем могут давать текстовые поля:

  • sLogContext;

  • sTextDDL;

  • sErrorDDL;

  • sError;

  • jData.

Для оценки роста рекомендуется анализировать:

  • количество строк в Btk_UpdateDbSchema на одну сессию;

  • количество задач в Btk_DbUpgradeSessionTask;

  • количество строк в Btk_DbSchemaVersionScript;

  • размер полей sLogContext, sTextDDL, sErrorDDL, sError и jData;

  • частоту обновлений с ошибками;

  • самые объемные сессии обновления.

Хранение и очистка#

Для рабочей базы рекомендуется начинать со срока хранения журнала обновлений 180–365 дней. Для контуров с редкими релизами или повышенными требованиями к прослеживаемости журнал можно хранить дольше.

Для Btk_DelayedScriptLog предусмотрена отдельная очистка. Метод Btk_DelayedScriptPkg.clearOldDelayedScriptLogs(<количество дней>) удаляет записи старше указанного количества дней и зарегистрирован в CleanupJob. По умолчанию срок хранения составляет 30 дней.

Для остальных данных журнала обновлений штатной регламентной очистки в коде нет.

Удалять только строки Btk_DbUpgradeSession прямым SQL нежелательно, потому что у журнала есть связанные таблицы, а внешние ключи в текущей структуре не описаны как ON DELETE CASCADE.

Рекомендуемый вариант — оформить отдельный скриптовый метод очистки и зарегистрировать его в CleanupJob как DeleteType.script.

Перед удалением сессий из Btk_DbUpgradeSession необходимо удалить связанные записи отложенных скриптов. Для этого можно вызвать Btk_DelayedScriptPkg.clearOldDelayedScriptLogs(...) с тем же сроком хранения, который используется для удаления сессий журнала.

После этого данные по Btk_DbUpgradeSession.dDate удаляются в следующем порядке:

  1. Btk_DbSchemaVersionScript по старым idSession, если таблица используется в контуре.

  2. Btk_DbUpgradeSessionTask.

  3. Btk_UpdateDbSchema.

  4. Btk_ReleaseModule.

  5. Btk_DbUpgradeSession.

SQL-ориентир для ручной проверки старых сессий:

select id
from Btk_DbUpgradeSession
where dDate < current_timestamp - interval '365 days';

Примечание

По умолчанию записи Btk_DelayedScriptLog хранятся 30 дней. Если сессии журнала обновлений хранятся дольше, сведения об отложенных скриптах для старых сессий могут быть удалены раньше самой сессии.

Содержание