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:

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 and Description
static 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 and Description
static StatusAndTiming.StatusApiVersion	API_V1
static StatusAndTiming.StatusApiVersion	API_V2
static StatusAndTiming.StatusApiVersion	CURRENT_API_VERSION

Constructor Summary

Constructors

Constructor and Description
StatusAndTiming()

Method Summary

Modifier and Type	Method and 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)
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 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 Detail

API_V1

public static final StatusAndTiming.StatusApiVersion API_V1

API_V2

public static final StatusAndTiming.StatusApiVersion API_V2

CURRENT_API_VERSION

public static final StatusAndTiming.StatusApiVersion CURRENT_API_VERSION

Constructor Detail

StatusAndTiming

public StatusAndTiming()

Method Detail

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.

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.

computeBranchStatuses2

@Nonnull
public static Map<String,GenericStatus> computeBranchStatuses2(@Nonnull
                                                                        org.jenkinsci.plugins.workflow.job.WorkflowRun run,
                                                                        @Nonnull
                                                                        org.jenkinsci.plugins.workflow.graphanalysis.ParallelMemoryFlowChunk parallel)

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(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

Parameters:

run - Run to show nodes for

showTiming -

showActions -