Bottleneck detection

Bottleneck detection monitors, detects, and alerts user of restrictions in a value stream.

Utilizing the power of machine learning and AI, the bottleneck detection algorithm monitors the current and previous state of the value stream to identify which stage the user should focus on first. Bottleneck detection is viewed by either of the following methods:
  • On the Value Streams page with the required value stream selected, click Value stream > Metric bar.
  • Click Value Streams > All Value Streams. In the tabular view, the Bottleneck field will identify the restriction in the value stream.
The bottleneck detection plugin is used to identify a value stream restriction in local throughput that limits the global throughput of a system. The plugin uses work item stage-change data in unison with three algorithms to detect the presence of a specific type of bottleneck in a value stream. Detected bottlenecks are displayed in the metrics bar in the form of the following:
  1. Bottleneck location displayed as value stream and stage.
  2. Detection message displayed when you hover over the identified bottleneck.
    Figure 1. Bottleneck detection
    Bottleneck detection hover over
  3. Measure of bottleneck severity level used for display prioritization.
Note: The bottleneck detection parameter is not a value stream metric.


The bottleneck detection plugin runs on a frequency set by the user during the initial configuration. Typically, bottlenecks do not vary continually and a frequency of 24 hours is adequate for most cases.

At runtime, the plugin reads stageChangeEvents records via the stageChangeEventsSince graphQL API for all value streams defined on an HCL DevOps Velocity (Velocity) instance. The records for each value stream are then processed through each individual algorithm. Bottleneck detection records are then returned for each value stream. A value stream may have multiple bottleneck detection records created during a given run, or it may have none. If multiple bottlenecks are found in a given run, the Velocity UI will only display the highest severity bottleneck while logging the full set of detections in the database.

After the detection process is completed, the identified bottleneck records are written to the metrics database via the uploadMetrics graphQL API.

Bottleneck algorithms

The plugin uses three algorithms that each detect a unique class of bottlenecks according to different category processes that include the following:
  1. Dominant stage bottleneck
  2. Batching bottleneck
  3. Inflow/outflow asymmetry bottleneck

A dominant stage bottleneck occurs when one stage in a value stream has a time-in-stage value greater than or equal to the sum of the time-in-stages of all other stages in that value stream. The dominant stage detection algorithm detects this condition in a value stream and uses the severity value of the dominant stage to non-dominant stages time-in-stages to assess the severity. Each value stream will have only one dominant stage bottleneck detection at a given time.

A batching bottleneck occurs when work items exit a given stage in short time intervals separated by large intervals with no associated activity. This algorithm detects batching by calculating stage exit event densities and comparing peak densities to off-peak densities. The severity of the batching bottleneck corresponds to the peak to off-peak density ratio. A value stream may contain multiple stages with batching bottlenecks at a given time.

An inflow/outflow asymmetry bottleneck occurs when there is an unusually large difference of work items flowing into and out of a stage on a given day. This algorithms monitors 24 hour periods where the net work item flow for a stage is greater than two standard deviations from the mean net flow, and total stage flow is in the top five percent of the historical stage flow records. The severity of the bottleneck is assessed by the amount value above the net flow detection threshold. A value stream may have multiple stages with inflow/outflow asymmetry bottlenecks at a given time.

Example bottleneck detection output

The following example shows the bottleneck detection output:

  tenantId : tenantId,
  workflowId : workflowId,
  dataSet : "Bottleneck Detection",
  record : {
                entries : {
                            alertType : "Bottleneck",
                            alertLocation :  bottleneckStageName,
                            alertString : bottleneckMessage,
                            alertLevel : severityMeasure,
                            alertLink : None

Bottleneck detection display troubleshooting

For problems and solutions associated with display of the bottleneck detection parameter, refer to the following table:
Table 1. Bottleneck detection display troubleshooting
Problem Solution
The plugin instance is not configured or activated. Verify the plugin instance is enabled and has a valid access key.
For a new or not fully configured value stream (one without valid stage definitions) there will not be sufficient data to detect bottlenecks. Ensure the value stream definitions are properly configured and associated historical data exists in the system. Preferably at least 30 days of records with a minimum of 10 days.
No bottlenecks are detected. It is possible for a value stream to not have any of the bottleneck conditions which the plugin detects. Check the plugin logs to verify the plugin is executing successfully.