Package io.jenkins.plugins.explain_error

Class PipelineLogExtractor

java.lang.Object
io.jenkins.plugins.explain_error.PipelineLogExtractor
public class PipelineLogExtractor extends Object
Utility for extracting log lines related to a failing build or pipeline step and computing a URL that points back to the error source.

For WorkflowRun (Pipeline) builds, this class walks the flow graph to locate the node that originally threw the error, reads a limited number of log lines from that step, and records a node-specific URL that can be used to navigate to the failure location. When no failing step log can be found, or when the build is not a pipeline, it falls back to the standard build console log.

If the optional pipeline-graph-view plugin is installed, the generated URL is compatible with its overview page so that consumers can deep-link directly into the failing node from error explanations.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    URL_NAME
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    PipelineLogExtractor(Run<?,?> run, int maxLines)
     
    PipelineLogExtractor(Run<?,?> run, int maxLines, boolean collectDownstreamLogs, String downstreamJobPattern)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    org.jenkinsci.plugins.workflow.graph.FlowNode
    findCommonAncestor(Set<org.jenkinsci.plugins.workflow.graph.FlowNode> nodes)
    Finds the most recent (lowest) common ancestor for a given set of Jenkins Pipeline FlowNodes.
    List<String>
    getFailedStepLog()
    Extracts the log output of the step(s) that caused the pipeline failure, combining results from multiple strategies so that parallel failures (e.g.
    String
    getUrl()
    Returns the URL associated with the extracted log.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

  • Constructor Details

    • PipelineLogExtractor

      public PipelineLogExtractor(Run<?,?> run, int maxLines)

    • PipelineLogExtractor

      public PipelineLogExtractor(Run<?,?> run, int maxLines, boolean collectDownstreamLogs, String downstreamJobPattern)

  • Method Details

    • findCommonAncestor

      public org.jenkinsci.plugins.workflow.graph.FlowNode findCommonAncestor(Set<org.jenkinsci.plugins.workflow.graph.FlowNode> nodes)
      Finds the most recent (lowest) common ancestor for a given set of Jenkins Pipeline FlowNodes.

      Jenkins pipeline execution forms a Directed Acyclic Graph (DAG). This method calculates the intersection of all upstream ancestors for the provided nodes. It then determines the "nearest" common ancestor by finding the node in that intersection with the highest integer ID, as Jenkins assigns monotonically increasing integer strings as IDs during pipeline execution.

      Parameters:
      nodes - A Set of FlowNode objects for which to find the common ancestor.
      Returns:
      The FlowNode representing the nearest common ancestor, or null if the input set is null, empty, or if no common ancestor exists.

    • getFailedStepLog

      public List<String> getFailedStepLog() throws IOException
      Extracts the log output of the step(s) that caused the pipeline failure, combining results from multiple strategies so that parallel failures (e.g. both a Rspec test failure and a RuboCop offense) are all captured.
      1. Strategy 1 — ErrorAction multi-collect: walks the FlowGraph and collects logs from all nodes with ErrorAction and an associated LogAction (explicit uncaught exceptions). Unlike the original single-return approach, this accumulates logs from every failing step up to maxLines total, covering parallel failures such as multiple Rspec pod crashes.
      Falls back to run.getLog(maxLines) (last N lines of console) only if all strategies produce no results.
      Returns:
      A non-null list of log lines combining all relevant failure output, capped at maxLines.
      Throws:
      IOException - if there is an error reading the build logs.

    • getUrl

      public String getUrl()
      Returns the URL associated with the extracted log.

      When getFailedStepLog() finds a failed pipeline step with an attached log and the pipeline-graph-view plugin is available, this will point to the pipeline overview page with the failing node preselected. Otherwise, it falls back to the build's console output URL.

      Returns:
      the Jenkins URL for either the pipeline overview of the failing step or the build console output, or null if getFailedStepLog() has not been invoked successfully.