Руководство системного программиста по ГОСТ 19.503-79
Теория данных (раздел 3)
ERD и словарь сущностей — Entity Relationship, нормализация, SQL. Карта — о разделе.
Руководство системного программиста (ГОСТ 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. Установка
```bash
# 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`)
<ExternalCodeEmbed example="yaml/project-7-7-08-tehnicheskoe-pismo-16-001" title="Шаблонная структура" minHeight={426} />
> ⚠️ Каждый параметр сопровождать:
> - **типом** (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 | Запуск службы xcore | Служба активна, PID записан | статус **active** |
| 2 | Отправка метрики по UDP | Метрика принята, без ошибок в логе | В `/var/log/xcore/main.log`: `INFO ingest: accepted metric 'cpu.util'` |
| 3 | Чтение через HTTP API | JSON с одним значением | Тело ответа: `{"values": [{"t": ..., "v": 42}]}` |
| 4 | Остановка службы | Корректное завершение | В логе: `INFO shutdown: flushed 1 metrics, exit code 0` |
Команды контрольного прогона (копировать в скрипт проверки):
```bash
sudo systemctl start xcore
systemctl is-active xcore # → active
echo "cpu.util 42 $(date +%s)" | nc -u localhost 9100
curl -s "http://localhost:8080/metrics/cpu.util?last=1"
sudo systemctl stop xcore
```
---
##### 4.2. Дополнительные проверки
- **Стресс-тест**: генерация 10 000 метрик/сек в течение 5 мин → задержка обработки ≤ 10 мс:
```bash
xcore-metrics-cli --latency --duration 5m --rate 10000
```
- **Отказоустойчивость**: убить `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` |
| **Влияние** | ✅ | Хранение метрик недоступно; буферизация работает, но данные не сохраняются |
| **Рекомендуемые действия** | ✅ | см. блок диагностики ниже |
```bash
systemctl status postgresql
psql -h localhost -U xcore_rw -d xcore -c 'SELECT 1'
# pg_hba.conf — host xcore xcore_rw 10.0.0.0/24 scram-sha-256
# /etc/xcore/config.yaml — db.host, db.port, db.user
```
> ✅ Группировать сообщения по **фазам** — *Настройка*, *Запуск*, *Работа*, *Аварийное завершение*.
> 🔁 Можно использовать таблицу (см. выше) или `details`-блоки в Markdown.
Пример в Markdown:
<details>
<summary><b>ERR-2015: Buffer overflow — dropped 1024 metrics</b></summary>
- **Условие**: входящий поток метрик превысил `buffer.capacity`, включён `buffer.drop_on_overflow=true`
- **Влияние**: потеря данных; качество мониторинга снижено
- **Действия**:
1. Увеличить `buffer.capacity` или включить `buffer.disk_spill`;
2. Настроить предупреждение по метрике `xcore_buffer_drop_total > 0`;
3. Проанализировать источник — возможно, аномалия в клиентском ПО.
</details>
---
## 5. Пример — Руководство системного программиста для вымышленной системы *XCore*
> 💡 Примечание — Весь документ целиком (включая титульный лист, лист изменений, приложения) занял бы ~18–22 страницы формата А4. Здесь приведены **содержательно насыщенные, но не избыточные** фрагменты — ровно то, что требуется по стандарту и применимо на практике.
---
### Аннотация
Документ "Руководство системного программиста" для системы *XCore* предназначен для специалистов по эксплуатации, отвечающих за установку, настройку, верификацию и сопровождение ПО в производственной среде. Содержит описание архитектуры, порядок конфигурирования, методику проверки работоспособности, интерпретацию диагностических сообщений и рекомендации по устранению типовых неисправностей.
---
### Содержание
1. Общие сведения о программе
2. Структура программы
3. Настройка программы
4. Проверка программы
5. Дополнительные возможности
6. Сообщения системному программисту
Приложение А. Схема компонентов
Приложение Б. Скрипты проверки
---
### 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. Установка
```bash
# 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
```
Проверка целостности (при ручной загрузке):
```bash
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`)
<ExternalCodeEmbed example="yaml/project-7-7-08-tehnicheskoe-pismo-16-002" title="3.3. Пример конфигурации (`/etc/xcore/xcore.yaml`)" minHeight={462} />
---
#### 3.4. Настройка прав доступа
```bash
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 | Запуск трёх служб | Все службы **active (running)** |
| 2 | Отправка тестовой метрики | В логе: `INFO ingest: accepted gauge 'test.metric'` |
| 3 | Чтение через API | JSON с значением метрики |
| 4 | Проверка файла в TSDB | Появился `test.metric.ldb` (> 0 байт) |
```bash
sudo systemctl start xcore-ingest xcore-buf xcore-store
systemctl is-active xcore-ingest xcore-buf xcore-store
echo "test.metric:42|g" | nc -u localhost 8125
curl -s "http://localhost:8080/metrics/test.metric?last=1"
ls -lh /var/lib/xcore/tsdb/
```
---
#### 4.2. Критерии приёма
- Все три службы работают без ошибок в течение `≥` 5 мин;
- Задержка от отправки до доступности через API `≤` 500 мс (на нагрузке `≤` 10 тыс. м/с);
- Логи не содержат записей уровня `ERROR` или `FATAL`;
- Потребление памяти `≤` 1.2 ГБ (при `memory_capacity=10000`).
---
### 5. Дополнительные возможности
#### 5.1. Включение TLS для HTTP-интерфейса
1. Положить сертификаты:
- `/etc/xcore/ssl/tls.crt` (публичный),
- `/etc/xcore/ssl/tls.key` (приватный);
2. В `xcore.yaml`:
```yaml
ingest:
https_port: 8443
tls_cert: "/etc/xcore/ssl/tls.crt"
tls_key: "/etc/xcore/ssl/tls.key"
```
3. Перезапустить `xcore-ingest`.
> ⚠️ Требования: сертификат должен быть валиден (не просрочен, CN/SubjectAltName включает хост).
---
#### 5.2. Экспорт в Kafka
Активируется через параметр:
```yaml
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 и применим в реальных проектах — от корпоративных внедрений до государственных контрактов.
---
## Дополнение — эксплуатационный фокус
### План первой диагностики
1. Проверить статус служб и зависимостей.
2. Проверить сетевые порты и доступ к хранилищу.
3. Выполнить контрольный запрос из раздела "Проверка".
4. Снять короткий срез логов и метрик.
---
### Что добавить в рабочее руководство
- карту каталогов с назначением каждого пути;
- таблицу "симптом -> причина -> действие";
- команду для безопасного сбора диагностического архива.
---
### Смежные материалы
- [Руководство оператора по ГОСТ](/encyclopedia/7-project/7-08-tehnicheskoe-pismo/18/)
- [Руководство по техническому обслуживанию по ГОСТ](/encyclopedia/7-project/7-08-tehnicheskoe-pismo/19/)
- [Руководство администратора по ГОСТ](/encyclopedia/7-project/7-08-tehnicheskoe-pismo/21/)