Coiled Runtime

Coiled Runtime是一个conda元包，它使得开始使用Dask变得简单。

安装

coiled-runtime可以使用conda安装

conda install -c conda-forge coiled-runtime

或使用pip

pip install coiled-runtime

夜间构建

coiled-runtime有用于测试目的的夜间conda包。您可以使用以下命令安装coiled-runtime的夜间版本

conda install -c coiled/label/dev -c dask/label/dev coiled-runtime 

构建

要本地构建和安装coiled-runtime，请按照以下步骤操作

# Have a local copy of the `coiled-runtime` repository
git clone https://github.com/coiled/coiled-runtime
cd coiled-runtime

# Make sure conda-build is installed
conda install -c conda-forge conda-build

# Build the metapackage
conda build recipe -c conda-forge --output-folder dist/conda --no-anaconda-upload

# Install the built `coiled-runtime` metapackage
conda install -c ./dist/conda/ -c conda-forge coiled-runtime

测试

以下是运行 coiled-runtime 测试套件的本地步骤：

1. 确保您的本地机器已认证可以使用 dask-engineering Coiled 账户和 Coiled Dask Engineering AWS S3 账户。
2. 创建一个 Python 环境，并安装 ci/environment.yml 中指定的开发依赖项。
3. 安装一个 Coiled 运行时环境。这可能来自 environments/ 中列出的环境之一，或者如果您正在测试 dask 或 distributed 的功能分支，它可能是一个开发环境。此测试套件配置为运行 Coiled 的 package_sync 功能，因此您的本地环境应复制到集群。
4. 使用 python -m pytest tests 运行测试

此外，当向此存储库提交拉取请求时，会自动运行测试。请参阅下面的创建拉取请求部分。

基准测试

coiled-runtime 测试套件包含一系列 pytest 修复程序，这些修复程序可以收集和存储基准测试指标，用于历史和回归分析。默认情况下，这些指标不会被收集和存储，但您可以在 pytest 调用中包含 --benchmark 标志来启用它们。

从高层次来看，基准测试是这样工作的：

• 从单个测试运行中收集数据并存储在本地 sqlite 数据库中。该数据库的模式存储在 benchmark_schema.py 中。
• 本地 sqlite 数据库追加到全局历史记录中，该记录存储在 S3。
• 可以使用各种工具分析历史数据。《dashboard.py》创建一系列静态 HTML 文档，显示测试的历史数据。

在本地运行基准测试

您可以通过使用 --benchmark 标志运行 pytest 来收集基准测试数据。这将创建一个位于存储库根目录的本地 benchmark.db sqlite 文件。如果您使用基准测试多次运行测试套件，数据将追加到数据库中。

您可以通过首先从 S3 下载全局数据库来比较历史数据。

aws s3 cp s3://coiled-runtime-ci/benchmarks/benchmark.db ./benchmark.db
pytest --benchmark

更改基准模式

您可以通过编辑 benchmark_schema.py 中的 SQLAlchemy 模式来添加、删除或修改列。但是，如果您有一个历史数据数据库，则新数据和旧数据模式的架构将不匹配。为了解决这个问题，您必须提供数据迁移并提交到存储库。我们使用 alembic 来管理 SQLAlchemy 迁移。在简单的情况下，仅向架构中添加或删除列，可以执行以下操作

# First, edit the `benchmark_schema.py` and commit the changes.

alembic revision --autogenerate -m "Description of migration"
git add alembic/versions/name_of_new_migration.py
git commit -m "Added a new migration"

迁移在 pytest 运行中自动应用，因此您无需自行运行它们。

删除旧测试数据

有时您可能会更改特定的测试，这使得旧的基准测试数据变得无关紧要。在这种情况下，您可以通过应用删除该数据的数据迁移来丢弃该测试的旧基准测试数据

alembic revision -m "Declare bankruptcy for <test-name>"
# Edit the migration here to do what you want.
git add alembic/versions/name_of_new_migration.py
git commit -m "Bankruptcy migration for <test-name>"

执行此操作的迁移示例在此处。

使用基准修复程序

我们定义了多个 pytest 修复程序，可以用于自动跟踪基准数据库中的某些指标。最相关的总结如下：

benchmark_time：记录墙上时钟时间持续时间。

benchmark_memory：记录内存使用情况。

benchmark_task_durations：记录计算、传输数据、将数据溢出到磁盘和反序列化数据所花费的时间。

auto_benchmark_time：包含此修复程序来自动测量整个测试的墙上时钟时间。

benchmark_all：记录所有可用的指标。

有关所有可用的修复程序及其使用示例的更多信息，请参阅其文档。

编写新的基准修复程序通常如下所示：

1. 请求 test_run_benchmark 修复程序，它产生一个 ORM 对象。
2. 进行所需的任何设置工作。
3. 将控制权交由测试
4. 测试完成后收集所需的信息。
5. 在 ORM 对象上设置适当的属性。

benchmark_time 固定装置提供了一个相当简单的示例。

调查性能退步

一个看似的性能退步的原因并不总是很明显。这可能是因为直接或间接依赖项的新版本，也可能是因为 Coiled 平台的变化。但通常是因为 dask 或 distributed 的变化。如果你怀疑是这样的话，Coiled 的 package_sync 功能与这里的基准测试基础设施以及 git bisect 结合得很好。

以下是一个示例工作流程，可用于识别引入性能退步的 dask 的特定提交。此工作流程假设你打开了两个终端窗口，一个包含 coiled-runtime 测试套件，另一个包含用于驱动 bisecting 的 dask 仓库。

创建你的软件环境

你应该创建一个可以运行此测试套件的软件环境，但带有可编辑安装的 dask。你可以用多种方式做到这一点，但一种方法可以是

conda env create -n test-env --file ci/environment.yml  # Create a test environment
conda activate test-env  # Activate your test environment
pip install .  # Install the `coiled-runtime` metapackage dependencies.
(cd <your-dask-dir> && pip install -e .)  # Do an editable install for dask

开始 bisecting

假设 dask 的当前 HEAD 已知是坏的，而 $REF 已知是好的。如果你在查看可以访问静态页面的上游运行，你可以检查每个运行的日期报告，并使用相应的日期执行 git log，以获取用于 bisecting 过程的提交列表。

git log --since='2022-08-15 14:15' --until='2022-08-18 14:15' --pretty=oneline 在打开到你的 dask 仓库的终端中，你可以使用以下命令初始化 bisect 工作流程

cd <your-dask-dir>
git bisect start
git bisect bad
git bisect good $REF

测试退步

现在你的可编辑安装正在 bisecting，请在 coiled-runtime 终端中运行测试或测试子集，以证明退步。假设 tests/benchmarks/test_parquet.py::test_write_wide_data 是这样的测试

pytest tests/benchmarks/test_parquet.py::test_write_wide_data --benchmark

一旦测试完成，它将在本地的 sqlite 文件 benchmark.db 中写入一条新记录。你将想要检查该条目是否显示退步。确切地检查方式将取决于测试和退步。你可能有一个从 benchmark.db 构建图表的脚本，类似于 dashboard.py，或者一个执行某种类型统计分析的脚本。但让我们假设一个更简单的情况，你可以从 average_memory 中识别它。你可以用以下方式查询它

sqlite3 benchmark.db "select dask_version, average_memory from test_run where name = 'test_write_wide_data';"

如果最后一条记录显示了退步，将 dask 终端的提交标记为 bad

git bisect bad

如果最后一条记录没有显示退步，将 dask 终端的提交标记为 good

git bisect good

继续这个过程，直到你缩小到单个提交。恭喜！你已经确定了退步的根源。

A/B 测试

可以运行 Coiled Runtime 基准测试以进行 A/B 比较。请参阅完整的文档。

贡献

此存储库使用 GitHub Actions 密钥管理用于访问资源（如 Coiled 集群、S3 存储桶等）的认证令牌。然而，由于 GitHub Actions 不授予对 forked 存储库的密钥访问权限，请直接从 coiled/coiled-runtime 存储库提交拉取请求，而不是个人 fork。

发布

要发布新的 coiled-runtime 版本

1. 在本地更新 coiled-runtime 版本和 recipe/meta.yaml 中指定的包锁定。
   • 在更新包版本锁定时（特别是 dask 和 distributed），请确认在 dask / distributed 问题跟踪器或离线报告中没有报告大规模稳定性问题（例如死锁）或性能退步。
2. 向 coiled-runtime 仓库提交一个名为 "发布 X.Y.Z" 的拉取请求，其中包含这些更改（X.Y.Z 将替换为实际版本号）。
3. 所有 CI 构建通过后，可以合并发布拉取请求。
4. 按照以下步骤在本地机器上为发布添加一个新的 git 标签

# Pull in changes from the Release X.Y.Z PR
git checkout main
git pull origin main

# Set release version number
export RELEASE=X.Y.Z
# Create and push release tag
git tag -a $RELEASE -m "Version $RELEASE"
git push origin main --tags

5. 通过向 coiled-runtime conda-forge feedstock 提交拉取请求来更新 conda-forge 上的 coiled-runtime 包，这将更新 coiled-runtime 版本和包版本锁定。
   • 注意，向 conda-forge feedstock 提交的拉取请求必须来自分叉。
   • 如果构建号还没有重置，请将其重置为 0。
   • 有关更新 conda-forge 包的更多信息，请参阅 conda-forge 文档。

许可证

BSD-3