Package io.jenkins.plugins.pipelinegraphview.analysis

Class StatusAndTiming

java.lang.Object
io.jenkins.plugins.pipelinegraphview.analysis.StatusAndTiming
public class StatusAndTiming extends Object
Provides common, comprehensive set of APIs for doing status and timing computations on pieces of a pipeline execution.

Concepts: a chunk, which is a set of FlowNodes in the same FlowExecution with a first and last node.

Chunks exist in a context: the FlowNode before and the FlowNode after. These follow common-sense rules:

  1. If a chunk has a null before node, then its first node must be the FlowStartNode for that execution
  2. If a chunk has a null after node, then its last node must be the FlowEndNode for that execution
  3. Both may be true at once (then the chunk contains the entire execution)
  4. First nodes must always occur before last nodes
  5. Where a WorkflowRun is a parameter, it and the FlowNodes must all belong to the same execution

Parallel branch handling:

  1. Each branch is considered independent
  2. Branches may succeed, fail, or be in-progress/waiting for input.
Author:
Sam Van Oort

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    StatusAndTiming.StatusApiVersion
    Denotes the version of the status API supported, which marks the permitted GenericStatus values it may return

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final StatusAndTiming.StatusApiVersion
    API_V1
     
    static final StatusAndTiming.StatusApiVersion
    API_V2
     
    static final StatusAndTiming.StatusApiVersion
    CURRENT_API_VERSION
     
    static boolean
    DISABLE_WARNING_ACTION_LOOKUP
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    StatusAndTiming()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static GenericStatus
    coerceStatusApi(GenericStatus rawStatus, StatusAndTiming.StatusApiVersion desiredVersion)
    Use this to permit consuming this API without having to be aware of new GenericStatus codes.
    static Map<String,GenericStatus>
    computeBranchStatuses(org.jenkinsci.plugins.workflow.job.WorkflowRun run, org.jenkinsci.plugins.workflow.graph.FlowNode parallelStart, List<org.jenkinsci.plugins.workflow.graph.BlockStartNode> branchStarts, List<org.jenkinsci.plugins.workflow.graph.FlowNode> branchEnds, org.jenkinsci.plugins.workflow.graph.FlowNode parallelEnd)
    Deprecated.
    static Map<String,GenericStatus>
    computeBranchStatuses(org.jenkinsci.plugins.workflow.job.WorkflowRun run, org.jenkinsci.plugins.workflow.graphanalysis.ParallelMemoryFlowChunk parallel)
    Deprecated.
    static Map<String,GenericStatus>
    computeBranchStatuses2(org.jenkinsci.plugins.workflow.job.WorkflowRun run, org.jenkinsci.plugins.workflow.graph.FlowNode parallelStart, List<org.jenkinsci.plugins.workflow.graph.BlockStartNode> branchStarts, List<org.jenkinsci.plugins.workflow.graph.FlowNode> branchEnds, org.jenkinsci.plugins.workflow.graph.FlowNode parallelEnd)
    Compute status codes for a set of parallel branches.
    static Map<String,GenericStatus>
    computeBranchStatuses2(org.jenkinsci.plugins.workflow.job.WorkflowRun run, org.jenkinsci.plugins.workflow.graphanalysis.ParallelMemoryFlowChunk parallel)
    Get statuses for each branch - note: some statuses may be null, API consumers MUST use coerceStatusApi(GenericStatus, StatusApiVersion) on outputs to safely handle addition of new statuses.
    static GenericStatus
    computeChunkStatus(org.jenkinsci.plugins.workflow.job.WorkflowRun run, org.jenkinsci.plugins.workflow.graph.FlowNode before, org.jenkinsci.plugins.workflow.graph.FlowNode firstNode, org.jenkinsci.plugins.workflow.graph.FlowNode lastNode, org.jenkinsci.plugins.workflow.graph.FlowNode after)
    Deprecated.
    static GenericStatus
    computeChunkStatus(org.jenkinsci.plugins.workflow.job.WorkflowRun run, org.jenkinsci.plugins.workflow.graphanalysis.MemoryFlowChunk chunk)
    Deprecated.
    static GenericStatus
    computeChunkStatus2(org.jenkinsci.plugins.workflow.job.WorkflowRun run, org.jenkinsci.plugins.workflow.graph.FlowNode before, org.jenkinsci.plugins.workflow.graph.FlowNode firstNode, org.jenkinsci.plugins.workflow.graph.FlowNode lastNode, org.jenkinsci.plugins.workflow.graph.FlowNode after)
    Compute the overall status for a chunk comprising firstNode through lastNode, inclusive
    static GenericStatus
    computeChunkStatus2(org.jenkinsci.plugins.workflow.job.WorkflowRun run, org.jenkinsci.plugins.workflow.graphanalysis.MemoryFlowChunk chunk)
    Return status or null if not executed all (null FlowExecution) Note: API consumers MUST use coerceStatusApi(GenericStatus, StatusApiVersion) on outputs to safely handle addition of new statuses.
    static TimingInfo
    computeChunkTiming(org.jenkinsci.plugins.workflow.job.WorkflowRun run, long internalPauseDuration, org.jenkinsci.plugins.workflow.graph.FlowNode firstNode, org.jenkinsci.plugins.workflow.graph.FlowNode lastNode, org.jenkinsci.plugins.workflow.graph.FlowNode after)
    Compute timing for a chunk of nodes
    static TimingInfo
    computeChunkTiming(org.jenkinsci.plugins.workflow.job.WorkflowRun run, long internalPauseDuration, org.jenkinsci.plugins.workflow.graphanalysis.MemoryFlowChunk chunk)
     
    static TimingInfo
    computeOverallParallelTiming(org.jenkinsci.plugins.workflow.job.WorkflowRun run, Map<String,TimingInfo> branchTimings, org.jenkinsci.plugins.workflow.graph.FlowNode parallelStart, org.jenkinsci.plugins.workflow.graph.FlowNode parallelEnd)
    Computes the branch timings for a set of parallel branches.
    static Map<String,TimingInfo>
    computeParallelBranchTimings(org.jenkinsci.plugins.workflow.job.WorkflowRun run, org.jenkinsci.plugins.workflow.graph.FlowNode parallelStart, List<org.jenkinsci.plugins.workflow.graph.BlockStartNode> branchStarts, List<org.jenkinsci.plugins.workflow.graph.FlowNode> branchEnds, org.jenkinsci.plugins.workflow.graph.FlowNode parallelEnd, long[] pauseDurations)
    Compute timing for all branches of a parallel
    static GenericStatus
    condenseStatus(Collection<GenericStatus> statuses)
    Combines the status results from a list of parallel branches to report a single overall status
    static org.jenkinsci.plugins.workflow.actions.WarningAction
    findWorstWarningBetween(org.jenkinsci.plugins.workflow.graph.FlowNode start, org.jenkinsci.plugins.workflow.graph.FlowNode end)
    Find the worst result WarningAction on FlowNodes between the given start and end nodes
    static boolean
    isPendingInput(org.jenkinsci.plugins.workflow.job.WorkflowRun run)
    Return true if the run is paused on input
    static void
    printNodes(org.jenkinsci.plugins.workflow.job.WorkflowRun run, boolean showTiming, boolean showActions)
    Helper, prints flow graph in some detail - now a common utility so others don't have to reinvent it
    static void
    verifySameRun(org.jenkinsci.plugins.workflow.job.WorkflowRun run, org.jenkinsci.plugins.workflow.graph.FlowNode... nodes)
    Check that all the flownodes & run describe the same pipeline run/execution

    Methods inherited from class java.lang.Object

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

  • Field Details

  • Constructor Details

    • StatusAndTiming

      public StatusAndTiming()

  • Method Details

    • coerceStatusApi

      public static GenericStatus coerceStatusApi(GenericStatus rawStatus, StatusAndTiming.StatusApiVersion desiredVersion)
      Use this to permit consuming this API without having to be aware of new GenericStatus codes. This will do a mapping from status codes to the closest equivalent in an older version of this API. For example, GenericStatus.QUEUED was originally coded as GenericStatus.IN_PROGRESS
      Parameters:
      rawStatus - Input status from recent forms of this API
      desiredVersion - Defines the statuses supported by the API version we wish to consume
      Returns:
      Input status correctly coerced to the best match among StatusAndTiming.StatusApiVersion.allowedStatuses

    • verifySameRun

      public static void verifySameRun(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, @CheckForNull org.jenkinsci.plugins.workflow.graph.FlowNode... nodes) throws IllegalArgumentException
      Check that all the flownodes & run describe the same pipeline run/execution
      Parameters:
      run - Run that nodes must belong to
      nodes - Nodes to match to run
      Throws:
      IllegalArgumentException - For the first flownode that doesn't belong to the FlowExecution of run

    • isPendingInput

      public static boolean isPendingInput(org.jenkinsci.plugins.workflow.job.WorkflowRun run)
      Return true if the run is paused on input
      Parameters:
      run -
      Returns:

    • computeChunkStatus

      @CheckForNull @Deprecated public static GenericStatus computeChunkStatus(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, @NonNull org.jenkinsci.plugins.workflow.graphanalysis.MemoryFlowChunk chunk)
      Deprecated.
      Deprecated version that coerces GenericStatus values to the original set (without GenericStatus.QUEUED). Most consumers should switch to computeChunkStatus2(WorkflowRun, MemoryFlowChunk) and use coerceStatusApi(GenericStatus, StatusApiVersion) to map new statuses to recognized ones.

    • computeChunkStatus2

      @CheckForNull public static GenericStatus computeChunkStatus2(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, @NonNull org.jenkinsci.plugins.workflow.graphanalysis.MemoryFlowChunk chunk)
      Return status or null if not executed all (null FlowExecution) Note: API consumers MUST use coerceStatusApi(GenericStatus, StatusApiVersion) on outputs to safely handle addition of new statuses.
      Parameters:
      run -
      chunk -
      Returns:
      Status or null if not executed all (null FlowExecution)

    • computeChunkStatus

      @CheckForNull @Deprecated public static GenericStatus computeChunkStatus(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, @CheckForNull org.jenkinsci.plugins.workflow.graph.FlowNode before, @NonNull org.jenkinsci.plugins.workflow.graph.FlowNode firstNode, @NonNull org.jenkinsci.plugins.workflow.graph.FlowNode lastNode, @CheckForNull org.jenkinsci.plugins.workflow.graph.FlowNode after)
      Deprecated.
      Deprecated version that coerces GenericStatus values to the original set (without GenericStatus.QUEUED). Most consumers should switch to computeChunkStatus2(WorkflowRun, FlowNode, FlowNode, FlowNode, FlowNode) and handle unknown status codes.

    • computeChunkStatus2

      @CheckForNull public static GenericStatus computeChunkStatus2(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, @CheckForNull org.jenkinsci.plugins.workflow.graph.FlowNode before, @NonNull org.jenkinsci.plugins.workflow.graph.FlowNode firstNode, @NonNull org.jenkinsci.plugins.workflow.graph.FlowNode lastNode, @CheckForNull org.jenkinsci.plugins.workflow.graph.FlowNode after)
      Compute the overall status for a chunk comprising firstNode through lastNode, inclusive

      All nodes must be in the same execution

      Note: for in-progress builds with parallel branches, if the branch is done, it has its own status.

      Note: API consumers MUST use coerceStatusApi(GenericStatus, StatusApiVersion) on outputs to safely handle addition of new statuses.
      Parameters:
      run - Run that nodes belong to
      before - Node before the first node in this piece
      firstNode - First node of this piece
      lastNode - Last node of this piece (if lastNode==firstNode, it's a single FlowNode)
      after - Node after this piece, null if the lastNode is the currentHead of the flow
      Returns:
      Status for the piece, or null if the FlowExecution is null.

    • findWorstWarningBetween

      @CheckForNull public static org.jenkinsci.plugins.workflow.actions.WarningAction findWorstWarningBetween(@NonNull org.jenkinsci.plugins.workflow.graph.FlowNode start, @NonNull org.jenkinsci.plugins.workflow.graph.FlowNode end)
      Find the worst result WarningAction on FlowNodes between the given start and end nodes
      Parameters:
      start - The flow node to start from
      end - The flow node to end on
      Returns:
      a possibly null WarningAction with the worst result

    • computeChunkTiming

      @CheckForNull public static TimingInfo computeChunkTiming(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, long internalPauseDuration, @NonNull org.jenkinsci.plugins.workflow.graphanalysis.MemoryFlowChunk chunk)

    • computeChunkTiming

      @CheckForNull public static TimingInfo computeChunkTiming(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, long internalPauseDuration, @NonNull org.jenkinsci.plugins.workflow.graph.FlowNode firstNode, @NonNull org.jenkinsci.plugins.workflow.graph.FlowNode lastNode, @CheckForNull org.jenkinsci.plugins.workflow.graph.FlowNode after)
      Compute timing for a chunk of nodes

      Note: for in-progress builds with parallel branches, the running branches end at the current time. Completed branches use the time at which the BlockEndNode terminating the branch was created.

      Parameters:
      run - WorkflowRun they all belong to
      internalPauseDuration - Millis paused in the chunk (including the ends)
      firstNode - First node in the chunk
      lastNode - Last node in the chunk
      after - Node after the chunk, if null we assume this chunk is at the end of the flow
      Returns:
      Best guess at timing, or null if we can't compute anything (no FlowExecution exists)

    • computeOverallParallelTiming

      @CheckForNull public static TimingInfo computeOverallParallelTiming(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, @NonNull Map<String,TimingInfo> branchTimings, @NonNull org.jenkinsci.plugins.workflow.graph.FlowNode parallelStart, @CheckForNull org.jenkinsci.plugins.workflow.graph.FlowNode parallelEnd)
      Computes the branch timings for a set of parallel branches. This will comprise the longest pause time from any branch, and overall runtime.
      Parameters:
      run -
      branchTimings - Map of branch name : precomputed timing info
      parallelStart -
      parallelEnd -
      Returns:

    • computeParallelBranchTimings

      @NonNull public static Map<String,TimingInfo> computeParallelBranchTimings(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, @NonNull org.jenkinsci.plugins.workflow.graph.FlowNode parallelStart, @NonNull List<org.jenkinsci.plugins.workflow.graph.BlockStartNode> branchStarts, @NonNull List<org.jenkinsci.plugins.workflow.graph.FlowNode> branchEnds, @CheckForNull org.jenkinsci.plugins.workflow.graph.FlowNode parallelEnd, @NonNull long[] pauseDurations)
      Compute timing for all branches of a parallel
      Parameters:
      run - Run the branches belong to
      parallelStart - Start of parallel block
      branchStarts - Nodes that begin each parallel branch
      branchEnds - Nodes that represent the "tip" of each parallel branch (may be the end node, or just the latest)
      parallelEnd - End of parallel block (null if in progress)
      pauseDurations - Accumulated pause durations for each of the branches, in order
      Returns:
      Map of branch name to timing.

    • computeBranchStatuses

      @NonNull @Deprecated public static Map<String,GenericStatus> computeBranchStatuses(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, @NonNull org.jenkinsci.plugins.workflow.graphanalysis.ParallelMemoryFlowChunk parallel)
      Deprecated.
      Get statuses for each branch - note: some statuses may be null. Retains compatibility with the original GenericStatus values. Use computeBranchStatuses2(WorkflowRun, ParallelMemoryFlowChunk) once you have a solid way to support new status codings.

    • computeBranchStatuses2

      @NonNull public static Map<String,GenericStatus> computeBranchStatuses2(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, @NonNull org.jenkinsci.plugins.workflow.graphanalysis.ParallelMemoryFlowChunk parallel)
      Get statuses for each branch - note: some statuses may be null, API consumers MUST use coerceStatusApi(GenericStatus, StatusApiVersion) on outputs to safely handle addition of new statuses.

    • computeBranchStatuses

      @Deprecated @NonNull public static Map<String,GenericStatus> computeBranchStatuses(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, @NonNull org.jenkinsci.plugins.workflow.graph.FlowNode parallelStart, @NonNull List<org.jenkinsci.plugins.workflow.graph.BlockStartNode> branchStarts, @NonNull List<org.jenkinsci.plugins.workflow.graph.FlowNode> branchEnds, @CheckForNull org.jenkinsci.plugins.workflow.graph.FlowNode parallelEnd)
      Deprecated.
      Get statuses for each branch - note: some statuses may be null. Retains compatibility with the original GenericStatus values. Use computeBranchStatuses2(WorkflowRun, FlowNode, List, List, FlowNode) once you support use of coerceStatusApi(GenericStatus, StatusApiVersion) to protect against changes.

    • computeBranchStatuses2

      @NonNull public static Map<String,GenericStatus> computeBranchStatuses2(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, @NonNull org.jenkinsci.plugins.workflow.graph.FlowNode parallelStart, @NonNull List<org.jenkinsci.plugins.workflow.graph.BlockStartNode> branchStarts, @NonNull List<org.jenkinsci.plugins.workflow.graph.FlowNode> branchEnds, @CheckForNull org.jenkinsci.plugins.workflow.graph.FlowNode parallelEnd)
      Compute status codes for a set of parallel branches.

      Note per computeChunkStatus2(WorkflowRun, MemoryFlowChunk) for in-progress builds with parallel branches, if the branch is done, it has its own status.

      Note: API consumers MUST use coerceStatusApi(GenericStatus, StatusApiVersion) on outputs to safely handle addition of new statuses.
      Parameters:
      run - Run containing these nodes
      branchStarts - The nodes starting off each parallel branch (BlockStartNode)
      branchEnds - Last node in each parallel branch - might be the end of the branch, or might just be the latest step run
      parallelStart - Start node for overall parallel block
      parallelEnd - End node for the overall parallelBlock (null if not complete)
      Returns:
      Map of branch name to its status

    • condenseStatus

      @CheckForNull public static GenericStatus condenseStatus(@NonNull Collection<GenericStatus> statuses)
      Combines the status results from a list of parallel branches to report a single overall status
      Parameters:
      statuses -
      Returns:
      Status, or null if none can be defined

    • printNodes

      @Restricted(org.kohsuke.accmod.restrictions.DoNotUse.class) public static void printNodes(@NonNull org.jenkinsci.plugins.workflow.job.WorkflowRun run, boolean showTiming, boolean showActions)
      Helper, prints flow graph in some detail - now a common utility so others don't have to reinvent it
      Parameters:
      run - Run to show nodes for
      showTiming -
      showActions -