add instance files description to first steps

docs/glossary.md

@@ -253,8 +253,26 @@ _Присоединение инстанса_ близко по смыслу к
 ### Персистентность {: #persistence }
 **Персистентность** — свойство кластера поддерживать постоянную доступность данных и обеспечивать их максимальную сохранность. В контексте in-memory-системы это означает наличие механизмов журналирования и сохранения данных инстанса на диске с тем, чтобы при перезапуске инстанса (плановом или из-за нештатной ситуации) его данные могли быть надежно восстановлены. Таких механизмов в Picodata два:
 
-- сохранение изменений БД и ее метаданных при помощи журнала упреждающей записи (Write-ahead log, WAL). Журнал представляет собой последовательность нескольких файлов `*.xlog`, каждый из которых не самостоятелен: в нем изменения записываются относительно предыдущего файла `.xlog`. При отсутствии снимков данных (см. ниже) для восстановления инстанса потребуется полный набор этих файлов;
-- полные снимки данных инстанса в виде файлов `*.snap`. Каждый такой файл самостоятельный и хранит информацию о полном состоянии инстанса на определенный момент времени. Для восстановления данных инстанса может быть достаточно лишь наиболее свежего файла `*.snap`, однако иногда требуется комбинация снимок+журнал: используется снимок (`*.snap`) и один/несколько файлов `*.xlog` с изменениями, произошедшими после создания того снимка.
+- сохранение изменений БД и ее метаданных при помощи журнала упреждающей записи (Write-ahead log, WAL). Журнал представляет собой последовательность нескольких файлов `*.xlog` для таблиц на [движке](#db-engine) `memtx` и `*.vylog` для таблиц на движке `vinyl`. Каждый из файлов журнала не самостоятелен: в нем изменения записываются относительно предыдущего файла с инкрементными изменениями. При отсутствии снимков данных (см. ниже) для восстановления инстанса потребуется полный набор этих файлов;
+- полные снимки данных инстанса в виде файлов `*.snap`. Каждый такой файл самостоятельный и хранит информацию о полном состоянии инстанса на определенный момент времени. Для восстановления данных инстанса может быть достаточно лишь наиболее свежего файла `*.snap`, однако иногда требуется комбинация снимок+журнал: используется снимок (`*.snap`) и один/несколько файлов `*.xlog`/`*.vylog` с изменениями, произошедшими после создания того снимка.
+
+Для наглядности покажем следующий возможный набор файлов инстанса:
+```
+00010.xlog -- изменения начиная с пустой базы, заканчивая моментом t1
+00020.xlog -- изменения начиная с момента t1, заканчивая моментом t2
+00030.snap -- изменения начиная с пустой базы, заканчивая моментом t2
+00030.xlog -- изменения начиная с момента t2, заканчивая моментом t3
+00040.xlog -- изменения начиная с момента t3, заканчивая моментом t4
+00050.snap -- изменения начиная с пустой базы, заканчивая моментом t4
+```
+
+В этом примере есть несколько способов восстановить полное состояние
+инстанса на момент `t4`:
+
+- либо `00010.xlog` + `00020.xlog` + `00030.xlog` + `00040.xlog`
+- либо `00030.snap` + `00030.xlog` + `00040.xlog`
+- либо `00050.snap`
+
 
 ### Горизонтальное масштабирование {: #sharding }
 **Горизонтальное масштабирование** (оно же сегментирование или шардирование, sharding) — подход, предполагающий разделение данных на сегменты (бакеты, buckets), которые могут храниться на отдельных репликасетах кластера. С точки зрения набора хранимых данных, каждый репликасет называется шардом. Деление на шарды — это еще один вариант логического деления кластера, но без привязки к серверам, на которых выполняются инстансы.

docs/tutorial_first_steps.md

@@ -57,6 +57,26 @@ picodata connect --unix /tmp/file.socket
 \set language lua
 ```
 
+## Рабочие файлы инстанса
+В [директории с данными инстанса](cli.md#data-dir) автоматически появляются следующие файлы:
+
+- `*.snap` — файлы [снапшотов](glossary.md#snapshot) БД
+- `*.xlog` — файлы журнала упреждающей записи (Write-ahead log, WAL) c
+  инкрементными изменениями БД
+- `*.vylog` — также файлы с инкрементными изменениями БД, но для таблиц,
+  использующих движок хранения [`vinyl`](glossary.md#db-engine).
+
+При перезапуске инстанса эти файлы необходимы для восстановления его
+состояния, обеспечивая [персистентное](glossary.md#persistence) хранение
+данных.
+
+Файлы снапшотов (`*.snap`) и журнала WAL (`*.xlog`/`*.vylog`) не
+полностью взаимозаменяющие, так как, например, при аварийном завершении
+инстанса часть записей может не попасть в последний снапшот, но при
+этом попадет в файл журнала. В таком случае для полного восстановления
+данных нужен будет и последний снапшот, и один или несколько файлов
+журнала.
+
 Параметры запуска из командной строки описаны в разделе [Аргументы командной строки Picodata](../cli).