События (`event`)

Функция event отвечает за вывод технологических и audit-событий Netgap. Она используется для оперативной диагностики, расследования инцидентов и передачи логов в централизованное хранилище. Подробно состав audit-событий описан в статье Аудит.

Назначение

События делятся на два типа:

tech — технологические события приложения: запуск, ошибки, внутренние операции, сетевые взаимодействия;
audit — события аудита, которые предназначены для контроля значимых действий и последующего анализа безопасности.

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

Настройки

События задаются массивом observability.event_targets.

Поле	Значения	Описание
`level`	Например `error`, `warn`, `info`, `debug`, `trace`; для `Tech` также выражение `EnvFilter`	Фильтр уровня событий.
`target_id`	`Tech`, `Audit`	Тип событий, которые попадут в эту цель.
`target_destination`	`Console`, `File`, `Loki`	Куда доставлять события.
`target_args`	Строка	Аргументы цели: пусто для консоли, путь для файла, URL для Loki.
`format`	`Text`, `ColorizedANSI`, `Json`	Формат вывода. Для Loki требуется `json`.

Ограничения:

для file поле target_args должно содержать путь к файлу;
для loki поле target_args должно содержать URL Loki, а format должен быть json;
audit-события в файл записываются синхронно, чтобы снизить риск потери данных при сбоях;
для файлов используется ежедневная ротация.

Настройка `level`

Для target_id: Audit поле level задает обычный порог уровня audit-событий. Используйте стандартные уровни error, warn, info, debug, trace; на практике для аудита обычно применяется info, чтобы фиксировать все значимые audit-события, или warn/error, если нужно получать только предупреждения и ошибки.

Для target_id: Tech поле level обрабатывается как выражение EnvFilter из tracing-subscriber. Поэтому для технологических логов можно задавать как общий уровень, так и более точные правила для модулей и зависимостей.

Примеры значений level для Tech:

Значение	Что делает
`info`	Включает технологические события уровня `info` и выше.
`warn`	Оставляет только предупреждения и ошибки.
`debug`	Включает подробные диагностические сообщения.
`info,netgap_gateway=debug`	В целом оставляет `info`, но для модуля `netgap_gateway` включает `debug`.
`warn,netgap_executor=info,ng_shared::observability=debug`	В целом оставляет `warn`, но повышает детализацию для указанных модулей.

Прямая отправка в Loki из приложения может быть полезна, когда нужно уменьшить количество промежуточных звеньев в контуре доставки логов и быстрее получать события в централизованном хранилище, например для повышения прозрачности и безопасности. При этом такая схема создает дополнительную сетевую и вычислительную нагрузку на компоненты Netgap. Если в инфраструктуре уже используются агенты Loki или другие log collectors, допустимо писать события Netgap в файл и настраивать сбор этого файла штатным collector-ом.

Примеры конфигурации

Вывод технологических логов в консоль:

observability:
  service_name: netgap-gateway
  event_targets:
    - level: info
      target_id: Tech
      target_destination: Console
      target_args: ""
      format: ColorizedANSI

Раздельная доставка технологических и audit-событий:

observability:
  service_name: netgap-gateway
  event_targets:
    - level: info
      target_id: Tech
      target_destination: Loki
      target_args: http://loki.example.local:3100
      format: Json
    - level: info
      target_id: Audit
      target_destination: File
      target_args: /var/log/netgap/audit.log
      format: Json

Добавление меток для Loki:

observability:
  service_name: netgap-executor
  labels:
    env: production
    site: dc1
  event_targets:
    - level: warn
      target_id: Tech
      target_destination: Loki
      target_args: http://loki.example.local:3100
      format: Json

Запись событий в файл для последующего сбора агентом Loki или log collector-ом:

observability:
  service_name: netgap-gateway
  labels:
    env: production
    site: dc1
  event_targets:
    - level: info
      target_id: Tech
      target_destination: File
      target_args: /var/log/netgap/tech.log
      format: Json
    - level: info
      target_id: Audit
      target_destination: File
      target_args: /var/log/netgap/audit.log
      format: Json

В этом варианте collector на стороне пользователя читает файлы /var/log/netgap/tech.log и /var/log/netgap/audit.log, добавляет нужные инфраструктурные метки и доставляет записи в Loki или другое хранилище логов. Настройки collector-а зависят от выбранного агента и целевой платформы.

Результат и доставка

Результат работы функции — поток логовых событий.

console доставляет события в стандартный вывод процесса.
file записывает события в файл с ежедневной ротацией.
loki отправляет события в Loki; для цели автоматически добавляется метка service_name, а также пользовательские labels, если они указаны.

Для Loki поддерживаются две типовые схемы доставки: прямая отправка из Netgap через target_destination: Loki или запись в файл через target_destination: File с последующим сбором агентом Loki/log collector-ом. Второй вариант обычно лучше подходит, если сбор логов уже стандартизирован на уровне хостов или Kubernetes и нагрузку на приложение нужно минимизировать.

Варианты применения

локальная отладка и быстрый просмотр логов в консоли;
долговременное хранение audit-событий в файлах;
централизованный сбор логов в Loki и просмотр через Grafana;
разделение технических и audit-событий по разным хранилищам и политикам доступа.

Назначение​

Настройки​

Настройка level​

Примеры конфигурации​

Результат и доставка​

Варианты применения​