Настройки операций

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

Общие опции для всех типов операций

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

  • pool — имя вычислительного пула, в котором будет работать операция. Если данный параметр не указан, то в качестве имени пула берется имя пользователя в YTsaurus, запустившего операцию;
  • weight(1.0) — вес запущенной операции, определяет, какую долю вычислительной квоты пула получит операция. Подробнее можно прочитать в разделе Планировщик и пулы;
  • pool_trees ("physical") — список деревьев пулов, в которых будут запускаться джобы операции;
  • tentative_pool_trees — список дополнительных деревьев пулов, ресурсы которых добавляются к ресурсам основных деревьев. При выполнении джобов в данных деревьях измеряются различные характеристики и в случае, если джобы в таких деревьях работают медленнее по сравнению с основными деревьями, то новые джобы конкретной операции в таких деревьях запускаться не будут;
  • use_default_tentative_pool_trees — включить использование всех деревьев в кластере, которые считаются подходящими под определение tentative.
  • tentative_tree_eligibility — конфигурация с настройками выполнения джобов операции в tentative деревьях;
    • sample_job_count (10) — количество джобов, которое будет запущено в качестве пробы;
    • max_tentative_job_duration_ratio (10) — максимальное допустимое замедление времени выполнения джобов;
    • min_job_duration (30) — настройка, задающая границу времени работы джобов в tentative деревьях. Новые джобы операции не будут запускаться в соответствующем tentative дереве, если среднее время выполнения джобов в tentative дереве больше данной границы;
    • ignore_missing_pool_trees (false) — включение данной опции игнорирует отсутствующие tentative деревья в кластере;
  • resource_limits, max_share_ratio — настройки fair_share, которые будут действовать суммарно на все джобы операции. Подробнее можно прочитать в разделе Характеристики пулов);
  • time_limit — ограничение на время работы операции в целом (в миллисекундах). Если операция не успеет завершиться за указанное время, она будет принудительно завершена планировщиком;
  • acl — Access Control List, определяющий права доступа к операции. Право manage
    означает мутирующие действия над операцией и её джобами: abort,
    suspend, использование job shell и т.д. Право read — немутирующие:
    get_job_stderr, get_job_input_context и так далее. К указанному acl будут
    добавлены записи про пользователя, запустившего операцию, и администраторов YTsaurus;
  • max_stderr_count (10) — ограничение на количество сохраняемых данных из стандартного потока ошибок (stderr) джобов, по умолчанию берется из настроек кластера, где это значение обычно равно 10. Максимальное значение параметра 150;
  • max_failed_job_count (10) — количество failed джобов, после которого операция считается failed. По умолчанию берется из настроек кластера, где это значение обычно равно 10;
  • unavailable_chunk_strategy и unavailable_chunk_tactics — как поступать в случае недоступности промежуточных результатов вычисления. Подробное в разделе Операции;
  • scheduling_tag_filter — фильтр для выбора узлов кластера при запуске джобов. Фильтр представляет собой логическое выражение с операторами & (логическое «и»), | (логическое «или»), ! (логическое «не») и круглыми скобками. Переменными в выражении являются возможные значения тегов узлов кластера. Тег представляет собой метку, которой размечается узел кластера. Разметка осуществляется командой сервиса YTsaurus при конфигурировании кластера. Если у узла кластера имеется тег, заданный в выражении, то выражение принимает значение «истина», если нет — «ложно». Если всё выражение целиком принимает значение «ложно», то такой узел кластера не будет выбран для запуска джоба;
  • max_data_size_per_job (200 Gb) — максимальный разрешенный объем данных на входе у одного джоба. Данная опция задает жесткую верхнюю границу на размер джоба. Если планировщик будет не в состоянии сформировать джоб меньше, операция завершится с ошибкой;
  • data_size_per_job (data_weight_per_job) – рекомендованный объём данных на входе одного джоба. Опция не имеет смысла для составных операций, например, MapReduce. В таких операциях нужно использовать следующие опции:
    • data_size_per_map_job (data_weight_per_map_job);
    • data_size_per_sort_job (data_weight_per_sort_job);
    • data_size_per_partition_job (data_weight_per_partition_job);
    • data_size_per_sorted_merge_job (data_weight_per_sorted_merge_job);
    • data_size_per_reduce_job (data_weight_per_reduce_job).
  • secure_vault — значения из данного словаря попадут в окружения всех пользовательских джобов данной операции и при этом не будут доступны для просмотра посторонними пользователями, в отличие от секции environment в спецификации пользовательского джоба. А именно, в переменную окружения YT_SECURE_VAULT запишется весь переданный словарь в YSON формате, а также для удобства использования для каждой пары key=value из словаря в переменную окружения YT_SECURE_VAULT_key запишется значение value. Так произойдёт, только если value является примитивным типом, то есть int64, uint64, double, boolean или string;
  • stderr_table_path — может быть указан путь к существующей таблице, таблица должна быть создана вне транзакций, если данная настройка указана, то полные данные из стандартного потока ошибок (stderr) всех джобов (кроме aborted) будут записаны в указанную таблицу. Таблица будет иметь следующие колонки:
    • job_id — идентификатор джоба;
    • part_index — в случае большого сообщения об ошибке, сообщение stderr одного джоба может быть разбито на несколько частей (в разных строках), в данной колонке записан номер такой части;
    • data — данные из стандартного потока ошибок.
  • core_table_path — путь к существующей таблице для записи core dump. Формат таблицы аналогичен описанному в stderr_table_path.
  • input_query — для операций Map, ordered и unordered Merge можно выполнить предварительную фильтрацию каждой входной строки с помощью языка запросов. Поскольку входная таблица и так известна и предполагается, что фильтрация будет отдельной для каждой строки, синтаксис запросов меняется и упрощается до * | <select-expr-1> [AS <select-alias-1>]... [WHERE <predicate-expr>]. В частности, нельзя использовать GROUP BY и ORDER BY. Запросы работают со строго схематизированными данными, поэтому необходимо, чтобы исходные таблицы имели строгую схему. В операции Merge схема итоговых данных в запросе учитывается при выводе схемы для выходной таблицы.
  • omit_inaccessible_columns (false) – пропускать колонки, доступ к которым отсутствует. По умолчанию операция в такой ситуации завершится с ошибкой при запуске.
  • alias – алиас данной операции. Делает операцию доступной в поиске и с использованием команды get-operation по указанной строке.

Примечание

В случае указания параметра input_query, атрибуты enable_row_index и enable_range_index не попадут в джоб;

  • job_node_account (tmp_jobs) — аккаунт, под которым будут храниться чанки файлов с логом ошибок (stderr) и input context;
  • suspend_operation_if_account_limit_exceeded (false) — приостанавливать (ставить на паузу) операцию в случае возникновения ошибки «Account limit exceeded» в джобе;
  • enable_job_splitting (true) — разрешать ли планировщику адаптивно доразбивать пользовательские джобы, которые долго выполняются;
  • fail_on_job_restart (false) — при любом завершении джоба, успевшего начать свою работу, отличном от успешного (то есть, при abort или fail), принудительно прерывать операцию. Полезно для операций, для которых недопустим перезапуск джобов;
  • title — заголовок операции. Переданный в него текст будет отображен в веб-интерфейсе;
  • started_by — словарь, описывающий клиента, посредством которого была запущена операция. Данное поле не предполагает строгой схемы, указанная информация будет отражена в веб-интерфейсе на странице операции;
  • annotations — словарь, в который пользователь может записать произвольную структурированную информацию, связанную с операцией. Содержимое annotations в YSON text формате попадает в архив операций, так что по нему можно в дальнейшем искать и идентифицировать операции в архиве.

Примечание

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

  • description — словарь, аналогичный annotations, также отображающийся в веб-интерфейсе на странице операции. В данную секцию стоит добавлять исключительно человекочитаемую информацию небольшого размера, чтобы не перегружать информацией страницу операции;
  • use_columnar_statistics (false) — использовать поколоночные статистики для точной оценки размеров джобов при запуске операций поверх таблиц с колоночными выборками. Данная опция улучшает автоматику разбиения на джобы, при этом из входных данных берутся колонки, образующие малую долю размера входных таблиц (ранее выбор колонок игнорировался и джобы получались очень маленькими, на что приходилось влиять с помощью опции data_weight_per_job);
  • sampling — конфигурация крупноблочного сэмплирования входных данных (недоступно в операциях Sort, RemoteCopy и Vanilla). Данный вид сэмплирования, в отличие от сэмплирования при чтении, старается пропорционально уменьшить количество прочитанных с диска данных, и поэтому в идеальных обстоятельствах должен приводить к пропорциональному ускорению операции. Ценой этого является тот факт, что результат не является полноценным сэмплированием в математическом смысле этого слова, а является лишь его приближением: данные разбиваются на достаточно большие блоки идущих подряд строк, и далее происходит сэмплирование данных блоков целиком. Для прикладных расчётов на достаточно больших таблицах результат может оказаться состоятельным. Значение параметра задаётся словарём со следующими ключами:
    • sampling_rate (null) — доля оставляемых строк;
    • io_block_size (16Mb) — минимальный размер блока сэмплирования. Не рекомендуется менять значение по умолчанию;
  • max_speculative_job_count_per_task — лимит числа спекулятивных джобов (пока поддерживаются для операций Map, Reduce, MapReduce, Sort, Merge).
  • job_speculation_timeout — таймаут в миллисекундах, по истечении которого для исполняемого джоба необходимо запустить спекулятивную.
  • try_avoid_duplicating_jobs — (false) по возможности не запускать джобов с одинаковым входом, если это не требуется. В частности, отключает спекулятивные джобы. Но невозможно гарантировать, что джобы с одинаковым входом не будут запущены. Например, если узел, на котором был запущен первый экземпляр джоба, потерял связность с кластером, то джоб на нём будет продолжать бежать и потенциально выполнять наблюдаемые побочные действия. А кластеру придется перезапустить джоб с тем же входом на другом узле.

Для каждого типа джоба в операции можно настраивать его параметры ввода-вывода. Если у операции имеется один тип джоба, секция в спецификации называется job_io. В случае же, если в операции есть разнотипные джобы (это относится к операциям MapReduce и Sort), то для каждого типа есть своя секция. Названия этих секций перечислены среди настроек соответствующих операций.

Параметры пользовательского скрипта

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

  • command (обязательный параметр) — строка, которая будет выполнена посредством вызова bash -c;
  • file_paths — список путей в Кипарисе к файлам или таблицам. Данные файлы и таблицы будут скачаны на узел кластера, где происходит выполнение команды, и в специальном окружении sandbox будут находиться символические ссылки на скачанные файлы. Ссылки доступны только на чтение. Имя файла по умолчанию будет равно basename пути в Кипарисе, однако его можно изменить, указав атрибут пути file_name. Если путь указывает на таблицу, обязательно указать атрибут formatформат, в котором таблица должна быть сохранена в файл на диске. Размер табличных файлов ограничен 10Гб;
  • docker_image — имя докер образа для корневой файловой системы джоба;
  • layer_paths — список путей к porto слоям в Кипарисе. Слои перечисляются от верхнего к нижнему;
  • cuda_toolkit_version – версия CUDA, требуемая джобу. Если версия указана, то в джоб будет подложен стандартный delta-слой с данной CUDA.
  • format, input_format, output_format (yson) — формат, в котором на вход операции поступают табличные данные. Опции input_format и output_format имеют приоритет над опцией format;
  • environment— словарь переменных окружения, которые будут указаны при выполнении операции. Данная опция нужна, чтобы не указывать переменные окружения в параметре command и не снижать его читаемость;
  • cpu_limit (1) — число вычислительных ядер, которое будет учтено планировщиком за выполняемым джобом при его планировании;
  • set_container_cpu_limit (false) – выставлять porto-контейнеру cpu_limit, равный заказанному. По умолчанию выставляется только вес, пропорциональный заказанному cpu_limit.
  • gpu_limit (0) — количество GPU-карт, которое будет выдано джобу;
  • memory_limit (512Mb) — ограничение на потребление памяти джобом в байтах;
  • user_job_memory_digest_default_value (0.5) - исходная догадка для выбора резерва памяти.
  • enable_input_table_index — писать ли во входном потоке информацию о том, из какой таблицы пришла строка (индекс входящей таблицы).. По умолчанию атрибуты записываются, только если входных таблиц больше одной;
  • tmpfs_path — путь в sandbox, в котором будет смонтирован tmpfs. Размер tmpfs по умолчанию равен memory_limit джоба и реально занятое в нем место учитывается в потреблении памяти джобом;
  • tmpfs_size — опциональный параметр, который задает ограничение на размер tmpfs в джобе. Параметр имеет смысл, только если указан tmpfs_path. Если параметр не указан, он считается равным memory_limit, при этом memory_reserve_factor автоматически становится равным 1;
  • tmpfs_volumes — данный параметр позволяет указать сразу список tmpfs разделов в джобе. Элемент списка — словарь с двумя полями size и path, заказываемые разделы не должны пересекаться по своим путям;
  • copy_files (false) — по умолчанию пользовательские файлы попадают в sandbox джоба по символической ссылке. Если включена данная настройка, они будут копироваться в sandbox. Включение данной настройки может быть полезно при использовании tmpfs_path=.;
  • check_input_fully_consumed (false) — опция позволяет включить на уровне системы проверку, что джоб прочитал все данные, записанные к нему в буфер, а не вышел раньше времени.
  • max_stderr_size (5Mb) — ограничение по объёму stderr, который будет сохранен в результате работы джоба. Данные записанные в stderr сверх данного ограничения игнорируются;
  • custom_statistics_count_limit (128) — ограничение на количество пользовательских статистик, которые можно записать из джоба, максимум – 1024;
  • job_time_limit — ограничение на время работы джоба в миллисекундах. Джобы превышающие ограничение будут считаться failed;
  • disk_request – список дисков, необходимых джобу. По умолчанию, джобу выдаётся локальный диск на том же узле кластера, где запущен джоб. Потребление дискового пространства не ограничивается, но джоб может быть прерван, если место на диске закончится. Каждый диск описывается следующими параметрами:
    • disk_space – ограничение на общий размер файлов в sandbox джоба на данном диске.
    • inode_count — ограничение на количество inode на данном диске.
    • account - аккаунт, в рамках которого будет учитываться заказанное место.
    • medium_name (default) – название медиума, на котором нужен диск.
  • interruption_signal – номер сигнала, который будет послан пользовательскому процессу, вытеснением джоба. Между посылкой сигнала и перед прерыванием джоба есть некоторый таймаут, зависящий от настроек кластера, за это время пользовательский процесс может попытаться дообработать данные и успешно выйти.
  • restart_exit_code – код возврата, сигнализирующий о том, что нужно перезапустить джоб после прерывания. Данная опция важна для vanilla-джобов, которые представляют сервисы или обрабатывают внешние по отношению к YTsaurus данные.
  • network_project – имя MTN проекта, в сети которого будет запущен джоб. Проект должен быть зарегистрирован в Кипарисе и доступен с точки зрения прав доступа.
  • job_speculation_timeout – таймаут, после которого возможен запуск спекулятивного джоба по отношению к данному. Спекулятивный джоб – механизм, который позволяет запускать дополнительную копию джоба на тех же входных данных (параллельно с основным джобом), если есть подозрение, что основной джоб завис. «Подозрительные» джобы планировщик находит самостоятельно, используя статистики о скорости чтения входных и записи выходных данных, времени подготовки джоба, наличии попыток разделить джоб на несколько и другие эвристики.
  • waiting_job_timeout – таймаут, в течение которого джоб может находиться в очереди на запуск на ноде. По умолчанию берется из настроек конкретного кластера.

Примечание

Перечисленные выше настройки характеризуют скрипт, а не операцию в целом. В частности, они должны располагаться не в корне спецификации, а в ветках mapper, reducer и так далее. Пользовательский скрипт вынесен в отдельную сущность, так как в операции MapReduce таких скриптов более одного (mapper, reducer, combiner).

Резервирование памяти

При настройках по умолчанию контроллер операции на основании статистик джобов подбирает резерв памяти для вновь запускаемых джобов. Работа механизма выполняется прозрачным для пользователей способом и не влияет на успешность операции. Однако, может приводить к появлению прерванных джобов с выделенной причиной resource_overdraft.

Детальное описание механизма на отдельной странице.

Внимание

При включении tmpfs (эквивалентно указанию tmpfs_path), без явной установки ограничения на его размер (параметр tmpfs_size), резерв памяти автоматически становится равным единице, так как ядро операционной системы Linux не позволяет делать оверкомит по размерам tmpfs, и превышение суммарного размера над физическими возможностями может привести к зависанию узла кластера.

Чтение нескольких входных таблиц

Данные из входных таблиц, записанные согласно указанному входному формату, будут поступать пользовательскому скрипту на стандартный вход (stdin). У пользовательского скрипта будут открыты дескрипторы выходных таблиц на запись. Номера дескрипторов 1, 4, 7, .. согласованы с тем порядком, в котором операции переданы выходные таблицы.

Заказ диска в джобах

Если в спецификации disk_request указать только disk_space, то для джобов будут использоваться диски, выделенные под джобы по умолчанию. Это HDD, то есть медиум default в большинстве случаев, и NVME, в случае запуска на современных GPU-хостах (v100 и новее). В данном случае никакого аккаунтинга используемого места не происходит, то есть считается, что свободного места на дисках в избытке и проблем не ожидается. Квотируются только данные, которые пользователь хранит на кластере, а используемое в джобе дисковое пространство, не учитывается в дисковой квоте (аккаунте) пользователя. При этом планировщик следит за тем, чтобы каждый джоб не превышал своих лимитов и чтобы сумма лимитов всех джобов на узле кластера не превышала доступное дисковое пространство на узле кластера.

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

Если вы хотите использовать иные диски в джобах ваших операций, например, SSD там, где по умолчанию предполагается HDD, то необходимо указывать специальный medium и ваш account, в котором будет происходить квотирование заказанного под джобы места. В данный момент времени на кластерах Арнольд и Хан диски под джобы находятся в медиуме ssd_slots_physical, соответственно, для их использования необходимо заказать места в аккаунт в данном медиуме.

Атрибуты на путях

На выходных таблицах операций поддерживаются следующие атрибуты (в скобках указаны значения по умолчанию, если заданы):

  • sorted_by — набор колонок, по которому должна быть отсортирована таблица;
  • append (false) — дописывать ли данные в данную выходную таблицу. Если append равен false, данные в таблице будут перезаписаны;
  • row_count_limit — досрочно завершить операцию, как только в выходной таблице появится хотя бы row_count_limit строк. Может быть установлен не более чем на одной таблице;

На входных таблицах операций поддерживаются атрибуты:

  • стандартные модификаторы выбора строки и колонок;
  • transaction_id — позволяет указать, под какой транзакцией необходимо обращаться к входной таблице;
  • timestamp — позволяет использовать состояние динамической таблицы на определённый момент времени;
  • rename_columns — позволяет переименовать некоторые колонки перед началом обработки таблицы в операции. Переименовывать можно только колонки, находящиеся в схеме. После переименования должны выполняться все ограничения на схему таблицы, а также не должно быть пересечений по именам колонок в чанках для нестрогой схемы. В случае, если указан набор колонок sorted_by на выходной таблице операции, либо схема выходной таблицы имеет ключевые колонки, будет происходить следующее:
    1. Джобы операции при формировании чанков для таблицы будут проверять сортированность записей по указанному набору колонок;
    2. Планировщик валидирует, что диапазоны ключей у сформированных чанков данной выходной таблицы не пересекаются, и после сформирует из этого набора чанков сортированную таблицу.

Операция завершится с ошибкой, если валидация на любом из перечисленных шагов не пройдёт.

Файлы

На путях к файлам поддерживаются следующие атрибуты:

  • file_name — имя файла данного файла в sandbox джоба;
  • executable — сделать ли файл исполняемым;
  • format — формат, в котором нужно сформировать файл из таблицы, если в качестве файла передан путь к таблице;
  • bypass_artifact_cache – флаг, указывающий на то, что файл необходимо скачать в sandbox джоба, минуя кеш. Данный атрибут может быть полезен, если файлы уже лежат на SSD или в памяти, и требуется их извлечь в джоб без лишних задержек; имеет смысл, если количество джобов в операции невелико, и поэтому кеширование неэффективно.