org.jenkinsci.plugins.workflow.pipelinegraphanalysis

Class StatusAndTiming

java.lang.Object

org.jenkinsci.plugins.workflow.pipelinegraphanalysis.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:

Each branch is considered independent
Branches may succeed, fail, or be in-progress/waiting for input.

Author:

Sam Van Oort

Constructor Summary

Constructors

Constructor and Description
StatusAndTiming()

Method Summary

Modifier and Type	Method and Description
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) Compute status codes for a set of parallel branches.
static Map<String,GenericStatus>	computeBranchStatuses(org.jenkinsci.plugins.workflow.job.WorkflowRun run, org.jenkinsci.plugins.workflow.graphanalysis.ParallelMemoryFlowChunk parallel)
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) 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.
static GenericStatus	computeChunkStatus(org.jenkinsci.plugins.workflow.job.WorkflowRun run, org.jenkinsci.plugins.workflow.graphanalysis.MemoryFlowChunk chunk) Return status or null if not executed all (null FlowExecution)
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 Note: for in-progress builds with parallel branches, the running branches end at the current time.
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 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

Constructor Detail

StatusAndTiming

public StatusAndTiming()

Method Detail

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 FlowExectuon of run

isPendingInput

public static boolean isPendingInput(org.jenkinsci.plugins.workflow.job.WorkflowRun run)

Return true if the run is paused on input

computeChunkStatus

@CheckForNull
public static GenericStatus computeChunkStatus(@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)

computeChunkStatus

@CheckForNull
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)

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.

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.

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
public static Map<String,GenericStatus> computeBranchStatuses(@Nonnull
                                                                       org.jenkinsci.plugins.workflow.job.WorkflowRun run,
                                                                       @Nonnull
                                                                       org.jenkinsci.plugins.workflow.graphanalysis.ParallelMemoryFlowChunk parallel)

computeBranchStatuses

@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)

Compute status codes for a set of parallel branches.

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

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

Returns:

Status, or null if none can be defined

printNodes

@Restricted(value=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