2.16. Конфигурация системы (config.yml)¶

2.16.1.1. types¶

Описание модели данных (типов объектов), которые будут сохраняться в системе. В качестве языка описания модели используется Avro Schema – см. подробнее раздел «Разработка доменной модели». Как правило, описание делается в отдельном файле с расширением .avsc, на который делается ссылка в этой секции. Например:

types: {__file: model.avsc}

2.16.1.2. functions¶

Описание функций, которые будут выполняться в конвейерах обработки объектов (секция pipelines). Для каждой функции указывается имя функции и исполняемая часть – Lua-код функции, который также обычно выносится в отдельный файл. Например:

functions:
  focus_routing: {__file: focus_routing.lua}

2.16.1.3. pipelines¶

Описание конвейеров обработки объектов (пайплайнов). Для каждого пайплайна указывается имя и входящие в него функции, заданные в секции functions. Например:

pipelines:
  connect_input_handle:
    - focus_routing

2.16.1.4. connector¶

Для кластерной роли connector настраиваются:

• input
• output
• routing

input

Параметры коннекторов для получения и первоначальной обработки (parsing) входящих запросов. Ряд параметров есть у всех типов коннекторов:

• name – имя коннектора (произвольное).
• type – тип коннектора. Поддерживаемые типы:
  • http – для запросов в формате JSON по HTTP;
  • soap – для запросов в формате XML (SOAP) по HTTP;
  • kafka – для интеграции с шиной данных Apache Kafka.
• pipeline – конвейер обработки входящих объектов, определенный в секции pipelines.

Помимо этих параметров, у некоторых типов коннекторов есть параметры, специфические только для них.

type: soap

• wsdl – схема WSDL, описывающая структуру входящего XML;
• success_response_body – шаблон ответа в случае успешной обработки запроса;
• error_response_body – шаблон ответа в случае ошибки;
• handlers – обработчики входящего запроса.

Например:

connector:
  input:
    - name: soap
      type: soap
      wsdl: {__file: Connect.wsdl}
      success_response_body: {__file: success_response_body.xml}
      error_response_body: {__file: error_response_body.xml}
      handlers:
        - function: Connect
          pipeline: connect_input_handle

type: kafka

• brokers – адреса (URL) брокеров сообщений;
• topics – темы сообщений;
• group_id – идентификатор группы подписчиков;
• token_name – имя токена приложения. Необходимо вначале сгенерировать токен в системе (см. описание процедуры) и далее указать имя токена (name) в качестве значения параметра. Токен будет использоваться для авторизации при обработке входящих сообщений, которые коннектор забирает из шины данных Apache Kafka. Поскольку формат сообщений шины не дает возможности передать токен в самом сообщении, токен указывается в конфигурации коннектора.

Например:

connector:
  input:
    - name: kafka
      type: kafka
      brokers:
        - localhost:9092
      topics:
        - orders
        - items
      group_id: kafka
      token_name: kafka_token
      pipeline: connect_input_handle

output

Параметры коннекторов для отправки исходящих запросов. Ряд параметров есть у всех типов коннекторов:

• name – имя коннектора (произвольное).
• type – тип коннектора. Поддерживаемые типы:
  • input_processor – для отправки объекта на роль input_processor;
  • http – для отправки объекта в формате JSON во внешнюю систему по HTTP;
  • soap – для отправки объекта в формате XML (SOAP) во внешнюю систему по HTTP;
  • kafka – для интеграции с шиной данных Apache Kafka;
  • smtp – для отправки запросов через SMTP-сервер;
  • dummy – для игнорирования объектов (пришедший объект никуда не отправляется).

Помимо этих параметров, у некоторых типов коннекторов есть параметры, специфические только для них.

type: http

• url – URL внешней системы, куда отправляется объект;
• format – формат, в котором оправляется объект. Для коннектора типа http формат – JSON.

Например:

connector:
  output:
    - name: to_external_http_service
      type: http
      url: http://localhost:8021/test_json_endpoint
      format: json

type: soap

• url – URL внешней системы, куда отправляется объект.

Например:

connector:
  output:
    - name: to_external_soap_service
      type: soap
      url: http://localhost:8020/test_soap_endpoint

type: kafka

• brokers – адреса (URL) брокеров сообщений;
• topic – тема сообщения.

Например:

connector:
  output:
    - name: to_kafka
      type: kafka
      brokers:
        - localhost:9092
      topic: objects

type: smtp

• url – URL сервера SMTP;
• from – имя отправителя, которое будет показываться в поле «From» при получении сообщения;
• subject – тема отправляемого сообщения;
• timeout – тайм-аут запроса к серверу SMTP, секунды;
• ssl_cert – путь к SSL-сертификату;
• ssl_key – путь к приватному ключу для SSL-сертификата.

Например:

connector:
  output:
    - name: to_smtp
      type: smtp
      url: localhost:2525
      from: tdg@localhost
      subject: TDG_Objects
      timeout: 5
      ssl_cert: ssl.crt
      ssl_key: ssl.pem

routing

Mаршрутизация объекта для отправки через определенный output, который определяется в зависимости от ключа маршрутизации key. Ключ маршрутизации объект получает в результате обработки в пайплайне, указанном в input. Если в input пайплайн не указан, объект обрабатывается пайплайном по умолчанию, которые превращает объект вида

{
  "obj_type": { "field_1": 1 }
}

в объект

{
  "field_1": 1
}

и задает значение ключа маршрутизации как routing_key = obj_type.

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

connector:
  routing:
    - key: input_processor
      output: to_input_processor

    - key: external_http_service
      output: to_external_http_service

    - key: external_soap_service
      output: to_external_soap_service

2.16.1.5. input_processor¶

Для кластерной роли input_processor настраиваются:

• classifiers
• routing
• storage

classifiers

Определение пользовательского пайплайна, выполняющего классификацию объектов. В результате классификации объекту присваивается нужный ключ маршрутизации, по которому определяются дальнейшие действия по его обработке. Если пайплайн не задан, объект никак не обрабатывается и направляется на обработку пайплайном, указанным в секции input_processor: routing.

routing

Маршрутизация объекта в определенный пайплайн обработки по ключу маршрутизации (параметр key).

storage

Настройки сохранения объекта в роли storage по ключу маршрутизации (параметр key). Параметр type определяет тип бизнес-объекта (агрегата).

Пример маршрута (порядка обработки) объекта

Рассмотрим порядок обработки объекта на примере конфигурации выше.

1. После попадания в систему на роль connector, объект будет обработан в соответствии с настройками конфигурации input в секции connector.

В нашем примере мы видим, что для всех возможных вариантов input (JSON via HHTP, XML via SOAP, Kafka) конвейер обработки указан один и тот же: pipeline: connect_input_handle.

2. В секции pipelines находим этот конвейер – он состоит из выполнения одной функции.

pipelines:
  connect_input_handle:
    - focus_routing

3. В секции functions мы видим, что исполняемый код этой функции находится в файле focus_routing.lua.

functions:
  ...
  focus_routing: {__file: focus_routing.lua}

Листинг кода:

local first = ...

local ret = {obj = first, priority = 1, routing_key = 'input_processor'}

return ret

Необработанный объект должен быть помещен в поле obj. Объекту будет присвоен ключ маршрутизации «input_processor».

4. Дальнейший маршрут объекта определяется настройками routing в секции connector. Для объектов с ключом маршрутизации «input_processor» это будет output: to_input_processor:

connector:

  routing:
    - key: input_processor
      output: to_input_processor

5. В секции connector находим данный output:

connector:

  output:
    - name: to_input_processor
      type: input_processor

Значение параметра type означает, что объект будет направлен на инстанс с ролью input_processor.

6. При попадании на роль input_processor объект прежде всего будет обрабатываться в соответствии с настройками из секции ниже:

input_processor:
  classifiers:
    - name: focus
      pipeline: focus_classifiers

В указанном здесь пайплайне будет выполняться следующий код из focus_classifier.lua:

local param = ...

local type_table =
    {
        ["Initiation"] =  "focus_initiation",
        ["Coupon Payment"] =  "focus_couponpayment",
        ["Exercise"] =  "focus_exercise",
        ["Rate Change"] =  "focus_ratechange"
    }

local node = lom.get_by_path(param.obj, 'message.header.routedata.event_type')

if node == nil then
    return param.obj
end

local event_type = string.strip(node[1])

param.routing_key = type_table[event_type]

return param

где lom.get_by_path – функция, которая берет значение из объекта по указанному пути. При этом путь записывается с разделением при помощи точки.

Допустим, что после обработки на данном этапе наш объект получит ключ маршрутизации «focus_couponpayment».

7. Дальнейшая обработка объекта с таким ключом маршрутизации будет определяться следующими настройками в секции input_processor:

input_processor:

  routing:
    - key: focus_couponpayment
      pipeline: coupon_payment_handle

  storage:
    - key: focus_couponpayment
      type: CouponPayment

Это означает, что сначала объект будет обработан в еще одном пайплайне – coupon_payment_handle, а потом направлен на роль storage как объект типа «CouponPayment». Данный тип должен быть описан в модели данных, которая определена в секции

types: {__file: model.avsc}

После успешной валидации по модели данных, объект будет сохранен на роли storage.

8. Если для данного ключа маршрутизации указаны еще какие-либо настройки в других секциях config.yml, объекты с этим ключом будут обработаны далее (см. пример про секцию output_processor).

2.16.1.6. output_processor¶

Задается логика обработки объектов, которые будут реплицироваться во внешние системы. Выполняется после успешного сохранения в объектов на инстансах с ролью storage.

Для объектов с определенным ключом маршрутизации определяется:

• каким пайплайном будет обработан объект;
• посредством какого output он будет отправляться во внешнюю систему.

В рассматриваемом примере:

output_processor:
  focus_couponpayment:
    pipeline: notification_filter
    output: to_external_http_service

Данные настройки означают, что объекты, которые на более ранних этапах обработки получили ключ маршрутизации «focus_couponpayment», будут вначале обработаны функциями из пайплайна notification_filter, а затем отосланы в соответствии с настройками указанного здесь output (смотрим эти настройки в секции connector):

connector:

  output:
    - name: to_external_http_service
      type: http
      url: http://localhost:8021/test_json_endpoint
      format: json

Аналогично определяется поведение роли output_processor в отношение объектов с другими ключами маршрутизации.

2.16.1.7. repair_queue¶

repair_queue:
  on_object_added:
    __unclassified__:
        postprocess_with_routing_key: unclassified

В данном примере настроен случай, когда определенные объекты, попавшие в ремонтную очередь, также должны быть реплицированы во внешнюю систему. В данном случае ранее на этапе классификации объект не удалось классифицировать, и ему было присвоено специальное значение ключа «__unclassified__», которым определяются неклассифицированные объекты.

При попадании такого объекта в ремонтную очередь, согласно настройкам postprocess_with_routing_key: unclassified, объекту присваивается другой ключ маршрутизации «unclassified», и с этим ключом он направляется на роль output_processor. Дальнейшая обработка объекта будет выполняться в соответствие с настройками в секции output_processor:

output_processor:
  unclassified:
    pipeline: notification_filter
    output: to_external_http_service

2.16.1.8. logger¶

В этой секции определяются настройки для кластерной роли logger.

• rotate_log – флаг (true/false), осуществлять ли ротацию лога;
• max_msg_in_log – максимальной количество сообщений, сохраняемых в логе;
• max_log_size – максимальный размер файла лога, в байтах;
• delete_by_n_msg – количество одновременно удаляемых сообщений при ротации лога. При превышении значений параметров max_msg_in_log или max_msg_log_size наиболее старые n сообщений в логе удаляются за раз, что повышает производительность по сравнению с режимом, когда старые сообщения удаляются по одному.

2.16.1.9. audit_log¶

В секции задаются следующие параметры для работы журнала аудита:

• enabled – включена (true) или выключена (false) запись событий в журнал аудита. По умолчанию: true.
• severity – уровень важности событий, которые будут записываться в журнал аудита. Возможные значения по возрастанию важности: VERBOSE, INFO, WARNINIG, ALARM. По умолчанию: INFO. При указании определенного уровня в журнал аудита будут записываться события этого уровня и выше. Например, если задано INFO, будут записываться события, соответствующие уровням INFO, WARNINIG и ALARM. Подробнее см. список событий, соответствующий каждому уровню.
• remove_older_than_n_hours – максимальное время хранения записей в журнале аудита, часы. Записи старше указанного времени удаляются. Значения по умолчанию нет.

2.16.1.10. tasks¶

В этой секции настраивается конфигурация задач, выполняемых при помощи ролей scheduler и task_runner. Например:

tasks:
  task_1:
    kind: single_shot
    pipeline: single_task
    keep: 5
  task_2:
    kind: continuous
    pipeline: long_task
    pause_sec: 10
  task_3:
    kind: periodical
    pipeline: long_task
    schedule: "0 */5 * * * *"

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

• task_N – имя задачи;
• kind – вид задачи: «single_shot», «continuous» или «periodical» (см. подробнее);
• pipeline – пайплайн, определяющий, что именно делается в рамках задачи;
• keep – количество завершенных экземпляров задачи, которые сохраняются в истории. По умолчанию: 10;
• pause_sec – пауза в выполнении задачи вида «continuous», секунды;
• schedule – расписание выполнения для задач вида «periodical». Задается в формате cron. Используется расширенный синтаксис, в котором минимальной величиной является секунда:

* * * * * *
| | | | | |
| | | | | ----- День недели (0-6) (Воскресенье = 0)
| | | | ------- Месяц (1-12)
| | | --------- День (1-31)
| | ----------- Час (0-23)
| ------------- Минута (0-59)
--------------- Секунда (0-59)

В примере выше значение параметра schedule: "0 */5 * * * *" означает, что задача будет запускаться периодически каждые 5 минут.

2.16.1.11. task_runner¶

running_count_threshold – порог количества выполняемых пайплайнов для задач (tasks) и отложенных работ (jobs). По умолчанию: 100.

Этот параметр не ограничивает количество запущенных пайплайнов: при превышении порога в журнале просто создается предупреждение «Too many running pipelines. Now running %d pipelines».

2.16.1.12. jobs¶

max_jobs_in_parallel – максимальное количество отложенных работ (jobs), которые могут выполняться одновременно. По умолчанию: 50.

Когда достигается указанное ограничение, отложенные работы сверх лимита устанавливаются в очередь и выполняются по мере возможности.

2.16.1.13. account_manager¶

Настройки кластерной роли account_manager, которая обеспечивает работу ролевой модели доступа и связанных с ней функций безопасности (см. подробнее).

• only_one_time_passwords – флаг (true/false). По умолчанию: false. Если указано значение true, будет запрещена возможность вручную задать пароль пользователя при его создании или импорте. TDG будет автоматически генерировать одноразовый пароль и высылать его на адрес электронной почты пользователя. Для отсылки пароля также необходимо иметь работающий сервер SMTP, описание его конфигурации в секции connector (output: type: smtp) и указание на этот output в секции account_manager:

  account_manager:
    only_one_time_passwords: true
    output:
      name: to_smtp
      options:
        subject: "Registration"
  

  Опционально можно указать заголовок письма, в котором высылается одноразовый пароль (options: subject:).

  Если указано значение only_one_time_passwords: false, то автоматическая генерация пароля и отсылка его пользователю также будет выполняться в случае, когда поле Password при создании пользователя оставлено пустым.

• password_change_timeout_seconds – минимальное время, которое должно пройти до следующей смены пароля, секунды. Значения по умолчанию нет.

• block_after_n_failed_attempts – количество неудачных попыток входа в систему, после которых пользователь будет заблокирован (статус пользователя станет «blocked»). Значения по умолчанию нет.

• ban_inactive_more_seconds – максимальное время, в течение которого пользователь может быть неактивен в системе, секунды. По истечении этого времени пользователь будет заблокирован. Максимально возможное значение параметра – 45 дней. Если значение превышает 45 дней или параметр не задан, будет взято значение по умолчанию, равное 45 дням.

• password_policy – настройки политики паролей. Эти настройки также можно задать через web-интерфейс.

  • min_length – минимальная допустимая длина пароля. По умолчанию: 8.
  • include – флаги (true/false), определяющие, какие категории символов должны обязательно входить в пароль:
    • lower – латинские буквы в нижнем регистре. По умолчанию: true.
    • upper – латинские буквы в верхнем регистре. По умолчанию: true.
    • digits – цифры от 0 до 9 включительно. По умолчанию: true.
    • symbols – дополнительные символы !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~. По умолчанию: false.

2.16.1.14. pepper¶

Строка символов, которая в целях усиления безопасности добавляется к паролю перед его хэшированием. Если данный параметр не указан в конфигурации, добавляется строка по умолчанию, определенная в коде системы.

2.16.1.15. auth_external¶

В настройке задается Lua-код или путь к файлу с Lua-кодом, в котором пользователь имеет возможность самостоятельно задать логику для авторизации входящих запросов. Код должен вернуть таблицу с параметром auth, в котором лежит функция для проверки входящих запросов в формате HTTP. Функция возвращает либо nil, если доступ запрещен, либо в противном случае – объект, содержащий аутентификационную информацию.

2.16.1.16. notifier¶

Настройки кластерной роли notifier.

• mail_server – секция настроек сервера SMTP, который используется для отправки нотификаций при попадании объекта в ремонтную очередь. Данные параметры также можно задать через web-интерфейс.
  • url – URL сервера SMTP;
  • from – имя отправителя, которое будет показываться в поле «From» при получении нотификации;
  • username – имя пользователя сервера SMTP;
  • password – пароль пользователя сервера SMTP;
  • timeout – тайм-аут запроса к серверу SMTP, секунды.
  • skip_verify_host – флаг (true/false): пропустить проверку хоста по протоколу TLS.
• users – секция, где задаются данные подписчиков (subscribers), которые будут получать нотификации. Подписчиков также можно создать через web-интерфейс.
  • id – идентификатор подписчика;
  • name – имя подписчика;
  • addr – e-mail подписчика.

2.16.1.17. services¶

Параметры, которые задаются для каждого из сервисов:

• type – тип запроса GraphQL для вызова сервиса: query или mutation. Если тип – query, параметр можно не указывать.
• function – ссылка на функцию, которая выполняет данный сервис. Функция должна быть описанна в конфигурации в секции functions.
• doc – произвольное описание сервиса.
• return_type – тип данных, который возвращается в результате выполнения сервиса.
• args – описание аргументов, передаваемых на вход при выполнении сервиса, в формате «имя_аргумента: тип_данных».

2.16.1.18. expiration¶

В секции задаются следующие параметры:

• type – тип объекта, в отношении которого задаются ограничения.
• lifetime_hours – время жизни объекта в часах. Объекты старше этой величины будут считаться устаревшими и подлежащими удалению. Значение по умолчанию: 24.
• delay_sec – интервал в секундах, через который запускается очередная проверка устаревших объектов и их удаление. Значение по умолчанию: 36000.
• keep_version_count – ограничение количества версий для объектов данного типа. По умолчанию: не ограничено.

Данные настройки также можно задать через web-интерфейс.

2.16.1.19. archivation¶

Определенные типы объектов могут поступать в систему в большом количестве, но при этом иметь короткое время активного использования, после чего потребность в обращении к ним возникает редко. Для этого случая реализован механизм архивации, когда такие объекты выгружаются из TDG и сохраняются отдельно на жестком диске.

Объекты сохраняются в текстовом виде в файлах формата .jsonl (формат имени – YYYY-MM-DDTHH:MM:SS.jsonl). Объекты записываются в файл построчно: один объект – одна строка вида {"TypeName": {... data ...}}, где TypeName – тип сохраняемого объекта.

Настройки архивации в конфигурации TDG:

• type – тип объекта.
• lifetime_days– время жизни объекта в TDG, дни. Объекты старше этой величины архивируется.
• schedule – расписание запуска задачи на архивацию в формате cron.
• dir – директория для хранения файлов с архивными данными.
• file_size_threshold – максимальный размер файла с архивными данными, байты. По достижении этого размера запись архивируемых данных начинается в новый файл. По умолчанию: 104857600 (100 Мб).

2.16.1.20. hard_limits¶

Для контроля нагрузки на сервер задаются следующие ограничения на выполнение GraphQL-запросов:

• scanned – запрос не должен проходить больше заданного количества кортежей в спейсах. По умолчанию: 2000.
• returned – запрос не должен возвращать больше заданного количества кортежей. По умолчанию: 100.

При превышения одного из ограничений выполнение запроса прекращается и возвращается ошибка.

2.16.1.21. force_yield_limits¶

force_yield_limits – ограничение на количество сканирований записей в спейсе. При достижении порога выполняется yield. По умолчанию: 1000.

Актуально при выполнении map_reduce, чтобы избежать зависаний на инстансах с ролью storage. Также учитывается при работе функций программного интерфейса репозитория.

2.16.1.22. graphql_query_chache_size¶

graphql_query_chache_size – размер кэша запросов GraphQL. Измеряется в количестве запросов, т.е. кэшируются N последних уникальных запросов в виде полного текста каждого запроса. По умолчанию: 3000.

2.16.1.23. vshard_timeout¶

vshard_timeout – время ожидания запроса, которое передается в vshard.callro/callrw, секунды. По умолчанию: 2.

Подробнее см. документацию по модулю vshard.

2.16.1.24. maintenance¶

clock_delta_threshold_sec – порог рассинхронизации истинного времени (CLOCK_REALTIME) на серверах, секунды. По умолчанию: 5.

При превышении порога в логе создается запись об ошибке «Time deviation threshold exceeded! Max clock delta is %s». Проверка синхронизации важна для операций, использующих метки времени, таких как логирование и аудит.

2.16.1.25. gc¶

Роль garbage_collector принудительно запускает сборку мусора в Lua. Роль включается неявно на всех инстансах.

Параметры:

• forced – включение (true) или отключение (false) принудительной сборки мусора. По умолчанию: false.
• period_sec – интервал, через который происходит запуск нового цикла сборки мусора, секунды.
• steps – размер шага сборщика мусора.

2.16.1.26. tracing¶

Настройки коммуникации с трейсинг-системой (tracing system), куда передаются данные для анализа производительности выполнения кода. Подробнее про настройки модуля, используемого для организации трейсинга кода, см. здесь.

• base_url – эндпойнт программного интерфейса (API endpoint), куда отсылаются собранные для анализа спаны (spans).
• api_method – тип HTTP-запроса для обращения к base_url. Для трейсинг-систем, поддерживающих протокол OpenZipkin, – POST.
• report_interval – интервал, через который в трейсинг-систему отсылаются накопленные спаны, секунды.
• spans_limit – размер буфера для накопления спанов перед отправкой в трейсинг-систему. Измеряется количеством спанов.

Например:

tracing:
  base_url: localhost:9411/api/v2/spans
  api_method: POST
  report_interval: 5
  spans_limit: 100

2.16.1.27. sequence_generator¶

Настройки, используемые при генерации последовательностей уникальных чисел:

• starts_with – число, с которого начинается последовательность. По умолчанию: 1.
• range_width – диапазон последовательности. По умолчанию: 100.

См. подробнее про функцию работы с последовательностью.

2.16.1.28. frontend¶

Роль используется для статического расширения пользовательского интерфейса. Параметры, определяемые в конфигурации:

• name – произвольное имя расширения.
• file – пути к файлам, реализующим расширение. Могут быть указаны файлы в формате .html, .css, .js.

Например:

frontend:
  - name: myapp
    files:
      "index.html":
        __file: app/index.html

2.16.1.29. test-soap-data¶

Параметр позволяет задать текст, который будет по умолчанию отображаться на закладке Test в web-интерфейсе. Может использоваться для удобства тестирования: в этой секции можно задать структуру тестового объекта в формате XML или JSON для имитации входящего запроса.

2.16.1.30. libraries¶

Настройка подключения пользовательских библиотек, которые могут использоваться в коде функций пайплайнов (см. секции functions и pipelines). Указывается имя библиотеки, которое будет использоваться в коде, и путь к файлу библиотеки, который загружается вместе с конфигурацией системы.

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

libraries:
  cache:
    __file: cached.lua
  utils:
    __file: utils.lua

Пример вызова:

Если в указанной в конфигурации библиотеке (например, utils.lua) определена функция

local function timediff(value)
    return (datetime.now() - value)
end

то в пользовательском коде функцию можно вызвать как utils.timediff(value).

2.16.1.31. welcome-message¶

Текст приветственного сообщения, которое будет появляться при входе в систему. Ограничения на количество символов в сообщении нет.