29. Журнали, діагностика та звернення по допомогу¶

Work in progress

«Учора працювало, а сьогодні зависло» — цілком зрозумілий початок розмови. Але щоб знайти причину, потрібні ще кілька деталей: що саме ви робили, коли це сталося і що в той момент бачив StudioFS. Зберемо ці відомості без пересилання всього робочого проєкту разом із паролями.

Якщо є підозра, що зміни ще не передано у сховище, спершу збережіть роботу й припиніть нові записи. Не видаляйте кеш і не запускайте «ремонт навмання» заради чистого звіту: можна втратити і дані, і сліди проблеми. Практичні перші перевірки є в попередньому розділі.

Спочатку — версія та короткий знімок стану¶

Ці команди допоможуть зібрати основу звернення:

studiofs --version
studiofs --help
studiofs status myvolume --verbose

Замініть myvolume на назву свого тому. status приймає назву тому, а не літеру диска чи каталог підключення. Він показує прив’язку метаданих, локальні лічильники, стан кешу й доступні показники запису. Якщо кеш підключення розташований в окремому каталозі, вкажіть ту саму базову теку через --cache-dir:

studiofs status myvolume --verbose --cache-dir "D:\StudioFS-cache"

Відсутність показника або попередження про застарілі дані — теж корисна інформація. Це не доказ, що відповідна черга порожня чи що все вже синхронізовано. Збережіть і текст помилки, якщо сама команда status не спрацювала.

Додайте версію та збірку ОС, версію драйвера файлової системи — WinFSP у Windows, macFUSE у macOS або FUSE у Linux. Для проблеми між двома комп’ютерами потрібні версії обох клієнтів. Вкажіть також тип S3-сховища й версію PostgreSQL, якщо вона відома; паролі для цього не потрібні.

Довідку конкретної команди можна відкрити окремо:

studiofs status --help
studiofs perf --help
studiofs mount --help

Орієнтуйтеся на довідку встановленої версії: набір параметрів у різних випусках може відрізнятися.

Якщо проблема проявляється під навантаженням¶

perf спостерігає за вже підключеним диском. На відміну від status, він приймає точку підключення:

studiofs perf Z: --interval 1000 --count 10 --json-lines > perf.jsonl

Для macOS або Linux замініть Z: на свій шлях, наприклад /mnt/studio. Інтервал задано в мілісекундах; --count 10 обмежує збір десятьма інтервальними зразками. Файл perf.jsonl буде створено в поточному каталозі. Виберіть для нього локальну теку поза диском StudioFS, щоб запис звіту не додавав навантаження на вимірюваний том.

Запустіть збір у другому терміналі й повторіть безпечну дію, на якій виникає проблема. Запишіть, коли почали її виконувати. perf показує лічильники, швидкості та затримки, а не замінює журнал помилок. Якщо підключення вже не працює, команда може не отримати статистику — додайте її повідомлення до звернення.

Без --count спостереження триває, доки ви його не зупините. Для короткого звіту зручніше одразу поставити межу.

Де шукати журнали¶

Місце залежить від способу запуску:

Типовий каталог журналів — ~/.studiofs/logs/ у macOS та Linux, а у Windows — .studiofs\logs у домашньому каталозі користувача, зазвичай %USERPROFILE%\.studiofs\logs. Якщо для цього клієнта задано STUDIOFS_CLIENT_ROOT, шукайте його підкаталог logs. Це окреме місце від каталогу кешу: зміна --cache-dir не переносить туди журнали.

Імена файлів мають вигляд <назва-тому>-<UUID>.log.<РРРР-ММ-ДД>. У назві тому непридатні для імені файла символи замінюються на _. Журнали фонового процесу розділяються за днями UTC; під час запуску він намагається видалити свої файли, старші за 30 днів. Тож потрібний фрагмент краще зберегти одразу. Якщо подія сталася біля опівночі UTC, перевірте обидва сусідні файли.

Для звернення зазвичай достатньо фрагмента за кілька хвилин до й після події. Збережіть часові позначки та сусідні повідомлення: останній рядок помилки часто є наслідком, а причина з’явилася раніше.

Коли потрібен докладніший журнал¶

Типовий рівень журналювання — info. Глобальний параметр --log-level приймає trace, debug, info, warn або error. Для короткого відтворення можна запустити підключення з рівнем debug:

studiofs --log-level debug mount myvolume /mnt/studio

У Windows замість /mnt/studio використайте свою літеру диска, наприклад Z:. Виконуйте такий запуск після штатного від’єднання попереднього підключення, коли це безпечно для роботи; порядок описано в розділі 17. Не перезапускайте аварійний клієнт лише заради докладнішого журналу, поки не зберегли доступні свідчення.

Параметр належить процесу, який ви запускаєте. Команда studiofs --log-level debug status myvolume не перемикає журналювання вже запущеного підключення.

У відкритому терміналі можна зберегти обидва потоки в локальний файл:

studiofs --log-level debug mount myvolume /mnt/studio > mount-debug.log 2>&1

Команда займе термінал на час роботи підключення, а повідомлення підуть у файл. Для фонового запуску додайте -d: тоді шукайте щоденний журнал у каталозі logs, а не покладайтеся на перенаправлення термінала.

Докладне журналювання створює більше даних і може впливати на вимірювання швидкості. Після потрібного короткого відтворення поверніться до звичайного запуску з info. Рівень trace варто застосовувати для конкретного запиту розробників, а не залишати назавжди.

Що прибрати перед надсиланням¶

Перегляньте копію кожного файла, який плануєте надіслати, включно з JSON, виводом команд і знімками екрана. Оригінали залиште локально. Не вважайте, що програма гарантовано приховала всі чутливі дані за вас.

Приберіть або замініть послідовними позначками:

• ключі доступу S3, секретні ключі, паролі, токени, заголовки авторизації та підписані URL;
• повні PostgreSQL DSN і рядки з’єднання, навіть якщо пароль у них уже замасковано;
• приватні адреси серверів, назви бакетів, користувачів і томів, ідентифікатори та локальні шляхи, якщо вони розкривають вашу інфраструктуру;
• назви клієнтів, проєктів і файлів, вміст документів та інші дані, які ви не маєте права публікувати.

Наприклад, позначте один і той самий комп’ютер як CLIENT_A, інший — як CLIENT_B, а приватний шлях — як <PROJECT_PATH>. Залиште структуру подій, коди помилок, часові позначки та порядок дій. Якщо змінили назви або часові позначки, поясніть це в описі, щоб розробники не шукали проблему в результаті редагування.

Не додавайте цілком .env, конфігурацію з обліковими даними, каталог клієнта чи кеш «про всяк випадок». Якщо секрет уже потрапив у публічне звернення, видалення тексту не робить його знову таємним: відкличте або замініть його через відповідний сервіс.

Дамп — не готовий пакунок для підтримки¶

studiofs dump експортує маніфест метаданих із PostgreSQL. Це не універсальний діагностичний архів і не повна резервна копія: він не містить усього вмісту файлів із S3, локальних ще не опублікованих змін чи повного стану всіх службових таблиць. Зокрема, він не замінює резервування каталогу знімків і стану обліку доступності об’єктів.

Водночас метадані можуть розкрити структуру проєктів, назви файлів та інші приватні відомості. Частина стану збережена у вигляді серіалізованих даних: побіжного перегляду JSON недостатньо, щоб оголосити дамп безпечним. Не прикріплюйте його до публічного звернення за замовчуванням. Якщо розробники попросили дамп, узгодьте потрібний обсяг і приватний спосіб передавання; краще відтворіть проблему на окремому тестовому томі з вигаданими даними.

Так само приховані команди studiofs internal diagnostics-*, профілювання та робочі процеси з docs/diagnostics-workflows.md призначені для керованих досліджень із розробниками. Вони не є обов’язковим кроком звичайного звернення. Не потрібно самостійно отримувати діагностичні дозволи чи запускати внутрішні сценарії, щоб повідомити про помилку.

Як скласти корисне звернення¶

Спершу пошукайте схожу проблему в GitHub Issues StudioFS. Якщо вже є звернення з тією самою поведінкою, корисніше додати своє середовище та відтворення туди. Для нової проблеми оберіть коротку назву, наприклад: «Windows: повторне відкриття файла зависає після втрати мережі».

Опис можна почати з такого шаблону. Для міжнародного обговорення заповніть його англійською, зберігши точний текст помилок:

Короткий опис:

Середовище:
- StudioFS: вивід studiofs --version на кожному залученому клієнті
- ОС і збірка; драйвер файлової системи та його версія
- Тип S3-сховища; версія PostgreSQL, якщо відома
- Кількість клієнтів; тип мережі; локальний чи зовнішній SSD для кешу

Передумови:
- Команда підключення без секретів; розмір і розташування кешу
- Новий чи наявний том; приблизний розмір і кількість тестових файлів
- Що змінилося перед появою проблеми

Кроки відтворення:
1. ...
2. ...
3. ...

Очікуваний результат:
Фактичний результат і точний текст помилки:
Частота: щоразу / інколи / один раз; кількість спроб
Час події та часовий пояс:

Додані матеріали:
- Очищений вивід status --verbose
- Фрагмент журналу за вказаний час
- Короткий perf.jsonl, якщо проблема стосується швидкодії

Що вже перевірено й який був результат:
Що приховано або замінено в доданих матеріалах:

Для проблеми між клієнтами розпишіть дії окремо: «CLIENT_A записав файл», «CLIENT_B відкрив його через …». Для низької швидкості додайте розмір файлів, послідовне чи випадкове читання, стан кешу та виміряний час. «Повільно» важко порівняти; «файл 2 ГБ відкривається 40 секунд після першого підключення» вже дає точку відліку.

Відтворення на малому тестовому файлі без матеріалів замовника особливо цінне. Але якщо повторення загрожує робочим даним, так і напишіть та надішліть те, що вже вдалося безпечно зібрати. Хороше звернення не вимагає ще раз втратити роботу заради переконливості.

Зміст · English · ← Попередня · Наступна →