Changelog¶

This document contains up-to-date information regarding Tarantool Data Grid release notes. The log format is based on Keep a Changelog, and the versioning follows Semantic Versioning rules.

[2.12.6] – 2024-11-12
[2.12.5] – 2024-10-23
[2.12.4] – 2024-10-22
[2.12.3] – 2024-10-14
[2.12.2] – 2024-09-24
[2.12.1] – 2024-09-18
[2.12.0] – 2024-08-20
[2.11.5] – 2024-06-05
[2.11.4] – 2024-04-23
[2.11.3] – 2024-04-01
[2.11.2] – 2024-03-13
[2.11.1] – 2024-02-27
[2.11.0] – 2024-02-26
[2.10.0] – 2023-12-11
[2.9.0] – 2023-11-21
[2.8.0] – 2023-08-30
[2.7.2] – 2023-07-21
[2.7.1] – 2023-06-07
[2.7.0] – 2023-05-30
[2.6.9] – 2023-04-27
[2.6.8] – 2023-04-07
[2.6.7] – 2023-02-27
[2.6.6] – 2023-02-20
[2.6.5] – 2023-02-03
[2.6.4] – 2022-11-16
[2.6.3] – 2022-10-06
[2.6.2] – 2022-09-05
[2.5.3] – 2022-08-18
[2.5.2] – 2022-08-12
[2.6.1] – 2022-08-11
[2.6.0] – 2022-06-30
[2.5.1] – 2022-06-30
[2.5.0] — 2022-04-25
[2.4.0] — 2022-01-28
[2.3.0] — 2021-10-27
[2.2.0] — 2021-09-29
[2.1.1] — 2021-09-01
[2.1.0] — 2021-08-24

[2.12.6] – 2024-11-12 ¶

SDK обновлен до версии 2.11.4-0-r658.
Расширена информация о клиенте, записываемая в журнал аудита при неудачных попытках авторизации.

[2.12.5] – 2024-10-23 ¶

Исправлена ошибка при попытке использования фрагментов в GraphQL-запросах.

[2.12.4] – 2024-10-22 ¶

Исправлена ошибка при попытке указать две выборки в GraphQL-запросе.
Исправлена ошибка при указании уровня логирования в аргументе командной строки или переменной окружения.

[2.12.3] – 2024-10-14 ¶

Исправлена возможность обновления необнуляемого элемента массива на null.
Убран sandboxing из функции, использующейся при миграции спейсов. Теперь можно использовать произвольные функции Lua/Tarantool.
Исправлена ошибка при запуске миграций в режиме dry_run.
Исправлена некорректная обработка спанов при включенном трейсинге при ошибке обработки объектов из Kafka.

[2.12.2] – 2024-09-24 ¶

Исправлена ошибка Field version nullability mismatch.

[2.12.1] – 2024-09-18 ¶

Cartridge обновлен до версии 2.12.4.
SDK обновлен до версии 2.11.4-0-r653.

[2.12.0] – 2024-08-20 ¶

[Breaking change] Базовый образ для сборки проекта обновлен с CentOS 7 до AlmaLinux 8. Теперь проект может не работать на более старых дистрибутивах.
[Breaking change] Отключено сопоставление с Lua-шаблоном при поиске содержимого сообщений журнала.
Удалить поле из модели данных теперь можно без запуска миграции.
Исправлены ошибки, возникающие при обновлении полей-массивов.
Kafka consumer теперь логирует offset сообщения в случае возникновения проблем.
Исправлена ошибка, возникающая при запуске миграций в режиме dry_run для спейсов с отключенным версионированием.
Cartridge обновлен до версии 2.12.3.
metrics обновлен до версии 1.2.0.

[2.11.5] – 2024-06-05 ¶

Добавлен метод connector.http_request в sandbox.
Добавлена подсистема событий events.
Исправлено разыменование nil (nil dereference) при перезагрузке конфигурации в Kafka-клиенте.
Исправлена обработка ошибок маршрутизации.
Исправлен расчет размера журнала TDG (спейса tdg_log).
Добавлен доступ к странице веб-интерфейса Console для пользователей с привилегией eval.
Cartridge обновлен до версии 2.12.0.
SDK обновлен до версии 2.11.3-0-r636.

[2.11.4] – 2024-04-23 ¶

Исправлена ошибка: account provider watcher печатал ошибку при инициализации.
Cartridge обновлен до версии 2.10.0.
expirationd обновлен до версии 1.6.0.
SDK обновлен до версии 2.11.3-0-r631.

[2.11.3] – 2024-04-01 ¶

Добавлен фильтр полей для запросов на получение данных.
Исправлена ошибка table is nil в обнуляемом поле записи.
Исправлена ошибка vshard gc при балансировке.
Исправлена ошибка, связанная с передачей значений cdata в метрики.
Исправлено использование типа Union совместно с массивами.
Исправлено значение версии по умолчанию для схемы GraphQL.

[2.11.2] – 2024-03-13 ¶

Исправлена нумерация версий PRM-пакета.
Исправлено переполнение в значениях дат.
SDK обновлен до версии 2.11.2-0-r621.
Cartridge обновлен до версии 2.9.0.

[2.11.0] – 2024-02-26 ¶

[Breaking change] Изменен формат ошибок некоторых функций Repository API.
Добавлена возможность указания заголовков (headers) для Kafka-коннектора.
Исправлено некорректное отображение версии продукта при использовании Docker-образа.
Исправлена обработка параметра if_not_exists в repository.put_batch().
Исправлена неконсистентность ошибок, возвращаемых repository.put_batch().
SDK обновлен до версии 2.11.2-0-r616.
Cartridge обновлен до версии 2.8.6.

[2.10.0] – 2023-12-11 ¶

[Breaking change] Полностью удалена функциональность тенантов.
Добавлена возможность вызова repository.call_on_storage() без указания типа.
Исправлена некорректная сериализация массивов.
Исправлена обработка параметра pkey функции repository.get() при указании версии.
Исправлены ошибки в триггерах механизма версионирования.
SDK обновлен до версии 2.11.2-0-r609.

[2.9.0] – 2023-11-21 ¶

Updated¶

SDK обновлен до версии 2.11.1-0-r605.
Cartridge обновлен до версии 2.8.4.
Обновлены зависимости web UI.

Added¶

[Breaking change] Частично удалена функциональность тенантов.
Добавлена опция handler для Kafka-коннектора.
Добавлена обработка ошибок в Kafka-коннекторе.
Добавлены метрики обработчика исходящих данных.
Добавлена возможность использования (require) кода из конфигурации в расширениях.

Fixed¶

Исправлен вызов deinit до вызова init в роли scheduler.
Исправлено отсутствие сообщений об ошибках в Kafka consumer.
Исправлено удаление частей конфигурации коннекторов в веб-интерфейсе.

[2.8.0] – 2023-08-30 ¶

Updated¶

SDK обновлен до версии 2.11.1-0-r579.
Cartridge обновлен до версии 2.8.2.
expirationd обновлен до версии 1.5.0.
Обновлены зависимости для веб-интерфейса.

Added¶

[Breaking change] Удалены настройки тенантов из веб-интерфейса.
Модуль compress добавлен в sandbox.
Добавлены настройки Kafka consumer в sandbox: consumer_seek_partitions и consumer_metadata.
Добавлены настройки Kafka consumer в sandbox: consumer_pause, consumer_resume и consumer_status.
Добавлен параметр initial_state во входящую конфигурацию Kafka.
Добавлен менеджер для управления вводом Kafka с помощью флагов в etcd.
В сообщение Kafka consumer добавлено название коннектора.
Добавлены метрики для обработчика REST.
Для tdg_service_user добавлена возможность вызова функции box.info().
Добавлена поддержка алгоритма сжатия zlib для полей типов данных.

Fixed¶

Исправлен запуск задач перед бутстрапом vshard.
Исправлена обработка сложных нулевых типов в сервисах.
Исправлена визуальная ошибка в EditDataActionForm.
Исправлена обработка параметра lifetime_hours=0.

[2.7.2] – 2023-07-21 ¶

Cartridge обновлен до версии 2.8.1.
Добавлены аргументы first_n_on_storage и after функций delete и update.
Добавлена возможность чтения данных из Kafka в простом (plain) формате.
Добавлена возможность повтора попытки загрузки первых N объектов из ремонтной очереди.
Улучшена валидация имен функций.
Исправлена потеря обнуляемых полей типа “массив” в возвращаемых типах сервисов.
Исправлено присваивание значения null через GraphQL.

[2.7.1] – 2023-06-07 ¶

Исправлен обход директорий в процессе распаковки конфигурации.
Добавлен список допустимых расширений файлов в архиве с конфигурацией.

[2.7.0] – 2023-05-30 ¶

Updated¶

SDK обновлен до версии 2.11.0-0-r563.
Cartridge обновлен до версии 2.8.0.
metrics обновлен до версии 1.0.0.
kafka обновлен до версии 1.6.6.

Added¶

icu-date заменен на модуль datetime во внутренних механизмах.

Note

Поведение модулей datetime и timezone могло измениться в некоторых редких случаях. В рамках тестирования такие изменения не выявлены.
LuaJIT переведен в режим GC64.
Добавлена функция repository.update_batch.
Добавлена функция repository.call_on_storage_batch.
Добавлен экспериментальный режим построения индексов в фоне. Включается опцией background_index_build.
Модуль clock добавлен в sandbox.
Добавлена возможность установки ключа (key) для отправки сообщений в kafka.
Watchdog выключен по умолчанию. Вместо него используется механизм fiber.slice.
Для HARD_LIMITS_SCANNED установлено значение unlimited. Вместо него используется механизм fiber.slice.

Fixed¶

Запрещены union-типы с одним полем.
Удалены некорректные предупреждения в веб-интерфейсе при выполнении некоторых GraphQL-запросов.
Исправлена ошибка при передаче аргументов сервисов через REST API.
Исправлена ошибка при изменении union-типа на другой тип.

[2.6.9] – 2023-04-27 ¶

Fixed bad error message on invalid union validation.
Vinyl spaces are now created only for types with expiration strategy cold_storage.
Fixed an error on opening the Model tab before bootstrap.
Fixed tasks starting before the configuration is completely applied.
Fixed TDG ignoring the changes in default functions upon configuration reload.
Fixed a bug with Kafka request context.

[2.6.8] – 2023-04-07 ¶

Updated¶

Cartridge updated to build (5c30d1cc).
expirationd updated to 1.4.0.
metrics updated to 0.17.0.
avro-schema updated to 3.1.0
smtp updated to 0.0.7.
SDK updated to 2.10.6-0-r549.

Added¶

Added aarch64 support to Docker build.
Added validation for fields being indexed twice.
Changed the behavior of the Submit button in the Model and KeepVersionModal components.
Added the validation that the jobs.max_jobs_in_parallel option value is positive.

Fixed¶

Fixed a bug that occurred on adding a nullable logical type field.
Fixed possible freezing on local RPC calls.
Fixed a possible crash of the fiber that runs jobs on storages.

[2.6.7] – 2023-02-27 ¶

Cartridge is updated.
undici updated from 5.8.2 to 5.19.1.
SDK updated to 2.10.5-0-r543.
Added the ability to get count for types via REST and GraphQL API.
Fixed an issue where the start time of a task was after the end time.

[2.6.6] – 2023-02-20 ¶

SDK updated to 2.10.4-0-r538.
Fixed updating of records with arrays of records.
Added the ability to put a batch of objects via REST.

[2.6.5] – 2023-02-03 ¶

SDK updated to 2.10.4-0-r532.
Updated and improved the graphiql module in WebUI.
Added yields to the cleanup functions in audit log and common log.

[2.6.4] – 2022-11-16 ¶

Updated¶

SDK updated to 2.10.4-0-r518.
Cartridge updated to build (f4258ae2).
metrics updated to 0.15.1.
kafka updated to 1.6.2

Added¶

Added the ability to specify in the config the user arguments to pass to the task function body.
Added the ability to run tasks on specific runners, which are marked with labels in the config.
Improved editor components:
- Full-text search on the Model and Code tabs.
- Display line numbers on the Model and Test tabs.
- Save the state of GraphQL and Test tabs when switching tabs and refreshing the page.
Token names now appear in audit logs.

Fixed¶

Fixed the inability to use the Enum type in service arguments.

[2.6.3] – 2022-10-06 ¶

Updated¶

SDK updated to 2.10.3-0-r510.

Added¶

Added lifetime_hours value 0 (“forever”).
Added the msgpack module to the sandbox.

[2.6.2] – 2022-09-05 ¶

Updated¶

Cartridge updated to 2.7.6.
metrics updated to 0.15.0.
SDK updated to 2.10.2-0-gf4228cb7d-r502.

Added¶

Display errors that occur in services called via IPROTO.

Fixed¶

Fixed incorrect display of errors.

[2.5.3] – 2022-08-18 ¶

Fixed¶

Fixed affinity calculation with pagination.
Fixed a confusing warning in the Kafka connector.
Fixed assignment of nested records in repository.update.

[2.5.2] – 2022-08-12 ¶

Added¶

Added the support for Kafka headers in the input connector.

[2.6.1] – 2022-08-11 ¶

Added¶

Added the new logical type Timestamp.
Added keep_version_count value 0 (“unlimited”).
Added the skip_result option for repository.put and repository.put_batch.
Added the new function tonumber64 to the sandbox.
Allowed to specify collations for specific parts of an index.
Implemented the audit log based on the Tarantool 2.10 audit module.

Fixed¶

Добавлена валидация для обнуляемых полей в repository.update.
Disabled the first option in repository.delete.
Fixed affinity calculation with pagination.
Fixed incorrect validator creation.

[2.6.0] – 2022-06-30 ¶

Breaking changes¶

Renamed tdg_expiration metrics to expirationd.

Added¶

Added the LDAP settings page.
Enabled the Tarantool flightrec feature by default.
Implemented the tuple compression.
Added the support for Kafka headers in the input connector.
Enhanced the datetime sandbox module with new onboard Tarantool datetime module functions.

Fixed¶

Fixed several frontend bugs.
Fixed a confusing warning in the Kafka connector.
Fixed an incorrect GraphQL error message in logs.
The file connector now waits until at least one runner instance is available.
Fixed assignment of nested records in repository.update.

[2.5.1] – 2022-06-30 ¶

Added¶

Added the Config file name column to the Configuration Files table.
Added the Docker image with dev mode enabled.
Support logical type in repository for non-indexed fields.

Fixed¶

Boolean kafka metrics are now numeric.
Reworked log and audit log filtration.
Added error handling in repository.put_batch.

[2.5.0] — 2022-04-25 ¶

Breaking changes¶

all is now the default debug option in Kafka debug mode.
Query plan field name changed to _query_plan (with single underscore) to conform to the GraphQL specification.
Removed all string metrics from Kafka and file connectors.

Added¶

Added skip_result flag for update and delete interfaces (iproto, REST, graphql, repository).
Added logger checkboxes to the Kafka connector modal.
The list of roles on the user/token creation and editing form can now be filtered by tenant.
Added GraphQL for Kafka consumers check (config.kafka_check_input).
Added the indexed_by option to the REST interface to choose scan index.
Options can now be passed to LDAP connections.
Added the “Test Connection” button to the Kafka configuration modal.
Added availability to load custom roles by config.
Added new functions table.make_map and table.make_array to the sandbox.
Added scanned and returned tuples count histogram to metrics.

Fixed¶

The default hard limits returned value is no more equal to scanned value.
The default value of tenant field in the “new user” modal is now “Default”.
Disable output mode is now removed for the Kafka logger.
topic, key, offset, and partition are now passed to the handler with a Kafka message.
A LDAP user that has several groups can now use access actions from all corresponding roles mapped for these groups.
Finalized the validation of the “Expires in” field in the user creation pop-up.
Fixed “Cannot perform action with bucket” error on repository.put_batch call.
Fixed the error that appeared if a service used utf8 enums in args.
In case of problems with the Kafka connector, an issue is now displayed.
Fixed the error that appeared when a LDAP user accessed the GraphQL API.
Banned deletion of data action if it is used in a role.

[2.4.0] — 2022-01-28 ¶

Updated¶

Updated bundle to 2.8.3-0-g01023dbc2-r442.

Added¶

Added metrics for IProto API.
Error messages are now displayed in the “Edit tenant” pop-up.
Case-insensitive UPN can now be used with LDAP.
Introduced the enable_debug configuration option for Kafka connectors.
It is now allowed to specify the read, balance, and mode options for GraphQL.
Introduced data queries via the @options directive.
Custom headers and status code can now be returned by the auth plugin.
Added metrics for the Kafka connector.
Added new metrics for the file connector.
Logger can now be configured for Kafka connectors (with the logger option that can have one of the following values: stderr, tdg, disable).
The maintenance.clear_data API can now accept type name to clear spaces of single type.
Introduced graceful shutdown for the connector role.

Fixed¶

Improved the “Compare configuration” popup.
The metrics format for the REST data API is now more convenient.
Disabled autocompletion in the role editing form.
The error message in the delete tenant modal is now cleared after the error is fixed.
Removed the Kafka connector ssl.key.password option from the UI.
Fixed the issue when a task could hang in pending state if a runner was unavailable for some time.

[2.3.0] — 2021-10-27 ¶

Updated¶

Cartridge updated to 2.7.3.

Added¶

Custom timeout can now be specified for map_reduce and call_on_storage.
Expiration statistics added to exported metrics.
Added the use_active_directory option for LDAP.
Added the organizational_units option for LDAP.

Fixed¶

Expired tuples are not returned anymore.
Fixed empty filters handling in queries.
Fixed an issue that could lead to deadlock in several TDG subsystems.
Fixed several task/job issues.
Fixed array assignment in updates.
Fixed LDAP subsystem issues.
Cluster cookie authorization is now banned.
The null type in GraphQL requests is now banned.

Deprecated¶

The “Expiration” configuration section was renamed to “Versioning”.

[2.2.0] — 2021-09-29 ¶

Added¶

Added support for ILIKE, case-insensitive LIKE.
LIKE/ILIKE is allowed only for string fields and explicitly banned for indexes.
Tracing now supports inheritance.
Added metrics for the REST data interface.
Added a GraphQL interface for locking config sections to prevent section deletion.
The model and expiration GraphQL APIs were replaced with the data_type API.
Introduced a GraphQL interface for metrics settings.

Fixed¶

Some multitenancy bugs fixed.
Backward iteration without cursor is now banned.
The namespace field is now banned in model.

[2.1.1] — 2021-09-01 ¶

Added¶

Enums are now validated during updates.
Added input_processor.storage.type validation.
It is now possible to setup more than one kafka input.
Вместо файбера TDG time_delta теперь нужно использовать параметр Cartridge issues_limits.
Added validation in cases where absent data types are used as arguments/return values and listed as nullable array elements.

Fixed¶

The case when expiration was defined, but the model wasn’t, is now processed correctly.
Nullable array elements are now processed correctly.
Multipart indexes with 2+ logicalTypes now work correctly.
It is now impossible to assign identical names to different connectors in the configuration.

Архитектура¶

В этой главе описывается архитектура Tarantool Data Grid.

Основные архитектурные компоненты TDG изображены на схеме ниже.

Как видно из схемы, различные аспекты работы TDG разделены по соответствующим кластерным ролям: Storage, Connector, Runner и Core. Каждый экземпляр (узел) в кластере может иметь одну или более ролей. Подробнее о кластерных ролях рассказывается в разделе Кластерные роли.

Хранение данных: Tarantool¶

Для хранения данных в TDG используется распределённое хранилище Tarantool. Его функциональность включает:

хранение данных в оперативной памяти;
репликацию данных в рамках набора реплик (replicaset);
шардирование данных (сегментирование, sharding) по разным экземплярам.

Таким образом, TDG обеспечивает “из коробки” распределённое, высокопроизводительное, отказоустойчивое и масштабируемое хранение данных.

Кроме того, в TDG доступны другие функции хранения данных, такие как:

Описание модели данных в формате Apache Avro;
Проверка данных на целостность и соответствие модели, а также ремонтная очередь для объектов, не прошедших проверку.
Возможность хранения истории изменений (версионирование).

Доступ к данным: GraphQL и REST API¶

Для доступа к данным TDG используются два основных способа: GraphQL и REST API.

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

Точки доступа создаются автоматически на основе модели данных и доступных сервисов. Эти сервисы также можно вызывать через GraphQL и REST API.

Исполнение бизнес-логики: Lua¶

TDG предоставляет возможность хранения и исполнения пользовательской бизнес-логики, например, валидации или преобразования данных.

Для добавления необходимой бизнес-логики нужно реализовать её в виде функций на языке Lua и загрузить их в TDG.

Загруженные функции можно использовать несколькими способами:

Вызывать извне. Для этого нужно добавить их в конфигурацию доступных сервисов. Такие сервисы доступны для вызова через GraphQL, REST API или iproto (бинарный протокол Tarantool).
Привязать к коннектору. В этом случае функции будут вызываться при каждом взаимодействии через этот коннектор, например, при поступлении нового объекта.
Выполнять по расписанию. Для этого в TDG есть планировщик задач, который позволяет настроить автоматическое выполнение пользовательской бизнес-логики.

Взаимодействие с внешними системами¶

Для обмена данными с внешними системами в TDG используются коннекторы. Коннекторы бывают двух типов: входящие (input) для получения данных извне и исходящие (output) для отправки данных из TDG.

Коннекторы позволяют обмениваться данными с такими источниками как:

Apache Kafka;
Oracle Database и другие базы данных, поддерживающие ODBC;
HTTP;
Файлы;
Бинарный протокол Tarantool (iproto).

Администрирование и безопасность¶

TDG предоставляет инструменты для управления различными техническими функциями, в том числе:

топологией кластера;
моделью данных;
сервисами;
коннекторами;
настройками безопасности.

Для управления конфигурацией TDG доступны два способа:

Веб-интерфейс (WebUI) позволяет управлять TDG в визуальном режиме в браузере;
Конфигурационные файлы позволяют хранить и распространять конфигурации в виде готовых артефактов.

Для мониторинга и расследования инцидентов TDG предоставляет метрики кластера в формате Prometheus. Метрики доступны для получения через REST API и визуализации в Grafana.

Встроенные инструменты безопасности TDG позволяют настроить доступ к различным функциям для пользователей и внешних систем. Для этого используется ролевая модель доступа. Роли могут быть приписаны как к профилям (для настройки доступа пользователей), так и к токенам приложений – средству авторизации приложений для взаимодействия с TDG. Для расследования инцидентов безопасности доступен журнал аудита.

Кластерные роли¶

Экземпляры TDG в кластере выполняют те или иные функции в соответствии с назначенными им кластерными ролями. Каждый экземпляр может иметь одну или несколько ролей.

В TDG существует четыре основных кластерных роли:

Core: настройка и администрирование.
Storage: проверка и хранение данных.
Runner: исполнение бизнес-логики с помощью кода на Lua.
Connector: обмен данными с внешними системами.

Еще одна кластерная роль, failover-coordinator, позволяет включать режим восстановления после сбоев с сохранением состояния (stateful failover). Подробности можно найти в документации Tarantool Cartridge.

Кластерные роли назначаются наборам реплик (replica set). Каждый экземпляр получает роли того набора реплик, в который он входит. В каждом наборе реплик все экземпляры взаимозаменяемы: на них хранится одно и то же состояние. Таким образом обеспечивается резервирование и устойчивость к сбоям.

Роль Core¶

Роль core используется для выполнения собственных функций TDG. Экземпляры с этой ролью обеспечивают управление моделью данных, сервисами, настройками безопасности и доступа и другими функциями. На этих экземплярах хранится внутренняя информация TDG и не хранятся пользовательские данные.

В кластере может быть только один набор реплик с ролью core.

Роль Storage¶

Роль storage используется для хранения пользовательских данных. На экземплярах с этой ролью создаются спейсы Tarantool в соответствии с моделью данных.

Объединение экземпляров storage в наборы реплик обеспечивает шардирование и репликацию данных: каждый набор реплик хранит своё подмножество данных (shard), и это подмножество реплицируется на все экземпляры набора реплик.

Количество наборов реплик Storage определяется объемом хранимых данных.

Роль Runner¶

Роль runner используется для выполнения пользовательской бизнес-логики. На этих экземплярах с помощью встроенного в Tarantool Lua-интерпретатора выполняются загруженные в TDG пользовательские скрипты: сервисы, задачи, обработчики входящих и исходящих данных.

Экземпляры runner не хранят состояние и используются только для исполнения кода. Таким образом, они все эквивалентны, и объединение в наборы реплик не влияет на их функциональность.

Роль Connector¶

Роль connector используется для сетевого взаимодействия с внешними системами. На экземплярах с этой ролью создаются адреса (endpoints) для обращения к кластеру через GraphQL и REST API, а также коннекторы для подключения по различным протоколам: HTTP (JSON или SOAP), Apache Kafka или iproto.

Экземпляры connector не хранят состояние и используются только для внешних подключений. Таким образом, они все эквивалентны, и объединение в наборы реплик не влияет на их функциональность.

Administrator’s guide¶

This document explains how to work with Tarantool Data Grid (TDG) if you are an administrator.

Deployment¶

В этой главе описаны способы, которыми можно развернуть TDG для разработки и тестирования (development environment).

Для получения помощи в развертывании кластера TDG для промышленной эксплуатации (production environment) заполните форму для связи на этой странице или напишите на sales@tarantool.io.

First deployment with Ansible¶

В этом руководстве описано, как впервые быстро развернуть Tarantool Data Grid (TDG) с помощью Ansible. Здесь приведен вариант развертывания TDG на двух виртуальных машинах с заданной конфигурацией.

Getting a TGZ file for deployment¶

To deploy Tarantool Data Grid, you need an RPM (.rpm), TGZ (tar.gz), or Docker image (docker-image.tar.gz) file. For deployment with Ansible, you can only use either an RPM or a TGZ file. For now, a TGZ file will do just fine. It is easier to deploy and does not require root access.

Download a TGZ file of the latest version at the customer zone of tarantool.io. Make sure your browser did not unarchive the downloaded file: the file extension should be tar.gz.

If you do not have access to the customer zone, contact us using the form on this page or write to sales@tarantool.io.

Setting up virtual machines¶

Чтобы развернуть TDG, вам нужно запустить две виртуальные машины с ОС Linux (желательно CentOS 7/RHEL 7) и доступом по SSH. Если у вас уже установлены приведенные ниже или альтернативные виртуальные машины, то пропустите эту главу. Если нет, то следуйте инструкции.

Установите VirtualBox для запуска виртуальных машин и Vagrant для автоматизации процесса конфигурации. Vagrant подготовит конфигурацию двух виртуальных машин с дополнительными сценариями для развертывания TDG.

Note

Перед установкой программного обеспечения проверьте, что разработчик не накладывает ограничений на использование — например, не ставит блокировки по IP-адресам. При возникновении проблем воспользуйтесь услугами альтернативных провайдеров виртуальных машин.

Make sure you have VBoxManage in your $PATH environment variable.

Check with the command:

$ which VBoxManage

In the downloaded TGZ file, there is a directory called deploy. There you’ll find Vagrantfile, which automates the creation of a test environment for cluster deployment.

Open the terminal, unpack the tar.gz archive, go to the deploy directory, and run virtual machines:

tar xzf tdg-<VERSION>.tar.gz # change <VERSION> for the TDG version you've downloaded
cd tdg2/deploy
vagrant up

This command will bring up two virtual machines with CentOS 7 and passwordless SSH access for user vagrant. IP addresses of those machines are: 172.19.0.2 and 172.19.0.3.

Deploying the cluster¶

Preparing¶

After you’ve created virtual machines, install locally Ansible and Tarantool Cartridge Ansible role (the latest 1.x version). If Ansible role version 2.x is available, you can choose it instead, but you may face some challenges.

Here is one of the ways to install Ansible and Ansible role:

pip install ansible~=4.1.0 # version 4.1 or later, but not version 5.x
ansible-galaxy install tarantool.cartridge,1.10.0

Configuring¶

In the deploy directory, there is the hosts.yml file. It contains cluster configuration.

Open it to set cluster cookie and path to package:

all
  vars:
    # cartridge_package_path: "../../packages/tdg-ENTER-VERSION-HERE.tgz" # path relative to playbook
    # cartridge_cluster_cookie: "ENTER-SECRET-COOKIE-HERE" # change for "secret-cookie"

Удалите #, чтобы раскомментировать эти строки, укажите версию TDG, которую вы скачали, и путь к TGZ-файлу. Также задайте cookie для кластера. Это должна быть уникальная строка, но для практики достаточно указать “secret-cookie”.

Here is an example:

all
  vars:
    cartridge_package_path: "../tdg-2.0.0-1132-g2358e716.tgz"
    cartridge_cluster_cookie: "secret-cookie"

If you need to, you can always edit this file to change cluster configuration. Here is some info about file sections:

all.vars — для общих переменных;
all.children.tdg_group.hosts for instances parameters
all.children.tdg_group.children to specify parameters for a group of instances:
- to group the instances by the host, set their ansible_host parameter
- to group the instances by replica set, set their replicaset_alias, roles, failover_priority parameters, and so on.

You can find more information about parameters in Tarantool Cartridge Ansible role documentation.

Deploying¶

В директории deploy находятся Ansible-плейбуки, которые помогут вам завершить развертывание. Есть два способа развернуть TDG с помощью плейбуков:

кластер TDG с полностью сконфигурированной топологией;
кластер TDG со списком экземпляров (инстансов, instances) без заданной конфигурации.

Чтобы полностью развернуть TDG с топологией, выполните эту команду:

$ ansible-playbook -i hosts.yml playbooks/deploy.yml

If you want to practice configuring the topology of the cluster via the web interface, run the playbook to deploy only instances:

$ ansible-playbook -i hosts.yml playbooks/deploy_without_topology.yml

Now you can open http://172.19.0.2:8081 in your web browser to see the cluster web interface. This is what you’ll see if you chose to deploy without topology:

Managing the cluster¶

Configuring topology of the cluster¶

If you have deployed instances with topology, skip this topic.

If you have deployed instances without topology, you can now edit topology by creating replica sets and specifying their parameters in the web interface:

On the Cluster tab, there is a set of unconfigured instances. Select the core instance with the 172.19.0.2:3001 URL and click Configure. You will get the Configure server dialog:
In the Configure server dialog, specify two replica set parameters: replica set name and role.

For the core instance, give the replica set name “core” and select the “core” role. After you’ve set the parameters, click Create replica set.

Set the same parameters for the rest of the unconfigured instances as follows:

Instance URL	Replica set name	Roles
172.19.0.2:3002	runner_1	runner, connector, failover-coordinator
172.19.0.2:3003	storage_1	storage
172.19.0.2:3004	storage_2	storage
172.19.0.3:3001	runner_2	runner, connector

There are two instances left to configure, storage_1_replica with the 172.19.0.3:3002 URL and storage_2_replica with the 172.19.0.3:3003 URL.

Join them to the already existing replica sets with storage roles:
- Select storage_1_replica and click Configure.
- In the Configure server dialog, switch to the tab called Join Replica Set.
- Check storage_1 and click Join replica set.
For storage_2_replica, repeat the same steps, but check storage_2 instead.

После того, как вы назначите все роли, нажмите “Bootstrap vshard”, чтобы “включить наборы реплик storage. Это инициализирует модуль Tarantool vshard. Подробнее об этом модуле можно узнать в документации по Tarantool.

You’ve created virtual buckets that are allocated to storages according to the number of instances with the storage role.

Starting or stopping instances¶

This step is optional.

In the deploy directory, there are also playbooks that start or stop the instances. You can stop and disable all instances by stop.yml playbook:

$ ansible-playbook -i hosts.yml playbooks/stop.yml

You can start and enable all instances by start.yml playbook:

$ ansible-playbook -i hosts.yml playbooks/start.yml

First manual deployment¶

В этом руководстве описано, как впервые быстро развернуть Tarantool Data Grid (TDG) вручную. В результате вы локально развернете кластер TDG с одним узлом.

Note

Чтобы развернуть TDG, вам понадобится ОС Linux (желательно CentOS 7/RHEL 7). Если у вас другая ОС, сначала вам нужно будет создать виртуальную машину с ОС Linux.

Getting a TGZ file for deployment¶

To deploy Tarantool Data Grid, you need an RPM (.rpm), TGZ (tar.gz), or Docker image (docker-image.tar.gz) file. For the first deployment, a TGZ file will do just fine. It is easier to deploy and does not require root access.

Download a TGZ file of the latest version at the customer zone of tarantool.io. Make sure your browser did not unarchive the downloaded file: the file extension should be tar.gz.

If you do not have access to the customer zone, you can get one by applying this form or writing to sales@tarantool.io.

Deployment¶

Unpack tar.gz file:

$ tar xzf tdg-<VERSION>.tar.gz # change <VERSION> for the TDG version that you've downloaded

Запустите кластер TDG с одним узлом внутри распакованного архива tar.gz:
```
$ ./tarantool ./init.lua --bootstrap true
```
Если у вас уже установлен Tarantool, убедитесь, что для развертывания TDG вы используете ту версию Tarantool, которая была упакована в только что скачанный архив tar.gz.
Перейдите на http://127.0.0.1:8080/, чтобы проверить развернутый кластер TDG:

By running tarantool ./init.lua --bootstrap true, you’ve deployed a configured instance with assigned roles. If you want to try and assign roles by yourself, run:
```
$ tarantool ./init.lua
```
В результате у вас будет экземпляр TDG в исходном состоянии:

Если вы хотите заново развернуть TDG с нуля, не забудьте сначала удалить файлы конфигурации, а также xlog- и snap-файлы, которые были созданы при первом развертывании TDG:
```
$ rm -rf ./dev/output
```

Running Tarantool Data Grid in Docker¶

Вы можете запустить TDG в Docker-контейнере, чтобы разработать свое решение или проверить, подходит ли Tarantool Data Grid для вашего проекта.

This guide will show you how to:

Download the Docker image file.
запустить экземпляр (инстанс, instance) |project_name| в Docker-контейнере;
Configure the instance.

Getting Docker image file for deployment¶

Download the Docker image file of the latest version at the customer zone of tarantool.io. The download link looks like tdg-<version>-<hash>-docker-image.tar.gz.

If you do not have access to the customer zone, you can get one by applying this form or writing to sales@tarantool.io.

Running an instance¶

First, load the Docker image from the file that you’ve downloaded:

$ # change <version> and <hash> for the TDG version that you've downloaded
$ docker load --input tdg2_tdg-<version>-<hash>docker-image.tar.gz

The output will look like the following:

$ docker load --input tdg2_tdg-2.0.0-1197-g1144f0c9-docker-image.tar.gz
174f56854903: Loading layer [==================================================>]  211.7MB/211.7MB
3755a040b03f: Loading layer [==================================================>]  124.4kB/124.4kB
62e0389f69ce: Loading layer [==================================================>]   80.7MB/80.7MB
6230a7f7e181: Loading layer [==================================================>]   2.56kB/2.56kB
e714472acbb5: Loading layer [==================================================>]  54.62MB/54.62MB
32e4a08d6732: Loading layer [==================================================>]  2.048kB/2.048kB
63380e3c2f5c: Loading layer [==================================================>]  127.6MB/127.6MB
9a6936065be6: Loading layer [==================================================>]  4.348MB/4.348MB
e70d4b034a27: Loading layer [==================================================>]  12.29kB/12.29kB
Loaded image: tdg:2.0.0-1197-g1144f0c9

For details about docker load, refer to the Docker documentation.

Find an archive named tdg in the list of images:

$ docker image ls tdg
REPOSITORY   TAG                    IMAGE ID       CREATED       SIZE
tdg          2.0.0-1197-g1144f0c9   564a45b770f8   10 days ago   463MB

Теперь запустите контейнер с экземпляром TDG:
```
$ docker run --rm -it -p 8080:8080 tdg:<tag>
```
For example:
```
$ docker run --rm -it -p 8080:8080 tdg:2.0.0-1197-g1144f0c9
```
You will now find the unconfigured instance at localhost:8080:

Configuring instance¶

On the Cluster tab, there is an unconfigured instance. To access all basic functions to work with data, click Configure. You will get the Configure server dialog:

In the Configure server dialog, specify two replica set parameters: replica set name and roles. Set any name and choose Select all option to switch on these roles:

core: configuration and administration
runner: running the business logic using Lua code
connector: data exchange with external systems
storage: data validation and storage

failover-coordinator role enables by default. You can read more about this role in Tarantool Cartridge documentation.

After assigning all roles, click Create replica set.

Note

В этом примере все роли включаются одновременно в одном наборе реплик. Это удобно для практики и позволяет больше узнать о возможностях TDG, но в производственной среде так делать не стоит.

Initialize Tarantool vshard module by clicking Bootstrap vshard:

You can read more about this module in Tarantool documentation.

Web UI¶

В этой главе рассказано, как получить доступ к веб-интерфейсу TDG и авторизоваться в системе. Кроме того, в главе описаны элементы управления и функции, представленные в веб-интерфейсе.

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

Signing in¶

Чтобы получить доступ к веб-интерфейсу TDG, выполните следующие шаги:

Contact your administrator to get your credentials:
- Username: login that is automatically generated when the administrator creates a user profile. For example, ui8896 or gz1200.
- Password: automatically generated when the administrator creates a user profile.
- TDG server address: http://<address>:<http_port>, is set by the administrator in the configuration file. This guide uses the http://172.19.0.2:8080 server address as an example.
В браузере введите адрес сервера TDG, чтобы открыть диалоговое окно авторизации.
Введите учетные данные: в поле Username – имя пользователя, а в поле Password – пароль.
Click Login.

Во время авторизации система TDG проверяет правильность ваших учетных данных и права доступа к определенным вкладкам TDG. После успешной авторизации вы увидите интерфейс TDG с доступом только к определенным вкладкам. Набор вкладок зависит от роли пользователя, которую вам назначил администратор.

Если в учетных данных окажется опечатка, TDG не сможет вас идентифицировать. В этом случае появится сообщение “Authentication failed”:

Try to input your credentials one more time.

Web UI overview¶

Интерфейс TDG состоит из двух частей:

Панель вкладок отображает список вкладок для навигации по разделам TDG.
Working area: displays the contents of the selected tab.

Tab pane¶

The contents of the tab pane vary depending on the user role. Users with the “admin” and “supervisor” rights can see all tabs. Users with the access rights of the “user” role have access to a limited set of tabs.

At the bottom of the page, there is a Collapse menu button. Click it to hide the full tab pane view.

The tab pane consists of the following tabs:

Cluster	Cluster configuration and administration.
Configuration files	Управление параметрами конфигурации TDG.
Test	Sending test queries in JSON or XML (SOAP) format.
GraphQL	Sending queries in GraphQL format.
Model	Актуальная модель данных, загруженная в систему.
Repair Queues: Input	Repair queue for the uploaded objects.
Repair Queues: Output	Repair queue for the objects replicated to external systems.
Repair Queues: Jobs	Repair queue for pending jobs that ended with an error.
Logger	Event log.
Audit Log	Audit log.
Tasks	Task management.
Data types	Data types that are represented in the uploaded data model.
Connectors	Connector creation and management.
Settings	System settings management.
Doc	Версия документации TDG на английском языке, доступная локально из разворачиваемого пакета TDG. Таким образом, она содержит только ту информацию, которая была опубликована до формирования пакета. Более актуальную документацию на русском языке вы можете найти на сайте tarantool.io.

Cluster tab¶

На вкладке Cluster отображается текущий статус кластера экземпляров TDG. На этой вкладке вы можете администрировать кластер через веб-интерфейс. Элементы управления можно разделить на несколько групп:

Replica sets
Replica set widget
Instance widget
Instance details
More functions

Replica sets ¶

In the highlighted area, you can see general replica set statistics:

Total	Total number of replica sets in the cluster.
Unhealthy	Number of replica sets with the “unhealthy” status.
Servers	Общее количество экземпляров TDG.
Filter	A dropdown menu to filter replica sets by status or cluster role.
Search box	A search box to display replica sets filtered by URI, UUID, role, alias, or labels.

Replica set widget ¶

The following statistics are available in the replica set widget:

Name and role	For example, replica set “storage_1” with the role “storage”.
Status	“Healthy” means the current replica set functions properly. “Unhealthy” means the current replica set is not available or does not function properly.
Storage group and replica set weight	Only for replica sets with the “storage” role. For example, storage group “default”, replica set weight “1”.
Edit button	Opens a dialog where you can edit the parameters of the replica set.
Instances widgets	The widgets of the instances included in this replica set.

Instance widget ¶

The widget of the instance is in the highlighted area. It allows you to see the following information about the instance:

Instance name	For example, “storage_1” or “storage_1_replica”.
URI	Instance URI for binary port access. Is set in the cluster configuration via the `advertise_uri` parameter. For example, `172.19.0.2:3003`.
Status	“Healthy” means the current instance functions properly. “Unhealthy” means the current instance is not available or does not function properly.
Leader indicator	Indicates if the instance is the leader in the replica set.
Memory usage indicator	The actual memory used / memory limit set for the instance. For example, 3.3 MiB / 1024.0 MiB.
Virtual buckets indicator	Indicates the number of virtual buckets on the instance. Only for replica sets with the “storage” role.
`…` button	Options to see instance details, promote the instance as a leader, disable or expel the instance.

Instance details ¶

For each instance, you can view detailed information about its parameters in read-only mode. On the Cluster tab of the instance, click … > Server details:

Server details: подробная информация об экземпляре

You will see a pop-up window with detailed information about the instance parameters:

More functions ¶

Several more TDG functions are also available on the Cluster tab:

Issues	The history of issues occurring in the cluster operation.
Probe server	Manual server availability check. Used when configuring a cluster.
Auth	Enable and disable mandatory authorization mode.
Failover: disabled/eventual/stateful	Switch for automatic recovery mode after failure.

Вкладка Connectors¶

В TDG роль connector предназначена для соединения и обмена данными с внешними системами. Для подключения доступно несколько протоколов соединения:

http – запросы в формате JSON по HTTP;
soap – запросы в формате XML (SOAP) по HTTP;
kafka – для интеграции с шиной данных Apache Kafka;
tarantool_protocol – коннектор iproto.

На вкладке Connectors отображается список всех input-коннекторов. Здесь вы можете создавать новые коннекторы и управлять их. Ниже описаны доступные сценарии работы с вкладкой:

Создание коннектора
Управление коннекторами

Создание коннектора ¶

Во вкладке Connectors нажмите кнопку Add connector:

Появится окно Create connector, где нужно ввести параметры коннектора:

Параметры коннектора¶

При добавлении коннектора доступна настройка маршрутизации и input-параметров – параметров для получения и парсинга входящих запросов. Чтобы узнать больше об этих параметрах, обратитесь к разделу Параметры коннекторов. Ниже в таблице приведены поля, доступные для настройки в редакторе:

Название параметра	Тип коннектора	Описание	Обязательный параметр
Name	Любой	Имя коннектора, должно быть уникальным	Да
synchronous mode	Любой	Режим работы TDG в качестве producer. По умолчанию, режим асинхронный: подтверждение о доставке сообщения отправляется сразу после того, как сообщение добавлено в очередь на отправку. При синхронном режиме подтверждение о доставке отправляется только после того, как сообщение было доставлено.	Да
Routing key	Любой	ключ маршрутизации	Да
Protocol type	Любой	Тип коннектора. Доступные типы: `http` (по умолчанию), `soap`, `kafka`, `tarantool_protocol`.	Да
Path	`http`	Адрес для отправки запроса в TDG	Да
WSDL	`soap`	Схема WSDL, описывающая структуру входящего XML	Да
Success response template	`soap`	Шаблон ответа в случае успешной обработки запроса	Нет
Error response template	`soap`	Шаблон ответа в случае ошибки	Нет
Brokers	`kafka`	URL-адреса брокеров сообщений	Да
Topics	`kafka`	Топики в терминологии Kafka	Да
Group ID	`kafka`	Идентификатор группы подписчиков	Да
Token name	`kafka`	Имя токена приложения	Нет
Options	`kafka`	Опции библиотеки librdkafka	Нет
Print debug logs	`kafka`	Режим отладки. По умолчанию, отладка отключена. При включении отладки по умолчанию используется параметр `debug: "all"`. Если в логах не требуются все атрибуты, установите необходимое значение параметра `debug` в секции options при конфигурации.	Нет
Direct all non-error logs to TDG logger	`kafka`	Запись всех логов Kafka, включая сообщения об ошибках, в логи TDG. Соответствует параметру `logger: tdg`. По умолчанию, в редакторе опция включена.	Нет

Пример¶

Создадим новый коннектор типа http:

Для поля Path часть адреса определена заранее и не может быть изменена. Предопределенный адрес – это URL, на котором запущен экземпляр TDG (например, http://localhost:8080/). В поле можно указать только последнюю часть адреса – endpoint. Значение по умолчанию для endpoint: http.

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

Столбцы Name, Protocol type, Routing key и Options в таблице можно сортировать по возрастанию и убыванию.

Управление коннекторами ¶

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

Доступные функции:

Редактирование коннектора

При изменении настроек существующего коннектора доступны все параметры, кроме типа коннектора.

Данные о коннекторах в редакторе можно перезаписать и извне. Например, если загрузить во вкладку Configuration Files файл с новыми настройками коннектора, созданного ранее в редакторе, новая конфигурация отобразится во вкладке Connectors после обновления страницы.

Удаление коннектора

При попытке удалить коннектор появится диалоговое окно с подтверждением удаления.

Кластерные роли¶

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

В TDG существует четыре основных кластерных роли:

Core: настройка и администрирование.
Storage: проверка и хранение данных.
Runner: исполнение бизнес-логики с помощью кода на Lua.
Connector: обмен данными с внешними системами.

Подробная информация о кластерных ролях приведена в разделе Кластерные роли главы Архитектура.

Настройка кластерных ролей через WebUI¶

Для настройки кластерных ролей через веб-интерфейс TDG используются инструменты на вкладке Cluster.

Назначение ролей новым экземплярам¶

Чтобы назначить роль экземпляру впервые, найдите его в списке Unconfigured Instances и нажмите соответствующую кнопку Configure.

В открывшемся окне вы можете назначить роль одним из двух способов:

Создать новый набор реплик с нужными ролями. Для этого введите имя нового набора реплик, выберите необходимые роли и нажмите Create replica set.
Добавить экземпляр в существующий набор реплик. Для этого перейдите на вкладку Join replica set, выберите один из существующих наборов реплик с необходимыми ролями и нажмите Join replica set.

Изменение ролей¶

Чтобы изменить роли набора реплик, откройте окно его редактирования (Edit replica set) и включите или отключите роли. Эти изменения применятся ко всем экземплярам выбранного набора реплик.

Warning

При отключении роли storage на наборе реплик необходимо перераспределить сегменты данных, которые на нём хранятся, на другие наборы реплик. Для этого перед отключением роли storage установите набору реплик вес (Replica set weight) равным 0 и нажмите Save.

После этого убедитесь, что в наборе реплик не осталось сегментов данных и отключите на нём роль storage.

Настройка кластерных ролей через Ansible¶

Если вы разворачиваете кластер TDG с помощью Ansible, вы можете определить наборы реплик и их роли в inventory-файле hosts.yml.

Наборы реплик и их роли определяются в inventory-файле в разделе all.children.

Для каждого набора реплик необходимо создать узел с именем replicaset_<name>, где <name> – название, под которым набор реплик будет использоваться в кластере. Пример создания набора реплик с именем storage_01:

all:
   children:
    replicaset_storage_01:

В узле набора реплик задаются два раздела:

vars – параметры набора реплик, в том числе параметр roles – список назначенных ролей.
hosts – список узлов, входящих в набор реплик.

Пример конфигурации набора реплик с ролью storage из двух узлов:

all:
   children:
    replicaset_storage_01:
      vars:  # replica set configuration
        replicaset_alias: storage-01
        weight: 1
        failover_priority:
          - storage-01  # leader
          - storage-01-r
        roles:
          - 'storage'

Конфигурация кластера из пяти узлов с тремя наборами реплик (два storage и один с ролями core, runner, connector) может выглядеть следующим образом:

all:
   children:
    replicaset_storage_01:
      vars:  # replica set configuration
        replicaset_alias: storage-01
        weight: 1
        failover_priority:
          - storage-01  # leader
          - storage-01-r
        roles:
          - 'storage'

      hosts:   # replica set instances
        storage-01:
        storage-01-r:

    replicaset_storage_02:
      vars:  # replica set configuration
        replicaset_alias: storage-02
        weight: 1
        failover_priority:
          - storage-02  # leader
          - storage-02-r
        roles:
          - 'storage'

      hosts:   # replica set instances
        storage-02:
        storage-02-r:

    replicaset_app_01:
      vars:  # replica set configuration
        replicaset_alias: app-01
        failover_priority:
          - app-01  # leader
        roles:
          - 'core'
          - 'connector'
          - 'runner'

Security settings¶

This chapter explains how to administer security policy settings.

Role-based access control¶

В Tarantool Data Grid используется основанная на ролях модель доступа к системным функциям и данным, хранящимся в системе. Администратор настраивает права доступа к данным, используя UI или такие внешние инструменты, как LDAP. Каждая роль имеет набор разрешений, которые определяют, что пользователи или внешние приложения могут просматривать или изменять.

You can find the list of roles on the Settings > Roles tab:

Default roles¶

There are three default roles that you can assign to users and external applications for authorized access and actions in the system:

admin
supervisor
user

The default roles have a predefined set of permissions, and they cannot be edited or deleted.

Role	Authority	Data access
admin	Полный доступ ко всем функциям TDG	Read and write access for all aggregates
supervisor	Full read-only access to TDG functions	Read access for all aggregates
user	Default access: has access to the Test tab to send test objects, the Repair Queues tab, the Tasks tab, and the GraphQL tab.	None

Adding new user roles via UI¶

You can create new user roles based on the default roles or the roles you’ve already created.

To create a new user role:

Switch to the Settings > Roles tab and click Add new role.
In the New role dialog, set the following parameters:
- Name: the name of the new role.
- Description: an optional description of the new role.
- Roles: an optional selection of the existing role on the basis of which the new role will be created.
В списке выберите действия, которые будут доступны для роли пользователя. Не забудьте проверить, есть ли у роли доступ к интерфейсу. Например, если вы собираетесь дать роли права на выполнение запросов GraphQL, отметьте Pages Access > Show GraphQL page.
Click Add new role.

After you’ve created a new user role, you can edit or delete it any time.

Managing users¶

В этой главе рассматриваются операции управления пользователями TDG:

Creating and editing user profiles
Changing user status
Exporting and importing users
Managing password policy

The list of users is in the Settings > Users tab:

Creating and editing user profiles ¶

Creating a new user¶

Чтобы создать профиль пользователя TDG, выполните следующие шаги:

Switch to the Settings > Users tab. Click Add new user. You will get the New user dialog:

In the New user dialog, set the following parameters:
- Name: user name.
- Email: user email.
- Password: a password to log into the system. There are several options here: you can generate a password by clicking Generate or leave an empty field. In the second case, the system will automatically generate and send a password to the user’s Email, but it requires a configured SMTP server.
- Expires in: password expiration date. This field is optional. Passwords are checked for expiration approximately every 30 minutes. Accounts with expired passwords are blocked.
- Role: user role according to the role-based model of access.
Click Submit.

You will now see the new user in the list of users. After you’ve created a user, you can edit the user’s profile: change profile settings, reset password, block or delete the user.

Editing a user profile¶

To edit a user profile, open the Settings > Users tab and click the pencil edit button:

Change profile settings and click Submit.

Deleting a user¶

The administrator can delete any user from the user list:

In the Actions column, choose the user profile you want to delete, click the ... button, and select Delete user.
In the dialog tab, confirm the deletion of the user by clicking OK.

The deleted user will be automatically removed from the list of users.

Changing user status ¶

After you’ve created a user’s profile, it is automatically activated in the system. You’ll see the “ACTIVE” status in the Status column in the list of users. As an administrator, you can change this status and block the user:

In the Actions column, click the ... button and select Block:
In the dialog tab, write the reason why you are blocking this user and click Block:

After that, the user’s status will change to “BLOCKED”. To unblock the user, click the ... button and select Unblock.

Resetting a password¶

The administrator can reset the password of any user:

In the Actions column, choose the user profile you want to update, click the ... button, and select Reset password.
In the dialog tab, confirm the resetting of the password by clicking OK.

The user will get a temporary password via email that is set in the user’s profile.

Note: to send a temporary password, you need a configured SMTP server.

To set the workflow for sending temporary passwords:

Install and start the SMTP server.
В файле конфигурации TDG config.yml пропишите следующие настройки:

connector:
  output:
    - name: to_smtp
      type: smtp
      url: <URL of SMTP server>
      from: <sender's address>
      timeout: <timeout value, seconds>

account_manager:
  only_one_time_passwords: true
  output:
    name: to_smtp

For example:

output:
    - name: to_smtp
      type: smtp
      url: localhost:2525
      from: tdg@example.com
      timeout: 5

Upload the changed configuration to the system.

Exporting and importing users ¶

You can export and import user profiles in JSON format:

Exporting users¶

In the Settings > Users tab, click Export. The system will generate and export a JSON file. This file will contain an array with profiles of all current users.

Here is a user profile example:

[
   {
    "expires_in":2592000,
    "login":"ui8896",
    "email":"test@mail.ru",
    "created_at":1626360261875418600,
    "state_reason":"test@mail.ru state is changed to active: recover from disabled",
    "failed_login_attempts":1,
    "uid":"bd2e91f3-ce0f-4ff1-8aae-bc4212f99c7d",
    "role":"admin",
    "state":"active"
    ,"username":"User1",
    "last_login":1628058891852268000,
    "last_password_update_time":null
   },
   {
   ...
   }
]

Importing users¶

To import users, you need a JSON file with an array of user profiles. You can make this file manually or generate it as described in the previous topic about the export. The JSON file must include the fields listed above in the user profile example, except for the fields called state_reason, last_login, last_password_update_time, password.

As for the password, there are several ways to set it:

Manually: In the JSON file, set a password for every user. Make sure the passwords meet the password policy requirements. In the Import users from JSON file dialog, do not check any boxes. The passwords will be uploaded from the JSON file as-is.
Generate passwords: Set null in the password field or don’t include this field in the JSON file at all. In the Import users from JSON file dialog, check the box Generate passwords. The password will be automatically generated according to the current password policy.
Send password via users email: You need a configured SMTP server for this. In the Import users from JSON file dialog, check the Send password via users email box.

You need to choose only one of the listed options for all imported users.

Here is how to import users:

In the Settings > Users tab, click Import.
In the Import users from JSON file dialog, check one of the boxes or leave the boxes empty. It depends on the option you chose to set the users’ passwords.
Upload the JSON file with user profiles and click Apply.

The new user profiles will now be added to the Users list table. The profile data will be shown in the web interface in the message containing the results of the import operation.

You can save the imported data, including the generated passwords, by clicking Download. The data will be saved as a .csv file.

Managing password policy ¶

Авторизацию пользователей в системе регулирует политика TDG в отношении паролей. Она применима в равной степени как к паролям, которые пользователи задают вручную, так и к автоматически сгенерированным паролям. Управлять политикой в отношении паролей можно на вкладке Settings > Password Policy:

Default password settings include lowercase and uppercase characters and digits from 0 to 9, inclusive. The default password length is 8 characters. You can change the default settings and click Save.

Токены приложений¶

Токен приложений – уникальный идентификатор, который генерируется в кластере TDG. Такой токен служит средством авторизации внешних приложений для взаимодействия с данными и функциями TDG. Администратор создает токен, назначает для него нужные права доступа к объектам TDG и передает его разработчикам внешней системы. Доступны два способа управления токенами приложений – в веб-интерфейсе TDG и через GraphQL API.

Токен приложений также используется для авторизации HTTP-запросов и авторизации коннекторов. Подробнее об этих процедурах рассказывается в разделе Авторизация Руководства разработчика.

Управление токенами в веб-интерфейсе¶

Добавление токена¶

Сгенерировать токен через веб-интерфейс можно на вкладке Settings > Tokens:

Нажмите кнопку Add token.
В диалоговом окне Create token укажите следующие параметры:
- Name: имя (ключ) токена, по которому он будет идентифицироваться в системе;
- Expires in: срок действия токена (опционально). Чтобы создать токен без срока действия, оставьте поле пустым;
- Role: роль токена. Аналогична роли пользователя в ролевой модели доступа;
Нажмите кнопку Submit, чтобы сгенерировать токен. В веб-интерфейсе появится сообщение, где токен будет представлен в явном виде:

Important

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

Имя созданного токена редактировать невозможно. Однако вы можете изменять роль токена и его срок действия.

Как и профили пользователей, токены приложений в веб-интерфейсе можно удалять, блокировать, экспортировать и импортировать.

Удаление токена¶

Администратор может удалить из списка любой токен приложения. Для этого:

Найдите нужный токен в колонке Actions. В меню действий ... выберите пункт Delete token.
В диалоговом окне подтвердите удаление токена, нажав кнопку OK. Токен будет удален из общего списка автоматически.

Блокировка токена¶

Созданный токен будет сразу активирован в системе, для него в колонке Status появится статус ACTIVE. Администратор может изменить этот статус и заблокировать токен:

В колонке Actions в меню действий ... выберите Block.
В диалоговом окне опишите причину блокировки токена и нажмите Block. После этого статус токена изменится на BLOCKED. Чтобы разблокировать токен, в меню действий ... выберите Unblock и в диалоговом окне опишите причину разблокировки токена.

Кроме того, токен будет заблокирован автоматически (просрочен), если пользователь будет неактивен в системе дольше определенного времени. Задать необходимое время (не более 45 дней) можно в параметре ban_inactive_more_seconds в секции account_manager файла конфигурации. Разблокировать просроченный токен можно, если задать для него новое значение параметра Expires in.

Экспорт и импорт токенов¶

Токены приложений можно экспортировать из системы и импортировать в нее в формате JSON. Для этого на вкладке Settings > Tokens нажмите кнопку Import или Export. Действия выполняются аналогично экспорту и импорту профилей пользователей.

Пример JSON-файла с токенами:

[
  {
    "expires_in": 900,
    "token": null,
    "state_reason": "App01 state is changed to blocked",
    "uid": "jdsDAY3Y-wcwYBkdS7Kma2wyEYLwIv_qjQvxeUsFeyh0txDuqgHWmIMzLFCWp8S3GTgbxRQw7dq7Rz-k2Tddyg",
    "role": "user",
    "state": "blocked",
    "last_login": null,
    "name": "Token1",
    "created_at": 1686839870157890300
  },
  {
    "expires_in": 0,
    "token": null,
    "state_reason": null,
    "uid": "pLQIQDvHvGsymbfI1jt37BUhYLuZOzWNSB8kbDoWDx4mwYLDEdJFz-pUwK7mASyojYl-O83t1Iqtqr4HUGyKbQ",
    "role": "user",
    "state": "active",
    "last_login": null,
    "name": "App02",
    "created_at": 1686927801987245300
  }
]

Управление токенами через GraphQL API¶

Токенами приложений в TDG можно управлять с помощью GraphQL-запросов на изменение настроек, используя протокол HTTP. HTTP-запросы при этом должны иметь заголовок схемы admin и соответствующий заголовок для авторизации. Подробнее о таких запросах рассказывается в разделе Управление настройками через GraphQL API. Пример выполнения curl-запроса на изменение настроек можно найти на странице Авторизация Руководства разработчика.

Используя GraphQL API, можно выполнять следующие действия:

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

Все операции, относящиеся к токенам, выполняются внутри блока token {}. Полный список параметров запросов и их описание приведены на странице Основные настройки TDG.

Чтение информации о токенах¶

Чтобы вывести список всех токенов приложения, используйте запрос list (query):

query {
  token {
    list {
      name
         }
        }
      }

Чтобы вывести информацию о токене по его имени, используйте запрос get (query):

query {
  token {
    get(name: "Token1")
          {
            name
            expires_in
            created_at
            uid
            role
            state
            unblocked_at
            state_reason
            last_login
          }
        }
      }

Добавление токена¶

Для создания токена приложения используйте запрос add (mutation):

mutation {
    token {
        add(
          name: "App01"
          expires_in: 0
          role: "user"
        ) {
            name
            token
            created_at
        }
    }
}

При успешной генерации токена система возвращает ответ с указанием токена в явном виде в параметре token:

{
  "data": {
    "token": {
      "add": {
        "name": "App01",
        "token": "b773dbec-b86b-41aa-5541-887ba722c62e",
        "created_at": 1567758613669985599
      }
    }
  }
}

Important

Сохраните созданный токен в надежном месте. В целях безопасности токен в явном виде показывается только один раз, при его генерации. При повторных запросах существующего токена система возвращает его только в виде хеша.

При попытке повторно создать токен с уже существующим именем система возвращает сообщение об ошибке.

Редактирование токена¶

Изменить можно только срок действия токена и его роль. Для редактирования токена приложения используйте запрос update (mutation):

mutation {
    token {
        update(
          name: "App01"
          expires_in: 25000
          role: "admin"
        ) {
            name
            expires_in
            role
        }
    }
}

Блокировка токена¶

Для изменения статуса токена приложения используйте запрос set_state (mutation):

mutation {
    token {
        set_state(
          name: "App01"
          state: "blocked"
        ) {
            name
            role
            state
        }
    }
}

Импорт токена¶

Для импорта токена приложения используйте запрос import (mutation):

mutation {
  token {
    import(
      uid: "9d9fec89-c1f0-467f-b756-156fe9d29840"
      name: "App02"
      expires_in: 2592000
      role: "admin"
      state: "active"
      created_at: 1686927801987245300
    ) {
      name
      uid
    }
  }
}

Удаление токена¶

Для удаления токена приложения используйте запрос remove (mutation):

mutation {
    token {
        remove(name: "App01") {
            name
            created_at
            role
        }
    }
}

Mandatory authentication mode¶

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

To enable mandatory authentication mode:

Create a user profile with the “admin” role.
Sign in to the system as this user.
On the Cluster tab, enable the Auth toggle switch:

In the Authorization dialog, click Enable:

The mandatory authentication mode is on.

Теперь пользователи могут входить в систему, используя логин и пароль. В интерфейсе TDG пользователю предоставляется доступ к определенным вкладкам. Набор вкладок зависит от роли пользователя. Чтобы предоставить авторизованный доступ к данным и функциям TDG внешнему приложению, используйте токены приложений.

Авторизация внешних пользователей и систем через LDAP¶

TDG поддерживает технологию единого входа (Single Sign-On) – механизм аутентификации, позволяющий пользователям получать доступ к нескольким приложениям и сервисам c одним набором учетных данных. Это означает, что авторизоваться в TDG можно как через пользователей и токены приложений, так и с использованием такого внешнего инструмента, как LDAP.

LDAP (Lightweight Directory Service Protocol) – открытый протокол для хранения и получения данных из службы каталогов. LDAP позволяет централизованно настраивать права доступа к данным.

В TDG доступны три способа настройка протокола LDAP:

в веб-интерфейсе TDG;
через конфигурационный файл config.yml;
через GraphQL API, в секции account_provider.

В этом руководстве рассмотрим первые два способа настройки протокола.

Для выполнения примера требуются:

настроенный кластер TDG;
настроенный сервер LDAP.

Note

Для локального тестирования LDAP-авторизации можно использовать сервер GLAuth. Гарантируется работа с версией GLAuth 2.0.0

Руководство включает в себя следующие шаги:

Особенности конфигурации LDAP
Настройка LDAP в веб-интерфейсе
Настройка LDAP в файле конфигурации

Особенности конфигурации LDAP ¶

По умолчанию, логин в систему – это строка вида user@domain, где:

user – пользователь LDAP, который состоит в определенном домене и организационном подразделении;
domain – домен LDAP.

Пример: tdguser@my.domain.ru.

Если подключена Active Directory, служба каталогов Microsoft, для входа в систему используется адрес электронной почты пользователя LDAP. В качестве фильтра при этом используется атрибут Active Directory userprincipalname=email, где email – адрес электронной почты пользователя.

Каждый пользователь LDAP состоит в одной или нескольких группах LDAP (domain group). Группе LDAP задается определенная роль (например, admin), которая определяет права доступа для пользователя из этой группы. Если пользователь LDAP состоит сразу в нескольких группах, он получает разрешения на действия из всех ролей, заданных для этих групп.

Настройка LDAP в веб-интерфейсе ¶

Добавим новую конфигурацию LDAP через веб-интерфейс TDG.

На вкладке Settings > LDAP нажмите кнопку Add Configuration.
В диалоговом окне LDAP укажите параметры, необходимые для вашей конфигурации:
- Domain – доменное имя, используемое в доменном логине пользователя (tdguser@my.domain.ru). Пример: my.domain.ru;
- Hosts – адрес подключения к серверу LDAP. Пример: server.my.domain.ru:389;
- Organizational units (опционально) – названия организационных подразделений или групп пользователей. Параметр будет пропущен, если для него не задано явное значение. Пример: tarantool;
- Options (опционально) – настройки LDAP. Параметр будет пропущен, если для него не задано явное значение;
- Roles – описание ролей, которые будут назначаться пользователю в зависимости от групп LDAP, в которых он состоит. Для каждой роли описаны название роли и соответствующие ей LDAP-группы. Описание LDAP-группы состоит из общего имени (CN), названия организационного подразделения или LDAP-группы (OU) и компонентов домена (DC).
  
  Пример: добавьте роль admin. Для нее в поле Domain Groups укажите значение CN=tarantool, OU=groups, OU=other_groups, DC=my, DC=domain, DC=ru;
- Search timeout (опционально) – время ожидания ответа от сервера LDAP в секундах. Значение по умолчанию: 2;
- Use TLS (опционально) – использование TLS. Значение по умолчанию: false;
- Use Active Directory (опционально) – использование Active Directory. Значение по умолчанию: false.
При настройке обратите внимание на параметры domain и organizational_units. Эти параметры используются при аутентификации для поиска пользователя в соответствующем домене и организационном подразделении.

Полное описание параметров LDAP приведено в разделе ldap справочника конфигурации.
Нажмите кнопку Submit, чтобы добавить конфигурацию LDAP.
Чтобы войти в систему как пользователь LDAP, нажмите кнопку Log in в правом верхнем углу. В диалоговом окне Authorization введите логин (вида user@domain) и пароль пользователя LDAP, затем нажмите кнопку Login.

Настройка LDAP в файле конфигурации ¶

Указать конфигурацию LDAP можно:

в общем конфигурационном файле (секция ldap в файле config.yml);
в отдельном файле ldap.yml.

Полное описание параметров LDAP приведено в разделе ldap справочника конфигурации.

Пример конфигурации с включенными TLS и Active Directory:

ldap:
  - domain: 'my.domain.ru'
    organizational_units: ['tarantool']
    hosts:
      - server.my.domain.ru:389
    use_active_directory: true
    use_tls: true
    search_timeout: 2
    options:
      - LDAP_OPT_X_TLS_CACERTFILE: /certs/CA_Root.crt
    roles:
      - domain_groups:
          - 'cn=tarantool,ou=groups,ou=other_groups,dc=my,dc=domain,dc=ru'
        role: 'admin'

Созданный yml-файл с настройками конфигурации нужно упаковать в zip-архив и загрузить в TDG согласно инструкции.

Setting up data actions¶

TDG позволяет управлять правами пользователей на чтение и запись данных, обрабатываемых и хранимых в системе. Чтобы роль пользователя получила права доступа к данным, создайте в веб-интерфейсе профиль доступа (data action) и назначьте этот профиль для нужной роли.

Creating a new data action
Assigning data actions to user roles

Creating a new data action ¶

To set up a new data action:

Open the Settings > Data actions tab.
Click Add data action.
In the New data action dialog, set the data action’s Name and check the Read/ Write rights for each aggregate:

Save the data action by clicking Save.

After creating a data action, you can edit any of its parameters.

Assigning data actions to user roles ¶

You can assign data action to any user role created by the administrator. However, assigning data actions to default roles is impossible, as they cannot be edited.

To assign a data action to a user role:

Switch to the Settings > Roles tab.
In the list of roles, choose the role you want to edit and click the pencil edit button.
In the list of all actions, find Data actions section and tick the checkbox of the data action you want to assign to the role:

Привязка профиля доступа к роли пользователя

Click Apply.

Likewise, you can assign data actions while creating a new role.

Security checklist¶

This chapter will help you audit the security of Tarantool Data Grid. It explains certain security aspects, their rationale, and the ways to check them.

Audit log¶

Журнал аудита содержит записи о событиях безопасности в TDG.

To view the log:

Configure at least one instance with the storage role.
Go to the Cluster tab and click the Bootstrap vshard button.
Go to the Audit log tab.

Enabling and disabling the audit log¶

The audit log is enabled by default and records messages regardless of authorization settings.

To disable the audit log, click the Disable logging button on the Audit log tab. You can also go to the Graphql tab and run the following GraphQL request:

mutation {
  audit_log {
    enabled(value: false)
  }
}

To check if the audit log is enabled:

query {
  audit_log {
    enabled
  }
}

Clearing the audit log¶

The audit log is stored in memtx and doesn’t clear automatically.

To fully clear the space associated with the audit log, run the following GraphQL code:

mutation {
        audit_log {
          clear
        }
      }

Log structure¶

Each table entry provides the following information:

Severity
From - To
Subject ID
Subject
Request ID
Module
Message

The audit log can be filtered by each of the parameters. Below is more information about every one of them.

Severity¶

Possible values (in order of ascending severity):

VERBOSE – детальная информация;
INFO – уведомление;
WARNING – предупреждение;
ALARM – тревога.

A filter by severity displays events of the specified level or more severe. Choose the “VERBOSE” filter to display all messages.

From - To¶

Date and time of the event. Displayed in GMT+0 (UTC) time.

Subject ID¶

Internal identifier of the access subject.

Subject¶

Access subject name and type. Possible values:

system %q: системное сообщение, где %q – имя сущности в системе.
token %q: доступ к HTTP API при помощи токена приложения (например, чтобы получить данные GraphQL), где %q – имя сущности, запросившей доступ.
user: access attempt from GUI.
anonymous: access attempt from GUI, if mandatory authorization is disabled.
unauthorized: access attempt from GUI by an unauthorized user.

Request ID¶

Internal identifier of the request.

Module¶

Name of the system module that initiated the event. Examples: common.admin.auth is the module responsible for authorization.

Message¶

Event description. Can be provided by the user.

Examples¶

Successful user authorization¶

Сообщение журнала аудита об успешной авторизации пользователя

Model update¶

Сообщение журнала аудита об обновлении модели

Clearing the audit log¶

Configuration via config.yml¶

The default settings that Tarantool Data Grid starts up with can be found in the file config.yml. Audit log settings can be listed in this

audit_log:
  remove_older_than_n_hours: 24 # how many hours a message should exist before being deleted
  severity: VERBOSE # record messages of this severity level and higher
  enabled: true

Задачи¶

В этой главе описаны возможности TDG по управлению задачами через веб-интерфейс.

Задачи позволяют запускать пользовательский код изнутри TDG. Инструкции по созданию и конфигурированию задач приведены в разделе Задачи руководства разработчика. Имя, вид и расписание выполнения задач определяются в конфигурации бизнес-логики.

Инструменты для управления задачами и отслеживания их выполнения расположены на вкладке Tasks.

Name: имя задачи.
ID: UUID экземпляра задачи.
Kind: вид задачи. Доступные виды:
- Single shot — единоразовая задача;
- Continuous — непрерывно выполняемая задача;
- Periodical — задача, выполняемая по расписанию. Для таких задач также отображается расписание.
Status: текущий статус задачи. Доступные статусы:
- DID NOT START
- PENDING
- RUNNING
- STOPPED
- FAILED
- COMPLETED
Started/Finished: дата и время старта или завершения экземпляра задачи.
Launched by: пользователь, запустивший выполнение задачи.
Items: количество завершенных экземпляров задачи.

Note

Максимальное количество хранимых в истории экземпляров задачи определяется параметром keep в конфигурации задачи. Более старые экземпляры удаляются.
Actions: возможные действия для управления выполнением задач. Доступные действия:
- Start: запустить новый экземпляр неактивной задачи.
- Stop: прекратить работу активного экземпляра задачи (в статусе “running”).
- Results: просмотреть результаты выполнения экземпляров задачи. В окне результатов доступен список хранимых экземпляров задачи, возможен просмотр их результатов и логов и запуск нового экземпляра:

Repair queue¶

Если система TDG не может обработать входящий объект, она помещает его в ремонтную очередь. Затем администратор проверяет его, устраняет проблему и отправляет объект на повторную обработку.

Input¶

On the Repair queues > Input tab, there is a repair queue for submitted objects.

Сюда попадают входящие объекты, которые система TDG не смогла обработать. Вот основные причины, по которым это происходит:

Error when processing an incoming object with a handler.
Система TDG ожидает объект в определенном формате, а входящий объект из внешней системы был отправлен в другом формате.
Internal system error.
Hardware failure.

You can work with objects in the repair queue through the web interface on the Input tab:

On this tab, you can see the list of objects, their status (“New”, “In Progress”, “Reworked”), and the date and time when they were placed in the repair queue.

The Repair queue interface lets you do the following:

Filter: filter the objects by any combination of characters in any table column or by specifying the date or time range.
Try again: process the object again by the same handler.
Delete: delete the selected object from the repair queue.
Try again all: process all objects one more time.
Delete all: delete all objects from the repair queue.

Click on the object to see its details:

In the Object info dialog, you can see:

ID: the object’s UUID.
Reason: error description and the complete stack trace.
Object: the object’s current structure in the JSON format.

When an object gets into the repair queue, it has the status “New”. When it is processed for a second time, the object’s status changes to “In Progress”. If the object was processed successfully, it is removed from the repair queue. If an error occurs during reprocessing, the system will display an error message. The object will remain in the repair queue with the status “Reworked”.

Notifications¶

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

On the Settings > Mail server tab, set the following parameters:

Url: the SMTP server used to send notifications.
From: the sender that will be shown in the mail client.
Username: SMTP server user name.
Password: SMTP server user password.
Timeout (sec): SMTP server request timeout in seconds.

On the Settings > Subscribers tab, click the Add subscriber button to add a new subscriber. Specify the subscriber’s name and email. Later, you can edit the subscriber’s profile or delete it.

Output¶

The object replication mechanism allows you to send objects to external systems in the desired format. In case of an error during the replication process, the object gets in the replication repair queue on the Output tab.

This queue has the same functions as the repair queue on the Input tab. The only difference is that the repair queue on the Input tab is for submitted objects that could not be processed and saved, whereas the replication repair queue on the Output tab is for objects that could not be replicated.

To work with objects in the replication repair queue, open the Repair queues > Output tab:

Like in the repair queue, you can filter objects, delete them, and try to replicate them again.

The object status shows the reason why the object ended up in the replication repair queue:

“Preprocessing error”: the replicated object was processed with an error.
“Sending error”: an error occured while sending the object to an external system.

If you choose an object and click Try again, the object will be processed again. Its status will change from “New” to “In progress”. If the operation is successful, the object will be moved to the next stage or deleted from the repair queue. If the operation finishes with an error, the status will change to “Rereplicated (Preprocessing error)” or “Rereplicated (Sending error)”. The object will remain in the replication repair queue.

Jobs¶

This is a repair queue for pending jobs that ended with an error. To monitor these jobs, open the Repair queues > Jobs tab:

This tab has the same functions as the repair queue for submitted objects on the Input tab.

Monitoring¶

Для мониторинга работы TDG предоставляются метрики в формате Prometheus. Для каждого из экземпляров кластера значения метрик доступны по адресу: http://<IP_адрес_экземпляра>/metrics. В системе-сборщике метрик необходимо подать на вход адреса для сбора метрик со всех экземпляров кластера.

Все доступные метрики можно разделить на несколько категорий:

метрики, специфичные для TDG;
стандартные метрики для мониторинга работы экземпляров Tarantool;
пользовательские метрики, разработанные в окружении sandbox на основе модуля tarantool/metrics.

Используются следующие типы метрик Prometheus:

counter – монотонно возрастающий счетчик;
gauge – числовое значение, которое может как возрастать, так и убывать;
histogram – выборка из некоторого количества значений. Тип histogram подсчитывает полученные значения и объединяет их в настраиваемые бакеты (buckets).
summary – выборка из некоторого количества значений. Тип summary подсчитывает полученные значения и объединяет их в настраиваемые квантили.

Чтобы узнать больше про типы метрик, обратитесь к документации Prometheus.

Метрики TDG¶

Метрики запросов GraphQL¶

Мониторинг и оценка запросов GraphQL.

Метрики имеют теги:

alias – имя экземпляра, на котором собираются метрики. Имя экземпляра было задано при развертывании кластера;
schema – имя схемы (default или admin), в которую поступил запрос GraphQL;
entity – тип данных, над которым производится операция;
operation_name – имя запроса GraphQL (может отсутствовать, если имя запроса не было задано). Рекомендуется указывать имена для всех запросов, чтобы можно было однозначно идентифицировать, к какому запросу относится информация в метрике.

Доступные метрики

tdg_graphql_query_time{alias,schema,entity,operation_name} – время обработки запроса на получение данных (query) в миллисекундах. Тип метрики: histogram;
tdg_graphql_mutation_time{alias,schema,entity,operation_name} – время обработки запроса на изменения данных (mutation) в миллисекундах. Тип метрики: histogram;
tdg_graphql_query_fail{alias,schema,entity,operation_name} – количество запросов на получение данных (query) c ошибками. Тип метрики: counter;
tdg_graphql_mutation_fail{alias,schema,entity,operation_name} – количество запросов на изменение данных (mutation) c ошибками. Тип метрики: counter.

Бакеты (bucket) гистограмм распределены в диапазоне от 0 до 1000 миллисекунд с интервалом в 100 миллисекунд (см. пример ниже).

Вызов сервиса аналогичен запросу (query) для типа данных. В тег entity при этом будет записано имя сервиса.

Каждый запрос может состоять из нескольких операций. В одной операции могут быть получены или модифицированы несколько типов данных. По каждому типу данных будет выдана отдельная метрика со своим набором тегов.

Пример:

# HELP tdg_graphql_query_time Graphql query execution time
# TYPE tdg_graphql_query_time histogram
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="100"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="200"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="300"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="400"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="500"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="600"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="700"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="800"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="900"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="1000"} 25
tdg_graphql_query_time_bucket{alias="core_1",schema="default",entity="City",operation_name="GetCity",le="+Inf"} 25
tdg_graphql_query_time_sum{alias="core_1",schema="default",entity="City",operation_name="GetCity"} 55
tdg_graphql_query_time_count{alias="core_1",schema="default",entity="City",operation_name="GetCity"} 25

# HELP tdg_graphql_mutation_time Graphql mutation execution time
# TYPE tdg_graphql_mutation_time histogram
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="100"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="200"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="300"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="400"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="500"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="600"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="700"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="800"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="900"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="1000"} 16
tdg_graphql_mutation_time_bucket{alias="core_1",schema="default",entity="City",operation_name="InsCity",le="+Inf"} 16
tdg_graphql_mutation_time_sum{alias="core_1",schema="default",entity="City",operation_name="InsCity"} 34
tdg_graphql_mutation_time_count{alias="core_1",schema="default",entity="City",operation_name="InsCity"} 16

# HELP tdg_graphql_query_fail Graphql query fail count
# TYPE tdg_graphql_query_fail counter
tdg_graphql_query_fail{alias="core_1",schema="default",entity="City",operation_name="GetCity"} 2

# HELP tdg_graphql_mutation_fail Graphql mutation fail count
# TYPE tdg_graphql_mutation_fail counter
tdg_graphql_mutation_fail{alias="core_1",schema="default",entity="City",operation_name="InsCity"} 4

Чтобы получить информацию о среднем количестве запросов GraphQL в секунду из Prometheus, воспользуйтесь запросом

rate(tdg_graphql_query_time_count[2m])

Период, по которому вычисляется rate() (в примере – 2m), должен быть как минимум в два раза больше периода сбора метрик. Если вы добавляете панель на стандартный Grafana Tarantool dashboard, воспользуйтесь переменной $rate_time_range.

Среднее время выполнения запроса GraphQL можно получить с помощью

rate(tdg_graphql_query_time_sum[2m])/rate(tdg_graphql_query_time_count[2m])

95-й перцентиль времени выполнения запроса GraphQL можно получить с помощью

histogram_quantile(0.95, sum(rate(tdg_graphql_query_time_bucket[2m])) by (le))

Метрики для задач и отложенных работ¶

Метрики для задач (tasks) и отложенных работ (jobs). Метрики актуальны только для экземпляров с ролью runner, так как задачи и отложенные работы запускаются на этих экземплярах.

Метрики задач имеют теги:

alias – имя экземпляра, на котором собираются метрики. Имя экземпляра было задано при развертывании кластера;
name – имя задачи;
kind – вид задачи:
- single_shot – единоразовая задача;
- continuous – непрерывно выполняемая задача;
- periodical – задача, выполняемая по расписанию.

Метрики отложенных работ и системных задач имеют только теги alias и name. В TDG cистемные задачи (system task) используются для версионирования.

Доступные метрики

tdg_tasks_started – число запущенных задач. Тип метрики: counter.
tdg_jobs_started – число запущенных отложенных работ. Тип метрики: counter.

tdg_system_tasks_started – число запущенных системных задач. Тип метрики: counter.

Пример:

# HELP tdg_system_tasks_started Total system tasks started
# TYPE tdg_system_tasks_started counter
tdg_tasks_started{alias="runner_1",name="districts_stat.calc_statistics.call",kind="periodical"} 2

# HELP tdg_jobs_started Total jobs started
# TYPE tdg_jobs_started counter
tdg_jobs_started{name="succeed",alias="runner_1"} 1

# HELP tdg_system_tasks_started Total system tasks started
# TYPE tdg_system_tasks_started counter
tdg_system_tasks_started{name="tasks.system.archivation.start",alias="runner_1"} 718

tdg_tasks_failed – число задач, которые завершились с ошибкой. Тип метрики: counter;

tdg_jobs_failed – число отложенных работ, которые завершились с ошибкой. Тип метрики: counter.

Пример:

# HELP tdg_tasks_failed Total tasks failed
# TYPE tdg_tasks_failed counter
tdg_tasks_succeeded{alias="runner_1",name="districts_stat.calc_statistics.call",kind="periodical"} 1

# HELP tdg_jobs_failed Total jobs failed
# TYPE tdg_jobs_failed counter
tdg_jobs_failed{name="fail",alias="runner_1"} 2

tdg_tasks_succeeded – число успешно выполненных задач. Тип метрики: counter;
tdg_jobs_succeeded – число успешно выполненных отложенных работ. Тип метрики: counter;

tdg_system_tasks_succeeded – число успешно выполненных системных задач. Тип метрики: counter.

Пример:

# HELP tdg_tasks_succeeded Total tasks succeeded
# TYPE tdg_tasks_succeeded counter
tdg_tasks_succeeded{alias="runner_1",name="districts_stat.calc_statistics.call",kind="periodical"} 2

# HELP tdg_jobs_succeeded Total jobs succeeded
# TYPE tdg_jobs_succeeded counter
tdg_jobs_succeeded{name="succeed",alias="runner_1"} 1

# HELP tdg_system_tasks_succeeded Total system tasks succeeded
# TYPE tdg_system_tasks_succeeded counter
tdg_system_tasks_succeeded{name="tasks.system.archivation.start",alias="runner_1"} 718

tdg_tasks_stopped – число приостановленных задач. Тип метрики: counter.

Пример:

# HELP tdg_tasks_stopped Total tasks stopped
# TYPE tdg_tasks_stopped counter
tdg_tasks_stopped{alias="runner_1",name="districts_stat.calc_statistics.call",kind="periodical"} 2

tdg_tasks_running – число задач, запущенных в данный момент. Тип метрики: gauge;
tdg_jobs_running – число отложенных работ, запущенных в данных момент. Тип метрики: gauge;

tdg_system_tasks_running – число системных задач, запущенных в данный момент. Тип метрики: gauge.

Пример:

# HELP tdg_tasks_running Currently running tasks
# TYPE tdg_tasks_running gauge
tdg_tasks_running{alias="runner_1",name="districts_stat.calc_statistics.call",kind="periodical"} 0

# HELP tdg_jobs_running Currently running jobs
# TYPE tdg_jobs_running gauge
tdg_jobs_running{name="succeed",alias="runner_1"} 0

# HELP tdg_system_tasks_running Currently running system tasks
# TYPE tdg_system_tasks_running gauge
tdg_system_tasks_running{name="tasks.system.archivation.start",alias="tnt_net_external_1_runner_1_1"} 0

tdg_tasks_execution_time – время исполнения задачи. Тип метрики: histogram;
tdg_jobs_execution_time – время исполнения отложенной работы. Тип метрики: histogram;

tdg_system_tasks_execution_time – время исполнения системной задачи. Тип метрики: histogram.

Бакеты (bucket) гистограмм распределены в диапазоне от 0 до 5 секунд: 0.0001, 0.00025, 0.0005, 0.001, 0.0025, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1, 2.5, 5.

Пример:

# HELP tdg_tasks_execution_time Tasks execution time statistics
# TYPE tdg_tasks_execution_time histogram
tdg_tasks_execution_time_count{alias="runner_1",name="calc_districts_stat",kind="periodical"} 2
tdg_tasks_execution_time_sum{alias="runner_1",name="calc_districts_stat",kind="periodical"} 0.014632841999969
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="0.0001",kind="periodical"} 0
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="0.00025",kind="periodical"} 0
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="0.0005",kind="periodical"} 0
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="0.001",kind="periodical"} 0
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="0.0025",kind="periodical"} 1
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="0.005",kind="periodical"} 1
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="0.01",kind="periodical"} 1
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="0.025",kind="periodical"} 2
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="0.05",kind="periodical"} 2
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="0.1",kind="periodical"} 2
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="0.25",kind="periodical"} 2
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="0.5",kind="periodical"} 2
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="1",kind="periodical"} 2
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="2.5",kind="periodical"} 2
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="5",kind="periodical"} 2
tdg_tasks_execution_time_bucket{alias="runner_1",name="calc_districts_stat",le="+Inf",kind="periodical"} 2

# HELP tdg_jobs_execution_time Jobs execution time statistics
# TYPE tdg_jobs_execution_time histogram
tdg_jobs_execution_time_count{name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_sum{name="succeed",alias="runner_1"} 1.0725110769272e-05
tdg_jobs_execution_time_bucket{le="0.0001",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="0.00025",name="succeed",alias="runner_1"}1
tdg_jobs_execution_time_bucket{le="0.0005",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="0.001",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="0.0025",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="0.005",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="0.01",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="0.025",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="0.05",name="succeed",alias="runner_1"}
tdg_jobs_execution_time_bucket{le="0.1",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="0.25",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="0.5",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="1",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="2.5",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="5",name="succeed",alias="runner_1"} 1
tdg_jobs_execution_time_bucket{le="+Inf",name="succeed",alias="runner_1"} 1

# HELP tdg_system_tasks_execution_time System tasks execution time statistics
# TYPE tdg_system_tasks_execution_time histogram
tdg_system_tasks_execution_time_count{name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_sum{name="tasks.system.archivation.start",alias="runner_1"} 0.052489631809294
tdg_system_tasks_execution_time_bucket{le="0.0001",name="tasks.system.archivation.start",alias="runner_1"} 631
tdg_system_tasks_execution_time_bucket{le="0.00025",name="tasks.system.archivation.start",alias="runner_1"} 715
tdg_system_tasks_execution_time_bucket{le="0.0005",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="0.001",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="0.0025",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="0.005",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="0.01",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="0.025",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="0.05",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="0.1",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="0.25",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="0.5",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="1",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="2.5",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="5",name="tasks.system.archivation.start",alias="runner_1"} 718
tdg_system_tasks_execution_time_bucket{le="+Inf",name="tasks.system.archivation.start",alias="runner_1"} 718

Метрики для кортежей¶

Статистика по операциям поиска кортежей в базе данных, где хранятся пользовательские данные:

tdg_scanned_tuples – число просканированных кортежей. Тип метрики: summary;
tdg_returned_tuples – число возвращенных кортежей. Тип метрики: histogram;
tdg_scanned_tuples_max – максимальное количество просканированных кортежей. Тип метрики: gauge;
tdg_returned_tuples_max – максимальное количество возвращаемых кортежей. Тип метрики: gauge.

Метрики запросов REST¶

Мониторинг и оценка запросов к данным через REST:

tdg_rest_exec_time – время исполнения REST-запроса. Тип метрики: summary;
tdg_rest_exec_time – время исполнения REST-запроса. Тип метрики: histogram.

Метрики запросов iproto¶

Мониторинг и оценка запросов к данным через iproto:

tdg_iproto_data_query_exec_time – время исполнения запроса по протоколу iproto. Тип метрики: summary;
tdg_iproto_data_query_exec_time – время исполнения запроса по протоколу iproto. Тип метрики: histogram.

Метрики файлового коннектора¶

Общая статистика по файловым коннекторам и статистика обработки файлов:

tdg_connector_input_file_processed_count – общее число обработанных файлов. Тип метрики: counter;
tdg_connector_input_file_processed_objects_count – общее число обработанных объектов. Тип метрики: counter;
tdg_connector_input_file_failed_count – общее число файлов, которые не удалось обработать. Тип метрики: counter;
tdg_connector_input_file_size – размер файла в байтах. Тип метрики: gauge;
tdg_connector_input_file_current_bytes_processed – количество обработанных байтов от текущего файла. Тип метрики: counter;
tdg_connector_input_file_current_processed_objects – число обработанных объектов от текущего файла. Тип метрики: counter.

Метрики expirationd¶

Статистика модуля expirationd (время жизни объектов). Сбор статистики включен по умолчанию.

Тип метрик – counter.

Метрики имеют тег name – название задачи (task).

Доступные метрики

expirationd_checked_count{name} – количество кортежей, проверенных на истечение lifetime_hours. Включает в себя: - кортежи с истекшим lifetime_hours (expired); - пропущенные кортежи (skipped);
expirationd_expired_count{name} – количество кортежей c истекшим lifetime_hours;
expirationd_restarts{name} – количество перезапусков (restart) с начала работы (старта). При старте принимает значение 1.
expirationd_working_time{name} – время исполнения задачи в секундах.

Метрики Kafka¶

В TDG доступен мониторинг сведений о коннекторе Kafka с помощью librdkafka. librdkafka – это реализация С-библиотеки протокола Apache Kafka, которая поддерживает как producer, так и consumer. Для библиотеки по умолчанию включено регулярное предоставление внутренней статистики.

Интервал обновления метрик можно настроить, используя опцию statistics.interval.ms. По умолчанию, значение statistics.interval.ms составляет 15000 миллисекунд. Диапазон доступных значений для параметра: 0–86400000 мс. Отключить сбор статистики можно, установив значение 0.

Полное описание параметров конфигурации для коннектора Kafka приведено в справочнике по настройке коннектора.

Метрики имеют тип gauge, если не указано иначе. Имеют префикс tdg_kafka_, общий для всех метрик Kafka.

Метрики Kafka состоят из нескольких уровней:

общая статистика (Common Statistics);
статистика по брокеру (Brokers);
статистика по топику (Topics);
- статистика по разделам топика (Partitions);
статистика группы потребителей (cgrp);
статистика идемпотентного продюсера (EOS).

Большая часть операций – это оконные функции, которые применяются на отрезках времени. Поэтому уровни Topics и Brokers также включают в себя раздел про плавающие окна (Rolling Window Statistics), например, скользящую среднюю, наименьшую и наибольшую величины, сумму значений и процентные значения.

Общая статистика¶

Общая статистика по всем брокерам:

tdg_kafka_ts – внутренние монотонные часы библиотеки librdkafka в микросекундах;
tdg_kafka_time – время с начала эпохи в секундах;
tdg_kafka_age – время существования экземпляра клиента в микросекундах;
tdg_kafka_replyq – количество операций (триггеров, событий и т.д.) в очереди на обслуживание с помощью rd_kafka_poll();
tdg_kafka_msg_cnt – текущее количество сообщений в очереди продюсера;
tdg_kafka_msg_size – текущий общий размер сообщений в очередях продюсера;
tdg_kafka_msg_max – максимальное количество сообщений, разрешенное в очередях продюсера;
tdg_kafka_msg_size_max – общий размер сообщений, разрешенный в очередях продюсера;
tdg_kafka_tx – общее количество запросов, отправленных брокерам Kafka;
tdg_kafka_tx_bytes – общее количество байтов, отправленных брокерам Kafka;
tdg_kafka_rx – общее количество запросов, полученных от брокеров Kafka;
tdg_kafka_rx_bytes – общее количество байтов, полученных от брокеров Kafka;
tdg_kafka_txmsgs – общее количество сообщений, отправленных брокерам Kafka;
tdg_kafka_txmsg_bytes – общее количество байтов сообщений, отправленных брокерам Kafka (включая фрейм – например, фрейм по каждому сообщению и фрейм MessageSet/пакета);
tdg_kafka_rxmsgs – общее количество сообщений, полученных от брокеров Kafka. Не включает в себя сообщения, которые были проигнорированы – например, из-за смещения;
tdg_kafka_rxmsg_bytes – общее количество байтов сообщений (включая фрейм), полученных от брокеров Kafka;
tdg_kafka_simple_cnt – внутреннее отслеживание устаревшего и нового состояния API consumer;
tdg_kafka_metadata_cache_cnt – количество топиков в кэше метаданных.

Плавающее окно (Rolling Window Statistics)¶

Постфиксы для метрик, связанные с оконными функциями. Например, к ним относятся стандартное отклонение, наибольшая и наименьшая величина и процентные значения (процентили). Позволяют получить получать дополнительную информацию о значении некоторых метрик с уровней Topics и Brokers. Полный список доступных метрик вместе с постфиксами указан в описаниях соответствующих уровней.

Переменная {name} – имя метрики вместе с префиксом tdg_kafka_. Например, tdg_kafka_broker_int_latency_max – наибольшее значение метрики tdg_kafka_broker_int_latency.

name_min – наименьшее значение;
name_max – наибольшее значение;
name_avg – среднее значение;
name_sum – сумма значений;
name_cnt – количество выбранных значений;
name_stddev – стандартное отклонение на основе гистограммы;
name_hdrsize – объем памяти Hdr Histogram;
name_outofrange – значения, пропущенные из-за выхода за пределы диапазона гистограммы.

Процентные значения:

p50 – процентиль 0.5;
p75 – процентиль 0.75;
p90 – процентиль 0.9;
p95 – процентиль 0.95;
p99 – процентиль 0.99;
p99_99 – процентиль 0.9999.

Значения процентилей можно просмотреть для следующих метрик:

уровень Broker – tdg_kafka_broker_int_latency, tdg_kafka_broker_outbuf_latency, tdg_kafka_broker_rtt, tdg_kafka_broker_throttle;
уровень Topic – tdg_kafka_topic_batchcnt, tdg_kafka_topic_batchsize.

Статистика по брокеру¶

tdg_kafka_broker_stateage – время с момента последнего изменения состояния брокера в микросекундах;
tdg_kafka_broker_outbuf_cnt – количество запросов, ожидающих отправки брокеру;
tdg_kafka_broker_outbuf_msg_cnt – количество сообщений, ожидающих отправки брокеру;
tdg_kafka_broker_waitresp_cnt – количество запросов на пути к брокеру, ожидающих ответа;
tdg_kafka_broker_waitresp_msg_cnt – количество сообщений на пути к брокеру, ожидающих ответа;
tdg_kafka_broker_tx – общее количество отправленных запросов;
tdg_kafka_broker_txbytes – исходящий трафик в байтах;
tdg_kafka_broker_txerrs – число ошибок при передаче;
tdg_kafka_broker_txretries – общее количество повторных запросов;
tdg_kafka_broker_txidle – время с момента, как был отправлен последний сокет, в микросекундах. Если для текущего подключения еще ничего не отправлялось, имеет значение -1;
tdg_kafka_broker_req_timeouts – общее количество запросов, время ожидания для которых истекло;
tdg_kafka_broker_rx – общее число полученных ответов;
tdg_kafka_broker_rxbytes – входящий трафик в байтах;
tdg_kafka_broker_rxerrs – число ошибок при получении;
tdg_kafka_broker_rxcorriderrs – общее количество различающихся идентификаторов корреляции в ответе (обычно для запросов с истекшим временем ожидания);
tdg_kafka_broker_rxpartial – общее количество частично полученных MessageSets;
tdg_kafka_broker_rxidle – время с момента получения последнего сокета в микросекундах. Если для текущего соединенния еще нет полученных данных, имеет значение -1;
tdg_kafka_broker_zbuf_grow – общее количество увеличений размера для буфера декомпрессии;
tdg_kafka_broker_buf_grow – общее количество увеличений размера буфера (deprecated, не используется);
tdg_kafka_broker_wakeups – пробуждения пула потоков брокера;
tdg_kafka_broker_connects – количество попыток соединения. Включает в себя успешные и неудачные попытки, а также количество неудачных попыток разрешения имен;
tdg_kafka_broker_disconnects – количество разорванных соединений, вызванных брокером, сетью, балансировщиком нагрузки и т. д;
tdg_kafka_broker_req – счетчики типа запроса. Ключ объекта – это имя запроса, значение – количество отправленных запросов;
tdg_kafka_broker_int_latency – задержка внутренней очереди продюсера в микросекундах. Метрика используется только вместе с постфиксами из раздела Rolling Window Statistics.

Список доступных метрик: tdg_kafka_broker_int_latency_avg, tdg_kafka_broker_int_latency_cnt, tdg_kafka_broker_int_latency_hdrsize, tdg_kafka_broker_int_latency_max, tdg_kafka_broker_int_latency_min, tdg_kafka_broker_int_latency_outofrange, tdg_kafka_broker_int_latency_stddev, tdg_kafka_broker_int_latency_sum;
tdg_kafka_broker_outbuf_latency – задержка внутренней очереди запросов в микросекундах. Можно использовать самостоятельно или вместе с постфиксами из раздела Rolling Window Statistics.

Список доступных метрик: tdg_kafka_broker_outbuf_latency_avg, tdg_kafka_broker_outbuf_latency_cnt, tdg_kafka_broker_outbuf_latency_hdrsize, tdg_kafka_broker_outbuf_latency_max, tdg_kafka_broker_outbuf_latency_min, tdg_kafka_broker_outbuf_latency_outofrange, tdg_kafka_broker_outbuf_latency_stddev, tdg_kafka_broker_outbuf_latency_sum;
tdg_kafka_broker_rtt – задержка брокера, время обхода в микросекундах. Можно использовать самостоятельно или вместе с постфиксами из раздела Rolling Window Statistics.

Список доступных метрик: tdg_kafka_broker_rtt_avg, tdg_kafka_broker_rtt_cnt, tdg_kafka_broker_rtt_hdrsize, tdg_kafka_broker_rtt_max, tdg_kafka_broker_rtt_min, tdg_kafka_broker_rtt_outofrange, tdg_kafka_broker_rtt_stddev, tdg_kafka_broker_rtt_sum;
tdg_kafka_broker_throttle – время регулирования брокера в миллисекундах. Можно использовать самостоятельно или вместе с постфиксами из раздела Rolling Window Statistics.

Список доступных метрик: tdg_kafka_broker_throttle_avg, tdg_kafka_broker_throttle_cnt, tdg_kafka_broker_throttle_hdrsize, tdg_kafka_broker_throttle_max, tdg_kafka_broker_throttle_min, tdg_kafka_broker_throttle_outofrange, tdg_kafka_broker_throttle_stddev, tdg_kafka_broker_throttle_sum.

Статистика по топику¶

tdg_kafka_topic_age – возраст объекта клиентского топика в миллисекундах;
tdg_kafka_topic_metadata_age – возраст метаданных от брокера для данного топика в миллисекундах;
tdg_kafka_topic_batchsize – размер пакета в байтах. Метрика используется только вместе с постфиксами из раздела Rolling Window Statistics.

Список доступных метрик: tdg_kafka_topic_batchsize_avg, tdg_kafka_topic_batchsize_cnt, tdg_kafka_topic_batchsize_hdrsize, tdg_kafka_topic_batchsize_max, tdg_kafka_topic_batchsize_min, tdg_kafka_topic_batchsize_outofrange, tdg_kafka_topic_batchsize_stddev, tdg_kafka_topic_batchsize_sum;
tdg_kafka_topic_batchcnt – счетчик пакетных сообщений. Можно использовать самостоятельно или вместе с постфиксами из раздела Rolling Window Statistics.

Список доступных метрик: tdg_kafka_topic_batchcnt_avg, tdg_kafka_topic_batchcnt_cnt, tdg_kafka_topic_batchcnt_hdrsize, tdg_kafka_topic_batchcnt_max, tdg_kafka_topic_batchcnt_min, tdg_kafka_topic_batchcnt_outofrange, tdg_kafka_topic_batchcnt_stddev, tdg_kafka_topic_batchcnt_sum;
tdg_kafka_topic_partitions – разделы. Метрика используется только вместе с постфиксами из раздела Partitions.

Статистика по разделам топика¶

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

tdg_kafka_topic_partitions_broker – ID брокера, сообщения из раздела которого извлекают в текущий момент;
tdg_kafka_topic_partitions_leader – ID текущего лидера брокеров;
tdg_kafka_topic_partitions_desired – раздел, явно требуемый при применении;
tdg_kafka_topic_partitions_unknown – раздел, который не отображен в метаданных топика брокера;
tdg_kafka_topic_partitions_msgq_cnt – количество сообщений, ожидающих отправки в очереди первого уровня;
tdg_kafka_topic_partitions_msgq_bytes – количество байтов в msgq_cnt;
tdg_kafka_topic_partitions_xmit_msgq_cnt – количество сообщений в очереди выборки, готовых к отправке;
tdg_kafka_topic_partitions_xmit_msgq_bytes – количество байтов в xmit_msgq;
tdg_kafka_topic_partitions_fetchq_cnt – количество предварительно выбранных сообщений в очереди выборки;
tdg_kafka_topic_partitions_fetchq_size – размер очереди выборки в байтах;
tdg_kafka_topic_partitions_query_offset – текущий/последний запрос на логическое смещение;
tdg_kafka_topic_partitions_next_offset – следующее смещение для выборки;
tdg_kafka_topic_partitions_app_offset – смещение в разделе последнего сообщения, переданного приложению, +1;
tdg_kafka_topic_partitions_stored_offset – смещение для фиксации в разделе;
tdg_kafka_topic_partitions_committed_offset – последнее зафиксированное смещение в разделе;
tdg_kafka_topic_partitions_eof_offset – последнее сигнализированное смещение PARTITION_EOF;
tdg_kafka_topic_partitions_lo_offset – минимальное доступное смещение для раздела на брокере;
tdg_kafka_topic_partitions_hi_offset – максимальное доступное смещение для раздела на брокере;
tdg_kafka_topic_partitions_ls_offset – последнее стабильное смещение раздела на брокере;
tdg_kafka_topic_partitions_consumer_lag – разница между hi_offset или ls_offset и commit_offset;
tdg_kafka_topic_partitions_consumer_lag_stored – разница между hi_offset или ls_offset и stored_offset;
tdg_kafka_topic_partitions_txmsgs – общее количество отправленных сообщений
tdg_kafka_topic_partitions_txbytes – общее количество байтов, переданных для txmsgs
tdg_kafka_topic_partitions_rxmsgs – общее количество полученных сообщений, за исключением игнорируемых сообщений;
tdg_kafka_topic_partitions_rxbytes – общее количество байтов, полученных для rxmsgs;
tdg_kafka_topic_partitions_msgs – общее количество полученных или общее количество отправленных сообщений;
tdg_kafka_topic_partitions_rx_ver_drops – удаленные устаревшие сообщения;
tdg_kafka_topic_partitions_msgs_inflight – текущее количество сообщений на пути к брокеру или от него (in-flight);
tdg_kafka_topic_partitions_next_ack_seq – следующая ожидаемая подтвержденная последовательность (идемпотентный продюсер);
tdg_kafka_topic_partitions_next_err_seq – следующая ожидаемая последовательность с ошибкой (идемпотентный продюсер);
tdg_kafka_topic_partitions_acked_msgid – ID внутреннего сообщения c последним подтверждением (идемпотентный продюсер).

Статистика группы consumer (cgrp)¶

tdg_kafka_cgrp_stateage – время с момента последнего изменения состояния в миллисекундах;
tdg_kafka_cgrp_rebalance_age – время с момента последней ребалансировки в миллисекундах;
tdg_kafka_cgrp_rebalance_cnt – общее количество ребалансировок;
tdg_kafka_cgrp_assignment_size – количество разделов для текущего назначения.

Статистика идемпотентного продюсера (EOS)¶

Библиотека librdkafka поддерживает семантику Exactly-Once Delivery (EOS) для доставки сообщений. Такая семантика гарантирует, что сообщения будут доставлены строго один раз. За реализацию семантики отвечает свойство идемпотентности в настройках продюсера и число подтверждений об успешной записи.

tdg_kafka_eos_idemp_stateage – время с момента последнего изменения состояния ID идемпотентного продюсера (idemp_state) в миллисекундах;
tdg_kafka_eos_txn_stateage – время с момента последнего изменения состояния транзакционного продюсера txn_state в миллисекундах;
tdg_kafka_eos_txn_may_enq – состояние транзакции позволяет добавлять в очередь новые сообщения;
tdg_kafka_eos_producer_id – текущий ID продюсера (или -1);
tdg_kafka_eos_producer_epoch – текущая эпоха (или -1);
tdg_kafka_eos_epoch_cnt – число назначений ID продюсера с момента запуска.

Метрики Tarantool¶

В системе TDG доступны метрики для мониторинга работы экземпляров Tarantool.

Общая статистика¶

Общая информация о различных параметрах экземпляров Tarantool. Тип метрик – gauge.

tnt_cfg_current_time – системное время экземпляра в формате unix timestamp;
tnt_info_uptime – время с момента запуска экземпляра в секундах;
tnt_read_only – принимает значение 1, если экземпляр находится в режиме read-only, иначе – 0.

Общая статистика использования памяти¶

Тип метрик – gauge.

tnt_info_memory_cache – объем памяти в байтах, используемый для кэширования данных. Актуально для движка базы данных vinyl;
tnt_info_memory_data – объем памяти в байтах, используемый для хранения данных (кортежей);
tnt_info_memory_index – объем памяти в байтах, используемый для индексирования данных;
tnt_info_memory_lua – объем памяти в байтах, используемый средой выполнения Lua-кода;
tnt_info_memory_net – объем памяти в байтах, используемый для буферов сетевого ввода/вывода;
tnt_info_memory_tx – объем памяти в байтах, используемый активными транзакциями.

Статистика использования памяти для распределения slab¶

Распределение slab – это основное распределение, используемое для хранения кортежей. Метрики помогают отслеживать:

суммарное использование памяти;
фрагментацию памяти.

Тип метрик – gauge.

Чтобы узнать больше о вариантах использования распределения slab, обратитесь к документации модуля box.slab.

Доступная память (в байтах)¶

tnt_slab_quota_size – максимальный объем памяти в байтах, который механизм распределения slab может использовать как для кортежей, так и для индексов. Значение по умолчанию в параметре memtx_memory: 2^28 байт = 268 435 456 байт;
tnt_slab_arena_size – общий объем памяти в байтах, используемый для кортежей и индексов. Включает в себя выделенные распределения slab, свободные в текущий момент;
tnt_slab_items_size – общий объем памяти в байтах, используемый только для кортежей. Включает в себя выделенные распределения slab, свободные в текущий момент. Не используется для индексов.

Использование памяти (в байтах)¶

tnt_slab_quota_used – объем памяти в байтах, уже выделенный для распределения slab;
tnt_slab_arena_used – эффективный объем памяти в байтах, используемый для кортежей и индексов. Не включает в себя выделенные распределения slab, свободные в текущий момент;
tnt_slab_items_used – эффективный объем памяти в байтах, используемый только для кортежей. Не включает в себя выделенные распределения slab, свободные в текущий момент. Не используется для индексов.

Потребление памяти (в процентах)¶

tnt_slab_quota_used_ratio – соотношение quota_used / quota_size;
tnt_slab_arena_used_ratio – соотношение arena_used / arena_size;
tnt_slab_items_used_ratio – соотношение items_used / slab_count * slab_size. Это распределения slab, которые используются только для кортежей, не для индексов.

Статистика использования памяти в конкретных спейсах¶

Все метрики, за исключением tnt_space_index_bsize, имеют два тега:

name – имя спейса;
engine – движок базы данных, используемый для этого спейса.

Тип метрик – gauge.

Доступные метрики

tnt_space_len{name,engine} – количество кортежей в спейсе;
tnt_space_bsize{name,engine} – количество байтов, которые занимает спейс (количество байтов во всех кортежах, включая ключи индекса);
tnt_space_index_bsize{name,index_name} – количество байтов, занятых под индексы. Метрика также имеет тег index_name – название индекса.
tnt_space_total_bsize{name,engine} – суммарное количество байтов space_bsize + space_index_bsize;
tnt_vinyl_tuples{name,engine} – суммарное количество кортежей для движка vinyl.

Статистика сетевой активности¶

Мониторинг нагрузки сети, пиков использования и падения трафика. Начиная с версии Tarantool 2.10, метрики имеют тег thread, который отображает сетевую статистику для каждого потока.

Трафик¶

Тип метрик – counter.

tnt_net_sent_total – исходящий трафик в байтах;
tnt_net_received_total – входящий трафик в байтах.

Сетевые соединения¶

tnt_net_connections_total – общее количество входящих сетевых соединений с момента запуска экземпляра. Тип метрики: counter;
tnt_net_connections_current – текущее количество входящих сетевых соединений. Тип метрики: gauge.

Сетевые запросы¶

tnt_net_requests_total – общее количество входящих сетевых запросов с момента запуска экземпляра. Тип метрики: counter;
tnt_net_requests_current – текущее количество входящих сетевых запросов в обработке. Может быть ограничено параметром конфигурации базы данных net_msg_max. Тип метрики: gauge;
tnt_net_requests_in_progress_total – общее количество сетевых запросов, обработанных потоком процессора транзакций (TX thread). Тип метрики: counter;
tnt_net_requests_in_progress_current – количество сетевых запросов, которые обрабатывает поток процессора транзакций (TX thread) в текущий момент. Тип метрики: gauge;
tnt_net_requests_in_stream_queue_total – общее количество сетевых запросов, помещенных в очереди стримов за все время потоком процессора транзакций (TX thread). Тип метрики: counter;
tnt_net_requests_in_stream_queue_current – количество сетевых запросов, ожидающих обработки в очередях стримов в текущий момент. Тип метрики: gauge.

Информация о файберах¶

Статистика по файберам. Тип метрик – gauge.

tnt_fiber_amount – общее количество файберов;
tnt_fiber_csw – количество переключений контекста для всех файберов;
tnt_fiber_memalloc – общий объем памяти в байтах, выделенный под файберы;
tnt_fiber_memused – объем памяти в байтах, используемый файберами.

Статистика входящих запросов (по типу запросов)¶

Тип метрики – gauge.

tnt_stats_op_total{operation} – общее количество запросов данного типа с момента запуска экземпляра.

Метрика имеет тег operation – тип входящего запроса, приходящего по бинарному протоколу. Возможные типы запроса:

auth – запросы на аутентификацию;
call – запросы на выполнение хранимой процедуры;
delete – запросы на удаление;
error – запросы, завершившиеся с ошибкой;
eval – запросы на выполнение Lua-кода;
execute – выполнение SQL-запросов;
insert – запросы на вставку;
prepare – запросы SQL prepare;
replace – запросы на замену;
select – запросы на поиск;
update – запросы на обновление;
upsert – запрос на обновление или вставку.

Информация о репликации¶

Текущий статус репликации. Тип метрик – gauge.

tnt_info_lsn – LSN (log sequence number, регистрационный номер в журнале) данного экземпляра;
tnt_info_vclock{id} – значение LSN из пары id: lsn в векторных часах, где id – идентификатор экземпляра в наборе реплик, lsn – регистрационный номер в журнале. Метрика имеет тег id – идентификатор экземпляра в наборе реплик.
tnt_replication_lsn{id,type} – LSN экземпляра Tarantool. Метрика имеет теги:
- id – идентификатор экземпляра в наборе реплик;
- type – тип. Возможные значения: master, replica;
tnt_replication_lag{id,stream} – значение лага репликации в секундах. Метрика имеет теги:
- id – идентификатор экземпляра в наборе реплик;
- stream – тип. Возможные значения: downstream, upstream.
tnt_replication_status{id,stream} – принимает значение 1 при статусе репликации follow, иначе – 0. Метрика имеет теги:
- id – идентификатор экземпляра в наборе реплик;
- stream – тип. Возможные значения: downstream, upstream.

Информация о синхронной репликации¶

Текущее состояние синхронной репликации. Тип метрик – gauge.

tnt_synchro_queue_owner – ID экземпляра, который является лидером синхронной репликации в текущий момент;
tnt_synchro_queue_term – текущий терм очереди;
tnt_synchro_queue_len – количество транзакций, собирающих подтверждения в текущий момент;
tnt_synchro_queue_busy – значение 1, если очередь обрабатывает системный запрос (CONFIRM/ROLLBACK/PROMOTE/DEMOTE), иначе – 0.

Метрики работы экземпляров Tarantool в кластере¶

Тип метрик – gauge.

tnt_cartridge_issues{level} – количество ошибок в работе экземпляра. Метрика имеет тег level – это уровень критичности ошибки:
- critical – критические ошибки в работе экземпляра. Пример: используется более 90% памяти;
- warning – другие ошибки в работе кластера. Пример: ошибки репликации на экземпляре;
tnt_cartridge_cluster_issues – суммарное количество ошибок в работе экземпляра в кластере;
tnt_clock_delta{delta} – рассинхронизация часов в кластере в секундах (разница во времени между локальными часами и часами другого экземпляра). Положительное значение указывает на то, что часы другого экземпляра опережают локальные. Отрицательное значение — на то, что часы другого экземпляра отстают от локальных. Метрика имеет тег delta. Возможные значения тега:
- max – разница с абсолютным максимальным значением часов (всегда положительная);
- min – разница с абсолютным минимальным значением часов (всегда отрицательная);
tnt_cartridge_failover_trigger_total – количество триггеров аварийного переключения в кластере.

Информация о выборах лидера¶

Текущее состояние узла в наборе реплик относительно выборов лидера. Тип метрик – gauge.

tnt_election_state – состояние узла во время выборов лидера. Когда выборы включены, узел доступен для записи только в состоянии лидера. Возможные значения:
- 0 (follower) – все узлы, не являющиеся лидерами (реплики);
- 1 (candidate) – узлы, начавшие новый раунд выборов (кандидаты);
- 2 (leader) – узел, набравший необходимый кворум голосов (лидер);
tnt_election_vote – ID узла, за который голосует текущий узел. Принимает значение 0, если узел еще не проголосовал в текущем терме;
tnt_election_leader – ID узла, который является лидером в текущем терме. Принимает значение 0, если узлу недоступна информация о лидере в текущем терме.
tnt_election_term – текущий терм выборов.

Статистика использования памяти для среды выполнения Lua-кода¶

Тип метрик – gauge.

tnt_runtime_lua – объем динамической памяти сборщика мусора в Lua в байтах;
tnt_runtime_used – объем памяти в байтах, используемый Lua в данный момент;
tnt_runtime_tuple – объем памяти в байтах, используемый для кортежей (кроме кортежей memtx и vinyl).

Метрики LuaJIT¶

Общая статистика JIT, работа сборщика мусора Lua и статистика выделения (аллокации) памяти. Метрики доступны, начиная с версии Tarantool 2.6

Общие метрики JIT¶

lj_jit_snap_restore_total – общее количество восстановлений стека при выходе с трассы. Тип метрики: counter;

lj_jit_trace_num – количество скомпилированных трасс. Тип метрики: gauge;

lj_jit_trace_abort_total – общее количество прерванных компиляций. Тип метрики: counter;

lj_jit_mcode_size – общий объем выделенного машинного кода в байтах. Тип метрики: gauge.

JIT-строки¶

lj_strhash_hit_total – количество интернированных строк. Тип метрики: counter;

lj_strhash_miss_total – общее количество выделенных строк. Тип метрики: counter.

Шаги сборщика мусора¶

lj_gc_steps_atomic_total – количество шагов инкрементального сборщика мусора (фаза atomic). Тип метрики: counter;

lj_gc_steps_sweepstring_total – количество шагов инкрементального сборщика мусора (фаза sweep для строк). Тип метрики: counter;

lj_gc_steps_finalize_total – количество шагов инкрементального сборщика мусора (фаза finalize). Тип метрики: counter;

lj_gc_steps_sweep_total – количество шагов инкрементального сборщика мусора (фаза sweep). Тип метрики: counter;

lj_gc_steps_propagate_total – количество шагов инкрементального сборщика мусора (фаза propagate). Тип метрики: counter;

lj_gc_steps_pause_total – количество шагов инкрементального сборщика мусора (фаза pause). Тип метрики: counter.

Выделение памяти¶

lj_gc_strnum – количество выделенных объектов string. Тип метрики: gauge;

lj_gc_tabnum – количество выделенных объектов table. Тип метрики: gauge;

lj_gc_cdatanum – количество выделенных объектов cdata. Тип метрики: gauge;

lj_gc_udatanum – количество выделенных объектов udata. Тип метрики: gauge;

lj_gc_freed_total – объем освобожденной памяти в байтах. Тип метрики: counter;

lj_gc_memory – текущий объем выделенной Lua-памяти в байтах. Тип метрики: gauge;

lj_gc_allocated_total – объем выделенной памяти в байтах. Тип метрики: counter.

Статистика CPU¶

Информация об использовании процессора. Метрики доступны только для Linux. Тип метрик – gauge.

tnt_cpu_number – общее количество процессоров, сконфигурированных операционной системой;
tnt_cpu_time – процессорное время хоста в секундах;
tnt_cpu_thread{kind,thread_name,thread_pid,file_name} – процессорное время потока Tarantool. Метрика имеет теги:
- kind – вид. Возможные значения: user, system;
- thread_name – имя потока. Возможные значения: tarantool, wal, iproto, coio;
- thread_pid – PID (process ID), идентификатор потока;
- file_name – имя файла точки входа, например, init.lua;
tnt_cpu_user_time – использованное пользовательское время процессора в секундах;
tnt_cpu_system_time – использованное системное время процессора в секундах.

Статистика работы движка vinyl¶

Информация о работе движка vinyl. Тип метрик – gauge.

Disk¶

Дисковые метрики используются для мониторинга общего объема данных на диске.

tnt_vinyl_disk_data_size – количество данных в байтах, которое хранится в файлах .run. Файлы .run расположены в директории vinyl_dir;
tnt_vinyl_disk_index_size – количество данных в байтах, которое хранится в файлах .index. Файлы .index расположены в директории vinyl_dir.

Regulator¶

Регулятор движка vinyl определяет, когда начинать действия по дисковому IO, и группирует их в пакеты.

tnt_vinyl_regulator_dump_bandwidth – пропускная способность дампа, байты в секунду;
tnt_vinyl_regulator_write_rate – фактическая средняя скорость выполнения операций записи, байты в секунду;
tnt_vinyl_regulator_rate_limit – ограничение скорости записи, байты в секунду;
tnt_vinyl_regulator_dump_watermark – максимальный объем памяти в байтах, используемый для in-memory хранения LSM-дерева движка vinyl.
tnt_vinyl_regulator_blocked_writers – количество файберов, заблокированных в ожидании квоты памяти движка vinyl для “Уровня 0” (L0).

Transactional activity¶

Работа с транзакциями.

tnt_vinyl_tx_commit – счетчик коммитов (успешных завершений транзакций). Включает в себя неявные коммиты. Например, операция на вставку вызывает неявный коммит, если только операция не находится в блоке begin–commit;
tnt_vinyl_tx_rollback – счетчик откатов (неудачных завершений транзакций). Включает в себя:
- явные запросы на rollback;
- запросы, завершившиеся с ошибкой;
tnt_vinyl_tx_conflict – счетчик конфликтов, которые привели к откату транзакций;
tnt_vinyl_tx_read_views – текущее количество транзакций, которые перешли в состояние read-only, чтобы временно избежать конфликта.

Memory¶

Области памяти, используемые движком vinyl для кэша и буферов записи.

tnt_vinyl_memory_tuple_cache – объем памяти в байтах, используемый в настоящее время для хранения кортежей (данных);
tnt_vinyl_memory_level0 – область памяти “Уровень 0” (L0) в байтах;
tnt_vinyl_memory_page_index – объем памяти в байтах, используемый в настоящее время для хранения индексов;
tnt_vinyl_memory_bloom_filter – объем памяти в байтах, используемый фильтрами bloom.

Scheduler¶

Планировщик движка vinyl, который раз в секунду вызывает регулятор и обновляет связанные с ним переменные.

tnt_vinyl_scheduler_tasks{status} – количество задач планировщика на дамп / сжатие. Метрика имеет тег status. Возможные значения тега:
- inprogress – для задач, запущенных в данный момент;
- completed – для успешно завершенных задач;
- failed – для задач, прерванных из-за ошибок;
tnt_vinyl_scheduler_dump_time – общее время в секундах, затраченное всеми рабочими потоками на выполнение дампов;
tnt_vinyl_scheduler_dump_count – счетчик выполненных дампов.

Статистика цикла событий¶

Информация о потоке транзакций цикла событий. Тип метрик – gauge.

tnt_ev_loop_time – время цикла событий в миллисекундах;
tnt_ev_loop_prolog_time – время пролога цикла событий в миллисекундах;
tnt_ev_loop_epilog_time – время эпилога цикла событий в миллисекундах.

Maintenance¶

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

Резервное копирование

Резервное копирование¶

Создание резервной копии¶

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

файлы-снимки (*.snap);
WAL-файлы (*.xlog);
файл .tarantool.cookie;
директорию /config.

Инструкции по резервному копированию экземпляров Tarantool приведены в документации Tarantool.

Восстановление из резервной копии¶

Для восстановления кластера TDG из резервной копии поместите содержимое резервной копии каждого экземпляра в соответствующую рабочую директорию. Содержимое резервной копии экземпляра включает:

файлы-снимки (*.snap);
WAL-файлы (*.xlog);
файл .tarantool.cookie;
директорию /config.

После этого запустите кластер.

Cluster management¶

В этой главе рассказано, как управлять кластером TDG: изменять топологию, добавляя и исключая узлы, задавать настройки восстановления после сбоев (failover) и так далее.

Adding cluster nodes

Adding cluster nodes¶

Добавление нового узла (экземпляра) в кластер TDG – это фактически та же операция развертывания.

In this example, you will take the already deployed TDG cluster, deploy a new TDG instance and configure it via web interface by creating a new replica set with the storage cluster role.

For deploying a new instance, you will use the same tar.gz package and the Ansible tool with the predefined inventory and playbook configuration as for the initial cluster deployment.

Navigate to the deploy directory extracted earlier from the tar.gz package and edit the Ansible inventory file hosts.yml. You need to add the description of a new instance and its parameters. In the code block below, parameters that should be added are marked with the comments # <-- Add ....

children:
  tdg_group:

    ### Instances ###

    hosts:

      ...

      storage_3:  # <-- Добавьте новый экземпляр и параметры конфигурации для него
        config:
          advertise_uri: "172.19.0.2:3005"
          http_port: 8085
          memtx_memory: 1073741824  # 1024 Mb

    children:

      ### Machines ###

      vm1:
        hosts:
          stateboard_instance:
          core:
          runner_1:
          storage_1:
          storage_2:
          storage_3:  # <-- Добавьте этот экземпляр к hosts на vm1
        vars:
          ansible_host: "172.19.0.2"

Important

While editing hosts.yml, double-check the following parameters:

cartridge_package_path—use the same package of the same application version you used for initial cluster deployment.
cartridge_cluster_cookie—should be the same as it was during the initial deployment. Otherwise, the new instance won’t be included in the cluster.

Deploy a new instance by using the deploy_without_topology.yml playbook:
```
$ ansible-playbook -i hosts.yml --limit storage_3 playbooks/deploy_without_topology.yml
```
The --limit option is used to apply the playbook steps only to the specified instance and avoid any changes for the existing ones.
Откройте или обновите страницу с интерфейсом TDG. В нашем примере она находится по адресу http://172.19.0.2:8081. Новый экземпляр появится на вкладке Cluster в разделе Unconfigured servers.
The last step is to create a new replica set with the “storage” role. For the “storage_3” instance, click Configure. In the Configure server dialog, specify the following parameters and click Create replica set:
- Replica set name: storage_3
- Roles: storage
- Replica set weight: 1

The Replica set weight parameter should be set to the same value as for other replica sets with the “storage” role. It is necessary to run automatic data rebalancing between the storages upon creating a new storage.

You can verify if rebalancing was done correctly by checking out the Buckets parameter: the value should be the same for storage instances on the same server (172.19.0.2 in this example). Rebalancing process takes some time, so you may need to wait a bit and refresh the page to see the result in web interface.

Developer’s guide¶

This document explains how to work with Tarantool Data Grid (TDG) if you are a developer.

Hello world with Lua¶

This guide explains how to set up a data model, run data queries, and write a couple of stored procedures in Lua.

Для начала вам понадобится запущенный экземпляр TDG. Можно запустить TDG в Docker-контейнере или же развернуть его на локальной машине вручную или с помощью Ansible.

Then you will learn how to:

Set up the data model.
Run data queries.
Write stored procedures.

Setting up the data model¶

This guide uses a data model that contains two types of objects: music bands and artists. Each music band has a name, a genre, and a year it was formed. Artists have a name, a country, and the instruments they play.

Here is an example of such a model:

[
    {
        "name": "MusicBand",
        "type": "record",
        "fields": [
            {"name": "name", "type": "string"},
            {"name": "genre", "type": {"type":"array", "items":"string"}},
            {"name": "wasformed", "type":"long"}
        ],
        "indexes": ["name", "genre", "wasformed"]
    },
    {
        "name": "Artist",
        "type": "record",
        "fields": [
            {"name": "fullname", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "instruments", "type": {"type":"array", "items":"string"}}
        ],
        "indexes": ["fullname"]
    }
]

In the menu on the left, there is a tab called Model. Switch to this tab and paste the model to the Request field. Click Submit:

You have set up the data model. Now you can upload, select, and delete data.

Uploading data to TDG¶

In the menu on the left, there is a tab called Graphql. Switch to this tab, select default as the desired scheme, and clear the request field:

Paste the following data to the request field:

mutation all {
  rammstein:MusicBand(insert: {
      name: "Rammstein",
      genre: ["metal", "industrial", "gothic"],
      wasformed: 1994}) {
    name
    genre
    wasformed
  }
  linkinpark:MusicBand(insert: {
      name: "Linkin Park",
      genre: ["alternative", "metal"],
      wasformed: 1996}) {
    name
    genre
    wasformed
  }
  blacksabbath:MusicBand(insert: {
      name: "Black Sabbath",
      genre: ["gothic", "metal"],
      wasformed: 1968}) {
    name
    genre
    wasformed
  }
  deeppurple:MusicBand(insert:{
      name: "Deep Purple",
      genre: ["metal", "rock"],
      wasformed: 1968}) {
    name
    genre
    wasformed
  }
  maxkorzh:MusicBand(insert:{
      name:"Max Korzh",
      genre:["rap", "electro"],
      wasformed: 2006}) {
    name
    genre
    wasformed
  }
}

Execute query by clicking the play button:

The data is now uploaded.

Running data queries¶

Reading data¶

You can read data in the Graphql tab. Make sure the default scheme is switched on, clear the field on the left, and write a request that selects every music band:

query {
  MusicBand {
    name
    wasformed
    genre
  }
}

Click the play button. In the right field, you’ll get the result:

Select data by the primary key:

query {
  MusicBand(name:"Black Sabbath") {
    name
    wasformed
    genre
  }
}

After clicking the play button, you will get all stored information about the Black Sabbath music band:

Чтение данных об одной музыкальной группе

Changing data¶

Add one more music genre to one of the music bands. In the Graphql tab, insert the data about the band with two genres instead of one:

mutation {
  MusicBand(insert:{
      name: "Deep Purple",
      genre: ["metal", "rock"],
      wasformed: 1968}) {
        name
        genre
        wasformed
  }
}

Click the play button. The information about the Deep Purple music band is now updated.

Deleting data¶

In the Graphql tab, write the query to delete all data about one of the music bands:

mutation {
  MusicBand(name:"Linkin Park" delete:true) {
    name
    genre
    wasformed
  }
}

Click the play button. You’ve deleted the data about the Linkin Park music band.

Writing stored procedures¶

Hello World¶

In the menu on the left, there is a tab called Code. Switch to the tab and create the src directory. In the src directory, create the hello.lua file, which is a Lua module that exports the functions:

function hello()
  return "Hello World"
end

return {
  hello = hello
}

Click Apply:

This Lua module requires a GraphQL interface. In the Code tab, create a file called services.yml and specify the signature of the GraphQL call:

hello_world:
  doc: "Hello World script"
  function: hello.hello
  return_type: string

Click Apply:

The code is validated and uploaded to the cluster. If there is an error, a notification at the bottom right corner will give you the details about it.

Now switch to the Graphql tab, select default the desired scheme, and call the stored procedure:

{
  hello_world
}

In the right field, you’ll get the result:

Randomized playlist¶

In the dataset, there are various music bands. Make a stored procedure to give you a randomized playlist.

In the Code tab, open the src directory and create a file called playlist.lua. This file defines the logic to generate a randomized playlist:

local repository = require('repository')

function shuffle(tbl)
  for i = #tbl, 2, -1 do
    local j = math.random(i)
    tbl[i], tbl[j] = tbl[j], tbl[i]
  end
  return tbl
end

function playlist()
  local result = repository.find("MusicBand", {})
  result = result or {}
  shuffle(result)
  return result
end

return {
    playlist=playlist
}

In the services.yml, specify the signature of the GraphQL call:

playlist:
    doc: "Return randomized playlist"
    function: playlist.playlist
    return_type: {"type":"array", "items":"MusicBand"}

Switch to the Graphql tab and run this command:

{
    playlist { name }
}

Click the play button. As a result, you’ll get a randomized playlist:

Each time you click the play button, you’ll get a different playlist.

Data model¶

В этой главе подробно описана структура модели данных TDG, а также перечислены доступные способы работы с ней – в файле и в веб-интерфейсе. В главе рассмотрен пример создания модели данных и её загрузки в TDG. Для выполнения примера требуется настроенный кластер TDG.

Язык модели данных
Определение модели данных
Загрузка модели данных
Расширения модели данных
Логические типы данных

Язык модели данных ¶

Модель данных включает в себя:

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

В TDG для описания модели данных используются язык Avro Schema, а также расширения, разработанные специально для системы TDG.

Схема в стандарте Avro Schema – это JSON-файл с расширением .avsc, содержащий описание типов данных для объектов и для их полей. Приложение использует схему в качестве формата и понимает ее, как массив типов объектов:

[
    {"name": "TypeA", "type": "record", ...},
    {"name": "TypeB", "type": "record", ...}
]

Все типы объектов соответствуют стандарту Avro Schema, за исключением расширений для системы TDG. Расширения обратно совместимы, а модель, описанная с их помощью, успешно преобразуется стандартными парсерами (синтаксическими анализаторами).

Определение модели данных ¶

Для начала зададим модель данных с двумя типами объектов – Country (страна) и City (город). В качестве примера возьмем следующую диаграмму объектов:

Теперь представим модель с диаграммы в виде схемы данных Avro:

[
    {
        "name": "Country",
        "type": "record",
        "doc": "Страна",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "phone_code", "type": ["null", "string"]}
        ],
        "indexes": ["title"],
        "relations": [
            { "name": "city_relation", "to": "City", "count": "many", "from_fields": "title", "to_fields": "country" }
        ]
    },
    {
        "name": "City",
        "type": "record",
        "doc": "Город",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "population", "type": "int"},
            {"name": "capital", "type": "boolean"},
            {"name": "postcodes", "type": {"type":"array", "items":"int"}}
        ],
        "indexes": [
            {"name":"primary", "parts":["title", "country"]},
            "title",
            "country",
            "population",
            "postcodes"
        ]
    }
]

где

name – название типа объекта;
type – вид схемы;
doc – текстовое описание для типа объекта;
fields – поля для типа объекта вместе с соответствующими им типами данных.
- name – название поля;
- type – тип данных для поля.
Note

Если в модели данных есть опциональное поле, его тип данных описывают с помощью объединяющего массива union. Такой массив содержит основной тип данных для этого поля и тип null. Пример:
```
{"name": "phone_code", "type": ["null", "string"]}
```
indexes – индексы, которые используются при выполнении операций. Первый по счету индекс в списке является первичным. Поле indexes – расширение TDG для задания ключей;
relations – вид связи между объектами. В этой модели данных типы объектов Country и City имеют связь один ко многим, так как в одной стране обычно расположено много городов. Поле relations – расширение TDG для задания отношений между объектами.

Описания всех доступных расширений TDG приведены в разделе Расширения модели данных.

Загрузка модели данных ¶

Чтобы применить модель данных и делать запросы к данным, нужно загрузить модель данных в TDG. Основные способы загрузки данных:

через веб-интерфейс на вкладке Model;
в файле .avsc, который будет запакован в архив вместе с файлом конфигурации.

Загрузка через веб-интерфейс¶

Чтобы загрузить модель данных через веб-интерфейс TDG, выполните следующие шаги:

Откройте веб-интерфейс на экземпляре, входящем в набор реплик с кластерной ролью runner. Если вы используете уже развернутый TDG-кластер, URL экземпляра будет следующий: http://172.19.0.2:8082.
В веб-интерфейсе выберите вкладку Model.
Вставьте созданную модель данных в поле Request.
Нажмите Submit. Если модель данных загружена успешно, в окне Response появится ответ OK.

Загрузка в составе zip-архива¶

Загрузить модель данных можно также в составе zip-архива вместе с файлом конфигурации. Для этого:

Упакуйте в zip-архив:
- модель данных в файле с расширением .avsc, например, model.avsc;
- файл конфигурации config.yml.
Загрузите архив в TDG согласно инструкции.

Расширения модели данных ¶

Расширения для системы TDG дополняют спецификацию Avro Schema. Эти расширения позволяют:

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

Задание отношений между объектами¶

Явно задавать связи между объектами нужно:

для валидации внешних ключей при вставке объектов;
для запросов связанных объектов через GraphQL.

Чтобы указать такую связь, используется поле relations в теле описания типа объекта. Это поле игнорируется существующими парсерами Avro Schema. Связываемые поля (внешние ключи в терминологии SQL) должны быть объявлены на уровне типов объектов.

Например, чтобы задать связь между страной и ее городами, требуются следующие поля:

title (Country) – первичный ключ доступен через обращение к типу объекта Country.title;
country (City) – внешний ключ доступен через обращение к типу объекта City.country.

Пример поля relations из заданной ранее модели данных:

{
    "relations": [
        {
            "name": "city_relation",
            "to": "City",
            "count": "many",
            "from_fields": "title",
            "to_fields": "country"
        },
        ...
    ]
}

где:

name – название поля, через которое можно получить связанные объекты в GraphQL-запросах;
to – тип объекта, с которым устанавливается связь;
count – вид связи. Возможные значения:
- one – связь один к одному;
- many – связь один ко многим;
from_fields – название поля или индекса, содержащего первичный ключ. Возможные значения:
- название индекса ("from_fields": "title");
- название поля ("from_fields": "field_name");
- список названий полей ("from_fields": ["field_name1", "field_name2"]);
to_fields – название поля или индекса, содержащего внешний ключ. Возможные значения:
- название индекса ("to_fields": "country");
- название поля ("to_fields": "field_name");
- список названий полей ("to_fields": ["field_name1", "field_name2"]).

Все параметры поля обязательные.

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

Дополним модель данных еще одним полем relations (City), чтобы можно было запрашивать данные в обоих направлениях. Полный пример может выглядеть так:

[
    {
        "name": "Country",
        "type": "record",
        "doc": "Страна",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "phone_code", "type": ["null", "string"]}
        ],
        "indexes": ["title"],
        "relations": [
            {"name": "city_relation", "to": "City", "count": "many", "from_fields": "title", "to_fields": "country"}
        ]
    },
    {
        "name": "City",
        "type": "record",
        "doc": "Город",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "population", "type": "int"},
            {"name": "capital", "type": "boolean"},
            {"name": "postcodes", "type": {"type":"array", "items":"int"}}
        ],
        "indexes": [
            {"name":"primary", "parts":["title", "country"]},
            "title",
            "country",
            "population",
            "postcodes"
        ],
        "relations": [
            {"name": "country_relation", "to": "Country", "count": "one", "from_fields": "country", "to_fields": "title"}
        ]
    }
]

Задание индексов (ключей)¶

Для задания индексов используется поле indexes в описании типа объекта. Поле не меняет поведение, регулируемое стандартом Avro Schema, а добавляет дополнительные ограничения на хранение и запросы. Если для типа объекта указаны индексы, TDG создает спейсы под этот тип.

Note

Если поле indexes содержит список индексов, первичным индексом считается первый индекс в списке.

Синтаксис поля indexes:

{
    "indexes": ["<index1>", <"index2">, <"index3">, ...]
}

Каждый индекс в поле indexes может быть задан в виде:

строки с названием поля, по которому будет построен индекс ("indexes": ["title"]);
словаря, на основе которого строятся составной индекс или индекс по полю вложенного объекта. Такой индекс указывается в следующем формате:
```
{
    "name": "<index_name>",
    "parts": [
        {"path": "<field_name>", "collation": "<collation_type>"},
        {"path": "<field_name>", "collation": "<collation_type>"},
        ...
    ]
}
```
где:
- name – название индекса, не совпадающее с именами существующих полей;
- parts – части индекса. Включает в себя:
  - path – названия полей, по которым строится индекс;
  - collation (опционально) – способ сравнения строк. Возможные значения:
    - binary (по умолчанию) – бинарное сравнение ('A' < 'B' < 'a');
    - case_sensitivity – сравнение, зависящее от регистра ('a' < 'A' < 'B');
    - case_insensitivity – сравнение, не зависящее от регистра (('a' = 'A') < 'B' и 'a' = 'A' = 'á' = 'Á').

Note

Существуют ограничения при использовании в поле indexes мультиключевого индекса – индекса по полю, содержащему массив. Подробная информация об этих ограничениях приведена в разделе Запросы по мультиключевому индексу.

Пример составного индекса

{
    "name": "City",
    "type": "record",
    "fields": [
        {"name": "title", "type": "string"},
        {"name": "country", "type": "string"},
        {"name": "population", "type": "int"},
        {"name": "capital", "type": "boolean"},
        {"name": "postcodes", "type": {"type":"array", "items":"int"}}
    ],
    "indexes": [
        {"name":"primary", "parts":["title", "country"]},
        "title",
        "country",
        "population",
        "postcodes"
    ]
}

Пример индексации по полю вложенного объекта

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

Note

Тип объекта можно использовать как вложенный только в случае, если у этого типа не задано поле indexes.

Например, представьте, что каждая страна (Country) в примере содержит дополнительный блок информации для туристов. Создадим новый тип объекта Info и сложный индекс в типе объекта Country. Тип объекта Info включается здесь непосредственно в тип объекта Country, поэтому индекс может сослаться на поле из Info:

[
    {
        "name": "Info",
        "type": "record",
        "doc": "Информация для туристов",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "info_text", "type": "string"}
        ]
    },
    {
        "name": "Country",
        "type": "record",
        "doc": "Страна",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "info", "type": "Info"},
            {"name": "phone_code", "type": ["null", "string"]}
        ],
        "indexes": [
            "title",
            {"name": "info_id", "parts": ["info.id"]}
        ]
    }
]

Распределение объектов по хранилищам¶

В случае распределенного хранилища данных объекты распределяются с использованием хеш-функции от первичного ключа объекта. Указать такой индекс можно в поле affinity.

Note

Поле affinity может содержать только те поля, которые входят в первичный ключ (в том числе составной).

Пример

Перед загрузкой модели с новым полем affinity удалите старую модель данных. Кроме того, проверьте список спейсов во вкладке Settings > Unlinked spaces в веб-интерфейсе TDG. Если в списке есть спейсы с типом объекта City, удалите их, чтобы избежать ошибки при загрузке новой модели.

Теперь дополните модель данных новым полем и загрузите модель в TDG:

{
    "name": "City",
    "type": "record",
    "doc": "Город",
    "fields": [
        {"name": "title", "type": "string"},
        {"name": "country", "type": "string"},
        {"name": "population", "type": "int"},
        {"name": "capital", "type": "boolean"},
        {"name": "postcodes", "type": {"type":"array", "items":"int"}}
    ],
    "indexes": [
        {"name":"primary", "parts":["title", "country"]},
        "title",
        "country",
        "population",
        "postcodes"
    ],
    "affinity": ["country"]
}

В примере города одной и той же страны размещены физически на одном хранилище. Поле affinity при этом содержит индекс из составного первичного ключа.

Атрибуты полей¶

Расширение для TDG дополняет список стандартных атрибутов полей Avro Schema:

default_function (function) – задает для поля динамическое значение по умолчанию. Значение атрибута – это функция, файл с которой хранится в директории src в корне проекта. При вставке в спейс новой записи вызывается указанная функция, и результат функции становится значением для данного поля. Атрибут не стоит путать со стандартным атрибутом default, который задает для поля статическое значение;
auto_increment (boolean) – значение true делает поле автоинкрементным. По умолчанию: false. Может использоваться в качестве числового идентификатора, уникального для объектов данного типа, даже при шардировании базы данных. Автоинкрементное поле обязательно должно иметь тип long. Атрибут несовместим с атрибутами default и default_function.

Пример

Расширьте тип объекта City этими атрибутами:

задайте по умолчанию для поля population динамическое значение;
добавьте поле с числовым идентификатором города.

Обновленные поля объекта могут выглядеть так:

{
    "name": "City",
    "type": "record",
    "fields": [
        {"name": "city_id", "type": "long", "auto_increment": true},
        {"name": "title", "type": "string"},
        {"name": "country", "type": "string"},
        {"name": "population", "type": "int", "default" : "count_population.call"}},
        ...
    ],
    ...
}

Логические типы данных ¶

Логический тип – это простой или составной тип данных Avro, содержащий дополнительные атрибуты для представления нового типа данных для поля. Чтобы объявить в модели поле с логическим типом, используется атрибут logicalType. Поля этих типов можно использовать при построении любых индексов, кроме мультиключевых. По умолчанию для логических типов задается строковый тип данных.

TDG поддерживает следующие логические типы:

Date – дата. Хранится в виде int. Формат записи: YYYY-MM-DDZ;
Time – время. Хранится в виде int. Формат записи: HH:MM:SSZ;
Datetime – дата и время. Хранится в виде int. Форматы записи:
- дата и время с миллисекундами: YYYY-MM-DDTHH:MM:SS.sssZ;
- дата и время с микросекундами: YYYY-MM-DDTHH:MM:SS.ssssssZ;
- дата и время с наносекундами: YYYY-MM-DDTHH:MM:SS.sssssssssZ.
Note

Начиная с версии TDG 2.7, тип DateTime объявлен устаревшим, используйте вместо него тип Timestamp.
Timestamp – тип для работы с датой и временем на основе Tarantool-модуля datetime;
Decimal – вычисления с точными числами. Пример записи: 10.001. Тип использует Tarantool-модуль decimal;
UUID – уникальный идентификатор. Формат записи: 00000000-0000-0000-0000-000000000000. Тип использует Tarantool-модуль uuid.

Примеры объявления полей с логическими типами:

[
    {
        "name": "LogicalTypes",
        "type": "record",
        "fields": [
            {"name": "id", "type": {"type": "string", "logicalType": "Timestamp"}},
            {"name": "datetime", "type": ["null", {"type": "string", "logicalType": "DateTime"}]},
            {"name": "time", "type": ["null", {"type": "string", "logicalType": "Time"}]},
            {"name": "date", "type": ["null", {"type": "string", "logicalType": "Date"}]},
            {"name": "decimal", "type": ["null", {"type": "string", "logicalType": "Decimal"}]},
            {"name": "uuid", "type": ["null", {"type": "string", "logicalType": "UUID"}]}
        ],
    "indexes": ["id", "datetime", "time", "date", "decimal", "uuid"]
    }
]

Авторизация¶

Авторизация и отправка HTTP-запроса¶

Чтобы HTTP-запрос был обработан, он должен пройти авторизацию по токену приложений. Заранее сгенерированный (например, в веб-интерфейсе TDG) токен приложений необходимо передать в HTTP-заголовке запроса по схеме Authorization: Bearer <token>, где:

Authorization – имя заголовка;
Bearer – схема HTTP-аутентификации;
<token> – ключ токена.

Пример

Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d

Important

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

В HTTP-запросе в заголовке указывается один из двух вариантов схемы данных:

схема default (по умолчанию) – работа с пользовательскими данными. Если схема данных в заголовке пропущена, для запроса используется схема default.
схема admin – управление настройками TDG.

Для выполнения запросов в примерах ниже используется утилита curl.

Пример запроса на добавление данных в схеме default:

curl --request POST \
  --url http://172.19.0.2:8080/graphql \
  --header 'Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d' \
  --data '{"query":"mutation{  Country(insert: {  title: \"Poland\", phone_code:\"+48\"}) {title phone_code}}"}'

Пример запроса в схеме admin:

curl --request POST \
  --url http://172.19.0.2:8080/graphql \
  --header 'Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d' \
  --header 'schema: admin' \
  --header 'Content-Type: application/json' \
  --data '{"query":"mutation{  token{  add(name:\"App01\", role:\"user\") {  name, token, created_at role }  }  }  "}'

В запросе внешнее приложение авторизуется, используя свой заранее созданный токен, и выпускает (генерирует) новый токен App01. Подробнее о генерации токена приложений через GraphQL API рассказывается в разделе Добавление токена Руководства администратора.

Авторизация коннекторов с использованием токена приложений¶

Приложения, использующие для доступа к данным в TDG коннекторы для языков программирования, авторизуются по токенам приложений. Подробнее о настройке таких коннекторов, запросах к данным и вызове сервисов рассказано в главе Использование бинарного протокола iproto.

Чтобы авторизовать коннектор, нужно указать токен приложения непосредственно в вызываемой функции в дополнительном аргументе credentials. Например, запрос на вставку объекта через интерфейс репозитория будет выглядеть следующим образом:

repository.put(type_name, obj, options, context, credentials)

где:

type_name – тип объекта;
object – объект для вставки;
options – параметры для управления запросом;
context – контекст выполнения запроса;
credentials – таблица с данными токена приложения. Единственный обязательный параметр в таблице – это ключ токена.

Пример авторизации с использованием токена приложений на языке Python:

from tarantool.connection import Connection
conn = Connection(server.host, server.binary_port, user='tdg_service_user', password='')
admin_token = {'token': '2fc136cf-8cae-4655-a431-7c318967263d'}
obj = {'id': '12567', 'name': 'John'}
conn.call('repository.put', 'Users', obj, {}, {}, admin_token)

Запрос из примера добавит новый объект Users с первичным ключом id, равным 12567, если такой ещё не существует.

Data access requests¶

Глава посвящена запросам данных в TDG. В ней описаны логика и синтаксис запросов, а также представлено несколько сценариев использования.

You will use the already deployed TDG cluster as the environment to run requests.

Preparing a data model
Uploading data
Data access requests

Preparing a data model ¶

Чтобы загрузить данные в TDG, а затем получать к ним доступ через запросы GraphQL, нужно сначала определить модель данных. В этом руководстве используется модель из раздела по настройке модели данных:

Модель данных загружена. Теперь можно добавлять, выбирать и удалять данные.

Uploading data ¶

Загрузить данные в TDG можно с помощью мутации GraphQL:

On the left menu, click the GraphQL tab.
Select default for the desired scheme and clear the request field.
Paste the following request into the left field:

mutation all {
    russia:Country(insert: {
        title: "Russia",
        phone_code: "+7"}) {
    title
    phone_code
    }
    germany:Country(insert: {
        title: "Germany",
        phone_code: "+49"}) {
    title
    }
    moscow:City(insert: {
        title: "Moscow",
        country: "Russia",
        population: 12655050,
        capital: true,
        postcodes: [101000, 119021, 115035, 109028, 109004]}) {
    title
    country
    population
    capital
    postcodes
    }
    spb:City(insert: {
        title: "Saint Petersburg",
        country: "Russia",
        population: 5384342,
        capital: false,
        postcodes: [191193, 191040, 195275, 983002, 983015]}) {
    title
    country
    population
    capital
    postcodes
    }
    tver:City(insert: {
        title: "Tver",
        country: "Russia",
        population: 424969,
        capital: false,
        postcodes: [170006, 170100, 170037, 170028]}) {
    title
    country
    population
    capital
    postcodes
    }
    berlin:City(insert: {
        title: "Berlin",
        country: "Germany",
        population: 3520031,
        capital: true,
        postcodes: [10115, 110117, 10245, 10367]}) {
    title
    country
    population
    capital
    postcodes
    }
    munich:City(insert: {
        title: "Munich",
        country: "Germany",
        population: 1450381,
        capital: false,
        postcodes: [80339, 80336, 80639, 80798]}) {
    title
    country
    population
    capital
    postcodes
    }
    dresden:City(insert: {
        title: "Dresden",
        country: "Germany",
        population: 547172,
        capital: false,
        postcodes: [40210, 40212, 40595, 40627]}) {
    title
    country
    population
    capital
    postcodes
    }
}

Execute the mutation by clicking the Execute Query button:

The data has been uploaded, as you can see by the system response in the right field.

Data access requests ¶

Here are the common use cases for data access requests:

General object type query
Requests by primary index
Requests by secondary index
Requests by compound index
Запросы по мультиключевому индексу
Comparison operators
Multiple conditions
Requests by relations
Пагинация
Requests by version
Выбор экземпляров для выполнения запросов

Примеры запросов GraphQL, приведенные ниже, проще всего запустить через встроенный клиент GraphiQL в веб-интерфейсе TDG. Отправляя запросы на доступ к данным, используйте схему по умолчанию (default):

On the left menu, click the GraphQL tab.
Select default for the desired scheme, clear the request field, and paste the example request code.

General object type query¶

To select objects of a particular type, specify the type’s name and the object fields to return. You don’t have to indicate all the object fields that are defined in the data model. Specify any number of fields you need. For example:

query {
  Country {
    title
  }
}

Ответ – объект JSON, содержащий массив со всеми записями типа Country. Для каждой записи ответ включает только указанные в запросе поля.

{
  "data": {
    "Country": [
      {
        "title": "Russia"
      },
      {
        "title": "Germany"
      }
    ]
  }
}

Requests by primary index¶

A specific object can be selected by primary index:

query {
  Country(title: "Germany") {
    title
    phone_code
  }
}

Requests by secondary index¶

Requests by secondary index have the same syntax:

query {
  City(country: "Russia") {
    title
    country
    population
  }
}

Requests by compound index¶

To perform a request by compound index, specify an array of field values:

query {
  City(primary: ["Saint Petersburg", "Russia"]) {
    title
    country
    population
  }
}

Запросы по мультиключевому индексу¶

Мультиключевой индекс (multikey index) – это индекс по полю, которое содержит массив. Если под условие запроса по мультиключевому индексу подходят несколько элементов массива, будет несколько ключей, указывающих на один и тот же объект. Такой объект вернется несколько раз, и это нужно учитывать при составлении запросов и при обработке полученных результатов.

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

Note

Мультиключевой индекс не может быть первичным.
Мультиключевой индекс не может быть составным.
Мультиключевой индекс невозможно построить по полю, содержащему сложные типы, например, DateTime, Date, Time и Decimal.

For example:

{
  City(postcodes_gt: 983000) {
    title
    postcodes
  }
}

Запрос вернет объект дважды:

{
  "data": {
    "City": [
      {
        "title": "Saint Petersburg",
        "postcodes": [
          191193,
          191040,
          195275,
          983002,
          983015
        ]
      },
      {
        "title": "Saint Petersburg",
        "postcodes": [
          191193,
          191040,
          195275,
          983002,
          983015
        ]
      }
    ]
  }
}

Comparison operators¶

Comparison operators are represented by index name suffixes.

Supported operators:

_gt (Greater Than)
_ge (Greater Than or Equal)
_lt (Less Than)
_le (Less Than or Equal)

For example:

query {
  City(population_ge: 1000000) {
    title
    country
    population
  }
}

При поиске по строковому индексу поддерживаются операторы:

_like – выборка по шаблону;
_ilike – выборка по шаблону без учета регистра.

В шаблонах можно использовать подстановочный символ %.

query {
  City(title_like: "M%") {
    title
    country
  }
}

Multiple conditions¶

В одном запросе можно сочетать несколько условий. Тогда TDG будет искать объекты, удовлетворяющие всем условиям одновременно (логическое И). Указывайте в условиях только индексированные поля.

query {
  City(country: "Russia", population_lt: 1000000) {
    title
    country
    population
  }
}

Requests by relations¶

Чтобы выбрать объекты по отношениям, используйте тот же синтаксис, что и в общем запросе объектов по типу.

В примере модели между объектами Country и City есть связь один ко многим. Поэтому вы можете одним запросом получить данные как о стране, так и о городах.

query {
    Country(title: "Russia") {
        title
        city {
            title
            population
    }
    }
}

Response example:

{
  "data": {
    "Country": [
      {
        "title": "Russia",
        "city": [
          {
            "title": "Moscow",
            "population": 12655050
          },
          {
            "title": "Saint Petersburg",
            "population": 5384342
          },
          {
            "title": "Tver",
            "population": 424969
          }
        ]
      }
    ]
  }
}

Pagination¶

В TDG применяется пагинация на основе курсора. Похожий механизм описан в документации GraphQL.

In general, the request with pagination has the following syntax:

query {
    object_name(first:N, after:$cursor)
    }

where

first определяет максимальное количество возвращаемых элементов (по умолчанию 10).
after передает непрозрачный курсор – строку, определяющую элемент, с которого система TDG должна продолжить выполнение запроса.

Here is the first request with pagination:

query {
    City(first: 2) {
        title
        country
        cursor
    }
}

The response is the following:

{
  "data": {
    "City": [
      {
        "cursor": "gaRzY2FukqZCZXJsaW6nR2VybWFueQ",
        "country": "Germany",
        "title": "Berlin"
      },
      {
        "cursor": "gaRzY2FukqdEcmVzZGVup0dlcm1hbnk",
        "country": "Germany",
        "title": "Dresden"
      }
    ]
  }
}

To get the next data batch, take the cursor field’s value of the last object received and pass it as the after argument to the next request:

query {
    City(first: 2, after: "gaRzY2FukqdEcmVzZGVup0dlcm1hbnk") {
        title
        country
        cursor
    }
}

Then run this logic in a cycle until you get an empty page:

{
  "data": {
    "City": []
  }
}

Pagination for requests with relations works in a similar way:

query {
  Country(title: "Russia") {
    title
    city(first: 2) {
        title
        population
        cursor
    }
  }
}

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

query {
    City(first: -2) {
        title
        country
        cursor
    }
}

Requests by version¶

В TDG реализовано версионирование объектов, поэтому в условие запроса можно включать версии. Подробности вы найдете на этой странице: Версионирование.

Выбор экземпляров для выполнения запросов¶

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

Поддерживаются следующие параметры:

mode – установка целевого экземпляра для выполнения запроса. Тип: string. Значения:
- write – целевым узлом будет мастер;
- read – значение по умолчанию.
prefer_replica – установка реплики в качестве целевого экземпляра для выполнения запроса. Тип: boolean. Значения:
- true – предпочитаемой целью будет одна из реплик. Если доступной реплики нет, то запрос будет выполнен на мастере.
- false (по умолчанию) – запрос будет выполнен на мастер-узле.
Параметр полезен для ресурсозатратных функций, чтобы избежать снижения скорости работы мастер-узлов;
balance – управление балансировкой нагрузки. Тип: boolean. Значения:
- true (по умолчанию) – запросы будут распределяться по всем экземплярам набора реплик по кругу. При этом, если prefer_replica = true, предпочтение отдается репликам.
- false – балансировка отключена.

Чтобы установить эти параметры, используйте в запросе GraphQL-директиву @options:

query {
    City @options(mode: read, balance: true) {
        title
        country
        population
    }
}

Эти параметры также можно определить в некоторых функциях программного интерфейса репозитория. Подробности вы найдете на странице Repository API.

Запросы к данным через REST API¶

В этом разделе описано взаимодействие с хранилищем TDG через REST API. Здесь вы найдёте примеры HTTP-запросов для распространённых сценариев работы с данными. Полное описание REST API TDG приведено в справочнике по REST API.

Подготовка данных
HTTP-адреса REST API
Авторизация
Запросы данных
Вставка данных
Изменение данных
Удаление данных

Подготовка данных ¶

В этом руководстве используется модель из раздела по настройке модели данных:

HTTP-адреса REST API ¶

Для работы с данными через REST API TDG предоставляет HTTP-адреса (endpoints) вида /data/<TypeName> для типов, объявленных в модели данных. Например, http://localhost:8081/data/City.

Авторизация ¶

Для авторизации по REST API используется процедура авторизации HTTP-запроса по токену приложений. Для подробностей обратитесь к разделу Авторизация и отправка HTTP-запросов.

Запросы данных ¶

Для получения данных определённого типа через REST API используются GET-запросы.

Через REST API можно выбирать данные по индексам со условиями поиска:

совпадение;
сравнение: больше, больше или равно, меньше, меньше или равно;
совпадение строки с шаблоном (учётом или без учёта регистра);
условие выбора версий для типов, поддерживающих версионирование.

Условия выбора объектов по индексам передаются в HTTP параметрах запроса вида:

<index_name>=<value> для поиска по полному совпадению;
<index_name>_<condition>=<value> для поиска по условию. Здесь <condition> – постфикс, определяющий оператор сравнения, например, _ge для условия “больше или равно”, like для проверки соответствия строки шаблону.

Полный список доступных параметров приведён в справочнике по REST API.

Рассмотрим реализацию некоторых популярных сценариев доступа к данным через REST API.

Точечный запрос объекта¶

Точечные запросы предполагают получение одного объекта по уникальному индексу. Для выполнения точечного запроса по полному совпадению достаточно выполнить один GET-запрос с параметром <index_name>=<value>, например, title_index=Berlin:

curl http://localhost:8081/data/City?title_index=Berlin

Note

Использование имён индексов, отличных от имён полей, позволяет точно знать, по какому индексу выполняется запрос и оптимизировать работу с данными за счёт этого.

Пакетная обработка¶

В случае выполнения запросов с неизвестным количеством результатов необходимо учитывать пагинацию – постраничную разбивку возвращаемых объектов. По умолчанию размер одной страницы равен 10. Это значит, что ответ на один запрос с условиями будет содержать максимум 10 записей, даже если подходящих объектов больше.

Если вы заранее знаете, сколько объектов хотите получить, вы можете изменить объём страницы с помощью параметра first. Например, получить 25 объектов, подходящих под условие выбора:

curl http://localhost:8081/data/City?population_ge=100000&first=25

Если количество результатов заранее неизвестно, нужно реализовать пакетную обработку (batching) с использованием курсоров. Курсоры позволяют задать начальный объект страницы.

Например, для получения всех объектов типа необходимо выполнять запросы в цикле с указанием параметра after - курсора последнего элемента, полученного в предыдущем запросе. Скрипт для выполнения такого цикла может выглядеть следующим образом:

while true; do
    url="http://127.0.0.1:8181/data/City?first=25"
    if [[ -n "$cursor" ]]; then
        url=$url"&after=$cursor"
    fi
    res=$(curl -s --url $url)
    if [[ $res == "[]" ]]; then break; fi
    len=$(echo $res | jq length)
    echo $len
    cursor=$(echo $res | jq ".[$len - 1].cursor")
done

Порядок возврата результатов¶

Порядок возврата результатов определяется индексом, используемым для выбора объектов, и условием выбора:

“меньше” и “меньше или равно” – по убыванию индекса
“больше” и “больше или равно” – по возрастанию индекса

Если индекс не указан (в запросе нет условий выбора), используется первичный индекс.

Объекты можно запросить в порядке возрастания любого из доступных индексов. Для этого используется параметр indexed_by=<index_name>:

curl http://localhost:8081/data/City?indexed_by=population&first=25

Note

Параметр indexed_by работает только при отсутствии условий выбора объектов. Если в запросе используется другой индекс для выбора объектов, условие indexed_by игнорируется.

Использование составных индексов¶

Если необходима фильтрация объектов по одному полю и сортировка по другому, рекомендуется использовать составной индекс, содержащий оба этих поля.

Пример: есть тип данных с полями типа string и datetime. Например, “событие”: у него есть дата и время (datetime) и идентификатор объекта, с которым произошло событие (string).

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

Для этого нужен составной индекс, включающий оба поля (object_datetime_index). Использовать этот индекс для поиска по полному совпадению не получится, поскольку изначально известен только идентификатор объекта, но не дата. Поэтому нужно выполнять поиск по условию “меньше или равно” с указанием только идентификатора объекта:

curl http://localhost:8081/data/Events?object_datetime_index_le="object_id"

Note

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

В этом случае объекты будут фильтроваться только по идентификатору, без условий выбора даты. Но оператор сравнения “меньше или равно” применяется и к дате, поэтому результаты будут упорядочены по её убыванию.

При этом результат будет содержать лишние объекты с идентификаторами меньше указанного. Такие объекты нужно отсеять, отфильтровав массив полученных результатов в коде приложения.

Вставка данных ¶

Для вставки данных определённого типа через REST API используются POST-запросы.

Тело POST-запроса должно содержать добавляемый объект в формате JSON.

Пример вызова curl для вставки объекта:

curl --request POST \
--url 'http://localhost:8081/data/City' \
--data '{"title": "Stuttgart","population": 623738,"country":"Germany","capital":false}'

В результате такого запроса возвращается вставленный объект в формате JSON. Для ускорения работы можно добавить параметр skip_result=true: в этом случае тело ответа будет пустым.

curl --request POST \
--url 'http://localhost:8081/data/City?skip_result=true' \
--data '{"title": "Stuttgart","population": 623738,"country":"Germany","capital":false}'

Изменение данных ¶

Для модификации данных определённого типа через REST API используются PUT-запросы.

В запросах на модификацию данных используются те же параметры для поиска объектов по индексу, что и в запросах на чтение: <index_name>, <index_name>_ge, <index_name>_lt и так далее.

Для изменения объекта выполните PUT-запрос с параметром <index_name>=<value>, однозначно идентифицирущим объект. Например, title=Berlin:

В теле запроса должны содержаться новые значения изменяемых полей объектов в формате JSON.

curl --request PUT \
--url 'http://localhost:8081/data/City?title=Berlin' \
--data '{"population": 3520032}'

Параметр skip_result (пустой ответ) также может применяться в запросах на изменение данных:

curl --request PUT \
--url 'http://localhost:8081/data/City?title=Berlin&skip_result=true' \
--data '{"population": 3520032}'

Удаление данных ¶

Для удаления данных определённого типа через REST API используются DELETE-запросы.

Для удаления объекта выполните DELETE-запрос с параметром <index_name>=<value>, однозначно идентифицирущим объект. Например, title=Berlin:

curl --request DELETE \
--url 'http://localhost:8081/data/City?title=Berlin'

Массовое удаление¶

Для массового удаления объектов можно использовать точечные DELETE-запросы с прохождением по списку объектов, например, полученному с помощью GET-запроса.

Однако, лучшим решением будет реализация массового удаления с помощью сервис-функций. Этот способ позволяет реализовать удаление с учётом особенностей схемы данных и в общем случае имеет лучшую производительность.

Разработка бизнес-логики¶

В этой главе описывается реализация бизнес-логики в TDG.

Бизнес-логика реализуется в TDG с помощью пользовательского кода на Lua – скриптовом языке, который нативно поддерживается в Tarantool. Единица бизнес-логики – исполняемая Lua-функция, загруженная в TDG – является аналогом хранимой процедуры в СУБД.

TDG расширяет возможности Tarantool по работе с пользовательским кодом, упрощая разработку бизнес-логики. В частности, доступны следующие возможности:

загрузка пользовательского кода как части конфигурации TDG;
исполнение пользовательского кода на узлах TDG с ролью Runner – отдельно от хранилища данных.
автоматическая генерация API для вызова пользовательских функций извне;
автоматическая обработка входящих и исходящих данных с помощью input- и output-процессоров;
выполнение задач по расписанию.
собственные Lua-модули для работы с хранилищем TDG, доступа к базам данных (ODBC), работы с JSON и другие;

Lua-код, реализующий бизнес-логику решения TDG, можно разделить на следующие виды:

Сервис-функции (services) предназначены для вызова внешними системами или пользователями через API: GraphQL, REST API или iproto.
Процессоры входящих и исходящих данных (input processor и output processor) автоматически выполняют пользовательский код при поступлении нового объекта через выбранный коннектор или отправке в него.
Задачи (tasks) вызываются изнутри TDG вручную, либо автоматически с заданным интервалом, либо по расписанию.

Подробнее о возможностях реализации бизнес-логики рассказывается на страницах этого раздела.

Сервис-функции¶

Сервис-функции (services) – это хранимые процедуры, реализующие бизнес-логику решения и доступные для вызова извне. В TDG такие процедуры представляют собой функции на языке Lua.

Чтобы добавить в TDG вызываемый сервис, нужно:

Задать конфигурацию сервиса в формате YAML: его имя, аргументы вызова, возвращаемое значение.
Реализовать необходимую логику на языке Lua с использованием Lua API TDG.
Загрузить файлы с исходным кодом и конфигурацией сервиса в TDG.

После этого TDG автоматически сгенерирует API для вызова сервиса через GraphQL, REST API и iproto (бинарный протокол Tarantool).

В этом руководстве рассмотрим пример создания нового сервиса в TDG и способы его вызова.

Для выполнения примера требуются:

настроенный кластер TDG;
модель данных, сохраненная в файле model.avsc. В примере используется модель из раздела по настройке модели данных;
HTTP-клиент, например, curl.

Пример сервиса будет возвращать список всех городов страны, загруженных в хранилище, по её имени.

Руководство включает в себя следующие шаги:

Подготовка конфигурации сервиса
Реализация логики на Lua
Загрузка сервиса
Вызов сервиса

Подготовка конфигурации сервиса ¶

Чтобы добавить в TDG сервис, необходимо добавить соответствующую секцию в конфигурацию TDG. Сервисы можно описывать либо в общем конфигурационном файле (секция services в файле config.yml), либо в отдельном файле services.yml.

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

Пример минимальной конфигурации сервиса без аргументов:

# config.yml

services:
  hello_world:
    doc: "Hello World script"
    function: hello.hello
    return_type: string

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

# config.yml

services:
  get_cities:
    doc: "Get cities by country name"
    function: cities.get_cities
    return_type: {"type":"array", "items":"City"}
    args:
      country: string

types:
   __file: model.avsc

Эта конфигурация задаёт следующее поведение:

Сервис будет доступен для вызова через GraphQL по имени get_cities и через REST API по адресу http://localhost:8081/service/get_cities;
При вызове будет выполняться функция get_cities из файла cities.lua;
Сервис будет возвращать массив объектов пользовательского типа City;
Сервис будет принимать один строковый аргумент – название страны.

Реализация логики на Lua ¶

Как указано в конфигурации сервиса, его код должен храниться в файле cities.lua в функции get_cities. Этот файл может выглядеть следующим образом:

-- cities.lua

local repository = require('repository')
local log = require('log')
local json = require('json')

function get_cities(arg)
  log.info('Getting cities of: %s', json.encode(arg))
  local result = repository.find("City", {{'country', '==', arg["country"]}})
  return result
end

return {
    get_cities = get_cities
}

Использование аргументов сервиса¶

Все аргументы сервиса передаются в первый аргумент функции в виде Lua-таблицы. Ключами в этой таблице являются имена аргументов, объявленные в конфигурации сервиса. Таким образом, для обращения к конкретному аргументу необходимо получить элемент таблицы по имени из конфигурации сервиса, например, arg["country"].

Использование модулей¶

TDG предоставляет набор Lua-модулей для реализации бизнес-логики. Набор включает как модули для работы с хранилищем Tarantool и подсистемами TDG, так и модули для работы с распространёнными технологиями, такими как различные СУБД или JSON.

В этом примере используются модули:

repository – интерфейс репозитория TDG. Содержит функции для работы с данными в хранилище Tarantool. В примере используется repository.find для поиска подходящих объектов типа City.
log – запись в журнал TDG. В примере используется log.info для записи в журнал информации о вызовах сервиса.
json – работа с JSON. В примере используется json.encode для формирования строкового JSON представления переданного аргумента.

Загрузка сервиса ¶

Чтобы выполнить пример, нужно загрузить архив с моделью данных, файлом конфигурации и функцией сервиса в TDG:

Поместите Lua-файл с кодом сервиса в папку src.
Упакуйте в zip-архив:
- папку src, внутри которой лежит файл с кодом сервиса;
- модель данных model.avsc;
- файл конфигурации config.yml.
Загрузите архив в TDG согласно инструкции.

Вызов сервиса ¶

GraphQL¶

Чтобы вызвать сервис через GraphQL, укажите в запросе имя сервиса и аргументы в формате name:value:

query {
  get_cities(country: "Germany")
}

Как и в случае запросов к данным, GraphQL позволяет получать отдельные поля возвращаемых объектов:

query {
  get_cities(country: "Germany") {
    title,
    capital
  }
}

Ответ:

{
  "data": {
    "get_cities": [
      {
        "title": "Berlin",
        "capital": true
      },
      {
        "title": "Dresden",
        "capital": false
      },
      {
        "title": "Munich",
        "capital": false
      }
    ]
  }
}

REST API¶

Сервисы доступны для вызова через REST API на HTTP-адресах (endpoint) вида /service/<service_name>. Для вызова сервисов используются POST-запросы.

Для вызова сервиса без аргументов отправьте POST-запрос на соответствующий адрес, например:

curl -X POST http://localhost:8081/service/hello_world

Если у сервиса есть аргументы, передайте их одним из двух способов:

в параметрах запроса с соответствующими именами:
```
curl -X POST http://localhost:8081/service/get_cities?country=Russia
```

в теле запроса в формате JSON:

curl -d '{"country":"Russia"}' -H "Content-Type: application/json" \
-X POST http://localhost:8081/service/get_cities

Ответ:

{
  "result": [
    {
      "cursor": "gaRzY2FukqZSdXNzaWGmTW9zY293",
      "country": "Russia",
      "title": "Moscow",
      "population": 12655050,
      "postcodes": [
        101000,
        119021,
        115035,
        109028,
        109004
      ],
      "capital": true
    },
    {
      "cursor": "gaRzY2FukqZSdXNzaWGwU2FpbnQgUGV0ZXJzYnVyZw",
      "country": "Russia",
      "title": "Saint Petersburg",
      "population": 5384342,
      "postcodes": [
        191193,
        191040,
        195275,
        983002,
        983015
      ],
      "capital": false
    },
    {
      "cursor": "gaRzY2FukqZSdXNzaWGkVHZlcg",
      "country": "Russia",
      "title": "Tver",
      "population": 424969,
      "postcodes": [
        170006,
        170100,
        170037,
        170028
      ],
      "capital": false
    }
  ]
}

Полная информация о REST API сервисов TDG приведена в справочнике по REST API.

Процессоры входящих и исходящих данных¶

Процессор (processor) – это подсистема, которая задает в TDG логику обработки объектов и автоматически выполняет пользовательский код при поступлении нового объекта или при его отправке через заданный коннектор. Для исполнения пользовательского кода используются обработчики.

Обработчик (handler) – это пользовательская функция, которая вызывается процессором и обрабатывает входящие или исходящие данные. В TDG такие функции представляют собой функции на языке Lua.

Существует два вида процессоров, оба они выполняются на экземплярах TDG с ролью runner:

input-процессор (input processor) – процессор входящих данных. Этот процессор обрабатывает объект, поступивший на вход через коннектор, настраивает для него маршрутизацию и правила хранения полученных объектов.
output-процессор (output processor) – процессор исходящих данных. Этот процессор готовит объект к отправке во внешнюю систему и передает его в коннектор.

В этом руководстве рассмотрим пример создания input-процессора и обработчика в TDG. В примере на HTTP-коннектор придет новый объект в формате JSON, который после преобразования в Lua-объект будет обработан input-процессором, а затем сохранен в хранилище – на экземплярах с ролью storage.

Для выполнения примера требуются:

настроенный кластер TDG;
модель данных, сохраненная в файле model.avsc. В примере используется модель данных из руководства Hello world на Lua.

Руководство включает в себя следующие шаги:

Конфигурация коннектора
Конфигурация input-процессора
Реализация обработчика
Загрузка конфигурации
Добавление объекта через input-процессор

Конфигурация коннектора ¶

Указать конфигурацию входящего коннектора можно:

в общем конфигурационном файле (секция connector в файле config.yml);
в отдельном файле connector.yml.

Задайте конфигурацию входящего HTTP-коннектора:

# config.yml

connector:
  input:
    - name: http
      type: http
      routing_key: input_key

При получении нового объекта в формате JSON через HTTP-коннектор:

JSON-объект преобразовывается в Lua-таблицу (объект Lua).
Для объекта генерируется UUID, по которому можно проследить дальнейший путь объекта (например, найти его в ремонтной очереди).
Объектам, пришедшим на коннектор, присваивается определенный ключ маршрутизации (секция routing_key в конфигурации коннектора).

Ключ маршрутизации – это строковый ключ, который задается объекту и определяет для него процесс дальнейшей обработки. На коннекторе такой ключ определяет, в какой обработчик на input-процессоре будет передан объект. Если ключ маршрутизации не задан, объект обрабатывается функцией по умолчанию, которая превращает объект вида { "obj_type": { "field_1": 1 } } в объект вида { "field_1": 1 } и задает значение ключа маршрутизации как routing_key = obj_type. После получения ключа маршрутизации объект передается на input-процессор.

Выше в конфигурации определены имя коннектора http, его тип http и ключ маршрутизации input_key, с которым объект отправится в обработчик, заданный в файле конфигурации в секции input_processor.

Подробная информация о параметрах конфигурации коннектора приведена в справочнике по конфигурации бизнес-логики.

Конфигурация input-процессора ¶

Чтобы задать процессор для входящих данных в TDG, необходимо добавить соответствующую секцию в конфигурацию TDG. Input-процессор можно описывать:

в общем конфигурационном файле (секция input processor в файле config.yml);
в отдельном файле input_processor.yml.

Конфигурация input-процессора включает такие параметры, как вызываемый обработчик, ключ маршрутизации и система, куда следует направить объект. Полная информация о параметрах конфигурации input-процессора приведена в справочнике по конфигурации бизнес-логики.

Задайте конфигурацию процессора для входящих данных:

# config.yml

input_processor:
  handlers:
    - key: input_key
      function: handle_band.newband
  storage:
    - key: band
      type: MusicBand

Здесь в секции handlers задан ключ маршрутизации input_key. Объекты с таким ключом, пришедшие из HTTP-коннектора на input-процессор, передаются в функцию newband из модуля handle_band.

Кроме того, в секции storage в параметре key задается еще один ключ маршрутизации band. После настройки такого ключа маршрутизации:

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

Объекты, которым в обработчике handle_band.newband был присвоен ключ band, будут провалидированы по этому ключу в соответствии с моделью данных, преобразованы в тип MusicBand и сохранены на экземплярах с ролью storage.

Note

Если при обработке объекта input-процессором возникает ошибка, объект отправляется в ремонтную очередь. Информация об объектах в ремонтной очереди с описанием ошибок доступна администратору в веб-интерфейсе TDG на вкладке Repair Queues.

После задания всех необходимых настроек общий файл конфигурации будет выглядеть следующим образом:

# config.yml

types:
  __file: model.avsc

connector:
  input:
    - name: http
      type: http
      routing_key: input_key

input_processor:
  handlers:
    - key: input_key
      function: handle_band.newband
  storage:
    - key: band
      type: MusicBand

Реализация обработчика ¶

Как указано в конфигурации процессора, код обработчика должен храниться в файле handle_band.lua. Создайте обработчик с функцией newband(obj), которая принимает на вход новый Lua-объект с музыкальной группой:

-- handle_band.lua

local log = require('log')
local json = require('json')

log.info('Starting handle_band.lua')
function newband(obj)
    log.info('Received new object from the HTTP connector: %s', json.encode(obj))
    obj.routing_key = "band"
    log.info('The routing key is set to "%s" value', obj.routing_key)
    return obj
end

return {
    newband = newband
}

Здесь функция newband(obj) выводит информацию об объекте obj, пришедшем из HTTP-коннектора, в логах TDG в формате JSON. После этого функция присваивает объекту новый ключ маршрутизации band, а затем возвращает этот объект.

Загрузка конфигурации ¶

Чтобы выполнить пример, нужно загрузить архив с файлом конфигурации, моделью данных и функциями обработчиков в TDG. Для этого:

Поместите Lua-файл с кодом обработчика в папку src.
Упакуйте в zip-архив:
- папку src, внутри которой лежит файл с кодом обработчика handle_band.lua;
- модель данных model.avsc;
- файл конфигурации config.yml.
Загрузите архив в TDG согласно инструкции.

Добавление объекта через input-процессор ¶

Чтобы проверить добавленную конфигурацию, добавьте новую музыкальную группу в TDG через HTTP-коннектор. Для этого переключитесь на вкладку Test и выберите для запроса формат JSON.

Введите в поле запрос в формате JSON и затем нажмите Submit:

{
  "name":"Beatles",
  "genre":["Rock-n-roll"],
  "wasformed": 1965
}

При успешном добавлении объекта в поле Response вернется ответ “OK”.

Проверить добавленные данные можно на вкладке Graphql. Убедитесь, что выбрана схема default, и напишите запрос на выборку всех музыкальных групп:

query {
  MusicBand {
    name
    wasformed
    genre
  }
}

Так как добавлена всего одна группа, ответ будет выглядеть следующим образом:

{
  "data": {
    "MusicBand": [
      {
        "genre": [
          "Rock-n-roll"
        ],
        "name": "Beatles",
        "wasformed": 1965
      }
    ]
  }
}

Также информацию о добавленном объекте можно проверить в логах TDG. В логах TDG видно, что сначала HTTP-коннектор получил на вход новый объект, а затем был запущен обработчик handle_band.lua.

Задачи¶

Задачи (tasks) – это загруженные в TDG пользовательские функции, которые исполняются автоматически (в том числе по расписанию) или вызываются вручную изнутри TDG.

Задачи используются для реализации внутренней бизнес-логики решения. Примеры: построение регулярных отчётов или инвалидация кэшей. Для реализации логики, доступной для вызова извне, используется механизм сервис-функций.

Технически, задачи реализуются в виде функций на языке Lua. Возвращаемое значение функции является результатом выполнения соответствующей задачи.

Существует три вида задач:

единоразовые (single-shot) – выполняются один раз после каждого вызова вручную из интерфейса TDG.
непрерывно выполняемые (continuous) – выполняются циклически с заданным интервалом времени. Например, если TDG используется как кэш горячих данных, такая задача может автоматически обновлять этот кэш на основе изменений в данных раз в несколько минут.
по расписанию (periodical) – выполняются по расписанию, заданному в расширенном формате cron с добавлением секунд; подробнее в справочнике по конфигурации бизнес-логики. Например, в конце каждого дня можно строить отчёты по хранимым в кластере данным.

В этом руководстве рассмотрим пример создания задач в TDG и инструменты управления задачами.

Для выполнения примера требуется настроенный кластер TDG.

Руководство включает в себя следующие шаги:

Конфигурация задач
Реализация задач на Lua
Загрузка задач
Управление задачами

Конфигурация задач ¶

Чтобы добавить в TDG задачу, необходимо добавить соответствующую секцию в конфигурацию TDG. Задачи можно описывать либо в общем конфигурационном файле (секция tasks в файле config.yml), либо в отдельном файле tasks.yml.

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

Пример конфигурации трёх задач разных видов:

# config.yml

tasks:
  report_now:
    kind: single_shot
    function: tasks.build_report
  update_caches:
    kind: continuous
    function: tasks.update_caches
    pause_sec: 3600
  weekly_report:
    kind: periodical
    function: tasks.build_report
    schedule: "0 0 19 * * 5"

Здесь:

report_now – единоразовая задача. Вызывается вручную.
update_caches – задача, которая выполняется автоматически с периодом в 1 час (3600 секунд).
weekly_report – задача, которая исполняется по расписанию каждую пятницу в 19:00:00. Использует ту же функцию, что и задача report_now.

Если вызываемая функция имеет аргументы, их значения можно передать в параметре args:

# config.yml

tasks:
  task_with_args:
    kind: single_shot
    function: tasks.function_with_args
    args: [1, "hello"]

Если в TDG включен режим обязательной аутентификации, необходимо добавить параметр run_as для указания пользователя, от имени которого будут выполняться задачи по расписанию и периодические задачи:

# config.yml

  update_caches:
    kind: continuous
    function: tasks.update_caches
    pause_sec: 3600
    run_as:
      user: username
  weekly_report:
    kind: periodical
    function: tasks.build_report
    schedule: "0 0 19 * * 5"
    run_as:
      user: username

Реализация задач на Lua ¶

Как указано в конфигурации задач, соответствующие им функции должны храниться в файле tasks.lua.

Для упрощения демонстрации реализуем функции-заглушки:

-- tasks.lua

local function build_report()
    return 'Report is ready'
end

local function update_caches()
    return 'Caches updated'
end

return {
    build_report = build_report
    update_caches = update_caches
}

Загрузка задач ¶

Чтобы выполнить пример, нужно загрузить архив с файлом конфигурации и функциями задач в TDG. Для этого:

Поместите Lua-файл с кодом задач в папку src.
Упакуйте в zip-архив:
- папку src, внутри которой лежит файл с кодом задач;
- файл конфигурации config.yml.
Загрузите архив в TDG согласно инструкции.

Управление задачами ¶

Инструменты для управления задачами и отслеживания их выполнения расположены на вкладке Tasks веб-интерфейса TDG. Полная информация об управлении задачами через веб-интерфейс приведена в разделе Задачи руководства администратора.

Взаимодействие с Kafka¶

Протокол Kafka – один из доступных форматов для запросов к данным в TDG. Формат позволяет как читать данные с сервера (брокера), а затем обрабатывать их, так и отправлять данные во внешние системы. В терминологии Kafka TDG при работе с запросами можно настроить как в качестве consumer (получение объектов), так и в качестве producer (отправка объектов). Для взаимодействия с шиной данных Apache Kafka в TDG используется коннектор типа Kafka.

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

Запросы к данным через Kafka-коннектор – пример настройки и работы с коннектором Kafka;
Cправочник по настройке коннектора – полное описание параметров конфигурации для коннектора Kafka;
Метрики – метрики для мониторинга работы коннектора Kafka;
Решение проблем – часто возникающие ошибки при работе с Kafka и способы их устранения.

Запросы к данным через Kafka-коннектор¶

В руководстве пошагово демонстрируется пример работы TDG c Kafka – от настройки коннектора до выполнения обмена данными. Пример реализует следующую логику:

получение объекта из топика (topic) Kafka;
изменение обработчиком объекта, полученного в TDG;
сохранение измененного объекта в хранилище;
отправка измененного объекта в тот же топик.

Для выполнения примера требуются:

настроенный кластер TDG;
модель данных, сохраненная в файле model.avsc. В примере используется модель из раздела по настройке модели данных;
установленные Python и pip;
установленный и запущенный с помощью ZooKeeper сервер Kafka.

Руководство включает в себя следующие шаги:

Настройка коннектора
Реализация обработчиков
Загрузка конфигурации
Запуск и настройка Kafka
Запуск обработки объектов

Настройка коннектора ¶

Коннектор в TDG можно настроить двумя способами:

указать параметры коннектора в файле конфигурации .yml;
добавить или изменить коннектор, используя веб-интерфейс (только для input-коннекторов). Чтобы узнать больше, обратитесь к разделу Вкладка Connectors.

Зададим настройки первым способом, в файле .yml.

Создайте файл конфигурации config.yml со следующими настройками:

types:
  __file: model.avsc

connector:
  input:
    - name: from_kafka
      type: kafka
      brokers:
        - localhost:9092
      topics:
        - cities
      group_id: kafka
      routing_key: add_kafka

  output:
    - name: to_kafka
      type: kafka
      brokers:
        - localhost:9092
      topic: cities

input_processor:
  handlers:
    - key: add_kafka
      function: kafka_input_handler.call
  storage:
     - key: input_key
       type: City

output_processor:
  input_key:
    handlers:
      - function: kafka_output_handler.call
        outputs:
          - to_kafka

В файле указываются:

используемая модель данных;
секция connector – настройки input- и output-коннекторов. Разделу input соответствует функция consumer, разделу output – функция producer. Настройки включают в себя имя коннектора, адрес сервера (брокера), а также название топика (cities), к которому будет обращаться TDG. В разделе input также определен ключ маршрутизации routing_key со значением add_kafka;
секция input_processor – обработка входящих данных. Здесь заданы ключ для хранилища (input_key), в котором будет сохранен объект City, а также определен обработчик (kafka_input_handler) для ключа маршрутизации add_kafka. Узнать больше про настройку input_processor можно в соответствующем разделе справочника;
секция output_processor – обработка исходящих данных. Здесь определены имя хранилища (input_key) и функция-обработчик (kafka_output_handler). Кроме того, задан параметр outputs (to_kafka) – это означает, что объект будет отправлен обратно в топик Kafka. Узнать больше про настройку output_processor можно в соответствующем разделе справочника.

Чтобы ознакомиться со всеми доступными параметрами конфигурации для коннектора Kafka, обратитесь к справочнику по настройке коннектора.

Реализация обработчиков ¶

Обработка входящих данных¶

Данные в формате JSON, приходящие из Kafka, попадают в обработчики (handlers), заданные в файле конфигурации в секции input_processor.

В функции обработчика можно модифицировать поступившую информации, а также обернуть данные в JSON с ключом routing_key для дальнейшей обработки.

В файле kafka_input_handler.lua укажите функцию, которая будет запускаться в input-процессоре. Функция увеличит значение population и задаст ключу routing_key значение input_key:

#!/usr/bin/env tarantool

return {
    call = function(params)
        params.obj.population = params.obj.population + 1
        params.routing_key = "input_key"
        return params
    end
}

Обработка исходящих данных¶

В разделе output указывается, как объект будет изменен в обработчике перед отправкой во внешние системы. Обработка выполняется после успешного сохранения объектов на экземплярах с ролью storage.

Чтобы обработать объект в output_processor, в файле конфигурации укажите название хранилища (input_key), в котором был сохранен объект, а затем определите обработчик для него (секция handlers).

Создайте файл kafka_output_handler.lua. В нем будет записана функция, вызываемая output-обработчиком. Функция вернет объект City:

#!/usr/bin/env tarantool

return {
    call = function(params)
        return {obj = params.obj}
    end
}

Загрузка конфигурации ¶

Чтобы выполнить пример, нужно загрузить архив с моделью данных, файлом конфигурации и функциями обработчиков (handlers) в TDG:

Поместите файлы со скриптами обработчиков (kafka_input_handler.lua и kafka_output_handler.lua) в папку src.
Упакуйте в zip-архив:
- папку src, внутри которой лежат файлы со скриптами обработчиков;
- модель данных model.avsc;
- файл конфигурации config.yml.
Загрузите архив в TDG согласно инструкции.

Запуск и настройка Kafka ¶

На сервере (брокере) Kafka создайте новый топик с именем cities. Для демонстрации работы примера и просмотра переданных в топик сообщений напишем простой скрипт на языке Python. Скрипт сыграет роль consumer Kafka, который получает сообщения из топика cities на брокере localhost:9092.

Чтобы работать с Kafka средствами Python, установите модуль kafka-python:

pip install kafka-python

Для запуска чтения сообщений, приходящих из топика cities, подготовьте следующий скрипт на языке Python:

from kafka import KafkaConsumer
consumer = KafkaConsumer('cities')
for message in consumer:
    print (message)

Чтобы выполнить скрипт, используйте интерактивный режим интерпретатора или сохраните функцию в файл consumer.py, а затем запустите ее командой python consumer.py.

Оставьте работать запущенный consumer.py, а затем переключитесь на новую вкладку консоли.

Запуск обработки объектов ¶

Чтобы запустить отправку сообщений, отправьте в Kafka JSON-объект типа City с полем population. Для этого подготовьте следующий скрипт на языке Python:

from kafka import KafkaProducer
producer = KafkaProducer(bootstrap_servers='localhost:9092')
headers = [("Header Key", b"Header Value")]
producer.send('cities', value='{"title": "Moscow", "population": 12655050}'.encode('ascii'), headers=headers)
producer.flush()

Скрипт содержит подключение к Kafka в качестве producer и отправку простого JSON-объекта: {"title": "Moscow", "population": 12655050}.

Чтобы выполнить скрипт, используйте интерактивный режим интерпретатора или сохраните функцию в файл producer.py, а затем запустите ее командой python producer.py.

В результате TDG получит объект City из топика cities, обработает его (увеличится значение поля population) и сохранит, а затем отправит объект в тот же топик Kafka. Это вызовет повторное получение, обработку и отправку. Пока пример запущен, во вкладке терминала consumer будут появляться все новые сообщения с постоянно возрастающим значением поля population.

Чтобы остановить обработку объектов, выполните одно из действий ниже:

Выключите Kafka или TDG.
Загрузите в TDG новую конфигурацию.

Решение проблем при работе с Kafka¶

При использовании Kafka проблемы могут возникнуть как на этапе подключения к брокеру, так и во время работы с данными. В статье рассматриваются распространенные ошибки и приводятся способы их устранения.

Чтобы облегчить решение возникших проблем

используйте приложение Offset Explorer и логи TDG;
попробуйте воспроизвести ошибки в тестовом режиме.

Обратитесь к разделу Инструменты для проверки ошибок, чтобы узнать больше.

Статья включает в себя следующие ошибки:

Проблема	Пример сообщения об ошибке
Неверно указан брокер	`Failed to resolve 'kafka-broker:9091': Name or service not known`
Неизвестный топик или раздел	`kafka_error: consumer "kafka": Broker: Unknown topic or partition`
Неверно заданы SSL-сертификаты	`ip:port/bootstrap: Disconnected while requesting ApiVersion: might be caused by incorrect security.protocol configuration (connecting to a SSL listener?) or broker version is < 0.10 (see api.version.request)`

Инструменты для проверки ошибок¶

Offset Explorer¶

Перед началом работы установите приложение Kafka Offset Explorer. В приложении можно просматривать данные кластеров – топики, брокеры, объекты и сообщения в топиках. Offset Explorer позволяет проверить соединение с кластером Apache Kafka, так что при подозрении на ошибку попробуйте подключиться к Kafka с его помощью. Если подключиться не удается, убедитесь, что конфигурация Kafka корректна.

Установив приложение, следуйте инструкции по подключению к Kafka. При добавлении кластера в Offset Explorer не забудьте заполнить поле Bootstrap servers во вкладке Advanced. Подключиться без этой настройки будет невозможно. В поле Bootstrap servers укажите номер порта, который используется для соединения. Данные для подключения должны соответствовать подключению в сервисе.

Логи TDG¶

При проверке конфигурации Kafka также могут быть полезны логи TDG. При подключении к Kafka в логах TDG выводятся:

input-параметры, с которыми был создан consumer Kafka;
output-параметры, с которыми был создан producer Kafka.

В логах указаны значения для всех опций библиотеки librdkafka, в том числе выставленные по умолчанию. Отключить вывод логов нельзя.

Пример вывода для consumer:

tdg2                | 2023-03-02 16:17:19.810 [1] main/304/main I> [dcb31ae4-ca99-4b1c-995f-a0dd05194fa9] Kafka consumer for "kafka" input configuration: ---
tdg2                | ssl.engine.id: dynamic
tdg2                | socket.blocking.max.ms: '1000'
tdg2                | message.max.bytes: '1000000'
tdg2                | connections.max.idle.ms: '0'
tdg2                | enable_sasl_queue: 'false'
tdg2                | batch.size: '1000000'
...

Воспроизведение ошибок¶

Если вы хотите воспроизвести в тестовом режиме ошибки из статьи, обратитесь к репозиторию с примером настройки подключения к Kafka. В примере с помощью Docker Compose развернуты три контейнера, которые нужны для минимальной настройки:

TDG;
Zookeeper;
брокер (сервер) Kafka.

Чтобы развернуть контейнеры и воспроизвести ошибки, скачайте пример и после распаковки архива следуйте инструкции из файла 6_Quickstart_guide_TDG.md.

Возможные ошибки¶

Неверно указан брокер¶

Пример вывода

Failed to resolve 'kafka-broker:9091': Name or service not known

Возможные причины

В файле конфигурации config.yml неверно указаны номер порта для брокера Kafka или название Docker-контейнера.

Решение

Проверьте адрес брокера (параметр brokers) в секции connector в файле конфигурации config.yml. Сравните это значение с параметрами брокера Kafka. Например, если брокер Kafka запущен с помощью Docker Compose, проверьте параметры брокера ports и container_name в файле конфигурации Docker-контейнеров (docker-compose.yml).

Неизвестный топик или раздел¶

Пример вывода

kafka_error: consumer "kafka": Broker: Unknown topic or partition

Возможные причины

Запрос на запись был отправлен в несуществующий топик или раздел. Ошибка возникает, если на момент отправки данных на брокер указанный топик еще не был создан, и в Kafka отключено автоматическое создание топиков.

Решение

Убедитесь, что указанный топик существует. Если топика еще не существует, попробуйте создать его в Offset Explorer. Если при создании топика возникли проблемы, обратитесь к администратору Kafka.
Проверьте, что в настройках Kafka разрешено автоматическое создание топиков при отправке данных – по умолчанию такое поведение отключено. Если создание топиков разрешено, в Offset Explorer новый топик появится после обновления в папке Topics. При этом данные о новой записи не будут потеряны – запись будет добавлена в топик. При последующей отправке данных в этот топик ошибка возникать не будет.

Неверно заданы SSL-сертификаты¶

Пример вывода

ip:port/bootstrap: Disconnected while requesting ApiVersion: might be caused by incorrect security.protocol configuration (connecting to a SSL listener?) or broker version is < 0.10 (see api.version.request) (after 2ms in state APIVERSION_QUERY, 3 identical error(s) suppressed)

Возможные причины

Сертификат SSL настроен некорректно.
Версия брокера Kafka ниже 0.10.

Решение

Если соединение недоступно, запустите приложение Offset Explorer и попытайтесь подключиться к Kafka. Если подключиться с помощью Offset Explorer не удалось, проверьте, что параметры брокера Kafka настроены корректно.
Проверьте значение параметра security.protocol в секции коннектора input (раздел options) в файле конфигурации config.yml.

Использование бинарного протокола iproto¶

TDG поддерживает работу с хранилищем данных и пользовательскими сервисами через бинарный протокол Tarantool (iproto). В частности, бинарный протокол используется коннекторами к Tarantool из разных языков программирования, таких как Python, Java, Go и другие. Полный список доступных коннекторов и примеры их использования приведены в документации Tarantool.

Бинарный протокол Tarantool обеспечивает лучшее быстродействие по сравнению с HTTP и таким образом позволяет наиболее эффективно создавать промежуточные слои бизнес-логики перед TDG. При этом выбор языка для реализации этой логики предоставляется разработчику.

В этом руководстве демонстрируется работа с данными и сервисами TDG через бинарный протокол Tarantool. Руководство включает следующие шаги:

Настройка коннектора
Подключение
Запросы GraphQL
Использование интерфейса репозитория
Вызов сервисов

В примерах используется:

модель данных из раздела по настройке модели данных;
сервисы из руководства по созданию сервис-функций.

Для вызовов используется язык Python и коннектор tarantool-python. Чтобы узнать, как делать аналогичные вызовы из других языков, обратитесь к документации соответствующего коннектора.

Настройка коннектора¶

Для возможности подключения к TDG через бинарный протокол используется коннектор типа tarantool_protocol. Настроить коннектор можно двумя способами:

Через веб-интерфейс на вкладке Connectors;
В YAML-конфигурации TDG в блоке connectors.

Пример YAML-конфигурации входящего коннектора iproto:

input:
- routing_key: null
  type: tarantool_protocol
  is_async: true
  name: iproto

Подробнее о параметрах коннектора рассказывается в справочнике по настройке коннекторов.

Подключение¶

Клиенты, которые подключаются к TDG через бинарный протокол, используют подключение напрямую к экземпляру Tarantool, имеющему кластерную роль connector. В связи с этим для подключения используется учетная запись пользователя Tarantool.

Important

Здесь используются пользователи, созданные в самом Tarantool, а не пользователи TDG. Подробнее об управлении пользователями Tarantool рассказывается в документации по контролю доступа в Tarantool.

Пример подключения через Python-коннектор:

from tarantool.connection import Connection

conn = Connection(server.host, server.binary_port, user='tdg_service_user', password='')

По умолчанию для подключения доступны пользователи:

tdg_service_user с пустым паролем;
admin c паролем, совпадающим с cluster cookie.

При необходимости вы можете добавить других пользователей Tarantool c нужными привилегиями. Инструкции по управлению пользователями в Tarantool приведены в документации по контролю доступа в Tarantool.

После того, как подключение установлено, TDG проверяет права клиента на выполнение каждого входящего вызова с помощью токенов приложений. Токен передается непосредственно в вызовах функций через iproto-соединение в аргументе credentials. Пример:

conn.call('repository.put', 'Users', obj, {}, {}, {'token': token})

Подробнее об использовании токенов приложений рассказывается в главе Авторизация.

Запросы GraphQL¶

Для отправки запросов GraphQL через бинарный протокол используется функция execute_graphql. Её основные аргументы:

query – строка, содержащая GraphQL-запрос;
variables – значения переменных, если они используются в запросе;
schema – схема данных: default (пользовательские данные) или admin.

Пример отправки GraphQL-запроса через бинарный протокол без переменных:

resp, _ = conn.call('execute_graphql', {
    "query": '''
           query {
               Country {
                   title
               }
           }
       ''',
    "schema": "default",
})

Пример отправки GraphQL-запроса через бинарный протокол с переменными:

resp, _ = conn.call('execute_graphql', {
    "query": '''
        query ($title: String!)  {
            Country(title: $title) {
                title,
                phone_code
            }
        }
    ''',
    "variables": {
        "title": "Russia"
    },
    "schema": "default",
})

Пример GraphQL-вызова сервиса через бинарный протокол:

resp, _ = conn.call('execute_graphql', {
    "query": '''
        query {
            hello_world
        }
    ''',
    "schema": "default",
})

Пример GraphQL-вызова сервиса ` с аргументами через бинарный протокол:

resp, _ = conn.call('execute_graphql', {
    "query": '''
        query ($title: String!)  {
            Country(title: $title) {
                title,
                phone_code
            }
        }
    ''',
    "variables": {
        "title": "Russia"
    },
    "schema": "default",
})

Note

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

Подробнее о доступе к данным в TDG через GraphQL рассказываeтся в главе Запросы данных.

Использование интерфейса репозитория¶

Функции Repository API доступны для вызова через бинарный протокол напрямую. Для вызова необходимо указать вызываемую функцию (например, repository.get) и передать её аргументы.

Пример запроса объекта по ключу через интерфейс репозитория:

resp, _ = conn.call('repository.get', ( 'Country', ['Russia']))

Пример вставки объекта через интерфейс репозитория:

resp, _ = conn.call('repository.put', ( 'Country', {'title': 'China', 'phone_code': '+86'}))

Вызов сервисов¶

Для вызова сервисов через бинарный протокол используется функция call_service. Её основной аргумент - имя вызываемого сервиса. Если у него есть аргументы, они передаются в виде таблицы в следующем аргументе.

Пример вызова сервиса без аргументов через бинарный протокол:

resp, _ = conn.call('call_service', 'hello_world')

Пример вызова сервиса с аргументами через бинарный протокол:

resp, _ = conn.call('call_service', 'get_cities', {'country': 'Russia'})

Загрузка данных из файлов¶

В этой главе описывается загрузка данных в TDG из файлов.

TDG предоставляет возможность загрузки данных в хранилища из файлов с помощью файловых коннекторов. Поддерживается загрузка из двух форматов: comma-separated values (csv) и JSON Lines (jsonl).

В момент своего создания файловый коннектор обрабатывает все входящие данные из указанного в конфигурации файла и затем удаляет его. После этого коннектор периодически проверяет существование файла и при его наличии загружает содержимое. Таким образом, для загрузки новых данных нужно помещать их в файл с тем же именем.

В этом руководстве рассмотрим пример загрузки данных из CSV-файла в TDG с помощью файлового коннектора.

Для выполнения примера требуются:

настроенный кластер TDG;
модель данных, сохраненная в файле model.avsc. В примере используется модель из раздела по настройке модели данных.

Руководство включает в себя следующие шаги:

Создание и загрузка файла с данными
Настройка коннектора
Реализация обработчика
Загрузка конфигурации
Проверка загрузки данных

Создание и загрузка файла с данными ¶

CSV-файл с данными для загрузки в TDG должен содержать в каждой строке поля одного объекта данных. Файл может содержать данные только одного модельного типа. Первая строка должна описывать формат строк с данными: в ней указывается порядок полей объекта.

CSV-файл countries.csv для загрузки нескольких объектов типа Country может выглядеть следующим образом:

"title","phone_code"
"Argentina","+54"
"Australia","+61"
"Austria","+43"

Note

Значения обнуляемых полей могут быть пропущены. В этом случае они получат значение null.

Файл с данными необходимо загрузить в место, откуда его сможет вычитать TDG. У пользователя, под которым работает процесс TDG, должны быть права на чтение и запись в директорию с этим файлом.

Для выполнения примера загрузите файл на сервер, на котором работает узел кластера с ролью connector, в директорию /tmp/csv/.

Настройка коннектора ¶

Файловый коннектор в TDG можно настроить в файле конфигурации .yml.

Создайте файл конфигурации config.yml со следующими настройками:

types:
  __file: model.avsc

connector:
  input:
    - name: csv_importer
      type: file
      format: csv
      workdir: /tmp/csv/
      filename: countries.csv
      routing_key: input_key

input_processor:
  handlers:
    - key: input_key
      function: classifier.call
  storage:
    - key: country
      type: Country

В файле указываются:

используемая модель данных;
секция connector – настройки файлового коннектора. Настройки включают в себя имя и тип коннектора, формат файла для загрузки (csv), его имя (countries.csv) и расположение (/tmp/csv/). Также определен ключ маршрутизации routing_key со значением input_key;
секция input_processor – обработка входящих данных. Здесь заданы ключ для хранилища (country), в котором будет сохранен объект Country, а также определен обработчик (classifier.call) для ключа маршрутизации input_key. Узнать больше про настройку input_processor можно в соответствующем разделе справочника;

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

Реализация обработчика ¶

Данные из файла попадают через коннектор в обработчики (handlers), заданные в файле конфигурации в секции input_processor.

В функции обработчика можно модифицировать поступившую информации, а также определить ключ routing_key для дальнейшей обработки. В данном случае следующим этапом будет сохранение в хранилище объектов Country.

В файле classifier.lua укажите функцию, которая будет запускаться в input-обработчике. Функция задаст ключу routing_key значение country:

return {
    call = function(param)
        param.routing_key = 'country'
        return param
    end
}

Загрузка конфигурации ¶

Чтобы выполнить пример, нужно загрузить архив с моделью данных, файлом конфигурации и функцией обработчика в TDG:

Поместите файл с функцией обработчика classifier.lua в папку src.
Упакуйте в zip-архив:
- папку src, внутри которой лежит файл classifier.lua;
- модель данных model.avsc;
- файл конфигурации config.yml.
Загрузите архив в TDG согласно инструкции.

Файловый коннектор выполнит загрузку данных в соответствии со своей конфигурацией немедленно после добавления.

Warning

В результате срабатывания файлового коннектора файл, из которого выполнялась загрузка, будет удалён.

В случае ошибки при работе файлового коннектора в директории workdir будет создан файл с расширением .error с информацией об ошибке.

Проверка загрузки данных ¶

В результате работы файлового коннектора:

Корректно форматированные объекты из файла будут загружены в соответствующее хранилище;
Объекты, которые не удалось загрузить автоматически, попадут в ремонтную очередь;

Для проверки добавления новых объектов отправьте GraphQL-запрос на чтение объектов типа Country (например, на вкладке GraphQL веб-интерфейса TDG):

{
  Country {
    phone_code
    title
  }
}

В результате вы получите список объектов, которые были описаны в CSV-файле:

{
  "data": {
    "Country": [
      {
        "title": "Argentina",
        "phone_code": "+54"
      },
      {
        "title": "Australia",
        "phone_code": "+61"
      },
      {
        "title": "Austria",
        "phone_code": "+43"
      }
    ]
  }
}

Версионирование¶

Этот раздел объясняет, как управлять данными в Tarantool Data Grid (TDG).

Управление версиями данных в TDG¶

Управление версиями данных (версионирование) – это возможность сохранять, извлекать и восстанавливать разные версии объектов, а также отслеживать когда и какие изменения в них были внесены.

В TDG для управления версиями используется параметр versioning, который задается в файле конфигурации config.yml.

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

Например, у нас есть модель данных и тип объекта Country, для которого включено версионирование. Спейс, где хранятся объекты данного типа, имеет первичный ключ. Если выполняется операция по сохранению в спейс нового объекта с таким же значением первичного ключа, то новый объект не заменит предыдущий, а будет сохранен как новый кортеж, но с уникальным значением timestamp, которое фиксируется каждый раз при сохранении объекта. Это время является идентификатором версии объекта и также сохраняется в кортеже, в котором хранится информация об объекте.

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

По умолчанию на хранение версий установлено ограничение – не более пяти версий для одного объекта, но вы можете выставить другое значение в config.yml.

Note

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

Почему версионирование важно?¶

Версионирование может быть полезно во многих случаях. Например:

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

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

Настройка параметров версионирования¶

Версионирование выключено по умолчанию, чтобы улучшить производительность TDG. Чтобы включить версионирование в конфигурации системы, укажите опцию versioning в файле config.yml.

Пример. Воспользуйтесь типом объекта Country из примера модели данных и настройте для него версионирование. Для этого откройте файл config.yml и в блоке versioning укажите следующее:

versioning:
  - type: Country
    enabled: true

После этого версионирование для Country будет включено.

Note

При включении версионирования старая история версий будет удалена.

Вы также можете настроить следующие параметры, относящиеся к версионированию:

keep_version_count– количество хранимых версий. По умолчанию: 5. Минимальное значение: 1. Если вы не хотите ограничивать количество хранимых версий, удалите этот параметр. Если параметр задан, старые версии будут удаляться. Только новые версии, количество которых меньше или равно заданному значению параметра, будут сохранены. Каждый раз, когда добавляется новая версия, система проводит проверку и удаляет старые версии при необходимости
delay_sec – интервал в секундах, через который запускается новая проверка устаревших объектов. Найденные устаревшие объекты удаляются. Минимальное значение: 1
lifetime_hours – время жизни версии в часах, также может быть задано в днях (lifetime_days) или годах (lifetime_years). По умолчанию не задано, поэтому версии хранятся неограниченное время. Минимальное значение: 1. Если параметр задан, версии, существующие дольше заданного значения параметра, будут удалены.
strategy – стратегия удаления предыдущих версий из хранилища (архивирование). Вы можете определить стратегию на постоянное удаление версий (permanent), вывод в файл (dir) или холодное хранение (cold_storage). По умолчанию: permanent.

Если параметр strategy задан на вывод в файл или хранение на диске, необходимо указать schedule – расписание запуска задачи на архивацию в формате cron с поддержкой секунд. При выводе в файл также необходимо указать максимальный размер файла, используя параметр file_size_threshold.

Note

Когда включена стратегия cold_storage, данные сохраняются в спейсе на vinyl. Получить доступ к таким данным можно только вручную, с помощью запросов space_object:select().

Полная информация о параметрах versioning приведена в справочнике по конфигурации.

Пример

Задайте параметры версионирования для типов объектов Country и City из примера модели данных.

Country: хранить 7 версий, ограничить время жизни 4 часами, запускать проверку через 1 секунду, использовать холодное хранение (хранить на диске).

City: хранить 3 версии, ограничить время жизни 2 днями, запускать проверку через 1 секунду, архивировать версии в файл.
versioning:
  - type: Country
    enabled: true
    keep_version_count: 7
    lifetime_hours: 4
    delay_sec: 1
    strategy: cold_storage
    schedule: "0 0 0 */1"
  - type: City
    enabled: true
    keep_version_count: 3
    lifetime_days: 2
    delay_sec: 1
    strategy: file
    schedule: "0 0 0 */1 * *"
    dir: "/var/data"
    file_size_threshold: 100001

Включить версионирование и задать эти параметры также можно в веб-интерфейсе во вкладке Data types. Если значение параметра lifetime_hours составляет больше 24 часов, система автоматически пересчитает значение в соответствующее количество дней, месяцев или лет.

Запросы к данным по версии¶

Запросы к данным по версии выполняются путем указания поля version в теле HTTP-запроса или запроса GraphQL.

В TDG есть две категории таких запросов:

Исторические данные – данные объектов, которые имеют более раннюю версию, чем указанная, или ту же версию, что и указанная в запросе.
Исторические модификации – данные об изменениях объектов, которые имеют более раннюю версию, чем указанная, или ту же версию, что и указанная в запросе.

Исторические данные¶

Запросы на чтение исторических данных полезны, например, когда часть информации была удалена в последней версии объекта.

Вспомним пример модели данных и рассмотрим запрос на чтение исторических данных Country.

Пример. У нас есть тип объекта Country с информацией о телефонном коде страны. Но в последней версии Country правильная информация о телефонном коде была изменена.

Чтобы получить правильную информацию о телефонном коде, нужно посмотреть предыдущую версию Country.

Сделать это можно в два этапа:

Узнайте последнюю версию Country
Сделайте запрос на чтение данных предыдущий версии Country

Чтобы проверить последнюю версию, добавьте поле version в параметры запроса GraphQL:

{
  Country(title: "Russia") {
    title
    phone_code
    version
  }
}

Пример ответа:

{
  "data": {
    "Country": [
      {
        "version": "1515",
        "title": "Russia",
        "phone_code": "+8"
      }
    ]
  }
}

Note

Ответ возвращает указанную или более раннюю версию, если запрошенная версия не существует. Если поле version не было указано, ответ вернет последнюю версию объекта.

Скопируйте из ответа значение version, вычтите из него единицу и выполните запрос GraphQL на предыдущую версию:

{
  Country(title: "Russia", version: "1514") {
    title
    phone_code
    version
  }
}

Пример ответа:

{
  "data": {
    "Country": [
      {
        "version": "1514",
        "title": "Russia",
        "phone_code": "+7"
      }
    ]
  }
}

Вы можете перебирать предыдущие версии, пока не обнаружите версию с нужной информацией.

Note

Если запрошенная версия меньше существующего минимального значения, ответ вернет пустой объект.

Вы также можете запросить все версии объекта, используя поле all_versions, и ограничить результат ответа при помощи пагинации:

{
  Country(title: "Russia", all_versions: true, first: 5) {
    title
    phone_code
  }
}

Исторические модификации¶

Запросы на исторические модификации данных полезны, например, когда нужно изменить или удалить данные в конкретной версии объекта.

TDG поддерживает следующие запросы на изменение данных (mutations):

Вставка объекта (insert)
Обновление объекта (update)
Удаление объекта (delete)

Для осуществления запросов на изменение данных вы можете использовать HTTP-запросы или запросы GraphQL.

Note

Выполнение HTTP-запросов потребует токен приложений. В примерах используется уже сгенерированный токен Authorization: Test f0d4d72b-2232-42ff-a1ee-1127a93df0d3. Вам необходимо сгенерировать свой токен с правами на запись и чтение в кластере TDG, к которому будет осуществляться доступ, иначе авторизация не пройдет.

Ниже приведены примеры обоих вариантов запросов.

Вставка объекта¶

Когда вы добавляете объект, поле version определяет, какая версия объекта добавляется или заменяется.

Пример. Добавьте объект типа Country с title: "Poland" и phone_code: "+48".

Пример запроса GraphQL:

mutation {
  Country(
    insert: {
      version: "1515"
      title: "Poland"
      phone_code: "+48"})
  {
    version
    title
    phone_code
  }
}

Пример HTTP-запроса с использованием утилиты curl:

curl --request POST \
   --url 'http://172.19.0.2:8080/graphql?=' \
   --header 'Authorization: Test f0d4d72b-2232-42ff-a1ee-1127a93df0d3' \
   --data '{"query":"mutation {Country(insert: {version: "1515", title: \"Poland\", phone_code:\"+48\"}) {version title phone_code}}"}'

Ответ в обоих случаях будет одинаковым:

{
  "data": {
    "Country": [
      {
        "version": "1515",
        "title": "Poland",
        "phone_code": "+48"
      }
    ]
  }
}

Note

Если указанного параметра version нет, то вставка данных будет выполнена в ближайшую предыдущую версию этого объекта. Если необходимо вставить данные во все версии объекта, используйте поле all_versions.

Обновление объекта¶

При обновлении данных в поле version указывается версия объекта, подлежащая изменению.

Пример. Вернемся к типу объекта Country. В запросе укажем версию 1515 и обновим поле phone_code на значение +7.

Пример запроса GraphQL:

mutation {
  Country(title: "Russia", version: "1515" update:[["set", "phone_code", "+7"]]) {
    version
    title
    phone_code
  }
}

Пример HTTP-запроса с использованием утилиты curl:

curl --request POST \
   --url 'http://172.19.0.2:8080/graphql?=' \
   --header 'Authorization: Test f0d4d72b-2232-42ff-a1ee-1127a93df0d3' \
   --data '{"query":"mutation {Country(update: {title: "Russia", version: "1515" [[\"set\", \"phone_code\", \"+7\"]]) {title version phone_code}}"}'

Ответ в обоих случаях будет одинаковым:

{
  "data": {
    "Country": [
      {
        "version": "1515"
        "title": "Russia"
        "phone_code": "+7"
      }
    ]
  }
}

Note

Если указанного параметра version нет, то обновление данных объекта будет выполнено в ближайшую предыдущую версию этого объекта.

Удаление объекта¶

При удалении данных в поле version указывается версия объекта, подлежащая удалению.

Note

Чтобы все версии объекта были полностью удалены, установите значение true параметру all_versions.

Пример. Удалите объект Country с версией 1514.

Пример запроса GraphQL:

mutation {
  Country(delete: true, title: "Russia", version: "1514") {
    title
    version
    phone_code
  }
}

Пример ответа:

{
  "data": {
    "Country": [
      {
        "version": "1514"
        "phone_code": "+7",
        "title": "Russia"
      }
    ]
  }
}

Note

Если параметр version не задан, то будет удалена последняя версия объекта.

Ограничения запросов¶

Использование дополнительных параметров блока hard-limits в config.yml помогает контролировать нагрузку на сервер. Вы можете задать следующие параметры:

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

Пример заполнения параметров:

hard-limits:
  scanned: 1500
  returned: 200

Практический пример использования¶

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

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

Вспомним пример модели данных и добавим новый тип объекта Tourists:

[
    {
        "name": "Country",
        "type": "record",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "phone_code", "type": ["null", "string"]}
        ],
        "indexes": ["title"],
        "relations": [
            { "name": "city_relation", "to": "City", "count": "many", "from_fields": "title", "to_fields": "country" }
        ]
    },
    {
        "name": "City",
        "type": "record",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "population", "type": "int"},
            {"name": "capital", "type": "boolean"},
            {"name": "postcodes", "type": {"type":"array", "items":"int"}}
        ],
        "indexes": [
            {"name":"primary", "parts":["title", "country"]},
            "title",
            "country",
            "population",
            "postcodes"
        ]
    },
    {
        "name": "Tourists",
        "type": "record",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "name", "type": "string"},
            {"name": "number_of_visits", "type": "int"}
        ],
        "indexes": ["title"],
        "relations": [
            { "name": "city", "to": "City", "count": "many", "from_fields": "title", "to_fields": "сity" }
        ]
    },
]

Tourists уже имеет 12 версий, и сегодня нам нужно сделать очередную выборку о количестве посещений туристами определенного города.

Для этого всегда использовался запрос на чтение Tourists:

{
  Tourists(title: "Moscow") {
    title
    country
    number_of_visits
  }
}

Но сегодня запрос, который отлично работал день назад, вызывает ошибки из-за измененных данных. Самый эффективный способ выяснить, что вызывает проблему – выполнить тот же запрос к предыдущей версии, в которой не было ошибки. В нашем случае – это версия 11:

{
  Tourists(title: "Moscow", version: "11") {
    title
    country
    number_of_visits
  }
}

Note

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

Но ответ снова возвращает ошибку. В этом случае необходимо сделать новый запрос к 10 версии объекта и продолжать делать запросы к предыдущим версиям, пока не будет найдена та, в которой нет ошибки.

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

Таким образом, если вы используете версионирование, это упрощает отладку и приводит к быстрому исправлению ошибок данных.

Reference¶

This document describes Tarantool Data Grid (TDG) API functions and configuration parameters.

Конфигурация Tarantool Data Grid¶

В этой главе описывается конфигурация Tarantool Data Grid. С ее помощью можно настроить логику обработки входящих запросов, кластерные роли и другие системные параметры TDG.

Местоположение¶

Конфигурация TDG может храниться в едином файле config.yml или быть семантически разбитой на несколько файлов: schema.yml, topology.yml и т. д. – подобно тому, как это делается в Tarantool Cartridge.

По умолчанию конфигурация каждого экземпляра хранится по адресу /var/lib/tarantool/<имя_экземпляра>/config.yml или в папке /var/lib/tarantool/<имя_экземпляра>/config/.

Загрузка¶

Если конфигурация собрана в одном файле config.yml, в веб-интерфейсе перейдите на вкладку Configuration files, нажмите на кнопку Upload a new config и загрузите файл.

Если конфигурация разнесена по разным файлам, соберите их в архив. Затем в веб-интерфейсе перейдите на вкладку Configuration files, нажмите на кнопку Upload a new config и загрузите архив. Файлы будут распакованы и применены.

Пример файла config.yml¶

---
types:
  __file: model.avsc

connector:
  input:
    - name: http
      type: http
      routing_key: input_processor

routing:
  - key: smtp_key
    output: to_smtp

output:
  - name: to_smtp
    type: smtp
    url: localhost:2525
    from: tdg@example.com
    timeout: 5
  - name: dummy
    type: dummy

input_processor:
  handlers:
    - key: input_processor
      function: handler.call

storage:
  - key: country_key
    type: Country
  - key: city_key
    type: City
  - key: tourists_key
    type: Tourists

output_processor:
  estate_key:
    handlers:
      - function: output.country_output.call
        outputs:
          - dummy

services:
  calc_district_stat:
    doc: "calculate statistic for selected district"
    function: districts_stat.calc_statistics.call
    return_type: string
    args:
      district: string
  calc_all_districts_stat:
    doc: "calculate statistic for all district"
    function: districts_stat.calc_statistics.call
    return_type: string

tasks:
  update_all_districts_stat:
    kind: periodical
    function: districts_stat.calc_statistics.call
    # синтаксис в стиле cron с точностью до секунд
    # формат: секунда минута час день месяц день_недели
    schedule: "0 */5 * * * *"

logger:
  enabled: true

versioning:
  - type: Country
    enabled: true
  - type: City
    enabled: true

Конфигурация кластера¶

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

Параметры топологии¶

Топология кластера настраивается при помощи секций topology и vshard_groups.

Note

Рекомендуется создать и настроить эти секции в отдельных файлах: topology.yml и vshard_groups.yml, поместив эти файлы в папку config в корне проекта.

Секция topology¶

Секция topology содержит три главных подраздела:

replicasets – содержит информацию о том, как экземпляры Tarantool организованы в наборы реплик, какие у узлов кластерные роли и веса при шардировании;
servers – список всех экземпляров Tarantool;
failover – настройки восстановления после сбоев.

replicasets¶

Этот подраздел содержит информацию о том, как экземпляры организованы в наборы реплик.

Каждый набор реплик идентифицируется по своему номеру UUID. Для каждого приводятся следующие параметры:

weight – вес набора реплик. По умолчанию: 0 (подключен, но пока не принимает данные). При указанном весе 0 попытки шардирования будут приводить к ошибке на роутере (vshard-router).
master – UUID экземпляра-мастера в этом наборе реплик.
alias – человекопонятное имя набора реплик.
vshard_group – группа шардирования, к которой относится набор реплик. По умолчанию: default.
roles – список кластерных ролей, включенных (true) или выключенных (false) для набора реплик.
all_rw – являются ли все узлы в наборе реплик мастерами. По умолчанию: false.

Пример для одного набора реплик:

replicasets:
  5e47bf8e-57f5-4166-96ba-e16f964fb82b: # UUID набора реплик
    weight: 1
    master:
    - dee26aab-0190-461d-9121-56b96b881a59
    alias: unnamed
    vshard_group: default
    roles:
      tracing: true
      ddl-manager: true
      maintenance: true
      watchdog: true
      account_provider: true
      metrics: true
      common: true
      core: true
      failover-coordinator: true
      storage: true
      runner: true
      vshard-router: true
      connector: true
      vshard-storage: true
    all_rw: false

servers¶

В этом подразделе приведен список всех экземпляров Tarantool. Каждый из них идентифицируется по своему номеру UUID. Для каждого указаны следующие параметры:

uri – внутренний URI-адрес экземпляра.
disabled – выключен ли экземпляр. По умолчанию: false.
replicaset_uuid – UUID набора реплик, в котором состоит экземпляр.

Пример для одного экземпляра:

servers:
  dee26aab-0190-461d-9121-56b96b881a59:
    uri: localhost:3301
    disabled: false
    replicaset_uuid: 5e47bf8e-57f5-4166-96ba-e16f964fb82b

failover¶

В этом подразделе указываются настройки восстановления после сбоев, аналогичные соответствующим настройкам Cartridge.

Пример:

failover:
  fencing_enabled: true
  failover_timeout: 20
  fencing_pause: 2
  mode: eventual
  fencing_timeout: 10

По умолчанию подраздел отключен:

failover: false

Секция vshard_groups¶

В этой секции указываются группы шардирования, или vshard-группы, к каждой из которых может принадлежать один или несколько наборов реплик. Внутри такой группы данные шардируются между входящими в нее наборами реплик.

В vshard-группе могут состоять только наборы реплик с ролью storage. Один набор реплик не может состоять в двух разных vshard-группах.

Параметры групп шардирования указываются так же, как при работе с Tarantool.

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

default:
  rebalancer_max_receiving: 100
  bootstrapped: true
  collect_lua_garbage: false
  sync_timeout: 1
  rebalancer_max_sending: 1
  sched_ref_quota: 300
  rebalancer_disbalance_threshold: 1
  bucket_count: 30000
  sched_move_quota: 1

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

Параметры авторизации¶

Авторизация настраивается при помощи секций auth/auth_external, ldap.

Секция auth позволяет настроить существующую систему авторизации аналогично тому, как это делается в Tarantool Cartridge. Вместо этого можно в секции auth_external указать путь к файлу с Lua-кодом, где задана нестандартная логика для авторизации входящих запросов.

Кроме того, ниже рассматривается секция pepper, где можно задать переменную, с помощью которой будут хешироваться пароли.

Секция auth_external¶

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

Пример. Укажем путь к файлу auth.lua с логикой для авторизации входящих запросов:

auth_external: {__file: auth.lua}

Содержание auth.lua определяется пользователем самостоятельно. Например, в файле может быть указана такая логика обработки:

-- Функция авторизует пользователя по HTTP-заголовку

local function auth(request)
local header = request.headers['custom_token']
if header == nil then
    return nil, "no header"
end

if header == 'error-injection' then
    error('error-injection')
end

if header == 'invalid-answer' then
    return 'invalid-answer'
end

if header == 'invalid-decision' then
    return {
        decision = 'invalid-decision',
    }
end

if header == 'invalid-token' then
    return {
        decision = 'reject',
        reason = 'invalid token',
    }
end

if header == 'fallback-token' then
    return {
        decision = 'fallback',
    }
end

if header == 'custom-response' then
    return {
        decision = 'reject',
        status_code = 418,
        reason = 'Hello, world!',
        headers = {
            ['custom'] = 'header',
        }
    }
end

return {
    decision = 'accept',
    account = {
        is_user = true,
        email = 'example@tarantool.org',
        role_id = 1,
    },
}
end

return {
    auth = auth,
}

Секция ldap¶

В этой секции указываются параметры авторизации внешних пользователей и систем через LDAP:

domain – доменное имя, которое используется в доменном логине пользователя (user@domain).
organizational_units – названия организационных подразделений или групп пользователей. Параметр опциональный и будет пропущен, если для него не задано значение.
hosts – адрес подключения к серверу LDAP.
use_active_directory – параметр, определяющий использование Active Directory (служба каталогов Microsoft). Значение по умолчанию: false.

Если установлено значение true, используйте адрес электронной почты для входа в систему и атрибут Active Directory userprincipalname=email в качестве фильтра, где email – адрес электронной почты пользователя. Часть с именем пользователя в email будет распознана одинаково независимо от регистра (aBc@mail.ru и AbC@mail.ru – это один и тот же пользователь).
use_tls – параметр, определяющий использование TLS. Значение по умолчанию: false.
search_timeout – время ожидания ответа от сервера LDAP в секундах. Значение по умолчанию: 2.
options – настройки LDAP. Параметр опционален. Доступные настройки:
- LDAP_OPT_DEBUG_LEVEL – уровень отладки клиентской библиотеки.
- LDAP_OPT_PROTOCOL_VERSION – версия протокола LDAP.
- LDAP_OPT_X_TLS_CACERTDIR– путь к директории с корневыми сертификатами.
- LDAP_OPT_X_TLS_CACERTFILE – полный путь к файлу корневого сертификата.
- LDAP_OPT_X_TLS_NEWCTX – создание нового контекста библиотеки TLS.
- LDAP_OPT_X_TLS_REQUIRE_CERT – стратегия проверки сертификатов. Принимает целое значение от 0 до 4, где:
  - 0 – LDAP_OPT_X_TLS_NEVER,
  - 1 – LDAP_OPT_X_TLS_HARD,
  - 2 – LDAP_OPT_X_TLS_DEMAND,
  - 3 – LDAP_OPT_X_TLS_ALLOW,
  - 4 – LDAP_OPT_X_TLS_TRY.
Подробное описание этих настроек LDAP приведено на странице ldap_get_option().
roles – описание ролей, которые будут назначаться пользователю в зависимости от групп LDAP, в которых он состоит. Вложенные параметры:
- role – роль, назначенная пользователю или внешнему приложению для авторизованного доступа и действий в системе (читать подробнее про роли).
- domain_groups – LDAP-группы, которые соответствуют указанной выше роли. В параметрах групп указываются:
  - cn (common name) – общее имя.
  - ou (organization unit name) – организационное подразделение или группа пользователей.
  - dc (domain component) – компонент домена.
Если пользователь состоит сразу в нескольких LDAP-группах, он получает разрешения на действия из всех ролей, назначенных для этих групп.

Пример

В примере заданы настройки для:

LDAP-группы tarantool с ролью admin;
LDAP-группы svcaccts с ролью supervisor.

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

ldap:
  - domain: 'my.domain.ru'
    organizational_units: ['tarantool']
    hosts:
      - server.my.domain.ru:389
    use_tls: false
    use_active_directory: false
    search_timeout: 2
    options:
      - LDAP_OPT_DEBUG_LEVEL: 3
    roles:
      - domain_groups:
          - 'cn=tarantool,ou=groups,dc=my,dc=domain,dc=ru'
        role: 'admin'

  - domain: 'my.domain.ru'
    organizational_units: ['svcaccts']
    hosts:
      - server.my.domain.ru:389
    use_tls: false
    use_active_directory: false
    search_timeout: 2
    roles:
      - domain_groups:
          - 'cn=svcaccts,ou=groups,dc=my,dc=domain,dc=ru'
        role: 'supervisor'

Секция pepper¶

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

Пример:

pepper: 2d60ec7f-e9f0-4018-b354-c54907b9423d

Настройка времени ожидания сетевых вызовов при шардировании¶

vshard-timeout – отдельная секция, где указывается время, в течение которого модуль vshard ожидает сетевые запросы. Это время в секундах передается в функциях vshard.router.callro() и vshard.router.callrw().

Значение по умолчанию – 2 секунды:

vshard-timeout: 2

Конфигурация бизнес-логики¶

В конфигурацию бизнес-логики можно добавить параметры модели данных, мониторинга, сервисов GraphQL, подсистем и коннекторов.

Note

Для простоты эксплуатации рекомендуется хранить различные параметры конфигурации в разных YAML-файлах.

Параметры модели данных¶

Настроить модель данных можно, используя следующие секции:

types – описание типов объектов в модели данных.
versioning – настройка параметров времени жизни объектов и ограничения количества версий объектов.
archivation – настройка параметров архивации объектов.
welcome-message – текст приветственного сообщения.
tdg-version – проверка версии TDG при применении конфигурации.

Секция types¶

В этой секции настраивается модель данных – указываются типы объектов, которые будут сохраняться в TDG. В качестве языка описания модели данных TDG используется Apache Avro Schema.

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

types: {__file: model.avsc}

Содержание model.avcs определяется пользователем самостоятельно. Например, в файле может быть указана такая модель данных:

[
    {
        "name": "Country",
        "type": "record",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "phone_code", "type": ["null", "string"]}
        ],
        "indexes": ["title"],
        "relations": [
        { "name": "city", "to": "City", "count": "many", "from_fields": "title", "to_fields": "country" }
        ]
    },
    {
        "name": "City",
        "type": "record",
        "fields": [
            {"name": "title", "type": "string"},
            {"name": "country", "type": "string"},
            {"name": "population", "type": "int"},
            {"name": "capital", "type": "boolean"}
        ],
        "indexes": [
            {"name":"primary", "parts":["title", "country"]},
            "title",
            "country",
            "population"
        ]
    }
]

Секция versioning¶

В этой секции настраивается версионирование – сохранение разных версий объектов для последующего извлечения, просмотра и восстановления объектов.

По умолчанию версионирование отключено. Чтобы его включить, укажите enabled: true для нужного типа объекта.

Пример. Включить версионирование для объекта типа Tourists можно так:

versioning:
  - type: Tourists
    enabled: true

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

keep_version_count – количество хранимых версий. По умолчанию: 5. Минимальное значение: 1. Если вы не хотите ограничивать количество хранимых версий, удалите этот параметр. Если параметр задан, старые версии будут удаляться. Только новые версии, количество которых меньше или равно заданному значению параметра, будут сохранены. Каждый раз, когда добавляется новая версия, система проводит проверку и удаляет старые версии при необходимости.
delay_sec – интервал в секундах, через который запускается новая проверка устаревших объектов. Найденные устаревшие объекты удаляются. Минимальное значение: 1.
lifetime_hours – время жизни версии в часах, также может быть задано в днях (lifetime_days) или годах (lifetime_years). По умолчанию не задано, поэтому версии хранятся неограниченное время. Минимальное значение: 1. Если параметр задан, версии, существующие дольше заданного значения параметра, будут удалены.
strategy – стратегия удаления предыдущих версий из хранилища (архивирование). Варианты стратегии:
- dir – вывод в файл;
- permanent – постоянное удаление версий;
- cold_storage – хранение на диске с расчетом на то, что данные будут запрашиваться редко.
  
  Note
  
  Когда включена стратегия cold_storage, данные сохраняются в спейсе на vinyl. Получить доступ к таким данным можно только вручную, с помощью запросов space_object:select().
Значение по умолчанию: permanent.

Если параметр strategy задан на вывод в файл или хранение на диске, необходимо указать schedule – расписание запуска задачи на архивацию в формате cron с поддержкой секунд. При выводе в файл также необходимо указать максимальный размер файла, используя параметр file_size_threshold.
schedule – расписание в формате cron, по которому проверяется наличие изменений в объектах. Обязательный параметр, если задана стратегия strategy: cold_storage или strategy: file.
dir – директория, где в JSON-файлах хранятся прежние версии объектов.
file_size_threshold – предельный размер JSON-файла, в котором хранятся прежние версии объектов. Когда предельное значение достигнуто, версии начинают сохраняться в новый файл. Обязательный параметр, если задана стратегия strategy: file.

Пример¶

Укажем параметры версионирования для типов объектов Country и City.

Country: хранить 7 версий, ограничить время жизни 4 часами, запускать проверку через 1 секунду, использовать холодное хранение (хранить на диске).

City: хранить 3 версии, ограничить время жизни 2 днями, запускать проверку через 1 секунду, архивировать версии в файл.

versioning:
  - type: Country
    enabled: true
    keep_version_count: 7
    lifetime_hours: 4
    delay_sec: 1
    strategy: cold_storage
    schedule: "0 0 0 */1"
  - type: City
    enabled: true
    keep_version_count: 3
    lifetime_days: 2
    delay_sec: 1
    strategy: file
    schedule: "0 0 0 */1 * *"
    dir: "/var/data"
    file_size_threshold: 100001

Секция archivation¶

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

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

По умолчанию архивация не настроена. Чтобы ее настроить, задайте в секции archivation следующие параметры:

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

Пример¶

Укажем настройки архивации для типа объекта Quotation, чтобы повысить производительность TDG за счёт архивирования редко используемых цитат.

archivation:
  - type: Quotation
    lifetime_days: 7
    schedule: "0 0 0 */1 * *"
    dir: "/var/data"
    file_size_threshold: 104857600

Секция welcome-message¶

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

Полезно изменять секцию welcome-message, например, если вы хотите облегчить работу с TDG новым сотрудникам, дописав им полезные подсказки, или решили оставить важную информацию для опытных коллег.

Пример¶

Изменим текст приветственного сообщения, чтобы сообщить коллегам о планируемом обновлении сервиса.

welcome-message: |
  Коллеги, сервис может быть недоступен в четверг с 12.00 до 14.00 в связи с плановым обновлением.

Секция tdg-version¶

В этой секции настраивается проверка версии TDG на совместимость при применении конфигурации. Для параметра указывается условие проверки, и с ним сравнивается текущая версия TDG. Если условие не выполняется, применение конфигурации останавливается.

Примеры¶

Проверим версию 1.6.0 на совместимость.

tdg-version: "== 1.6.0"

В примере:

==, <=, <, >, >= – оператор.
1.7.0 – версия major.minor.patch (семантическое версионирование) или scm-<число>.

Note

Чтобы избежать возможных ошибок при чтении, всегда заключайте выражение из оператора и версии в кавычки. Обязательного помещения в кавычки не требует только выражение с ==.

Синтаксис YAML позволяет указывать многостроковые значения с помощью операторов >, <, >=, >= в первой строке. Чтобы задать версию больше, чем выбранное значение, нужно поместить оператор > и версию в кавычки.

Пример неправильного заполнения, когда версия будет прочитана как 1.6.0:

tdg-version: > 1.6.0

Пример правильного заполнения, когда версия будет прочитана как больше чем 1.6.0:

tdg-version: "> 1.6.0"

Параметры мониторинга¶

Настроить параметры мониторинга и изменить логику обработки объектов, при необходимости передавая функциональную нагрузку на резервный компонент, можно при помощи секций jobs, tracing, repair_queue, maintenance и metrics.

Секция jobs¶

В этой секции при помощи параметра max_jobs_in_parallel настраивается максимальное количество отложенных задач (jobs), которые могут выполняться одновременно. Если вы используете отложенные задачи, рекомендуется настроить данную секцию и ограничить количество отложенных задач, чтобы сохранить высокую производительность TDG.

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

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

jobs:
  max_jobs_in_parallel: 50

Секция tracing¶

В этой секции настраиваются параметры для взаимодействия с системой трассировки, которая позволяет анализировать производительность выполнения кода TDG:

lbase_url – адрес API-ресурса (endpoint), куда отсылаются собранные для анализа участки кода (spans).
lapi_method – тип HTTP-запроса для обращения к base_url. Для систем трассировки, поддерживающих протокол OpenZipkin, используется POST.
lreport_interval – интервал в секундах, через который в систему трассировки отсылаются накопленные участки кода.
lspans_limit – максимальное количество участков кода, которое может накапливаться в буфере перед отправкой в систему трассировки.

Пример¶

Укажем локальный адрес для отправки участков кода с максимальным размером буфера = 100.

tracing:
  base_url: localhost:8080/api/v2/spans
  api_method: POST
  report_interval: 0
  spans_limit: 100

Секция repair_queue¶

При стандартном поведении TDG, когда объект поступает в систему на обработку, он сразу помещается в ремонтную очередь. Если объект удалось обработать и сохранить, он удаляется из ремонтной очереди. В случае ошибки объекты остаются в ремонтной очереди, и администратор имеет возможность просматривать их, а после устранения источника проблемы – отправлять на повторную обработку.

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

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

repair_queue:
  on_object_added:
    __unclassified__:
        postprocess_with_routing_key: unclassified

Секция maintenance¶

В этой секции устанавливаются следующие параметры, сигнализирующие об ошибках системы:

clock_delta_threshold_sec – порог рассинхронизации истинного времени (CLOCK_REALTIME) на разных экземплярах Tarantool. Значение указывается в секундах.
fragmentation_threshold_critical – порог, при превышении которого система покажет критическое сообщение о фрагментации данных. Принимает относительные значения от 0 до 1.
fragmentation_threshold_warning – порог, при превышении которого система покажет предупреждение о фрагментации данных. Принимает относительные значения от 0 до 1.

Если тот или иной параметр в секции maintenance выходит за указанные рамки, об этом появляется сообщение в веб-интерфейсе TDG на вкладке Cluster.

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

maintenance:
  clock_delta_threshold_sec: 5
  fragmentation_threshold_critical: 0.9
  fragmentation_threshold_warning: 0.6

Секция metrics¶

В этой секции настраиваются параметры, задающие формат и возможность просмотра метрик по нескольким адресам ресурсов (endpoints) для мониторинга работы TDG. Эти параметры указываются внутри подраздела export:

metrics:
  export:
    - path: '/path_for_json_metrics'
      format: 'json'
    - path: '/path_for_prometheus_metrics'
      format: 'prometheus'
    - path: '/health'
      format: 'health'

Параметры:

path – путь, по которому будут доступны метрики.
format – формат, в котором будут доступны метрики. Может принимать следующие значения:
- 'json'
- 'prometheus'
- 'health' – информация о текущем состоянии экземпляра. Если состояние экземпляра удовлетворительное (healthy), ответом на запрос будет HTTP-код 200, если нет – HTTP-код 500.

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

По умолчанию значения метрик в формате Prometheus доступны по адресу http://<IP_адрес_экземпляра>/metrics.

После заполнения секции metrics в файле конфигурации метрики по умолчанию в формате Prometheus по адресу http://<IP_адрес_экземпляра>/metrics перестанут быть доступными. Чтобы сделать их доступными, также укажите path: '/metrics' и format: 'prometheus' в секции metrics.

Параметры сервисов GraphQL¶

Настроить сервисы GraphQL можно, используя следующие секции:

services – параметры настройки сервисов.
hard-limits – параметры ограничений для запросов GraphQL.
force_yield_limits – параметры ограничений на количество сканирований записей.
graphql_query_cache_size – параметры размера кэша запросов GraphQL.
test-soap-data – текст запроса по умолчанию на вкладке Test.

Секция services¶

В этой секции настраивается конфигурация сервисов.

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

get_price – имя сервиса. Оно всегда должно начинаться с латинской буквы и может содержать латинские буквы, цифры и символ подчеркивания (_).
type – тип запроса GraphQL для вызова сервиса: query или mutation. Если тип – query, параметр можно не указывать.
doc – произвольное описание сервиса.
function – ссылка на Lua-файл с сервис-функцией.
return_type – тип данных, который возвращается в результате выполнения сервиса.
args – описание аргументов, передаваемых на вход при выполнении сервиса, в формате имя_аргумента: тип_данных.

services:
  get_price:
    doc: "Get the item price by ID"
    function: {__file: get_price_by_id.lua}
    return_type: ItemPrice
    args:
      item_id: string

Секция hard-limits¶

В этой секции устанавливаются ограничения для запросов GraphQL. Такие настройки для планировщика запросов позволяют контролировать нагрузку на кластер и предотвращают полное сканирование спейса в TDG. Также данные ограничения учитываются при работе функций Repository API и Sandbox API.

Параметры:

scanned – максимальное количество кортежей, которое TDG будет сканировать при выполнении запроса. Значение по умолчанию: 2000.

Note

Начиная с версии 2.7.0, вместо ограничения scanned для hard-limits TDG использует механизм fiber.slice.
returned – максимальное количество кортежей, которое может вернуть одно хранилище. Значение по умолчанию: 100. Например, returned = 100, а в настройках пагинации параметр first равен 5. Тогда запрос вернет 5 кортежей, а остальной массив данных можно обойти с помощью параметра after.

Настройка данных параметров возможна при конфигурации системы или с помощью специальных запросов и мутаций GraphQL. Пример настроек подраздела hard-limits в файле конфигурации:

hard-limits:
  scanned: 2000
  returned: 100

Во встроенном клиенте GraphiQL в веб-интерфейсе TDG для установки данных ограничений используется схема admin. Пример запроса:

mutation {
  config {
    hard_limits(scanned:5000 returned:400) {
      scanned
      returned
    }
  }
}

Данные настройки превентивно требуют качественного написания запросов. Если одно из ограничений превышается, выполнение запроса прекращается и возвращается ошибка. Всего существует два вида ошибок – для параметров scanned и returned соответственно.

Кроме того, ошибка возникает, если:

для параметра returned верно first > returned;
для параметра scanned верно, что количество записей больше значения scanned, при этом first > scanned.

Пример ошибки: Hard limit for scan rows reached 2000 for space \"storage_MusicBand\"

Такая ошибка при сканировании означает, что при поиске по индексу в спейсе MusicBand было просмотрено более 2000 записей. Для устранения ошибки необходимо добавить индекс, который сократит выборку для данного запроса.

Note

Появление данной ошибки сканирования также возможно, когда используются функции repository.find(), repository.update() и repository.delete() из раздела Repository API.

Ошибка может возникнуть

независимо от значения параметра first, если не используется индекс.

Например, есть запрос repository.find("ModelName", {{'key', '==', 'a'}}. Значение параметра scanned = 5000. Первые 5000 записей при этом не подходят по запросу. Такой запрос вызовет ошибку.

Решение: добавить индекс – "indexes": [..., "key"];
если в запросе используются два или больше фильтров.

Например, есть запрос с несколькими фильтрами, где scanned = 5000. Под первый фильтр подходит 10000 записей. При этом первые 5000 записей не подходят под второй фильтр. Такой запрос вызовет ошибку.

Секция force_yield_limits¶

В этой секции устанавливается ограничение на количество сканирований записей в спейсе. При достижении порога управление потоком переходит от текущего файбера к другому (выполняется yield).

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

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

force_yield_limits: 1000

Секция graphql_query_cache_size¶

В этой секции устанавливается размер кэша для уникальных GraphQL-запросов.

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

graphql_query_cache_size: 3000

Секция test-soap-data¶

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

Пример. Укажем путь к файлу.

test-soap-data: {__file: test_object.json}

Параметры подсистем¶

Каждая подсистема – это набор определенных функциональных возможностей, входящих в ту или иную кластерную роль.

Управляющие подсистемы объединяет в себе роль core.
Обрабатывающие подсистемы объединяет в себе роль runner.
Принимающие подсистемы объединяет в себе роль connector.
Хранящие подсистемы объединяет в себе роль storage.

Ниже рассматриваются параметры, связанные со следующими подсистемами:

input_processor – настраивает логику обработки, маршрутизацию и правила хранения объектов. Относится к роли runner.
output_processor – настраивает логику обработки объектов, которые будут реплицироваться во внешние системы. Относится к роли runner.
account_manager – настраивает работу ролевой модели доступа и связанные с ней функции безопасности. Относится к роли core.
notifier – настраивает отправку уведомлений при попадании объекта в ремонтную очередь. Относится к роли core.
gc – принудительно запускает сборку мусора в коде Lua. Запускается на экземплярах с любой ролью.
sequence_generator – генерирует последовательность случайных чисел. Относится к роли core.
logger – настраивает ведение журнала. Запускается на экземплярах с любой ролью.
tasks – настраивает задачи, выполняемые при помощи ролей scheduler и task_runner.
task_runner – настраивает порог количества выполняемых пайплайнов для задач (tasks) и отложенных задач (jobs). Относится к роли runner.
audit_log – настраивает ведение журнала аудита. Запускается на экземплярах с любой ролью.

input_processor¶

В этой секции настраиваются параметры процессора ввода данных:

handlers – определение обработчиков входящего запроса.

Если обработчик не задан, объект обрабатывается в соответствии со значением, указанным в секции input_processor: routing.

Вложенные параметры:
- key: ключ маршрутизации, по которому определяется, как следует обработать объект.
- function: функция, которую следует применить к объекту.
routing – маршрутизация объекта в определенный пайплайн обработки.

Вложенные параметры:
- key: ключ маршрутизации.
- output: система, куда следует направить объект.
storage – настройки сохранения объекта на экземплярах роли storage.

Вложенные параметры:
- key: ключ маршрутизации.
- type (необязательно): тип бизнес-объекта (агрегата), куда следует направить объект.

Пример:

input_processor:
  handlers:
    - key: input_processor
      function: handler.call
  routing:
    - key: input_processor
      output: to_input_processor
  storage:
    - key: estate_key

output_processor¶

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

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

handlers – обработчики входящих запросов:
- function: имя функции, которую следует применить к объекту.
- outputs: параметры, с которым объект будет отправлен во внешнюю систему.

Пример:

output_processor:
  estate_key:
    handlers:
      - function: output.estate_output.call
        outputs:
          - dummy

account_manager¶

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

Параметры:

only_one_time_passwords – флаг (true/false). По умолчанию: false. Если указано значение true, нет возможности вручную задавать пароль при создании или импорте профиля пользователя. Вместо этого TDG автоматически генерирует одноразовый пароль и высылает его на адрес электронной почты пользователя. Для отсылки пароля также необходимо иметь работающий сервер SMTP, описание его конфигурации в секции connector (output: type: smtp) и указание на этот output в секции account_manager. Опционально можно указать заголовок письма, в котором высылается одноразовый пароль (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 – настройки политики в отношении паролей. Эти настройки также можно задать через веб-интерфейс TDG.
min_length – минимально допустимая длина пароля. По умолчанию: 8.
include – флаги (true/false), определяющие, какие категории символов должны обязательно входить в пароль.

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

Пример. Настроим возможность получать одноразовый пароль по электронной почте.

account_manager:
  only_one_time_passwords: true
  output:
    name: to_smtp
    options:
      subject: "Registration"
  password_change_timeout_seconds: 10
  block_after_n_failed_attempts: 5
  ban_inactive_more_seconds: 86400
  password_policy:
    min_length: 8
    include:
      lower: true
      upper: true
      digits: true
      symbols: false

notifier¶

В этой секции настраивается подсистема notifier для отправки уведомлений:

mail_server – секция настроек сервера SMTP, который используется для отправки уведомлений при попадании объекта в ремонтную очередь. Данные параметры также можно задать через веб-интерфейс TDG.

Вложенные параметры:
- url – URL сервера SMTP.
- from – имя отправителя, которое будет показываться в поле «From» при получении уведомления.
- username – имя пользователя сервера SMTP.
- password – пароль пользователя сервера SMTP.
- timeout – тайм-аут запроса к серверу SMTP. Указывается в секундах.
- skip_verify_host – флаг (true/false): пропустить проверку хоста по протоколу TLS.
users – секция, где задаются данные подписчиков (subscribers), которые будут получать уведомления. Подписчиков также можно создать через веб-интерфейс TDG.

Вложенные параметры:
- id – идентификатор подписчика.
- name – имя подписчика.
- addr – e-mail подписчика.

Пример:

notifier:
  mail_server:
    url: 127.0.0.1:2525
    from: TDG_repair_queue
    username: user
    password: passpass
    timeout: 5
    skip_verify_host: true
  users:
    - id: 1
      name: Petrov
      addr: petrov@mailserver.com

gc¶

В этой секции настраивается подсистема garbage_collector, которая принудительно запускает сборку мусора в Lua. Подсистема включается неявно на всех экземплярах:

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

Пример. Настроим принудительную сборку мусора так, чтобы она происходила каждые три секунды.

gc:
  forced: true
  period_sec: 3
  steps: 20

sequence_generator¶

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

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

Пример. Зададим генерацию последовательности уникальных чисел с 5 при диапазоне 15.

sequence_generator:
  starts_with: 5
  range_width: 15

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 сообщений в логе удаляются за раз, что повышает производительность по сравнению с режимом, когда старые сообщения удаляются по одному.

logger:
  rotate_log: true
  max_msg_in_log: 500000
  max_log_size: 10485760
  delete_by_n_msg: 1000

tasks¶

В этом разделе определяется, какие задачи и в какое время будут запускаться в системе.

Пример:

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

В этом примере:

task_N – имя задачи.
kind – вид задачи: single_shot (однократная), continuous (постоянная) или periodical (периодическая).
function – функция, определяющая, что именно делается в рамках задачи.
keep – количество завершенных экземпляров задачи, которые сохраняются в истории. По умолчанию: 10.
pause_sec – пауза в выполнении задачи вида continuous. Указывается в секундах.
schedule – расписание выполнения для задач вида periodical. Задается в формате cron c расширенным синтаксисом, в котором минимальной величиной является секунда:
```
* * * * * *
| | | | | |
| | | | | ----- День недели (0-6) (Воскресенье = 0)
| | | | ------- Месяц (1-12)
| | | --------- День (1-31)
| | ----------- Час (0-23)
| ------------- Минута (0-59)
--------------- Секунда (0-59)
```
Например, schedule: "0 */5 * * * *" означает, что задача будет запускаться периодически каждые 5 минут.
run_as – пользователь, от имени которого выполняется задача. Применяется только для задач видов continuous или periodical. Указанный пользователь должен иметь достаточно прав для выполнения действий задачи. Если режим обязательной аутентификации выключен, параметр run_as не обязателен. Внутри блока run_as передается параметр:
- user – имя пользователя.

task_runner¶

В этой секции настраивается running_count_threshold – порог количества функций, выполняемых в рамках задач (tasks) и отложенных задач (jobs).

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

task_runner:
  running_count_threshold: 100

audit_log¶

В этой секции задаются параметры журнала аудита. Все параметры опциональные:

enabled – включить (true) или выключить (false) запись событий в журнал аудита. По умолчанию: false.
severity – уровень важности событий, которые будут записываться в журнал аудита. Возможные значения по возрастанию важности: VERBOSE, INFO, WARNING, ALARM. По умолчанию: INFO.

При указании определенного уровня в журнал аудита будут записываться события этого уровня и выше. Например, если задано INFO, будут записываться события, соответствующие уровням INFO, WARNING и ALARM.
remove_older_than_n_hours – максимальное время хранения записей в журнале аудита. Указывается в часах. Записи старше указанного времени удаляются.

Пример. Включим запись событий уровня INFO и более высоких.

audit_log:
  enabled: true
  severity: INFO
  remove_older_than_n_hours: 5

По умолчанию журнал аудита выключен:

audit_log:
  enabled: false

Параметры коннекторов¶

В этой секции настраиваются параметры коннекторов TDG:

input – получение и первоначальная обработка (парсинг) входящих запросов;
output – отправка запросов во внешние системы;
routing – маршрутизация объектов.

Настройка input¶

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

name – имя коннектора (произвольное).
type – тип коннектора. Поддерживаемые типы:
- http – для запросов в формате JSON по HTTP;
- soap – для запросов в формате XML (SOAP) по HTTP;
- kafka – для интеграции с шиной данных Apache Kafka;
- tarantool_protocol – для запросов через iproto;
- file – для загрузки данных из файлов.
is_async – режим работы TDG в качестве producer:
- true (по умолчанию) – асинхронный режим: подтверждение о доставке сообщения отправляется сразу после того, как сообщение добавлено в очередь на отправку.
- false – синхронный режим: подтверждение о доставке сообщения отправляется только после того, как сообщение было доставлено.

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

Особые параметры коннектора типа soap¶

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

Note

Шаблоны ответа (параметры success_response_body и error_response_body) опциональны. Пользователь может задать шаблоны в нужном ему формате, соответствующем системе, в которую отправляется ответ. TDG ограничений на формат не накладывает. В шаблоне error_response_body возможно использовать один спецификатор форматирования %s, чтобы передать в тело ответа текст ошибки.

Пример. Укажем коннектор типа soap.

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_input_handle

Особые параметры коннектора типа kafka¶

brokers – URL-адреса брокеров сообщений.
topics – топики (topics) в терминологии Kafka.
group_id – идентификатор группы подписчиков.
token_name – имя токена приложения. Необходимо сначала сгенерировать токен приложения в системе, а затем указать имя токена (name) в качестве значения параметра. Токен будет использоваться для авторизации при обработке входящих сообщений, которые коннектор забирает из Apache Kafka. Поскольку формат сообщений Kafka не дает возможности передать токен в самом сообщении, токен указывается в конфигурации коннектора.
enable_debug – режим отладки для Kafka:
- true – режим отладки включен. Значение true добавляет параметр debug: "all" в настройки соединения для Kafka. Если в логах не требуются все атрибуты, установите необходимое значение параметра debug в секции options.
- false (по умолчанию) – опция отключена.
options – опции библиотеки librdkafka:
- enable.auto.offset.store – значение true задает автоматическое обновление параметра смещения (autocommit). Значение по умолчанию: false.
- enable.partition.eof – значение true не выводит ошибку RD_KAFKA_RESP_ERR__PARTITION_EOF, если consumer доходит до конца сегмента. Значение по умолчанию: false.
- auto.offset.reset – смещение, используемое при отсутствии другого значения в памяти. Значение по умолчанию: earliest.
- statistics.interval.ms (integer) – интервал обновления метрик в миллисекундах. Значение по умолчанию: 15000. Диапазон доступных значений: 0–86400000. Значение 0 отключает сбор статистики.
- security.protocol – протокол для связи с брокерами. Возможные значения: plaintext, ssl, sasl_plaintext, sasl_ssl. Значение по умолчанию: plaintext.
- debug – выбор режима отладки. Возможные значения: generic, metadata, topic, cgrp, fetch, consumer, all. Значение по умолчанию: all.
workers_count – количество читателей сообщений (workers), которые будут работать на коннекторе. Значение по умолчанию: 10. Параметр может быть полезен для случая, когда нужно гарантированно сохранить порядок чтения входящих сообщений. Если читателей сообщений несколько, то будет идти параллельная обработка нескольких сообщений сразу, и их порядок может быть нарушен. Чтобы гарантировать сохранение порядка, необходимо в кластере оставить один connector и один input_processor и задать значение workers_count: 1.
logger – выбор режима для журнала событий:
- stderr (по умолчанию) – в логи TDG выводятся только сообщения об ошибках.
- tdg – в TDG отправляются все логи Kafka, включая сообщения об ошибках.

Для коннектора типа kafka в конфигурации можно задать более одного входящего коннектора.

Note

При подключении к Kafka в логах TDG выводятся input-параметры, с которым был создан consumer Kafka. В логах указаны значения для всех опций библиотеки librdkafka, в том числе выставленные по умолчанию. Отключить вывод логов нельзя.

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

tdg2                | 2023-03-02 16:17:19.810 [1] main/304/main I> [dcb31ae4-ca99-4b1c-995f-a0dd05194fa9] Kafka consumer for "kafka" input configuration: ---
tdg2                | ssl.engine.id: dynamic
tdg2                | socket.blocking.max.ms: '1000'
tdg2                | message.max.bytes: '1000000'
tdg2                | connections.max.idle.ms: '0'
tdg2                | enable_sasl_queue: 'false'
tdg2                | batch.size: '1000000'
...

Пример. Укажем коннектор типа kafka.

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

  - name: kafka-2
    type: kafka
    brokers:
      - localhost:9092
    topics:
      - orders-2
      - items-2
    group_id: kafka
    token_name: kafka_token
    function: connect_input_handle
    workers_count: 1

Особые параметры коннектора типа file¶

format – формат файла для чтения данных: csv или jsonl.
filename – имя файла для чтения данных.
workdir – директория для поиска файла.

Пример. Укажем коннектор типа file.

connector:
  input:
    - name: json_importer
      type: file
      format: jsonl
      filename: data.json
      routing_key: input_key
      workdir: .

Настройка output¶

output – параметры коннекторов для отправки исходящих запросов. У всех типов коннекторов есть общие параметры:

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

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

Особые параметры коннектора типа http¶

url – URL внешней системы, куда отправляется объект.
format – формат, в котором отправляется объект. Для коннектора типа http формат – всегда JSON.
options – опции параметра opts из встроенного модуля Tarantool http).

Пример. Укажем коннектор типа http.

connector:
    output:
        - name: to_external_http_service
          type: http
          url: http://localhost:8021
          format: json
          options:
            timeout: 5
            keepalive_idle: 60
            keepalive_interval: 60
            verify_host: true
            verify_peer: true
          headers:
            hello: world

Особые параметры коннектора типа soap¶

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

Пример. Укажем коннектор типа soap.

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

Особые параметры коннектора типа kafka¶

brokers – адреса (URL) брокеров сообщений.
topic – топик (topic) в терминологии Kafka.
format – формат, в котором отправляется сообщение в Kafka. Возможные значения: json и plain. Значение plain может применяться для случая, когда необходимо отправить в Kafka сообщение в формате XML. Значение по умолчанию: json.
options – опции библиотеки librdkafka:
- queue.buffering.max.ms (integer) – задержка в миллисекундах. Используется, чтобы дождаться, пока накопятся сообщения в очереди продюсера, прежде чем будут созданы пакеты сообщений для отправки брокерам. Значение по умолчанию: 5.
- statistics.interval.ms (integer) – интервал обновления метрик в миллисекундах. Значение по умолчанию: 15000. Диапазон доступных значений: 0–86400000. Значение 0 отключает сбор статистики.
- debug – выбор режима отладки. Возможные значения: generic, metadata, broker, topic, msg, all. Значение по умолчанию: all.
logger – выбор режима для журнала событий:
- stderr (по умолчанию) – в логи TDG выводятся только сообщения об ошибках.
- tdg – в TDG отправляются все логи Kafka, включая сообщения об ошибках.
set_key – генерация ключа UUID для отправляемого сообщения. Значение по умолчанию: true. При значении false ключ в исходящем сообщении будет пустым.

Note

При подключении к Kafka в логах TDG выводятся output-параметры, с которым был создан producer Kafka. В логах указаны значения для всех опций библиотеки librdkafka, в том числе выставленные по умолчанию. Отключить вывод логов нельзя.

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

tdg2                | 2023-03-02 16:17:19.821 [1] main/304/main I> [dcb31ae4-ca99-4b1c-995f-a0dd05194fa9] Kafka producer for "to_kafka" output configuration: ---
tdg2                | ssl.engine.id: dynamic
tdg2                | socket.blocking.max.ms: '1000'
tdg2                | message.max.bytes: '1000000'
tdg2                | connections.max.idle.ms: '0'
tdg2                | enable_sasl_queue: 'false'
tdg2                | batch.size: '1000000'
...

Пример. Укажем коннектор типа kafka.

connector:
  output:
    - name: to_kafka
      type: kafka
      brokers:
        - localhost:9092
      topic: objects
      options:
        debug: "all"
        queue.buffering.max.ms: 1
      is_async: true

Особые параметры коннектора типа smtp¶

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

Пример. Укажем коннектор типа smtp.

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¶

routing – маршрутизация объекта для отправки в систему, которая определяется в поле 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

Пример настройки бизнес-логики¶

connector:
  input:
    - name: http
      type: http
      routing_key: input_key

  output:
    - name: http_output
      type: http
      url: http://localhost:{HTTP_PORT}
      format: json
      headers:
        hello: world

    - name: invalid_http_output
      type: http
      url: http://localhost:8085
      format: json

    - name: soap_output
      type: soap
      url: http://localhost:{HTTP_PORT}
      headers:
        config_header: header_for_soap

input_processor:
  handlers:
    - key: input_key
      function: classifier.call

  storage:
    - key: test_object_1
      type: TestObject

    - key: test_object_2
      type: TestObject

    - key: test_object_3
      type: TestObject

    - key: soap_object
      type: TestObject

    - key: updatable_object
      type: UpdatableObject

    - key: object_with_entity
      type: ObjectWithEntity

    - key: bad_object
      type: BadObject

repair_queue:
  on_object_added:
    bad_object:
      postprocess_with_routing_key: bad_object_failed

    __unclassified__:
      postprocess_with_routing_key: unclassified

output_processor:
  test_object_1:
    handlers:
      - function: output_processor_handler.call
        outputs:
          - http_output

  test_object_2:
    handlers:
      - function: output_processor_handler.call
        outputs:
          - invalid_http_output

  test_object_3:
    handlers:
      - function: bad_output_processor_handler.call
        outputs:
          - invalid_http_output

  updatable_object:
    handlers:
      - function: output_processor_handler.call
        outputs:
          - http_output

  bad_object_failed:
    handlers:
      - function: output_processor_handler.call
        outputs:
          - http_output

  object_with_entity:
    handlers:
      - function: output_processor_handler.call
        outputs:
          - http_output

  soap_object:
    handlers:
      - function: soap_processor.call
        outputs:
          - soap_output

  unclassified:
    handlers:
      - function: output_processor_handler.call
        outputs:
          - http_output

Permissions¶

В Tarantool Data Grid используется основанная на ролях модель доступа к системным функциям и данным, хранящимся в системе. В этой главе подробно описываются профили доступа, которые можно назначать для создаваемых ролей, и связанные с этими профилями действия.

Access provider¶

Работа с настройками доступа:

Show LDAP configuration — просмотр конфигурации LDAP.
Update LDAP configuration — изменение конфигурации LDAP.

Audit Logs¶

Работа с журналом аудита:

Clear the audit log — очистка журнала аудита.
Enable the audit log — включение журнала аудита.
Set the lowest severity level for audit log messages — возможность установки минимального уровня важности событий для журнала аудита.
Show the audit log — просмотр журнала аудита.

Cartridge Actions¶

Работа с Cartridge:

Allow to bootstrap vshard — разрешить включение шардирования.
Allow to disable listed servers — разрешить отключение серверов из списка.
Allow to edit cluster topology server — разрешить изменять топологию кластера.
Allow to edit vshard options — разрешить изменять настройки шардирования.
Allow to modify auth parameters — разрешить изменять настройки аутентификации.
Allow to modify failover parameters — разрешить изменять настройки восстановления после сбоев.
Allow to probe server — разрешить проверять работоспособность сервера.
Allow to promote instance to the leader of replica set — разрешить повышать уровень экземпляра до лидера набора реплик.
Allow to reapply config on the specified nodes — разрешить повторное применение конфигурации к заданным узлам.
Allow to restart replication — разрешить перезапуск репликации.
Show cluster compression status — просмотр статуса сжатия для кластера.
Show cluster management suggestions — просмотр подсказок по управлению кластером.
Show cluster problems — просмотр проблемы возникших в кластере.
Show cluster servers — просмотр серверов входящих в кластер.
Show replica sets information — просмотр информации о наборах реплик.

Checks¶

Работа с различными проверками:

Check syntax of cron expression — проверка синтаксиса cron-выражений.
Check write permissions for directory — проверка разрешения на запись для директории.

Configuration¶

Работа с конфигурацией:

Apply configuration — применение конфигурации.
Change current configuration — изменение текущей конфигурации.
Change the settings of the password generator — изменение настроек создания паролей.
Check the input section in config — проверка входных данных в секции конфигурации.
Delete stored configurations from space — удаление сохраненных конфигураций из спейса.
Load sample configuration — загрузка примеров конфигурации.
Read default keep_version_count parameter for versioning — чтение значения по умолчанию параметра keep_version_count, используемого для версионирования.
Read TDG configuration — чтение конфигурации TDG.
Read the cache size for GraphQL queries — чтение размера кэша для запросов GraphQL.
Read the force yield limit — чтение лимита времени принудительной отдача контекста (yield).
Read the hard limits — чтение жестких лимитов (hard limits).
Read the input section in config — чтение входных данных в секции конфигурации.
Read the locked sections in config — чтение заблокированных секций в конфигурации.
Read the timeout for vshard requests — чтение таймаута для запросов шардирования.
Read time limit for inactive users and tokens in config — чтение лимита времени для неактивных пользователей и токенов в конфигурации.
Save TDG configuration — сохранение конфигурации TDG.
Set default keep_version_count parameter for versioning — установка значения по умолчанию параметра keep_version_count, используемого для версионирования.
Set the cache size for GraphQL queries — установка размера кэша для запросов GraphQL.
Set the force yield limit — установка лимита времени принудительной отдача контекста (yield).
Set the hard limits — установка жестких лимитов (hard limits).
Set the timeout for vshard requests — установка таймаута для запросов шардирования.
Show metrics configuration — просмотр конфигурации метрик.
Update metrics configuration — изменение конфигурации метрик.
Update the input section in config — изменение входных данных в секции конфигурации.
Update time limit for inactive users and tokens in config — изменение лимита времени для неактивных пользователей и токенов в конфигурации.
Write the locked sections in config — изменение заблокированных секций в конфигурации.

Data Actions Management¶

Управление профилями доступа:

Allow to create new data action — возможность создания нового профиля доступа.
Allow to delete data action — возможность удаления профиля доступа.
Allow to read data actions — возможность чтения профиля доступа.
Allow to update data action — возможность изменения профиля доступа.

Data Type Management¶

Работа с типами данных:

Allow to modify model and versioning configuration — возможность изменения модели и конфигурации версионирования.
Allow to read model and versioning configuration — возможность чтения модели и конфигурации версионирования.
Clean up expired data — удаление устаревших данных.

Jobs List¶

Работа с отложенными задачами:

Delete the job — удаление отложенной задачи.
Show all jobs — просмотр всех отложенных задач.
Try executing the job again — повторная попытка запуска отложенной задачи.

Logs¶

Работа с общим журналом событий:

Change configuration of logging — изменение конфигурации журнала событий.
Clear logs — очистка журнала событий.
Show logs — просмотр журнала событий.

Notifier¶

Управление уведомлениями:

Delete users subscribed to notifications — удаление пользователей подписанных на уведомления.
Show all users subscribed to notifications — просмотр пользователей подписанных на уведомления.
Show the mail servers for sending notifications — просмотр почтовых серверов для отправки уведомлений.
Specify a user subscribed to notifications — подписка пользователя на уведомления.
Specify the mail server for sending notifications — задание почтового сервера для отправки уведомлений.

Output Processor List¶

Управление обработчиком исходящих данных (output processor):

Delete tasks in the output processor — удаление задач из обработчика исходящих данных.
Restart post processing in the output processor — перезапуск постобработки обработчика исходящих данных.
Show all tasks sent to the output processor (state + history) — просмотр всех задач отправленных в обработчик исходящих данных.

Pages Access¶

Управление доступом к интерфейсу:

Show audit_log page — доступ к странице Audit log.
Show cluster page — доступ к странице Cluster.
Show configuration page — доступ к странице Configuration Files.
Show connectors configuration page — доступ к странице Connectors.
Show data types page — доступ к странице Data types.
Show doc page — доступ к странице Doc.
Show graphql page — доступ к странице Graphql.
Show logger page — доступ к странице Logger.
Show model page — доступ к странице Model.
Show repair pages — доступ к странице Repair Queues.
Show settings page — доступ к странице Settings.
Show tasks page — доступ к странице Tasks.
Show test page — доступ к странице Test.

Repair Queue¶

Работа с ремонтной очередью:

Delete objects in the repair queue — удаление объектов из ремонтной очереди.
Retry processing objects in the repair queue — повторение попытки обработки объектов из ремонтной очереди.
Show all objects in the repair queue — показать все объекты из ремонтной очереди.

Roles¶

Управление ролями доступа:

Change access-related roles — изменение ролей доступа.
Change settings for access-related roles — изменение настроек ролей доступа.
Create access-related roles — создание ролей доступа.
Delete access-related roles — удаление ролей доступа.
Read the role information — просмотр информации о роли доступа.
Show access-related actions — просмотр действий для роли доступа.
Show all access roles — просмотр всех доступных ролей доступа.
Show all actions allowed for the access-related role — просмотр всех действий доступных для роли доступа.

Services¶

Работа с сервисами:

Allow to run read services (query) — возможность запуска сервисов для запроса данных.
Allow to run write services (mutation) — возможность запуска сервисов для изменения данных.

Storage¶

Работа с хранилищем:

Delete spaces not linked from anywhere — удаление неиспользуемых спейсов.
Drop all spaces — удаление всех спейсов.
Remove data from spaces not linked from anywhere — удаление данных из неиспользуемых спейсов.
Show all aggregates — показывать все типы данных.
Show all spaces not linked from anywhere — просмотр всех неиспользуемых спейсов.
Show length of all storage spaces — просмотр размера всех спейсов в хранилище.

Tasks¶

Работа с задачами:

Delete the result of a task — удаление результата выполнения задачи.
Edit tasks config — изменение конфигурации задач.
Run the task — запуск задачи.
Show tasks config — просмотр конфигурации задач.
Show the tasks with statuses — просмотр задач с их статусами.
Stop the task — остановка задачи.

Tokens¶

Работа с токенами:

Change the token state — изменение состояния токена.
Create a new token — создание нового токена.
Delete the token — удаление токена.
Get the token — получение токена.
Import a token — импорт токена.
Show all tokens — просмотр всех токенов.
Update the token — обновление токена.

Users¶

Работа с пользователями:

Change the user's state — изменение состояния пользователя.
Create a new user — создание нового пользователя.
Delete the user — удаление пользователя.
Import a user — импорт пользователя.
Set user password — задание пользовательского пароля.
Show all users — просмотр всех пользователей.
Update user information — обновление информации о пользователе.

Sandbox API¶

В TDG пользовательский код выполняется в окружении sandbox, отдельно от собственного кода TDG. sandbox – изолированная среда (песочница) для исполнения кода, где используется JIT-компилятор LuaJIT. Sandbox API включает в себя:

модули и функции Lua и Tarantool;
функции, специфичные для TDG, предназначенные для доступа к данным, их обработке и других действий.

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

В sandbox недоступны некоторые функции или интерфейсы (например, библиотека ffi).

Все доступные модули и функции Sandbox API в этом справочнике разделены на группы по своей функциональности:

Repository API¶

Sandbox API включает в себя модуль repository – интерфейс репозитория TDG. Этот модуль предоставляет функции для работы с шардированным хранилищем. Функции позволяют выполнять следующие действия с данными:

операции выбора, вставки, изменения и удаления данных;
управление процессом обработки данных.

Все запросы к данным в TDG от внешних информационных систем, включая GraphQL-запросы (а также запросы, выполняемые во вкладке GraphQL), реализованы на основе функций программного интерфейса репозитория.

Доступные функции:

repository.find() – выборка по полям объектов одного типа, включая несколько условий;
repository.get() – выбор одного кортежа по индексу;
repository.put() – вставка нового или замена существующего объекта;
repository.put_batch() – вставка нового или замена существующего массива;
repository.update() – обновление объектов;
repository.update_batch() – вызов нескольких обновлений объектов в одном запросе;
repository.delete() – удаление объектов;
repository.count() – количество объектов, соответствующих заданному условию;
repository.pairs() – создание итератора;
repository.call_on_storage() – вызов функции на экземпляре с ролью storage для локальной обработки данных;
repository.call_on_storage_batch() – вызов нескольких функций на экземпляре с ролью storage;
repository.push_job() – отложенный запуск задач и функций;
repository.map_reduce() – сложная агрегация по кластеру.

Функции find(), update(), update-batch(), delete и count() поддерживают порядковую нумерацию страниц (пагинацию). Для этого используются параметры:

first и after – в функциях find() и count();
first_n_on_storage и after – в функциях update(), update_batch() и delete().

Все функции модуля, кроме call_on_storage() и push_job(), поддерживают версионирование – получение или обработку объектов, которые предшествуют или равны определённой версии.

Фильтрация объектов¶

Для выбора нужных объектов запросы применяют условия-предикаты, или фильтры. Предикаты указываются в параметре filter в формате булевых выражений.

Синтаксис предикатов¶

В запросах предикаты (filter) записываются в виде:

{{left, comparator, right}, ...}

где:

left – левая часть выражения. Содержит один из двух вариантов:
- полный путь к полю объекта (Customer.first_name);
- название индекса (id);
comparator – оператор сравнения: ">", ">=", "==", "<=", "<";
right – правая часть выражения. Содержит один из двух вариантов:
- полный путь к полю объекта (Customer.first_name);
- строковое значение, численное значение, булево значение или таблица.

Если в предикате несколько условий, по умолчанию они объединяются логической операцией and (конъюнкцией).

Примеры предикатов:

{{"id", ">", 10}}
{{"id", ">", 10}, {"id", "<", 100}}
{{"Customer.first_name", "==", "Ivan"}, {"birth_year", "==", 1990}}
{{"Customer.first_name", "==", "Ivan"}, {"reg_date", "==", {1990, 04, 23}}}

Как работают фильтры¶

Все условия-предикаты в параметре filter проверяются по очереди, чтобы определить основной фильтр для сканирования. Остальные фильтры используются как дополнительные условия при прохождении по индексу. При выборе основного фильтра соблюдается следующий порядок:

Если в списке условий есть фильтр по индексу, он используется в качестве основного и задает индекс для сканирования;
Если в запросе нет фильтра по индексу, проверяются фильтры по полю. Если при этом какое-то поле является первым в составном индексе, используется этот составной индекс.
Если нет ни одного подходящего индекса, идет полное сканирование спейса по первичному ключу.

При этом в версиях до 2.7.0 TDG использует ограничение на полное сканирование спейса (параметр scanned в секции hard-limits конфигурации). По умолчанию при выполнении запроса сканируются 2000 кортежей.

Начиная с версии 2.7.0, вместо ограничения scanned для hard-limits TDG использует механизм fiber.slice;
Если условие содержит операторы like или ilike, такое условие не может задавать индекс для сканирования.

Для примера определим модель данных с двумя типами объектов: Client и Passport:

[
    {
        "name": "Passport",
        "type": "record",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "passport_series", "type": "string"},
            {"name": "passport_number", "type": "string"},
            {"name": "expired_flag", "type": "boolean"}
        ],
        "indexes": [
            "id",
            {
                "name": "passport",
                "parts": ["passport_series", "passport_number"]
            }
        ]
    },
    {
        "name": "Client",
        "type": "record",
        "fields": [
            {"name": "id", "type": "long"},
            {"name": "first_name", "type": "string"},
            {"name": "last_name", "type": "string"},
            {"name": "passports", "type": {"type": "array", "items": "Passport"}}
        ],
        "indexes": ["id"]
    }
]

Пример 1

Запрос возвращает клиентов по имени Ivan с id больше 40:

repository.find(
  "Client",
  {{"first_name", "==", "Ivan"},
  {"id", ">", 40}})

В запросе указаны:

фильтр по индексу id – первичный ключ, по которому ведется сканирование;
фильтр по полю first_name – дополнительное условие поиска.

Пример 2

Запрос возвращает клиентов по имени Ivan, у которых первый паспорт имеет указанную серию:

repository.find(
  "Client",
  {{"first_name", "==", "Ivan"},
  {"passports.1.passport_series", "==", "012345"}})

В запросе указаны два фильтра по полю. При этом поле passport_series – часть составного индекса passport. Сканирование идет по индексу passport.

Пример 3

Запрос возвращает клиентов, у которых истек срок действия первого паспорта:

repository.find(
  "Client",
  {{"first_name", "==", "Ivan"}
  {"last_name", "==", "Petrov"},
  {"passports.1.expired_flag", "==", "false"}})

Среди условий нет подходящего индекса (в том числе составного), так что начинается полное сканирование по первичному ключу.

Оптимистичные блокировки¶

Внесение параллельных изменений из разных обработчиков в один и тот же объект может вызвать конфликты. Чтобы избежать конфликта, задайте один из двух параметров в аргументе запроса options:

only_if_version – механизм оптимистичных блокировок, основанный на версиях объектов. Запрос выполнится, только если данная версия объекта является последней и совпадает с заданной в запросе.
```
repository.put(
  "Client",
  {id = "42", first_name = "Ivan", last_name = "Petrov"},
  {version = 6, only_if_version = 5})
```
Запрос в примере выполняет поиск по первичному ключу id. Если объект с таким id найден, он обновляется, только если версия объекта в системе на момент исполнения совпадает со значением в параметре only_if_version. После успешного исполнения запроса последняя версия объекта станет равна 6.
if_not_exists – проверка на наличие дубликата объекта перед вставкой. Параметр доступен при вставке новых объектов (repository.put()) или массивов (repository.put_batch()), а также при подсчете количества объектов (repository.count()). Если задано значение true, система проверяет, существует ли уже такой объект. Если такого объекта еще нет, новый объект добавляется в хранилище.

Note

Параметры only_if_version и if_not_exists взаимоисключающие. При использовании параметров вместе в одном запросе система выдаст ошибку.

Справочник по Repository API¶

repository.find(type_name, filter[, options])¶

Возвращает объекты, соответствующие заданным условиям. Если тип объекта поддерживает версионирование, метод возвращает указанную версию объекта.

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
- first – количество возвращаемых элементов. Значение по умолчанию: 10;
- after – курсор пагинации на первый элемент;
- all_versions – поиск по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false;
- version – версия объекта, которая будет возвращена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметр all_versions, то обрабатываются все версии меньше или равные заданной;
- mode – целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;
- prefer_replica – целевой экземпляр для выполнения запроса. Возможные значения: true и false. Если задано true, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;
- balance – управление балансировкой нагрузки. Возможные значения: true и false. Если задано true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам.

Returns

таблица объектов, соответствующих заданным условиям

Return type

table

Пример

repository.find(
  "Client",
  {{"first_name", "==", "Ivan"},
  {"last_name", "==", "Petrov"}})

repository.get(type_name, pkey[, options])¶

Получает объект по первичному ключу. Если тип объекта поддерживает версионирование, метод возвращает указанную версию объекта.

Parameters

type_name (string) – тип объекта
pkey (any) – первичный ключ
options (table) –
параметры для управления запросом. Доступные параметры:
- version – версия объекта, которая будет получена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;
- mode – целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;
- prefer_replica – целевой экземпляр для выполнения запроса. По умолчанию: false. Если задано true, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;
- balance – управление балансировкой нагрузки. По умолчанию: false. Если задано true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам.

Returns

объект

Return type

table

Пример

repository.get("Client", 42)

repository.put(type_name, object[, options])¶

Вставляет новый или заменяет существующий объект. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод вставляет новую версию объекта или заменяет существующую.

Parameters

type_name (string) – тип объекта
object (table) – объект для вставки
options (table) –
параметры для управления запросом. Доступные параметры:
- version – версия объекта, которая будет добавлена или заменена. Параметр применяется только при включенном версионировании. Если параметр задан, заменяется указанная версия объекта. Если такой версии не существует, заменяется ближайшая предшествующая версия. Объект при этом сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и вставляет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;
- only_if_version – проверка имеющейся версии перед вставкой. Параметр применяется только при включенном версионировании. При указанном параметре запрос добавляет или заменяет объект, только если последняя версия объекта совпадает с указанной;
- if_not_exists – проверка имеющегося объекта перед вставкой. По умолчанию: false. Если задано значение true, система проверяет, существует ли уже такой объект в хранилище. Новый объект будет добавлен, если его еще нет в хранилище;
- skip_result – при значении true возвращает пустой массив, а не сами измененные объекты. По умолчанию: false.

Returns

измененный объект

Return type

table

Пример

Запрос добавляет объект с первичным ключом id:

repository.put("Client", {id = "42", first_name = "Ivan", last_name = "Petrov"})

Если версионирование отключено:

новый объект добавляется в хранилище;
объект c уже существующим id заменяет собой старый такой объект.

Если версионирование включено:

новый объект добавляется в хранилище, version равно последней версии;
для объекта c уже существующим id добавляется новая версия объекта.

repository.put_batch(type_name, array[, options])¶

Вставляет массив из новых объектов или заменяет существующие. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод вставляет новую версию объекта или заменяет существующую.

Parameters

type_name (string) – тип объекта
array (table) – массив объектов для вставки
options (table) –
параметры для управления запросом. Доступные параметры:
- version – версия объекта, которая будет добавлена или заменена. Параметр применяется только при включенном версионировании. Если параметр задан, заменяется указанная версия объекта. Если такой версии не существует, заменяется ближайшая предшествующая версия. Объект при этом сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и вставляет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;
- only_if_version – проверка имеющейся версии перед вставкой. Параметр применяется только при включенном версионировании. При указанном параметре запрос добавляет или заменяет объект, только если последняя версия объекта совпадает с указанной;
- if_not_exists – проверка имеющегося массива объектов перед вставкой. По умолчанию: false. Если задано значение true, система проверяет, существуют ли уже такие объекты в хранилище. Новые объекты будет добавлены, если их еще нет в хранилище;
- skip_result – при значении true возвращает пустой массив, а не сами измененные объекты. По умолчанию: false.

Returns

таблица с измененными объектами

Return type

table

Пример

Запрос вставляет массив объектов:

array = {}
batch_count = 1000
for i = 1, batch_count do
  array[i] = {id = tostring(i), old_field = tostring(i)}
end

repository.put_batch("Client", array)

Если версионирование отключено:

новые объекты добавляются в хранилище;
объекты c уже существующими id заменяют собой старые такие объекты.

Если версионирование включено:

новые объекты добавляются в хранилище, version равно последней версии;
для объектов c уже существующими id добавляются новые версии объектов.

repository.update(type_name, filter, updaters[, options])¶

Обновляет объекты, соответствующие заданным условиям. Запрос выполняется в две стадии:

исполнение запроса на каждом хранилище, которое может содержать объекты по условию в аргументе filter;
сбор результатов на роутере.

Если тип объекта поддерживает версионирование, метод сохраняет новую версию объекта или обновляет существующую.

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
updaters (table) –
список обновлений для объекта, состоящий из списка мутаторов {{mutator, path, new_value}, ...}, где:
- mutator – имя мутатора, например:
  - set – устанавливает значение;
  - add – увеличивает значение на указанное число;
  - sub – уменьшает значение на указанное число;
- path – строковый путь до поля объекта с точкой-разделителем (.). Путь до объекта(ов) массива должен включать индекс массива или символ * для захвата всех вложенных объектов;
- new_value – новое значение;
options (table) –
параметры для управления запросом. Доступные параметры:
- first_n_on_storage – количество возвращаемых элементов;
- after – курсор пагинации на первый элемент;
- version – версия объекта, которая будет изменена. Параметр применяется только при включенном версионировании. Если параметр задан, обновляется указанная версия объекта. Если такой версии не существует, обновляется ближайшая предшествующая версия. Объект обновляется, и результат сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и сохраняет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;
- only_if_version – проверка имеющейся версии перед обновлением. Параметр применяется только при включенном версионировании. При указанном параметре объект обновляется, только если последняя версия объекта совпадает с указанной;
- indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс;
- skip_result – при значении true возвращает пустой массив, а не сами обновленные объекты. По умолчанию: false.

Returns

таблица с обновленными объектами

Return type

table

Примеры

Запрос обновляет имя клиента с id = 42:

repository.update(
  "Client",
  {{"id", "==", 42}},
  {{"set", "first_name", "Ivan"},
  {"set", "last_name", "Petrov"}})

Если у клиента истек срок действия первого паспорта и необходимо обновить соответствующее поле expired_flag, можно использовать следующий запрос:

repository.update(
  "Client",
  {{"id", "==", 42}},
  {{"set", "passports.1.expired_flag", "true"}})

где .1. – индекс массива, содержащего экземпляры сущности Passport объекта Client, то есть первый паспорт клиента.

repository.update_batch(type_name, updates_list[, options])¶

Обновляет объекты, соответствующие заданным условиям. Вызывает несколько обновлений в одном запросе. Если тип объекта поддерживает версионирование, метод сохраняет новую версию объекта или обновляет существующую.

Parameters

type_name (string) – тип объекта
updates_list (table) –
список обновлений, которые необходимо применить. Для каждого обновления в списке задаются вложенные элементы:
- таблица, содержащая список условий-предикатов для выбора (фильтрации) объектов указанного типа;
- список мутаторов {{mutator, path, new_value}, ...} (список обновлений для объекта), где:
  - mutator – имя мутатора, например:
    - set – устанавливает значение;
    - add – увеличивает значение на указанное число;
    - sub – уменьшает значение на указанное число;
  - path – строковый путь до поля объекта с точкой-разделителем (.). Путь до объекта(ов) массива должен включать индекс массива или символ * для захвата всех вложенных объектов;
  - new_value – новое значение;
options (table) –
параметры для управления запросом. Доступные параметры:
- first_n_on_storage – количество возвращаемых элементов;
- after – курсор пагинации на первый элемент;
- version – версия объекта, которая будет изменена. Параметр применяется только при включенном версионировании. Если параметр задан, обновляется указанная версия объекта. Если такой версии не существует, обновляется ближайшая предшествующая версия. Объект обновляется, и результат сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и сохраняет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;
- only_if_version – проверка имеющейся версии перед обновлением. Параметр применяется только при включенном версионировании. При указанном параметре объект обновляется, только если последняя версия объекта совпадает с указанной;
- indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс;
- skip_result – при значении true возвращает пустой массив, а не сами обновленные объекты. По умолчанию: false.

Returns

таблица с обновленными объектами

Return type

table

Пример

Запрос обновляет имена клиентов с id = 40 и id = 41:

repository.update_batch(
  "Client", { {
  {{"id", "==", 40}},
  {{"set", "first_name", "Maria"},
  {"set", "last_name", "Ivanova"}},
  }, {
  {{"id", "==", 41}},
  {{"set", "first_name", "Anna"},
  {"set", "last_name", "Ivanova"}}
  } })

repository.delete(type_name, filter[, options])¶

Удаляет объекты, соответствующие заданным условиям. Поддерживает оптимистичные блокировки. Если тип объекта поддерживает версионирование, метод удаляет указанную версию объекта.

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
- first_n_on_storage – количество возвращаемых элементов;
- after – курсор пагинации на первый элемент;
- version – версия объекта для удаления. Параметр применяется только при включенном версионировании. Если параметр задан, удаляется указанная версия объекта. Если такой версии не существует, удаляется ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;
- only_if_version – проверка имеющейся версии перед удалением. Параметр применяется только при включенном версионировании. При указанном параметре объект удаляется, только если последняя версия объекта совпадает с указанной;
- indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс;
- skip_result – при значении true возвращает пустой массив, а не сами удаленные объекты. По умолчанию: false.

Returns

таблица с удаленными объектами

Return type

table

Пример

Запрос удаляет клиентов с заданной фамилией:

repository.delete(
  "Client",
  {{"last_name", "==", "Petrov"}})

В результате запроса все объекты, удовлетворяющие условию, дополняются новой версией (используется значение по умолчанию).

repository.count(type_name, filter[, options])¶

Вычисляет количество объектов, соответствующих заданным условиям. Если тип объекта поддерживает версионирование, метод обрабатывает указанную версию объекта.

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
- first – количество элементов. Значение по умолчанию: 10;
- after – курсор пагинации на первый элемент;
- version – версия объекта. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметр all_versions, то обрабатываются все версии меньше или равные заданной;
- all_versions – поиск по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false;
- only_if_version – проверка имеющейся версии перед обработкой. Параметр применяется только при включенном версионировании. При указанном параметре объект обрабатывается, только если последняя версия объекта совпадает с указанной;
- if_not_exists – проверка имеющегося объекта перед обработкой. По умолчанию: false. Если задано значение true, система проверяет, существует ли уже такой объект в хранилище;
- indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс;
- skip_result – при значении true возвращает пустой массив, а не сами обновленные объекты. По умолчанию: false.

Returns

количество объектов, соответствующих фильтру

Return type

number

repository.pairs(type_name, filter[, options])¶

Создает итератор. Используется для чтения большого объема данных. Сигнатура функции аналогична repository.find(), но в pairs() нет параметра first, пагинация применяется автоматически. Если тип объекта поддерживает версионирование, метод обрабатывает указанную версию объекта.

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
- after – курсор пагинации на первый элемент;
- version – версия объекта. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметр all_versions, то обрабатываются все версии меньше или равные заданной;
- all_versions – поиск по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false;
- mode – целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;
- prefer_replica – целевой экземпляр для выполнения запроса. По умолчанию: false. Если задано true, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;
- balance – управление балансировкой нагрузки. По умолчанию: false. Если задано true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам;
- timeout – время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout.

Returns

итератор

Пример

В примере таблица заполняется результатами вызова repository.pairs() и затем печатается:

local res = {}
for _, object in repository.pairs("Client",{{"first_name", "==", "Ivan"}}) do
    table.insert(res, object)
end
print(res)

repository.call_on_storage(type_name, index_name, value, func_name[, func_args, options])¶

Вызывает функцию на экземпляре с ролью storage. Файл с функцией должен храниться в директории src в корневой директории TDG.

Parameters

type_name (string) – тип объекта
index_name (string) – имя индекса
value (any) – значение ключа поиска
func_name (string) – имя вызываемой функции
func_args (table) – аргументы, которые передаются в вызываемую функцию
options (table) –
параметры для управления запросом. Доступные параметры:
- timeout – время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout;
- mode – целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;
- prefer_replica – целевой экземпляр для выполнения запроса. По умолчанию: false. Если задано true, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;
- balance – управление балансировкой нагрузки. По умолчанию: false. Если задано true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам.

Returns

результат выполнения функции

Return type

any

Пример

Запрос вызывает функцию on_storage.call для объекта с id = 42, в функцию переданы аргументы 2 и 4:

repository.call_on_storage('Data', 'id', '42', 'on_storage.call', {2, 4}, { timeout = 0.1 })

repository.call_on_storage_batch(type_name, arguments_list[, options])¶

Группирует и вызывает несколько функций на экземплярах с ролью storage. Файлы с функциями должны храниться в директории src в корневой директории TDG.

Parameters

type_name (string) – тип объекта
arguments_list (table) –
список (map) c парами key-value, где key – ключ с идентификатором вызова, а value – таблица из следующих элементов:
- имя индекса;
- значение индекса;
- имя вызываемой функции;
- таблица с аргументами, которые передаются в вызываемую функцию.
options (table) –
параметры для управления запросом. Доступные параметры:
- timeout – время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout;
- mode – целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;
- prefer_replica – целевой экземпляр для выполнения запроса. По умолчанию: false. Если задано true, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;
- balance – управление балансировкой нагрузки. По умолчанию: false. Если задано true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам.

Returns

результаты выполнения функций

Return type

table

Пример

Запрос вызывает функцию on_storage.call для объектов с id от 1 до 3, в функцию переданы аргументы fn_arg1 и fn_arg2:

repository.call_on_storage_batch(
  'Data', {
  {on_storage1 = {'id', '1', 'on_storage.call', {'fn_arg1', 'fn_arg2'}}},
  {on_storage2 = {'id', '2', 'on_storage.call', {'fn_arg1', 'fn_arg2'}}},
  {on_storage3 = {'id', '3', 'on_storage.call', {'fn_arg1', 'fn_arg2'}}}
  })

repository.push_job(name, args)¶

Асинхронный запуск задач и функций.

Parameters

name (string) – имя функции, определенное в файле конфигурации
args (table) – аргументы функции

Returns

true при успешном запуске задачи

Return type

boolean

repository.map_reduce(type_name, filter, map_fn_name, combine_fn_name, reduce_fn_name, options)¶

Запрос на обработку всех данных кластером по модели MapReduce. Выполняется на всех экземплярах типа storage. Состоит из трех этапов:

Map – выполняется на экземплярах с ролью storage;
Combine – выполняется на экземплярах с ролью storage;
Reduce — выполняется на экземпляре, где была вызвана функция map_reduce.

Если тип объекта поддерживает версионирование, метод обрабатывает указанную версию объекта.

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
map_fn_name (string) – указатель на функцию для этапа Map
combine_fn_name (string) – указатель на функцию для этапа Combine
reduce_fn_name (string) – указатель на функцию для этапа Reduce
options (table) –
параметры для управления запросом. Доступные параметры:
- map_args – дополнительные аргументы для этапа Map;
- combine_args – дополнительные аргументы для этапа Combine;
- combine_initial_state – исходное состояние для этапа Combine;
- reduce_args – дополнительные аргументы для этапа Reduce;
- reduce_initial_state — исходное состояние для этапа Reduce;
- version – версия объекта, которая будет обработана. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;
- mode – целевой экземпляр для выполнения запроса. Возможные значения: read и write. Если задано write, целью будет мастер;
- prefer_replica – целевой экземпляр для выполнения запроса. По умолчанию: false. Если задано true, то предпочитаемая цель – одна из реплик. Если доступной реплики нет, то целью будет мастер. Опция полезна для ресурсозатратных функций, чтобы избежать замедления работы мастера;
- balance – управление балансировкой нагрузки. По умолчанию: false. Если задано true, добавится балансировка нагрузки – запросы на чтение распределяются по всем узлам набора реплик по кругу. Если при этом параметр prefer_replica определен как true, предпочтение отдается репликам;
- timeout – время ожидания выполнения запроса, секунды. Значение не должно быть больше, чем значение параметра конфигурации vshard_timeout.

Returns

результат выполнения reduce_fn_name

Return type

any

Этап Map

На каждом экземпляре c ролью storage вызывается функция map_fn_name. Функция вызывается столько раз, сколько на этом экземпляре будет найдено объектов, соответствующих типу type_name и условиям filter. Функция map_fn_name применяется к каждому найденному кортежу.

local map_res, err = map_fn(tuple, options.map_args)

Функция может вернуть любые данные или nil. Если возвращены данные, на следующем этапе они будут использованы для запуска функции combine_fn_name. combine_fn_name будет вызвана столько раз, сколько раз вызовы Map вернут данные.

Этап Combine (опционально)

Нужен для уменьшения количества данных, полученных на стадии Map, перед их передачей по сети и дальнейшей обработкой. Результат каждого вызова map_fn_name передаётся в combine_fn_name. Далее каждый вызов combine_fn_name осуществляется с передачей исходного состояния, равного результату предыдущего вызова combine_fn_name. Для первого вызова исходное состояние равно combine_initial_state, либо равно пустой таблице, если этот параметр не задан.

local combine_res = options.combine_initial_state or {}
local combine_res, err = combine_fn_name(combine_res, map_res, options.combine_args)

Функция combine_fn также выполняется на роли storage.

Результат выполнения combine_fn накапливается в переменной combine_res и передается на ту роль, откуда был вызван map_reduce – в функцию reduce_fn_name.

Этап Reduce

Этап предназначен для завершения обработки данных со всего кластера. Данные передаются по сети на экземпляр, на котором была вызвана функция map_reduce. Там вызывается функция reduce_fn_name. Функция будет вызвана столько раз, сколько экземпляров типа storage в кластере найдут подходящие объекты и, соответственно, вернут результат в combine_res. Результат reduce_fn_name возвращается как результат всего map_reduce.

local reduce_res, err = reduce_fn_name(combine_res, options.reduce_initial_state, options.reduce_args)

Доступ к данным¶

Основные функции для доступа к данным в TDG входят в программный интерфейс репозитория. Кроме этого, для работы доступны следующие модули:

model_accessor – доступ к данным на экземпляре с ролью storage. Модуль включает в себя группы функций:
blob_storage – key-value хранилище на базе движка vinyl;
local_cache – локальный кэш;
shared_storage – распределенный кэш;
connector – работа с коннекторами;
odbc – работы с API ODBC.

model_accessor¶

Модуль model_accessor содержит функции для доступа к данным на экземпляре с ролью storage.

CRUD¶

Note

Все запросы ниже, за исключением put(), поддерживают параметр filter, позволяющий задать условия фильтрации объектов. Узнать больше об этом параметре можно в разделе Repository API.

model_accessor.count(type_name, filter[, options])¶

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

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
- first – количество элементов. Значение по умолчанию: 10;
- after – курсор пагинации на первый элемент;
- version – версия объекта. Параметр применяется только при включенном версионировании. Если параметр задан, обрабатывается указанная версия объекта. Если такой версии не существует, обрабатывается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметр all_versions, то обрабатываются все версии меньше или равные заданной;
- all_versions – поиск по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false;
- indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс.

Returns

количество записей, соответствующих фильтру

Return type

number

model_accessor.find(type_name, filter[, options])¶

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

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
- first – количество возвращаемых элементов. Значение по умолчанию: 10;
- after – курсор пагинации на первый элемент;
- all_versions – поиск по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false;
- version – версия объекта, которая будет возвращена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия. Если вместе с этим параметром задан параметр all_versions, то обрабатываются все версии меньше или равные заданной.

Returns

таблица объектов, соответствующих заданным условиям

Return type

table

model_accessor.get(type_name, filter[, options])¶

Parameters

type_name (string) – тип объекта
filter (table) – первичный ключ
options (table) –
параметры для управления запросом. Доступные параметры:
- first – количество возвращаемых элементов. Значение по умолчанию: 10;
- after – курсор пагинации на первый элемент;
- version – версия объекта, которая будет получена. Параметр применяется только при включенном версионировании. Если параметр задан, возвращается указанная версия объекта. Если такой версии не существует, возвращается ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;
- all_versions – указатель для поиска по всем версиям объекта, если задано значение true. Параметр применяется только при включенном версионировании. По умолчанию: false.

Returns

объект

Return type

table

model_accessor.delete(type_name, filter[, options])¶

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
options (table) –
параметры для управления запросом. Доступные параметры:
- first – количество возвращаемых элементов. Значение по умолчанию: 10;
- version – версия объекта для удаления. Параметр применяется только при включенном версионировании. Если параметр задан, удаляется указанная версия объекта. Если такой версии не существует, удаляется ближайшая предшествующая версия. Значение по умолчанию: последняя хранимая версия;
- only_if_version – проверка имеющейся версии перед удалением. Параметр применяется только при включенном версионировании. При указанном параметре объект удаляется, только если последняя версия объекта совпадает с указанной;
- indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс.

Returns

количество удаленных объектов

Return type

number

model_accessor.put(type_name, object[, options])¶

Parameters

type_name (string) – тип объекта
object (table) – объект для вставки
options (table) –
параметры для управления запросом. Доступные параметры:
- version – версия объекта, которая будет добавлена или заменена. Параметр применяется только при включенном версионировании. Если параметр задан, заменяется указанная версия объекта. Если такой версии не существует, заменяется ближайшая предшествующая версия. Объект при этом сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и вставляет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;
- only_if_version – проверка имеющейся версии перед вставкой. Параметр применяется только при включенном версионировании. При указанном параметре запрос добавляет или заменяет объект, только если последняя версия объекта совпадает с указанной;
- if_not_exists – проверка имеющегося объекта перед вставкой. По умолчанию: false. Если задано значение true, система проверяет, существует ли уже такой объект в хранилище. Новый объект будет добавлен, если его еще нет в хранилище.

Returns

количество измененных объектов

Return type

number

model_accessor.update(type_name, filter, updaters[, options])¶

Обновляет объекты, соответствующие заданным условиям. Если тип объекта поддерживает версионирование, метод сохраняет новую версию объекта или обновляет существующую.

Parameters

type_name (string) – тип объекта
filter (table) – список условий-предикатов для выбора (фильтрации) объектов указанного типа
updaters (table) –
список обновлений для объекта, состоящий из списка мутаторов {{mutator, path, new_value}, ...}, где:
- mutator – имя мутатора, например:
  - set – устанавливает значение;
  - add – увеличивает значение на указанное число;
  - sub – уменьшает значение на указанное число;
- path – строковый путь до поля объекта с точкой-разделителем (.). Путь до объекта(ов) массива должен включать индекс массива или символ * для захвата всех вложенных объектов;
- new_value – новое значение;
options (table) –
параметры для управления запросом. Доступные параметры:
- first – количество возвращаемых элементов. Значение по умолчанию: 10;
- version – версия объекта, которая будет изменена. Параметр применяется только при включенном версионировании. Если параметр задан, обновляется указанная версия объекта. Если такой версии не существует, обновляется ближайшая предшествующая версия. Объект обновляется, и результат сохраняется с той же версией. Если параметр не задан, запрос получает последнюю версию объекта и сохраняет новую версию объекта. Значение по умолчанию: целое монотонно возрастающее число;
- only_if_version – проверка имеющейся версии перед обновлением. Параметр применяется только при включенном версионировании. При указанном параметре объект обновляется, только если последняя версия объекта совпадает с указанной;
- indexed_by – индекс, по которому выполняется поиск. Используется, если необходимо явным образом указать индекс.

Returns

количество обновленных объектов

Return type

number

Управление транзакциями¶

model_accessor.begin_transaction()¶

Начинает транзакцию. Аналог функции box.begin().

Returns: none

model_accessor.commit_transaction()¶

Завершает транзакцию и сохраняет все изменения. Аналог функции box.commit().

Returns: none

model_accessor.rollback_transaction()¶

Завершает транзакцию без сохранения изменений. Аналог функции box.rollback().

Returns: none

model_accessor.is_in_transaction()¶

Проверяет наличие активной транзакции. Аналог функции box.is_in_txn().

Returns: true при наличии активной транзакции, иначе – false
Return type: boolean

Утилиты¶

model_accessor.unflatten(type_name, tuple)¶

Преобразует плоский кортеж в Lua-таблицу.

Parameters

type_name (string) – тип объекта
tuple (table/tuple) – кортеж, который требуется преобразовать

Returns

Lua-таблица

Return type

table

model_accessor.is_read_only()¶

Возвращает значение параметра box.info.ro – true или false.

Returns: true, если экземпляр находится в режиме read-only или в статусе orphan, иначе false.
Return type: boolean

model_accessor.snapshot()¶

Создает снимок всех данных и сохраняет его. Аналог функции box.snapshot

Returns: результат выполнения операции – ok, если снимок создан успешно
Return type: string

blob_storage¶

Модуль blob_storage содержит функции для работы с key-value хранилищем на базе движка vinyl.

blob_storage.new(namespace)¶

Создает новое key-value хранилище.

Parameters: namespace (string) – имя хранилища
Returns: указатель на созданное хранилище
Return type: table

local_cache¶

Модуль local_cache содержит функции для доступа к локальному кэшу. Локальный кэш представляет собой Lua-таблицу, с которой можно работать (добавлять и получать данные) в рамках одного экземпляра.

local_cache.set(key, val)¶

Задает в таблице пару ключ–значение.

Parameters

key (string) – ключ
val (any) – значение

Returns

none

local_cache.get(key)¶

Получает значение из таблицы по переданному ключу.

Parameters: key (string) – ключ
Returns: значение для переданного ключа
Return type: any

shared_storage¶

Модуль shared_storage содержит функции для работы с распределенным кэшем. Распределенный кэш можно использовать для передачи объектов между функциями и экземплярами TDG.

shared_storage.new(namespace)¶

Создает новый распределенный кэш.

Parameters: namespace (string) – имя хранилища
Returns: указатель на созданное хранилище
Return type: table

Note

При создании распределенного кэша создаётся спейс, хранящийся на одном из наборов реплик с ролью storage. Персистентность данных в распределенном кэше не гарантируется: данные из него могут быть потеряны, например, при перезапуске кластера.

Пример

Чтобы подключить существующий распределенный кэш или создать новый, используйте следующую команду:

local shared_storage_object = shared_storage.new('some_namespace')

Данные в распределенный кэш помещаются в формате key, value, например:

shared_storage_object:set('abc', 123)

где 'abc' – это ключ (key), а 123 – значение (value).

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

shared_storage_object:get('abc')

connector¶

Модуль connector содержит функции для отправки данных из sandbox в коннектор.

connector.send(output_name, obj[, output_options])¶

Направляет объект в секцию output для отправки в смежную систему.

Parameters

output_name (string) – имя коннектора
obj (object) – объект для отправки
output_options (table) – опции для отправки во внешнюю систему

Returns

true в случае успешной отправки, false в случае возникновения ошибки

Return type

boolean

odbc¶

Модуль odbc содержит функции для работы с API ODBC.

odbc.execute(connection_name, statement, params)¶

Выполняет запрос через ODBC c заданными параметрами.

Parameters

connection_name (string) – название соединения
statement (string) – выполняемый запрос
params (table) – параметры запроса

Returns

объект запроса

Return type

object

odbc.prepare(connection_name, query)¶

Подготавливает запрос через ODBC.

Parameters

connection_name (string) – название соединения
query (string) – запрос

Returns

объект подготовленного запроса

Return type

object

Преобразование данных¶

Доступные модули:

mapping_tools – работа со значениями объекта;
soap – конвертация XML-документов в объекты Lua и обратно;
json – конвертация JSON-строк в объект Lua и обратно;
yaml – конвертация YAML-строк в объект Lua и обратно;
msgpack – конвертация строк MsgPack в объекты Lua и обратно;
table – работа с таблицами в Lua;
decimal – вычисления с точными числами;
digest – кодирование и хеширование;
fun – библиотека Luafun для функционального программирования;
math – интерфейс стандартной математической библиотеки Lua;
string – работа со строками в Lua;
utf8 – обработка строк в кодировке UTF-8;
uuid – модуль для работы с UUID (универсальный уникальный идентификатор).

Помимо модулей, для работы доступна константа box.NULL (нулевой указатель) из встроенного Tarantool-модуля box.

mapping_tools¶

Модуль mapping_tools содержит функции для работы со значениями внутри объектов.

mapping_tools.get_by_path(obj, path[, delimiter])¶

Получает значение из объекта по его пути с заданным разделителем.

Parameters

obj (table) – объект
path (string) – путь к объекту
delimiter (string) – разделитель (. по умолчанию).

Returns

объект

Return type

table

mapping_tools.set_by_path(obj, path, value[, delimiter])¶

Присваивает значение объекту по его пути с заданным разделителем.

Parameters

obj (table) – объект
path (string) – путь к объекту
value (table) – значение объекта
delimiter (string) – разделитель (. по умолчанию).

Returns

none

mapping_tools.just_get_and_set(source_object, source_path, target_object, target_path)¶

Получает значение из одного объекта и присваивает его другому объекту.

Parameters

source_object (table) – исходный объект, из которого получают значение
source_path (string) – путь к исходному объекту
target_object (table) – целевой объект, которому передается значение исходного объекта
target_path (string) – путь к целевому объекту

Returns

none

soap¶

Модуль soap содержит функции для преобразования SOAP-запроса в формате XML в объекты Lua и обратно.

soap.encode(data)¶

Преобразует Lua-таблицу в строку с XML-документом.

Parameters: data (table) – Lua-таблица
Returns: XML-документ
Return type: string

soap.decode(doc)¶

Преобразует строку с XML-документом в объекты Lua.

Parameters

doc (string) – XML-документ

Returns

объекты Lua, полученные в результате парсинга XML.

строка, содержащая указатель на пространство имен (namespace);
строка с именем метода, переданного в SOAP-запросе (method);
Lua-таблица, которая содержит значения, переданные в тегах SOAP-запроса (entries).

Return type

string or table

json¶

Функции из модуля json для преобразования строки в формате JSON в объект Lua и обратно.

json.encode(lua_value[, configuration])¶

Преобразует объект Lua в строку в формате JSON.

Parameters

lua_value (table/scalar) – объект Lua
configuration – дополнительные опции конфигурации (см. функцию json.cfg())

Returns

JSON-строка

Return type

string

json.decode(string[, configuration])¶

Преобразует JSON-строку в объект Lua.

Parameters

string (string) – строка в формате JSON
configuration – дополнительные опции конфигурации (см. функцию json.cfg())

Returns

Lua-таблица

Return type

table

yaml¶

Функция из модуля yaml для преобразования строки в формате YAML в объект Lua.

yaml.encode(lua_value)¶

Преобразует объект Lua в строку в формате YAML.

Parameters: lua_value (table/scalar) – объект Lua
Returns: YAML-строка
Return type: string

table¶

Модуль table содержит функции для работы с таблицами в Lua. Информация о модуле table и доступных функциях приведена в справочнике по встроенным модулям. Кроме того, модуль расширен двумя дополнительными функциями:

cmpdeeply(got, expected)
append_table(where, from).

table.cmpdeeply(got, expected[, extra])¶

Сравнение двух таблиц с учетом вложенности.

Parameters

got (lua-value) – фактический результат
expected (lua-value) – ожидаемый результат
extra (table) – таблица, в которой сохраняется путь для различающихся элементов

Returns

результат сравнения, true или false

Return type

boolean

table.append_table(where, from)¶

Копирует один массив в конец другого массива. При этом используется неглубокое (shallow) копирование.

Parameters

where (table) – целевая таблица, в которую вставляют значения из первой таблицы
from (table) – таблица, значения которой добавляют в целевую таблицу

Returns

целевая таблица

Return type

table

Константа box.NULL¶

Константа box.NULL представляет собой нулевой указатель (NULL pointer). box.NULL позволяет хранить ключ без значения, в таблицах эта константа является местозаполнителем для значения nil. Имеет тип cdata. Чтобы узнать больше о box.NULL, обратитесь к соответствующему разделу справочника> в документации Tarantool.

Управление обработкой¶

Доступные модули и функции:

spawn – запуск файберов. Чтобы узнать больше о файберах, обратитесь к разделам Файберы и модулю fiber в документации Tarantool.
fiber.sleep() – передача управления другому файберу и переход в спящий режим;
request_context – получение контекста запроса.

spawn¶

Модуль spawn содержит функции для запуска файберов.

spawn.spawn(func_name, args, options)¶

Запускает один или несколько файберов для выполнения функции func_name с заданными аргументами.

Parameters

func_name (string) – имя функции
args (table) – аргументы функции
options (table) – дополнительные параметры, в которых можно указать время ожидания. Пример: spawn('my_func', {1, 2, 3}, {timeout = 30}).

Return type

table

spawn.spawn_n(func_name, func_num, options)¶

Запускает func_num количество файберов для выполнения функции func_name без аргументов.

Parameters

func_name (string) – имя функции
func_num (number) – количество запускаемых файберов
options (table) – дополнительные параметры, в которых можно указать время ожидания. Пример: spawn_n('my_func', 2, {timeout = 30}).

Returns

функция spawn()

fiber¶

Функция из модуля fiber.

fiber.sleep(time)¶

Передает управление другому файберу и переходит в режим ожидания на указанное количество секунд. Перевести в режим ожидания можно только текущий файбер.

Parameters: time (number) – количество секунд в режиме ожидания
Returns: none

request_context¶

request_context.get()¶

Returns: контекст запроса
Return type: table

Мониторинг¶

Доступные модули:

log – запись сообщений в журнал;
tracing – трассировка;
metrics – метрики.

log¶

Модуль log содержит функции для записи сообщений в журнал (по аналогии с модулем Tarantool log).

log.error(message)¶

log.warn(message)¶

log.info(message)¶

log.verbose(message)¶

log.debug(message)¶

Записывает сообщение в журнал с указанным уровнем детализации. Значение на выходе представляет собой строку в журнале, которая содержит:

текущую метку времени
название модуля
обозначения „E“, „W“, „I“, „V“ или „D“ – в зависимости от вызванной функции
содержимое аргумента message

Parameters

message (any) –

Сообщение в журнале. Аргумент message может содержать:

строку
спецификаторы формата %d or %s
таблицу
скалярный тип данных

Returns

nil

tracing¶

Модуль tracing содержит функцию трассировки.

tracing.start_span(name, ...)¶

Начинает span (основной блок трассировки в распределенных системах) и возвращает специальный объект. Для завершения трассировки выполнения функции используется метод finish возвращаемого объекта.

Parameters: name (string) – имя для span
Returns: object

metrics¶

Функции из модуля metrics. Узнать больше о метриках в TDG можно из раздела Мониторинг в руководстве администратора.

metrics.counter(name[, help, metainfo])¶

Регистрирует новый монотонно возрастающий счетчик.

Parameters

name (string) – имя счетчика
help (string) – описание счетчика
metainfo (table) – метаинформация счетчика

Returns

объект счетчика

Return type

counter_obj

metrics.gauge(name[, help, metainfo])¶

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

Parameters

name (string) – имя метрики типа gauge
help (string) – описание метрики типа gauge
metainfo (table) – метаинформация метрики типа gauge

Returns

объект gauge

Return type

gauge_obj

metrics.histogram(name[, help, metainfo])¶

Регистрирует новую гистограмму. Гистограмма – выборка из некоторого количества значений. Тип histogram подсчитывает полученные значения и объединяет их в настраиваемые бакеты (buckets).

Parameters

name (string) – имя гистограммы
help (string) – описание гистограммы
buckets (table) – бакеты гистограммы (массив сортированных неотрицательных чисел)
metainfo (table) – метаинформация гистограммы

Returns

объект гистограммы

Return type

histogram_obj

Работа с датами и временем¶

Доступные модули:

datetime – работа с датой и временем;
timezone – работа с часовыми поясами;
clock – значения времени, полученные из функции Posix / C CLOCK_GETTIME. Для работы доступны все функции модуля, за исключением функции clock.bench().

datetime¶

Модуль datetime содержит функции для работы с датой и временем. Помимо функций ниже, для работы также доступны функции из встроенного Tarantool-модуля datetime.

datetime.now()¶

Returns: текущее время по Гринвичу (GMT) в наносекундах
Return type: cdata

datetime.sec_to_iso_8601_date(sec)¶

Преобразует число секунд в строковое представление даты.

Parameters: sec (number) – число секунд
Returns: дата в формате ISO 8601 вида yyyy-MM-dd
Return type: string

datetime.nsec_to_iso_8601_date(nsec)¶

Преобразует число наносекунд в строковое представление даты.

Parameters: nsec (cdata) – число наносекунд
Returns: дата в формате ISO 8601 вида yyyy-MM-dd
Return type: string

datetime.nsec_to_iso_8601_datetime(nsec)¶

Преобразует число наносекунд в строковое представление даты и времени.

Parameters: nsec (cdata) – число наносекунд
Returns: дата и время в формате ISO 8601 вида yyyy-MM-ddTHH:mm:ss.SSSZ
Return type: string

datetime.nsec_to_iso_8601_time(nsec)¶

Преобразует заданную в наносекундах дату и время в строковое представление времени.

Parameters: nsec (cdata) – число наносекунд
Returns: время в формате ISO 8601 вида HH:mm:ss.SSS
Return type: string

datetime.nsec_to_day_of_week(nsec)¶

Возвращает день недели для заданной в наносекундах даты и времени.

Parameters: nsec (cdata) – число наносекунд
Returns: день недели в формате числа от 1 до 7, где 1 – воскресенье, а 7 – суббота
Return type: number

datetime.iso_8601_datetime_to_nsec(iso_8601_datetime)¶

Преобразует строковое представление даты и времени в наносекунды.

Parameters

iso_8601_datetime (string) –

дата и время в формате ISO 8601. Доступные форматы строки:

yyyy-MM-dd'T'HH:mm:ss.SSSZZZZZ
yyyy-MM-dd'T'HH:mm:ssZZZZZ
yyyy-MM-dd'T'HH:mm:ss
yyyy-MM-dd'T'HHmmss.SZZZZZ
yyyy-MM-dd'T'HHmmssZZZZZ
yyyy-MM-dd'T'HHmmss.SSS
yyyy-MM-dd'T'HHmmss

Returns

число наносекунд

Return type

cdata

datetime.iso_8601_date_to_nsec(iso_8601_date)¶

Преобразует строковое представление даты в наносекунды.

Parameters: iso_8601_date (string) – дата в формате ISO 8601 вида yyyy-MM-dd
Returns: число наносекунд
Return type: cdata

datetime.iso_8601_time_to_nsec(iso_8601_time)¶

Преобразует строковое представление времени в наносекунды.

Parameters: iso_8601_time (string) – время в формате ISO 8601. Доступные форматы: HH:mm:ss.SSS, HH:mm:ss.
Returns: число наносекунд
Return type: cdata

datetime.iso_8601_day_of_week_to_number(iso_8601_day_of_week)¶

Преобразует строковое представление дня недели в число от 1 до 7, где 1 – воскресенье, а 7 – суббота.

Parameters: iso_8601_day_of_week (string) – день недели в формате ISO 8601 (например, “Sunday”, “Sun”)
Returns: число от 1 до 7
Return type: number

datetime.custom_datetime_str_to_nsec(date_str, format_str)¶

Преобразует заданное шаблоном строковое представление даты или даты и времени в наносекунды.

Parameters

date_str (string) – дата или дата и времени
format_str (string) – шаблон строки

Returns

число наносекунд

Return type

cdata

datetime.millisec_to_formatted_datetime(datetime_millisec, datetime_format_str)¶

Преобразует миллисекунды в заданное шаблоном строковое представление даты и времени.

Parameters

datetime_millisec (number) – время в миллисекундах
datetime_format_str (string) – шаблон строки даты и времени

Returns

дата и время, заданные шаблоном

Return type

string

datetime.to_sec(nsec)¶

Преобразует наносекунды в секунды и приводит к типу number.

Parameters: nsec (cdata) – число наносекунд
Returns: число секунд
Return type: number

datetime.to_millisec(nsec)¶

Преобразует наносекунды в миллисекунды и приводит к типу number.

Parameters: nsec (cdata) – число наносекунд
Returns: число миллисекунд
Return type: number

datetime.seconds_since_midnight()¶

Returns: число секунд с начала суток по Гринвичу (GMT)
Return type: number

datetime.curr_date_nsec()¶

Метка времени (Unix timestamp) в наносекундах, соответствующая началу текущих суток UTC. Например, для времени и даты 01.01.2023 15:42 вернется метка, соответствующая 01.01.2023 00:00.

Returns: Unix timestamp в наносекундах
Return type: cdata

Набор констант, которые используются для работы со временем:

NSEC_IN_SEC – число наносекунд в секунде;
NSEC_IN_MILLISEC – число наносекунд в миллисекунде;
NSEC_IN_DAY – число наносекунд в сутках.

timezone¶

Модуль timezone содержит функции для работы с часовыми поясами.

timezone.now()¶

Returns: текущее время по Гринвичу (GMT) в наносекундах
Return type: cdata

timezone.seconds_since_midnight(timezone_id)¶

Parameters: timezone_id (string) – ID часового пояса
Returns: число секунд с начала текущих суток для указанного часового пояса
Return type: number

timezone.curr_date_nsec(timezone_id)¶

Метка времени (Unix timestamp) в наносекундах, соответствующая началу текущих местных суток для указанного часового пояса.

Parameters: timezone_id (string) – ID часового пояса
Returns: Unix timestamp в наносекундах
Return type: cdata

Работа с последовательностями¶

sequence – генератор уникальных возрастающих целых чисел. Уникальность чисел гарантируется в пределах отдельной последовательности с заданным именем даже при вызове из разных файберов или на разных экземплярах. Чтобы обеспечить уникальность при вызовах из разных экземпляров, используется роль core. Эта роль выделяет доступные диапазоны чисел. Новый диапазон чисел выделяется:

при первом обращении,
при исчерпании выданного ранее диапазона.

По умолчанию для экземпляров или файберов выделяются диапазоны по 100 номеров.

sequence¶

sequence.get(sequence_name)¶

Возвращает ссылку на объект заданной последовательности. Если последовательность с таким именем отсутствует, создаёт новую последовательность. Объект последовательности имеет единственный метод next, который возвращает следующий элемент последовательности.

Пример использования

На двух разных экземплярах один раз вызывается обработчик, заполняющий поле объекта уникальным номером с помощью метода next. Тогда на первом экземпляре номер объекта будет 1, а на втором – 101. Если после этого каждый обработчик вызывать еще 99 раз, то номера объектов будут 2–100 и 102–200 соответственно. При повторном запуске обработчика на первом экземпляре объекту будет присвоен номер 201.

Parameters: sequence_name – имя последовательности
Returns: ссылка на объект последовательности
Return type: table

Встроенные функции Lua¶

Помимо модулей, для работы доступны отдельные функции из библиотеки Lua:

assert() – вызов исключения, если значение аргумента содержит false;
error() – вызов исключения;
next() – вывод следующего элемента таблицы по индексу;
pairs() – итерации по парам ключ-значение (key-value) таблицы;
ipairs() – итерации по парам ключ-значение для числовых ключей;
pcall() – вызов функции в защищенном режиме;
xpcall() – вызов функции в защищенном режиме с указанием обработчика ошибки;
print() – печать в stdout;
select() – выборка аргументов функции или общее число переданных аргументов;
tonumber() – конвертация в число;
tonumber64() – конвертация в 64-битное число;
tostring() – конвертация в строку;
type() – определение типа данных у переданного аргумента;
unpack() – вывод элементов переданной таблицы.

assert(v[, message])¶

Вызывает исключение, если аргумент v содержит nil или false.

Parameters

v (boolean) – аргумент или условие, значение которого проверяется
message (string) – сообщение об ошибке. Значение по умолчанию: assertion failed!.

Returns

v, если аргумент содержит true;
сообщение об ошибке, если аргумент содержит false.

error(message[, level])¶

Завершает последнюю вызванную защищенную функцию и вызывает исключение. Обычно при этом в начало сообщения добавляется информация о месте возникновения ошибки.

Parameters

message (any) – сообщение об ошибке
level (number) –
место возникновения (уровень) ошибки. Возможные уровни:
- 0 – уровень ошибки не добавляется в сообщение;
- 1 (по умолчанию) – уровень ошибки в месте вызова функции error();
- 2 – уровень ошибки в месте вызова функции, которая вызвала функцию error().

Returns

none

next(t[, index])¶

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

Parameters

t (table) – таблица
index (number) – индекс элемента в таблице. Если аргумент t – таблица, а index – индекс элемента в в таблице, то next() возвращает индекс следующего после него элемента и связанное с ним значение. Если аргумент пропущен, он интерпретируется как nil. Если в аргументе index передан nil, функция возвращает начальный индекс и значение для него. Если передан индекс последнего элемента таблицы или таблица пустая, возвращается nil.

Returns

индекс элемента таблицы + связанное с ним значение или nil

pairs(t)¶

Позволяет выполнять итерации по парам ключ-значение (key-value) таблицы t.

Parameters

t (table) – таблица, по которой производится итерация

Returns

функция next()
таблица t
nil

ipairs(t)¶

Позволяет выполнять итерации по парам ключ-значение (key-value) таблицы t. Использует числовые ключи, другие ключи игнорируются.

Parameters

t (table) – таблица, по которой производится итерация

Returns

функция итерации
таблица t
nil

pcall(function_name, arg1, ···)¶

Вызывает функцию в защищенном режиме с заданными аргументами. pcall обрабатывает функцию и возвращает код состояния – true или false (boolean).

Parameters

function_name (string) – имя вызываемой функции
arg1 (any) – аргумент функции

Returns

true, если вызов функции был успешным;
false, если возникла ошибка.

Если ошибок нет, помимо статуса возвращаются все результаты вызова. Если ошибки есть, помимо статуса возвращается результат выполнения err.

xpcall(function_name, err, arg1, ...)¶

Как и pcall(), вызывает функцию в защищенном режиме с заданными аргументами, но еще позволяет установить новый обработчик ошибок err. xpcall обрабатывает функцию и возвращает код состояния – true или false (boolean). В случае возникновения ошибки вызывается обработчик err с исходным объектом ошибки и возвращает код состояния (boolean).

Parameters

function_name (string) – имя вызываемой функции
err (string) – обработчик ошибок
arg1 (any) – аргумент функции

Returns

true, если вызов функции был успешным;
false, если возникла ошибка.

print(...)¶

Принимает любое количество аргументов и печатает их значения в stdout. Для конвертации значений аргументов в строки используется функция tostring().

Returns: none

select(index, ...)¶

Возвращает значения аргументов функции или общее число переданных аргументов.

Parameters

index (string/number) – индекс, который содержит число или строку #
arg (any) – аргумент, переданный в функцию

Returns

все аргументы после аргумента с заданным индексом, если index – число;
общее количество переданных аргументов, если index – строка #.

tonumber(value)¶

Конвертирует заданное значение в число.

Parameters: value (string/number) – строка или Lua-число
Returns: конвертированное значение
Return type: number

tonumber64(value)¶

Конвертирует заданное значение в 64-битное целое число. Подробнее о функции tonumber64() можно прочитать в справочнике по встроенным модулям.

Parameters: value (string/number) – строка или Lua-число. На вход принимаются числа в десятичной, двоичной и шестнадцатеричной системах счисления. Если передать число с дробной частью (например, tonumber64('2.2')) в виде строки, функция вернет null.
Returns: конвертированное значение
Return type: number

tostring(value)¶

Конвертирует заданное значение в строку.

Parameters: value (any) – строка или Lua-число
Returns: конвертированное значение
Return type: string

type(value)¶

Определяет тип данных у переданного аргумента.

Parameters: value (any) – аргумент, тип которого требуется определить
Returns: тип данных в формате строки
Return type: string

unpack(list[, i, j])¶

Возвращает элементы для переданной таблицы. Если индексы элементов i и j пропущены, возвращает все элементы таблицы list.

Parameters

list (table) – таблица
i (number) – индекс первого возвращаемого элемента. Значение по умолчанию: 1.
j (number) – индекс последнего возвращаемого элемента. По умолчанию, j – общее количество элементов таблицы list (длина списка).

Returns

элементы таблицы

Расширения¶

Вы можете загрузить подключаемые функции, или расширения, в TDG вместе с конфигурацией приложения. Для этого поместите расширения в корень проекта в директорию extensions.

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

подключается модуль global.lua (при его наличии), который содержит глобальные изменения поведения приложения;
становятся доступны подключенные расширения в окружении sandbox.

Расширение global.lua¶

Модуль global.lua используется, чтобы задать в TDG глобальные изменения поведения, например, для настройки пользовательского HTTP-маршрута или функции IPROTO. Код из файла модуля запускается при обновлении конфигурации на всех экземплярах и выполняется вне окружения sandbox.

Чтобы добавить это расширение, выполните следующие действия:

В корневой директории TDG создайте директорию extensions.
Создайте файл модуля global.lua, напишите в нем необходимый код, а затем разместите файл в директории extensions. Модуль должен возвращать функцию init(), которая вызывается при применении конфигурации.
Упакуйте в zip-архив:
- папку extensions, внутри которой лежит файл модуля;
- файл конфигурации config.yml.
Загрузите архив в TDG согласно инструкции.

Подключение новых функций¶

Warning

Подключение новых функций в TDG может приводить к проблемам с безопасностью. Чтобы предупредить эти проблемы, рекомендуется:

самостоятельно проверять функции на уязвимости перед подключением;
включить режим обязательной аутентификации.

Чтобы подключить новые функции (расширения) к Sandbox API, выполните следующие действия:

В корневой директории TDG создайте директорию extensions/sandbox. На следующем шаге в нее будет добавлен модуль с подключаемыми функциями. Также нужно проследить, чтобы у пользователей были необходимые права для чтения данной директории.
Разместите в директории sandbox файл Lua-модуля, который вы хотите подключить. Модуль при этом должен возвращать объект с определяемыми модулем функциями. Кроме того, в добавленном модуле все используемые встроенные библиотеки должны быть явно подключены с использованием require(). Пример файла с Lua-модулем:
```
-- ./extensions/sandbox/csv.lua
-- По умолчанию в TDG не доступен модуль ``csv``

return require('csv')
```
Упакуйте в zip-архив:
- папку extensions/sandbox, внутри которой лежит файл модуля;
- файл конфигурации config.yml.
Загрузите архив в TDG согласно инструкции.

REST API¶

В этом справочнике содержатся сведения об адресах HTTP-ресурсов (endpoints) и параметрах запросов и ответов REST API TDG. Выполняя запросы к REST API, можно совершать операции с данными, вызывать сервисы и получать метрики для мониторинга.

Операции с данными

Операции с данными¶

TDG предоставляет следующие возможности работы с данными через REST API:

Чтение данных¶

Для чтения данных из TDG используются GET-запросы на адреса вида data/<TypeName>. В параметрах запроса передаются условия выборки объектов.

Такие запросы эквивалентны вызовам repository.find() c аналогичными аргументами.

Запрос¶

GET /data/<TypeName>?<arguments>

<TypeName> – имя типа данных из модели.
<arguments> – параметры запроса.

Запрос может содержать следующие параметры (все они являются опциональными):

`<index_name>`	Выборка по индексу `<index_name>` по полному совпадению с указанным значением. Например: `id=10`. При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index=0,10,true,null`.
`<index_name_gt>`	Выборка по индексу `<index_name>` с условием “больше указанного значения”. Например: `population_gt=100000` При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index_gt=0,10`
`<index_name_ge>`	Выборка по индексу `<index_name>` с условием “больше или равно указанного значения”. Например: `population_ge=100000` При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index_ge=0,10`
`<index_name_lt>`	Выборка по индексу `<index_name>` с условием “меньше указанного значения”. Например: `population_lt=100000` При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index_lt=0,10`
`<index_name_le>`	Выборка по индексу `<index_name>` с условием “меньше или равно указанного значения”. Например: `population_le=100000` При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index_le=0,10`
`<index_name_like>`	Выборка по строковому индексу `<index_name>` по шаблону. Например: `name=Abc%`
`<index_name_ilike>`	Выборка по строковому индексу `<index_name>` по шаблону без учёта регистра. Например: `name=abc%`
`indexed_by`	Имя индекса для упорядочивания объектов выборки. При передаче этого параметра объекты будут упорядочены по возрастанию значений указанного индекса. Обратите внимание, что параметр `indexed_by` применяется на этапе выборки объектов. Таким образом, запросы, отличающиеся только значением `indexed_by`, могут возвращать разные наборы объектов. Например, запрос с `indexed_by=price&first=5` вернёт 5 объектов с наименьшими значениями `price`, а запрос c `indexed_by=name&first=5` – 5 объектов с первыми значениями `name` в лексикографическом порядке.
`first`	Количество возвращаемых объектов. Значение по умолчанию: `10`.
`after`	Значение курсора первого возвращаемого объекта (поле `cursor` в возвращаемых объектах JSON). Значение по умолчанию: курсор первого добавленного объекта.
`version`	Запрашиваемая версия объектов для типов, поддерживающих версионирование. Значение по умолчанию: последняя хранимая версия. Номер версии также можно передать в HTTP-заголовке `version`.
`all_versions`	Флаг получения всех доступных версий объектов для типов, поддерживающих версионирование. Значение по умолчанию: `false`.

Note

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

Тело запроса для получения данных должно быть пустым.

Ответ¶

Набор объектов, удовлетворяющих заданным условиям, в формате JSON.

Пример¶

Запрос:

GET http://localhost:8081/data/City?population_ge=300000&indexed_by=title&first=3

Ответ:

[
    {
        "cursor": "gaRzY2FukqZCZXJsaW6nR2VybWFueQ",
        "country": "Germany",
        "title": "Berlin",
        "population": 3520031,
        "capital": true
    },
    {
        "cursor": "gaRzY2FukqdEcmVzZGVup0dlcm1hbnk",
        "country": "Germany",
        "title": "Dresden",
        "population": 547172,
        "capital": false
    },
    {
        "cursor": "gaRzY2FukqZNb3Njb3emUnVzc2lh",
        "country": "Russia",
        "title": "Moscow",
        "population": 12655050,
        "capital": true
    }
]

Вставка данных¶

Для вставки данных в TDG используются POST-запросы на адреса вида data/<TypeName>. Такие запросы эквивалентны вызовам repository.put c аналогичными аргументами.

Запрос¶

POST /data/<TypeName>?<arguments>

<TypeName> – имя типа данных из модели.
<arguments> – параметры запроса.

Запрос может содержать следующие параметры (все они являются опциональными):

version

Номер версии объекта для типов, поддерживающих версионирование. Значение по умолчанию: текущее значение временной метки Unix (Unix timestamp).

Номер версии также можно передать в HTTP-заголовке version.

only_if_version

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

skip_result

Флаг выполнения запроса без возврата вставленного объекта. Значение по умолчанию: false.

Тело запроса для вставки объекта должно содержать описание этого объекта в формате JSON.

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

Ответ¶

Если skip_result=false (по умолчанию): описание вставленного объекта в формате JSON.
Если skip_result=true: пустое тело ответа.

Пример¶

Запрос:

POST http://localhost:8081/data/City

{
    "population": 3520031,
    "title": "Berlin",
    "capital": true,
    "country":"Germany"
}

Ответ:

{
    "population": 3520031,
    "title": "Berlin",
    "capital": true,
    "country":"Germany"
}

Изменение данных¶

Для изменения данных в TDG используются PUT-запросы на адреса вида data/<TypeName>. В параметрах запроса передаются условия выборки объектов для изменения, а в теле – новые значения изменяемых полей.

Такие запросы эквивалентны вызовам repository.update c аналогичными аргументами.

Запрос¶

PUT /data/<TypeName>?<arguments>

<TypeName> – имя типа данных из модели.
<arguments> – параметры запроса.

Warning

Если в PUT-запросе нет ни одного условия выбора объектов (<index_name> или <index_name_*>), его результатом будет изменение всех объектов типа.

Запрос может содержать следующие параметры (все они являются опциональными):

`<index_name>`	Выборка по индексу `<index_name>` по полному совпадению с указанным значением. Например: `id=10`. При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index=0,10,true,null`.
`<index_name_gt>`	Выборка по индексу `<index_name>` с условием “больше указанного значения”. Например: `population_gt=100000` При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index_gt=0,10`
`<index_name_ge>`	Выборка по индексу `<index_name>` с условием “больше или равно указанного значения”. Например: `population_ge=100000` При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index_ge=0,10`
`<index_name_lt>`	Выборка по индексу `<index_name>` с условием “меньше указанного значения”. Например: `population_lt=100000` При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index_lt=0,10`
`<index_name_le>`	Выборка по индексу `<index_name>` с условием “меньше или равно указанного значения”. Например: `population_le=100000` При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index_le=0,10`
`<index_name_like>`	Выборка по строковому индексу `<index_name>` по шаблону. Например: `name=Abc%`
`<index_name_ilike>`	Выборка по строковому индексу `<index_name>` по шаблону без учёта регистра. Например: `name=abc%`
`indexed_by`	Имя индекса для упорядочивания объектов выборки. При передаче этого параметра объекты будут упорядочены по возрастанию значений указанного индекса.
`version`	Номер версии объекта для типов, поддерживающих версионирование. Значение по умолчанию: текущее значение временной метки Unix (Unix timestamp). Номер версии также можно передать в HTTP-заголовке `version`.
`only_if_version`	Для типов, поддерживающих версионирование: выполнить изменение, только если номер актуальной версии объекта равен указанному значению. Значение по умолчанию: последняя хранимая версия.
`skip_result`	Флаг выполнения запроса без возврата списка изменённых объектов. Значение по умолчанию: `false`.

Тело запроса для изменения данных должно содержать новые значения изменяемых полей в формате JSON.

Ответ¶

Если skip_result=false (по умолчанию): описание изменённого объекта в формате JSON.
Если skip_result=true: пустое тело ответа.

Пример¶

Запрос:

POST http://localhost:8081/data/City?population_le=500000

{
    "capital": false
}

Ответ:

[
    {
        "country": "Germany",
        "title": "Bonn",
        "population": 318809,
        "capital": false
    },
    {
        "country": "Germany",
        "title": "Karlsruhe",
        "population": 307755,
        "capital": false
    },
    {
        "country": "Russia",
        "title": "Tver",
        "population": 424969,
        "capital": false
    }
]

Удаление данных¶

Для удаления данных из TDG используются DELETE-запросы на адреса вида data/<TypeName>. В параметрах запроса передаются условия выборки объектов для удаления.

Такие запросы эквивалентны вызовам repository.delete c аналогичными аргументами.

Запрос¶

DELETE /data/<TypeName>?<arguments>

<TypeName> – имя типа данных из модели.
<arguments> – параметры запроса.

Warning

Если в DELETE-запросе нет ни одного условия выбора объектов (<index_name> или <index_name_*>), его результатом будет удаление всех объектов типа.

Запрос может содержать следующие параметры (все они являются опциональными):

`<index_name>`	Выборка по индексу `<index_name>` по полному совпадению с указанным значением. Например: `id=10`. При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index=0,10,true,null`.
`<index_name_gt>`	Выборка по индексу `<index_name>` с условием “больше указанного значения”. Например: `population_gt=100000` При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index_gt=0,10`
`<index_name_ge>`	Выборка по индексу `<index_name>` с условием “больше или равно указанного значения”. Например: `population_ge=100000` При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index_ge=0,10`
`<index_name_lt>`	Выборка по индексу `<index_name>` с условием “меньше указанного значения”. Например: `population_lt=100000` При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index_lt=0,10`
`<index_name_le>`	Выборка по индексу `<index_name>` с условием “меньше или равно указанного значения”. Например: `population_le=100000` При использовании составных индексов указывайте значения полей через запятую. Например: `multipart_index_le=0,10`
`<index_name_like>`	Выборка по строковому индексу `<index_name>` по шаблону. Например: `name=Abc%`
`<index_name_ilike>`	Выборка по строковому индексу `<index_name>` по шаблону без учёта регистра. Например: `name=abc%`
`indexed_by`	Имя индекса для упорядочивания объектов выборки. При передаче этого параметра объекты будут упорядочены по возрастанию значений указанного индекса.
`version`	Удаляемая версия объектов для типов, поддерживающих версионирование. Значение по умолчанию: последняя хранимая версия.
`all_versions`	Флаг удаления всех доступных версий объектов для типов, поддерживающих версионирование. Значение по умолчанию: `false`.
`skip_result`	Флаг выполнения запроса без возврата списка удаляемых объектов. Значение по умолчанию: `false`.

Note

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

Тело запроса для удаления данных должно быть пустым.

Ответ¶

Если skip_result=false (по умолчанию): набор объектов, удалённых из хранилища в результате выполнения запроса, в формате JSON.
Если skip_result=true: пустое тело ответа.

Пример¶

Запрос:

DELETE http://localhost:8081/data/City?population_ge=300000

Ответ:

[
    {
        "cursor": "gaRzY2FukqZCZXJsaW6nR2VybWFueQ",
        "country": "Germany",
        "title": "Berlin",
        "population": 3520031,
        "capital": true
    },
    {
        "cursor": "gaRzY2FukqdEcmVzZGVup0dlcm1hbnk",
        "country": "Germany",
        "title": "Dresden",
        "population": 547172,
        "capital": false
    },
    {
        "cursor": "gaRzY2FukqZNb3Njb3emUnVzc2lh",
        "country": "Russia",
        "title": "Moscow",
        "population": 12655050,
        "capital": true
    }
]

Вызов сервисов¶

TDG предоставляет REST API для вызова сервисов, развёрнутых в кластере. Для вызова сервисов используются POST-запросы на адреса вида /service/<service_name>. Аргументы для вызова передаются в параметрах запроса или в виде JSON в теле запроса.

Запрос¶

POST /service/<service_name>?<arguments>

<service_name> – имя сервиса.
<arguments> – аргументы вызова сервиса.

Аргументы вызова сервиса можно передавать двумя способами:

в параметрах запроса: <name>=<value>
в теле запроса в формате JSON:
```
{
  "name":"value"
}
```

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

Если аргумент может принимать значение null, его можно не передавать.

Ответ¶

Возвращаемое значение сервиса в формате JSON.

Пример¶

Запрос:

POST http://localhost:8081/service/say_hello?name=world&times=2

Ответ:

{
    "result": "Hello, world! Hello, world!"
}

Получение метрик кластера¶

Для получения метрик кластера TDG используются GET-запросы на адрес metrics. TDG возвращает метрики в формате Prometheus. Это позволяет в дальнейшем использовать их, например, для визуализации в Grafana.

Запрос¶

GET /metrics

Тело запроса для получения метрик должно быть пустым.

Ответ¶

Текущие значения метрик кластера TDG в формате Prometheus.

Пример¶

Запрос:

GET http://localhost:8081/metrics

Фрагмент ответа:

# HELP tdg_kafka_broker_int_latency_min Kafka: Smallest value of internal producer queue latency in microseconds
# TYPE tdg_kafka_broker_int_latency_min gauge
# HELP lj_gc_freed Total amount of freed memory
# TYPE lj_gc_freed counter
lj_gc_freed{alias="app-01"} 96399741997
# HELP tdg_kafka_eos_producer_id Kafka: The currently assigned Producer ID (or -1)
# TYPE tdg_kafka_eos_producer_id gauge
# HELP tdg_kafka_simple_cnt Kafka: Internal tracking of legacy vs new consumer API state
# TYPE tdg_kafka_simple_cnt gauge
# HELP tnt_cpu_user_time CPU user time usage
# TYPE tnt_cpu_user_time gauge
tnt_cpu_user_time{alias="app-01"} 1868.676635
# HELP tnt_slab_quota_used_ratio Slab quota_used_ratio info
# TYPE tnt_slab_quota_used_ratio gauge
tnt_slab_quota_used_ratio{alias="app-01"} 12.5
# HELP tnt_cpu_number The number of processors
# TYPE tnt_cpu_number gauge
tnt_cpu_number{alias="app-01"} 1
...

Управление настройками через GraphQL API¶

Этот раздел посвящен различным запросам, позволяющим просматривать и изменять настройки TDG.

Все запросы на просмотр и изменение настроек TDG передаются по протоколу HTTP в формате GraphQL. При этом они должны иметь соответствующий заголовок для авторизации.

Note

Для выполнения GraphQL-запросов можно использовать встроенный веб-клиент GraphiQL (на вкладке Graphql веб-интерфейса) или любой сторонний GraphQL-клиент, либо иное средство для отправки HTTP-запросов. При этом специализированные GraphQL-клиенты, в отличие от средств отправки HTTP-запросов, могут использовать функции автодополнения и проверки синтаксиса запросов, а также автоматического формирования документации на GraphQL API. Данные стандартные возможности GraphQL позволяют определять состав функций API, а также состав аргументов функций, типы исходных данных и возвращаемых результатов.

GraphQL-запросы от клиентов (за исключением встроенного веб клиента GraphiQL) необходимо направлять на соответствующие адреса (endpoints):

/graphql (без указания схемы или с указанием в заголовке схемы default) – используется для запросов к пользовательским данным, хранящимся в TDG. Подробнее смотрите Раздел про GraphQL-запросы к данным.
/graphql (с указанием в заголовке схемы admin) – используется для основных настроек TDG.
/admin/api – используется для изменения топологии кластера и других настроек Tarantool Cartridge.

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

Основные настройки TDG¶

Для выполнения запроса направьте его по протоколу HTTP на HTTP-порт экземпляра кластера с ролью connector с указанием адреса ресурса (endpoint) /graphql и заголовком admin, а также данными авторизации.

Пример выполнения запроса при помощи утилиты curl:

curl --request POST \
  --url http://172.19.0.2:8080/graphql \
  --header 'Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d' \
  --header 'schema: admin' \
  --data '{"query":"query{  user{  list{  username  }  }  }  "}'

Далее приведены все типы запросов на чтение или изменение основных настроек TDG. Для некоторых запросов дополнительно указаны возвращаемые значения и пояснения к ним.

Запросы на получение информации по текущим настройкам и состоянию (query)¶

Пример запроса на получение названия роли по ее id (access_role.get):

query {
    access_role {
        get(id: 1) {
            name
        }
    }
}

query.jobs¶

Чтение ремонтной очереди неудавшихся отложенных работ (попытка выполнения которых закончилась неудачно, вкладка Failed jobs):

get_list – возвращает список объектов ремонтной очереди отложенных работ.

query.repair_list¶: Возвращает список объектов, находящихся в ремонтной очереди (вкладка Repair).

query.tasks¶

Чтение списка задач:

get_list – возвращает список задач и результатов их исполнения.

query.password_generator¶

Генерация и проверка валидности паролей, чтение настроек требований к сложности паролей:

generate – возвращает сгенерированный пароль.
validate – выполняет проверку переданного пароля на соответствие имеющимся требованиям к сложности пароля.
config – возвращает текущие настройки требований к сложности пароля.

query.output_processor¶

Чтение данных ремонтной очереди объектов на отправку (вкладка Output Processor):

get_list – возвращает список объектов в ремонтной очереди на отправку (объекты, отправка которых не удалась).

query.access_role¶

Чтение настроек ролевой модели:

actions_list – возвращает список всех возможных действий, доступ к которым настраивается при помощи ролевой модели.
get_access_role_actions – возвращает список действий, доступных для роли по ее id.
list – возвращает список ролей.
get – возвращает данные о роли по ее id.

query.cartridge¶

Чтение данных из конфигурации:

test_soap_data – возвращает текст подсказки по умолчанию на вкладке Test веб-интерфейса.
self – отображает информацию о текущем сервере (экземпляре TDG).

query.data_access_action¶

Чтение информации о шаблонах доступа к действиям над данными:

list – возвращает список настроенных шаблонов доступа.
get – возвращает информацию о шаблоне по его id.

query.user¶

Чтение информации о пользователях и настройке доступа анонимных пользователей:

is_anonymous_allowed – возвращает статус настройки, разрешающей доступ без авторизации.
self – возвращает информацию о текущем пользователе.
list – возвращает список пользователей.

query.notifier_get_users¶: Возвращает список подписчиков (вкладка Subscribers).

query.audit_log¶

Чтение данных о журнале событий безопасности:

get – возвращает журнал событий безопасности (аудит лог).
enabled – возвращает статус настройки, отвечающей за включение и отключение ведения журнала аудита.

query.maintenance¶

Чтение служебной информации:

clock_delta – данные по рассинхронизации времени на внутренних (системных) часах экземпляров. Может возвращать следующие значения:
- value – возвращает максимальное текущее значение отклонения часов между экземплярами кластера.
- is_threshold_exceeded – отвечает на вопрос, превышено ли предельное значение отклонения часов среди экземпляров кластера.
get_aggregates – возвращает список агрегатов модели данных.
current_tdg_version – проверяет версию TDG при применении конфигурации (только в схеме admin).
unlinked_space_list – возвращает список агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные.

query.token¶

Чтение информации о токенах приложений:

list – выводит список всех токенов приложений.
get – выводит информацию о токене по его имени. В запрос передается единственный аргумент name – имя токена.

query.get_mail_server¶: Возвращает настройки почтового сервера для отправки оповещений.

query.config¶

Чтение настроек кластера:

vshard-timeout – возвращает таймаут выполнения удаленного вызова для операции модуля Tarantool vshard.
force_yield_limits – возвращает количество чтений записей спейса, после которых происходит принудительная передача управления (yield) для обеспечения кооперативной многозадачности.
hard_limits – возвращает текущие настройки ограничений при выполнении GraphQL-запросов. Может возвращать следующие значения:
- scanned – ограничение числа записей в спейсах, которые могут быть прочитаны для выполнения запроса.
- returned – ограничение числа записей, которые могут быть возвращены в ответе на запрос.
graphql_query_cache_size – возвращает ограничение количества кэшируемых уникальных GraphQL-запросов. Кэшируется только текст запроса, но не переменные.
locked_sections_list – Список закрепленных секций. Если в список закрепленных секций добавить любую секцию, например, секцию metrics, а потом загрузить новый файл конфигурации, в котором секции metrics не будет, то эта секция не удалится – вместо нее будет использована последняя загруженная версия секции metrics. Прописать закрепленные секции в файле конфигурации явным образом нельзя.

query.account_provider¶

Управление доступом:

ldap – возвращает конфигурацию LDAP.

query.checks¶

Валидация различных настроек:

cron_syntax – проверяет корректность синтаксиса заданного cron-выражения.
storage_dir_writable – проверяет возможность записи в заданную директорию.

query.data_type¶

Доступ к текущей модели данных:

model – возвращает текущую модель данных.
expiration – возвращает настройки устаревания данных.
versioning – возвращает параметры версионирования модели данных.

query.logs¶

Доступ к общему журналу событий:

get – возвращает записи общего журнала событий (логи).
config – возвращает конфигурацию журнала событий.

query.metrics¶

Доступа к метрикам:

config – возвращает настройки метрик.

query.migration¶

Управление миграцией данных:

stats – возвращает ход выполнения миграции данных.

query.settings¶

Настройки учетной записи:

get – возвращает настройки учетной записи.

Запросы на внесение изменений в настройки (mutation)¶

Пример запроса на изменение настроек требований к сложности паролей пользователей (password_generator.config):

mutation {
    password_generator {
        config(lower: true, digits: true, symbols: false, min_length: 6)
    }
}

mutation.jobs¶

Работа с ремонтной очередью неудавшихся отложенных работ (попытка выполнения которых закончилась неудачно, вкладка Failed jobs):

delete_all_jobs – удалить все отложенные работы из ремонтной очереди отложенных работ.
try_again_all – выполнить повторную попытку обработки всех отложенных работ из ремонтной очереди отложенных работ.
try_again – выполнить повторную попытку обработки неудавшейся отложенной работы по ее id.
delete_job – удалить неудавшуюся отложенную работу по ее id.

mutation.token¶

Работа с токенами приложений:

remove – удалить токен приложения по его имени. В запрос передается единственный аргумент name – имя токена.
import – импортировать токен приложения. Возможные аргументы:
- state_reason (опционально) – пояснение к присвоению текущего статуса.
- expires_in – ограничение времени действия токена в секундах. Значение 0 означает неограниченный срок действия.
- uid – внутренний ID токена.
- role – имя роли из ролевой модели доступа.
- state – статус (active/blocked).
- created_at – дата и время создания в формате Unix time.
- name – имя токена.
- last_login (опционально) – дата и время последнего входа в формате Unix time.
- unblocked_at (опционально) – дата и время последней разблокировки в формате Unix time.
add – добавить новый токен приложения. Возможные аргументы:
- expires_in – ограничение времени действия токена в секундах. Значение 0 означает неограниченный срок действия.
- name – имя токена.
- role – имя роли из ролевой модели доступа.
update – отредактировать данные токена приложения (срок действия или роль). Возможные аргументы:
- expires_in – ограничение времени действия токена в секундах. Значение 0 означает неограниченный срок действия.
- name – имя токена.
- role – имя роли из ролевой модели доступа.
set_state – изменить статус токена приложения (заблокировать или разблокировать). Возможные аргументы:
- state – статус (active/blocked/new).
- reason (опционально) – пояснение к присвоению нового статуса.
- name – имя токена.

mutation.notifier_upsert_user¶

Добавление нового или редактирование существующего адреса для оповещения (вкладка Subscribers). Возможные аргументы:

name – имя контакта для оповещения.
addr – адрес электронной почты.
id – внутренний идентификатор (строка).

mutation.clear_repair_queue¶: Очистить ремонтную очередь (вкладка Repair).

mutation.password_generator¶: Изменение настроек требований к сложности паролей пользователей.

mutation.output_processor¶

Работа с ремонтной очередью на отправку (вкладка Output processor):

clear_list – удалить все объекты на отправку из ремонтной очереди.
try_again_all – выполнить повторную попытку обработки всех объектов на отправку из ремонтной очереди.
try_again – выполнить повторную попытку обработки объекта на отправку из ремонтной очереди по его id.
delete_from_list – удалить объект на отправку из ремонтной очереди по его id.

mutation.access_role¶

Управление настройками ролевой модели:

delete – удаление роли пользователя по ее id.
create – создание новой роли пользователя. Возможные аргументы:
- name – имя новой роли.
- description (опционально) – описание новой роли.
update – изменение имени или описания роли пользователя.
update_access_role_actions – изменение прав доступа для роли. Возможные аргументы:
- id – идентификатор роли.
- actions – список изменяемых прав:
  - id – идентификатор права.
  - allowed – данные о наличии права для роли (Boolean).

mutation.set_mail_server¶

Изменение настроек почтового сервера для отправки оповещений (см. Подробнее про модуль SMTP). Возможные аргументы:

username – имя учетной записи, с которой будет проводиться рассылка.
password – пароль от учетной записи.
url – адрес почтового сервера.
from – адрес, указываемый в поле отправителя сообщения.
skip_verify_host – при установке true позволяет пропускать проверку валидности сертификата хоста.
timeout – таймаут отправки.

mutation.cartridge¶

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

load_config_example – загружает тестовый пример конфигурации вместо имеющейся конфигурации.

mutation.data_access_action¶

Внесение изменений в шаблоны доступа к действиям над данным:

delete – удалить шаблон.
create – добавить новый шаблон.
update – отредактировать существующий шаблон.

mutation.user¶

Управление пользователями:

import – импорт пользователя.
add – добавление нового пользователя.
remove – удаление существующего пользователя по его uid.
modify – редактирование существующего пользователя по его uid.
self_modify – редактирование пароля или имени учетной записи для текущего пользователя (из-под которого выполняется GraphQL-запрос).
set_state – блокирование или разблокирование пользователя.
reset_password – сброс пароля пользователя по его uid.

mutation.tasks¶

Управление задачами:

start – запуск задачи по ее id.
stop – остановка задачи по ее id.
forget – удаляет один из результатов выполнения задачи по его id.

mutation.maintenance¶

Служебные функции:

drop_unlinked_spaces – удаление спейсов от агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные.
truncate_unlinked_spaces – удаление данных из спейсов агрегатов, которые были удалены из модели, но при этом в хранилище остались их сохраненные данные.

mutation.audit_log¶

Ведение журнала событий безопасности (аудит лог):

enabled – включение функции ведения журнала событий безопасности.
clear – очистка журнала событий безопасности.
severity – настройка уровня важности событий, которые будут записываться в журнал событий безопасности.

mutation.notifier_delete_user¶: Удаляет запись из списка подписчиков (вкладка Subscribers) по ее id.

mutation.repair_all¶: Выполняет повторную попытку обработки всех объектов из ремонтной очереди (вкладка Repair).

mutation.repair¶: Выполняет повторную попытку обработки объекта из ремонтной очереди (вкладка Repair) по его id.

mutation.delete_from_repair_queue¶: Выполняет удаление объекта из ремонтной очереди (вкладка Repair) по его id.

mutation.config¶

Изменение настроек кластера:

vshard-timeout – таймаут выполнения удаленного вызова для операции модуля Tarantool vshard.
force_yield_limits – количество чтений записей спейса, после которых происходит принудительная передача управления (yield) для обеспечения кооперативной многозадачности.
hard_limits – ограничения при выполнении GraphQL-запросов. Возможные аргументы:
- scanned – ограничение числа записей в спейсах, которые могут быть прочитаны для выполнения запроса.
- returned – ограничение числа записей, которые могут быть возвращены в ответе на запрос.
graphql_query_cache_size – ограничение количества кэшируемых уникальных GraphQL-запросов.

mutation.account_provider¶

Управление доступом:

ldap – позволяет изменить конфигурацию LDAP.

mutation.backup¶

Управление резервным копированием конфигураций:

config_apply – применяет конфигурацию заданной версии.
config_delete – удаляет конфигурацию заданной версии.
config_save_current – создает резервную копию конфигурации с заданным комментарием.
settings – изменяет настройки резервного копирования конфигураций.

mutation.connector¶

Управление коннекторами:

http_request – отправляет заданный объект используя HTTP.
soap_request – отправляет заданный объект используя SOAP.

mutation.data_type¶

Доступ к текущей модели данных:

model – позволяет изменить текущую модель данных.
expiration – позволяет изменить настройки устаревания данных.
versioning – позволяет изменить версию модели данных.

mutation.expiration_cleanup¶: Очистка (сброс) настроек устаревания данных по имени агрегата.

mutation.logs¶

Управление общим журналом событий:

truncate – очищает журнал событий.
config – позволяет изменить конфигурацию журнала событий.

mutation.metrics¶

Управление метриками:

config – позволяет изменить настройки метрик.

mutation.migration¶

Управление миграцией данных:

apply – позволяет поменять настройки миграции данных.
dry_run – запускает миграцию данных.

mutation.settings¶

Управление настройками учетной записи:

put – добавляет заданные настройки учетной записи.
delete – удаляет заданные настройки учетной записи.

Настройки Tarantool Cartridge¶

Для выполнения запроса, его необходимо направить по протоколу HTTP на HTTP порт любого экземпляра кластера с указанием адреса ресурса (endpoint) /admin/api, а также данными авторизации.

Пример выполнения запроса при помощи утилиты curl:

curl --request POST \
  --url http://172.19.0.2:8080/admin/api \
  --header 'Authorization: Bearer 2fc136cf-8cae-4655-a431-7c318967263d' \
  --header 'content-type: application/json' \
  --data '{"query":"query{\n  cluster{\n    known_roles{\n      name\n      dependencies\n    }\n  }\n}"}'

Далее приведены все типы запросов на чтение или изменение основных настроек Tarantool Cartridge. Для некоторых запросов дополнительно указаны возвращаемые значения и пояснения к ним.

Запросы на получение информации по текущим настройкам и состоянию кластера (query)¶

Пример запроса на получение информации о пользователе по его имени (cluster.users):

query {
    cluster {
        users { username }
    }
}

query.cluster¶

Управление кластером:

self – позволяет получить информацию о текущем сервере (который выполняет запрос).
failover – возвращает текущий статус включения функции failover.
failover_params – возвращает текущие настройки функции failover. Может возвращать следующие значения:
- tarantool_params – параметры подключения:
  - uri – адрес подключения.
  - password – пароль для подключения.
- mode – режим работы (disabled, eventual или stateful).
- state_provider – тип внешнего хранилища для режима работы stateful.
vshard_bucker_count – возвращает число виртуальных бакетов в кластере
issues – возвращает список проблем (issues), зарегистрированных в кластере.
auth_param – возвращает параметры авторизации. Эти параметры относятся к авторизации в Tarantool Cartridge, а не в TDG:
- enabled – включена ли функция авторизации.
- username – имя текущего пользователя.
- cookie_max_age – максимальное время жизни пользовательской cookie (в секундах).
- cookie_renew_age – если передаваемая пользовательская cookie старше, чем указано в данном параметре, то ее необходимо обновить.
- implements_add_user – в кластере реализована функция добавления пользователей.
- implements_remove_user – в кластере реализована функция удаления пользователей.
- implements_edit_user – в кластере реализована функция редактирования пользователей.
- implements_list_user – в кластере реализована функция вывода списка пользователей.
- implements_get_user – в кластере реализована функция вывода информации о конкретном пользователе.
- implements_check_password – в кластере реализована функция проверки аутентификатора пользователя.
known_roles – возвращает список всех известных ролей экземпляров и их зависимостей.
webui_blacklist – возвращает список страниц веб-интерфейса, которые должны быть скрыты (исключены из отображения). Обычно это те страницы, доступ к которым запрещен (запрет доступа осуществляется другими механизмами).
vshard_groups – информация об имеющихся группах модуля vshard, используемых для распределенного хранения данных.
can_bootstrap_vshard – имеется ли возможность вызвать функцию bootsrap_vshard.
config – возвращает текущую конфигурацию.

query.servers¶: Возвращает информацию по серверам кластера.

query.replicasets¶: Возвращает информацию по наборам реплик кластера.

Запросы на внесение изменений в настройки (mutation)¶

Пример запроса на изменение настроек автоматического восстановления (cluster.failover):

mutation {
    cluster {
        failover(enabled: false)
    }
}

mutation.cluster¶

Настройки кластера:

schema – применение новой модели данных.
failover – включение или отключение функции автоматического восстановления.
failover_params – настройка функции автоматического восстановления.
edit_topology – позволяет задавать топологию кластера (наборы реплик и их роли).
auth_params – настройка параметров авторизации. Эти параметры относятся к авторизации в Tarantool Cartridge, а не к TDG:
- enabled – включена ли функция авторизации.
- cookie_max_age – максимальное время жизни пользовательской cookie (в секундах).
- cookie_renew_age – если передаваемая пользовательская cookie старше, чем указано в данном параметре, то ее необходимо обновить.
failover_promote – переключение мастера в наборе реплик с указанным id на экземпляр с указанным id. Работает только в stateful-режиме функции автоматического восстановления (failover).

edit_server – редактирование основных параметров сервера. Устаревшая функция. Оставлена для обратной совместимости. Используйте cluster/edit_topology вместо данной функции.
probe_server – проверяет, доступен ли экземпляр по указанному адресу для подключения его к кластеру.
edit_replicaset – редактирование основных параметров набора реплик. Устаревшая функция. Оставлена для обратной совместимости. Используйте cluster/edit_topology вместо данной функции.
join_server – подключение нового экземпляра к существующему набору реплик. Устаревшая функция. Оставлена для обратной совместимости. Используйте cluster/edit_topology вместо данной функции.
bootstrap_vshard – при вызове происходит распределение данных по серверам (См. bootsrap_vshard).
expel_server – необратимое удаление сервера из кластера. Устаревшая функция. Оставлена для обратной совместимости. Используйте cluster/edit_topology вместо данной функции.

Introduction to Tarantool Data Grid 2.0¶

Основные возможности¶

Хранение данных¶

Хранение и исполнение бизнес-логики¶

Интеграция/API¶

Безопасность¶

Практическое применение¶

Пример бизнес-решения на TDG¶

Шаг 1: Описать модель объекта данных¶

Шаг 2: Задать логику объединения данных¶

Шаг 3: Запустить решение на одном сервере¶

Release notes¶

What’s new in Tarantool Data Grid 2.0¶

Changelog¶

Updated¶

Added¶

Fixed¶

Updated¶

Added¶

Fixed¶

Updated¶

Added¶

Fixed¶

Updated¶

Added¶

Fixed¶

Updated¶

Added¶

Fixed¶

Updated¶

Added¶

Updated¶

Added¶

Fixed¶

Fixed¶

Added¶

Added¶

Fixed¶

Breaking changes¶

Added¶

Fixed¶

Added¶

Fixed¶

Breaking changes¶

Added¶

Fixed¶

Updated¶

Added¶

Fixed¶

Updated¶

Added¶

Fixed¶

Deprecated¶

Added¶

Fixed¶

Added¶

Fixed¶

Архитектура¶

Хранение данных: Tarantool¶

Доступ к данным: GraphQL и REST API¶

Исполнение бизнес-логики: Lua¶

Взаимодействие с внешними системами¶

Администрирование и безопасность¶

Кластерные роли¶

Роль Core¶

Роль Storage¶

Роль Runner¶

Роль Connector¶

Administrator’s guide¶

Deployment¶

First deployment with Ansible¶

Getting a TGZ file for deployment¶

Setting up virtual machines¶

Deploying the cluster¶

Preparing¶

Configuring¶

Deploying¶

Managing the cluster¶

Configuring topology of the cluster¶

Starting or stopping instances¶