From 14ba5f801916f60943acc474a3db2ab6883fb899 Mon Sep 17 00:00:00 2001 From: Karteekmurthys Date: Mon, 1 Jul 2024 23:01:24 +0530 Subject: [PATCH] [native] Prestissimo worker metrics documentation --- .../src/main/sphinx/presto_cpp/features.rst | 49 +- .../src/main/sphinx/presto_cpp/properties.rst | 7 + presto-native-execution/README.md | 651 +++++++++++------- 3 files changed, 448 insertions(+), 259 deletions(-) diff --git a/presto-docs/src/main/sphinx/presto_cpp/features.rst b/presto-docs/src/main/sphinx/presto_cpp/features.rst index 28c2b2ff77d87..5b660a393ba8e 100644 --- a/presto-docs/src/main/sphinx/presto_cpp/features.rst +++ b/presto-docs/src/main/sphinx/presto_cpp/features.rst @@ -22,15 +22,36 @@ HTTP endpoints related to tasks are registered to Proxygen in Other HTTP endpoints include: -* POST: v1/memory - * Reports memory, but no assignments are adjusted unlike in Java workers. -* GET: v1/info -* GET: v1/status +* POST: v1/memory: Reports memory, but no assignments are adjusted unlike in Java workers +* GET: v1/info/metrics: Returns worker level metrics in Prometheus Data format. Refer section `Worker Metrics Collection <#worker-metrics-collection>`_ for more info. Here is a sample Metrics data returned by this API. -The request/response flow of Presto C++ is identical to Java workers. The -tasks or new splits are registered via `TaskUpdateRequest`. Resource -utilization and query progress are sent to the coordinator via task endpoints. + .. code-block:: text + # TYPE presto_cpp_num_http_request counter + presto_cpp_num_http_request{cluster="testing",worker=""} 0 + # TYPE presto_cpp_num_http_request_error counter + presto_cpp_num_http_request_error{cluster="testing",worker=""} 0 + # TYPE presto_cpp_memory_pushback_count counter + presto_cpp_memory_pushback_count{cluster="testing",worker=""} 0 + # TYPE velox_driver_yield_count counter + velox_driver_yield_count{cluster="testing",worker=""} 0 + # TYPE velox_cache_shrink_count counter + velox_cache_shrink_count{cluster="testing",worker=""} 0 + # TYPE velox_memory_cache_num_stale_entries counter + velox_memory_cache_num_stale_entries{cluster="testing",worker=""} 0 + # TYPE velox_arbitrator_requests_count counter + velox_arbitrator_requests_count{cluster="testing",worker=""} 0 + + +* GET: v1/info: Returns basic information about the worker. Here is an example: + + .. code-block:: text + + {"coordinator":false,"environment":"testing","nodeVersion":{"version":"testversion"},"starting":false,"uptime":"49.00s"} + +* GET: v1/status: Returns memory pool information. + +The request/response flow of Presto C++ is identical to Java workers. The tasks or new splits are registered via `TaskUpdateRequest`. Resource utilization and query progress are sent to the coordinator via task endpoints. Remote Function Execution ------------------------- @@ -169,7 +190,7 @@ Size of the SSD cache when async data cache is enabled. * **Default value:** ``true`` * **Presto on Spark default value:** ``false`` -Enable periodic clean up of old tasks. The default value is ``true`` for Presto C++. +Enable periodic clean up of old tasks. The default value is ``true`` for Presto C++. For Presto on Spark this property defaults to ``false``, as zombie or stuck tasks are handled by Spark by speculative execution. @@ -185,6 +206,18 @@ Old task is defined as a PrestoTask which has not received heartbeat for at leas ``old-task-cleanup-ms``, or is not running and has an end time more than ``old-task-cleanup-ms`` ago. +Worker metrics collection +------------------------- + +Users can enable collection of worker level metrics by setting the property: + +``runtime-metrics-collection-enabled`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +* **Type:** ``boolean`` +* **Default value:** ``false`` + + When true, the default behavior is a no-op. There is a prior setup that must be done before enabling this flag. To enable + metrics collection in Prometheus Data Format refer `here `_. Session Properties ------------------ diff --git a/presto-docs/src/main/sphinx/presto_cpp/properties.rst b/presto-docs/src/main/sphinx/presto_cpp/properties.rst index ff4cae57e02b5..be38fef8f0d6c 100644 --- a/presto-docs/src/main/sphinx/presto_cpp/properties.rst +++ b/presto-docs/src/main/sphinx/presto_cpp/properties.rst @@ -124,6 +124,13 @@ The configuration properties of Presto C++ workers are described here, in alphab 1) the non-reserved space in ``query-memory-gb`` is used up; and 2) the amount it tries to get is less than ``memory-pool-reserved-capacity``. +``runtime-metrics-collection-enabled`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +* **Type:** ``boolean`` +* **Default value:** ``false`` + + Enables collection of worker level metrics. + ``system-memory-gb`` ^^^^^^^^^^^^^^^^^^^^ diff --git a/presto-native-execution/README.md b/presto-native-execution/README.md index a5346e7b38b6b..d97e540186928 100644 --- a/presto-native-execution/README.md +++ b/presto-native-execution/README.md @@ -1,251 +1,400 @@ -# Prestissimo - C++ Presto Worker Implementation using Velox - -Prestissimo implements the [Presto Worker REST API](https://prestodb.io/docs/current/develop/worker-protocol.html) -using [Velox](https://github.com/facebookincubator/velox). - -## Table of Contents -* [Build from Source](#build-from-source) -* [Build using Dockerfile](#build-using-dockerfile) -* [Development](#development) -* [Create Pull Request](#create-pull-request) -* [Advance Velox Version](#advance-velox-version) -* [Functional test using containers](#functional-test-using-containers) -* [Troubleshooting](#troubleshooting) - -## Build from Source -* Clone the Presto repository - -`git clone https://github.com/prestodb/presto.git` -* Run `cd presto/presto-native-execution && make submodules` - -### Dependency installation -Dependency installation scripts based on the operating system are -available inside `presto/presto-native-execution/scripts`. - -* MacOS: `setup-macos.sh` -* CentOS Stream 8: `setup-centos.sh` -* Ubuntu: `setup-ubuntu.sh` - -Create a directory say `dependencies` and invoke one of these scripts from -this folder. All the dependencies are installed in the system default location eg: `/usr/local`. - -The following libraries are installed by the above setup scripts. -The Velox library installs other -[dependencies](https://github.com/facebookincubator/velox/tree/main/CMake/resolve_dependency_modules/README.md) -not listed below. - -| Name | Version | -| ---------- | ------- | -| [Velox](https://github.com/facebookincubator/velox) | Latest | -| [CMake](https://cmake.org/) | Minimum `3.10` | -| [gperf](https://www.gnu.org/software/gperf) |`v3.1`| -| [proxygen](https://github.com/facebook/proxygen) |`v2024.04.01.00`| - -### Supported architectures, operating systems, and compilers - -The supported architectures are `x86_64 (avx, sse)`, and `AArch64 (apple-m1+crc, neoverse-n1)`. - -Prestissimo can be built by a variety of compilers (and versions) but not all. -Compilers (and versions) not mentioned are known to not work or have not been tried. - -#### Recommended -| OS | compiler | -| -- | -------- | -| CentOS 8/RHEL 8 | `gcc9` | -| Ubuntu 22.04 | `gcc11` | -| MacOS | `clang15` | - -#### Older alternatives -| OS | compiler | -| -- | -------- | -| Ubuntu 20.04 | `gcc9` | -| MacOS | `clang14` | - -#### Experimental -| OS | compiler | -| -- | -------- | -| CentOS 9/RHEL 9 | `gcc12` | - -### Build Prestissimo -To enable Parquet and S3 support, set `PRESTO_ENABLE_PARQUET = "ON"`, -`PRESTO_ENABLE_S3 = "ON"` in the environment. - -S3 support needs the [AWS SDK C++](https://github.com/aws/aws-sdk-cpp) library. -This dependency can be installed by running the script below from the -`presto/presto-native-execution` directory. - -`./velox/scripts/setup-adapters.sh aws` - -To enable JWT authentication support, set `PRESTO_ENABLE_JWT = "ON"` in -the environment. - -JWT authentication support needs the [JWT CPP](https://github.com/Thalhammer/jwt-cpp) library. -This dependency can be installed by running the script below from the -`presto/presto-native-execution` directory. - -`./scripts/setup-adapters.sh jwt` - -* After installing the above dependencies, from the -`presto/presto-native-execution` directory, run `make` -* For development, use -`make debug` to build a non-optimized debug version. -* Use `make unittest` to build -and run tests. - -### Makefile Targets -A reminder of the available Makefile targets can be obtained using `make help` -``` - make help - all Build the release version - clean Delete all build artifacts - cmake Use CMake to create a Makefile build system - build Build the software based in BUILD_DIR and BUILD_TYPE variables - debug Build with debugging symbols - release Build the release version - unittest Build with debugging and run unit tests - format-fix Fix formatting issues in the current branch - format-check Check for formatting issues on the current branch - header-fix Fix license header issues in the current branch - header-check Check for license header issues on the current branch - tidy-fix Fix clang-tidy issues in the current branch - tidy-check Check clang-tidy issues in the current branch - help Show the help messages -``` - -## Build using Dockerfile -Information on how to build a dependency and runtime image of Prestissimo [can be found here](scripts/dockerfiles/README.md). - -## Development -### Setup Presto with [IntelliJ IDEA](https://www.jetbrains.com/idea/) and Prestissimo with [CLion](https://www.jetbrains.com/clion/) - -Clone the whole Presto repository. Close IntelliJ and CLion if running. - -From the Presto repo run the commands below: -* `git fetch upstream` -* `git co upstream/master` -* `mvn clean install -DskipTests -T1C -pl -presto-docs` - -Run IntelliJ IDEA: - -Run HiveExternalWorkerQueryRunner, -* Edit/Create `HiveExternalWorkerQueryRunner` Application Run/Debug Configuration (alter paths accordingly). - * Main class: `com.facebook.presto.nativeworker.HiveExternalWorkerQueryRunner`. - * VM options: `-ea -Xmx5G -XX:+ExitOnOutOfMemoryError -Duser.timezone=America/Bahia_Banderas -Dhive.security=legacy`. - * Working directory: `$MODULE_DIR$` - * Environment variables: `PRESTO_SERVER=/Users//git/presto/presto-native-execution/cmake-build-debug/presto_cpp/main/presto_server;DATA_DIR=/Users//Desktop/data;WORKER_COUNT=0` - * Use classpath of module: choose `presto-native-execution` module. - -Run IcebergExternalWorkerQueryRunner, -* Edit/Create `IcebergExternalWorkerQueryRunner` Application Run/Debug Configuration (alter paths accordingly). - * Main class: `com.facebook.presto.nativeworker.IcebergExternalWorkerQueryRunner`. - * VM options: `-ea -Xmx5G -XX:+ExitOnOutOfMemoryError -Duser.timezone=America/Bahia_Banderas -Dhive.security=legacy`. - * Working directory: `$MODULE_DIR$` - * Environment variables: `PRESTO_SERVER=/Users//git/presto/presto-native-execution/cmake-build-debug/presto_cpp/main/presto_server;DATA_DIR=/Users//Desktop/data;WORKER_COUNT=0` - * When `addStorageFormatToPath = false` **(Default)**, - - `$DATA_DIR/iceberg_data/`. Here `catalog_type` could be `HIVE | HADOOP | NESSIE | REST`. - - `addStorageFormatToPath` is `false` by default because Java `HiveQueryRunner` and `IcebergQueryRunner` do not add the file format to the path. - * When `addStorageFormatToPath = true`, - - `$DATA_DIR/iceberg_data//`. Here `file_format` could be `PARQUET | ORC | AVRO` and `catalog_type` could be `HIVE | HADOOP | NESSIE | REST`. - * Use classpath of module: choose `presto-native-execution` module. - -Run CLion: -* File->Close Project if any is open. -* Open `presto/presto-native-execution` directory as CMake project and wait till CLion loads/generates cmake files, symbols, etc. -* Edit configuration for `presto_server` module (alter paths accordingly). - * Program arguments: `--logtostderr=1 --v=1 --etc_dir=/Users//git/presto/presto-native-execution/etc` - * Working directory: `/Users//git/presto/presto-native-execution` -* Edit menu CLion->Preferences->Build, Execution, Deployment->CMake - * CMake options: `-DVELOX_BUILD_TESTING=ON -DCMAKE_BUILD_TYPE=Debug` - * Build options: `-- -j 12` - * Optional CMake options to enable Parquet and S3: `-DPRESTO_ENABLE_PARQUET=ON -DPRESTO_ENABLE_S3=ON` -* Edit menu CLion->Preferences->Editor->Code Style->C/C++ - * Scheme: `Project` -* To enable clang format you need - * Open any h or cpp file in the editor and select `Enable ClangFormat` by clicking `4 spaces` rectangle in the status bar (bottom right) which is next to `UTF-8` bar. - - ![ScreenShot](cl_clangformat_switcherenable.png) - -### Run Presto Coordinator + Worker -* Note that everything below can be done without using IDEs by running command line commands (not in this readme). -* Run QueryRunner as per your choice, - * For Hive, Run `HiveExternalWorkerQueryRunner` from IntelliJ and wait until it starts (`======== SERVER STARTED ========` is displayed in the log output). - * For Iceberg, Run `IcebergExternalWorkerQueryRunner` from IntelliJ and wait until it starts (`======== SERVER STARTED ========` is displayed in the log output). -* Scroll up the log output and find `Discovery URL http://127.0.0.1:50555`. The port is 'random' with every start. -* Copy that port (or the whole URL) to the `discovery.uri` field in `presto/presto-native-execution/etc/config.properties` for the worker to discover the Coordinator. -* In CLion run "presto_server" module. Connection success will be indicated by `Announcement succeeded: 202` line in the log output. -* Two ways to run Presto client to start executing queries on the running local setup: - 1. In command line from presto root directory run the presto client: - * `java -jar presto-cli/target/presto-cli-*-executable.jar --catalog hive --schema tpch` - 2. Run `Presto Client` Application (see above on how to create and setup the configuration) inside IntelliJ -* You can start from `show tables;` and `describe table;` queries and execute more queries as needed. - -### Run Integration (End to End or E2E) Tests -* Note that everything below can be done w/o using IDEs by running command line commands (not in this readme). -* Open a test file which has the test(s) you want to run in IntelliJ from `presto/presto-native-execution/src/test/java/com/facebook/presto/nativeworker` path. -* Click the green arrow to the left of the test class line of code and chose if you want to Run or Debug. This will run all tests in this class. -* Alternatively click the green arrow to the left of the test class' test method line of code and chose if you want tor Run or Debug. This will run all tests only in this class's member. -* The framework will launch single Coordinator and four native workers to test-run the queries. -* Similarly, the unit tests of Velox and presto_cpp can be run from CLion. - -### Code formatting, headers, and clang-tidy - -Makefile targets exist for showing, fixing and checking formatting, license -headers and clang-tidy warnings. These targets are shortcuts for calling -`presto/presto-native-execution/scripts/check.py` . - -GitHub Actions run `make format-check`, `make header-check` and -`make tidy-check` as part of our continuous integration. Pull requests should -pass linux-build, format-check, header-check and other jobs without errors -before being accepted. - -Formatting issues found on the changed lines in the current commit can be -displayed using `make format-show`. These issues can be fixed by using `make -format-fix`. This will apply formatting changes to changed lines in the -current commit. - -Header issues found on the changed files in the current commit can be displayed -using `make header-show`. These issues can be fixed by using `make -header-fix`. This will apply license header updates to the files in the current -commit. - -Similar commands `make tidy-show`, `make-tidy-fix`, `make tidy-check` exist for -running clang-tidy, but these checks are currently advisory only. - -An entire directory tree of files can be formatted and have license headers added -using the `tree` variant of the format.sh commands: -``` -presto/presto-native-execution/scripts/check.py format tree -presto/presto-native-execution/scripts/check.py format tree --fix - -presto/presto-native-execution/scripts/check.py header tree -presto/presto-native-execution/scripts/check.py header tree --fix -``` - -All the available formatting commands can be displayed by using -`presto/presto-native-execution/scripts/check.py help`. - -There is currently no mechanism to *opt out* files or directories from the -checks. When we need one it can be added. - -## Create Pull Request -* Submit PRs as usual following [Presto repository guidelines](https://github.com/prestodb/presto/wiki/Review-and-Commit-guidelines). -* Prestissimo follows the Velox [coding style](https://github.com/facebookincubator/velox/blob/main/CODING_STYLE.md). -* Add `[native]` prefix in the `title` as well as to the `commit message` for PRs modifying anything in `presto-native-execution`. -* PRs that only change files in `presto-native-execution` should be approved by a Code Owner ([team-velox](https://github.com/orgs/prestodb/teams/team-velox)) to have merging enabled. - -## Advance Velox Version -For Prestissimo to use a newer Velox version from the Presto repository root: -* `git -C presto-native-execution/velox checkout main` -* `git -C presto-native-execution/velox pull` -* `git add presto-native-execution/velox` -* Build and run tests (including E2E) to ensure everything works. -* Submit a PR, get it approved and merged. - -## Functional test using containers -To build container images and do functional tests, see [Prestissimo: Functional Testing Using Containers](testcontainers/README.md). - -## Troubleshooting -For known build issues check the wiki page [Troubleshooting known build issues](https://github.com/prestodb/presto/wiki/Troubleshooting-known-build-issues). +=================== +Presto C++ Features +=================== + +.. contents:: +:local: +:backlinks: none +:depth: 1 + +Endpoints +--------- + +HTTP endpoints related to tasks are registered to Proxygen in +`TaskResource.cpp`. Important endpoints implemented include: + +* POST: v1/task: This processes a `TaskUpdateRequest` +* GET: v1/task: This returns a serialized `TaskInfo` (used for comprehensive + metrics, may be reported less frequently) +* GET: v1/task/status: This returns + a serialized `TaskStatus` (used for query progress tracking, must be reported + frequently) + +Other HTTP endpoints include: + +* POST: v1/memory: Reports memory, but no assignments are adjusted unlike in Java workers +* GET: v1/info/metrics: Returns worker level metrics in Prometheus Data format. Refer section Worker Metrics Collection for more info. Here is a sample Metrics data returned by this API. + + .. code-block:: text + + # TYPE presto_cpp_num_http_request counter + presto_cpp_num_http_request{cluster="testing",worker=""} 0 + # TYPE presto_cpp_num_http_request_error counter + presto_cpp_num_http_request_error{cluster="testing",worker=""} 0 + # TYPE presto_cpp_memory_pushback_count counter + presto_cpp_memory_pushback_count{cluster="testing",worker=""} 0 + # TYPE velox_driver_yield_count counter + velox_driver_yield_count{cluster="testing",worker=""} 0 + # TYPE velox_cache_shrink_count counter + velox_cache_shrink_count{cluster="testing",worker=""} 0 + # TYPE velox_memory_cache_num_stale_entries counter + velox_memory_cache_num_stale_entries{cluster="testing",worker=""} 0 + # TYPE velox_arbitrator_requests_count counter + velox_arbitrator_requests_count{cluster="testing",worker=""} 0 + + +* GET: v1/info: Returns basic information about the worker. Here is an example: + + .. code-block:: text + + {"coordinator":false,"environment":"testing","nodeVersion":{"version":"testversion"},"starting":false,"uptime":"49.00s"} + +* GET: v1/status: Returns memory pool information. + +The request/response flow of Presto C++ is identical to Java workers. The tasks or new splits are registered via `TaskUpdateRequest`. Resource utilization and query progress are sent to the coordinator via task endpoints. + +Remote Function Execution +------------------------- + +Presto C++ supports remote execution of scalar functions. This feature is +useful for cases when the function code is not written in C++, or if for +security or flexibility reasons, the function code cannot be linked to the same +executable as the main engine. + +Remote function signatures need to be provided using a JSON file, following +the format implemented by `JsonFileBasedFunctionNamespaceManager +`_. +The following properties allow the configuration of remote function execution: + +``remote-function-server.signature.files.directory.path`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``string`` +* **Default value:** ``""`` + +The local filesystem path where JSON files containing remote function +signatures are located. If not empty, the Presto native worker will +recursively search, open, parse, and register function definitions from +these JSON files. + +``remote-function-server.catalog-name`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``string`` +* **Default value:** ``""`` + +The catalog name to be added as a prefix to the function names registered +in Velox. The function name pattern registered is +``catalog.schema.function_name``, where ``catalog`` is defined by this +parameter, and ``schema`` and ``function_name`` are read from the input +JSON file. + +If empty, the function is registered as ``schema.function_name``. + +``remote-function-server.serde`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``string`` +* **Default value:** ``"presto_page"`` + +The serialization/deserialization method to use when communicating with +the remote function server. Supported values are ``presto_page`` or +``spark_unsafe_row``. + +``remote-function-server.thrift.address`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``string`` +* **Default value:** ``""`` + +The location (ip address or hostname) that hosts the remote function +server, if any remote functions were registered using +``remote-function-server.signature.files.directory.path``. +If not specified, falls back to the loopback interface (``::1``) + +``remote-function-server.thrift.port`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``integer`` +* **Default value:** ``0`` + +The port that hosts the remote function server. If not specified and remote +functions are trying to be registered, an exception is thrown. + +``remote-function-server.thrift.uds-path`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``string`` +* **Default value:** ``""`` + +The UDS (unix domain socket) path to communicate with a local remote +function server. If specified, takes precedence over +``remote-function-server.thrift.address`` and +``remote-function-server.thrift.port``. + +JWT authentication support +-------------------------- + +C++ based Presto supports JWT authentication for internal communication. +For details on the generally supported parameters visit `JWT <../security/internal-communication.html#jwt>`_. + +There is also an additional parameter: + +``internal-communication.jwt.expiration-seconds`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type** ``integer`` +* **Default value:** ``300`` + +There is a time period between creating the JWT on the client +and verification by the server. +If the time period is less than or equal to the parameter value, the request +is valid. +If the time period exceeds the parameter value, the request is rejected as +authentication failure (HTTP 401). + +Async Data Cache and Prefetching +-------------------------------- + +``connector.num-io-threads-hw-multiplier`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type** ``double`` +* **Default value:** ``1.0`` +* **Presto on Spark default value:** ``0.0`` + +Size of IO executor for connectors to do preload/prefetch. Prefetch is +disabled if ``connector.num-io-threads-hw-multiplier`` is set to zero. + +``async-data-cache-enabled`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type** ``bool`` +* **Default value:** ``true`` +* **Presto on Spark default value:** ``false`` + +Whether async data cache is enabled. + +``async-cache-ssd-gb`` +^^^^^^^^^^^^^^^^^^^^^^ + +* **Type** ``integer`` +* **Default value:** ``0`` + +Size of the SSD cache when async data cache is enabled. + +``enable-old-task-cleanup`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type** ``bool`` +* **Default value:** ``true`` +* **Presto on Spark default value:** ``false`` + +Enable periodic clean up of old tasks. The default value is ``true`` for Presto C++. +For Presto on Spark this property defaults to ``false``, as zombie or stuck tasks +are handled by Spark by speculative execution. + +``old-task-cleanup-ms`` +^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type** ``integer`` +* **Default value:** ``60000`` + +Duration after which a task should be considered as old and will be eligible +for cleanup. Only applicable when ``enable-old-task-cleanup`` is ``true``. +Old task is defined as a PrestoTask which has not received heartbeat for at least +``old-task-cleanup-ms``, or is not running and has an end time more than +``old-task-cleanup-ms`` ago. + +Worker metrics collection +------------------------- + +Users can enable collection of worker level metrics by setting the property: + +``runtime-metrics-collection-enabled`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +* **Type:** ``boolean`` +* **Default value:** ``false`` + + When true, the default behavior is a no-op. There is a prior setup that must be done before enabling this flag. To enable + metrics collection in Prometheus Data Format refer `here `_. + +Session Properties +------------------ + +The following are the native session properties for C++ based Presto. + +``driver_cpu_time_slice_limit_ms`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``integer`` +* **Default value:** ``1000`` + +Native Execution only. Defines the maximum CPU time in milliseconds that a driver thread +is permitted to run before it must yield to other threads,facilitating fair CPU usage across +multiple threads. + +A positive value enforces this limit, ensuring threads do not monopolize CPU resources. + +Negative values are considered invalid and are treated as a request to use the system default setting, +which is ``1000`` ms in this case. + +Note: Setting the property to ``0`` allows a thread to run indefinitely +without yielding, which is not recommended in a shared environment as it can lead to +resource contention. + +``legacy_timestamp`` +^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``boolean`` +* **Default value:** ``true`` + +Native Execution only. Use legacy TIME and TIMESTAMP semantics. + +``native_aggregation_spill_memory_threshold`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``integer`` +* **Default value:** ``0`` + +Native Execution only. Specifies the maximum memory in bytes +that a final aggregation operation can utilize before it starts spilling to disk. +If set to ``0``, there is no limit, allowing the aggregation to consume unlimited memory resources, +which may impact system performance. + +``native_debug_validate_output_from_operators`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``boolean`` +* **Default value:** ``false`` + +If set to ``true``, then during the execution of tasks, the output vectors of every operator are validated for consistency. +It can help identify issues where a malformed vector causes failures or crashes, facilitating the debugging of operator output issues. + +Note: This is an expensive check and should only be used for debugging purposes. + +``native_join_spill_enabled`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``boolean`` +* **Default value:** ``true`` + +Native Execution only. Enable join spilling on native engine. + +``native_join_spill_memory_threshold`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``integer`` +* **Default value:** ``0`` + +Native Execution only. Specifies the maximum memory, in bytes, that a hash join operation can use before starting to spill to disk. +A value of ``0`` indicates no limit, permitting the join operation to use unlimited memory resources, which might affect overall system performance. + +``native_join_spiller_partition_bits`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``integer`` +* **Default value:** ``2`` + +Native Execution only. Specifies the number of bits (N) +used to calculate the spilling partition number for hash join and RowNumber operations. +The partition number is determined as ``2`` raised to the power of N, defining how data is partitioned during the spill process. + +``native_max_spill_file_size`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``integer`` +* **Default value:** ``0`` + +Specifies the maximum allowed spill file size in bytes. If set to ``0``, there is no limit on the spill file size, +allowing spill files to grow as large as necessary based on available disk space. +Use ``native_max_spill_file_size`` to manage disk space usage during operations that require spilling to disk. + +``native_max_spill_level`` +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``integer`` +* **Default value:** ``4`` + +Native Execution only. The maximum allowed spilling level for hash join build. +``0`` is the initial spilling level, ``-1`` means unlimited. + +``native_order_by_spill_memory_threshold`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``integer`` +* **Default value:** ``0`` + +Native Execution only. Specifies the maximum memory, in bytes, that the `ORDER BY` operation can utilize before starting to spill data to disk. +If set to ``0``, there is no limit on memory usage, potentially leading to large memory allocations for sorting operations. +Use this threshold to manage memory usage more efficiently during `ORDER BY` operations. + +``native_row_number_spill_enabled`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``boolean`` +* **Default value:** ``true`` + +Native Execution only. Enable row number spilling on native engine. + +``native_simplified_expression_evaluation_enabled`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``boolean`` +* **Default value:** ``false`` + +Native Execution only. Enable simplified path in expression evaluation. + +``native_spill_compression_codec`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``varchar`` +* **Default value:** ``none`` + +Native Execution only. Specifies the compression CODEC used to compress spilled data. +Supported compression CODECs are: ZLIB, SNAPPY, LZO, ZSTD, LZ4, and GZIP. +Setting this property to ``none`` disables compression. + +``native_spill_file_create_config`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``varchar`` +* **Default value:** ``""`` + +Native Execution only. Specifies the configuration parameters used to create spill files. +These parameters are provided to the underlying file system, allowing for customizable spill file creation based on the requirements of the environment. +The format and options of these parameters are determined by the capabilities of the underlying file system +and may include settings such as file location, size limits, and file system-specific optimizations. + +``native_spill_write_buffer_size`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``bigint`` +* **Default value:** ``1048576`` + +Native Execution only. The maximum size in bytes to buffer the serialized spill data before writing to disk for IO efficiency. +If set to ``0``, buffering is disabled. + +``native_topn_row_number_spill_enabled`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``boolean`` +* **Default value:** ``true`` + +Native Execution only. Enable topN row number spilling on native engine. + +``native_window_spill_enabled`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``boolean`` +* **Default value:** ``true`` + +Native Execution only. Enable window spilling on native engine. + +``native_writer_spill_enabled`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Type:** ``boolean`` +* **Default value:** ``true`` + +Native Execution only. Enable writer spilling on native engine.