Руководство системного программиста по ГОСТ 19.503-79

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Руководителю Аналитику Техническому писателю

Руководство системного программиста (ГОСТ 19.503–79)

ГОСТ

Основано на ГОСТ 19.503–79.

Руководство системного программиста — это инструкция для того, кто ставит и настраивает программу на сервере.

Нужно для:

системного администратора;
DevOps-инженера;
специалиста поддержки;
аудитора;
аналитика;
разработчика.

Чтобы программу можно было установить, настроить и починить.

1. Обзор стандарта ГОСТ 19.503–79

1.1. Назначение стандарта

ГОСТ 19.503–79 устанавливает единые требования к содержанию и оформлению программного документа «Руководство системного программиста» — одного из базовых документов Единой системы программной документации (ЕСПД).

Документ предназначен для системных программистов, администраторов и специалистов по внедрению, занимающихся:

установкой,
настройкой,
проверкой работоспособности,
интеграцией и сопровождением программного обеспечения (ПО).

Не следует путать с «Руководством оператора» (ГОСТ 19.505) или «Описанием программы» (ГОСТ 19.402) — это именно технический документ для глубокого взаимодействия с программой на уровне инфраструктуры, конфигурации и отладки.

1.2. Область применения

Стандарт применяется при разработке ПО, подлежащего:

государственному регулированию (военные, промышленные, энергетические, АСУ ТП системы);
внутренним корпоративным требованиям документирования (например, в крупных банках или интеграторах);
образовательным и методическим целям — как база для обучения техническому письму и инженерии документации.

Несмотря на возраст стандарта, его принципы полностью актуальны и в современных DevOps- и SRE-практиках, особенно в части:

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

1.3. Соответствие международным аналогам

ГОСТ 19.503–79 полностью соответствует СТ СЭВ 2094–80 и в функциональном плане сопоставим с такими форматами, как:

Система Administrator’s Guide (Red Hat, IBM, Oracle),
Installation and Configuration Manual (Microsoft),
разделы Deployment, Troubleshooting, Система Messages в документации Kubernetes, PostgreSQL, ELK Stack.

Отличие ГОСТ — строгая регламентация обязательных разделов и их внутренней структуры.

1.4. Структура документа по ГОСТ

Согласно п. 1.2 стандарта, обязательные разделы:

№	Наименование раздела	Обязательность
1	Общие сведения о программе	✅ Обязательный
2	Структура программы	✅ Обязательный
3	Настройка программы	✅ Обязательный
4	Проверка программы	✅ Обязательный
5	Дополнительные возможности	⚠️ По необходимости
6	Сообщения системному программисту	✅ Обязательный

Дополнительно (п. 1.1 и 2.7):

Титульный лист + лист регистрации изменений — по ГОСТ 19.105–78;
Аннотация (информационная часть) — краткое резюме назначения и состава документа;
Содержание — оглавление с нумерацией разделов, подразделов, приложений;
Приложения — опционально (примеры команд, схемы, логи, таблицы параметров и т.п.).

⚠️ Примечание: согласно Изменению № 1 (1981 г.), допускается:

объединять смежные разделы (например, «Настройка» и «Проверка» — если процедуры идентичны);

опускать слово «программа» в заголовках, заменяя его на наименование ПО («Настройка «Альфа-Монитор»» вместо «Настройка программы»);

исключать раздел «Дополнительные возможности» при отсутствии расширенных функций.

2. Типичные ошибки при написании и как их избежать

Ошибка	Описание	Как избежать
❌ Отсутствие аннотации и содержания	Нарушение п. 1.1 стандарта: «Составление информационной части является обязательным». Даже в технических документах для внутреннего использования это снижает навигируемость.	Всегда начинать с краткой аннотации (3–5 строк): цель, аудитория, ключевые разделы. Генерировать оглавление автоматически (например, в Docusaurus, MkDocs, Confluence).
❌ Смешение ролей: руководство для администратора vs. для разработчика	Описание API, архитектуры или кода — это зона «Описания программы» (ГОСТ 19.402) или «Программы и методики испытаний» (ГОСТ 19.301).	Чётко следовать целевой аудитории: документ предназначен для системного программиста, т.е. того, кто развёртывает и конфигурирует, а не пишет код.
❌ Отсутствие контекста в «Сообщениях»	Перечисляются только тексты ошибок без интерпретации, диагностики и действий.	Для каждого сообщения указывать:

Код/идентификатор (если есть),

Условие возникновения,

Влияние на работу,

Рекомендуемые действия (в виде пунктов). | | ❌ Техническая неоднозначность в «Настройке» | Фразы вроде «сконфигурировать параметры» без указания файла, формата, значений по умолчанию. | Использовать шаблон:

Файл конфигурации: /etc/xsys/config.yaml

Параметр: db.timeout

Тип: integer (секунды)

Диапазон: 10–300

Значение по умолчанию: 30

Пример: db.timeout: 120 | | ❌ Непроверяемые инструкции в «Проверке» | Указание «запустить и убедиться, что работает» без критериев успеха. | Включать:

Набор контрольных примеров (input → expected output),

Методы прогона (например, xsys-cli --test),

Пороговые значения (время ответа < 200 мс, потребление памяти < 512 МБ),

Критерии приёма (все тесты пройдены, лог не содержит ERROR). | | ❌ Игнорирование зависимостей в «Общих сведениях» | Указание только ОС, без версий, драйверов, библиотек времени выполнения. | Фиксировать точные требования:

- ОС: Ubuntu 22.04 LTS (kernel ≥ 5.15)  
- runtime: OpenJDK 17.0.8 (Temurin)  
- Библиотеки: `libpq5 ≥ 14.5`, `openssl ≥ 3.0.2`  
- Оборудование: 4 ядра CPU, 8 ГБ RAM, SSD ≥ 50 ГБ свободного места  
``` |

> 💡 **Педагогический совет**: при обучении техническому письму полезно давать упражнение: *«Напишите инструкцию так, чтобы её мог выполнить коллега, никогда не видевший систему, за 30 минут без звонков»*.

---

### 3. Принципы оформления (по ГОСТ 19.105–78)  
Хотя основное содержание регламентирует ГОСТ 19.503–79, **форма** — по ГОСТ 19.105–78:

- Нумерация разделов — десятичная (`2.3.1`, `4.1.2.5`);
- Подписи рисунков и таблиц — сверху (`Рисунок 1 — Схема взаимодействия модулей`);
- Таблицы — со сквозной нумерацией (`Таблица 1`, `Таблица 2`);
- Код и конфиги — в блоках с указанием языка/формата;
- Приложения — обозначаются заглавными буквами (`Приложение А`, `Приложение Б`);
- Изменения — фиксируются в *Листе регистрации изменений* (обязательно при обновлении документа).

---

## 4. Пошаговое руководство по написанию Руководства системного программиста  

Рекомендуется писать документ **в следующем порядке**, даже если в итоге разделы будут переупорядочены или объединены. Такой порядок гарантирует логическую полноту и минимизирует необходимость переписывания.

---

### Шаг 1. Подготовка информационной части  
#### 1.1 Аннотация  
**Объём**: 3–7 строк.  
**Цель**: дать читателю (администратору, техническому писателю, аудитору) мгновенное представление о документе.  

**Структура аннотации**:

```markdown
Документ «Руководство системного программиста» для [Наименование ПО]  
предназначен для специалистов, осуществляющих установку, настройку,  
проверку работоспособности и сопровождение системы в эксплуатационной  
среде. Содержит описание структуры ПО, порядка конфигурирования,  
критериев проверки и интерпретации диагностических сообщений.

✅ Обязательно: указать аудиторию, цель документа, охват разделов.
❌ Не включать: историю создания, сравнения с конкурентами, маркетинговые формулировки.

1.2 Содержание

Генерируется автоматически (например, в mkdocs.yml, Docusaurus, Confluence).
Требования:

Уровень вложенности — до 3-го (например: 2.3.1);
Включать приложения;
Не включать титульный лист, аннотацию, лист изменений.

Шаг 2. Раздел 1. Общие сведения о программе

Цель: обеспечить быстрое позиционирование ПО в инфраструктуре.

Что включать (обязательно):

Подраздел	Содержание	Пример формулировки
1.1 Назначение	Для чего предназначено ПО, в каком контексте используется.	«Система XCore предназначена для централизованного сбора, нормализации и кэширования метрик производительности распределённых сервисов в режиме реального времени».
1.2 Функции	Краткий перечень ключевых функций (не детализировать — это в ТЗ или Описании ПО).	- Приём телеметрии по протоколам Prometheus/StatsD; - Хранение временных рядов в локальном хранилище (до 72 ч); - Экспорт агрегированных данных в ELK.
1.3 Требования к среде исполнения	Строгая спецификация (версии, параметры, зависимости).	`markdown - ОС: Ubuntu 22.04 LTS (amd64), ядро ≥ 5.15.0; - CPU: ≥ 2 vCPU; - RAM: ≥ 4 ГБ; - Дисковое пространство: ≥ 20 ГБ (SSD, ext4); - Сетевые порты: 9100/UDP (вход), 8080/TCP (API); - Библиотеки: glibc ≥ 2.35, libssl3, zlib1g ≥ 1.2.11; - Runtime: OpenJDK 17.0.8 (LTS).`

⚠️ Важно: Не ссылаться на «стандартную инсталляцию Linux». Указывать конкретные дистрибутивы и версии — иначе документ неприменим в production.

Шаг 3. Раздел 2. Структура программы

Цель: дать представление о модульности и компонентах системы — без погружения в исходный код.

Что включать (обязательно):

Диаграмма компонентов (в приложении или в тексте);
Список модулей с кратким назначением;
Способы взаимодействия (IPC, REST, gRPC, shared memory);
Зависимости от сторонних ПО (например: XCore → PostgreSQL v14+, Redis 6.2+).

Шаблон подраздела:

2.1. Состав программных модулей

Модуль	Тип	Назначение	Взаимодействие
`xcore-ingest`	daemon (systemd)	Приём и предварительная фильтрация метрик	← UDP:9100, → `xcore-buf` (TCP/9101)
`xcore-buf`	демон буферизации	Буферизация и контроль переполнения	← `xcore-ingest`, → `xcore-store` (gRPC), → `stdout` (лог)
`xcore-store`	сервис хранения	Запись в локальное хранилище (TSDB)	← `xcore-buf`, ← HTTP API (порт 8080)

✅ Рекомендовано: использовать таблицу — она компактна и структурирована.
💡 Совет: если ПО содержит >10 модулей, выносить полную схему в Приложение А.

2.2. Внешние зависимости

Базы данных: PostgreSQL 14, схема xcore_metrics, пользователь xcore_rw;
Очереди: не используются (опционально — RabbitMQ 3.11+ для расширенного режима);
Сторонние API: /auth — OAuth2 endpoint для проверки токена (опционально).

Шаг 4. Раздел 3. Настройка программы

Цель: сделать процесс развёртывания воспроизводимым и атомарным.

Что включать (обязательно):

Порядок установки (пакетный менеджер / бинарный архив / контейнер);
Описание файлов конфигурации (расположение, формат, права);
Параметры с пояснениями;
Примеры типовых сценариев.

Шаблонная структура:

3.1. Установка

# Debian/Ubuntu
curl -fsSL https://repo.xcore.example/apt/gpg | sudo gpg --dearmor -o /usr/share/keyrings/xcore-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/xcore-archive-keyring.gpg] https://repo.xcore.example/apt stable main" | sudo tee /etc/apt/sources.list.d/xcore.list
sudo apt update && sudo apt install xcore-full

✅ Включать контрольную сумму (SHA256) бинарного дистрибутива при ручной загрузке.

3.2. Конфигурационные файлы

Файл	Формат	Режим доступа	Назначение
`/etc/xcore/config.yaml`	YAML	644 (root:root)	Основные параметры: порты, пути, политики
`/etc/xcore/storage.d/tsdb.conf`	INI	640 (root:xcore)	Параметры TSDB: retention, compaction
`/etc/systemd/system/xcore.service.d/override.conf`	systemd drop-in	644	Настройка лимитов (RAM, FD, CPU)

3.3. Ключевые параметры (фрагмент `/etc/xcore/config.yaml`)

# 3.3.1. Сетевые настройки
Сеть:
  # Порт для приёма метрик (UDP)
  ingest_port: 9100           # integer, default: 9100, range: 1024–65535
  # Интерфейс привязки (0.0.0.0 — все)
  bind_address: "0.0.0.0"     # string, IPv4/IPv6

# 3.3.2. Буферизация
buffer:
  # Размер кольцевого буфера (в элементах)
  capacity: 10000             # integer ≥ 1000, default: 5000
  # Задержка сброса при неполном буфере (мс)
  flush_timeout_ms: 500       # integer 10–5000, default: 200

# 3.3.3. Логирование
logging:
  level: "INFO"              # enum: DEBUG, INFO, WARN, ERROR
  file: "/var/log/xcore/main.log"
  rotate: true
  max_size_mb: 100

⚠️ Каждый параметр сопровождать:

типом (integer, string, enum…);

диапазоном/валидными значениями;

значением по умолчанию;

кратким пояснением смысла.

3.4. Типовые сценарии настройки

Минимальная инсталляция (один хост, RAM < 6 ГБ) → параметры buffer.capacity=2000, tsdb.retention_hours=24;
Высоконагрузочная инсталляция (кластер, 100k+ метрик/сек) → включить buffer.disk_spill=true, настроить systemd на MemoryMax=8G.

Шаг 5. Раздел 4. Проверка программы

Цель: обеспечить объективную верификацию работоспособности — без субъективных оценок («вроде работает»).

Что включать (обязательно):

Контрольные примеры (input → expected output);
Способы прогона (CLI, REST, UI);
Критерии приёма (количественные и качественные);
Логи и метрики для подтверждения.

Шаблон:

4.1. Контрольный прогон (базовый сценарий)

Шаг	Действие	Ожидаемый результат	Критерий успеха
1	`systemctl start xcore`	Служба активна, PID записан	`systemctl is-active xcore` → `active`
2	`echo "cpu.util 42 $(date +%s)" \| nc -u localhost 9100`	Метрика принята, без ошибок в логе	В `/var/log/xcore/main.log`: `INFO ingest: accepted metric 'cpu.util'`
3	`curl -s http://localhost:8080/metrics/cpu.util?last=1`	JSON с одним значением	Тело ответа: `{"values": [{"t": ..., "v": 42}]}`
4	`systemctl stop xcore`	Корректное завершение	В логе: `INFO shutdown: flushed 1 metrics, exit code 0`

4.2. Дополнительные проверки

Стресс-тест: генерация 10 000 метрик/сек в течение 5 мин → задержка обработки ≤ 10 мс (измеряется через xcore-metrics-cli --latency);
Отказоустойчивость: убить xcore-buf → автоматический рестарт (через systemd); метрики не теряются (буфер сохраняется на диск при disk_spill=true).

✅ Критерии проверки должны быть измеримы и автоматизируемы.
💡 Рекомендуется прикладывать скрипты проверки в Приложение Б.

Шаг 6. Раздел 5. Дополнительные возможности (опционально)

Включается, только если есть:

режимы работы (например, --debug, --readonly);
плагины, расширения;
альтернативные протоколы или алгоритмы.

Структура:

5.1. Режим отладки
5.2. Поддержка TLS для входящего трафика
5.3. Интеграция с Prometheus Remote Write

❗ Если таких возможностей нет — раздел опускается (согласно Изменению №1).

Шаг 7. Раздел 6. Сообщения системному программисту

Цель: превратить «сырые» логи в действенные инструкции.

Формат записи для каждого сообщения:

Поле	Обязательность	Пример
Идентификатор	рекомендуется	`ERR-1003`
Текст сообщения	✅	`[ERROR] db.connect: connection refused to localhost:5432`
Условие возникновения	✅	Невозможно установить соединение с PostgreSQL при запуске `xcore-store`
Влияние	✅	Хранение метрик недоступно; буферизация работает, но данные не сохраняются
Рекомендуемые действия	✅	1. Проверить, запущен ли PostgreSQL: `systemctl status postgresql`; 2. Убедиться, что `pg_hba.conf` разрешает подключения от пользователя `xcore_rw`; 3. Проверить параметры `db.host`, `db.port`, `db.user` в `/etc/xcore/config.yaml`.

✅ Группировать сообщения по фазам: Настройка, Запуск, Работа, Аварийное завершение.
🔁 Можно использовать таблицу (см. выше) или details-блоки в Markdown.

Пример в Markdown:

ERR-2015: Buffer overflow — dropped 1024 metrics

Условие: входящий поток метрик превысил buffer.capacity, включён buffer.drop_on_overflow=true
Влияние: потеря данных; качество мониторинга снижено
Действия:
1. Увеличить buffer.capacity или включить buffer.disk_spill;
2. Настроить предупреждение по метрике xcore_buffer_drop_total > 0;
3. Проанализировать источник — возможно, аномалия в клиентском ПО.

5. Пример: Руководство системного программиста для вымышленной системы XCore

💡 Примечание: Весь документ целиком (включая титульный лист, лист изменений, приложения) занял бы ~18–22 страницы формата А4. Здесь приведены содержательно насыщенные, но не избыточные фрагменты — ровно то, что требуется по стандарту и применимо на практике.

Аннотация

Документ «Руководство системного программиста» для системы XCore предназначен для специалистов по эксплуатации, отвечающих за установку, настройку, верификацию и сопровождение ПО в производственной среде. Содержит описание архитектуры, порядок конфигурирования, методику проверки работоспособности, интерпретацию диагностических сообщений и рекомендации по устранению типовых неисправностей.

Содержание

Общие сведения о программе
Структура программы
Настройка программы
Проверка программы
Дополнительные возможности
Сообщения системному программисту
Приложение А. Схема компонентов
Приложение Б. Скрипты проверки

1. Общие сведения о программе

1.1. Назначение

Система XCore предназначена для централизованного приёма, буферизации и краткосрочного хранения временных рядов (метрик производительности) от распределённых сервисов. Обеспечивает отказоустойчивую передачу данных в анализирующие системы (например, ELK, Grafana) при кратковременных сбоях сети.

1.2. Функции

Приём метрик по протоколам:
- StatsD (UDP, порт 8125);
- Prometheus Text Exposition (HTTP POST /metrics, порт 8080);
Буферизация с защитой от переполнения (в памяти и на диске);
Локальное хранение временных рядов (до 72 ч, формат TSDB);
Экспорт:
- REST API (GET /metrics/{name}),
- Prometheus Remote Write (опционально),
- Kafka (опционально).

1.3. Требования к техническим и программным средствам

Категория	Требование
Аппаратное обеспечение	2 vCPU, 4 ГБ RAM, 50 ГБ SSD (ext4 или XFS), сетевой интерфейс `≥` 1 Гбит/с
Операционная система	Ubuntu 22.04 LTS (x86_64 или aarch64), ядро `≥` 5.15; альтернативно: RHEL 9.x (с EPEL)
Программное обеспечение	OpenJDK 17.0.8 (LTS), `systemd ≥ 249`, `glibc ≥ 2.35`, `libssl3`, `zlib1g`
Сетевые требования	Открыты порты: 8125/UDP (ingest), 8080/TCP (API), 2181/TCP (ZooKeeper — опционально)
Права доступа	Процесс запускается от пользователя `xcore`; каталог `/var/lib/xcore` — владельцем `xcore:xcore`, права `750`

2. Структура программы

2.1. Состав модулей

Модуль	Тип	Взаимодействие	Зависимости
`xcore-ingest`	systemd-сервис	← UDP:8125, ← HTTP POST /metrics (8080) → `xcore-buf` (gRPC, 127.0.0.1:9001)	—
`xcore-buf`	systemd-сервис	← `xcore-ingest`, ← CLI `xcore-ctl`, → `xcore-store`, → `/var/log/xcore/buf.log`	`libprotobuf-lite`
`xcore-store`	systemd-сервис	← `xcore-buf`, ← HTTP GET `/metrics/*` (8080), → `/var/lib/xcore/tsdb/`	`leveldb ≥ 1.23`

2.2. Связи с другими программами

PostgreSQL 14+ — для хранения метаданных (таблица xcore.sources);
ZooKeeper 3.8+ — для координации в кластерном режиме (опционально);
Prometheus — как клиент (pull) или сервер (remote_write);
ELK Stack — экспорт логов через Filebeat (настроено отдельно).

📌 Схема компонентов приведена в Приложении А.

3. Настройка программы

3.1. Установка

# Ubuntu/Debian
curl -fsSL https://pkg.xcore.example/gpg.key | sudo gpg --dearmor -o /usr/share/keyrings/xcore.gpg
echo "deb [signed-by=/usr/share/keyrings/xcore.gpg] https://pkg.xcore.example/deb stable main" | sudo tee /etc/apt/sources.list.d/xcore.list
sudo apt update && sudo apt install xcore

Проверка целостности (при ручной загрузке):

sha256sum xcore_1.4.2_amd64.deb
# Должно быть: 3a7d4e8c2b1f0... (значение из https://pkg.xcore.example/checksums.txt)

3.2. Конфигурационные файлы

Файл	Описание
`/etc/xcore/xcore.yaml`	Основной конфиг (YAML); права `640`, владелец `root:xcore`
`/etc/systemd/system/xcore-ingest.service.d/limits.conf`	Лимиты: `LimitNOFILE=65536`, `MemoryMax=1G`
`/var/lib/xcore/tsdb/config.ini`	Параметры TSDB: `retention_hours = 72`, `compaction_interval_min = 60`

3.3. Пример конфигурации (`/etc/xcore/xcore.yaml`)

# XCore 1.4 — основной конфигурационный файл
ingest:
  statsd_port: 8125          # UDP-порт для StatsD (0 — отключить)
  http_port: 8080            # HTTP-порт для /metrics (0 — отключить)
  max_packet_size: 1400      # байт; max UDP payload

buffer:
  memory_capacity: 10000     # элементов; min 1000, default 5000
  disk_spill: true           # сбрасывать в /var/lib/xcore/spill/ при переполнении
  spill_path: "/var/lib/xcore/spill"
  drop_on_overflow: false    # если true — терять метрики, если буфер и диск заполнены

store:
  path: "/var/lib/xcore/tsdb"
  retention_hours: 72        # автоматическое удаление старых данных
  write_batch_size: 1000

logging:
  level: "INFO"
  file: "/var/log/xcore/xcore.log"
  rotate: true
  max_size_mb: 200

3.4. Настройка прав доступа

sudo useradd -r -s /usr/sbin/nologin xcore
sudo mkdir -p /var/lib/xcore/{tsdb,spill}
sudo chown -R xcore:xcore /var/lib/xcore
sudo chmod 750 /var/lib/xcore
sudo systemctl daemon-reload

4. Проверка программы

4.1. Базовый прогон

№	Действие	Команда / шаг	Ожидаемый результат
1	Запуск	`sudo systemctl start xcore-ingest xcore-buf xcore-store`	Все службы активны: `active (running)`
2	Отправка метрики	`echo "test.metric:42	g" \| nc -u localhost 8125`
3	Чтение	`curl -s http://localhost:8080/metrics/test.metric?last=1`	`{"name":"test.metric","values":[{"t":1731234567,"v":42}]}`
4	Проверка хранилища	`ls -lh /var/lib/xcore/tsdb/`	Появился файл `test.metric.ldb` (`>`0 байт)

4.2. Критерии приёма

Все три службы работают без ошибок в течение ≥ 5 мин;
Задержка от отправки до доступности через API ≤ 500 мс (на нагрузке ≤ 10 тыс. м/с);
Логи не содержат записей уровня ERROR или FATAL;
Потребление памяти ≤ 1.2 ГБ (при memory_capacity=10000).

5. Дополнительные возможности

5.1. Включение TLS для HTTP-интерфейса

Положить сертификаты:
- /etc/xcore/ssl/tls.crt (публичный),
- /etc/xcore/ssl/tls.key (приватный);

В xcore.yaml:

ingest:
  https_port: 8443
  tls_cert: "/etc/xcore/ssl/tls.crt"
  tls_key: "/etc/xcore/ssl/tls.key"

Перезапустить xcore-ingest.

⚠️ Требования: сертификат должен быть валиден (не просрочен, CN/SubjectAltName включает хост).

5.2. Экспорт в Kafka

Активируется через параметр:

export:
  kafka:
    enabled: true
    brokers: ["kafka1:9092", "kafka2:9092"]
    topic: "xcore-metrics"
    batch_size: 500

6. Сообщения системному программисту

ID	Текст сообщения	Условие	Действия
`ERR-1001`	`[ERROR] ingest: bind failed on 0.0.0.0:8125 — Address already in use`	Порт занят другим процессом (например, `statsd`)	1. `sudo ss -ulpn \| grep :8125`; 2. Остановить конфликтующий сервис или изменить `statsd_port` в конфиге.
`ERR-2005`	`[FATAL] store: failed to open DB at '/var/lib/xcore/tsdb': Permission denied`	Неправильные права на каталог	1. `ls -ld /var/lib/xcore/tsdb`; 2. `sudo chown -R xcore:xcore /var/lib/xcore`.
`WARN-3012`	`[WARN] buf: disk spill active — /var/lib/xcore/spill usage 85%`	Диск для спилла заполнен `>`80%	1. Увеличить `spill_path` на более ёмкий том; 2. Настроить мониторинг по метрике `xcore_spill_usage_percent`.
`INFO-4001`	`[INFO] shutdown: flushed 1248 metrics, exit code 0`	Штатное завершение	Нормально — данные не потеряны.

📌 Полный перечень сообщений — в машинно-читаемом формате JSON: /usr/share/doc/xcore/messages.json.

6. Проверочный чек-лист для автора/редактора

Используйте этот список до сдачи документа в ревью. Все пункты должны быть выполнены.

🔹 Общие требования (ГОСТ 19.105–78)

Есть титульный лист (с обозначением ГОСТ 19.503–79, наименованием ПО, номером документа);
Есть Лист регистрации изменений (даже если изменений пока нет — шаблон обязателен);
Аннотация (3–7 строк), отдельно от введения;
Содержание со сквозной нумерацией до 3-го уровня;
Все таблицы и рисунки пронумерованы и подписаны;
Приложения обозначены заглавными буквами (А, Б, В…);
Нумерация разделов — десятичная (1, 1.1, 1.1.3).

🔹 Содержание по разделам (ГОСТ 19.503–79)

Раздел 1: назначение, функции, требования к среде — конкретика (версии, объёмы, порты);
Раздел 2: структура — модули, связи (внутренние/внешние), зависимости;
Раздел 3: настройка — команды, пути, параметры с типами, диапазонами, значениями по умолчанию;
Раздел 4: проверка — контрольные примеры с измеримыми критериями (не «работает/не работает»);
Раздел 5: включён только при наличии дополнительных функций; иначе — опущен;
Раздел 6: сообщения — для каждого: текст, условие, влияние, конкретные действия.

🔹 Педагогические и практические критерии

Нет ссылок на «стандартную ОС» — только конкретные дистрибутивы и версии;
Нет «разработческих» деталей (алгоритмы, классы, API-контракты внутренних модулей);
Все команды и конфиги — в блоках кода с указанием языка/формата;
В логах и сообщениях — реалистичные форматы (не Error! → [ERROR] module: detail…);
Есть хотя бы один типовой сценарий настройки (минимальный/максимальный);
Есть хотя бы один пример устранения ошибки в разделе 6.

✅ При выполнении всех пунктов документ соответствует ГОСТ 19.503–79 и применим в реальных проектах — от корпоративных внедрений до государственных контрактов.

См. также

Другие статьи этого же раздела в боковом меню (как на странице «О разделе»).

Руководство системного программиста (ГОСТ 19.503–79)​

1. Обзор стандарта ГОСТ 19.503–79​

1.1. Назначение стандарта​

1.2. Область применения​

1.3. Соответствие международным аналогам​

1.4. Структура документа по ГОСТ​

2. Типичные ошибки при написании и как их избежать​

1.2 Содержание​

Шаг 2. Раздел 1. Общие сведения о программе​

Шаг 3. Раздел 2. Структура программы​

Шаблон подраздела:​

2.1. Состав программных модулей​

2.2. Внешние зависимости​

Шаг 4. Раздел 3. Настройка программы​

Шаблонная структура:​

3.1. Установка​

3.2. Конфигурационные файлы​

3.3. Ключевые параметры (фрагмент /etc/xcore/config.yaml)​

3.4. Типовые сценарии настройки​

Шаг 5. Раздел 4. Проверка программы​

Шаблон:​

4.1. Контрольный прогон (базовый сценарий)​

4.2. Дополнительные проверки​

Шаг 6. Раздел 5. Дополнительные возможности (опционально)​

Шаг 7. Раздел 6. Сообщения системному программисту​

5. Пример: Руководство системного программиста для вымышленной системы XCore​

Аннотация​

Содержание​

1. Общие сведения о программе​

1.1. Назначение​

1.2. Функции​

1.3. Требования к техническим и программным средствам​

2. Структура программы​

2.1. Состав модулей​

2.2. Связи с другими программами​

3. Настройка программы​

3.1. Установка​

3.2. Конфигурационные файлы​

3.3. Пример конфигурации (/etc/xcore/xcore.yaml)​

3.4. Настройка прав доступа​

4. Проверка программы​

4.1. Базовый прогон​

4.2. Критерии приёма​

5. Дополнительные возможности​

5.1. Включение TLS для HTTP-интерфейса​

5.2. Экспорт в Kafka​

6. Сообщения системному программисту​

6. Проверочный чек-лист для автора/редактора​

🔹 Общие требования (ГОСТ 19.105–78)​

🔹 Содержание по разделам (ГОСТ 19.503–79)​

🔹 Педагогические и практические критерии​

См. также

📄️Техническое письмо

📄️Документация

📄️Виды документации

📄️Технический писатель

📄️Качество документации

📄️Архитектура документации

📄️Экосистема технического письма

📄️Стилевые паттерны технической документации

📄️Техническое задание по ГОСТ

📄️Спецификация по ГОСТ

📄️ПМИ по ГОСТ

📄️ПЗ по ГОСТ

Руководство системного программиста (ГОСТ 19.503–79)

1. Обзор стандарта ГОСТ 19.503–79

1.1. Назначение стандарта

1.2. Область применения

1.3. Соответствие международным аналогам

1.4. Структура документа по ГОСТ

2. Типичные ошибки при написании и как их избежать

1.2 Содержание

Шаг 2. Раздел 1. Общие сведения о программе

Шаг 3. Раздел 2. Структура программы

Шаблон подраздела:

2.1. Состав программных модулей

2.2. Внешние зависимости

Шаг 4. Раздел 3. Настройка программы

Шаблонная структура:

3.1. Установка

3.2. Конфигурационные файлы

3.3. Ключевые параметры (фрагмент `/etc/xcore/config.yaml`)

3.4. Типовые сценарии настройки

Шаг 5. Раздел 4. Проверка программы

Шаблон:

4.1. Контрольный прогон (базовый сценарий)

4.2. Дополнительные проверки

Шаг 6. Раздел 5. Дополнительные возможности (опционально)

Шаг 7. Раздел 6. Сообщения системному программисту

5. Пример: Руководство системного программиста для вымышленной системы XCore

Аннотация

Содержание

1. Общие сведения о программе

1.1. Назначение

1.2. Функции

1.3. Требования к техническим и программным средствам

2. Структура программы

2.1. Состав модулей

2.2. Связи с другими программами

3. Настройка программы

3.1. Установка

3.2. Конфигурационные файлы

3.3. Пример конфигурации (`/etc/xcore/xcore.yaml`)

3.4. Настройка прав доступа

4. Проверка программы

4.1. Базовый прогон

4.2. Критерии приёма

5. Дополнительные возможности

5.1. Включение TLS для HTTP-интерфейса

5.2. Экспорт в Kafka

6. Сообщения системному программисту

6. Проверочный чек-лист для автора/редактора

🔹 Общие требования (ГОСТ 19.105–78)

🔹 Содержание по разделам (ГОСТ 19.503–79)

🔹 Педагогические и практические критерии