从源代码出发，Jenkins 任务排队时间过长问题的解决过程

深藏阁楼爱情的钟 2024-02-17 11:56 120阅读 0赞

最近开发了一个部署相关的工具，使用 Jenkins 来构建应用。Jenkins 的任务从模板中创建而来。每次部署时，通过 Jenkins API 来触发构建任务。在线上运行时发现，通过 API 触发的 Jenkins 任务总是会时不时在队列中等待较长的时间。某些情况下的等待时间甚至长达几分钟。直接在 Jenkins 界面上触发的任务却几乎不需要排队，直接马上就可以执行。过长的等待时间影响了构建的效率，这是一个急需解决的问题。这个问题奇怪的地方在于，手动从界面上触发的任务几乎不需要排队，而 API 触发的任务的排队时间则完全随机，毫无规律可言。

![494f9a6e5f9311d241be67ed537ad5df.jpeg][]

当任务在队列中时，Jenkins 会在界面上显示该任务在队列中等待的原因。对于 API 创建的任务，它们的等待原因是“Finished waiting”。从这个原因的字面含义确实看不出来什么。当出现这样的问题时，最直接的办法是从源代码中寻找答案。

从 GitHub 上把 Jenkins 的源代码下载到本地。寻找问题的起点是搜索字符串“Finished waiting”。这个字符串定义在资源包（resource bundle）中，对应的键是 `Queue.FinishedWaiting`。再搜索使用了这个键的代码，定位到了类 `hudson.model.Queue`。从名字可以看出来，这个类表示的是 Jenkins 内部的工作队列。在这个类中定义了可能出现在队列中的不同类型的条目。类 `WaitingItem` 表示的是处于等待状态的条目。这个类的 `getCauseOfBlockage()`方法刚好用到了`Queue.FinishedWaiting` 这个键，表示当前条目被阻塞的原因。这个 `WaitingItem` 类是主要的调查目标。

`WaitingItem` 类中有 `enter()` 和 `leave()` 两个方法，分别表示该条目进入队列和离开队列。看起来那些等待时间过长的任务，在进入了队列之后，经过很长一段时间，它们的 `leave()` 方法才被调用。

![b39845fd0bd5a44deba4da73ba648e43.jpeg][]

继续追踪这两个方法的调用，会发现 `enter()` 方法在 `scheduleInternal()` 中被调用，用来调度新的任务。而 `leave()` 方法则在 `maintain()` 中被调用，用来在合适的时机从队列中移除任务并执行。所以看起来问题是出在 `maintain()` 方法中。

`maintain()` 方法负责维护队列，并把任务在不同的状态中移动。当有可能影响到任务调度的情况发生时，Jenkins 会在内部调用这个方法。在 `scheduleInternal()` 方法中，把新的任务添加到队列之后，它会调用 `scheduleMaintenance()` 方法提交一个 `Runnable` 任务来调用 `maintain()` 方法。

![3f73c17367fecdfb82a2797b1bf69815.jpeg][]

经过上面的分析，任务等待时间过长的原因可能是，`maintain()` 方法被调用时，并没有发现处于等待的任务。所以这个任务需要等到下一次 `maintain()` 方法调用时才会被执行。这中间可能有与时序相关的问题。

--------------------

问题找到了之后，下一步考虑的是怎么解决问题。如果要从根本上解决问题，应该从 Jenkins 入手，尝试在 Jenkins 中找到问题发生的根源，并进行修复。这种方案要求对 Jenkins 的代码库有足够程度的了解，在本地构建开发环境，并尝试稳定地复现问题。找到问题并解决之后，还需要添加 Pull Request 到 Jenkins 的代码库，并等待新版本的发布。整个过程耗时漫长。作为 Jenkins 的使用者，我自己并没有太大的意愿去花费精力在 Jenkins 自身的问题上。这种与时序有关的问题，很难复现和调试。我需要的是一个能够有效解决问题的 workaround。

前面提到了，产生问题的原因是 `maintain()` 方法在执行时可能没有发现等待中的任务。那么解决的办法可以很直接，那就是每次提交任务之后，等待几秒钟，再调用一次 `maintain()` 方法。这样就可以确保 `maintain()` 方法能够发现等待中的任务。`maintain()` 方法是由 `scheduleMaintenance()` 方法调用的，而 `scheduleMaintenance()` 是 `Queue` 类的一个公开方法。我只需要能够调用这个 `scheduleMaintenance()` 方法就可以了。

Jenkins 有一个叫做脚本控制台的功能，可以在运行的 Jenkins 实例上执行 Groovy 脚本。Groovy 脚本可以直接对运行的 Jenkins 实例进行修改。

![02161d8fbd8bfb7a26137f7b158b37ea.jpeg][]

每个 Jenkins 运行的实例中，`Queue` 对象只有一个。只需要找到这个 `Queue` 对象，并调用其中的 `scheduleMaintenance()` 方法，问题就解决了。脚本控制台已经内置提供了很多 Jenkins 的对象。实际上需要执行的代码很简单。

Jenkins.instance.queue.scheduleMaintenance()

通过在脚本控制台进行测试，发现只要执行了上述的脚本，原本在队列中的任务，马上就可以被调度执行。这也证明了问题确实解决了。

最后一个问题是如何把对 `scheduleMaintenance()` 的调用自动化，也就是在每次通过 API 触发了任务，等待几秒钟之后，自动调用 `scheduleMaintenance()` 方法。Jenkins 的脚本控制台并没有提供公开的 API。我采取的做法是用 HTTP 客户端模拟脚本控制台界面上的操作。脚本控制台的界面在运行脚本时，实际上执行了一个表单提交动作。这个表单被提交到了网址 `<jenkins_url>/computer/(built-in)/script`，内容类型是 `application/x-www-form-urlencoded`。请求中只需要包含一个参数 `script`，表示需要执行的脚本内容。Jenkins 使用的是 BASIC 认证，需要把访问的用户名和密码包含在请求中。使用 HTTP 客户端模拟上述请求并不难。

下面给出了使用 Spring RestTemplate 执行 Groovy 脚本的代码示例。

var headers = new HttpHeaders();
    headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
    var authentication = "Basic " + Base64.getEncoder()
        .encodeToString(String.format("%s:%s", username, password).getBytes(StandardCharsets.UTF_8));
    headers.add("Authorization", authentication);
    MultiValueMap<String, String> map = new LinkedMultiValueMap<>();
    map.add("script", "Jenkins.instance.queue.scheduleMaintenance()");
    var entity = new HttpEntity<>(map, headers);
    try {
      restTemplate.exchange(
          String.format("%s/computer/(built-in)/script", jenkinsUrl),
          HttpMethod.POST, entity,
          String.class);
    } catch (Exception e) {
      // 处理异常
    }

至此，Jenkins 任务排队时间过长的问题得到了解决。虽然并没有从根本上解决问题，但已经是一个在有限的时间内可以完成的不错的解法。

[494f9a6e5f9311d241be67ed537ad5df.jpeg]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/06/dbcde91853c74edea00a088b4fe771d2.png
[b39845fd0bd5a44deba4da73ba648e43.jpeg]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/06/2e4e5563436b4703a96c17a4f3c7751d.png
[3f73c17367fecdfb82a2797b1bf69815.jpeg]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/06/07224e338e5347b8b289065e750d0890.png
[02161d8fbd8bfb7a26137f7b158b37ea.jpeg]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/06/64f1056b626d4f778f96e3d01220e247.png