# Logstash管道热停止失败的排查方法
#### 问题描述
Logstash集群通过logstash-output-elasticsearch插件向目的端Elasticsearch集群写入数据。在通过热停止功能更新管道配置时，热停止执行失败，管道阻塞无法正常关闭，运行日志中出现"The shutdown process appears to be stalled due to busy or blocked plugins"报错信息。
#### 排查思路
表1可能原因与排查方法 
| 序号 | 可能原因         | 关键报错特征                                | 处理措施                                                                            |
|:---|:---|:---|:---|
| 1  | 目的端索引被设置为只读  | HTTP 403 + cluster_block_exception    | 详细操作请参见[原因一：目的端索引只读]          |
| 2  | 目的端集群JVM内存熔断 | HTTP 429 + circuit_breaking_exception | 详细操作请参见[原因二：目的端集群JVM内存熔断] |
   
1. 登录[云搜索服务管理控制台](https://console.huaweicloud.com/elasticsearch/)。
2. 在左侧导航栏选择"集群管理 \> Logstash"。
3. 在集群列表单击目标集群名称，进入集群详情页。
4. 选择"配置中心"页签，在管道列表单击上方的"运行日志"。
5. 在运行日志中搜索报错信息。
   - **目的端索引只读的典型报错日志示例**
     - 写入阶段：
       ```
       [2026-07-31T08:30:38,426][ERROR][logstash.outputs.elasticsearch][pipeline.name][plugin.id] Encountered a retryable error. Will Retry with exponential backoff  {:code=>403, :url=>"http://xx.xx.xx.xx:9200/_bulk"}
       .
       .
       .
       [2026-07-31T06:39:25,387][INFO ][logstash.outputs.elasticsearch][pipeline.name][plugin.id] retrying failed action with response code: 403 ({"type"=>"cluster_block_exception", "reason"=>"index [target_index_name] blocked by: [FORBIDDEN/8/index write (api)];"})
       ```
       
     
     - 热停止阶段：
       ```
       [2026-07-31T06:33:21,217][ERROR][org.logstash.execution.ShutdownWatcherExt] The shutdown process appears to be stalled due to busy or blocked plugins. Check the logs for more information.
       ```
       
      
   
   - **目的端集群JVM内存熔断的典型报错日志示例**
     - 写入阶段：
       ```
       [2026-07-31T08:30:38,426][ERROR][logstash.outputs.elasticsearch][pipeline.name][plugin.id] Encountered a retryable error. Will Retry with exponential backoff  {:code=>429, :url=>"http://xx.xx.xx.xx:9200/_bulk"}
       .
       .
       .
       [2026-07-31T06:39:25,387][INFO ][logstash.outputs.elasticsearch][pipeline.name][plugin.id] retrying failed action with response code: 429 ({"type"=>"circuit_breaking_exception", "reason"=>"fake circuit break here!!!!!!"bytes_wanted"=>0, "bytes_limit"=>0", "durability"=>"TRANSIENT"})
       ```
       
     
     - 热停止阶段：
       ```
       [2026-07-31T08:31:13,951][ERROR][org.logstash.execution.ShutdownWatcherExt] The shutdown process appears to be stalled due to busy or blocked plugins. Check the logs for more information.
       ```
       
      
    
 
 #### 原因一：目的端索引只读
目的端索引的"index.blocks.write"属性被设置为"true"，Logstash写入数据时写入阻塞（Write Block）收到HTTP 403拒绝错误，logstash-output-elasticsearch插件将403视为可重试错误并持续重试。由于重试循环未检查"@stopping"标志位，热停止会等待管道内正在处理的事件全部处理完再关闭管道，但事件因持续重试始终无法处理完成，管道阻塞超时。
**处理措施：**
1. 在运行日志中搜索403或cluster_block_exception关键字。 如运行日志中存在HTTP 403错误且包含cluster_block_exception，则确认为原因一，请顺序执行后续步骤解决。
   
2. 强制停止管道。
   ![](https://support.huaweicloud.com/trouble-css/public_sys-resources/warning_3.0-zh-cn.png)
   全部停止会直接中断集群内所有正在运行的管道任务，正在传输中的数据可能出现短暂延迟或位点重置，请确保源端数据具备可追溯性。
   1. 在配置中心页面，单击管道列表上方的"全部停止"。
   
   2. 在对话框中，单击"确定"，停止所有管道的数据迁移任务。
   
   3. 观察管道列表的"运行状态"列，确认所有管道状态均显示为"已停止"。
    
3. 解除目的端索引只读状态。 登录目的端Elasticsearch集群的Kibana页面，在"Dev Tools"中执行以下命令，解除索引只读状态：
   ```
   PUT <索引名称>/_settings
   {
     "index.blocks.write": false
   }
   ```
   
4. 重新启动管道任务。
   1. 在配置中心页面的配置文件列表中，勾选需要启动的配置文件，单击上方的"启动"。
   
   2. 在弹窗中确认保持常驻配置，单击"确定"。
   
   3. 在管道列表中确认目标管道的"运行状态"显示为"工作中"，且"事件"列数据持续更新，表示数据迁移任务恢复正常。
    
 
 #### 原因二：目的端集群JVM内存熔断
目的端Elasticsearch集群JVM内存使用率超过95%，触发父级内存熔断机制（Circuit Breaker）并返回BadResponseCodeError 429错误。与原因一类似，logstash-output-elasticsearch插件将429视为可重试错误并持续重试，导致热停止流程等待管道内事件处理完成时管道阻塞超时。
**处理措施：**
1. 在运行日志中搜索429或circuit_breaking_exception关键字。 如运行日志中存在HTTP 429错误且包含circuit_breaking_exception，则确认为原因二，请顺序执行后续步骤解决。
   
2. 强制停止管道。
   ![](https://support.huaweicloud.com/trouble-css/public_sys-resources/warning_3.0-zh-cn.png)
   全部停止会直接中断集群内所有正在运行的管道任务，正在传输中的数据可能出现短暂延迟或位点重置，请确保源端数据具备可追溯性。
   1. 在配置中心页面，单击管道列表上方的"全部停止"。
   
   2. 在对话框中，单击"确定"，停止所有管道的数据迁移任务。
   
   3. 观察管道列表的"运行状态"列，确认所有管道状态均显示为"已停止"。
    
3. 恢复目的端集群JVM内存。 通过以下方式降低目的端Elasticsearch集群JVM内存使用率：
   - **降低写入压力**：减少并发写入请求数量，降低批量写入大小。
   
   - **释放内存** ：在Kibana中执行以下命令，触发缓存清理：
     ```
     POST /_cache/clear
     ```
     
   
   - **扩容集群**：增加目的端集群节点数量或升级节点规格，提升JVM内存容量。
    
4. 重新启动管道任务。
   1. 在配置中心页面的配置文件列表中，勾选需要启动的配置文件，单击上方的"启动"。
   
   2. 在弹窗中确认保持常驻配置，单击"确定"。
   
   3. 在管道列表中确认目标管道的"运行状态"显示为"工作中"，且"事件"列数据持续更新，表示数据迁移任务恢复正常。
    
 
#### 提交工单
如果上述方法均不能解决您的疑问，请[提交工单](https://console.huaweicloud.com/ticket/#/ticketindex/createIndex)寻求更多帮助。